File indexing completed on 2024-05-12 04:44:32

 // SPDX-FileCopyrightText: Lukas Sommer <sommerluk@gmail.com>
 // SPDX-License-Identifier: BSD-2-Clause OR MIT
 
 // This file contains the following documentation:
 // – All the @page documentation. Putting all @page documentation in this
 //   single file allows that they show up in the documentation in
 //   alphabetical order.
 // – The namespace documentation
 
 /** @page build Build instructions and requirements
  *
  * Build-time dependencies:
  * - LittleCMS 2 (minimum version: 2.0)
  * - Qt 5 (minimum version: 5.15) <!-- Qt 5.15 has an API that is close
  *   to Qt 6. It introduces some new functions we are using to avoid
  *   deprecated older functions. --> or Qt 6 (minimum version: 6.0.0).
      Components: Core, Gui, Widgets, DBus, Concurrent, Test, Svg.
  * - CMake
  * - ECM (Extra CMake Modules from KDE)
  * - C++17
  * - Both, the input character set and the execution character set, have
  *   to be UTF8. (See @ref compilercharacterset for more details.)
  * <!--
  *      Qt 5.6 (which is the minimum Qt version required
  *      by this library) only requires C++03. Only starting
  *      with Qt 5.7, Qt itself requires C++11. Source:
  *      https://doc.qt.io/qt-5.9/cmake-manual.html#using-qt-5-with-cmake-older-than-3-1-0
  *
  *      Qt 6 requires minimum C++17, as
  *      https://doc-snapshots.qt.io/qt6-dev/cmake-get-started.html
  *      explains.
  *
  *      Our library code uses C++11 features, for example “constexpr”.
  *
  *      In the CMakeLists.txt file, we set -std=c++17 and we set
  *      also -Wpedantic and -pedantic-errors to enforce it. That is
  *      a useful option for this library if we decide to make it Qt-6-only.
  *      But it is even be useful if we support Qt 5, so we have future-proof
  *      requirements that we do not have to raise soon, and that are a
  *      good base for LTS.
  * -->
  * - Optional: There is also a LittleCMS plugin called
  *   <em>fast_float plug-in</em> that you can include into the
  *   source code of your application and load it in your main function
  *   before using this library. This can make color management faster.
  *   (Note that this plugin has a different license than LittleCMS itself.)
  *
  * Additional mandatory run-time dependencies:
  * - QSvgIconEnginePlugin. Available plugins are loaded
  *   automatically by Qt. Therefore, just make sure that this plugin is
  *   present. On Linux, it seems possible to enforce this by linking
  *   dynamically to the plugin itself, if you want to. This forces Linux
  *   package managers to produce packages of your application that depend
  *   not only on Qt base, but also on the SVG plugin. A typical file name of
  *   the plugin is <tt>plugins/iconengines/libqsvgicon.so</tt>.
  *
  * Please make sure that you comply with the licences of used libraries.
  *
  * To prepare the build, run cmake. We provide plenty of CMake options
  * that control the build type (shared/dynamic vs. static), IPO/LPO and
  * much more. The options are self-documenting. When you run CMake,
  * the options are listed with their values and a description of them.
  *
  * Then, to build and install the library:
  * @code{.unparsed}
  * make && sudo make install
  * @endcode
  *
  * To do unit testing:
  * @code{.unparsed}
  * make build_test test
  * @endcode */
 
 /** @internal
  *
  * @page codingstyle Coding style
  *
  * Always document your code.
  *
  * @section codingstylecpp C++
  *
  * - Provide unit tests for your code.
  * - If working with children within Qt’s object hierarchy, allocate on the
  *   heap and use raw pointers or guarded pointers (`QPointer`). If not,
  *   allocate on the stack or use smart pointers. Prefer Qt’s smart pointers
  *   over the <tt>std</tt> smart pointers of C++.
  * - Use KDE’s
  *   <a href="https://community.kde.org/Policies/Frameworks_Coding_Style">
  *   Frameworks Coding Style</a>. This can be done automatically with
  *   clang-format.
  * - Comments within the code should have this form: <tt>// comment</tt>
  *   <br/> This allows to comment out quickly large parts of the code for
  *   testing purposes.
  * - Comments for Doxygen should have this form: <tt>/⁠** Comment *⁠/</tt>
  *
  * @section codingstylecmake CMake
  *
  * @subsection codingstylecmakeusefuldocumentation Useful documentation
  *
  * - <a href="https://preshing.com/20170522/learn-cmakes-scripting-language-in-15-minutes/">
  *   Introduction to the CMake script language</a>
  * - <a href="https://github.com/onqtam/awesome-cmake">
  *   Curated list of awesome CMake scripts, modules, examples and others</a>
  * - <a href="https://llvm.org/docs/CMakePrimer.html">General introduction
  *   into CMake (both, the script language and the commands)</a>
  *
  * @subsection codingstylecmakemodern Use “Modern CMake”
  *
  * Use <em>Modern CMake</em>: Avoid global settings like
  * <tt>include_directories()</tt>. Use target-based commands like
  * <tt>target_include_directories()</tt> instead. Use
  * <tt>target_link_libraries()</tt> to pull in dependencies, which gives you
  * automatically the correct include directories, compile options etc.
  * When using <tt>target_link_libraries()</tt>, always specify
  * <tt>PUBLIC</tt> or <tt>PRIVATE</tt> or <tt>INTERFACE</tt> explicitly.
  *
  * @subsection codingstylecmakeindent Indent
  *
  * Use 4 spaces for indenting. Do not use tabs.
  *
  * @subsection codingstylecmakequotationmarks Quotation marks
  *
  * Use quotation marks when you want to represent a string.
  * Do not use quotation marks when you mean a keyword. Example:
  *
  * @code{.unparsed}
  * set(myvar "foo")
  * @endcode
  *
  * Particularly, always quote strings within control structures:
  *
  * @code{.unparsed}
  * if("${myvar}" STREQUAL "bar")
  * @endcode
  *
  * @subsection codingstylecmakeboolean Boolean
  *
  * CMake allows various representations of boolean. Use only the forms
  * <tt>TRUE</tt> and <tt>FALSE</tt>. Do not quote them.
  *
  * @subsection codingstylevariablecheck Check if a variable exists
  *
  * Check if a variable exists like this:
  *
  * @code{.unparsed}
  * if(DEFINED varname)
  * @endcode
  *
  * @subsection codingstylecmakenaming Naming
  *
  * Functions and macros:
  *
  * @code{.unparsed}
  * lower_case()
  * @endcode
  *
  * Control structures: <tt>lower_case()</tt>, with empty <tt>else()</tt>,
  * <tt>endif()</tt>, <tt>endfunction()</tt>…
  *
  * Operators/keywords/directives/extra options: <tt>UPPER_CASE</tt> without
  * quotes. Examples:
  *
  * @code{.unparsed}
  * if(condition STREQUAL "")
  * @endcode
  *
  * @code{.unparsed}
  * do_something(... USE_THIS)
  * @endcode
  *
  * @code{.unparsed}
  * file(COPY ...)
  * @endcode
  *
  * @subsection codingstyleparenthesis Parenthesis
  *
  * Multi-line calls have trailing parenthesis on the same line as
  * last parameter, not on separate line:
  *
  * @code{.unparsed}
  * set(my_variable
  *     "value1"
  *     "value2"
  *     "value3)
  * @endcode
  *
  * @subsection codingstyleorder Order
  *
  * Source and header lists should be ordered alphabetically,
  * subdirectories last, preferably separated by a single empty line.
  *
  * @subsection codingstylelinelength Line length
  *
  * Keep the length of the line below 80 characters when possible.
  * No trailing whitespace.
  *
  * @subsection codingstyledirectories Directories
  *
  * A directory path may not have a trailing <tt>/</tt>. This is to avoid
  * duplicates like <tt>//</tt> when composing paths:
  *
  * @code{.unparsed}
  * set(my_path "/usr/bin/") # BAD
  * set(my_path "/usr/bin") # GOOD
  * set(my_file "${my_path}/my_file")
  * @endcode
  *
  * @subsection codingstylelists Lists
  *
  * Declaring an empty list:
  *
  * @code{.unparsed}
  * set(mylist)
  * @endcode
  *
  * Declaring and initializing a list at the same time:
  *
  * @code{.unparsed}
  * set(mylist
  *     "first item"
  *     "second item"
  *     "third item")
  * @endcode
  *
  * Append to a list:
  *
  * @code{.unparsed}
  * list(APPEND mylist "last item")
  * @endcode
  *
  * @subsection codingstyleprojectname ${PROJECT_NAME}
  *
  * Use <tt>${PROJECT_NAME}</tt> for global variables, targets and labels
  * instead of repeating the project name manually or using fixed names:
  *
  * @code{.unparsed}
  * add_executable(${PROJECT_NAME} …)
  * @endcode */
 
 /** @page compilercharacterset Compiler character sets
  *
  * @section compilercharacterset_ Compiler character sets
  *
  * Compilers have three different character sets:
  * - Input character set (the character set of the source code)
  * - Narrow execution character set
  *   (for <tt>char</tt> and for string literals without prefix)
  * - Wide execution character set
  *   (for <tt>wchar_t</tt> and for string literals with <tt>L</tt> prefix)
  *
  * @subsection inputcharacterset Input character set
  *
  * This source code of this library is encoded in UTF8. Therefore, your
  * compiler must treat is also as UTF-8.
  *
  * Why are we using UTF-8 instead of ASCII?
  * - UTF-8 is more complete than ASCII. ASCII does not even provide basic
  *   typographic symbols like en-dash, em-dash or non-breaking space
  *   characters or quotes.
  * - Unicode exists since 1991, UTF-8 since 1993. It’s time to get rid of
  *   the insufficient ASCII character. It’s time to use Unicode.
  * - We use non-ASCII characters for (typographically
  *   correct) Doxygen documentation and partially also for non-Doxygen
  *   source code comments. It would be quite annoying to use HTML
  *   entities for each non-ASCII character in the Doxygen documentation;
  *   and it would be pointless to do it for non-Doxygen source code
  *   comments.
  * - <tt>i18n()</tt> and <tt>ki18n()</tt> and <tt>tr()</tt> require both,
  *   the source file and <tt>char*</tt> to be encoded in UTF-8; no other
  *   encodings are supported. (Only ASCII would be UTF-8 compatible,
  *   but in practice this encoding is not supported, but only 8859-Latin
  *   encodings, which allow code points higher than 127, which risks to
  *   introduce incompatibilities. Therefore, this would not be a good
  *   option.)
  * - The C++ identifiers of library symbols are however (currently)
  *   ASCII-only.
  *
  * So we use a <tt>static_assert</tt> statement to control this.
  *
  * @subsection narowexecutioncharacterset Narrow execution character set
  *
  * Why are we using UTF-8 as narrow execution character set?
  * - <tt>i18n()</tt> and <tt>ki18n()</tt> and <tt>tr()</tt> require both,
  *   the source file and <tt>char*</tt> to be encoded in UTF-8; no other
  *   encodings are supported.
  * - Implicit conversion from <tt>char*</tt> to <tt>QString</tt> assumes
  *   that <tt>char*</tt> is UTF-8 encoded. Thus we disable this implicit
  *   conversion in <tt>CMakeLists.txt</tt>, it’s wise to stay compatible.
  *
  * Therefore, a static assert controls that really UTF-8 is used
  * as narrow execution character set.
  *
  * @subsection wideexecutioncharacterset Wide execution character set
  *
  * We do not use actively the wide execution character set. There is
  * a usage when communicating with LittleCMS, but there we depend anyway
  * from LittleCMS. Therefore, currently, no static assert forces a specific
  * wide execution character set.
  *
  * @internal
  *
  * @note The static asserts that enforce the character sets are located
  * in @ref staticasserts.cpp. */
 
 /** @internal
  *
  * @page datatypes Data types
  *
  * The library uses in general <tt>int</tt> for integer values, because
  * <tt>QSize()</tt> and <tt>QPoint()</tt> also do. As the library relies
  * heavily on the usage of <tt>QSize()</tt> and <tt>QPoint()</tt>, this
  * seems reasonable.
  *
  * For the same reason, it uses generally <tt>qreal</tt>
  * for floating point values, because <tt>QPointF()</tt> also does.
  *
  * Output colors that are shown on the screen, are usually 8-bit-per-channel
  * colors. For internal transformation, usually <tt>qreal</tt>
  * is used for each channel, giving a better precision and reducing rounding
  * errors. */
 
 /** @internal
  *
  * @page generaltodolist General TODO list
  *
  * This is a TODO list that contains general ideas or issues of this
  * library.
  *
  * @todo Use words as hints for color ranges? Muted/dull colors have a low
  * chroma value. The dark ones (getrübte/gebrochene Farben) are created by
  * adding black (and possibly a bit of white) and include warm tones (the
  * browns) and cool tones (the olives). The light ones are called Pastel
  * colors and are created by adding white (and possibly a bit of
  * black) and include warm tones (like baby pink) and cool
  * tones (like baby blue). Warm colors are located at a color angle of
  * about 45°, cool colors at about 225°. Could we mark this in the diagrams?
  * Cold and warm could be marked by a text outside the color wheel at the
  * given position. The other ones seem to be more complicated: These specific
  * color terms do not have a translation in all languages. (For “muted colors”,
  * there is no good German translation, and for “getrübte Farben”, there is
  * no good English translation.
  *
  * @todo A design question: Following KDE’s HIG, if the command requires
  * additional user interaction to complete, at the end its label there
  * should be an elipsis sfs (…). Currently, this only seems to apply
  * to @ref PerceptualColor::ColorDialogPrivate::m_screenColorPickerButton.
  *
  * @todo https://invent.kde.org/plasma/kdeplasma-addons/-/merge_requests/249
  * allows the user to drag and drop an image file. The image’s average color
  * is calculated and set as current color of Plasma’s color picker widget.
  * Furthermore, it seems that Plasma’s color picker widget also accepts
  * color codes for drag-and-drop. (Which ones? Maybe the #128945 style?)
  * Would this make sense also for our library?
  *
  * @todo ITUR profile: Minimum widget size must be smaller! On high sizes, the
  * inner focus indicator of color wheel too narrow to hue circle.
  * On RGB 255 0 0 no value indicator is visible. The high-chroma values
  * are empty in the diagram!
  *
  * @todo Touch friendly: @ref PerceptualColor::ColorPatch,
  * @ref PerceptualColor::GradientSlider etc. at least
  * as thick as (normal) buttons. Qt6 replaces QTouchDevice by
  * QInputDevice::devices()…
  *
  * @todo For all diagram images: No abort during first interlacing pass. (See
  * @ref PerceptualColor::AsyncImageProvider for details.)
  *
  * @todo All scripts (both, local and CI scripts) should break and stop
  * on every error. When implementing this, be beware of side effects
  * (some local scripts are also called from the CI and so on…).
  *
  * @todo Review @ref PerceptualColor::RgbColorSpace. And change
  * it in order to allow support for Oklab. And maybe Googles
  * <a href="https://github.com/material-foundation/material-color-utilities">
  * HTC</a>.
  *
  * @todo A design question: In the chroma-lightness diagram, the color
  * wheel is a slider and reacts as such. However, in the chroma-hue-diagram,
  * the same color wheel is just decoration (for orientation). Isn’t this
  * different behaviour of two visually identical elements confusing?
  *
  * @todo A design question: Should we use
  * <a href="https://doc.qt.io/qt-6/qt.html#CursorShape-enum">
  * <tt>Qt::CrossCursor</tt></a> for two-dimensional selections like
  * @ref PerceptualColor::ChromaHueDiagram? And should we use
  * <a href="https://doc.qt.io/qt-6/qt.html#CursorShape-enum"><tt>
  * Qt::UpArrowCursor</tt></a> for one-dimensional selections like
  * @ref PerceptualColor::GradientSlider?
  *
  * @todo Remove things form the public API, leaving only the absolutely
  * minimal API that is required by the user.
  *
  * @todo Avoid “final” in the public API (or even altogether?). Implement
  * a codecheck for this.
  *
  * @todo <a href="https://valgrind.org/docs/manual/quick-start.html"> Test with
  * valgrind.org</a>
  *
  * @todo Most widgets of this library allocate in each paint event a new
  * buffer to paint on, before painting on the widget. This is also done
  * because only <tt>QImage</tt> guarantees the same result on all platforms,
  * while <tt>QPixmap</tt> is platform-dependent and Qt does not guarantee that
  * for example <tt>QPainter::Antialiasing</tt> is available on all platforms.
  * However, not using a buffer would save memory! Can we know if the current
  * platform supports <tt>QPainter::Antialiasing</tt> and buffer only if
  * necessary? Or could we at least instantiate only one single buffer per
  * application, that is than shared between all the widgets of our library?
  * This buffer would never be freed, so it will always occupy memory. But
  * this avoids the time-consuming memory allocations at each paint event!
  *
  * @todo Use <tt>QCache</tt> where is makes sense. Maybe
  * @ref PerceptualColor::RgbColorSpace::reduceCielchD50ChromaToFitIntoGamut() or
  * @ref PerceptualColor::RgbColorSpace::isCielchD50InGamut() or
  * @ref PerceptualColor::RgbColorSpace::isCielabD50InGamut() or
  * @ref PerceptualColor::ChromaLightnessDiagramPrivate::nearestInGamutColorByAdjustingChromaLightness(().
  *
  * @todo Switch AbstractDiagram::handleOutlineThickness() and
  * handleRadius() and spaceForFocusIndicator() to use PM_DefaultFrameWidth.
  * (PM_DefaultFrameWidth seems to be used yet in ColorPatch.)
  *
  * @todo QColor is ambiguous: It allows different types of color system,
  * or even various versions of the same color system at different
  * precisions (RGB). This makes it difficult to communicate in the API
  * which is the type of color (model) it contains. Therefore, we should
  * eliminate all its usage within this library (except where it is necessary
  * for API compatibility with Qt).
  *
  * @todo If using the Motif style, the @ref PerceptualColor::ChromaHueDiagram
  * widget, which has circular look-and-feel, has a rectangular focus
  * indicator corresponding the rectangular widget geometry, which looks
  * quite ugly. On the other hand, @ref PerceptualColor::WheelColorPicker
  * has also circular  look-and-feel, but no rectangular focus indicator
  * corresponding the rectangular widget geometry, which looks better.
  * Why doesn’t @ref PerceptualColor::ChromaHueDiagram also behave
  * like @ref PerceptualColor::WheelColorPicker? And
  * how does @ref PerceptualColor::ColorWheel behave?
  *
  * @todo Idea: Provide QColorWidget (like QColorDialog, but inheriting
  * from QWidget, and no buttons). Does this make sense?
  *
  * @todo Use implicit data sharing in @ref PerceptualColor::RgbColorSpace
  * instead of <tt>QSharedPointer\< @ref PerceptualColor::RgbColorSpace \></tt>.
  * But: Wouldn’t this require to make the declaration
  * of @ref PerceptualColor::RgbColorSpace, which was secret until today,
  * public? If so, this would not be good…
  *
  * @todo Dual-Licence with Apache2 and/or Boost licence?
  *
  * @todo Reduce number of exported symbols.
  *
  * @todo Rename main.cpp.
  *
  * @todo Currently, we consider that a mouse clicks click a pixel, but mean
  * the coordinate point in the middle of this pixel. This seems an approach
  * that other widgets (including Qt itself) do not use. And maybe is meant also
  * the coordinate at the top of the mouse cursor, so no offset by (0.5, 0.5)
  * would be necessary. This would give better results (at least on LTR
  * mouse cursors, but what's about crosshair cursors and RTL cursors?)
  *
  * @todo We do some hacks to get circle-like (instead of rectangular)
  * feeling for our circular widgets, which is not perfect when talking
  * about mouse events. It seems that QWidget::setMask() offers an
  * alternative, restricting mouse events (and painting) to a given
  * mask. Does this actually work also for mouse focus management?
  * If so: Has it performance penalties? If not, we should probably use
  * it! And document that those widgets are circular widgets and from
  * a user perspective behave like circular widgets (both paint event
  * and mouse cursor reactions/usage feeling), though from an application
  * programmer (that uses this library) perspective, they are of course
  * rectangular in the layout system. And: Post the results on
  * <a href="https://forum.qt.io/topic/118547/accept-reject-focus-coming-by-mouse-click-based-on-coordinates">
  * this Qt Forum thread</a>.
  *
  * @todo Support more of Qt Style Sheets, for example allow
  * customizing the neutral-gray background of diagrams? If
  * so, @ref PerceptualColor::drawQWidgetStyleSheetAware()
  * is available. Otherwise, remove the currently not used
  * @ref PerceptualColor::drawQWidgetStyleSheetAware() from
  * this library.
  *
  * @todo Unit tests for endianess. Maybe QtEndian can help…
  *
  * @todo General library properties:
  * - test cross-platform support and different byte-orders
  * - Could we integrate more with QStyle? Apparently
  *   <a href="https://api.kde.org/frameworks/frameworkintegration/html/classKStyle.html">
  *   KStyle</a> is a QCommonStyle-based class that provides
  *   support for QString-based query for custom style hints,
  *   control elements and sub elements. There is also
  *   <a href="https://api.kde.org/frameworks/kwidgetsaddons/html/namespaceKStyleExtensions.html">
  *   KStyleExtensions</a> that allows apparently custom widgets to query
  *   for these QString-based custom support, which allows to make the same
  *   query independently of the actual style, without the need to hard-code
  *   individual custom enum values for QStyle::ControlElement (and similar
  *   enum) for each individual style. KStyleExtensions works for all
  *   styles, also for these that are <em>not</em> subclasses of
  *   <tt>KStyle</tt>. It reports if a given query is supported or not
  *   by the underlying style. However, even Breeze, KDE’s default style,
  *   seems not to inherit from KStyle, so the question is if KStyle is
  *   not rather deprecated yet. An alternative would be if a style
  *   has special functions just for PerceptualColor rendering, like
  *   <tt>renderColorWheel</tt>. Than, we could cast the current QStyle
  *   of the application to this style (if the actual current
  *   style <em>is</em> this style), and call these functions. Big
  *   disadvantage: We would have to <em>link</em> against all styles
  *   that we want to support, which makes our library <em>depend</em>
  *   on them, which is not reasonable.
  * - More work on accessibility. [This includes to work well with bigger
  *   fonts. Should then the gradient be thicker and the marker
  *   thicker? setAccessibleName().] The application Accerciser provides
  *   inspection possibilities.
  *
  * @todo From KDE’s binary compatibility info page: In order to make a class
  * to extend in the future you should follow these rules:
  * - add non-inline virtual destructor even if the body is empty.
  * - re-implement event in QObject-derived classes, even if the body for
  *   the function is just calling the base class' implementation. This is
  *   specifically to avoid problems caused by adding a reimplemented virtual
  *   function as discussed below.
  *
  * @todo Following the recommendation of the C++ core guidelines, all
  * destructors should be noexcept.
  *
  * @todo Make genereatescreenshots and the unit tests run on hardware
  * without graphic card. This would be good for Continuous Integration.
  * The XVFB Virtual framebuffer (https://de.m.wikipedia.org/wiki/Xvfb)
  * can do this for X apps. Also, it is possible to start X apps on
  * terminal without a window manager, see
  * https://linuxconfig.org/how-to-run-x-applications-without-a-desktop-or-a-wm
  * but I suppose an X server is still required? There seem to exist also
  * possibilities for Wayland
  * https://unix.stackexchange.com/questions/653672/virtual-wayland-display-server-possible
  * Also, there seems to be a Qt Platform Abstraction called “minimal”
  * (https://doc.qt.io/qt-6/qpa.html) for testing purposes. Elsewhere,
  * if I remember correctly, it was described as useful for testing without X.
  *
  * @todo The missing 3rd diagram (hue-lightness? But: Impossible to model
  * the circular behaviour of the LCH color space: It cannot be a cut through
  * the gamut body, but has to be a curve within the gamut body – not so
  * nice. And: The diagram width has to change with the selected hue if we want
  * to have correct scaling between x axis and y axis…
  *
  * @todo In https://phabricator.kde.org/T12359 is recommended to provide
  * RESET statements for all properties for better compatibility with QML.
  * As we provide widgets, this should not be too important. Are there also
  * good arguments for widgets to provide RESET?
  *
  * @todo Provide an init() function that calls qRegisterMetaType() for
  * all our types?
  *
  * @todo We prevent division by 0 in
  * @ref PerceptualColor::ChromaLightnessDiagramPrivate::fromWidgetPixelPositionToColor().
  * We should make sure this happens also in the other diagram widgets!
  *
  * @todo Add a @ref PerceptualColor::ConstPropagatingUniquePointer to
  * all classes, including the non-pimpl classes, to allow for later
  * enhancements.
  *
  * @todo Remove setDevicePixelRatioF from all *Image classes. (It is
  * confusing, and at the same time there is no real need/benefit.)
  * Complete list: @ref PerceptualColor::ChromaHueImageParameters,
  * @ref PerceptualColor::ColorWheelImage,
  * @ref PerceptualColor::GradientImageParameters.
  *
  * @todo Test also on Windows. (Does it work well with VisualStudio?)
  *
  * @todo Test also Big-Endian compatibility using s390x Linux via Qemu?
  * KDE Invent does not support this out-of-the-box, but with a custom
  * script?
  *
  * @todo Test opaque RGB color space object with a non-export-all version
  * of this library to make sure it actually works for third-party developers.
  *
  * @todo Sometimes, on dual-screen setup, one screen has another DPI than
  * the other screen. Does this library behave correctly in these situations?
  *
  * @todo Would it make sense for @ref PerceptualColor::ChromaHueDiagram and
  * @ref PerceptualColor::ChromaLightnessDiagram to split up their property
  * <tt>currentColor</tt> into two properties: A two-dimensional property
  * for what the user can change, and a one-dimensional property
  * for what only the programmer can change? Or at least provide
  * a Q_INVOKABLE getter and maybe also setter support? So
  * @ref PerceptualColor::WheelColorPicker could use this
  * instead of a lambda expression to set the hue of the
  * @ref PerceptualColor::ChromaLightnessDiagram. And: Also when we don’t do
  * that: When setting <tt>currentColor</tt> to an out-of-gamut color,
  * what happens? Does @ref PerceptualColor::ChromaHueDiagram preserve
  * lightness, while @ref PerceptualColor::ChromaLightnessDiagram preserves
  * hue? Would this make sense?
  *
  * @todo Paint grayed-out handles for all widgets when setEnabled(false)
  * is used! For example 25% lightness instead of black. And 75% lightness
  * instead of white. But: Provide this information
  * in @ref PerceptualColor::AbstractDiagram!
  *
  * @todo It might be interesting to use <tt>QStyle::PM_FocusFrameHMargin</tt>
  * <em>(Horizontal margin that the focus frame will outset the widget
  * by.)</em> Or: <tt>QStyle::PM_FocusFrameVMargin</tt>. Using this for the
  * distance between the focus indicator and the actual content of the widget
  * maybe give a more <tt>QStyle</tt> compliant look. But: If using this,
  * ensurePolished() must be called before!
  *
  * @todo Use <tt>explicit</tt> on all constructors?
  *
  * @todo Screen picker with magnifier glass in two steps
  * similar to https://colorsnapper.com ? Or like in Firefox
  * (Menu → Weitere Werkzeuge → Farbpalette)?
  *
  * @todo Multi-licensing? Add Boost licence and Unlicense as an additional
  * choice?
  *
  * @todo The image cache for the gamut widgets should be updated
  * asynchronously (in its own thread or even various own threads
  * in parallel). While waiting for the result, an empty image could be used.
  * Or it might be useful to provide first a low-resolution version, and only
  * later-on a high-resolution version. Anyway, KDE provides an interesting
  * recommendation: <tt>int Units::humanMoment = 2000;</tt> <em>Time in
  * milliseconds equivalent to the theoretical human moment, which can be
  * used to determine whether how long to wait until the user should be
  * informed of something, or can be used as the limit for how long something
  * should wait before being automatically initiated. / Some examples: /
  * When the user types text in a search field, wait no longer than this
  * duration after the user completes typing before starting the search /
  * When loading data which would commonly arrive rapidly enough to not
  * require interaction, wait this long before showing a spinner</em> See
  * https://api.kde.org/frameworks/plasma-framework/html/classUnits.html#ab22ad7033b2e3d00a862650e82f5ba5e
  * for details.
  *
  * @todo HLC @ref PerceptualColor::MultiSpinBox Allow entering (on the
  * keyboard) of too big hues (361°), negative hues (-1°), negative chroma (-20)
  * and too big chroma (201 or 256) – but do not allow this with the arrows
  * (and how do the arrows react when currently one of these values is
  * shown?). Does this make sense? Anyway do <em>not</em> allow this for
  * lightness, because the lightness is <em>by definition</em> bound
  * to <tt>[0, 100]</tt>.
  *
  * @todo Multi-threaded application of color transforms. It seems okay to
  * create the color transforms in one thread and use the same color
  * transform (once created) from various other threads at the same time
  * as long as the flag <tt>cmsFLAGS_NOCACHE</tt> is used to create the
  * transform.
  *
  * @todo Automatically scale the thickness of the wheel (and maybe even the
  * handle) with varying widget size?
  *
  * @todo Support more color spaces? https://pypi.org/project/colorio/ for
  * example supports a lot of (also perceptually uniform) color spaces…
  *
  * @todo Export less symbols?
  *
  * @todo Check in all classes that take a @ref PerceptualColor::RgbColorSpace
  * that the shared pointer is actually not a <tt>nullptr</tt>. If is
  * <em>is</em> a <tt>nullptr</tt> than throw an exception. Throwing the
  * exception early might make error detection easier for users of the library.
  *
  * * @todo Avoid default arguments like <tt>void test(int i = 0)</tt> in
  * public headers, as changes require re-compilation of the client application
  * to take effect, which might lead to a miss-match of behaviour between
  * application and library, if  compile-time and run-time version of the
  * library are not the same. Is the problem  for default constructors
  * like <tt>ClassName() = default</tt> similar?
  *
  * @todo mark all public non-slot functions with Q_INVOKABLE (except property
  * setters and getters)
  *
  * @todo A good widget library should also be touchscreen-ready. Find
  * an alternative to @ref PerceptualColor::MultiSpinBox? How, for up
  * to 360 values (degrees in step by 1)? Or should the steps simply be bigger?
  *
  * @todo KDE Frameworks / https://marketplace.qt.io/ ?
  * https://community.kde.org/Incubator
  *
  * @todo Provide property bindings as described in
  * https://www.qt.io/blog/property-bindings-in-qt-6 or not? It is worth
  * when we do not support QML? What are the pitfalls? Imagine a property
  * that holds a percent value from 0 to 100; the setter enforces this
  * range; the binding bypasses the setter and allows every value? And:
  * How can callbacks know about when a setter was called in C++? See
  * also: https://doc.qt.io/qt-5/qtqml-cppintegration-exposecppattributes.html
  * and https://doc.qt.io/qt-5/qtqml-tutorials-extending-qml-example.html and
  * http://blog.aeguana.com/2015/12/12/writing-a-gui-using-qml-for-a-c-project/
  * for interaction between QML and C++. Pitfalls: Example of color() property
  * stored internally at m_color: Much implementation code of the class will
  * access directly m_color instead of color(), so when using bindings,
  * this code is broken?
  *
  * @todo Provide QML support so that for
  * https://doc.qt.io/qt-5/qml-qtquick-dialogs-colordialog.html (or its
  * Qt6 counterpart) we provide a source compatible alternative, like for
  * QColorWidget? Split the library in three parts (Common, Widgets, QML)?
  * Support <a href="https://mauikit.org/">MauiKit</a>?
  *
  * @todo Apparently QWidget cannot be used from QML. (Though there is
  * https://www.kdab.com/declarative-widgets/ – how does that work?) Is it
  * therefore worth to have complete support for signals in all our QWidget
  * code if this is not really necessary for QWidget (for example for
  * properties that can only be changed by the library user and not by the
  * end user)?
  *
  * @todo Comply with <a href="https://community.kde.org/Policies">KDE
  * policies</a>.
  *
  * @todo Remove all qDebug calls from the source
  *
  * @todo Qt Designer support for the widgets. Quote from a blog from Viking
  * about Qt Designer plugins:
  * The problem is that you have to build it with exactly the same compiler
  * tool chain as designer was built with, and you have to do it in release
  * mode. Unless your Qt is built in debug, then your plugin needs to be
  * built in debug mode as well. So you can’t just always use the same
  * compiler as you build the application with, if you use the system Qt or
  * a downloaded Qt version.
  *
  * @todo Use <a href="https://lvc.github.io/abi-compliance-checker/">
  * abi-compliance-checker</a> to control ABI compatibility.
  *
  * @todo Follow KDE’s <a href="https://hig.kde.org/index.html">HIG</a>
  *
  * @todo Test linking against lcms.h in version 2.0.0 for compatibility
  * (or require more recent version?)
  *
  * @todo Require (by static cast additional to CMake conditions) a minimum
  * Qt version?
  *
  * @todo Would it be a good idea to implement Q_PROPERTY RESET overall? See
  * also https://phabricator.kde.org/T12359
  *
  * @todo Better design on small widget sizes for the whole library.
  *
  * @todo Anti-aliasing the gamut diagrams? Wouldn't this be bad for
  * performance?
  *
  * @todo Use a cross-hair cursor on @ref PerceptualColor::ChromaHueDiagram
  * and @ref PerceptualColor::ChromaLightnessDiagram when the mouse is
  * hovering over the gamut, to show that this surface can be clicked?
  *
  * @todo Touch-friendly interface: Would it be good to have buttons for
  * plus and minus on the various LCH axis which would be companions
  * for @ref PerceptualColor::ChromaHueDiagram and
  * @ref PerceptualColor::ChromaLightnessDiagram and would allow
  * more exactly choose colors also on touch devices?
  *
  * @todo Would it be a good idea to have plus and minus buttons that
  * manipulate the current color along the depth and vividness axis
  * as proposed in “Extending CIELAB - Vividness, V, depth, D, and clarity, T”
  * by Roy S. Berns?
  *
  * @todo Spell checking for the documentation, if possible also grammar
  * checking with LanguageTool */
 
 /** @page hidpisupport High DPI support
  *
  * This library supports High DPI out of the box.
  *
  * The only thing that requires special attention are icons.
  *
  * @section iconsupport Icon support
  *
  * This library uses by default a possibly existing icon theme
  * if available in Qt. Windows and Mac do not provide icon themes by
  * default, while Linux usually provides them. SVG is pretty much the standard
  * nowadays and the only reliably way to have crisp icons also on desktop
  * scales like 1.25 or 1.5. If high-DPI icons are available depends finally
  * on your operation system. Only if no icon at all is provided by the
  * operation system, the library falls back to built-in high-DPI SVG icons.
  *
  * Note that QSvgIconEnginePlugin is a mandatory run-time
  * dependency (see @ref build for details).
  *
  * @section qt5icons Qt5 legacy
  *
  * While <a href="https://bugreports.qt.io/browse/QTBUG-89279">Qt6
  * renders icons always with high-DPI</a> (if available),
  * Qt5 renders icons by default in low resolution. This applies even
  * for SVG icons on high-DPI displays! Application developers have to enable
  * high-DPI icon rendering manually with the following code (which should be
  * put by convention <em>before</em> creating the <tt>QCoreApplication</tt>
  * object):
  * <br/><tt>QCoreApplication::setAttribute(Qt::AA_UseHighDpiPixmaps);</tt> */
 
 /** @page howtogetstarted How to get started
  *
  * How to get started? @ref PerceptualColor::ColorDialog provides a
  * perceptual replacement for QColorDialog:
  * @snippet testcolordialog.cpp ColorDialog Get color
  *
  * This is a minimal, but complete example project showing how to use
  * this library:
  *
  * CMakeLists.txt:
  * @include examples/CMakeLists.txt
  *
  * example.cpp:
  * @include examples/example.cpp */
 
 /** @page i18nl10n Internationalization and localization
  *
  * @section Internationalization
  *
  * This library is internationalized (i18n). This include also support
  * for right-to-left layouts in the widgets.
  *
  * @section Localization
  *
  * This library is also localized (l10n). The localization is divided
  * into two separate areas, which behave differently and independently
  * of each other.
  *
  * 1. Translation.
  * 2. Everything else.
  *
  * @subsection localizationtranslation Translation
  *
  * The translation of user-visible strings is a global setting for the whole
  * library. The language for the translation is auto-detected depending on
  * the settings of the current computer. You can specify the translation
  * explicitly with @ref PerceptualColor::setTranslation(), which can also
  * be used to change the translation dynamically (during program execution).
  * The various translations are build directly into the library binary;
  * no external files need to be available or loaded.
  *
  * @subsection localizationeverythingelse Everything else
  *
  * All other localization settings (like which decimal separator to use or
  * which date format to use) are individual per widget, depending on the
  * <tt><a href="https://doc.qt.io/qt-6/qwidget.html#locale-prop">
  * QWidget::locale()</a></tt> property. Changing the localization dynamically
  * (during program execution) is currently not supported.
  *
  * @internal
  *
  * @todo Support changing the localization dynamically (during program
  * execution). This affects also @ref PerceptualColor::MultiSpinBox and
  * the <tt>QSpinBox</tt> in @ref PerceptualColor::ColorDialog that is
  * used for the opacity and maybe also the RGB-Hex-LineEdit.
  *
  * @todo Provide more localizations! */
 
 /** @page licenseinfo License
  *
  * @copyright
  * - We follow the <a href="https://reuse.software/">“Reuse”
  *   specification</a>.
  * - The files from which the library (and this documentation as well)
  *   are generated do not all have the same license; instead, each file
  *   is subject to one of the following permissive licenses:
  *   - BSD-2-Clause OR MIT (for example, some C++ source code files)
  *   - MIT (for example, some icons)
  *   - BSD-3-Clause (for example, some CMake files)
  *   - CC0-1.0 (for example, some color profiles)
  * - Other parts of the codebase (which will
  *   <em>not</em> be installed by CMake, examples include <em>autotests</em>
  *   and <em>utils</em>) might have different licenses and/or include
  *   compiled-in resources that have different licenses. */
 
 /** @internal
  *
  * @page measurementdetails Measurement details
  *
  * When this library deals with raster graphics, it simultaneously uses
  * concepts concerning measurement. This page describes the terminology
  * used within the documentation of this library.
  *
  * @section introduction Introduction
  * Today’s displays have a wide range of physical pixel density (pixels
  * per length). Displays with a high physical pixel density are called
  * <b>High-DPI displays</b> or <b>HiDPI displays</b> or <b>Retina displays</b>.
  *
  * @section unitsofmeasurement Units of measurement
  * As Qt documentation says:
  *      “<em>Qt uses a model where the application coordinate system is
  *      independent of the display device resolution. The application
  *      operates in </em>device-independent pixels<em>, which are then
  *      mapped to the physical pixels of the display via a scale
  *      factor, known as the </em>device pixel ratio<em>.</em>”
  *
  * So when rendering widgets, there are two different units of measurement
  * to consider:
  * - <b>Device-independent pixels</b> are the  unit of measurement for
  *   widgets, windows, screens, mouse events and so on in Qt.
  * - <b>Physical pixels</b> are the unit that measures actual physical
  *   display pixels.
  *
  * The conversion factor between these two units of measurement is
  * <tt>QPaintDevice::devicePixelRatioF()</tt>, a floating point number.
  * It is usually <tt>1.00</tt> on classic low-resolution screens. It could be
  * for example <tt>1.25</tt> or <tt>2.00</tt> on displays with a higher
  * pixel density.
  *
  * @section coordinatepointsversuspixelpositions Coordinate points versus pixel positions
  *
  * - <b>Coordinate points</b> are points in the mathematical sense, that
  *   means they have zero surface. Coordinate points should be stored as
  *   <em>floating point numbers</em>.
  * - <b>Pixel positions</b> describe the position of a particular pixel
  *   within the pixel grid. Pixels are surfaces, not points. A pixel is a
  *   square of the width and length <tt>1</tt>. The pixel at position
  *   <tt>QPoint(x, y)</tt> is the square with the top-left edge at coordinate
  *   point <tt>QPoint(x, y)</tt> and the bottom-right edge at coordinate
  *   point <tt>QPoint(x+1, y+1)</tt>. Pixel positions should be stored
  *   as <em>integer numbers</em>.
  *
  * Some functions (like mouse events) work with pixel positions, other
  * functions (like antialiased floating-point drawing operations) work
  * with coordinate points. It’s important to always distinguish correctly
  * these two different concepts. See https://doc.qt.io/qt-6/coordsys.html
  * for more details about integer precision vs floating point precision
  * on drawing operations. */
 
 /** @page namespacepollution Name⁠space pollution
  *
  * This library avoids namespace pollution and collisions:
  *
  * - Macros are prefixed with <tt>PERCEPTUALCOLOR_</tt>.
  * - Symbols that have external linkage are within the
  *   namespace <tt>PerceptualColor</tt>. (Exception: The
  *   <a href="https://doc.qt.io/qt-5/resources.html">
  *   Qt resource system</a> generates functions prefixed
  *   with <tt>qInitResources_</tt> and <tt>qCleanupResources_</tt>
  *   that are not within the previously mentioned namespace.)
  * - Resources within the <a href="https://doc.qt.io/qt-5/resources.html">Qt
  *   resource system</a> are within the folder <tt>:/PerceptualColor/</tt>.  */
 
 /** @internal
  *
  * @page pimpl Pointer to implementation idiom
  *
  * This library uses the <em>pointer to implementation</em> idiom
  * (also known as pimpl idiom, d-pointer idiom or opaque-pointer idiom)
  * in almost all classes that are part of the public API, and also in
  * some classes that are part of the private API. The idiom is described
  * in detail in the Internet. The following flavour of the idiom is used
  * in our library:
  *
  * - The pointer to the implementation is called <tt>d_pointer</tt>. It’s of
  *   type @ref PerceptualColor::ConstPropagatingUniquePointer which provides
  *   const-correctness.
  * - The back pointer is called <tt>q_pointer</tt>. (A “q” is just a “d”
  *   pointing in a different direction, get it?). It’s
  *   of type @ref PerceptualColor::ConstPropagatingRawPointer which provides
  *   const-correctness.
  * - <a href="https://euroquis.nl//kde/2022/01/31/dptr.html"> The
  *   <tt>q_pointer</tt> <em>must not</em> ever be used in the destructor
  *   of the private implementation.</a> Rationale: All functions of the
  *   public class could potentially use the d_pointer. However, at the moment
  *   the destructor of the private class has started, the use of the d_pointer
  *   is already undefined behaviour. With some compilers this leads to an
  *   immediate crash, with other compilers it leads to
  *   silent undefined behaviour.
  *
  * The private classes are <em>not</em> nested
  * classes of their public counterpart. This is also
  * <a href="https://community.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B#Using_a_d-Pointer">
  * what the the KDE community recommends</a>:
  * > It is also possible (but not recommended) to declare the private
  * > class […] as a nested private class (e.g. Foo::Private). […] remember
  * > that the nested private class will inherit the public symbol visibility
  * > of the containing exported class. This will cause the functions
  * > of the private class to be named in the dynamic library's symbol
  * > table. […] Other downsides […] include […] the fact that it can't be
  * > forward-declared in unrelated headers anymore (which can be useful to
  * > declare it as a friend class).
  *
  * @note This idiom is also used by Qt itself, and Qt even provides some macros
  * and extension points (<tt>Q_DECLARE_PRIVATE</tt>, <tt>Q_D</tt>, a protected
  * member called <tt>d_ptr</tt> in almost all classes…), that help dealing
  * with the pimpl idiom. Though available, these Qt features are not
  * officially documented; and they would also interfere with private
  * implementations of Qt itself without documented behaviour, which seems
  * inappropriate. Furthermore, the Qt pimpl idiom is complicate because
  * it uses (for performance reasons) inheritance between the private
  * implementation classes. This breaks, however, the encapsulation, because
  * all formerly private elements of a class become protected now. Our class
  * hierarchy is not that deep, so the performance gain might not be worth
  * the additional code complexity. Therefore, this library uses a more simple
  * pimpl idiom without inheritance of the private implementation. It has
  * however all the other features of the Qt pimpl idiom, including
  * <tt>const</tt> propagating access to the private implementation
  * thanks to @ref PerceptualColor::ConstPropagatingUniquePointer and
  * @ref PerceptualColor::ConstPropagatingRawPointer. And, at difference
  * to Qt’s pimpl idiom, it keeps private code strictly private.
  * Note however, that switching later from our current pimpl idiom to
  * the polymorphic Qt pimpl idiom would break the binary
  * compatibility. See also the document <em>
  * <a href="https://accu.org/journals/overload/18/100/love_1718/">Interface
  * Versioning in C++</a></em> and KDE’s information document <em>
  * <a
  * href="https://community.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B">
  * Binary Compatibility Issues With C++</a></em> and for details.
  *
  * @note It would be nice to have the d_pointer and q_pointer
  * be themselves be declared <tt>const</tt>, because this would
  * clearly communicate that those pointers are not expected to change
  * the address they point to. Unfortunately, apparently this does not
  * work with neither @ref PerceptualColor::ConstPropagatingUniquePointer nor
  * @ref PerceptualColor::ConstPropagatingRawPointer as it would change also
  * all the access rights to the pointed object to always <tt>const</tt>. */
 
 /** @page qtstylesheetssupport Qt Style Sheets support
  *
  * The widget of this library supports the Qt Style Sheet
  * <a href="https://doc.qt.io/qt-6/stylesheet-reference.html#list-of-stylable-widgets">
  * properties of the Qt class they are derived from</a> only where it
  * makes sense. So you set the <tt>background-color</tt> of
  * a @ref PerceptualColor::MultiSpinBox. But you should not set
  * it for a @ref PerceptualColor::GradientSlider because the point
  * of this widget is to always use the gradient as the background;
  * the same applies for most widgets that showcase colors.
  *
  * When using class names of this library as
  * selectors in Qt Style Sheets, you have to
  * <a href="https://doc.qt.io/Qt-6/stylesheet-syntax.html#widgets-inside-c-namespaces">
  * substitute the namespace separator <tt>::</tt> by <tt>\--</tt></a>
  * to get a working selector: To select the class
  * @ref PerceptualColor::ColorDialog, use the selector
  * <tt>PerceptualColor\--ColorDialog</tt>. */
 
 /** @page lchrange Range of LCH values
  *
  *
  * The LCH values in this library are implemented with the following range:
  *
  * |               |    l     |    a     |    b     |    c     |    h     |
  * | :------------ | :------: | :------: | :------: |:-------: | :------: |
  * | CIELab/CIELCh | [0, 100] | [0, 255] | [0, 255] | [0, 255] | [0, 360[ |
  * | Oklab/Oklch   |  [0, 1]  |  [0, 2]  |  [0, 2]  |  [0, 2]  | [0, 360[ |
  *
  * This range is enough to cover the hole range of human perception. (Note
  * that the actual range of human perception has an irregular shape and
  * covers only parts of all possible combinations of LCH values. And
  * the actual gamut of real-word output devices is smaller than the
  * human perception.)
  *
  * @internal
  *
  * @section lchrangerationale Rationale
  *
  * The gamut of actual human perception within the LAB color model (and
  * its alternative representation LCH) has an irregular shape. Its maximum
  * extensions:
  *
  * <b>Lightness (L)</b>
  * The maximum range for LAB/LCH lightness is limited by
  * definition: <tt>[0, 100]</tt> for CIELch and <tt>[0, 1]</tt> for Oklch.
  *
  * <b>Hue (H)</b>
  * The maximum range for LCH hue is limited by definition to
  * the full circle: <tt>[0°, 360°[</tt>.
  *
  * <b>a, b, Chroma (C)</b>
  * The maximum range for a, b and Chroma (C) is complex. It is <em>not</em>
  * limited by definition. A useful limit is the actual human perception.
  *
  * | CIELab/CIELCh                 |        a          |         b         |      C      |
  * | :---------------------------- |:----------------: | :---------------: | :---------: |
  * | Usual implementation¹         |    [−128, 127]    |    [−128, 127]    |             |
  * | Human perception (Wikipedia)² |    [−170, 100]    |    [−100, 150]    |             |
  * | Human perception (2° D50)³    | [−165.39, 129.05] | [−132.62, 146.69] | [0, 183.42] |
  * | Human perception (2° D65)³    | [−170.84, 147.84] | [−129.66, 146.78] | [0, 194.84] |
  * | Human perception (10° D65)³   | [−164.29, 115.14] | [−116.10, 145.53] | [0, 186.17] |
  *
  * 1. The range of  <tt>[−128, 127]</tt> is in C++ a signed 8‑bit integer. But
  *    this data type usually used in software implementations is (as the table
  *    clearly shows) not enough to cover the hole range of actual human
  *    color perception.
  * 2. Ranges of CIELAB coordinates according to the
  *    <a href="https://de.wikipedia.org/w/index.php?title=Lab-Farbraum&oldid=197156292">
  *    German Wikipedia</a>.
  * 3. The German association <em>Freie Farbe e. V.</em> has
  *    published a calculation of the
  *    <a href="https://www.freiefarbe.de/artikel/grenzen-des-cielab-farbraums/">
  *    shape of actual human perception</a> for various observation angles
  *    and illuminants. This data contains only the CIELAB coordinates
  *    (L, a, b). From this data, the chroma (C) component can be calculated
  *    easily as Pythagoras of the a axis and b axis value pairs:
  *    √(a² + b²) = C.
  *
  * Logically, the chroma value can reach higher values than a and b, however,
  * for simplicity it seems appropriate to use the same range for chroma, a and
  * b. Following these tables, the maximum chroma in human perception in CIELCh
  * is <tt>194.84</tt>. As apparently this depends on viewing  conditions,
  * it might be a good idea to use a slightly higher limit, to be sure that the
  * value will never be too small. Here, <tt>200</tt> might be a good candidate.
  * However, some gamuts are wider. The <em>LargeRGB-elle-V2-g22.icc</em>
  * profile goes up to a chroma value of 245. Finally, we have fixed the valid
  * range to 255, because this is for sure enough to cover the human
  * perception, and it will cover almost all existing profiles.
  *
  * For Oklch we have observed up to 1.52 as chroma values when using the
  * <em>LargeRGB-elle-V2-g22.icc</em> profile. As with CIELCh chroma, we have
  * added a safety margin, rounded up to the next integer, and finally
  * chosen 2 as maximum.
  *
  * @internal
  *
  * @sa @ref PerceptualColor::CielchD50Values::maximumChroma
  * @sa @ref PerceptualColor::OklchValues::maximumChroma
  *
  * @todo Why is the exact extend of non-imaginary colors unknown? Could it be
  * deduced from the <a href="https://en.m.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space">
  * CIE xy chromacity diagram</a>? And: Is 255 enough even for large color
  * spaces like <a href="https://en.m.wikipedia.org/wiki/Rec._2020">
  * Rec. 2020</a> or <a href="https://en.m.wikipedia.org/wiki/DCI-P3">
  * DCI-P3</a>?
  */
 
 /** @page versioninfo Version information at compiletime and runtime
  *
  * This library uses
  * <a href="https://semver.org/">Semantic Versioning 2.0.0</a>.
  *
  * Version information is provided by the header <tt>version.h</tt>
  *
  * To know against which version of this library you are <em>running</em>, use
  * - @ref PerceptualColor::perceptualColorRunTimeVersion
  *
  * To know against which version of this library you are <em>compiling</em>,
  * use
  * - @ref PERCEPTUALCOLOR_COMPILE_TIME_VERSION
  * - @ref PERCEPTUALCOLOR_COMPILE_TIME_VERSION_MAJOR
  * - @ref PERCEPTUALCOLOR_COMPILE_TIME_VERSION_MINOR
  * - @ref PERCEPTUALCOLOR_COMPILE_TIME_VERSION_PATCH */
 
 /** @brief The namespace of this library.
  *
  * All symbols that are provided in this library are encapsulated within this
  * namespace. */
 namespace PerceptualColor
 {
 } // namespace PerceptualColor