Rules¶

FileRules¶

class PyOpenColorIO.FileRules¶

The File Rules are a set of filepath to color space mappings that are evaluated from first to last. The first rule to match is what determines which color space is returned. There are four types of rules available. Each rule type has a name key that may be used by applications to refer to that rule. Name values must be unique i.e. using a case insensitive comparison. The other keys depend on the rule type:

Basic Rule: This is the basic rule type that uses Unix glob style pattern matching and is thus very easy to use. It contains the keys:
name: Name of the rule
colorspace: Color space name to be returned.
pattern: Glob pattern to be used for the main part of the name/path.
extension: Glob pattern to be used for the file extension. Note that if glob tokens are not used, the extension will be used in a non-case-sensitive way by default.
Regex Rule: This is similar to the basic rule but allows additional capabilities for power-users. It contains the keys:
name: Name of the rule
colorspace: Color space name to be returned.
regex: Regular expression to be evaluated.
OCIO v1 style Rule: This rule allows the use of the OCIO v1 style, where the string is searched for color space names from the config. This rule may occur 0 or 1 times in the list. The position in the list prioritizes it with respect to the other rules. StrictParsing is not used. If no color space is found in the path, the rule will not match and the next rule will be considered. see insertPathSearchRule. It has the key:
name: Must be “ColorSpaceNamePathSearch”.
Default Rule: The file_rules must always end with this rule. If no prior rules match, this rule specifies the color space applications will use. see setDefaultRuleColorSpace. It has the keys:
name: must be “Default”.
colorspace : Color space name to be returned.

Custom string keys and associated string values may be used to convey app or workflow-specific information, e.g. whether the color space should be left as is or converted into a working space.

Getters and setters are using the rule position, they will throw if the position is not valid. If the rule at the specified position does not implement the requested property getter will return NULL and setter will throw.

When loading a v1 config, a set of FileRules are created with ColorSpaceNamePathSearch followed by the Default rule pointing to the default role. This allows getColorSpaceFromFilepath to emulate OCIO v1 code that used parseColorSpaceFromString with strictparsing set to false.

FileRules() → None¶: Creates FileRules for a Config. File rules will contain the default rule using the default role. The default rule cannot be removed.

decreaseRulePriority(ruleIndex: int) → None¶: Move a rule closer to the end of the list by one position.

getColorSpace(ruleIndex: int) → str¶: Set the rule’s color space (may also be a role).

getCustomKeyName(ruleIndex: int, key: int) → str¶: Get name of key.

getCustomKeyValue(ruleIndex: int, key: int) → str¶: Get value for the key.

getExtension(ruleIndex: int) → str¶: Setting extension will erase regex.

getIndexForRule(ruleName: str) → int¶: Get the index from the rule name.

getName(ruleIndex: int) → str¶: Get name of the rule.

getNumCustomKeys(ruleIndex: int) → int¶: Get number of key/value pairs.

getNumEntries() → int¶: Does include default rule. Result will be at least 1.

getPattern(ruleIndex: int) → str¶: Setting pattern will erase regex.

getRegex(ruleIndex: int) → str¶: Setting a regex will erase pattern & extension.

increaseRulePriority(ruleIndex: int) → None¶: Move a rule closer to the start of the list by one position.

insertPathSearchRule(ruleIndex: int) → None¶

Helper function to insert a rule.

Uses Config:parseColorSpaceFromString to search the path for any of the color spaces named in the config (as per OCIO v1).

insertRule(*args, **kwargs)¶

Overloaded function.

insertRule(self: PyOpenColorIO.FileRules, ruleIndex: int, name: str, colorSpace: str, pattern: str, extension: str) -> None

Insert a rule at a given ruleIndex.

Rule currently at ruleIndex will be pushed to index: ruleIndex + 1. Name must be unique. - “Default” is a reserved name for the default rule. The default rule is automatically added and can’t be removed. (see FileRules::setDefaultRuleColorSpace ). - “ColorSpaceNamePathSearch” is also a reserved name (see FileRules::insertPathSearchRule ).

Will throw if pattern, extension or regex is a null or empty string.

Will throw if ruleIndex is not less than FileRules::getNumEntries .

insertRule(self: PyOpenColorIO.FileRules, ruleIndex: int, name: str, colorSpace: str, regex: str) -> None

isDefault() → bool¶: Check if there is only the default rule using default role and no custom key. This is the default FileRules state when creating a new config.

