A high-level interface to ICC color profiles. More...

#include <ICCProfile.h>

Classes
class	Info
	A structure to hold descriptive data about ICC profiles. More...

Public Types
using	color_space = ICCColorSpace::mask_type

using	handle = void *

using	profile_class = ICCProfileClass::mask_type

using	profile_list = SortedArray< Info >

using	rendering_direction = ICCRenderingDirection::value_type

using	rendering_intent = ICCRenderingIntent::value_type

Public Member Functions
	ICCProfile ()=default

	ICCProfile (const ByteArray &rawData)

	ICCProfile (const ICCProfile &)=default

	ICCProfile (const String &profilePath)

	ICCProfile (const void *rawData)

	ICCProfile (ICCProfile &&)=default

virtual	~ICCProfile ()

profile_class	Class () const

void	Clear ()

void	ClearEmbeddedFlag ()

color_space	ColorSpace () const

String	Copyright (const char language="en", const char country="US") const

String	Description (const char language="en", const char country="US") const

String	FilePath () const

void	GetInformation (String &description, String &manufacturer, String &model, String &copyright, const char language="en", const char country="US") const

bool	IsDiskProfile () const

bool	IsEmbedded () const

bool	IsGrayscale () const

bool	IsProfile () const

bool	IsRGB () const

bool	IsSameProfile (const ICCProfile &other) const

void	Load (const String &profilePath)

String	Manufacturer (const char language="en", const char country="US") const

String	Model (const char language="en", const char country="US") const

handle	Open () const

	operator bool () const

ICCProfile &	operator= (const ICCProfile &)=default

ICCProfile &	operator= (ICCProfile &&)=default

const ByteArray &	ProfileData () const

size_type	ProfileSize () const

void	Set (const ByteArray &profile)

void	Set (const void *rawData)

void	SetEmbeddedFlag (bool on=true)

bool	SupportsRenderingIntent (rendering_intent intent, rendering_direction direction) const

Static Public Member Functions
static profile_class	Class (handle h)

static void	Close (handle h)

static color_space	ColorSpace (handle h)

static String	Copyright (handle h, const char language="en", const char country="US")

static String	Description (handle h, const char language="en", const char country="US")

static void	ExtractProfileList (StringList &selectedDescriptionsList, StringList &selectedPathsList, const StringList &pathList, ICCColorSpaces spaces=ICCColorSpace::Any, ICCProfileClasses classes=ICCProfileClass::Any)

static String	FindInstalledProfile (const String &description, bool exactMatch=true)

static StringList	FindProfiles (const String &dirPath=String())

static profile_list	FindProfilesByColorSpace (ICCColorSpaces spaces)

static bool	IsValid (const ByteArray &icc)

static bool	IsValid (const void *rawdata)

static bool	IsValidFile (const String &profilePath)

static bool	IsValidHandle (handle h)

static String	Manufacturer (handle h, const char language="en", const char country="US")

static String	Model (handle h, const char language="en", const char country="US")

static handle	Open (const ByteArray &icc)

static handle	Open (const String &profilePath)

static handle	Open (const void *rawData)

static StringList	ProfileDirectories ()

static bool	SupportsRenderingIntent (handle h, rendering_intent intent, rendering_direction direction)

Friends
void	Swap (ICCProfile &x1, ICCProfile &x2)

Detailed Description

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.

See also: ICCProfileTransformation

Definition at line 234 of file ICCProfile.h.

Member Typedef Documentation

◆ color_space

using pcl::ICCProfile::color_space = ICCColorSpace::mask_type

Represents an ICC profile color space.

Definition at line 251 of file ICCProfile.h.

◆ handle

using pcl::ICCProfile::handle = void*

Represents an opaque handle to an internal ICC profile.

Definition at line 241 of file ICCProfile.h.

◆ profile_class

using pcl::ICCProfile::profile_class = ICCProfileClass::mask_type

Represents an ICC profile device class.

Definition at line 246 of file ICCProfile.h.

◆ profile_list

using pcl::ICCProfile::profile_list = SortedArray<Info>

Represents a sorted list of ICC profile information items.

Definition at line 866 of file ICCProfile.h.

◆ rendering_direction

using pcl::ICCProfile::rendering_direction = ICCRenderingDirection::value_type

Represents an ICC transform rendering direction.

Definition at line 261 of file ICCProfile.h.

◆ rendering_intent

