Perceptual Color

polarpointf.h
1// SPDX-FileCopyrightText: Lukas Sommer <sommerluk@gmail.com>
2// SPDX-License-Identifier: BSD-2-Clause OR MIT
3
4#ifndef POLARPOINTF_H
5#define POLARPOINTF_H
6
7#include <qdebug.h>
8#include <qmetatype.h>
9#include <qpoint.h>
10
11namespace PerceptualColor
12{
13/** @internal
14 *
15 * @brief A point in a
16 * <a href="https://en.wikipedia.org/wiki/Polar_coordinate_system">polar
17 * coordinate system</a>
18 *
19 * Polar coordinates are important for color
20 * handling because many color models use the
21 * <a href="https://en.wikipedia.org/wiki/Cylindrical_coordinate_system">
22 * cylindrical coordinate system</a> which extends the two-dimensional
23 * polar coordinate system to three dimensions by adding a (linear)
24 * <em>z</em> coordinate.
25 *
26 * Polar coordinate systems represent points by a radial coordinate
27 * (<em>radius</em>, also called <em>r</em> or <em>ρ</em>) and an angular
28 * coordinate (<em>angle</em>, also called <em>azimuth</em>, <em>φ</em>,
29 * <em>θ</em> or <em>t</em>).
30 *
31 * Polar coordinates allow multiple representations for a single point:
32 * - An angle of 0° is the same as 360° is the same as 720° is the same
33 * as −360°.
34 * - A radius of 1 and an angle of 0° is the same as a radius of −1 and an
35 * angle of 180°.
36 * - If the radius is 0, the angle is meaningless: A radius of 0 and an angle
37 * of 57° is the same as a radius of 0 and an angle of 233°.
38 *
39 * @invariant The polar coordinates are normalized. See @ref normalizePolar360
40 * for details.
41 *
42 * To provide a clear API, there is no <em>equal</em> operator. Use
43 * @ref isSamePoint() instead..
44 *
45 * This type is declared as type to Qt’s type system via
46 * <tt>Q_DECLARE_METATYPE</tt>. Depending on your use case (for
47 * example if you want to use for <em>queued</em> signal-slot connections),
48 * you might consider calling <tt>qRegisterMetaType()</tt> for
49 * this type, once you have a QApplication object.
50 *
51 * This data type can be passed to QDebug thanks to
52 * @ref operator<<(QDebug dbg, const PerceptualColor::PolarPointF value)
53 */
54class PolarPointF final
55{
56public:
57 /** @brief Constructor
58 *
59 * Constructs an object with @ref radius() = 0 and @ref angleDegree() = 0 */
60 explicit PolarPointF() = default;
61
62 /** @brief Default copy constructor
63 *
64 * @param other the object to copy */
65 PolarPointF(const PolarPointF &other) = default;
66
67 /** @brief Default move constructor
68 *
69 * @param other the object to move */
70 PolarPointF(PolarPointF &&other) noexcept = default;
71
72 explicit PolarPointF(const double newRadius, const double newAngleDegree);
73
74 explicit PolarPointF(const QPointF cartesianCoordiantes);
75
76 /** @brief Default assignment operator
77 *
78 * @returns The default implementation’s return value.
79 *
80 * @param other the object to assign */
81 // Clazy, our static code checker, complains about the next line of code
82 // as follows:
83 // “Pass small and trivially-copyable type by value”
84 // However, this is a copy constructor. We cannot pass the argument
85 // by value, because the compiler would complain as follows:
86 // “the parameter for an explicitly-defaulted copy assignment
87 // operator must be an lvalue reference type”
88 // Therefore, we exclude the following line from this specific clazy check,
89 // by adding a magic comment after it.
90 PolarPointF &operator=(const PolarPointF &other) = default; // clazy:exclude=function-args-by-value
91
92 /** @brief Default move assignment operator
93 *
94 * @param other the object to move-assign
95 *
96 * @returns The default implementation’s return value. */
97 PolarPointF &operator=(PolarPointF &&other) noexcept = default;
98
99 [[nodiscard]] double angleDegree() const;
100
101 [[nodiscard]] bool isSamePoint(const PolarPointF other) const;
102
103 [[nodiscard]] double radius() const;
104
105 QPointF toCartesian() const;
106
107private:
108 /** @brief Holds the @ref angleDegree() value. */
109 double m_angleDegree{0};
110
111 /** @brief Holds the @ref radius() value. */
112 double m_radius{0};
113};
114
115QDebug operator<<(QDebug dbg, const PerceptualColor::PolarPointF value);
116
117} // namespace PerceptualColor
118
119Q_DECLARE_METATYPE(PerceptualColor::PolarPointF)
120
121#endif // POLARPOINTF_H
KTEXTEDITOR_EXPORT QDebug operator<<(QDebug s, const MovingCursor &cursor)
The namespace of this library.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Oct 11 2024 12:07:52 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.