Applications Helpers

ColorSpaceMenuHelpers

PyOpenColorIO.ColorSpaceHelpers.AddColorSpace(config: PyOpenColorIO.Config, name: str, transformFilePath: str, categories: str = '', connectionColorSpaceName: str) None

Add a new color space to the config instance. The output of the userTransform must be in the specified connectionColorSpace.

Note: If the config does not already use categories, we do not add them since that would make a big change to how existing color spaces show up in menus.

class PyOpenColorIO.ColorSpaceMenuParameters

Parameters controlling which color spaces appear in menus.

The ColorSpaceMenuHelper class is intended to be used by applications to get the list of items to show in color space menus.

The ColorSpaceMenuParameters class is used to configure the behavior as needed for any given menu. Here is the algorithm used to produce a list of “items” (or strings) that will appear in a menu:

  1. Use setRole to identify a role that controls a given menu. If the config has this role, then only that color space is returned. The name is set to the color space name, the UIName is presented as “<role name> (<color space name>)”. It may be useful for the application to then grey-out the menu or otherwise indicate to the user that the value for this menu is not user selectable since it was pre-determined by the config. If the config does not have that role, the algorithm continues to the remaining steps.

2) The IncludeColorSpaces, SearchReferenceSpaceType, and IncludeNamedTransforms parameters are used to identify a set of items from the config that are potential candidates for use in the menu, as follows: - IncludeColorSpaces: Set to true to include color spaces in the menu. - SearchReferenceSpaceType: Use this to control whether the menu should include all color spaces, only display color spaces, or only non-display color spaces. - IncludeNamedTransforms: Set to true to include named transforms in the menu.

3) The set of items from step 2 is then filtered in step 3 using the following parameters: - AppCategories: A list of strings specified by the application based on the purpose of the menu. For example, if the menu is used to select a color space for importing an image, the application might specify the ‘file-io’ category, whereas if it is to select a working color space, it might specify the ‘working-space’ category. Application developers should document what strings they are using for each menu so that config authors know what categories to use in their configs. Alternatively, an application could let advanced users customize the string to use for a given menu in the application. - Encodings: A list of strings used to further refine the items selected from the AppCategories. For example, an application might specify ‘working-space’ as the category and then specify ‘scene-linear’ as the encoding to only use items that have both of those properties (e.g., only select scene-linear working color spaces). - UserCategories: A list of strings specified by the end-user of the application. OCIO will check for these strings in an environment variable, or they may be passed in from the application.

Basically the intent is for the filtering to return the intersection of the app categories, encoding, and user categories. However, some fall-backs are in place to ensure that the filtering does not remove all menu items. Here is the detailed description:

3a) The items from step 2 are filtered to generate a list of appItems containing only the ones that contain at least one of the AppCategories strings in their “categories” property and one of the encodings in their “encoding” property. If this list is empty, an attempt is made to generate a non-empty appItems list by only filtering by AppCategories. If that is empty, an attempt is made to only filter by Encodings.

3b) The items from step 2 are filtered to generate a list of userItems containing only the ones that have at least one of the UserCategories strings in their “categories” property.

3c) If both appItems and userItems are non-empty, a list of resultItems will be generated as the intersection of those two lists.

3d) If the resultItems list is empty, the appList will be expanded by only filtering by AppCategories and not encodings. The resultItems will be formed again as the intersection of the appItems and userItems.

3e) If the resultItems is still empty, it will be set to just the appItems from step 3a.

3f) If the resultItems is still empty, it will be set to just the userItems.

3g) If the resultItems is still empty, the items are not filtered and all items from step 2 are returned. The rationale is that if step 2 has produced any items, it is not acceptable for step 3 to remove all of them. An application usually expects to have a non-zero number of items to display in the menu. However, if step 2 produces no items (e.g. the application requests only named transforms and the config has no named transform), then no items will be returned.

  1. If IncludeRoles is true, the items from step 3 are extended by including an item for each role. The name is set to the role name, the UIName is presented as “<role name> (<color

    space name>)”, and the family is set to “Roles”.

  2. If AddColorSpace has been used to add any additional items, these are appended to the final list.

ColorSpaceMenuParameters(*args, **kwargs)

