Config¶

class PyOpenColorIO.Config¶

A config defines all the color spaces to be available at runtime.

The color configuration (Config) is the main object for interacting with this library. It encapsulates all of the information necessary to use customized ColorSpaceTransform and DisplayViewTransform operations.

See the user-guide for more information on selecting, creating, and working with custom color configurations.

For applications interested in using only one color config at a time (this is the vast majority of apps), their API would traditionally get the global configuration and use that, as opposed to creating a new one. This simplifies the use case for plugins and bindings, as it alleviates the need to pass around configuration handles.

An example of an application where this would not be sufficient would be a multi-threaded image proxy server (daemon), which wished to handle multiple show configurations in a single process concurrently. This app would need to keep multiple configurations alive, and to manage them appropriately.

Roughly speaking, a novice user should select a default configuration that most closely approximates the use case (animation, visual effects, etc.), and set the OCIO environment variable to point at the root of that configuration.

Note

Initialization using environment variables is typically preferable in a multi-app ecosystem, as it allows all applications to be consistently configured.

See developers-usageexamples

static CreateFromBuiltinConfig(arg0: str) → PyOpenColorIO.Config¶

Create a configuration using an OCIO built-in config.

Parameters:: configName – Built-in config name.

The available configNames are: “cg-config-v0.1.0_aces-v1.3_ocio-v2.1.1”– ACES CG config, basic color spaces for computer graphics apps. More information about these configs is available at: https://github.com/AcademySoftwareFoundation/OpenColorIO-Config-ACES

Information about the available configs is available from the BuiltinConfigRegistry.

:exception Exception: If the configName is not recognized.

Returns:: One of the configs built into the OCIO library.

static CreateFromConfigIOProxy(arg0: OpenColorIO_v2_2dev::ConfigIOProxy) → PyOpenColorIO.Config¶

Create a config from the supplied ConfigIOProxy object. This allows the calling program to directly provide the config and associated LUTs rather than reading them from the standard file system.

See the ConfigIOProxy class documentation for more info.

Parameters:: ciop – ConfigIOProxy object providing access to the config’s files.

:exception Exception: If the config may not be read from the proxy, or does not parse.

Returns:: The Config object.

static CreateFromEnv() → PyOpenColorIO.Config¶

Create a configuration using the OCIO environment variable.

Also supports the OCIO URI format for Built-in configs and supports archived configs. See Config::CreateFromFile.

If the variable is missing or empty, returns the same result as Config::CreateRaw. :return: The Config object.

static CreateFromFile(fileName: str) → PyOpenColorIO.Config¶

Create a configuration using a specific config file.

Also supports the following OCIO URI format for Built-in configs: “ocio://default” - Default Built-in config. “ocio://<CONFIG NAME>” - A specific Built-in config. For the list of available <CONFIG NAME> strings, see Config::CreateFromBuiltinConfig.

Also supports archived configs (.ocioz files).

:exception Exception: If the file may not be read or does not parse.

Returns:: The Config object.

static CreateFromStream(str: str) → PyOpenColorIO.Config¶

Create a configuration using a stream.

Note that CreateFromStream does not set the working directory so the caller would need to set that separately in order to resolve FileTransforms. This function is typically only used for self-contained configs (no LUTs).

Configs created from CreateFromStream can not be archived unless the working directory is set and contains any necessary LUT files.

Parameters:: istream – Stream to the config.

:exception Exception: If the stream does not parse.

Returns:: The Config object.

static CreateRaw() → PyOpenColorIO.Config¶

Create a fall-back config.

This may be useful to allow client apps to launch in cases when the supplied config path is not loadable. :return: The Config object.

class DisplayAllIterator¶

DisplayAllIterator(*args, **kwargs)¶

static GetProcessorFromConfigs(*args, **kwargs)¶

Overloaded function.

GetProcessorFromConfigs(srcConfig: PyOpenColorIO.Config, srcColorSpaceName: str, dstConfig: PyOpenColorIO.Config, dstColorSpaceName: str) -> PyOpenColorIO.Processor

Get a processor to convert between color spaces in two separate configs.

This relies on both configs having the aces_interchange role (when srcName is scene-referred) or the role cie_xyz_d65_interchange (when srcName is display-referred) defined. An exception is thrown if that is not the case.

GetProcessorFromConfigs(srcContext: PyOpenColorIO.Context, srcConfig: PyOpenColorIO.Config, srcColorSpaceName: str, dstContext: PyOpenColorIO.Context, dstConfig: PyOpenColorIO.Config, dstColorSpaceName: str) -> PyOpenColorIO.Processor
GetProcessorFromConfigs(srcConfig: PyOpenColorIO.Config, srcColorSpaceName: str, srcInterchangeName: str, dstConfig: PyOpenColorIO.Config, dstColorSpaceName: str, dstInterchangeName: str) -> PyOpenColorIO.Processor

The srcInterchangeName and dstInterchangeName must refer to a pair of color spaces in the two configs that are the same. A role name may also be used.

GetProcessorFromConfigs(srcContext: PyOpenColorIO.Context, srcConfig: PyOpenColorIO.Config, srcColorSpaceName: str, srcInterchangeName: str, dstContext: PyOpenColorIO.Context, dstConfig: PyOpenColorIO.Config, dstColorSpaceName: str, dstInterchangeName: str) -> PyOpenColorIO.Processor

class ViewForViewTypeIterator¶

ViewForViewTypeIterator(*args, **kwargs)¶

class VirtualViewIterator¶

VirtualViewIterator(*args, **kwargs)¶

VirtualViewIterator() → None¶

Create an empty config of the current version.

Note that an empty config will not pass validation since required elements will be missing. :return: The Config object.

str(self) → str¶

addColorSpace(colorSpace: PyOpenColorIO.ColorSpace) → None¶: Add a color space to the configuration.

Note

If another color space is already present with the same name, this will overwrite it. This stores a copy of the specified color space.

Note

Adding a color space to a Config does not affect any ColorSpaceSet sets that have already been created.

addDisplaySharedView(display: str, view: str) → None¶

Add a (reference to a) shared view to a display.

The shared view must be part of the config. See Config::addSharedView

This will throw if: - Display or view are null or empty. - Display already has a view (shared or not) with the same name.

addDisplayView(*args, **kwargs)¶

Overloaded function.

addDisplayView(self: PyOpenColorIO.Config, display: str, view: str, colorSpaceName: str, looks: str = ‘’) -> None

For the (display, view) pair, specify which color space and look to use. If a look is not desired, then just pass a null or empty string.

addDisplayView(self: PyOpenColorIO.Config, display: str, view: str, viewTransform: str, displayColorSpaceName: str, looks: str = ‘’, ruleName: str = ‘’, description: str = ‘’) -> None

For the (display, view) pair, specify which color space and look to use. If a look is not desired, then just pass a null or empty string.

addEnvironmentVar(name: str, defaultValue: str) → None¶: Add (or update) an environment variable with a default value. But it removes it if the default value is null.

addLook(look: PyOpenColorIO.Look) → None¶

addNamedTransform(namedTransform: PyOpenColorIO.NamedTransform) → None¶

addSearchPath(path: str) → None¶

Add a single search path to the end of the list.

Paths may be either absolute or relative. Relative paths are relative to the working directory. Forward slashes will be normalized to reverse for Windows. Environment (context) variables may be used in paths.

addSharedView(view: str, viewTransformName: str, colorSpaceName: str, looks: str = '', ruleName: str = '', description: str = '') → None¶

Will throw if view or colorSpaceName are null or empty.

The following methods only manipulate active displays and views. Active displays and views are defined from an env. variable or from the config file.

Looks is a potentially comma (or colon) delimited list of lookNames, Where +/- prefixes are optionally allowed to denote forward/inverse look specification. (And forward is assumed in the absence of either)

Add shared view (or replace existing one with same name). Shared views are defined at config level and can be referenced by several displays. Either provide a view transform and a display color space or just a color space (and a null view transform). Looks, rule and description are optional, they can be null or empty.

Shared views using a view transform may use the token <USE_DISPLAY_NAME> for the color space (see OCIO_VIEW_USE_DISPLAY_NAME). In that case, when the view is referenced in a display, the display color space that is used will be the one matching the display name. In other words, the view will be customized based on the display it is used in. Config::validate will throw if the config does not contain the matching display color space.

addViewTransform(viewTransform: PyOpenColorIO.ViewTransform) → None¶

addVirtualDisplaySharedView(sharedView: str) → None¶

addVirtualDisplayView(view: str, viewTransformName: str, colorSpaceName: str, looks: str = '', ruleName: str = '', description: str = '') → None¶

archive(arg0: str) → None¶

Archive the config and its LUTs into the specified output stream.

