ColorSpace¶

class PyOpenColorIO.ColorSpace¶

The :ref:`ColorSpace` is the state of an image with respect to colorimetry and color encoding. Transforming images between different ColorSpaces is the primary motivation for this library.

While a complete discussion of color spaces is beyond the scope of header documentation, traditional uses would be to have ColorSpaces corresponding to: physical capture devices (known cameras, scanners), and internal ‘convenience’ spaces (such as scene linear, logarithmic).

ColorSpaces are specific to a particular image precision (float32, uint8, etc.), and the set of ColorSpaces that provide equivalent mappings (at different precisions) are referred to as a ‘family’.

ColorSpace(*args, **kwargs)¶

Overloaded function.

__init__(self: PyOpenColorIO.ColorSpace) -> None
__init__(self: PyOpenColorIO.ColorSpace, referenceSpace: PyOpenColorIO.ReferenceSpaceType) -> None
__init__(self: PyOpenColorIO.ColorSpace, referenceSpace: PyOpenColorIO.ReferenceSpaceType = <ReferenceSpaceType.REFERENCE_SPACE_SCENE: 0>, name: str = ‘’, aliases: List[str] = [], family: str = ‘’, encoding: str = ‘’, equalityGroup: str = ‘’, description: str = ‘’, bitDepth: PyOpenColorIO.BitDepth = <BitDepth.BIT_DEPTH_UNKNOWN: 0>, isData: bool = False, allocation: PyOpenColorIO.Allocation = <Allocation.ALLOCATION_UNIFORM: 1>, allocationVars: List[float] = [], toReference: PyOpenColorIO.Transform = None, fromReference: PyOpenColorIO.Transform = None, categories: List[str] = []) -> None

addAlias(alias: str) → None¶: Add an alias for the color space name (the aliases may be used as a synonym for the name). Nothing will be added if the alias is already the color space name, one of its aliases, or the argument is null. The aliases must not conflict with existing roles, color space names, named transform names, or other aliases. This is verified when adding the color space to the config.

addCategory(category: str) → None¶: Add a single category.

Note

Will do nothing if the category already exists.

clearAliases() → None¶

clearCategories() → None¶: Clear all the categories.

getAliases() → PyOpenColorIO.ColorSpace.ColorSpaceAliasIterator¶

getAllocation() → PyOpenColorIO.Allocation¶

Allocation

If this colorspace needs to be transferred to a limited dynamic range coding space (such as during display with a GPU path), use this allocation to maximize bit efficiency.

getAllocationVars() → List[float]¶

getBitDepth() → PyOpenColorIO.BitDepth¶

getCategories() → PyOpenColorIO.ColorSpace.ColorSpaceCategoryIterator¶

getDescription() → str¶

getEncoding() → str¶

Encodings

It is sometimes useful for applications to group color spaces based on how the color values are digitally encoded. For example, images in scene-linear, logarithmic, video, and data color spaces could have different default views. Unlike the Family and EqualityGroup attributes of a color space, the list of Encodings is predefined in the OCIO documentation (rather than being config-specific) to make it easier for applications to utilize.

Here is an example config entry that could appear under a ColorSpace:

encoding: scene-linear

Encoding strings are not case-sensitive. Although users may add their own encodings, the strings will typically come from a fixed set listed in the documentation (similar to roles).

getEqualityGroup() → str¶: Get the ColorSpace group name (used for equality comparisons) This allows no-op transforms between different colorspaces. If an equalityGroup is not defined (an empty string), it will be considered unique (i.e., it will not compare as equal to other ColorSpaces with an empty equality group). This is often, though not always, set to the same value as ‘family’.

getFamily() → str¶: Get the family, for use in user interfaces (optional) The family string could use a ‘/’ separator to indicate levels to be used by hierarchical menus.

getName() → str¶

getReferenceSpaceType() → PyOpenColorIO.ReferenceSpaceType¶: A display color space will use the display-referred reference space.

getTransform(direction: PyOpenColorIO.ColorSpaceDirection) → PyOpenColorIO.Transform¶

:ref:`Transform`

If a transform in the specified direction has been specified, return it. Otherwise return a null ConstTransformRcPtr

hasCategory(category: str) → bool¶

Return true if the category is present.

A category is used to allow applications to filter the list of color spaces they display in menus based on what that color space is used for.

Here is an example config entry that could appear under a ColorSpace:

categories: [ file-io, working-space, basic-3d ]

The example contains three categories: ‘file-io’, ‘working-space’ and ‘basic-3d’.

Note