removeRule(ruleIndex: int) → None¶: Note

Default rule can’t be removed. Will throw if ruleIndex + 1 is not less than FileRules::getNumEntries .

setColorSpace(ruleIndex: int, colorSpace: str) → None¶

setCustomKey(ruleIndex: int, key: str, value: str) → None¶: Adds a key/value or replace value if key exists. Setting a NULL or an empty value will erase the key.

setDefaultRuleColorSpace(colorSpace: str) → None¶: Helper function to set the color space for the default rule.

setExtension(ruleIndex: int, extension: str) → None¶

setPattern(ruleIndex: int, pattern: str) → None¶

setRegex(ruleIndex: int, regex: str) → None¶

class FileRules¶

Basic Rule: This is the basic rule type that uses Unix glob style pattern matching and is thus very easy to use. It contains the keys:
- name: Name of the rule
- colorspace: Color space name to be returned.
- pattern: Glob pattern to be used for the main part of the name/path.
- extension: Glob pattern to be used for the file extension. Note that if glob tokens are not used, the extension will be used in a non-case-sensitive way by default.
Regex Rule: This is similar to the basic rule but allows additional capabilities for power-users. It contains the keys:
- name: Name of the rule
- colorspace: Color space name to be returned.
- regex: Regular expression to be evaluated.
OCIO v1 style Rule: This rule allows the use of the OCIO v1 style, where the string is searched for color space names from the config. This rule may occur 0 or 1 times in the list. The position in the list prioritizes it with respect to the other rules. StrictParsing is not used. If no color space is found in the path, the rule will not match and the next rule will be considered. see insertPathSearchRule. It has the key:
- name: Must be “ColorSpaceNamePathSearch”.
Default Rule: The file_rules must always end with this rule. If no prior rules match, this rule specifies the color space applications will use. see setDefaultRuleColorSpace. It has the keys:
- name: must be “Default”.
- colorspace : Color space name to be returned.

Custom string keys and associated string values may be used to convey app or workflow-specific information, e.g. whether the color space should be left as is or converted into a working space.

Public Functions

FileRulesRcPtr createEditableCopy() const¶: The method clones the content decoupling the two instances.

size_t getNumEntries() const noexcept¶: Does include default rule. Result will be at least 1.

size_t getIndexForRule(const char *ruleName) const¶: Get the index from the rule name.

const char *getName(size_t ruleIndex) const¶: Get name of the rule.

const char *getPattern(size_t ruleIndex) const¶: Setting pattern will erase regex.

void setPattern(size_t ruleIndex, const char *pattern)¶

const char *getExtension(size_t ruleIndex) const¶: Setting extension will erase regex.

void setExtension(size_t ruleIndex, const char *extension)¶

const char *getRegex(size_t ruleIndex) const¶: Setting a regex will erase pattern & extension.

void setRegex(size_t ruleIndex, const char *regex)¶

const char *getColorSpace(size_t ruleIndex) const¶: Set the rule’s color space (may also be a role).

void setColorSpace(size_t ruleIndex, const char *colorSpace)¶

size_t getNumCustomKeys(size_t ruleIndex) const¶: Get number of key/value pairs.

const char *getCustomKeyName(size_t ruleIndex, size_t key) const¶: Get name of key.

const char *getCustomKeyValue(size_t ruleIndex, size_t key) const¶: Get value for the key.

void setCustomKey(size_t ruleIndex, const char *key, const char *value)¶: Adds a key/value or replace value if key exists. Setting a NULL or an empty value will erase the key.

void insertRule(size_t ruleIndex, const char *name, const char *colorSpace, const char *pattern, const char *extension)¶

Insert a rule at a given ruleIndex.

Rule currently at ruleIndex will be pushed to index: ruleIndex + 1. Name must be unique.

”Default” is a reserved name for the default rule. The default rule is automatically added and can’t be removed. (see FileRules::setDefaultRuleColorSpace ).
”ColorSpaceNamePathSearch” is also a reserved name (see FileRules::insertPathSearchRule ).

Will throw if pattern, extension or regex is a null or empty string.

Will throw if ruleIndex is not less than FileRules::getNumEntries .

void insertRule(size_t ruleIndex, const char *name, const char *colorSpace, const char *regex)¶

void insertPathSearchRule(size_t ruleIndex)¶

Helper function to insert a rule.

Uses Config:parseColorSpaceFromString to search the path for any of the color spaces named in the config (as per OCIO v1).