using pcl::ICCProfile::rendering_intent = ICCRenderingIntent::value_type

Represents an ICC rendering intent.

Definition at line 256 of file ICCProfile.h.

Constructor & Destructor Documentation

◆ ICCProfile() [1/6]

pcl::ICCProfile::ICCProfile ( )

default

Constructs an empty ICCProfile object. An empty ICCProfile doesn't store an ICC profile structure.

◆ ICCProfile() [2/6]

pcl::ICCProfile::ICCProfile ( const ICCProfile & )

default

Copy constructor.

◆ ICCProfile() [3/6]

pcl::ICCProfile::ICCProfile ( ICCProfile && )

default

Move constructor.

◆ ICCProfile() [4/6]

pcl::ICCProfile::ICCProfile ( const String & profilePath )

inline

Constructs an ICCProfile object and loads an ICC profile from a file at the specified 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.

Definition at line 287 of file ICCProfile.h.

◆ ICCProfile() [5/6]

pcl::ICCProfile::ICCProfile ( const ByteArray & rawData )

inline

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 ).

Definition at line 297 of file ICCProfile.h.

◆ ICCProfile() [6/6]

pcl::ICCProfile::ICCProfile ( const void * rawData )

inline

Constructs an ICCProfile object to store a copy of the raw ICC profile structure at the specified location. This constructor simply calls Set( rawData ).

Definition at line 307 of file ICCProfile.h.

◆ ~ICCProfile()

virtual pcl::ICCProfile::~ICCProfile ( )

inlinevirtual

Virtual destructor. If this object stores an ICC profile structure, it is deallocated upon destruction.

Definition at line 316 of file ICCProfile.h.

Member Function Documentation

◆ Class() [1/2]

profile_class pcl::ICCProfile::Class ( ) 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.

◆ Class() [2/2]

static profile_class pcl::ICCProfile::Class ( handle h )

static

Returns the ICC profile class of an open profile. See the ICCProfileClass namespace for supported profile classes.

◆ Clear()

void pcl::ICCProfile::Clear ( )

inline

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.

Definition at line 560 of file ICCProfile.h.

◆ ClearEmbeddedFlag()

void pcl::ICCProfile::ClearEmbeddedFlag ( )

inline

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 )

Definition at line 515 of file ICCProfile.h.

◆ Close()

static void pcl::ICCProfile::Close ( handle h )

static

Closes an open ICC profile handle.

◆ ColorSpace() [1/2]

color_space pcl::ICCProfile::ColorSpace ( ) 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.

◆ ColorSpace() [2/2]

static color_space pcl::ICCProfile::ColorSpace ( handle h )

static

Returns the ICC color space of an open profile. See the ICCColorSpace namespace for supported color spaces.

◆ Copyright() [1/2]