Overloaded function.

  1. __init__(self: PyOpenColorIO.ColorSpaceMenuParameters, config: PyOpenColorIO.Config) -> None

  2. __init__(self: PyOpenColorIO.ColorSpaceMenuParameters, config: PyOpenColorIO.Config, role: str = ‘’, includeColorSpaces: bool = True, searchReferenceSpaceType: PyOpenColorIO.SearchReferenceSpaceType = <SearchReferenceSpaceType.SEARCH_REFERENCE_SPACE_ALL: 2>, includeNamedTransforms: bool = False, appCategories: str = ‘’, encodings: str = ‘’, userCategories: str = ‘’, includeRoles: bool = False) -> None

addColorSpace(colorSpace: str) None

Add an additional color space (or named transform) to the menu.

Note that an additional color space could be: - an inactive color space, - an active color space not having at least one of the selected categories, - a newly created color space. Will throw when creating the menu if color space is not part of the config. Nothing is done if it is already part of the menu. It’s ok to call this multiple times with the same color space, it will only be added to the menu once. If a role name is passed in, the name in the menu will be the color space name the role points to.

clearAddedColorSpaces() None
getAddedColorSpaces() PyOpenColorIO.ColorSpaceMenuParameters.AddedColorSpaceIterator
getAppCategories() str
getConfig() PyOpenColorIO.Config
getEncodings() str
getIncludeColorSpaces() bool
getIncludeNamedTransforms() bool
getIncludeRoles() bool
getRole() str
getSearchReferenceSpaceType() PyOpenColorIO.SearchReferenceSpaceType

Can be used to restrict the search using the ReferenceSpaceType of the color spaces. It has no effect on roles and named transforms.

getUserCategories() str
setAppCategories(appCategories: str) None

App categories is a comma separated list of categories. If appCategories is not NULL and not empty, all color spaces that have one of the categories will be part of the menu.

setConfig(config: PyOpenColorIO.Config) None

Config is required to be able to create a ColorSpaceMenuHelper.

setEncodings(encodings: str) None

Encodings is a comma separated list of encodings. When not empty, is retricting the search to color spaces that are using one of the encodings.

setIncludeColorSpaces(includeColorSpaces: bool = True) None

Include all color spaces (or not) to ColorSpaceMenuHelper. Default is to include color spaces.

setIncludeNamedTransforms(includeNamedTransforms: bool = True) None

Include all named transforms (or not) to ColorSpaceMenuHelper. Default is not to include named transforms.

setIncludeRoles(includeRoles: bool = True) None

Include all roles (or not) to ColorSpaceMenuHelper. Default is not to include roles. Roles are added after color spaces with an single hierarchy level named “Roles”.

setRole(role: str) None

If role is a valid role, other parameters are ignored and menu will contain only that role.

setSearchReferenceSpaceType(searchReferenceSpaceType: PyOpenColorIO.SearchReferenceSpaceType) None
setUserCategories(categories: str) None

User categories is a comma separated list of categories. If OCIO_USER_CATEGORIES_ENVVAR env. variable is defined and not empty, this parameter is ignored and the value of the env. variable is used for user categories.

class PyOpenColorIO.ColorSpaceMenuHelper

Helper class to create menus for the content of a config.

Menu can list color spaces, roles, named transforms. Each entry has a name, a UI name, a description, and a family. Family can also be accessed as hierarchy levels; levels are created by splitting the family using the ‘family separator’. Hierarchy levels are meant to be used as sub-menus.

The UI name is what is intended to be put in application menus seen by the end-user. However, please note that the UI name is not guaranteed to remain stable between releases and so if applications need to save something it should be the ‘name’ rather than the ‘UI name’. Currently, the only difference between the ‘name’ and ‘UI name’ is for roles.

The overall ordering of items is: color spaces, named transforms, roles, and additional color spaces. The display color spaces will either come before or after the other color spaces based on where that block of spaces appears in the config. The order of items returned by the menu helper preserves the order of items in the config itself for each type of elements, thus preserving the intent of the config author. For example, if you call getName at idx and idx+1, the name returned at idx+1 will be from farther down in the config than the one at idx as long as both are of the same type. (An application may ask for only the items in one of those blocks if it wants to handle them separately.) If the application makes use of hierarchical menus, that will obviously impose a different order on what the user sees in the menu. Though even with hierarchical menus, applications should try to preserve config ordering (which is equivalent to index ordering) for items within the same sub-menu.