The config is archived by serializing the Config object into a file named “config.ocio” and then walking through the current working directory and any sub-directories. Any files that have an extension matching a supported LUT file format are added to the archive. Any files that do not have an extension (or have some unsupported LUT extension, including .ocio), will not be added to the archive. To reiterate, it is the in-memory Config object that is archived, and not any .ocio file in the current working directory. The directory structure relative to the working directory is preserved. No files outside the working directory are archived so that if it is later expanded, no files will be created outside the working dir.

The reason the archive is created using all supported LUT file extensions rather than by trying to resolve all the FileTransforms in the Config to specific files is because of the goal to allow context variables to continue to work.

If a Config is created with CreateFromStream, CreateFromFile with an OCIOZ archive, or CreateFromConfigIOProxy, it cannot be archived unless the working directory is manually set to a directory that contains any necessary LUT files.

The provided output stream must be closed by the caller, if necessary (e.g., an ofstream).

Parameters:: ostream – The output stream to write to.

clearColorSpaces() → None¶: Remove all the color spaces from the configuration.

Note

Removing color spaces from a Config does not affect any ColorSpaceSet sets that have already been created.

clearDisplays() → None¶: Clear all the displays.

clearEnvironmentVars() → None¶

clearLooks() → None¶

clearNamedTransforms() → None¶

clearSearchPaths() → None¶

clearViewTransforms() → None¶

clearVirtualDisplay() → None¶: Clear the virtual display.

filepathOnlyMatchesDefaultRule(filePath: str) → bool¶: Returns true if the only rule matched by filePath is the default rule. This is a convenience method for applications that want to require the user to manually choose a color space when strictParsing is true and no other rules match.

getActiveDisplays() → str¶

getActiveViews() → str¶

getCacheID(*args, **kwargs)¶

Overloaded function.

getCacheID(self: PyOpenColorIO.Config) -> str

This will produce a hash of the all colorspace definitions, etc. All external references, such as files used in FileTransforms, etc., will be incorporated into the cacheID. While the contents of the files are not read, the file system is queried for relevant information (mtime, inode) so that the config’s cacheID will change when the underlying luts are updated.

If a context is not provided, the current Context will be used.

If a null context is provided, file references will not be taken into account (this is essentially a hash of Config::serialize).

getCacheID(self: PyOpenColorIO.Config, context: PyOpenColorIO.Context) -> str

If a context is not provided, the current Context will be used.

If a null context is provided, file references will not be taken into account (this is essentially a hash of Config::serialize).

getCanonicalName(name: str) → str¶: Accepts an alias, role name, named transform name, or color space name and returns the color space name or the named transform name.

getColorSpace(name: str) → PyOpenColorIO.ColorSpace¶: Get the color space from all the color spaces (i.e. active and inactive) and return null if the name is not found.

Note

The fcn accepts either a color space name, role name, or alias. (Color space names take precedence over roles.)

getColorSpaceFromFilepath(filePath: str) → tuple¶: Get the color space of the first rule that matched filePath. (For v1 configs, this is equivalent to calling parseColorSpaceFromString with strictparsing set to false.)

getColorSpaceNames(*args, **kwargs)¶

Overloaded function.

getColorSpaceNames(self: PyOpenColorIO.Config, searchReferenceType: PyOpenColorIO.SearchReferenceSpaceType, visibility: PyOpenColorIO.ColorSpaceVisibility) -> PyOpenColorIO.Config.ColorSpaceNameIterator
getColorSpaceNames(self: PyOpenColorIO.Config) -> PyOpenColorIO.Config.ActiveColorSpaceNameIterator

getColorSpaces(*args, **kwargs)¶

Overloaded function.

getColorSpaces(self: PyOpenColorIO.Config, category: str) -> PyOpenColorIO.ColorSpaceSet

Get all active color spaces having a specific category in the order they appear in the config file.

Note

If the category is null or empty, the method returns all the active color spaces like Config::getNumColorSpaces and Config::getColorSpaceNameByIndex do.

Note

It’s worth noticing that the method returns a copy of the selected color spaces decoupling the result from the config. Hence, any changes on the config do not affect the existing color space sets, and vice-versa.

getColorSpaces(self: PyOpenColorIO.Config, searchReferenceType: PyOpenColorIO.SearchReferenceSpaceType, visibility: PyOpenColorIO.ColorSpaceVisibility) -> PyOpenColorIO.Config.ColorSpaceIterator
getColorSpaces(self: PyOpenColorIO.Config) -> PyOpenColorIO.Config.ActiveColorSpaceIterator

getCurrentContext() → PyOpenColorIO.Context¶

getDefaultDisplay() → str¶

getDefaultLumaCoefs() → List[float[3]]¶: Get the default coefficients for computing luma.

Note

There is no “1 size fits all” set of luma coefficients. (The values are typically different for each colorspace, and the application of them may be nonsensical depending on the intensity coding anyways). Thus, the ‘right’ answer is to make these functions on the ColorSpace class. However, it’s often useful to have a config-wide default so here it is. We will add the colorspace specific luma call if/when another client is interesting in using it.

getDefaultSceneToDisplayViewTransform() → PyOpenColorIO.ViewTransform¶: This view transform is the one that will be used by default if a ColorSpaceTransform is needed between a scene-referred and display-referred color space. The config author may specify a transform to use via the default_view_transform entry in the config. If that is not present, or does not return a valid view transform from the scene-referred connection space, the fall-back is to use the first valid view transform in the config. Returns a null ConstTransformRcPtr if there isn’t one.

getDefaultView(*args, **kwargs)¶

Overloaded function.

getDefaultView(self: PyOpenColorIO.Config, display: str) -> str
getDefaultView(self: PyOpenColorIO.Config, display: str, colorSpacename: str) -> str

getDefaultViewTransformName() → str¶

Get or set the default_view_transform string from the config.

Note that if this is not the name of a valid view transform from the scene-referred connection space, it will be ignored.

getDescription() → str¶

getDisplayViewColorSpaceName(display: str, view: str) → str¶: Returns the colorspace attribute of the (display, view) pair. (Note that this may be either a color space or a display color space.)

getDisplayViewDescription(display: str, view: str) → str¶: Returns the description attribute of a (display, view) pair.

getDisplayViewLooks(display: str, view: str) → str¶: Returns the looks attribute of a (display, view) pair.

getDisplayViewRule(display: str, view: str) → str¶: Returns the rule attribute of a (display, view) pair.

getDisplayViewTransformName(display: str, view: str) → str¶: Returns the view_transform attribute of the (display, view) pair. View can be a shared view of the display. If display is null or empty, config shared views are used.

getDisplays() → PyOpenColorIO.Config.DisplayIterator¶

getDisplaysAll() → PyOpenColorIO.Config.DisplayAllIterator¶

getEnvironmentMode() → PyOpenColorIO.EnvironmentMode¶

getEnvironmentVarDefault(name: str) → str¶

getEnvironmentVarNames() → PyOpenColorIO.Config.EnvironmentVarNameIterator¶

getFamilySeparator() → str¶

Get the family separator.

A single character used to separate the family string into tokens for use in hierarchical menus. Defaults to ‘/’.

getFileRules() → PyOpenColorIO.FileRules¶: Get read-only version of the file rules.

getInactiveColorSpaces() → str¶

getLook(name: str) → PyOpenColorIO.Look¶

getLookNames() → PyOpenColorIO.Config.LookNameIterator¶

getLooks() → PyOpenColorIO.Config.LookIterator¶

getMajorVersion() → int¶: Get the configuration major version.

getMinorVersion() → int¶: Get the configuration minor version.

getName() → str¶

Get/set a name string for the config.

The name string may be used to communicate config update details or similar information to workflows external to OCIO in cases where the config path/filename itself does not provide adequate information.

getNamedTransform(name: str) → PyOpenColorIO.NamedTransform¶

getNamedTransformNames(*args, **kwargs)¶

Overloaded function.

getNamedTransformNames(self: PyOpenColorIO.Config, visibility: PyOpenColorIO.NamedTransformVisibility) -> PyOpenColorIO.Config.NamedTransformNameIterator
getNamedTransformNames(self: PyOpenColorIO.Config) -> PyOpenColorIO.Config.ActiveNamedTransformNameIterator

getNamedTransforms(*args, **kwargs)¶

Overloaded function.

getNamedTransforms(self: PyOpenColorIO.Config, visibility: PyOpenColorIO.NamedTransformVisibility) -> PyOpenColorIO.Config.NamedTransformIterator
getNamedTransforms(self: PyOpenColorIO.Config) -> PyOpenColorIO.Config.ActiveNamedTransformIterator

getProcessor(*args, **kwargs)¶

Overloaded function.

getProcessor(self: PyOpenColorIO.Config, srcColorSpace: PyOpenColorIO.ColorSpace, dstColorSpace: PyOpenColorIO.ColorSpace) -> PyOpenColorIO.Processor

Get the processor to apply a ColorSpaceTransform from a source to a destination color space.

