// ____ ______ __ // / __ \ / ____// / // / /_/ // / / / // / ____// /___ / /___ PixInsight Class Library // /_/ \____//_____/ PCL 2.4.23 // ---------------------------------------------------------------------------- // pcl/ICCProfile.h - Released 2022-03-12T18:59:29Z // ---------------------------------------------------------------------------- // This file is part of the PixInsight Class Library (PCL). // PCL is a multiplatform C++ framework for development of PixInsight modules. // // Copyright (c) 2003-2022 Pleiades Astrophoto S.L. All Rights Reserved. // // Redistribution and use in both source and binary forms, with or without // modification, is permitted provided that the following conditions are met: // // 1. All redistributions of source code must retain the above copyright // notice, this list of conditions and the following disclaimer. // // 2. All redistributions in binary form must reproduce the above copyright // notice, this list of conditions and the following disclaimer in the // documentation and/or other materials provided with the distribution. // // 3. Neither the names "PixInsight" and "Pleiades Astrophoto", nor the names // of their contributors, may be used to endorse or promote products derived // from this software without specific prior written permission. For written // permission, please contact info@pixinsight.com. // // 4. All products derived from this software, in any form whatsoever, must // reproduce the following acknowledgment in the end-user documentation // and/or other materials provided with the product: // // "This product is based on software from the PixInsight project, developed // by Pleiades Astrophoto and its contributors (https://pixinsight.com/)." // // Alternatively, if that is where third-party acknowledgments normally // appear, this acknowledgment must be reproduced in the product itself. // // THIS SOFTWARE IS PROVIDED BY PLEIADES ASTROPHOTO AND ITS CONTRIBUTORS // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED // TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PLEIADES ASTROPHOTO OR ITS // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, // EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, BUSINESS // INTERRUPTION; PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; AND LOSS OF USE, // DATA OR PROFITS) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE // POSSIBILITY OF SUCH DAMAGE. // ---------------------------------------------------------------------------- #ifndef __PCL_ICCProfile_h #define __PCL_ICCProfile_h /// \file pcl/ICCProfile.h #include #include #include #include namespace pcl { // ---------------------------------------------------------------------------- /*! * \defgroup color_management Color Management Classes */ /*! * \namespace pcl::ICCProfileClass * \brief Representation of ICC color profile classes * \ingroup color_management * * * * * * * * * * * *
ICCProfileClass::Unknown Unknown or unsupported ICC profile class
ICCProfileClass::Any Any ICC profile class
ICCProfileClass::InputDevice Input device (scanner) profile
ICCProfileClass::DisplayDevice Display device (monitor) profile
ICCProfileClass::OutputDevice Output device (printer) profile
ICCProfileClass::DeviceLink Device link profile
ICCProfileClass::ColorSpaceConversion Color space conversion profile
ICCProfileClass::AbstractProfile Abstract profile
ICCProfileClass::NamedColorProfile Named color profile
*/ namespace ICCProfileClass { enum mask_type { Unknown = 0x80000000, Any = 0x00000000, InputDevice = 0x00000001, DisplayDevice = 0x00000002, OutputDevice = 0x00000004, DeviceLink = 0x00000008, ColorSpaceConversion = 0x00000010, AbstractProfile = 0x00000020, NamedColorProfile = 0x00000040 }; } /*! * \class pcl::ICCProfileClasses * \brief A combination of ICCProfileClass values. * \ingroup color_management */ typedef Flags ICCProfileClasses; // ---------------------------------------------------------------------------- /*! * \namespace pcl::ICCColorSpace * \brief Representation of data and connection color spaces in ICC color profiles. * \ingroup color_management * * * * * * * * * * * * * * * * *
ICCColorSpace::Unknown Unknown or unsupported color space
ICCColorSpace::Any Any color space in an ICC profile
ICCColorSpace::XYZ CIE XYZ color space
ICCColorSpace::Lab CIE L*a*b* color space
ICCColorSpace::Luv CIE L*u*v* color space
ICCColorSpace::YCbCr YCbCr color space
ICCColorSpace::Yxy Yxy (luminance and chromaticity coordinates)
ICCColorSpace::RGB RGB color space
ICCColorSpace::Gray Grayscale color space
ICCColorSpace::HSV HSV color ordering system
ICCColorSpace::HLS HLS color ordering system
ICCColorSpace::CMYK CMYK color space
ICCColorSpace::CMY CMY color space
ICCColorSpace::LuvK LuvK color space
* * Other color spaces supported by the ICC profile specification, as for * example 2-color and 15-color spaces, are unknown to this implementation. */ namespace ICCColorSpace { enum mask_type { Unknown = 0x80000000, Any = 0x00000000, XYZ = 0x00000001, Lab = 0x00000002, Luv = 0x00000004, YCbCr = 0x00000008, Yxy = 0x00000010, RGB = 0x00000020, Gray = 0x00000040, HSV = 0x00000080, HLS = 0x00000100, CMYK = 0x00000200, CMY = 0x00000400, LuvK = 0x00000800 }; } /*! * \class pcl::ICCColorSpaces * \brief A combination of ICCColorSpace values. * \ingroup color_management */ typedef Flags ICCColorSpaces; // ---------------------------------------------------------------------------- /*! * \namespace pcl::ICCRenderingIntent * \brief ICC rendering intents * \ingroup color_management * * * * * * *
ICCRenderingIntent::Perceptual Perceptual rendering intent (photographic images)
ICCRenderingIntent::Saturation Saturation rendering intent (graphics)
ICCRenderingIntent::RelativeColorimetric Relative colorimetric rendering intent (match white points)
ICCRenderingIntent::AbsoluteColorimetric Absolute colorimetric rendering intent (proofing)
*/ namespace ICCRenderingIntent { enum value_type { Perceptual, Saturation, RelativeColorimetric, AbsoluteColorimetric }; } // ---------------------------------------------------------------------------- /*! * \namespace pcl::ICCRenderingDirection * \brief ICC transform rendering direction * \ingroup color_management * * * * * *
ICCRenderingDirection::Input Denotes a rendering intent applied to input pixel values.
ICCRenderingDirection::Output Denotes a rendering intent applied to output pixel values.
ICCRenderingDirection::Proofing Denotes a rendering intent applied by a proofing transform.
*/ namespace ICCRenderingDirection { enum value_type { Input, Output, Proofing }; } // ---------------------------------------------------------------------------- /*! * \class ICCProfile * \brief A high-level interface to ICC color profiles * * %ICCProfile is a high-level interface to the ICC profile handling * functionality implemented in the PixInsight core application. An instance of * %ICCProfile transports an ICC profile structure that can be embedded in * image files or used to build color management transformations with the * ICCProfileTransformation class. * * %ICCProfile implements a set of utility functions for profile validation, * profile information retrieval, profile disk I/O and profile directory * search, among other tasks. * * \ingroup color_management * \sa ICCProfileTransformation */ class PCL_CLASS ICCProfile { public: /*! * Represents an opaque handle to an internal ICC profile. */ typedef void* handle; /*! * Represents an ICC profile device class. */ typedef ICCProfileClass::mask_type profile_class; /*! * Represents an ICC profile color space. */ typedef ICCColorSpace::mask_type color_space; /*! * Represents an ICC rendering intent. */ typedef ICCRenderingIntent::value_type rendering_intent; /*! * Represents an ICC transform rendering direction. */ typedef ICCRenderingDirection::value_type rendering_direction; /*! * Constructs an empty %ICCProfile object. An empty %ICCProfile doesn't * store an ICC profile structure. */ ICCProfile() = default; /*! * Copy constructor. */ ICCProfile( const ICCProfile& ) = default; /*! * Move constructor. */ ICCProfile( ICCProfile&& ) = default; /*! * Constructs an %ICCProfile object and loads an ICC profile from a file at * the specified \a profilePath. * * If the specified file does not exist, is not readable, or does not * contain a valid ICC profile structure, this constructor throws an Error * exception. */ ICCProfile( const String& profilePath ) { Load( profilePath ); } /*! * Constructs an %ICCProfile object to store a copy of the raw ICC profile * structure available in the specified container. This constructor simply * calls Set( rawData ). */ ICCProfile( const ByteArray& rawData ) { Set( rawData ); } /*! * Constructs an %ICCProfile object to store a copy of the raw ICC profile * structure at the specified location. This constructor simply calls * Set( rawData ). */ ICCProfile( const void* rawData ) { Set( rawData ); } /*! * Destroys an %ICCProfile object. If this object stores an ICC profile * structure, it is deallocated upon destruction. */ virtual ~ICCProfile() { } /*! * Copy assignment operator. Returns a reference to this object. */ ICCProfile& operator =( const ICCProfile& ) = default; /*! * Move assignment operator. Returns a reference to this object. */ ICCProfile& operator =( ICCProfile&& ) = default; /*! * Returns true iff this object stores an ICC color profile structure. */ bool IsProfile() const { return !m_data.IsEmpty(); } /*! * A convenience synonym for IsProfile(). */ operator bool() const { return IsProfile(); } /*! * Returns true if this profile has been read from a disk file. Otherwise * this object either does not transport an ICC profile, or the profile has * been generated or assigned directly from a memory buffer. */ bool IsDiskProfile() const { return !m_path.IsEmpty(); } /*! * Returns true iff the ICC profile stored in this object is identical to the * profile stored in \a other %ICCProfile object. * * If necessary, this function performs a byte-to-byte comparison between * both ICC profile structures (when both have the same size in bytes). */ bool IsSameProfile( const ICCProfile& other ) const; /*! * Returns a reference to the immutable container that stores an ICC profile * in this %ICCProfile object. The returned ByteArray is empty if this * object does not transport an ICC color profile. */ const ByteArray& ProfileData() const { return m_data; } /*! * Returns the length of the stored ICC profile structure in bytes. Returns * zero if this %ICCProfile object doesn't store an ICC color profile. */ size_type ProfileSize() const; /*! * Returns the full file path of the stored ICC profile, if this object * transports an ICC profile structure that has been loaded from a file, or * an empty string otherwise. */ String FilePath() const { return m_path; } /*! * Returns the localized profile description of the stored ICC profile. * * \param language Optional language code (ISO 639/2) of the requested * profile description. The default value is "en" for * English. * * \param country Optional country code (ISO 3166) of the requested * profile description. The default value is "US" for * United States. * * If this object does not transport an ICC profile, this routine returns an * empty string. Otherwise this routine will always return a valid profile * description, even if no localized version exists for the requested * language and country. The returned description will be as close as * possible to the requested localization. */ String Description( const char* language = "en", const char* country = "US" ) const; /*! * Returns the localized manufacturer information of the stored ICC profile. * * See Description( const char*, const char* ) const for detailed * information on function parameters and behavior. */ String Manufacturer( const char* language = "en", const char* country = "US" ) const; /*! * Returns the localized device model information of the stored ICC profile. * * See Description( const char*, const char* ) const for detailed * information on function parameters and behavior. */ String Model( const char* language = "en", const char* country = "US" ) const; /*! * Returns the localized copyright information of the stored ICC profile. * * See Description( const char*, const char* ) const for detailed * information on function parameters and behavior. */ String Copyright( const char* language = "en", const char* country = "US" ) const; /*! * Retrieves localized description, manufacturer, device model and copyright * information from the stored ICC profile. * * If this object does not transport an ICC profile, this routine clears the * \a description, \a manufacturer, \a model and \a copyright strings. If a * valid ICC profile is stored in this object, the passed strings will be * assigned with the corresponding information, as close as possible to the * requested localization. See Description( const char*, const char* ) const * for detailed information on localization parameters. */ void GetInformation( String& description, String& manufacturer, String& model, String& copyright, const char* language = "en", const char* country = "US" ) const; /*! * Returns the ICC profile class of the stored profile. See the * ICCProfileClass namespace for supported profile classes. * * If this object doesn't transport an ICC profile, this function returns * ICCProfileClass::Unknown. */ profile_class Class() const; /*! * Returns the ICC color space of the stored profile. See the ICCColorSpace * namespace for supported color spaces. * * If this object doesn't transport an ICC profile, this function returns * ICCColorSpace::Unknown. */ color_space ColorSpace() const; /*! * Returns true iff this object stores an RGB ICC profile. */ bool IsRGB() const { return ColorSpace() == ICCColorSpace::RGB; } /*! * Returns true iff this object stores a grayscale ICC profile. */ bool IsGrayscale() const { return ColorSpace() == ICCColorSpace::Gray; } /*! * Returns true iff this object stores an ICC profile that supports the * specified \a intent in the specified transform \a direction. See the * ICCRenderingIntent and ICCRenderingDirection namespaces, respectively, * for supported rendering intents and directions. */ bool SupportsRenderingIntent( rendering_intent intent, rendering_direction direction ) const; /*! * Returns true iff this object stores an embedded ICC profile. * * An embedded ICC profile must have the Embedded Profile bit field * (bit #0 of header byte #44) set. */ bool IsEmbedded() const; /*! * Sets or clears the Embedded Profile header bit field (bit #0 of * header byte #44) of the stored ICC profile. * * \note If this %ICCProfile object is being used to embed an ICC profile in * an image file, the Embedded Profile flag must be set before * embedding. */ void SetEmbeddedFlag( bool on = true ); /*! * Clears or sets the Embedded Profile header bit field (bit #0 of * header byte #44) of the stored ICC profile. * * This is a convenience member function, equivalent to * SetEmbeddedFlag( false ) */ void ClearEmbeddedFlag() { SetEmbeddedFlag( false ); } /*! * Loads an ICC profile from a disk file at \a profilePath and stores it in * this %ICCProfile object. * * If this object stores an ICC profile before calling this function, it is * deallocated upon successful load of the specified ICC profile. * * If the specified file does not exist or is not readable, or if the file * contains data that cannot be identified as a valid ICC profile, this * function throws an Error exception. */ void Load( const String& profilePath ); /*! * Forces this %ICCProfile object to store a copy of the ICC profile stored * in the specified ByteArray container. Previously existing ICC profile * data will be deallocated. * * If the specified container is empty, calling this function is equivalent * to Clear(). If the container is not empty, it must store a valid ICC * profile structure; otherwise this function will throw an Error exception. */ void Set( const ByteArray& profile ); /*! * Forces this %ICCProfile object to store a copy of the raw ICC profile * data at the specified location. Previously existing ICC profile data will * be deallocated. * * The specified pointer must be the starting address of a valid ICC profile * structure; otherwise this function will throw an Error exception. */ void Set( const void* rawData ); /*! * Deallocates the stored ICC profile structure and all auxiliary data. * * If the profile has been opened before calling this function, any existing * handle to it will not be closed or invalidated. */ void Clear() { m_data.Clear(); m_path.Clear(); } /*! * Opens the ICC profile stored in this %ICCProfile object. Returns a handle * to the opened ICC profile. * * If this object does not transport a valid ICC profile structure, this * function throws an Error exception. * * Color management transformations are defined through handles to open ICC * profiles. The caller is responsible for closing ICC profile handles when * they are no longer needed. */ handle Open() const { return Open( m_data ); } /*! * Exchanges two ICC profiles \a x1 and \a x2. */ friend void Swap( ICCProfile& x1, ICCProfile& x2 ) { pcl::Swap( x1.m_data, x2.m_data ); pcl::Swap( x1.m_path, x2.m_path ); } /*! * Opens an ICC profile disk file at \a profilePath. Returns a handle to the * opened ICC profile. * * If the specified file does not exist or is not readable, or if it does * not contain a valid ICC profile structure, this function throws an Error * exception. */ static handle Open( const String& profilePath ); /*! * Opens an ICC profile from raw ICC profile data stored at the specified * location. Returns a handle to the opened ICC profile. * * If the argument does not point to a valid ICC profile structure, this * function throws an Error exception. */ static handle Open( const void* rawData ); /*! * Opens an ICC profile stored in the specified ByteArray container \a icc. * Returns a handle to the opened ICC profile. * * If the specified container is empty or does not contain a valid ICC * profile structure, this function throws an Error exception. */ static handle Open( const ByteArray& icc ) { return Open( icc.Begin() ); } /*! * Closes an open ICC profile handle. */ static void Close( handle h ); /*! * Validates an ICC profile handle. Returns true iff the specified handle is * a valid handle to an open ICC profile. */ static bool IsValidHandle( handle h ); /*! * Validates an ICC profile structure stored in a file at \a profilePath. * Returns true iff the specified file exists and contains a valid ICC * profile. */ static bool IsValidFile( const String& profilePath ); /*! * Validates an ICC profile from raw ICC profile data stored at the * specified location. Returns true iff the argument points to a valid ICC * profile structure. */ static bool IsValid( const void* rawdata ); /*! * Validates an ICC profile structure stored in the specified ByteArray * container \a icc. Returns true iff the container stores a valid ICC * profile. */ static bool IsValid( const ByteArray& icc ) { return IsValid( icc.Begin() ); } /*! * Returns the localized profile description of an open ICC profile. * * \param h Handle to an open ICC profile, from which the requested * profile description will be obtained. * * \param language Optional language code (ISO 639/2) of the requested * profile description. The default value is "en" for * English. * * \param country Optional country code (ISO 3166) of the requested * profile description. The default value is "US" for the * United States. * * This routine will always return a valid profile description, even if no * localized version is available for the requested language and country. * The returned description will be as close as possible to the requested * localization. */ static String Description( handle h, const char* language = "en", const char* country = "US" ); /*! * Returns the localized manufacturer information of an open ICC profile. * * See Description( handle, const char*, const char* ) for detailed * information on function parameters and behavior. */ static String Manufacturer( handle h, const char* language = "en", const char* country = "US" ); /*! * Returns the localized device model information of an open ICC profile. * * See Description( handle, const char*, const char* ) for detailed * information on function parameters and behavior. */ static String Model( handle h, const char* language = "en", const char* country = "US" ); /*! * Returns the localized copyright information of an open ICC profile. * * See Description( handle, const char*, const char* ) for detailed * information on function parameters and behavior. */ static String Copyright( handle h, const char* language = "en", const char* country = "US" ); /*! * Returns the ICC profile class of an open profile. See the ICCProfileClass * namespace for supported profile classes. */ static profile_class Class( handle h ); /*! * Returns the ICC color space of an open profile. See the ICCColorSpace * namespace for supported color spaces. */ static color_space ColorSpace( handle h ); /*! * Returns true iff an open profile supports the specified \a intent in the * specified transform \a direction. See the ICCRenderingIntent and * ICCRenderingDirection namespaces, respectively, for supported rendering * intents and directions. */ static bool SupportsRenderingIntent( handle h, rendering_intent intent, rendering_direction direction ); /*! * Returns the list of profile directories. * * The profile directories contain the ICC profiles currently installed in * the system. The specific directories provided by this function are * platform-dependent. * * On X11 Linux and FreeBSD, there is no universally standardized color * management system. By default, the returned list will include a single * directory that can be one of the following: * * /usr/share/color/icc * ~/.color/icc * * for system-wide or user-local profiles, respectively. If none of the * above directories exists (and is readable) on the local filesystem, the * routine will return a fallback directory within the installation * directory tree of the PixInsight core application. * * On OS X, the returned list may contain one or more from the following * directories: * * ~/Library/ColorSync/Profiles * /Library/ColorSync/Profiles * /Network/Library/ColorSync/Profiles * * Finally, on Windows this function returns the current COLOR directory, * as reported by the GetColorDirectory() Win32 API function. */ static StringList ProfileDirectories(); /*! * Gets a list of full paths for every ICC profile on a given directory. * * \param dirPath Optional path to a search directory. If no directory is * specified, or if an empty string is passed, the whole * list of system profile directories, as returned by the * ProfileDirectories() member function, will be searched * recursively. * * This routine performs a recursive directory search on the specified * directory, or on each system profiles directory if no directory is * specified. Profiles are quickly identified by opening them and validating * their profile headers. The search is not limited to any particular file * suffix such as ".icc" or ".icm". * * Returns a list of full paths to the ICC profile files found on the * search directory. */ static StringList FindProfiles( const String& dirPath = String() ); /*! * Finds the file path to an installed ICC profile, given its profile * description. * * \param description Description of the profile to search for. * * \param exactMatch If true, this routine will search for a profile that * matches the specified \a description exactly, including * character case. If false, the routine will report any * profile whose description contains the specified * description performing case-insensitive comparisons. * The default value is true, so profile descriptions must * be matched exactly by default. * * This function searches the system color directories, as reported by the * ProfileDirectories() member function, until it finds an ICC profile with * the specified \a description. This routine performs a recursive directory * search on each profiles directory. * * Returns the full path to the ICC profile, or an empty string if no * profile was found matching the specified \a description. */ static String FindInstalledProfile( const String& description, bool exactMatch = true ); /*! * Extracts a subset of profile paths and their descriptions from a * previously retrieved list of full paths to ICC profiles. * * \param[out] selectedDescriptionsList The list of profile descriptions * for selected profiles. * * \param[out] selectedPathsList The list of paths to selected profiles. * * \param pathList The input list of paths to ICC profiles. * * \param spaces A combination of ICC color spaces for selected ICC * profiles. * * \param classes A combination of ICC device classes for selected ICC * profiles. */ static void ExtractProfileList( StringList& selectedDescriptionsList, StringList& selectedPathsList, const StringList& pathList, ICCColorSpaces spaces = ICCColorSpace::Any, ICCProfileClasses classes = ICCProfileClass::Any ); // ------------------------------------------------------------------------- /*! * \class pcl::ICCProfile::Info * \brief A structure to hold descriptive data about ICC profiles. * \ingroup color_management * * The %ICCProfile::Info structure is designed to be used with the * ICCProfile::FindProfilesByColorSpace() utility function. */ struct Info { String description; //!< Description of an ICC profile String path; //!< Full path to an ICC profile disk file /*! * Constructs an %ICCProfile::Info structure. */ Info( const String& a_description, const String& a_path = String() ) : description( a_description ) , path( a_path ) { } /*! * Equality operator. Two %ICCProfile::Info objects are equal if their * profile descriptions are equal. */ bool operator ==( const Info& x ) const { return description == x.description; } /*! * Less than relational operator. %ICCProfile::Info objects are sorted by * their profile descriptions */ bool operator <( const Info& x ) const { return description < x.description; } }; /*! * Represents a sorted list of ICC profile information items. */ typedef SortedArray profile_list; /*! * Returns a sorted list of profile information items (full file paths and * profile description strings) for the existing ICC profiles of the * specified ICC profile color spaces. * * \param spaces A combination of ICC profile color spaces to search for. * * The search operation is restricted to the system color directories, as * reported by the ProfileDirectories() member function. This routine * performs a recursive directory search on each profiles directory. * * Duplicate profiles are not included in the output \a info list. If the * same profile is present in two or more directories, or if the same * profile is present on the same directory with different file names, only * the first instance seen will be included. Profiles are compared by their * profile descriptions. */ static profile_list FindProfilesByColorSpace( ICCColorSpaces spaces ); /*! * \internal */ static void ThrowErrorWithCMSInfo( const String& message ); private: ByteArray m_data; // ICC profile data String m_path; // empty if this is an embedded or newly created profile }; // ---------------------------------------------------------------------------- } // pcl #endif // __PCL_ICCProfile_h // ---------------------------------------------------------------------------- // EOF pcl/ICCProfile.h - Released 2022-03-12T18:59:29Z