Category strings are not case-sensitive and the order is not significant.

There is no limit imposed on length or number. Although users may add their own categories, the strings will typically come from a fixed set listed in the documentation (similar to roles).

isData() → bool¶

Data

ColorSpaces that are data are treated a bit special. Basically, any colorspace transforms you try to apply to them are ignored. (Think of applying a gamut mapping transform to an ID pass). However, the setDataBypass method on ColorSpaceTransform and DisplayViewTransform allow applications to process data when necessary. (Think of sending mattes to an HDR monitor.)

This is traditionally used for pixel data that represents non-color pixel data, such as normals, point positions, ID information, etc.

removeAlias(alias: str) → None¶: Does nothing if alias is not present.

removeCategory(category: str) → None¶: Remove a category.

Note

Will do nothing if the category is missing.

setAllocation(allocation: PyOpenColorIO.Allocation) → None¶

setAllocationVars(vars: List[float]) → None¶

setBitDepth(bitDepth: PyOpenColorIO.BitDepth) → None¶

setDescription(description: str) → None¶

setEncoding(encoding: str) → None¶

setEqualityGroup(equalityGroup: str) → None¶

setFamily(family: str) → None¶: Set the family, for use in user interfaces (optional)

setIsData(isData: bool) → None¶

setName(name: str) → None¶: If the name is already an alias, that alias is removed.

setTransform(transform: PyOpenColorIO.Transform, direction: PyOpenColorIO.ColorSpaceDirection) → None¶: Specify the transform for the appropriate direction. Setting the transform to null will clear it.

class PyOpenColorIO.ColorSpace.ColorSpaceCategoryIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.ColorSpace.ColorSpaceCategoryIterator¶

len(self) → int¶

next(self) → str¶

class PyOpenColorIO.ColorSpace.ColorSpaceAliasIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.ColorSpace.ColorSpaceAliasIterator¶

len(self) → int¶

next(self) → str¶

class ColorSpace¶

The ColorSpace is the state of an image with respect to colorimetry and color encoding. Transforming images between different ColorSpaces is the primary motivation for this library.

Public Functions

ColorSpaceRcPtr createEditableCopy() const¶

const char *getName() const noexcept¶

void setName(const char *name) noexcept¶: If the name is already an alias, that alias is removed.

size_t getNumAliases() const noexcept¶

const char *getAlias(size_t idx) const noexcept¶: Return empty string if idx is out of range.

void addAlias(const char *alias) noexcept¶: Add an alias for the color space name (the aliases may be used as a synonym for the name). Nothing will be added if the alias is already the color space name, one of its aliases, or the argument is null. The aliases must not conflict with existing roles, color space names, named transform names, or other aliases. This is verified when adding the color space to the config.

void removeAlias(const char *alias) noexcept¶: Does nothing if alias is not present.

void clearAliases() noexcept¶

const char *getFamily() const noexcept¶: Get the family, for use in user interfaces (optional) The family string could use a ‘/’ separator to indicate levels to be used by hierarchical menus.

void setFamily(const char *family)¶: Set the family, for use in user interfaces (optional)

const char *getEqualityGroup() const noexcept¶: Get the ColorSpace group name (used for equality comparisons) This allows no-op transforms between different colorspaces. If an equalityGroup is not defined (an empty string), it will be considered unique (i.e., it will not compare as equal to other ColorSpaces with an empty equality group).

void setEqualityGroup(const char *equalityGroup)¶

const char *getDescription() const noexcept¶

void setDescription(const char *description)¶

BitDepth getBitDepth() const noexcept¶

void setBitDepth(BitDepth bitDepth)¶

ReferenceSpaceType getReferenceSpaceType() const noexcept¶: A display color space will use the display-referred reference space.

bool hasCategory(const char *category) const¶

Return true if the category is present.

A category is used to allow applications to filter the list of color spaces they display in menus based on what that color space is used for.

Here is an example config entry that could appear under a ColorSpace:

categories: [ file-io, working-space, basic-3d ]

The example contains three categories: ‘file-io’, ‘working-space’ and ‘basic-3d’.

There is no limit imposed on length or number. Although users may add their own categories, the strings will typically come from a fixed set listed in the documentation (similar to roles).

Note

Category strings are not case-sensitive and the order is not significant.

void addCategory(const char *category)¶: Add a single category.

Note

Will do nothing if the category already exists.

void removeCategory(const char *category)¶: Remove a category.

Note

Will do nothing if the category is missing.

int getNumCategories() const¶: Get the number of categories.