getProcessor(self: PyOpenColorIO.Config, context: PyOpenColorIO.Context, srcColorSpace: PyOpenColorIO.ColorSpace, dstColorSpace: PyOpenColorIO.ColorSpace) -> PyOpenColorIO.Processor
getProcessor(self: PyOpenColorIO.Config, srcColorSpaceName: str, dstColorSpaceName: str) -> PyOpenColorIO.Processor

Note

Names can be colorspace name, role name, or a combination of both.

getProcessor(self: PyOpenColorIO.Config, context: PyOpenColorIO.Context, srcColorSpaceName: str, dstColorSpaceName: str) -> PyOpenColorIO.Processor
getProcessor(self: PyOpenColorIO.Config, srcColorSpaceName: str, display: str, view: str, direction: PyOpenColorIO.TransformDirection) -> PyOpenColorIO.Processor

Get the processor to apply a DisplayViewTransform for a display and view. Refer to the Display/View Registration section above for more info on the display and view arguments.

getProcessor(self: PyOpenColorIO.Config, context: PyOpenColorIO.Context, srcColorSpaceName: str, display: str, view: str, direction: PyOpenColorIO.TransformDirection) -> PyOpenColorIO.Processor
getProcessor(self: PyOpenColorIO.Config, namedTransform: PyOpenColorIO.NamedTransform, direction: PyOpenColorIO.TransformDirection) -> PyOpenColorIO.Processor

Get the processor to apply a NamedTransform in the specified direction.

getProcessor(self: PyOpenColorIO.Config, context: PyOpenColorIO.Context, namedTransform: PyOpenColorIO.NamedTransform, direction: PyOpenColorIO.TransformDirection) -> PyOpenColorIO.Processor
getProcessor(self: PyOpenColorIO.Config, namedTransformName: str, direction: PyOpenColorIO.TransformDirection) -> PyOpenColorIO.Processor
getProcessor(self: PyOpenColorIO.Config, context: PyOpenColorIO.Context, namedTransformName: str, direction: PyOpenColorIO.TransformDirection) -> PyOpenColorIO.Processor
getProcessor(self: PyOpenColorIO.Config, transform: PyOpenColorIO.Transform) -> PyOpenColorIO.Processor

Get the processor for the specified transform.

Not often needed, but will allow for the re-use of atomic OCIO functionality (such as to apply an individual LUT file).

getProcessor(self: PyOpenColorIO.Config, transform: PyOpenColorIO.Transform, direction: PyOpenColorIO.TransformDirection) -> PyOpenColorIO.Processor
getProcessor(self: PyOpenColorIO.Config, context: PyOpenColorIO.Context, transform: PyOpenColorIO.Transform, direction: PyOpenColorIO.TransformDirection) -> PyOpenColorIO.Processor

getRoleNames() → PyOpenColorIO.Config.RoleNameIterator¶

getRoles() → PyOpenColorIO.Config.RoleColorSpaceIterator¶

getSearchPath() → str¶

getSearchPaths() → PyOpenColorIO.Config.SearchPathIterator¶

getSharedViews() → PyOpenColorIO.Config.SharedViewIterator¶

getViewTransform(name: str) → PyOpenColorIO.ViewTransform¶

getViewTransformNames() → PyOpenColorIO.Config.ViewTransformNameIterator¶

getViewTransforms() → PyOpenColorIO.Config.ViewTransformIterator¶

getViewingRules() → PyOpenColorIO.ViewingRules¶: Get read-only version of the viewing rules.

getViews(*args, **kwargs)¶

Overloaded function.

getViews(self: PyOpenColorIO.Config, display: str) -> PyOpenColorIO.Config.ViewIterator
getViews(self: PyOpenColorIO.Config, type: PyOpenColorIO.ViewType, display: str) -> PyOpenColorIO.Config.ViewForViewTypeIterator
getViews(self: PyOpenColorIO.Config, display: str, colorSpaceName: str) -> PyOpenColorIO.Config.ViewForColorSpaceIterator

getVirtualDisplayViewColorSpaceName(view: str) → str¶

getVirtualDisplayViewDescription(view: str) → str¶

getVirtualDisplayViewLooks(view: str) → str¶

getVirtualDisplayViewRule(view: str) → str¶

getVirtualDisplayViewTransformName(view: str) → str¶

getVirtualDisplayViews(display: PyOpenColorIO.ViewType) → PyOpenColorIO.Config.VirtualViewIterator¶

getWorkingDir() → str¶

hasRole(role: str) → bool¶: Return true if the role has been defined.

instantiateDisplayFromICCProfile(ICCProfileFilepath: str) → int¶

Instantiate a new display from a virtual display, using an ICC profile.

On platforms such as Linux, where the SystemMonitors class is not able to obtain a list of ICC profiles from the OS, this method may be used to manually specify a path to an ICC profile.

Will throw if the virtual display definition is missing from the config.

Returns the index of the display.

instantiateDisplayFromMonitorName(monitorName: str) → int¶

Instantiate a new display from a virtual display, using the monitor name.

This method uses the virtual display to create an actual display for the given monitorName. The new display will receive the views from the virtual display.

After the ICC profile is read, a display name will be created by combining the description text from the profile with the monitorName obtained from the OS. Use the SystemMonitors class to obtain the list of monitorName strings for the displays connected to the computer.

A new display color space will also be created using the display name. It will have a from_display_reference transform that is a FileTransform pointing to the ICC profile.

Any instantiated display color spaces for a virtual display are intended to be temporary (i.e. last as long as the current session). By default, they are not saved when writing a config file. If there is a need to make it a permanent color space, it may be desirable to copy the ICC profile somewhere under the config search_path.

Will throw if the config does not have a virtual display or if the monitorName does not exist.

If there is already a display or a display color space with the name monitorName, it will be replaced/updated.

Returns the index of the display.

isArchivable() → bool¶

Verify if the config is archivable.

A config is not archivable if any of the following are true: – The working directory is not set – It contains FileTransforms with a src outside the working directory – The search path contains paths outside the working directory – The search path contains paths that start with a context variable

Context variables are allowed but the intent is that they may only resolve to paths that are within or below the working directory. This is because the archiving function will only archive files that are within the working directory in order to ensure that if it is later expanded, that it will not create any files outside this directory.

For example, a context variable on the search path intended to contain the name of a sub-directory under the working directory must have the form “./$DIR_NAME” rather than just “$DIR_NAME” to be considered archivable. This is imperfect since there is no way to prevent the context variable from creating a path outside the working dir, but it should at least draw attention to the fact that the archive would fail if used with context vars that try to abuse the intended functionality.

Returns:: bool Archivable if true.

isColorSpaceLinear(colorSpace: str, referenceSpaceType: PyOpenColorIO.ReferenceSpaceType) → bool¶

Return true if the specified color space is linear.

The determination of linearity is made with respect to one of the two reference spaces (i.e., either the scene-referred one or the display-referred one). If the reference space type of the color space is the opposite of the requested reference space type, false is returned immediately rather than trying to invoke the default view transform to convert between the reference spaces.

Note: This function relies on heuristics that may sometimes give an incorrect result. For example, if the encoding attribute is not set appropriately or the sampled values fail to detect non-linearity.

The algorithm proceeds as follows: – If the color space isdata attribute is true, return false. – If the reference space type of the color space differs from the requested reference space type, return false. – If the color space’s encoding attribute is present, return true if it matches the expected reference space type (i.e., “scene-linear” for REFERENCE_SPACE_SCENE or “display-linear” for REFERENCE_SPACE_DISPLAY) and false otherwise. – If the color space has no to_reference or from_reference transform, return true. – Evaluate several points through the color space’s transform and check if the output only differs by a scale factor (which may be different per channel, e.g. allowing an arbitrary matrix transform, with no offset).

Note that the encoding test happens before the sampled value test to give config authors ultimate control over the linearity determination. For example, they could set the encoding attribute to indicate linearity if they want to ignore some areas of non-linearity (e.g., at extreme values). Or they could set it to indicate that a color space should not be considered linear, even if it is, in a mathematical sense.

Parameters:

colorSpace – Color space to evaluate.
referenceSpaceType – Evaluate linearity with respect to the specified reference space (either scene-referred or display-referred).

isColorSpaceUsed(name: str) → bool¶: Return true if the color space is used by a transform, a role, or a look.

Note

Name must be the canonical name.

isDisplayTemporary(display: str) → bool¶

isStrictParsingEnabled() → bool¶

loadEnvironment() → None¶

parseColorSpaceFromString(str: str) → str¶

Given the specified string, get the longest, right-most, colorspace substring that appears.

If strict parsing is enabled, and no color space is found, return an empty string.
If strict parsing is disabled, return ROLE_DEFAULT (if defined).
If the default role is not defined, return an empty string.

removeColorSpace(name: str) → None¶: Remove a color space from the configuration.

Note

It does not throw an exception. Name must be the canonical name. If a role name or alias is provided or if the name is not in the config, nothing is done.

Note

Removing a color space from a Config does not affect any ColorSpaceSet sets that have already been created.

removeDisplayView(display: str, view: str) → None¶

Remove the view and the display if no more views.

It does not remove the associated color space. If the view name is a shared view, it only removes the reference to the view from the display but the shared view, remains in the config.

Will throw if the view does not exist.

removeSharedView(view: str) → None¶: Remove a shared view. Will throw if the view does not exist.

removeVirtualDisplayView(view: str) → None¶: Remove the view from the virtual display.

serialize(*args, **kwargs)¶

Overloaded function.

serialize(self: PyOpenColorIO.Config, fileName: str) -> None
serialize(self: PyOpenColorIO.Config) -> str

Returns the string representation of the Config in YAML text form.

This is typically stored on disk in a file with the extension .ocio. NB: This does not validate the config. Applications should validate before serializing.

setActiveDisplays(displays: str) → None¶

$OCIO_ACTIVE_DISPLAYS envvar can, at runtime, optionally override the allowed displays. It is a comma or colon delimited list. Active displays that are not in the specified profile will be ignored, and the left-most defined display will be the default.

Comma-delimited list of names to filter and order the active displays.

Note

The setter does not override the envvar. The getter does not take into account the envvar value and thus may not represent what the user is seeing.

setActiveViews(views: str) → None¶

$OCIO_ACTIVE_VIEWS envvar can, at runtime, optionally override the allowed views. It is a comma or colon delimited list. Active views that are not in the specified profile will be ignored, and the left-most defined view will be the default.

Comma-delimited list of names to filter and order the active views.

Note

The setter does not override the envvar. The getter does not take into account the envvar value and thus may not represent what the user is seeing.

setDefaultLumaCoefs(rgb: List[float[3]]) → None¶: These should be normalized (sum to 1.0 exactly).

setDefaultViewTransformName(name: str) → None¶

setDescription(description: str) → None¶

setEnvironmentMode(mode: PyOpenColorIO.EnvironmentMode) → None¶

setFamilySeparator(separator: str) → None¶

Set the family separator.

Succeeds if the characters is null or a valid character from the ASCII table i.e. from value 32 (i.e. space) to 126 (i.e. ‘~’); otherwise, it throws an exception.

setFileRules(fileRules: PyOpenColorIO.FileRules) → None¶: Set file rules.

Note

The argument is cloned.

setInactiveColorSpaces(inactiveColorSpaces: str) → None¶

Set/get a list of inactive color space or named transform names.

Notes: - List can contain color space and/or named transform names. - The inactive spaces are color spaces that should not appear in application menus. - These color spaces will still work in Config::getProcessor calls. - The argument is a comma-delimited string. A null or empty string empties the list. - The environment variable OCIO_INACTIVE_COLORSPACES may also be used to set the inactive color space list. - The env. var. takes precedence over the inactive_colorspaces list in the config file. - Setting the list via the API takes precedence over either the env. var. or the config file list.

setMajorVersion(major: int) → None¶

Set the configuration major version.

Throws if it is not supported. Resets minor to the most recent minor for the given major.

setMinorVersion(minor: int) → None¶: Set the configuration minor version. Throws if it is not supported for the current major.

setName(name: str) → None¶

setProcessorCacheFlags(flags: PyOpenColorIO.ProcessorCacheFlags) → None¶

Control the caching of processors in the config instance. By default, caching is on.: The flags allow turning caching off entirely or only turning it off if dynamic properties are being used by the processor.

setRole(role: str, colorSpaceName: str) → None¶: Note

Setting the colorSpaceName name to a null string unsets it.

setSearchPath(path: str) → None¶

Set all search paths as a concatenated string, ‘:’ to separate the paths.

See addSearchPath for a more robust and platform-agnostic method of setting the search paths.

setStrictParsingEnabled(enabled: bool) → None¶

setVersion(major: int, minor: int) → None¶: Set the configuration major and minor versions. Throws if version is not supported.

setViewingRules(ViewingRules: PyOpenColorIO.ViewingRules) → None¶: Set viewing rules.

Note

The argument is cloned.

setWorkingDir(dirName: str) → None¶: The working directory defaults to the location of the config file. It is used to convert any relative paths to absolute. If no search paths have been set, the working directory will be used as the fallback search path. No environment (context) variables may be used in the working directory.

upgradeToLatestVersion() → None¶: Allows an older config to be serialized as the current version.

validate() → None¶

Performs a thorough validation for the most common user errors.

This will throw an exception if the config is malformed. The most common error occurs when references are made to colorspaces that do not exist.

class PyOpenColorIO.Config.EnvironmentVarNameIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.Config.EnvironmentVarNameIterator¶

len(self) → int¶

next(self) → str¶

class PyOpenColorIO.Config.SearchPathIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.Config.SearchPathIterator¶

len(self) → int¶

next(self) → str¶

class PyOpenColorIO.Config.ColorSpaceNameIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.Config.ColorSpaceNameIterator¶

len(self) → int¶

next(self) → str¶

class PyOpenColorIO.Config.ColorSpaceIterator¶

self[arg0: int] → PyOpenColorIO.ColorSpace¶

iter(self) → PyOpenColorIO.Config.ColorSpaceIterator¶

len(self) → int¶

next(self) → PyOpenColorIO.ColorSpace¶

class PyOpenColorIO.Config.ActiveColorSpaceNameIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.Config.ActiveColorSpaceNameIterator¶

len(self) → int¶

next(self) → str¶

class PyOpenColorIO.Config.ActiveColorSpaceIterator¶

self[arg0: int] → PyOpenColorIO.ColorSpace¶

iter(self) → PyOpenColorIO.Config.ActiveColorSpaceIterator¶

len(self) → int¶

next(self) → PyOpenColorIO.ColorSpace¶

class PyOpenColorIO.Config.RoleNameIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.Config.RoleNameIterator¶

len(self) → int¶

next(self) → str¶

class PyOpenColorIO.Config.RoleColorSpaceIterator¶

self[arg0: int] → tuple¶

iter(self) → PyOpenColorIO.Config.RoleColorSpaceIterator¶

len(self) → int¶

next(self) → tuple¶

class PyOpenColorIO.Config.DisplayIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.Config.DisplayIterator¶

len(self) → int¶

next(self) → str¶

class PyOpenColorIO.Config.SharedViewIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.Config.SharedViewIterator¶

len(self) → int¶

next(self) → str¶

class PyOpenColorIO.Config.ViewIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.Config.ViewIterator¶

len(self) → int¶

next(self) → str¶

class PyOpenColorIO.Config.ViewForColorSpaceIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.Config.ViewForColorSpaceIterator¶

len(self) → int¶

next(self) → str¶

class PyOpenColorIO.Config.LookNameIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.Config.LookNameIterator¶

len(self) → int¶

next(self) → str¶

class PyOpenColorIO.Config.LookIterator¶

self[arg0: int] → PyOpenColorIO.Look¶

iter(self) → PyOpenColorIO.Config.LookIterator¶

len(self) → int¶

next(self) → PyOpenColorIO.Look¶

class PyOpenColorIO.Config.ViewTransformNameIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.Config.ViewTransformNameIterator¶

len(self) → int¶

next(self) → str¶

class PyOpenColorIO.Config.ViewTransformIterator¶

self[arg0: int] → PyOpenColorIO.ViewTransform¶

iter(self) → PyOpenColorIO.Config.ViewTransformIterator¶

len(self) → int¶

next(self) → PyOpenColorIO.ViewTransform¶

class PyOpenColorIO.Config.NamedTransformNameIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.Config.NamedTransformNameIterator¶

len(self) → int¶

next(self) → str¶

class PyOpenColorIO.Config.NamedTransformIterator¶

self[arg0: int] → PyOpenColorIO.NamedTransform¶

iter(self) → PyOpenColorIO.Config.NamedTransformIterator¶

len(self) → int¶

next(self) → PyOpenColorIO.NamedTransform¶

class PyOpenColorIO.Config.ActiveNamedTransformNameIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.Config.ActiveNamedTransformNameIterator¶

len(self) → int¶

next(self) → str¶

class PyOpenColorIO.Config.ActiveNamedTransformIterator¶

self[arg0: int] → PyOpenColorIO.NamedTransform¶

iter(self) → PyOpenColorIO.Config.ActiveNamedTransformIterator¶

len(self) → int¶

next(self) → PyOpenColorIO.NamedTransform¶

ConstConfigRcPtr OpenColorIO_v2_3dev::GetCurrentConfig()¶: Get the current configuration.

void OpenColorIO_v2_3dev::SetCurrentConfig(const ConstConfigRcPtr &config)¶: Set the current configuration. This will then store a copy of the specified config.

class Config¶

A config defines all the color spaces to be available at runtime.

See the user-guide for more information on selecting, creating, and working with custom color configurations.

Roughly speaking, a novice user should select a default configuration that most closely approximates the use case (animation, visual effects, etc.), and set the :envvar:OCIO environment variable to point at the root of that configuration.

See developers-usageexamples

Note

Initialization using environment variables is typically preferable in a multi-app ecosystem, as it allows all applications to be consistently configured.

Public Functions

ConfigRcPtr createEditableCopy() const¶

unsigned int getMajorVersion() const¶: Get the configuration major version.

void setMajorVersion(unsigned int major)¶

Set the configuration major version.

Throws if it is not supported. Resets minor to the most recent minor for the given major.

unsigned int getMinorVersion() const¶: Get the configuration minor version.

void setMinorVersion(unsigned int minor)¶: Set the configuration minor version. Throws if it is not supported for the current major.

void setVersion(unsigned int major, unsigned int minor)¶: Set the configuration major and minor versions. Throws if version is not supported.

void upgradeToLatestVersion() noexcept¶: Allows an older config to be serialized as the current version.

void validate() const¶

Performs a thorough validation for the most common user errors.

This will throw an exception if the config is malformed. The most common error occurs when references are made to colorspaces that do not exist.

const char *getName() const noexcept¶

Get/set a name string for the config.

void setName(const char *name) noexcept¶

char getFamilySeparator() const¶

Get the family separator.

A single character used to separate the family string into tokens for use in hierarchical menus. Defaults to ‘/’.

void setFamilySeparator(char separator)¶

Set the family separator.

Succeeds if the characters is null or a valid character from the ASCII table i.e. from value 32 (i.e. space) to 126 (i.e. ‘~’); otherwise, it throws an exception.

const char *getDescription() const¶

void setDescription(const char *description)¶

void serialize(std::ostream &os) const¶

Returns the string representation of the Config in YAML text form.

This is typically stored on disk in a file with the extension .ocio. NB: This does not validate the config. Applications should validate before serializing.

const char *getCacheID() const¶

If a context is not provided, the current Context will be used.

If a null context is provided, file references will not be taken into account (this is essentially a hash of Config::serialize).

const char *getCacheID(const ConstContextRcPtr &context) const¶

ConstContextRcPtr getCurrentContext() const¶

void addEnvironmentVar(const char *name, const char *defaultValue)¶: Add (or update) an environment variable with a default value. But it removes it if the default value is null.

int getNumEnvironmentVars() const¶

const char *getEnvironmentVarNameByIndex(int index) const¶

const char *getEnvironmentVarDefault(const char *name) const¶

void clearEnvironmentVars()¶

void setEnvironmentMode(EnvironmentMode mode) noexcept¶

The EnvironmentMode controls the behavior of loadEnvironment.

ENV_ENVIRONMENT_LOAD_PREDEFINED - Only update vars already added to the Context.
ENV_ENVIRONMENT_LOAD_ALL - Load all env. vars into the Context.

Client programs generally will not use these methods because the EnvironmentMode is set automatically when a Config is loaded. If the Config has an “environment” section, the mode is set to LOAD_PREDEFINED, and otherwise set to LOAD_ALL.

Note

Loading ALL the env. vars may reduce performance and reduce cache efficiency.

EnvironmentMode getEnvironmentMode() const noexcept¶

void loadEnvironment() noexcept¶: Initialize the environment/context variables in the Config’s Context.

const char *getSearchPath() const¶

void setSearchPath(const char *path)¶

Set all search paths as a concatenated string, use ‘:’ to separate the paths.

See addSearchPath for a more robust and platform-agnostic method of setting the search paths.

int getNumSearchPaths() const¶

const char *getSearchPath(int index) const¶

Get a search path from the list.

The paths are in the order they will be searched (that is, highest to lowest priority).

void clearSearchPaths()¶

void addSearchPath(const char *path)¶

Add a single search path to the end of the list.

const char *getWorkingDir() const¶

void setWorkingDir(const char *dirname)¶: The working directory defaults to the location of the config file. It is used to convert any relative paths to absolute. If no search paths have been set, the working directory will be used as the fallback search path. No environment (context) variables may be used in the working directory.

ColorSpaceSetRcPtr getColorSpaces(const char *category) const¶: Get all active color spaces having a specific category in the order they appear in the config file.

Note

If the category is null or empty, the method returns all the active color spaces like Config::getNumColorSpaces and Config::getColorSpaceNameByIndex do.

Note

It’s worth noticing that the method returns a copy of the selected color spaces decoupling the result from the config. Hence, any changes on the config do not affect the existing color space sets, and vice-versa.

int getNumColorSpaces(SearchReferenceSpaceType searchReferenceType, ColorSpaceVisibility visibility) const¶: Work on the color spaces selected by the reference color space type and visibility.

const char *getColorSpaceNameByIndex(SearchReferenceSpaceType searchReferenceType, ColorSpaceVisibility visibility, int index) const¶

Work on the color spaces selected by the reference color space type and visibility (active or inactive).

Return empty for invalid index.

int getNumColorSpaces() const¶: Work on the active color spaces only.

Note

Only works from the list of active color spaces.

const char *getColorSpaceNameByIndex(int index) const¶: Work on the active color spaces only and return null for invalid index.

Note

Only works from the list of active color spaces.

int getIndexForColorSpace(const char *name) const¶: Get an index from the active color spaces only and return -1 if the name is not found.

Note

The fcn accepts either a color space name, role name, or alias. (Color space names take precedence over roles.)

ConstColorSpaceRcPtr getColorSpace(const char *name) const¶: Get the color space from all the color spaces (i.e. active and inactive) and return null if the name is not found.

Note

The fcn accepts either a color space name, role name, or alias. (Color space names take precedence over roles.)

const char *getCanonicalName(const char *name) const¶: Accepts an alias, role name, named transform name, or color space name and returns the color space name or the named transform name.

void addColorSpace(const ConstColorSpaceRcPtr &cs)¶: Add a color space to the configuration.

Note

If another color space is already present with the same name, this will overwrite it. This stores a copy of the specified color space.

Note

Adding a color space to a Config does not affect any ColorSpaceSet sets that have already been created.

void removeColorSpace(const char *name)¶: Remove a color space from the configuration.

Note

It does not throw an exception. Name must be the canonical name. If a role name or alias is provided or if the name is not in the config, nothing is done.

Note

Removing a color space from a Config does not affect any ColorSpaceSet sets that have already been created.

bool isColorSpaceUsed(const char *name) const noexcept¶: Return true if the color space is used by a transform, a role, or a look.

Note

Name must be the canonical name.

void clearColorSpaces()¶: Remove all the color spaces from the configuration.

Note

Removing color spaces from a Config does not affect any ColorSpaceSet sets that have already been created.

void setInactiveColorSpaces(const char *inactiveColorSpaces)¶

Set/get a list of inactive color space or named transform names.

Notes:

List can contain color space and/or named transform names.
The inactive spaces are color spaces that should not appear in application menus.
These color spaces will still work in Config::getProcessor calls.
The argument is a comma-delimited string. A null or empty string empties the list.
The environment variable OCIO_INACTIVE_COLORSPACES may also be used to set the inactive color space list.
The env. var. takes precedence over the inactive_colorspaces list in the config file.
Setting the list via the API takes precedence over either the env. var. or the config file list.

const char *getInactiveColorSpaces() const¶

bool isInactiveColorSpace(const char *colorspace) const noexcept¶: Return true if the color space name is present in the inactive_colorspaces list.

bool isColorSpaceLinear(const char *colorSpace, ReferenceSpaceType referenceSpaceType) const¶

Return true if the specified color space is linear.

The algorithm proceeds as follows: — If the color space isdata attribute is true, return false. — If the reference space type of the color space differs from the requested reference space type, return false. — If the color space’s encoding attribute is present, return true if it matches the expected reference space type (i.e., “scene-linear” for REFERENCE_SPACE_SCENE or “display-linear” for REFERENCE_SPACE_DISPLAY) and false otherwise. — If the color space has no to_reference or from_reference transform, return true. — Evaluate several points through the color space’s transform and check if the output only differs by a scale factor (which may be different per channel, e.g. allowing an arbitrary matrix transform, with no offset).

Parameters:

colorSpace – Color space to evaluate.
referenceSpaceType – Evaluate linearity with respect to the specified reference space (either scene-referred or display-referred).

void setRole(const char *role, const char *colorSpaceName)¶

Methods related to Roles.

A role allows a config author to indicate that a given color space should be used for a particular purpose.

Role names may be passed to most functions that accept color space names, such as getColorSpace. So for example, you may find the name of the color space assigned to the scene_linear role by getting the color space object for “scene_linear” and then calling getName on the color space object.

Note

Setting the colorSpaceName name to a null string unsets it.

int getNumRoles() const¶

bool hasRole(const char *role) const¶: Return true if the role has been defined.

const char *getRoleName(int index) const¶

Get the role name at index, this will return values like ‘scene_linear’, ‘compositing_log’.

Return empty string if index is out of range.

const char *getRoleColorSpace(int index) const¶

Get the role color space at index.

Return empty string if index is out of range.

const char *getRoleColorSpace(const char *roleName) const noexcept¶

Get the color space name used for the specified role.

Return an empty string if the role is not present

void addSharedView(const char *view, const char *viewTransformName, const char *colorSpaceName, const char *looks, const char *ruleName, const char *description)¶

Will throw if view or colorSpaceName are null or empty.

Methods related to displays and views.

The following methods only manipulate active displays and views. Active displays and views are defined from an env. variable or from the config file.

Shared views using a view transform may use the token <USE_DISPLAY_NAME> for the color space (see :c:var:OCIO_VIEW_USE_DISPLAY_NAME). In that case, when the view is referenced in a display, the display color space that is used will be the one matching the display name. In other words, the view will be customized based on the display it is used in. Config::validate will throw if the config does not contain the matching display color space.

void removeSharedView(const char *view)¶: Remove a shared view. Will throw if the view does not exist.

const char *getDefaultDisplay() const¶

int getNumDisplays() const¶

const char *getDisplay(int index) const¶: Will return “” if the index is invalid.

const char *getDefaultView(const char *display) const¶

const char *getDefaultView(const char *display, const char *colorspaceName) const¶

int getNumViews(const char *display) const¶: Return the number of views attached to the display including the number of shared views if any. Return 0 if display does not exist.

const char *getView(const char *display, int index) const¶

int getNumViews(const char *display, const char *colorspaceName) const¶: If the config has ViewingRules, get the number of active Views for this colorspace. (If there are no rules, it returns all of them.)

const char *getView(const char *display, const char *colorspaceName, int index) const¶

const char *getDisplayViewTransformName(const char *display, const char *view) const¶: Returns the view_transform attribute of the (display, view) pair. View can be a shared view of the display. If display is null or empty, config shared views are used.

const char *getDisplayViewColorSpaceName(const char *display, const char *view) const¶: Returns the colorspace attribute of the (display, view) pair. (Note that this may be either a color space or a display color space.)

const char *getDisplayViewLooks(const char *display, const char *view) const¶: Returns the looks attribute of a (display, view) pair.

const char *getDisplayViewRule(const char *display, const char *view) const noexcept¶: Returns the rule attribute of a (display, view) pair.

const char *getDisplayViewDescription(const char *display, const char *view) const noexcept¶: Returns the description attribute of a (display, view) pair.

void addDisplayView(const char *display, const char *view, const char *colorSpaceName, const char *looks)¶: For the (display, view) pair, specify which color space and look to use. If a look is not desired, then just pass a null or empty string.

void addDisplayView(const char *display, const char *view, const char *viewTransformName, const char *colorSpaceName, const char *looks, const char *ruleName, const char *description)¶

For the (display, view) pair, specify the color space or alternatively specify the view transform and display color space. The looks, viewing rule, and description are optional. Pass a null or empty string for any optional arguments. If the view already exists, it is replaced.

Will throw if:

Display, view or colorSpace are null or empty.
Display already has a shared view with the same name.

void addDisplaySharedView(const char *display, const char *sharedView)¶

Add a (reference to a) shared view to a display.

The shared view must be part of the config. See Config::addSharedView

This will throw if:

Display or view are null or empty.
Display already has a view (shared or not) with the same name.

void removeDisplayView(const char *display, const char *view)¶

Remove the view and the display if no more views.

It does not remove the associated color space. If the view name is a shared view, it only removes the reference to the view from the display but the shared view, remains in the config.

Will throw if the view does not exist.

void clearDisplays()¶: Clear all the displays.

void addVirtualDisplayView(const char *view, const char *viewTransformName, const char *colorSpaceName, const char *looks, const char *ruleName, const char *description)¶

Methods related to the Virtual Display.

… (See descriptions for the non-virtual methods above.)

The virtual display is the way to incorporate the ICC monitor profile for a user’s display into OCIO. The views that are defined for the virtual display are the views that are used to create a new display for an ICC profile. They serve as a kind of template that lets OCIO know how to build the new display.

Typically the views will define a View Transform and set the colorSpaceName to “<USE_DISPLAY_NAME>” so that it will use the display color space with the same name as the display, in this case corresponding to the ICC profile.

void addVirtualDisplaySharedView(const char *sharedView)¶

int getVirtualDisplayNumViews(ViewType type) const noexcept¶: Get the number of views associated to the virtual display.

const char *getVirtualDisplayView(ViewType type, int index) const noexcept¶: Get the view name at a specific index.

const char *getVirtualDisplayViewTransformName(const char *view) const noexcept¶

const char *getVirtualDisplayViewColorSpaceName(const char *view) const noexcept¶

const char *getVirtualDisplayViewLooks(const char *view) const noexcept¶

const char *getVirtualDisplayViewRule(const char *view) const noexcept¶

const char *getVirtualDisplayViewDescription(const char *view) const noexcept¶

void removeVirtualDisplayView(const char *view) noexcept¶: Remove the view from the virtual display.

void clearVirtualDisplay() noexcept¶: Clear the virtual display.

int instantiateDisplayFromMonitorName(const char *monitorName)¶

Instantiate a new display from a virtual display, using the monitor name.

This method uses the virtual display to create an actual display for the given monitorName. The new display will receive the views from the virtual display.

A new display color space will also be created using the display name. It will have a from_display_reference transform that is a FileTransform pointing to the ICC profile.

Will throw if the config does not have a virtual display or if the monitorName does not exist.

If there is already a display or a display color space with the name monitorName, it will be replaced/updated.

Returns the index of the display.

int instantiateDisplayFromICCProfile(const char *ICCProfileFilepath)¶

Instantiate a new display from a virtual display, using an ICC profile.

On platforms such as Linux, where the SystemMonitors class is not able to obtain a list of ICC profiles from the OS, this method may be used to manually specify a path to an ICC profile.

Will throw if the virtual display definition is missing from the config.

Returns the index of the display.

void setActiveDisplays(const char *displays)¶

Comma-delimited list of names to filter and order the active displays.

Note

The setter does not override the envvar. The getter does not take into account the envvar value and thus may not represent what the user is seeing.

const char *getActiveDisplays() const¶

void setActiveViews(const char *views)¶

Comma-delimited list of names to filter and order the active views.

Note

The setter does not override the envvar. The getter does not take into account the envvar value and thus may not represent what the user is seeing.

const char *getActiveViews() const¶

int getNumDisplaysAll() const noexcept¶: Get all displays in the config, ignoring the active_displays list.

const char *getDisplayAll(int index) const noexcept¶

int getDisplayAllByName(const char*) const noexcept¶

bool isDisplayTemporary(int index) const noexcept¶: Will be true for a display that was instantiated from a virtual display. These displays are intended to be temporary (i.e. for the current session) and are not saved to a config file.

int getNumViews(ViewType type, const char *display) const¶: Get either the shared or display-defined views for a display. The active_views list is ignored. Passing a null or empty display (with type=VIEW_SHARED) returns the contents of the shared_views section of the config. Return 0 if display does not exist.

const char *getView(ViewType type, const char *display, int index) const¶

ConstViewingRulesRcPtr getViewingRules() const noexcept¶: Get read-only version of the viewing rules.

void setViewingRules(ConstViewingRulesRcPtr viewingRules)¶: Set viewing rules.

Note

The argument is cloned.

void getDefaultLumaCoefs(double *rgb) const¶: Get the default coefficients for computing luma.

Note

There is no “1 size fits all” set of luma coefficients. (The values are typically different for each colorspace, and the application of them may be nonsensical depending on the intensity coding anyways). Thus, the ‘right’ answer is to make these functions on the ColorSpace class. However, it’s often useful to have a config-wide default so here it is. We will add the colorspace specific luma call if/when another client is interesting in using it.

void setDefaultLumaCoefs(const double *rgb)¶: These should be normalized (sum to 1.0 exactly).

ConstLookRcPtr getLook(const char *name) const¶

int getNumLooks() const¶

const char *getLookNameByIndex(int index) const¶

void addLook(const ConstLookRcPtr &look)¶

void clearLooks()¶

int getNumViewTransforms() const noexcept¶

ConstViewTransformRcPtr getViewTransform(const char *name) const noexcept¶

const char *getViewTransformNameByIndex(int i) const noexcept¶

void addViewTransform(const ConstViewTransformRcPtr &viewTransform)¶

ConstViewTransformRcPtr getDefaultSceneToDisplayViewTransform() const¶: This view transform is the one that will be used by default if a ColorSpaceTransform is needed between a scene-referred and display-referred color space. The config author may specify a transform to use via the default_view_transform entry in the config. If that is not present, or does not return a valid view transform from the scene-referred connection space, the fall-back is to use the first valid view transform in the config. Returns a null ConstTransformRcPtr if there isn’t one.

const char *getDefaultViewTransformName() const noexcept¶

Get or set the default_view_transform string from the config.

Note that if this is not the name of a valid view transform from the scene-referred connection space, it will be ignored.

void setDefaultViewTransformName(const char *defaultName) noexcept¶

void clearViewTransforms()¶

int getNumNamedTransforms(NamedTransformVisibility visibility) const noexcept¶

Work on the named transforms selected by visibility.

Methods related to named transforms.

const char *getNamedTransformNameByIndex(NamedTransformVisibility visibility, int index) const noexcept¶

Work on the named transforms selected by visibility (active or inactive).

Return an empty string for invalid index.

int getNumNamedTransforms() const noexcept¶: Work on the active named transforms only.

const char *getNamedTransformNameByIndex(int index) const noexcept¶: Work on the active named transforms only and return an empty string for invalid index.

int getIndexForNamedTransform(const char *name) const noexcept¶: Get an index from the active named transforms only and return -1 if the name is not found.

ConstNamedTransformRcPtr getNamedTransform(const char *name) const noexcept¶: Get the named transform from all the named transforms (i.e. active and inactive) and return null if the name is not found.

void addNamedTransform(const ConstNamedTransformRcPtr &namedTransform)¶: Add or replace named transform.

Note

Throws if namedTransform is null, name is missing, or no transform is set. Also throws if the name or the aliases conflict with names or aliases already in the config.

void clearNamedTransforms()¶: Clear all named transforms.

ConstFileRulesRcPtr getFileRules() const noexcept¶: Get read-only version of the file rules.

void setFileRules(ConstFileRulesRcPtr fileRules)¶: Set file rules.

Note

The argument is cloned.

const char *getColorSpaceFromFilepath(const char *filePath) const¶: Get the color space of the first rule that matched filePath. (For v1 configs, this is equivalent to calling parseColorSpaceFromString with strictparsing set to false.)

const char *getColorSpaceFromFilepath(const char *filePath, size_t &ruleIndex) const¶: Most applications will use the preceding method, but this method may be used for applications that want to know which was the highest priority rule to match filePath. FileRules::getNumCustomKeys and custom keys methods may then be used to get additional information about the matching rule.

bool filepathOnlyMatchesDefaultRule(const char *filePath) const¶: Returns true if the only rule matched by filePath is the default rule. This is a convenience method for applications that want to require the user to manually choose a color space when strictParsing is true and no other rules match.

const char *parseColorSpaceFromString(const char *str) const¶

Given the specified string, get the longest, right-most, colorspace substring that appears.

If strict parsing is enabled, and no color space is found, return an empty string.
If strict parsing is disabled, return ROLE_DEFAULT (if defined).
If the default role is not defined, return an empty string.

bool isStrictParsingEnabled() const¶

void setStrictParsingEnabled(bool enabled)¶

ConstProcessorRcPtr getProcessor(const ConstContextRcPtr &context, const ConstColorSpaceRcPtr &srcColorSpace, const ConstColorSpaceRcPtr &dstColorSpace) const¶: Get the processor to apply a ColorSpaceTransform from a source to a destination color space.

ConstProcessorRcPtr getProcessor(const ConstColorSpaceRcPtr &srcColorSpace, const ConstColorSpaceRcPtr &dstColorSpace) const¶

ConstProcessorRcPtr getProcessor(const char *srcColorSpaceName, const char *dstColorSpaceName) const¶: Note

Names can be colorspace name, role name, or a combination of both.

ConstProcessorRcPtr getProcessor(const ConstContextRcPtr &context, const char *srcColorSpaceName, const char *dstColorSpaceName) const¶

ConstProcessorRcPtr getProcessor(const char *srcColorSpaceName, const char *display, const char *view, TransformDirection direction) const¶: Get the processor to apply a DisplayViewTransform for a display and view. Refer to the Display/View Registration section above for more info on the display and view arguments.

ConstProcessorRcPtr getProcessor(const ConstContextRcPtr &context, const char *srcColorSpaceName, const char *display, const char *view, TransformDirection direction) const¶

ConstProcessorRcPtr getProcessor(const ConstNamedTransformRcPtr &namedTransform, TransformDirection direction) const¶: Get the processor to apply a NamedTransform in the specified direction.

ConstProcessorRcPtr getProcessor(const ConstContextRcPtr &context, const ConstNamedTransformRcPtr &namedTransform, TransformDirection direction) const¶

ConstProcessorRcPtr getProcessor(const char *namedTransformName, TransformDirection direction) const¶

ConstProcessorRcPtr getProcessor(const ConstContextRcPtr &context, const char *namedTransformName, TransformDirection direction) const¶

ConstProcessorRcPtr getProcessor(const ConstTransformRcPtr &transform) const¶

Get the processor for the specified transform.

Not often needed, but will allow for the re-use of atomic OCIO functionality (such as to apply an individual LUT file).

ConstProcessorRcPtr getProcessor(const ConstTransformRcPtr &transform, TransformDirection direction) const¶

ConstProcessorRcPtr getProcessor(const ConstContextRcPtr &context, const ConstTransformRcPtr &transform, TransformDirection direction) const¶

ProcessorCacheFlags getProcessorCacheFlags() const noexcept¶: Get the Processor Cache flags.

void setProcessorCacheFlags(ProcessorCacheFlags flags) const noexcept¶: Control the caching of processors in the config instance. By default, caching is on. The flags allow turning caching off entirely or only turning it off if dynamic properties are being used by the processor.

void clearProcessorCache() noexcept¶

Clears this config’s cache of Processor, CPUProcessor, and GPUProcessor instances.

This must be done if any of the LUT files used by these Processors have been modified. Note that setProcessorCacheFlags(PROCESSOR_CACHE_OFF) turns off caching but does not clear any existing cache.

void setConfigIOProxy(ConfigIOProxyRcPtr ciop)¶: Set the ConfigIOProxy object used to provision the config and LUTs from somewhere other than the file system. (This is set on the config’s embedded Context object.)

ConfigIOProxyRcPtr getConfigIOProxy() const¶

bool isArchivable() const¶

Verify if the config is archivable.

A config is not archivable if any of the following are true: — The working directory is not set — It contains FileTransforms with a src outside the working directory — The search path contains paths outside the working directory — The search path contains paths that start with a context variable

Returns:: bool Archivable if true.

void archive(std::ostream &ostream) const¶

Archive the config and its LUTs into the specified output stream.

The provided output stream must be closed by the caller, if necessary (e.g., an ofstream).

Parameters:: ostream – The output stream to write to.

Config(const Config&) = delete¶

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

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

Public Static Functions

static ConfigRcPtr Create()¶

Create an empty config of the current version.

Note that an empty config will not pass validation since required elements will be missing.

Returns:: The Config object.

static ConstConfigRcPtr CreateRaw()¶

Create a fall-back config.

This may be useful to allow client apps to launch in cases when the supplied config path is not loadable.

Returns:: The Config object.

static ConstConfigRcPtr CreateFromEnv()¶

Create a configuration using the OCIO environment variable.

Also supports the OCIO URI format for Built-in configs and supports archived configs. See Config::CreateFromFile.

If the variable is missing or empty, returns the same result as Config::CreateRaw.

Returns:: The Config object.

static ConstConfigRcPtr CreateFromFile(const char *filename)¶

Create a configuration using a specific config file.

Supports the OCIO URI format for Built-in configs. See Config::CreateFromBuiltinConfig.

Supports archived configs (.ocioz files).

Throws:: Exception – If the file may not be read or does not parse.
Returns:: The Config object.

static ConstConfigRcPtr CreateFromStream(std::istream &istream)¶

Create a configuration using a stream.

Configs created from CreateFromStream can not be archived unless the working directory is set and contains any necessary LUT files.

Parameters:: istream – Stream to the config.
Throws:: Exception – If the stream does not parse.
Returns:: The Config object.

static ConstConfigRcPtr CreateFromConfigIOProxy(ConfigIOProxyRcPtr ciop)¶

Create a config from the supplied ConfigIOProxy object. This allows the calling program to directly provide the config and associated LUTs rather than reading them from the standard file system.

See the ConfigIOProxy class documentation for more info.

Parameters:: ciop – ConfigIOProxy object providing access to the config’s files.
Throws:: Exception – If the config may not be read from the proxy, or does not parse.
Returns:: The Config object.

static ConstConfigRcPtr CreateFromBuiltinConfig(const char *configName)¶

Create a configuration using an OCIO built-in config.

Also supports the following OCIO URI format for Built-in configs: “ocio://default” - Default Built-in config. “ocio://cg-config-latest” - Latest Built-in CG config. “ocio://studio-config-latest” - Latest Built-in Studio config. “ocio://<CONFIG NAME>” - A specific Built-in config.

The available configNames are:

ACES Studio config, contains a more complete collection of color spaces and displays: “studio-config-v1.0.0_aces-v1.3_ocio-v2.1” “studio-config-v2.1.0_aces-v1.3_ocio-v2.3”

ACES CG config, basic color spaces for computer graphics apps: “cg-config-v1.0.0_aces-v1.3_ocio-v2.1” “cg-config-v2.1.0_aces-v1.3_ocio-v2.3”

More information is available at: https://github.com/AcademySoftwareFoundation/OpenColorIO-Config-ACES

Information about the available configs is available from the BuiltinConfigRegistry.

Parameters:: configName – Built-in config name (with or without the “ocio://” URI prefix).
Throws:: Exception – If the configName is not recognized.
Returns:: One of the configs built into the OCIO library.

static char GetDefaultFamilySeparator() noexcept¶: Get the default family separator i.e. ‘/’ .

static const char *IdentifyBuiltinColorSpace(const ConstConfigRcPtr &srcConfig, const ConstConfigRcPtr &builtinConfig, const char *builtinColorSpaceName)¶

Find the name of the color space in the source config that is the same as a color space in the default built-in config. For example, setting the builtinColorSpaceName to “sRGB - Texture” (a color space name from that config), would return the name for the corresponding sRGB texture space in the current config (or empty if it was not found). Note that this method relies on heuristics which may evolve over time and which may not work on all configs.

The method only looks at active color spaces. If the interchange roles are missing and heuristics are used, only scene-referred color spaces are searched.

Parameters:

srcConfig – The config to search for the desired color space.
builtinConfig – The built-in config to use. See Config::CreateFromBuiltinConfig.
builtinColorSpaceName – Color space name in the built-in default config.

Throws:

Exception – if an interchange space cannot be found or the equivalent space cannot be found.

Returns:

Matching color space name from the source config. Empty if not found.

static void IdentifyInterchangeSpace(const char **srcInterchangeName, const char **builtinInterchangeName, const ConstConfigRcPtr &srcConfig, const char *srcColorSpaceName, const ConstConfigRcPtr &builtinConfig, const char *builtinColorSpaceName)¶

Identify the two names of a common color space that exists in both the given config and the provided built-in config that may be used for converting color spaces between the two configs. If both configs have the interchange role set, than the color spaces set to that role will be returned. Otherwise, heuristics will be used to try and identify a known color space in the source config. These are the same heuristics that are used for other methods such as identifyBuiltinColorSpace and GetProcessorTo/FromBuiltinColorSpace.

Using this method in connection with GetProcessorFromConfigs is more efficient if you need to call GetProcessorTo/FromBuiltinColorSpace multiple times since it is only necessary to run the heuristics once (to identify the interchange spaces).

The srcColorSpaceName and builtinColorSpace name are used to decide which interchange role to use (scene- or display-referred). However, they are not used if the interchange roles are not present and the heuristics are used. It is actually only the ReferenceSpaceType of the color spaces that are used, so it is not necessary to call this function multiple times if all the spaces are of the same type. (These are the same arguments that would also be set if you were instead calling GetProcessorTo/FromBuiltinColorSpace.)

Parameters:

srcInterchangeName – [out] Color space name from the source config.
builtinInterchangeName – [out] Corresponding color space name from the built-in config.
srcConfig – The config to search for the desired color space.
srcColorSpaceName – Color space name in the given config to convert to/from.
builtinConfig – The built-in config to use. See Config::CreateFromBuiltinConfig.
builtinColorSpaceName – Color space name in the default built-in config.

Throws:

Exception – if either the srcInterchange or builtinInterchange cannot be identified.

static ConstProcessorRcPtr GetProcessorToBuiltinColorSpace(ConstConfigRcPtr srcConfig, const char *srcColorSpaceName, const char *builtinColorSpaceName)¶

Get a Processor to or from a known external color space.

These methods provide a way to interface color spaces in a config with known standard external color spaces. The set of external color space are those contained in the current default Built-in config. This includes common spaces such as “Linear Rec.709 (sRGB)”, “sRGB - Texture”, “ACEScg”, and “ACES2065-1”.

If the source config defines the necessary Interchange Role (typically “aces_interchange”), then the conversion will be well-defined and equivalent to calling GetProcessorFromConfigs with the source config and the Built-in config.

However, if the Interchange Roles are not present, heuristics will be used to try and identify a common color space in the source config that may be used to allow the conversion to proceed. If the heuristics fail to find a suitable space, an exception is thrown. The heuristics may evolve, so the results returned by this function for a given source config and color space may change in future releases of the library. However, the Interchange Roles are required in config versions 2.2 and higher, so it is hoped that the need for the heuristics will decrease over time.

Parameters:

srcConfig – The user’s source config.
srcColorSpaceName – The name of the color space in the source config.
builtinColorSpaceName – The name of the color space in the current default Built-in config.

Throws:

Exception – if either the src or builtin interchange space cannot be identified.

static ConstProcessorRcPtr GetProcessorFromBuiltinColorSpace(const char *builtinColorSpaceName, ConstConfigRcPtr srcConfig, const char *srcColorSpaceName)¶

See description of GetProcessorToBuiltinColorSpace.

Parameters:

builtinColorSpaceName – The name of the color space in the current default Built-in config.
srcConfig – The user’s source config.
srcColorSpaceName – The name of the color space in the source config.

static ConstProcessorRcPtr GetProcessorFromConfigs(const ConstConfigRcPtr &srcConfig, const char *srcColorSpaceName, const ConstConfigRcPtr &dstConfig, const char *dstColorSpaceName)¶

Get a processor to convert between color spaces in two separate configs.

static ConstProcessorRcPtr GetProcessorFromConfigs(const ConstContextRcPtr &srcContext, const ConstConfigRcPtr &srcConfig, const char *srcColorSpaceName, const ConstContextRcPtr &dstContext, const ConstConfigRcPtr &dstConfig, const char *dstColorSpaceName)¶

static ConstProcessorRcPtr GetProcessorFromConfigs(const ConstConfigRcPtr &srcConfig, const char *srcColorSpaceName, const char *srcInterchangeName, const ConstConfigRcPtr &dstConfig, const char *dstColorSpaceName, const char *dstInterchangeName)¶

The srcInterchangeName and dstInterchangeName must refer to a pair of color spaces in the two configs that are the same. A role name may also be used.

Note: For all of the two-config GetProcessor functions, if either the source or destination color spaces are data spaces, the entire processor will be a no-op.

static ConstProcessorRcPtr GetProcessorFromConfigs(const ConstContextRcPtr &srcContext, const ConstConfigRcPtr &srcConfig, const char *srcColorSpaceName, const char *srcInterchangeName, const ConstContextRcPtr &dstContext, const ConstConfigRcPtr &dstConfig, const char *dstColorSpaceName, const char *dstInterchangeName)¶

static ConstProcessorRcPtr GetProcessorFromConfigs(const ConstConfigRcPtr &srcConfig, const char *srcColorSpaceName, const ConstConfigRcPtr &dstConfig, const char *dstDisplay, const char *dstView, TransformDirection direction)¶: Get a processor to convert from a color space to a display and view in two separate configs.

static ConstProcessorRcPtr GetProcessorFromConfigs(const ConstContextRcPtr &srcContext, const ConstConfigRcPtr &srcConfig, const char *srcColorSpaceName, const ConstContextRcPtr &dstContext, const ConstConfigRcPtr &dstConfig, const char *dstDisplay, const char *dstView, TransformDirection direction)¶

static ConstProcessorRcPtr GetProcessorFromConfigs(const ConstConfigRcPtr &srcConfig, const char *srcColorSpaceName, const char *srcInterchangeName, const ConstConfigRcPtr &dstConfig, const char *dstDisplay, const char *dstView, const char *dstInterchangeName, TransformDirection direction)¶: The srcInterchangeName and dstInterchangeName must refer to a pair of color spaces in the two configs that are the same. A role name may also be used.

static ConstProcessorRcPtr GetProcessorFromConfigs(const ConstContextRcPtr &srcContext, const ConstConfigRcPtr &srcConfig, const char *srcColorSpaceName, const char *srcInterchangeName, const ConstContextRcPtr &dstContext, const ConstConfigRcPtr &dstConfig, const char *dstDisplay, const char *dstView, const char *dstInterchangeName, TransformDirection direction)¶

std::ostream &OpenColorIO_v2_3dev::operator<<(std::ostream&, const Config&)¶

typedef std::shared_ptr<const Config> OpenColorIO_v2_3dev::ConstConfigRcPtr¶

typedef std::shared_ptr<Config> OpenColorIO_v2_3dev::ConfigRcPtr¶

Constants: Roles, Shared View