ColorSpaceMenuHelper(parameters: PyOpenColorIO.ColorSpaceMenuParameters) None
getDescription(index: int) str
getFamily(index: int) str
getHierarchyLevels(index: int) PyOpenColorIO.ColorSpaceMenuHelper.ColorSpaceLevelIterator
getIndexFromName(name: str) int

Get the index of the element of a given name. Return (size_t)-1 name if NULL or empty, or if no element with that name is found.

getIndexFromUIName(name: str) int
getName(index: int) str

Get the color space (or role) name used in the config for this menu item. Will be empty if the index is out of range.

getNameFromUIName(name: str) str

Get the color space name from the UI name.

getNumColorSpaces() int

Access to the color spaces (or roles).

getUIName(index: int) str

Get the name to use in the menu UI. This might be different from the config name, for example in the case of roles. Will be empty if the index is out of range.

getUINameFromName(name: str) str

Get the color space UI name from the name.

class PyOpenColorIO.ColorSpaceMenuHelper.ColorSpaceLevelIterator
self[arg0: int] str
iter(self) PyOpenColorIO.ColorSpaceMenuHelper.ColorSpaceLevelIterator
len(self) int
next(self) str

DisplayViewHelpers

PyOpenColorIO.DisplayViewHelpers.GetProcessor(config: PyOpenColorIO.Config, context: PyOpenColorIO.Context = None, workingSpaceName: str, displayName: str, viewName: str, channelView: PyOpenColorIO.MatrixTransform = None, direction: PyOpenColorIO.TransformDirection = <TransformDirection.TRANSFORM_DIR_FORWARD: 0>) PyOpenColorIO.Processor

Get the processor from the working color space to (display, view) pair (forward) or (display, view) pair to working (inverse). The working color space name could be a role name or a color space name. ChannelView can be empty. If not already present, each of these functions adds ExposureContrastTransforms to enable changing exposure, contrast, and gamma after the processor has been created using dynamic properties.

PyOpenColorIO.DisplayViewHelpers.GetIdentityProcessor(config: PyOpenColorIO.Config) PyOpenColorIO.Processor

Get an identity processor containing only the ExposureContrastTransforms.

PyOpenColorIO.DisplayViewHelpers.AddDisplayView(config: PyOpenColorIO.Config, displayName: str, viewName: str, lookName: str = '', colorSpaceName: str = '', colorSpaceFamily: str = '', colorSpaceDescription: str = '', colorSpaceCategories: str = '', transformFilePath: str, connectionColorSpaceName: str) None

Add a new (display, view) pair and the new color space to a configuration instance. The input to the userTransform must be in the specified connectionColorSpace.

PyOpenColorIO.DisplayViewHelpers.RemoveDisplayView(config: PyOpenColorIO.Config, displayName: str, viewName: str) None

Remove a (display, view) pair including the associated color space (only if not used). Note that the view is always removed but the display is only removed if empty.

LegacyViewingPipeline

class PyOpenColorIO.LegacyViewingPipeline

Whereas the DisplayViewTransform simply applies a specific view from an OCIO display, the LegacyViewingPipeline provides an example of a complete viewing pipeline of the sort that could be used to implement a viewport in a typical application. It therefore adds, around the DisplayViewTransform, various optional color correction steps and RGBA channel view swizzling. The direction of the DisplayViewTranform is used as the direction of the pipeline. Note: The LegacyViewingPipeline class provides the same functionality as the OCIO v1 DisplayTransform.

Legacy viewing pipeline: - Start in display transform input color space. - If linearCC is provided: - Go to scene_linear colorspace. - Apply linearCC transform.

  • If colorTimingCC is provided:

  • Go to color_timing colorspace.

  • Apply colorTimingCC transform.

  • Apply looks (from display transform or from looks override).

  • Go to first look color space.

  • Apply first look transform.

  • Iterate for all looks.

  • Apply channelView transform.

  • Apply display transform (without looks).

  • Apply displayCC. Note that looks are applied even if the display transform involves data color spaces.

LegacyViewingPipeline() None
getChannelView() PyOpenColorIO.Transform
getColorTimingCC() PyOpenColorIO.Transform
getDisplayCC() PyOpenColorIO.Transform
getDisplayViewTransform() PyOpenColorIO.DisplayViewTransform
getLinearCC() PyOpenColorIO.Transform
getLooksOverride() str
getLooksOverrideEnabled() bool
getProcessor(config: PyOpenColorIO.Config, context: PyOpenColorIO.Context = None) PyOpenColorIO.Processor
setChannelView(arg0: PyOpenColorIO.Transform) None
setColorTimingCC(arg0: PyOpenColorIO.Transform) None
setDisplayCC(arg0: PyOpenColorIO.Transform) None
setDisplayViewTransform(arg0: PyOpenColorIO.DisplayViewTransform) None
setLinearCC(arg0: PyOpenColorIO.Transform) None
setLooksOverride(looks: str) None

A user can optionally override the looks that are, by default, used with the expected display / view combination. A common use case for this functionality is in an image viewing app, where per-shot looks are supported. If for some reason a per-shot look is not defined for the current Context, the Config::getProcessor fcn will not succeed by default. Thus, with this mechanism the viewing app could override to looks = “”, and this will allow image display to continue (though hopefully) the interface would reflect this fallback option.

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

setLooksOverrideEnabled(arg0: bool) None

Specify whether the lookOverride should be used, or not. This is a separate flag, as it’s often useful to override “looks” to an empty string.

MixingHelpers

class PyOpenColorIO.MixingSlider

The MixingSlider and MixingColorSpaceManager classes are to help applications implement correct color pickers. The term “color mixing” is used here to describe what is done in a typical application “color picker” user interface.

A user may want to mix colors in different color spaces. The two most common mixing space options are a scene-linear working space or the display space.

Since scene-linear color spaces are not perceptually uniform, it is necessary to compensate UI widgets such as sliders. For example, it is nice if mid-gray falls near the center of mixing controls rather than way over near the black end. This may be done by using a mapping from linear into an approximately perceptually uniform space.

Also note that a color picking/mixing UI may want to present a given color space in several different encodings. The most common two encodings for color mixing are RGB and HSV.

Note that these helpers anticipate that a user may want to mix colors using values that extend outside the typical [0,1] domain.

MixingSlider(*args, **kwargs)
getSliderMaxEdge() float

Maximum edge of a UI slider for conversion to mixing space.

getSliderMinEdge() float

Minimum edge of a UI slider for conversion to mixing space.

mixingToSlider(mixingUnits: float) float

Convert from mixing space units to distance along the slider.

setSliderMaxEdge(arg0: float) None

Set the maximum edge of a UI slider for conversion to mixing space.

setSliderMinEdge(arg0: float) None

Set the minimum edge of a UI slider for conversion to mixing space.

sliderToMixing(sliderUnits: float) float

Convert from units in distance along the slider to mixing space units.

class PyOpenColorIO.MixingColorSpaceManager

Used to mix (or pick/choose) colors.

MixingColorSpaceManager(config: PyOpenColorIO.Config) None
getMixingEncodings() PyOpenColorIO.MixingColorSpaceManager.MixingEncodingIterator
getMixingSpaces() PyOpenColorIO.MixingColorSpaceManager.MixingSpaceIterator
getProcessor(workingSpaceName: str, displayName: str, viewName: str, direction: PyOpenColorIO.TransformDirection = <TransformDirection.TRANSFORM_DIR_FORWARD: 0>) PyOpenColorIO.Processor
getSelectedMixingEncodingIdx() int
getSelectedMixingSpaceIdx() int
getSlider(*args, **kwargs)

Overloaded function.

  1. getSlider(self: PyOpenColorIO.MixingColorSpaceManager) -> PyOpenColorIO.MixingSlider

  2. getSlider(self: PyOpenColorIO.MixingColorSpaceManager, sliderMixingMinEdge: float, sliderMixingMaxEdge: float) -> PyOpenColorIO.MixingSlider

isPerceptuallyUniform() bool
refresh(config: PyOpenColorIO.Config) None

Refresh the instance (i.e. needed following a configuration change for example).

setSelectedMixingEncoding(mixingEncoding: str) None
setSelectedMixingEncodingIdx(arg0: int) None
setSelectedMixingSpace(mixingSpace: str) None
setSelectedMixingSpaceIdx(arg0: int) None
class PyOpenColorIO.MixingColorSpaceManager.MixingSpaceIterator
self[arg0: int] str
iter(self) PyOpenColorIO.MixingColorSpaceManager.MixingSpaceIterator
len(self) int
next(self) str
class PyOpenColorIO.MixingColorSpaceManager.MixingEncodingIterator
self[arg0: int] str
iter(self) PyOpenColorIO.MixingColorSpaceManager.MixingEncodingIterator
len(self) int
next(self) str