# OpenColorIO

## Open Source Color Management

# Python API

## 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 `PyOpenColorIO.ColorSpaceTransform` and `PyOpenColorIO.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

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

## Exceptions

class `PyOpenColorIO.``Exception`

class `PyOpenColorIO.``ExceptionMissingFile`

## Global

`PyOpenColorIO.``ClearAllCaches`()

`PyOpenColorIO.``GetCurrentConfig`()

`PyOpenColorIO.``GetLoggingLevel`()

`PyOpenColorIO.``SetCurrentConfig`()

`PyOpenColorIO.``SetLoggingLevel`()

## Config

class `PyOpenColorIO.``Config`

  Config

  static `CreateFromEnv`()

    CreateFromEnv()

    Create a `PyOpenColorIO.Config` object using the environment variable.

    Returns: | Config object

  static `CreateFromFile`()

    CreateFromFile(filename)

    Create a `PyOpenColorIO.Config` object using the information in a file.

    Parameters:

    - filename (string) – name of file

    Returns: | Config object

  `addColorSpace`

    addColorSpace(pyColorSpace)

    Add a specified color space to `PyOpenColorIO.Config`.

    Parameters:

    - pyColorSpace (object) – color space

    Note

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

  `addDisplay`

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

    NEEDS WORK

    Parameters:

    - display (string) –
    - view (string) –
    - colorSpaceName (string) –
    - looks (string) – optional

  `addLook`

    addLook(pylook)

    Adds a look to `PyOpenColorIO.Config`.

    Parameters:

    - pylook (look object) – look

  `clearColorSpaces`

    clearColorSpaces()

    Clear the color spaces in `PyOpenColorIO.Config`.

  `clearDisplays`

    clearDisplays()

  `clearLook`

    clearLooks()

    Clear looks in `PyOpenColorIO.Config`.

  `clearLooks`

    clearLooks()

    Clear looks in `PyOpenColorIO.Config`.

  `createEditableCopy`

    createEditableCopy()

    Returns an editable copy of `PyOpenColorIO.Config`.

    Returns: | editable copy of `PyOpenColorIO.Config`
    Return type: | Config object

  `getActiveDisplays`

    getActiveDisplays()

    Returns the active displays in `PyOpenColorIO.Config`.

    Returns: | active displays
    Return type: | string

  `getActiveViews`

    getActiveViews()

    Returns the active views in `PyOpenColorIO.Config`.

    Returns: | active views
    Return type: | string

  `getCacheID`

    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 `PyOpenColorIO.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:`PyOpenColorIO.Config.serialize`).

    Parameters:

    - pycontext (object) – optional

    Returns: | hash of `PyOpenColorIO.Config`
    Return type: | string

  `getColorSpace`

    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

  `getColorSpaces`

    getColorSpaces()

    Returns all the ColorSpaces defined in `Config`.

    Returns: | ColorSpaces in `PyOpenColorIO.Config`
    Return type: | tuple

  `getCurrentContext`

    getCurrentContext()

    Return the current context, which is essentially a record of all the environment variables that are available for use in file path lookups.

    Returns: | context
    Return type: | pycontext

  `getDefaultDisplay`

    getDefaultDisplay()

    Returns the default display set in `PyOpenColorIO.Config`.

    Returns: | default display
    Return type: | string

  `getDefaultLumaCoefs`

    getDefaultLumaCoefs()

    Returns the default luma coefficients in `PyOpenColorIO.Config`.

    Returns: | luma coefficients
    Return type: | list of floats

  `getDefaultView`

    getDefaultView(display)

    Returns the default view of `PyOpenColorIO.Config`.

    Parameters:

    - display (string) – default view

    Returns: | view
    Return type: | string

  `getDescription`

    getDescription()

    Returns the stored description of `PyOpenColorIO.Config`.

    Returns: | stored description of `PyOpenColorIO.Config`
    Return type: | string

  `getDisplayColorSpaceName`

    getDisplayColorSpaceName(display, view)

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

    Parameters:

    - display (string) – display
    - view (string) – view

    Returns: | display color space name
    Return type: | string

  `getDisplayLooks`

    getDisplayLooks(display, view)

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

    Parameters:

    - display (string) – display
    - view (string) – view

    Returns: | looks
    Return type: | string

  `getDisplays`

    getDisplays()

    Returns all the displays defined in `PyOpenColorIO.Config`.

    Returns: | displays in `Config`
    Return type: | list of strings

  `getLook`

    getLook(str)

    Returns the information of a specified look in `PyOpenColorIO.Config`.

    Parameters:

    - str (string) – look

    Returns: | specified look
    Return type: | look object

  `getLooks`

    getLooks()

    Returns a list of all the looks defined in `PyOpenColorIO.Config`.

    Returns: | looks
    Return type: | tuple of look objects

  `getProcessor`

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

  `getSearchPath`

    getSearchPath()

    Returns the search path.

    Returns: | search path
    Return type: | string

  `getViews`

    getViews(display)

    Returns all the views defined in `PyOpenColorIO.Config`.

    Parameters:

    - display (string) – views in `Config`

    Returns: | views in `Config`.
    Return type: | list of strings

  `getWorkingDir`

    getWorkingDir()

    Returns the working directory.

    Returns: | the working directory
    Rtype path: | string

  `isEditable`

    isEditable()

    Returns whether Config is editable.

    The configurations returned from :py:function:`PyOpenColorIO.GetCurrentConfig` are not editable, and if you want to edit them you can use :py:method:`PyOpenColorIO.Config.createEditableCopy`.

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

    Returns: | state of `PyOpenColorIO.Config`‘s editability
    Return type: | bool

  `parseColorSpaceFromString`

    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

  `sanityCheck`

    sanityCheck()

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

  `serialize`

    serialize()

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

    Returns: | `PyOpenColorIO.Config` in YAML text form
    Return type: | string

  `setActiveDisplays`

    setActiveDisplays(displays)

    Sets the active displays in `PyOpenColorIO.Config`.

    Parameters:

    - displays (string) – active displays

  `setActiveViews`

    setActiveViews(views)

    Sets the active views in `PyOpenColorIO.Config`.

    Parameters:

    - views (string) – active views

  `setDefaultLumaCoefs`

    setDefaultLumaCoefs(pyCoef)

    Sets the default luma coefficients in `PyOpenColorIO.Config`.

    Parameters:

    - pyCoef (object) – luma coefficients

  `setDescription`

    setDescription(desc)

    Sets the description of `PyOpenColorIO.Config`.

    Parameters:

    - desc (string) – description of `PyOpenColorIO.Config`

  `setRole`

    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

  `setSearchPath`

    setSearchPath(path)

    Sets the search path.

    Parameters:

    - path (string) – the search path

  `setWorkingDir`

    setWorkingDir(path)

    Sets the working directory.

    Parameters:

    - path (string) – the working directory

## ColorSpace

class `PyOpenColorIO.``ColorSpace`

  A color space is the state of an image in terms of colorimetry and color encoding. I.e., it defines how an image’s color information needs to be interpreted.

  Transforming images between different color spaces is the primary motivation for the OCIO library.

  While a complete discussion of color spaces is beyond the scope of this documentation, traditional uses would be to have color spaces describing image capture devices, such as cameras and scanners, and internal ‘convenience’ spaces, such as scene-linear and logarithmic.

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

      import PyOpenColorIO as OCIO
      config = OCIO.Config()

  `createEditableCopy`
  `getAllocation`

    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`
  `getBitDepth`
  `getDescription`
  `getEqualityGroup`
  `getFamily`
  `getName`
  `getTransform`
  `isData`

    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). Also, the `PyOpenColorIO.DisplayTransform` process obeys special ‘data min’ and ‘data max’ args.

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

  `isEditable`
  `setAllocation`
  `setAllocationVars`
  `setBitDepth`
  `setDescription`
  `setEqualityGroup`
  `setFamily`
  `setIsData`
  `setName`
  `setTransform`

