|
Python API
Description
A color configuration (PyOpenColorIO.Config ) defines all the color spaces to be
available at runtime.
(PyOpenColorIO.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.
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
An exception class to throw for errors detected at runtime.
Warning
All functions in the Config class can potentially throw this exception.
-
class
PyOpenColorIO. ExceptionMissingFile
An exception class for errors detected at runtime, thrown when OCIO cannot
find a file that is expected to exist. This is provided as a custom type to
distinguish cases where one wants to continue looking for missing files,
but wants to properly fail for other error conditions.
Global
-
PyOpenColorIO. ClearAllCaches ()
-
PyOpenColorIO. GetCurrentConfig ()
-
PyOpenColorIO. GetLoggingLevel ()
-
PyOpenColorIO. SetCurrentConfig ()
-
PyOpenColorIO. SetLoggingLevel ()
Config
-
class
PyOpenColorIO. Config
-
CreateFromEnv ()
Create a PyOpenColorIO.Config object using the environment variable.
- Returns
Config object
-
CreateFromFile (filename)
Create a PyOpenColorIO.Config object using the information in a file.
- Parameters
filename (string) – name of file
- Returns
Config object
-
CreateFromStream ()
-
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 (display, view, colorSpaceName[, looks])
NEEDS WORK
- Parameters
-
-
addEnvironmentVar ()
-
addLook (pylook)
Adds a look to PyOpenColorIO.Config .
- Parameters
pylook (look object) – look
-
clearColorSpaces ()
Clear the color spaces in PyOpenColorIO.Config .
-
clearDisplays ()
-
clearEnvironmentVars ()
-
clearLook ()
clearLooks()
Clear looks in PyOpenColorIO.Config .
-
clearLooks ()
Clear looks in PyOpenColorIO.Config .
-
createEditableCopy ()
Returns an editable copy of PyOpenColorIO.Config .
- Returns
editable copy of PyOpenColorIO.Config
- Return type
Config object
-
getActiveDisplays ()
Returns the active displays in PyOpenColorIO.Config .
- Returns
active displays
- Return type
string
-
getActiveViews ()
Returns the active views in PyOpenColorIO.Config .
- Returns
active views
- Return type
string
-
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 PyOpenColorIO.Config.serialize() ).
- Parameters
pycontext (object) – optional
- Returns
hash of PyOpenColorIO.Config
- Return type
string
-
getColorSpace (name)
Returns the data for the specified color space in PyOpenColorIO.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
-
getColorSpaceNameByIndex ()
-
getColorSpaces ()
Returns all the ColorSpaces defined in PyOpenColorIO.Config .
- Returns
ColorSpaces in PyOpenColorIO.Config
- Return type
tuple
-
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 ()
Returns the default display set in PyOpenColorIO.Config .
- Returns
default display
- Return type
string
-
getDefaultLumaCoefs ()
Returns the default luma coefficients in PyOpenColorIO.Config .
- Returns
luma coefficients
- Return type
list of floats
-
getDefaultView (display)
Returns the default view of PyOpenColorIO.Config .
- Parameters
display (string) – default view
- Returns
view
- Return type
string
-
getDescription ()
Returns the stored description of PyOpenColorIO.Config .
- Returns
stored description of PyOpenColorIO.Config
- Return type
string
-
getDisplay ()
-
getDisplayColorSpaceName (display, view)
Returns the ColorSpace name corresponding to the display and view
combination in PyOpenColorIO.Config .
- Parameters
-
- Returns
display color space name
- Return type
string
-
getDisplayLooks (display, view)
Returns the looks corresponding to the display and view combination in
PyOpenColorIO.Config .
- Parameters
-
- Returns
looks
- Return type
string
-
getDisplays ()
Returns all the displays defined in PyOpenColorIO.Config .
- Returns
displays in PyOpenColorIO.Config
- Return type
list of strings
-
getEnvironmentVarDefault ()
-
getEnvironmentVarDefaults ()
-
getEnvironmentVarNameByIndex ()
-
getIndexForColorSpace ()
-
getLook (str)
Returns the information of a specified look in
PyOpenColorIO.Config .
- Parameters
str (string) – look
- Returns
specified look
- Return type
look object
-
getLookNameByIndex ()
-
getLooks ()
Returns a list of all the looks defined in
PyOpenColorIO.Config .
- Returns
looks
- Return type
tuple of look objects
-
getNumColorSpaces ()
-
getNumDisplays ()
-
getNumEnvironmentVars ()
-
getNumLooks ()
-
getNumRoles ()
-
getNumViews ()
-
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 :
Pass a transform into arg1, in which case arg2 will be ignored.
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
-
getRoleName ()
-
getSearchPath ()
Returns the search path.
- Returns
search path
- Return type
string
-
getView ()
-
getViews (display)
Returns all the views defined in PyOpenColorIO.Config .
- Parameters
display (string) – views in PyOpenColorIO.Config
- Returns
views in PyOpenColorIO.Config .
- Return type
list of strings
-
getWorkingDir ()
Returns the working directory.
- Returns
the working directory
- Rtype path
string
-
hasRole ()
-
isEditable ()
Returns whether Config is editable.
The configurations returned from
PyOpenColorIO.GetCurrentConfig() are not editable, and if
you want to edit them you can use
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
-
isStrictParsingEnabled ()
-
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 ()
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 ()
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 (displays)
Sets the active displays in PyOpenColorIO.Config .
- Parameters
displays (string) – active displays
-
setActiveViews (views)
Sets the active views in PyOpenColorIO.Config .
- Parameters
views (string) – active views
-
setDefaultLumaCoefs (pyCoef)
Sets the default luma coefficients in PyOpenColorIO.Config .
- Parameters
pyCoef (object) – luma coefficients
-
setDescription (desc)
Sets the description of PyOpenColorIO.Config .
- Parameters
desc (string) – description of PyOpenColorIO.Config
-
setRole (role, csname)
Set a role’s ColorSpace.
Setting the colorSpaceName name to a null string unsets it.
- Parameters
-
-
setSearchPath (path)
Sets the search path.
- Parameters
path (string) – the search path
-
setStrictParsingEnabled ()
-
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 ()
-
getDescription ()
-
getInverseTransform ()
-
getName ()
-
getProcessSpace ()
-
getTransform ()
-
isEditable ()
-
setDescription ()
-
setInverseTransform ()
-
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 (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 (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 ()
Returns the cache ID of the CPU that PyOpenColorIO.Processor
will run on.
- Returns
CPU cache ID
- Return type
string
-
getGpuLut3D (shaderDesc)
Returns the GPU LUT 3D.
- Parameters
shaderDesc (dict) – define ‘language’,’functionName’,’lut3DEdgeLen’
- Returns
GPU LUT 3D
- Return type
list
-
getGpuLut3DCacheID (shaderDesc)
Returns the GPU 3D LUT cache ID.
- Parameters
shaderDesc (dict) – two params
- Returns
GPU 3D LUT cache ID
- Return type
string
-
getGpuShaderText (shaderDesc)
Returns the GPU shader text.
- Parameters
shaderDesc (dict) – define ‘language’,’functionName’,’lut3DEdgeLen’
- Returns
GPU shader text
- Return type
string
-
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 ()
Returns information about the process that generated this processor.
- Returns
processor metadata
- Return type
PyOpenColorIO.ProcessorMetadata
-
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 ()
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
-
clearStringVars ()
-
createEditableCopy ()
-
getCacheID ()
-
getEnvironmentMode ()
-
getNumStringVars ()
-
getSearchPath ()
-
getStringVar ()
-
getStringVarNameByIndex ()
-
getWorkingDir ()
-
isEditable ()
-
loadEnvironment ()
-
resolveFileLocation ()
-
resolveStringVar ()
-
setEnvironmentMode ()
-
setSearchPath ()
-
setStringVar ()
-
setWorkingDir ()
|