void setDefaultRuleColorSpace(const char *colorSpace)¶: Helper function to set the color space for the default rule.

void removeRule(size_t ruleIndex)¶: Note

Default rule can’t be removed. Will throw if ruleIndex + 1 is not less than FileRules::getNumEntries .

void increaseRulePriority(size_t ruleIndex)¶: Move a rule closer to the start of the list by one position.

void decreaseRulePriority(size_t ruleIndex)¶: Move a rule closer to the end of the list by one position.

bool isDefault() const noexcept¶: Check if there is only the default rule using default role and no custom key. This is the default FileRules state when creating a new config.

FileRules(const FileRules&) = delete¶

FileRules &operator=(const FileRules&) = delete¶

virtual ~FileRules()¶: Do not use (needed only for pybind11).

Public Static Functions

static FileRulesRcPtr Create()¶: Creates FileRules for a Config. File rules will contain the default rule using the default role. The default rule cannot be removed.

Public Static Attributes

static const char *DefaultRuleName¶: Reserved rule name for the default rule.

static const char *FilePathSearchRuleName¶

Reserved rule name for the file path search rule.

ViewingRules¶

class PyOpenColorIO.ViewingRules¶

ViewingRules

Viewing Rules allow config authors to filter the list of views an application should offer based on the color space of an image. For example, a config may define a large number of views but not all of them may be appropriate for use with all color spaces. E.g., some views may be intended for use with scene-linear color space encodings and others with video color space encodings.

Each rule has a name key for applications to refer to the rule. Name values must be unique (using case insensitive comparison). Viewing Rules may also have the following keys:

colorspaces: Either a single colorspace name or a list of names.
encodings: One or more strings to be found in the colorspace’s encoding attribute. Either this attribute or colorspaces must be present, but not both.
custom : Allows arbitrary key / value string pairs, similar to FileRules.

Getters and setters are using the rule position, they will throw if the position is not valid.

ViewingRules() → None¶: Creates ViewingRules for a Config.

addColorSpace(ruleIndex: int, colorSpaceName: str) → None¶

Add colorspace name. Will throw if:

RuleIndex is invalid.
ViewingRules::getNumEncodings is not 0.

addEncoding(ruleIndex: int, encodingName: str) → None¶

Add encoding name. Will throw if:

RuleIndex is invalid.
ViewingRules::getNumColorSpaces is not 0.

getColorSpaces(ruleIndex: int) → PyOpenColorIO.ViewingRules.ViewingRuleColorSpaceIterator¶

getCustomKeyName(ruleIndex: int, key: int) → str¶: Get name of key. Will throw if ruleIndex or keyIndex is invalid.

getCustomKeyValue(ruleIndex: int, key: int) → str¶: Get value for the key. Will throw if ruleIndex or keyIndex is invalid.

getEncodings(ruleIndex: int) → PyOpenColorIO.ViewingRules.ViewingRuleEncodingIterator¶

getIndexForRule(ruleName: str) → int¶: Get the index from the rule name. Will throw if there is no rule named ruleName.

getName(ruleIndex: int) → str¶: Get name of the rule. Will throw if ruleIndex is invalid.

getNumCustomKeys(ruleIndex: int) → int¶: Get number of key/value pairs. Will throw if ruleIndex is invalid.

getNumEntries() → int¶

insertRule(ruleIndex: int, name: str) → None¶

Insert a rule at a given ruleIndex.

Rule currently at ruleIndex will be pushed to index: ruleIndex + 1. If ruleIndex is ViewingRules::getNumEntries, a new rule will be added at the end. Will throw if: - RuleIndex is invalid (must be less than or equal to ViewingRules::getNumEntries). - RuleName already exists.

removeColorSpace(ruleIndex: int, colorSpaceIndex: int) → None¶: Remove colorspace. Will throw if ruleIndex or colorSpaceIndex is invalid.

removeEncoding(ruleIndex: int, encodingIndex: int) → None¶: Remove encoding. Will throw if ruleIndex or encodingIndex is invalid.

removeRule(ruleIndex: int) → None¶: Remove a rule. Throws if ruleIndex is not valid.

setCustomKey(ruleIndex: int, key: str, value: str) → None¶: Adds a key/value or replace value if key exists. Setting a NULL or an empty value will erase the key. Will throw if ruleIndex is invalid.

class PyOpenColorIO.ViewingRules.ViewingRuleColorSpaceIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.ViewingRules.ViewingRuleColorSpaceIterator¶

len(self) → int¶

next(self) → str¶

class PyOpenColorIO.ViewingRules.ViewingRuleEncodingIterator¶

self[arg0: int] → str¶

iter(self) → PyOpenColorIO.ViewingRules.ViewingRuleEncodingIterator¶

len(self) → int¶

next(self) → str¶

class ViewingRules¶

ViewingRules

Each rule has a name key for applications to refer to the rule. Name values must be unique (using case insensitive comparison). Viewing Rules may also have the following keys:

colorspaces: Either a single colorspace name or a list of names.
encodings: One or more strings to be found in the colorspace’s encoding attribute. Either this attribute or colorspaces must be present, but not both.
custom : Allows arbitrary key / value string pairs, similar to FileRules.

Getters and setters are using the rule position, they will throw if the position is not valid.

Public Functions

ViewingRulesRcPtr createEditableCopy() const¶: The method clones the content decoupling the two instances.

size_t getNumEntries() const noexcept¶

size_t getIndexForRule(const char *ruleName) const¶: Get the index from the rule name. Will throw if there is no rule named ruleName.

const char *getName(size_t ruleIndex) const¶: Get name of the rule. Will throw if ruleIndex is invalid.

size_t getNumColorSpaces(size_t ruleIndex) const¶: Get number of colorspaces. Will throw if ruleIndex is invalid.

const char *getColorSpace(size_t ruleIndex, size_t colorSpaceIndex) const¶: Get colorspace name. Will throw if ruleIndex or colorSpaceIndex is invalid.

void addColorSpace(size_t ruleIndex, const char *colorSpace)¶

Add colorspace name. Will throw if:

RuleIndex is invalid.
ViewingRules::getNumEncodings is not 0.

void removeColorSpace(size_t ruleIndex, size_t colorSpaceIndex)¶: Remove colorspace. Will throw if ruleIndex or colorSpaceIndex is invalid.

size_t getNumEncodings(size_t ruleIndex) const¶: Get number of encodings. Will throw if ruleIndex is invalid.

const char *getEncoding(size_t ruleIndex, size_t encodingIndex) const¶: Get encoding name. Will throw if ruleIndex or encodingIndex is invalid.

void addEncoding(size_t ruleIndex, const char *encoding)¶

Add encoding name. Will throw if:

RuleIndex is invalid.
ViewingRules::getNumColorSpaces is not 0.

void removeEncoding(size_t ruleIndex, size_t encodingIndex)¶: Remove encoding. Will throw if ruleIndex or encodingIndex is invalid.

size_t getNumCustomKeys(size_t ruleIndex) const¶: Get number of key/value pairs. Will throw if ruleIndex is invalid.

const char *getCustomKeyName(size_t ruleIndex, size_t keyIndex) const¶: Get name of key. Will throw if ruleIndex or keyIndex is invalid.

const char *getCustomKeyValue(size_t ruleIndex, size_t keyIndex) const¶: Get value for the key. Will throw if ruleIndex or keyIndex is invalid.

void setCustomKey(size_t ruleIndex, const char *key, const char *value)¶: Adds a key/value or replace value if key exists. Setting a NULL or an empty value will erase the key. Will throw if ruleIndex is invalid.

void insertRule(size_t ruleIndex, const char *ruleName)¶

Insert a rule at a given ruleIndex.

Rule currently at ruleIndex will be pushed to index: ruleIndex + 1. If ruleIndex is ViewingRules::getNumEntries, a new rule will be added at the end. Will throw if:

RuleIndex is invalid (must be less than or equal to ViewingRules::getNumEntries).
RuleName already exists.

void removeRule(size_t ruleIndex)¶: Remove a rule. Throws if ruleIndex is not valid.

ViewingRules(const ViewingRules&) = delete¶

ViewingRules &operator=(const ViewingRules&) = delete¶

virtual ~ViewingRules()¶: Do not use (needed only for pybind11).

Public Static Functions

static ViewingRulesRcPtr Create()¶: Creates ViewingRules for a Config.

std::ostream &OpenColorIO_v2_2::operator<<(std::ostream&, const ViewingRules&)¶

typedef std::shared_ptr<const ViewingRules> OpenColorIO_v2_2::ConstViewingRulesRcPtr¶

typedef std::shared_ptr<ViewingRules> OpenColorIO_v2_2::ViewingRulesRcPtr¶