## Look

class `PyOpenColorIO.``Look`

  The Look is an ‘artistic’ image modification, in a specified image state.

  The processSpace defines the ColorSpace the image is required to be in, for the math to apply correctly.

  `createEditableCopy`
  `getName`
  `getProcessSpace`
  `getTransform`
  `isEditable`
  `setName`
  `setProcessSpace`
  `setTransform`

## Processor

class `PyOpenColorIO.``Processor`

  Processor is the baked representation of a particular color transform. Once you have a process for a particular transform created, you can hang onto it to efficiently transform pixels.

  Processors can only be created from the PyOpenColorIO.Config getProcessor(...) call.

  `applyRGB`

    applyRGB(pixeldata)

    Apply the RGB part of the transform represented by `PyOpenColorIO.Processor` to an image.

    Parameters:

    - pixeldata (object) – rgbrgb... array (length % 3 == 0)

    Returns: | color converted pixeldata
    Return type: | list

  `applyRGBA`

    applyRGBA(pixeldata)

    Apply the RGB and alpha part of the transform represented by `PyOpenColorIO.Processor` to an image.

    Parameters:

    - pixeldata (object) – rgbargba... array (length % 4 == 0)

    Returns: | color converted pixeldata
    Return type: | list

  `getCpuCacheID`

    getCpuCacheID()

    Returns the cache ID of the CPU that `PyOpenColorIO.Processor` will run on.

    Returns: | CPU cache ID
    Return type: | string

  `getGpuLut3D`

    getGpuLut3D(shaderDesc)

    Returns the GPU LUT 3D.

    Parameters:

    - shaderDesc (dict) – define ‘language’,’functionName’,’lut3DEdgeLen’

    Returns: | GPU LUT 3D
    Return type: | list

  `getGpuLut3DCacheID`

    getGpuLut3DCacheID(shaderDesc)

    Returns the GPU 3D LUT cache ID.

    Parameters:

    - shaderDesc (dict) – two params

    Returns: | GPU 3D LUT cache ID
    Return type: | string

  `getGpuShaderText`

    getGpuShaderText(shaderDesc)

    Returns the GPU shader text.

    Parameters:

    - shaderDesc (dict) – define ‘language’,’functionName’,’lut3DEdgeLen’

    Returns: | GPU shader text
    Return type: | string

  `getGpuShaderTextCacheID`

    getGpuShaderTextCacheID(shaderDesc)

    Returns the GPU shader text cache ID.

    Parameters:

    - shaderDesc (dict) – define ‘language’,’functionName’,’lut3DEdgeLen’

    Returns: | GPU shader text cache ID
    Return type: | string

  `getMetadata`

    getMetadata()

    Returns information about the process that generated this processor.

    Returns: | processor metadata
    Return type: | PyOpenColorIO.ProcessorMetadata

  `hasChannelCrosstalk`

    hasChannelCrosstalk()

    Returns whether the transformation of `PyOpenColorIO.Processor` introduces crosstalk between the image channels.

    Returns: | whether there’s crosstalk between channels
    Return type: | bool

  `isNoOp`

    isNoOp()

    Returns whether the actual transformation represented by `PyOpenColorIO.Processor` is a no-op.

    Returns: | whether transform is a no-op
    Return type: | bool

## Context

class `PyOpenColorIO.``Context`

  Context

  `createEditableCopy`
  `getCacheID`
  `getSearchPath`
  `getStringVar`
  `getWorkingDir`
  `isEditable`
  `loadEnvironment`
  `resolveFileLocation`
  `resolveStringVar`
  `setSearchPath`
  `setStringVar`
  `setWorkingDir`