String pcl::ICCProfile::Copyright	(	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.

◆ Copyright() [2/2]

static String pcl::ICCProfile::Copyright	(	handle	h,
		const char *	language = `"en"`,
		const char *	country = `"US"`
	)

static

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.

◆ Description() [1/2]

String pcl::ICCProfile::Description	(	const char *	language = `"en"`,
		const char *	country = `"US"`
	)		const

Returns the localized profile description of the stored ICC profile.

Parameters

language	Optional language code (ISO 639/2) of the requested profile description. The default value is "en" for English.
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.

◆ Description() [2/2]

static String pcl::ICCProfile::Description	(	handle	h,
		const char *	language = `"en"`,
		const char *	country = `"US"`
	)

static

Returns the localized profile description of an open ICC profile.

Parameters

h	Handle to an open ICC profile, from which the requested profile description will be obtained.
language	Optional language code (ISO 639/2) of the requested profile description. The default value is "en" for English.
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.

◆ ExtractProfileList()

static void pcl::ICCProfile::ExtractProfileList	(	StringList &	selectedDescriptionsList,
		StringList &	selectedPathsList,
		const StringList &	pathList,
		ICCColorSpaces	spaces = `ICCColorSpace::Any`,
		ICCProfileClasses	classes = `ICCProfileClass::Any`
	)

static

Extracts a subset of profile paths and their descriptions from a previously retrieved list of full paths to ICC profiles.

Parameters

[out]	selectedDescriptionsList	The list of profile descriptions for selected profiles.
[out]	selectedPathsList	The list of paths to selected profiles.
	pathList	The input list of paths to ICC profiles.
	spaces	A combination of ICC color spaces for selected ICC profiles.
	classes	A combination of ICC device classes for selected ICC profiles.

◆ FilePath()

String pcl::ICCProfile::FilePath ( ) const

inline

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.

Definition at line 386 of file ICCProfile.h.

◆ FindInstalledProfile()

static String pcl::ICCProfile::FindInstalledProfile	(	const String &	description,
		bool	exactMatch = `true`
	)

static

Finds the file path to an installed ICC profile, given its profile description.

Parameters

description	Description of the profile to search for.
exactMatch	If true, this routine will search for a profile that matches the specified 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 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 description.

◆ FindProfiles()

static StringList pcl::ICCProfile::FindProfiles ( const String & dirPath = String() )

static

Gets a list of full paths for every ICC profile on a given directory.

Parameters

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.

◆ FindProfilesByColorSpace()

static profile_list pcl::ICCProfile::FindProfilesByColorSpace ( ICCColorSpaces spaces )

static

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.

Parameters

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 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.

◆ GetInformation()

void pcl::ICCProfile::GetInformation	(	String &	description,
		String &	manufacturer,
		String &	model,
		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 description, manufacturer, model and 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.

◆ IsDiskProfile()

bool pcl::ICCProfile::IsDiskProfile ( ) const

inline

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.

Definition at line 351 of file ICCProfile.h.

◆ IsEmbedded()

bool pcl::ICCProfile::IsEmbedded ( ) 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.

◆ IsGrayscale()

bool pcl::ICCProfile::IsGrayscale ( ) const

inline

Returns true iff this object stores a grayscale ICC profile.

Definition at line 477 of file ICCProfile.h.

◆ IsProfile()

bool pcl::ICCProfile::IsProfile ( ) const

inline

Returns true iff this object stores an ICC color profile structure.

Definition at line 333 of file ICCProfile.h.

◆ IsRGB()

bool pcl::ICCProfile::IsRGB ( ) const

inline

Returns true iff this object stores an RGB ICC profile.

Definition at line 469 of file ICCProfile.h.

◆ IsSameProfile()

bool pcl::ICCProfile::IsSameProfile ( const ICCProfile & other ) const

Returns true iff the ICC profile stored in this object is identical to the profile stored in 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).

◆ IsValid() [1/2]

static bool pcl::ICCProfile::IsValid ( const ByteArray & icc )

inlinestatic

Validates an ICC profile structure stored in the specified ByteArray container icc. Returns true iff the container stores a valid ICC profile.

Definition at line 652 of file ICCProfile.h.

References pcl::Array< T, A >::Begin().

◆ IsValid() [2/2]

static bool pcl::ICCProfile::IsValid ( const void * rawdata )

static

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.

◆ IsValidFile()

static bool pcl::ICCProfile::IsValidFile ( const String & profilePath )

static

Validates an ICC profile structure stored in a file at profilePath. Returns true iff the specified file exists and contains a valid ICC profile.

◆ IsValidHandle()

static bool pcl::ICCProfile::IsValidHandle ( handle h )

static

Validates an ICC profile handle. Returns true iff the specified handle is a valid handle to an open ICC profile.

◆ Load()

void pcl::ICCProfile::Load ( const String & profilePath )

Loads an ICC profile from a disk file at 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.

◆ Manufacturer() [1/2]

String pcl::ICCProfile::Manufacturer	(	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.

◆ Manufacturer() [2/2]

static String pcl::ICCProfile::Manufacturer	(	handle	h,
		const char *	language = `"en"`,
		const char *	country = `"US"`
	)

static

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.

◆ Model() [1/2]

String pcl::ICCProfile::Model	(	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.

◆ Model() [2/2]

static String pcl::ICCProfile::Model	(	handle	h,
		const char *	language = `"en"`,
		const char *	country = `"US"`
	)

static

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.

◆ Open() [1/4]

handle pcl::ICCProfile::Open ( ) const

inline

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.

Definition at line 577 of file ICCProfile.h.

◆ Open() [2/4]

static handle pcl::ICCProfile::Open ( const ByteArray & icc )

inlinestatic

Opens an ICC profile stored in the specified ByteArray container 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.

Definition at line 617 of file ICCProfile.h.

◆ Open() [3/4]

static handle pcl::ICCProfile::Open ( const String & profilePath )

static

Opens an ICC profile disk file at 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.

◆ Open() [4/4]

static handle pcl::ICCProfile::Open ( const void * rawData )

static

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.

◆ operator bool()

pcl::ICCProfile::operator bool ( ) const

inline

A convenience synonym for IsProfile().

Definition at line 341 of file ICCProfile.h.

◆ operator=() [1/2]

ICCProfile& pcl::ICCProfile::operator= ( const ICCProfile & )

default

Copy assignment operator. Returns a reference to this object.

◆ operator=() [2/2]

ICCProfile& pcl::ICCProfile::operator= ( ICCProfile && )

default

Move assignment operator. Returns a reference to this object.

◆ ProfileData()

const ByteArray& pcl::ICCProfile::ProfileData ( ) const

inline

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.

Definition at line 370 of file ICCProfile.h.

◆ ProfileDirectories()

static StringList pcl::ICCProfile::ProfileDirectories ( )

static

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.

◆ ProfileSize()

size_type pcl::ICCProfile::ProfileSize ( ) const

Returns the length of the stored ICC profile structure in bytes. Returns zero if this ICCProfile object doesn't store an ICC color profile.

◆ Set() [1/2]

void pcl::ICCProfile::Set ( const ByteArray & profile )

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.

◆ Set() [2/2]

void pcl::ICCProfile::Set ( const void * rawData )

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.

◆ SetEmbeddedFlag()

void pcl::ICCProfile::SetEmbeddedFlag ( bool on = true )

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.

◆ SupportsRenderingIntent() [1/2]

static bool pcl::ICCProfile::SupportsRenderingIntent	(	handle	h,
		rendering_intent	intent,
		rendering_direction	direction
	)

static

Returns true iff an open profile supports the specified intent in the specified transform direction. See the ICCRenderingIntent and ICCRenderingDirection namespaces, respectively, for supported rendering intents and directions.

◆ SupportsRenderingIntent() [2/2]

bool pcl::ICCProfile::SupportsRenderingIntent	(	rendering_intent	intent,
		rendering_direction	direction
	)		const

Returns true iff this object stores an ICC profile that supports the specified intent in the specified transform direction. See the ICCRenderingIntent and ICCRenderingDirection namespaces, respectively, for supported rendering intents and directions.

Friends And Related Function Documentation

◆ Swap

void Swap	(	ICCProfile &	x1,
		ICCProfile &	x2
	)

friend

Exchanges two ICC profiles x1 and x2.

Definition at line 585 of file ICCProfile.h.

The documentation for this class was generated from the following file:

ICCProfile.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ color_space

◆ handle

◆ profile_class

◆ profile_list

◆ rendering_direction

◆ rendering_intent

Constructor & Destructor Documentation

◆ ICCProfile() [1/6]

◆ ICCProfile() [2/6]

◆ ICCProfile() [3/6]

◆ ICCProfile() [4/6]

◆ ICCProfile() [5/6]

◆ ICCProfile() [6/6]

◆ ~ICCProfile()

Member Function Documentation

◆ Class() [1/2]

◆ Class() [2/2]

◆ Clear()

◆ ClearEmbeddedFlag()

◆ Close()

◆ ColorSpace() [1/2]

◆ ColorSpace() [2/2]

◆ Copyright() [1/2]

◆ Copyright() [2/2]

◆ Description() [1/2]

◆ Description() [2/2]

◆ ExtractProfileList()

◆ FilePath()

◆ FindInstalledProfile()

◆ FindProfiles()

◆ FindProfilesByColorSpace()

◆ GetInformation()

◆ IsDiskProfile()

◆ IsEmbedded()

◆ IsGrayscale()

◆ IsProfile()

◆ IsRGB()

◆ IsSameProfile()

◆ IsValid() [1/2]

◆ IsValid() [2/2]

◆ IsValidFile()

◆ IsValidHandle()

◆ Load()

◆ Manufacturer() [1/2]

◆ Manufacturer() [2/2]

◆ Model() [1/2]

◆ Model() [2/2]

◆ Open() [1/4]

◆ Open() [2/4]

◆ Open() [3/4]

◆ Open() [4/4]

◆ operator bool()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ ProfileData()

◆ ProfileDirectories()

◆ ProfileSize()

◆ Set() [1/2]

◆ Set() [2/2]

◆ SetEmbeddedFlag()

◆ SupportsRenderingIntent() [1/2]

◆ SupportsRenderingIntent() [2/2]

Friends And Related Function Documentation

◆ Swap