const char *getCategory(int index) const¶: Return the category name using its index.

Note

Will be null if the index is invalid.

void clearCategories()¶: Clear all the categories.

const char *getEncoding() const noexcept¶

Encodings

Here is an example config entry that could appear under a ColorSpace:

encoding: scene-linear

Encoding strings are not case-sensitive. Although users may add their own encodings, the strings will typically come from a fixed set listed in the documentation (similar to roles).

void setEncoding(const char *encoding)¶

bool isData() const noexcept¶

Data

This is traditionally used for pixel data that represents non-color pixel data, such as normals, point positions, ID information, etc.

void setIsData(bool isData) noexcept¶

Allocation getAllocation() const noexcept¶

Allocation

If this colorspace needs to be transferred to a limited dynamic range coding space (such as during display with a GPU path), use this allocation to maximize bit efficiency.

void setAllocation(Allocation allocation) noexcept¶

int getAllocationNumVars() const¶

Specify the optional variable values to configure the allocation. If no variables are specified, the defaults are used.

ALLOCATION_UNIFORM::

2 vars: [min, max]

ALLOCATION_LG2::

2 vars: [lg2min, lg2max] 3 vars: [lg2min, lg2max, linear_offset]

void getAllocationVars(float *vars) const¶

void setAllocationVars(int numvars, const float *vars)¶

ConstTransformRcPtr getTransform(ColorSpaceDirection dir) const noexcept¶

Transform

If a transform in the specified direction has been specified, return it. Otherwise return a null ConstTransformRcPtr

void setTransform(const ConstTransformRcPtr &transform, ColorSpaceDirection dir)¶: Specify the transform for the appropriate direction. Setting the transform to null will clear it.

ColorSpace(const ColorSpace&) = delete¶

ColorSpace &operator=(const ColorSpace&) = delete¶

~ColorSpace()¶: Do not use (needed only for pybind11).

Public Static Functions

static ColorSpaceRcPtr Create()¶

static ColorSpaceRcPtr Create(ReferenceSpaceType referenceSpace)¶

std::ostream &OpenColorIO_v2_2dev::operator<<(std::ostream&, const ColorSpace&)¶

typedef std::shared_ptr<const ColorSpace> OpenColorIO_v2_2dev::ConstColorSpaceRcPtr¶

typedef std::shared_ptr<ColorSpace> OpenColorIO_v2_2dev::ColorSpaceRcPtr¶

ColorSpaceSet¶

class PyOpenColorIO.ColorSpaceSet¶

The :ref:`ColorSpaceSet` is a set of color spaces (i.e. no color space duplication) which could be the result of Config::getColorSpaces or built from scratch.

Note

The color spaces are decoupled from the config ones, i.e., any changes to the set itself or to its color spaces do not affect the original color spaces from the configuration. If needed, use Config::addColorSpace to update the configuration.

self & arg0: PyOpenColorIO.ColorSpaceSet → PyOpenColorIO.ColorSpaceSet¶

Perform the intersection of two sets.

Note

This function provides operations on two color space sets where the result contains copied color spaces and no duplicates.

Parameters:

lcss –
rcss –

self == arg0: PyOpenColorIO.ColorSpaceSet → bool¶: Return true if the two sets are equal.

Note

The comparison is done on the color space names (not a deep comparison).

ColorSpaceSet() → None¶: Create an empty set of color spaces.

self != arg0: PyOpenColorIO.ColorSpaceSet → bool¶: Return true if the two sets are different.

self | arg0: PyOpenColorIO.ColorSpaceSet → PyOpenColorIO.ColorSpaceSet¶

Perform the union of two sets.

Note

This function provides operations on two color space sets where the result contains copied color spaces and no duplicates.

Parameters:

lcss –
rcss –

self - arg0: PyOpenColorIO.ColorSpaceSet → PyOpenColorIO.ColorSpaceSet¶

Perform the difference of two sets.

Note

This function provides operations on two color space sets where the result contains copied color spaces and no duplicates.

Parameters:

lcss –
rcss –

addColorSpace(colorSpace: PyOpenColorIO.ColorSpace) → None¶: Add color space(s).

Note

If another color space is already registered with the same name, this will overwrite it. This stores a copy of the specified color space(s). Throws if one of the aliases is already assigned as a name or alias to an existing color space.

addColorSpaces(colorSpaces: PyOpenColorIO.ColorSpaceSet) → None¶

clearColorSpaces() → None¶: Clear all color spaces.

getColorSpace(name: str) → PyOpenColorIO.ColorSpace¶: Note

