PCL
pcl::ICCProfile Class Reference

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

#include <ICCProfile.h>

Classes

class  Info
 A structure to hold descriptive data about ICC profiles.The ICCProfile::Info structure is designed to be used with the ICCProfile::FindProfilesByColorSpace() utility function. More...
 

Public Types

typedef ICCColorSpace::mask_type color_space
 
typedef void * handle
 
typedef ICCProfileClass::mask_type profile_class
 
typedef SortedArray< Infoprofile_list
 
typedef ICCRenderingDirection::value_type rendering_direction
 
typedef ICCRenderingIntent::value_type rendering_intent
 

Public Member Functions

 ICCProfile ()=default
 
 ICCProfile (const ICCProfile &)=default
 
 ICCProfile (ICCProfile &&)=default
 
 ICCProfile (const String &profilePath)
 
 ICCProfile (const ByteArray &rawData)
 
 ICCProfile (const void *rawData)
 
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
 
ICCProfileoperator= (const ICCProfile &)=default
 
ICCProfileoperator= (ICCProfile &&)=default
 
const ByteArrayProfileData () 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 void *rawdata)
 
static bool IsValid (const ByteArray &icc)
 
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 String &profilePath)
 
static handle Open (const void *rawData)
 
static handle Open (const ByteArray &icc)
 
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

typedef ICCColorSpace::mask_type pcl::ICCProfile::color_space

Represents an ICC profile color space.

Definition at line 251 of file ICCProfile.h.

◆ handle

typedef void* pcl::ICCProfile::handle

Represents an opaque handle to an internal ICC profile.

Definition at line 241 of file ICCProfile.h.

◆ profile_class

typedef ICCProfileClass::mask_type pcl::ICCProfile::profile_class

Represents an ICC profile device class.

Definition at line 246 of file ICCProfile.h.

◆ profile_list

Represents a sorted list of ICC profile information items.

Definition at line 865 of file ICCProfile.h.

◆ rendering_direction

typedef ICCRenderingDirection::value_type pcl::ICCProfile::rendering_direction

Represents an ICC transform rendering direction.

Definition at line 261 of file ICCProfile.h.

◆ rendering_intent

typedef ICCRenderingIntent::value_type pcl::ICCProfile::rendering_intent

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

Destroys an ICCProfile object. 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
languageOptional language code (ISO 639/2) of the requested profile description. The default value is "en" for English.
countryOptional 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
hHandle to an open ICC profile, from which the requested profile description will be obtained.
languageOptional language code (ISO 639/2) of the requested profile description. The default value is "en" for English.
countryOptional 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]selectedDescriptionsListThe list of profile descriptions for selected profiles.
[out]selectedPathsListThe list of paths to selected profiles.
pathListThe input list of paths to ICC profiles.
spacesA combination of ICC color spaces for selected ICC profiles.
classesA 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
descriptionDescription of the profile to search for.
exactMatchIf 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
dirPathOptional 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
spacesA 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 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.

◆ IsValid() [2/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.

◆ 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 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() [3/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.

◆ Open() [4/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.

◆ 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]

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.

◆ SupportsRenderingIntent() [2/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.

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: