OpenColorIO

Open Source Color Management

OpenColorIO 1.0.6 documentation

Python: Config

Examples of Use

import PyOpenColorIO as OCIO

# Load an existing configuration from the environment.
# The resulting configuration is read-only. If $OCIO is set, it will use that.
# Otherwise it will use an internal default.
config = OCIO.GetCurrentConfig()

# What color spaces exist?
colorSpaceNames = [ cs.getName() for cs in config.getColorSpaces() ]

# Given a string, can we parse a color space name from it?
inputString = 'myname_linear.exr'
colorSpaceName = config.parseColorSpaceFromString(inputString)
if colorSpaceName:
    print 'Found color space', colorSpaceName
else:
    print 'Could not get color space from string', inputString

# What is the name of scene-linear in the configuration?
colorSpace = config.getColorSpace(OCIO.Constants.ROLE_SCENE_LINEAR)
if colorSpace:
    print colorSpace.getName()
else:
    print 'The role of scene-linear is not defined in the configuration'

# For examples of how to actually perform the color transform math,
# see 'Python: Processor' docs.

# Create a new, empty, editable configuration
config = OCIO.Config()

# Create a new color space, and add it
cs = OCIO.ColorSpace(...)
# (See ColorSpace for details)
config.addColorSpace(cs)

# For additional examples of config manipulation, see
# https://github.com/imageworks/OpenColorIO-Configs/blob/master/nuke-default/make.py

Description

A color configuration (Config) defines all the color spaces to be available at runtime.

(Config) is the main object for interacting with this library. It encapsulates all the information necessary to use customized ColorSpaceTransform and DisplayTransform 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 configuration 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) that wants to handle multiple show configurations concurrently in a single process. This app would need to keep multiple configurations alive, and 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.

Note

Paths to LUTs can be relative. The search paths are defined in Config.

See Usage Examples

class Config

Functions

Config.CreateFromEnv()

Create a Config object using the environment variable.

Returns:Config object
Config.CreateFromFile(filename)

Create a Config object using the information in a file.

Parameters:filename (string) – name of file
Returns:Config object

Initialization Methods

Config.isEditable()

Returns whether Config is editable.

The configurations returned from :py:method:`getCurrentConfig()` are not editable, and if you want to edit them you can use :py:method:`createEditableCopy()`.

If you attempt to call any of the set functions on a noneditable Config, an exception will be thrown.

Returns:state of Config‘s editability
Return type:bool
Config.createEditableCopy()

Returns an editable copy of Config.

Returns:editable copy of Config
Return type:Config object
Config.sanityCheck()

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

Resource Methods

Config.getDescription()

Returns the stored description of Config.

Returns:stored description of Config
Return type:string
Config.setDescription(desc)

Sets the description of Config.

Parameters:desc (string) – description of Config
Config.serialize()

Returns the string representation of Config in YAML text form. This is typically stored on disk in a file with the .ocio extension.

Returns:Config in YAML text form
Return type:string
Config.getCacheID([pycontext])

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 relavent 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 :py:method:`Config.serialize()`).

Parameters:pycontext (object) – optional
Returns:hash of Config
Return type:string
Config.getSearchPath()

Returns the search path.

Returns:search path
Return type:string
Config.setSearchPath(path)

Sets the search path.

Parameters:path (string) – the search path
Config.getWorkingDir()

Returns the working directory.

Returns:the working directory
Rtype path:string
Config.setWorkingDir()

Sets the working directory.

Parameters:path (string) – the working directory

ColorSpace Methods

Config.getColorSpaces()

Returns all the ColorSpaces defined in Config.

Returns:ColorSpaces in Config
Return type:tuple
Config.getColorSpace(name)

Returns the data for the specified color space in Config.

This will return null if the specified name is not found.

Parameters:name (string) – name of color space
Returns:data for specified color space
Return type:pyColorSpace object
Config.addColorSpace(pyColorSpace)

Add a specified color space to Config.

Parameters:pyColorSpace (object) – color space

Note

If another color space is already registered with the same name, this will overwrite it.

Config.clearColorSpaces()

Clear the color spaces in Config.

Config.parseColorSpaceFromString(str)

Parses out the color space from a string.

Given the specified string, gets the longest, right-most color space substring. * If strict parsing is enabled, and no color space is found, return an empty string. * If strict parsing is disabled, return the default role, if defined. * If the default role is not defined, return an empty string.

Parameters:str (string) – ColorSpace data
Returns:parsed data
Return type:string

Roles Methods

A role acts as an alias for a ColorSpace.

You can query for the ColorSpace corresponding to a role using :py:function:`getColorSpace()`.

Config.setRole(role, csname)

Set a role’s ColorSpace.

Setting the colorSpaceName name to a null string unsets it.

Parameters:
  • role (string) – role whose ColorSpace will be set
  • csname (string) – name of ColorSpace

Display/View Registration Methods

A display is a virtual or physical display device (e.g., DLP projector or sRGB monitor).

A view further specifies what you’re trying to see. I.e., display set to sRGB and view set to film_avid would be asking to see what film_avid on a movie screen would look like on your sRGB monitor.

Config.getDefaultDisplay()

Returns the default display set in Config.

Returns:default display
Return type:string
Config.getDisplays()

Returns all the displays defined in Config.

Returns:displays in Config
Return type:list of strings
Config.getDefaultView(display)

Returns the default view of Config.

Parameters:display (string) – default view
Returns:view
Return type:string
Config.getViews(display)

Returns all the views defined in Config.

Parameters:display (string) – views in Config
Returns:views in Config.
Return type:list of strings
Config.getDisplayColorSpaceName(display, view)

Returns the ColorSpace name corresponding to the display and view combination in Config.

Parameters:
  • display (string) – display
  • view (string) – view
Returns:

display color space name

Return type:

string

Config.getDisplayLooks(display, view)

Returns the looks corresponding to the display and view combination in Config.

Parameters:
  • display (string) – display
  • view (string) – view
Returns:

looks

Return type:

string

Config.addDisplay(display, view, colorSpaceName[, looks])

NEEDS WORK

Parameters:
  • display (string) –
  • view (string) –
  • colorSpaceName (string) –
  • looks (string) – optional
Config.clearDisplays()
Config.setActiveDisplays()

Sets the active displays in Config.

Parameters:displays (string) – active displays
Config.getActiveDisplays()

Returns the active displays in Config.

Returns:active displays
Return type:string
Config.setActiveViews()

Sets the active views in Config.

Parameters:displays (string) – active views
Config.getActiveViews()

Returns the active views in Config.

Returns:active views
Return type:string

Luma Methods

Manage the default coefficients for computing luma.

Note

There is no one-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. Thus, the right answer is to make these functions on the Config class. However, it’s often useful to have a Config-wide default, so here it is. We will add the ColorSpace specific luma call when another client is interested in using it.

Config.setDefaultLumaCoefs()

Sets the default luma coefficients in Config.

Parameters:pyCoef (object) – luma coefficients
Config.getDefaultLumaCoefs()

Returns the default luma coefficients in Config.

Returns:luma coefficients
Return type:list of floats

Look Methods

Manage per-shot look settings.

Looks is a comma- or colon-delimited list of lookNames, where optional ‘+’ and ‘-‘ prefixes denote forward and inverse look specifications, respectively. A forward look is assumed in the absence of a prefix.

Config.getLook()

Returns the information of a specified look in Config.

Parameters:str (string) – look
Returns:specified look
Return type:look object
Config.getLooks()

Returns a list of all the looks defined in Config.

Returns:looks
Return type:tuple of look objects
Config.addLook()

Adds a look to Config.

Parameters:pylook (look object) – look
Config.clearLook()

Clear look in Config.

Processor Methods

Used to convert from inputColorSpace to outputColorSpace.

Config.getProcessor(arg1[, arg2[, direction[, context]])

Returns a processor for a specified transform.

Although this is not often needed, it allows for the reuse of atomic OCIO functionality, such as applying an individual LUT file.

There are two canonical ways of creating a Processor:

  1. Pass a transform into arg1, in which case arg2 will be ignored.
  2. Set arg1 as the source and arg2 as the destination. These can be ColorSpace names, objects, or roles.

Both arguments, direction (of transform) and context, are optional and respected for both methods of Processor creation.

This will fail if either the source or destination color space is null.

See Python: Processor for more details.

Note

This may provide higher fidelity than anticipated due to internal optimizations. For example, if inputColorSpace and outputColorSpace are members of the same family, no conversion will be applied, even though, strictly speaking, quantization should be added.

If you wish to test these calls for quantization characteristics, apply in two steps; the image must contain RGB triples (though arbitrary numbers of additional channels can be optionally supported using the pixelStrideBytes arg). ???

Parameters:
  • arg1 (object) –
  • arg2 (object) – ignored if arg1 is a transform
  • direction (string) – optional
  • context (object) – optional