Only accepts color space names (i.e. no role name).

Will return null if the name is not found.

getColorSpaceNames() → PyOpenColorIO.ColorSpaceSet.ColorSpaceNameIterator¶

getColorSpaces() → PyOpenColorIO.ColorSpaceSet.ColorSpaceIterator¶

removeColorSpace(colorSpace: str) → None¶: Remove color space(s) using color space names (i.e. no role name).

Note

The removal of a missing color space does nothing.

removeColorSpaces(colorSpaces: PyOpenColorIO.ColorSpaceSet) → None¶

class PyOpenColorIO.ColorSpaceSet.ColorSpaceNameIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.ColorSpaceSet.ColorSpaceNameIterator¶

len(self) → int¶

next(self) → str¶

class PyOpenColorIO.ColorSpaceSet.ColorSpaceIterator¶

self[arg0: int] → PyOpenColorIO.ColorSpace¶

iter(self) → PyOpenColorIO.ColorSpaceSet.ColorSpaceIterator¶

len(self) → int¶

next(self) → PyOpenColorIO.ColorSpace¶

class ColorSpaceSet¶

The ColorSpaceSet is a set of color spaces (i.e. no color space duplication) which could be the result of Config::getColorSpaces or built from scratch.

Note

Public Functions

ColorSpaceSetRcPtr createEditableCopy() const¶: Create a set containing a copy of all the color spaces.

bool operator==(const ColorSpaceSet &css) const¶: Return true if the two sets are equal.

Note

The comparison is done on the color space names (not a deep comparison).

bool operator!=(const ColorSpaceSet &css) const¶: Return true if the two sets are different.

int getNumColorSpaces() const¶: Return the number of color spaces.

const char *getColorSpaceNameByIndex(int index) const¶: Return the color space name using its index. This will be null if an invalid index is specified.

ConstColorSpaceRcPtr getColorSpaceByIndex(int index) const¶: Return the color space using its index. This will be empty if an invalid index is specified.

ConstColorSpaceRcPtr getColorSpace(const char *name) const¶: Will return null if the name is not found.

Note

Only accepts color space names (i.e. no role name).

int getColorSpaceIndex(const char *name) const¶: Will return -1 if the name is not found.

Note

Only accepts color space names (i.e. no role name).

bool hasColorSpace(const char *name) const¶

Note

Only accepts color space names (i.e. no role name)

Parameters:: name –
Returns:: true
Returns:: false

void addColorSpace(const ConstColorSpaceRcPtr &cs)¶: Add color space(s).

Note

If another color space is already registered with the same name, this will overwrite it. This stores a copy of the specified color space(s). Throws if one of the aliases is already assigned as a name or alias to an existing color space.

void addColorSpaces(const ConstColorSpaceSetRcPtr &cs)¶

void removeColorSpace(const char *name)¶: Remove color space(s) using color space names (i.e. no role name).

Note

The removal of a missing color space does nothing.

void removeColorSpaces(const ConstColorSpaceSetRcPtr &cs)¶

void clearColorSpaces()¶: Clear all color spaces.

~ColorSpaceSet()¶: Do not use (needed only for pybind11).

Public Static Functions

static ColorSpaceSetRcPtr Create()¶: Create an empty set of color spaces.

ConstColorSpaceSetRcPtr operator||(const ConstColorSpaceSetRcPtr &lcss, const ConstColorSpaceSetRcPtr &rcss)¶

Perform the union of two sets.

Note

This function provides operations on two color space sets where the result contains copied color spaces and no duplicates.

Parameters:

lcss –
rcss –

ConstColorSpaceSetRcPtr operator&&(const ConstColorSpaceSetRcPtr &lcss, const ConstColorSpaceSetRcPtr &rcss)¶

Perform the intersection of two sets.

Note

This function provides operations on two color space sets where the result contains copied color spaces and no duplicates.

Parameters:

lcss –
rcss –

ConstColorSpaceSetRcPtr operator-(const ConstColorSpaceSetRcPtr &lcss, const ConstColorSpaceSetRcPtr &rcss)¶

Perform the difference of two sets.

Note

This function provides operations on two color space sets where the result contains copied color spaces and no duplicates.

Parameters:

lcss –
rcss –

typedef std::shared_ptr<const ColorSpaceSet> OpenColorIO_v2_2dev::ConstColorSpaceSetRcPtr¶

typedef std::shared_ptr<ColorSpaceSet> OpenColorIO_v2_2dev::ColorSpaceSetRcPtr¶