|
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.
-
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
-
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:
- 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 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
|
|