Processors

Processor

PythonC++

class PyOpenColorIO.Processor

The :ref:`Processor` represents a specific color transformation which is the result of Config::getProcessor.

Processor(*args, **kwargs)

createGroupTransform() → PyOpenColorIO.GroupTransform

Return a GroupTransform that contains a copy of the transforms that comprise the processor. (Changes to it will not modify the original processor.) Note that the GroupTransform::write method may be used to serialize a Processor. Serializing to CTF format is a useful technique for debugging Processor contents.

getCacheID() → str

getDefaultCPUProcessor() → PyOpenColorIO.CPUProcessor

Get an optimized CPUProcessor instance.

Note

This may provide higher fidelity than anticipated due to internal optimizations. For example, if the inputColorSpace and the outputColorSpace are members of the same equalitygroup, no conversion will be applied, even though strictly speaking quantization should be added.

Note

The typical use case to apply color processing to an image is:

OCIO::ConstConfigRcPtr config = OCIO::GetCurrentConfig();

OCIO::ConstProcessorRcPtr processor
    = config->getProcessor(colorSpace1, colorSpace2);

OCIO::ConstCPUProcessorRcPtr cpuProcessor
    = processor->getDefaultCPUProcessor();

OCIO::PackedImageDesc img(imgDataPtr, imgWidth, imgHeight, imgChannels);
cpuProcessor->apply(img);

getDefaultGPUProcessor() → PyOpenColorIO.GPUProcessor

Get an optimized GPUProcessor instance.

getDynamicProperty(type: PyOpenColorIO.DynamicPropertyType) → PyOpenColorIO.DynamicProperty

The returned pointer may be used to set the default value of any dynamic properties of the requested type. Throws if the requested property is not found. Note that if the processor contains several ops that support the requested property, only one can be dynamic and only this one will be controlled.

Note

The dynamic properties are a convenient way to change on-the-fly values without generating again and again a CPU or GPU processor instance. Color transformations can contain dynamic properties from a ExposureContrastTransform for example. So, Processor, CPUProcessor and GpuShaderCreator all have ways to manage dynamic properties. However, the transform dynamic properties are decoupled between the types of processor instances so that the same Processor can generate several independent CPU and/or GPU processor instances i.e. changing the value of the exposure dynamic property from a CPU processor instance does not affect the corresponding GPU processor instance. Processor creation will log a warning if there are more than one property of a given type. There may be more than one property of a given type, but only one will respond to parameter updates, the others will use their original parameter values.

getFormatMetadata() → PyOpenColorIO.FormatMetadata

Get a FormatMetadata containing the top level metadata for the processor. For a processor from a CLF file, this corresponds to the ProcessList metadata.

getOptimizedCPUProcessor(*args, **kwargs)

Overloaded function.

1. getOptimizedCPUProcessor(self: PyOpenColorIO.Processor, oFlags: PyOpenColorIO.OptimizationFlags) -> PyOpenColorIO.CPUProcessor

2. getOptimizedCPUProcessor(self: PyOpenColorIO.Processor, inBitDepth: PyOpenColorIO.BitDepth, outBitDepth: PyOpenColorIO.BitDepth, oFlags: PyOpenColorIO.OptimizationFlags) -> PyOpenColorIO.CPUProcessor

getOptimizedGPUProcessor(oFlags: PyOpenColorIO.OptimizationFlags) → PyOpenColorIO.GPUProcessor

getOptimizedProcessor(*args, **kwargs)

Overloaded function.

1. getOptimizedProcessor(self: PyOpenColorIO.Processor, oFlags: PyOpenColorIO.OptimizationFlags) -> PyOpenColorIO.Processor

Run the optimizer on a Processor to create a new Processor. It is usually not necessary to call this since getting a CPUProcessor or GPUProcessor will also optimize. However if you need both, calling this method first makes getting a CPU and GPU Processor faster since the optimization is effectively only done once.

2. getOptimizedProcessor(self: PyOpenColorIO.Processor, inBitDepth: PyOpenColorIO.BitDepth, outBitDepth: PyOpenColorIO.BitDepth, oFlags: PyOpenColorIO.OptimizationFlags) -> PyOpenColorIO.Processor

Run the optimizer on a Processor to create a new Processor. It is usually not necessary to call this since getting a CPUProcessor or GPUProcessor will also optimize. However if you need both, calling this method first makes getting a CPU and GPU Processor faster since the optimization is effectively only done once.

getProcessorMetadata() → PyOpenColorIO.ProcessorMetadata

The ProcessorMetadata contains technical information such as the number of files and looks used in the processor.

getTransformFormatMetadata() → PyOpenColorIO.Processor.TransformFormatMetadataIterator

hasChannelCrosstalk() → bool

True if the image transformation is non-separable. For example, if a change in red may also cause a change in green or blue.

hasDynamicProperty(type: PyOpenColorIO.DynamicPropertyType) → bool

True if at least one dynamic property of that type exists.

isDynamic() → bool

True if at least one dynamic property of any type exists and is dynamic.

isNoOp() → bool

class PyOpenColorIO.Processor.TransformFormatMetadataIterator

self[arg0: int] → PyOpenColorIO.FormatMetadata

iter(self) → PyOpenColorIO.Processor.TransformFormatMetadataIterator

len(self) → int

next(self) → PyOpenColorIO.FormatMetadata

CPUProcessor

PythonC++

class PyOpenColorIO.CPUProcessor

CPUProcessor(*args, **kwargs)

apply(*args, **kwargs)

Overloaded function.

1. apply(self: PyOpenColorIO.CPUProcessor, imgDesc: PyOpenColorIO.ImageDesc) -> None

Apply to an image with any kind of channel ordering while respecting the input and output bit-depths. Image values are modified in place.

Note

The GIL is released during processing, freeing up Python to execute other threads concurrently.

Note

For large images, applyRGB or applyRGBA are preferred for processing a NumPy array. The Python ImageDesc implementation requires copying all values (once) in order to own the underlying pointer. The dedicated packed apply* methods utilize ImageDesc on the C++ side so avoid the copy.

2. apply(self: PyOpenColorIO.CPUProcessor, srcImgDesc: PyOpenColorIO.ImageDesc, dstImgDesc: PyOpenColorIO.ImageDesc) -> None

Apply to an image with any kind of channel ordering while respecting the input and output bit-depths. Modified srcImgDesc image values are written to the dstImgDesc image, leaving srcImgDesc unchanged.

Note

The GIL is released during processing, freeing up Python to execute other threads concurrently.

Note

For large images, applyRGB or applyRGBA are preferred for processing a NumPy array. The Python ImageDesc implementation requires copying all values (once) in order to own the underlying pointer. The dedicated packed apply* methods utilize ImageDesc on the C++ side so avoid the copy.

applyRGB(*args, **kwargs)

Overloaded function.

1. applyRGB(self: PyOpenColorIO.CPUProcessor, data: buffer) -> None

Apply to a packed RGB array adhering to the Python buffer protocol. This will typically be a NumPy array. Input and output bit-depths are respected but must match. Any array size or shape is supported as long as the flattened array size is divisible by 3. Array values are modified in place.

Note

This differs from the C++ implementation which only applies to a single pixel. This method uses a PackedImageDesc under the hood to apply to an entire image at once. The GIL is released during processing, freeing up Python to execute other threads concurrently.

2. applyRGB(self: PyOpenColorIO.CPUProcessor, data: List[float]) -> List[float]

Apply to a packed RGB list of float values. Any size is supported as long as the list length is divisible by 3. A new list with processed float values is returned, leaving the input list unchanged.

Note

This differs from the C++ implementation which only applies to a single pixel. This method uses a PackedImageDesc under the hood to apply to an entire image at once. The GIL is released during processing, freeing up Python to execute other threads concurrently.

Note

For large images, a NumPy array should be preferred over a list. List values are copied on input and output, where an array is modified in place.

applyRGBA(*args, **kwargs)

Overloaded function.

1. applyRGBA(self: PyOpenColorIO.CPUProcessor, data: buffer) -> None

Apply to a packed RGBA array adhering to the Python buffer protocol. This will typically be a NumPy array. Input and output bit-depths are respected but must match. Any array size or shape is supported as long as the flattened array size is divisible by 4. Array values are modified in place.

Note

This differs from the C++ implementation which only applies to a single pixel. This method uses a PackedImageDesc under the hood to apply to an entire image at once. The GIL is released during processing, freeing up Python to execute other threads concurrently.

2. applyRGBA(self: PyOpenColorIO.CPUProcessor, data: List[float]) -> List[float]

Apply to a packed RGBA list of float values. Any size is supported as long as the list length is divisible by 4. A new list with processed float values is returned, leaving the input list unchanged.

Note

This differs from the C++ implementation which only applies to a single pixel. This method uses a PackedImageDesc under the hood to apply to an entire image at once. The GIL is released during processing, freeing up Python to execute other threads concurrently.

Note

For large images, a NumPy array should be preferred over a list. List values are copied on input and output, where an array is modified in place.

getCacheID() → str

getDynamicProperty(type: PyOpenColorIO.DynamicPropertyType) → PyOpenColorIO.DynamicProperty

The returned pointer may be used to set the value of any dynamic properties of the requested type. Throws if the requested property is not found. Note that if the processor contains several ops that support the requested property, only one can be dynamic.

Note

The dynamic properties in this object are decoupled from the ones in the Processor it was generated from. For each dynamic property in the Processor, there is one in the CPU processor.

getInputBitDepth() → PyOpenColorIO.BitDepth

Bit-depth of the input pixel buffer.

getOutputBitDepth() → PyOpenColorIO.BitDepth

Bit-depth of the output pixel buffer.

hasChannelCrosstalk() → bool

isIdentity() → bool

Equivalent to isNoOp from the underlying Processor, i.e., it ignores in/out bit-depth differences.

isNoOp() → bool

The in and out bit-depths must be equal for isNoOp to be true.

GPUProcessor

PythonC++

class PyOpenColorIO.GPUProcessor

GPUProcessor(*args, **kwargs)

extractGpuShaderInfo(shaderDesc: PyOpenColorIO.GpuShaderDesc) → None

Extract & Store the shader information to implement the color processing.

getCacheID() → str

hasChannelCrosstalk() → bool

isNoOp() → bool

ProcessorMetadata

PythonC++

class PyOpenColorIO.ProcessorMetadata

This class contains meta information about the process that generated this processor. The results of these functions do not impact the pixel processing.

ProcessorMetadata() → None

addFile(fileName: str) → None

addLook(look: str) → None

getFiles() → PyOpenColorIO.ProcessorMetadata.FileIterator

getLooks() → PyOpenColorIO.ProcessorMetadata.LookIterator

class PyOpenColorIO.ProcessorMetadata.FileIterator

self[arg0: int] → str

iter(self) → PyOpenColorIO.ProcessorMetadata.FileIterator

len(self) → int

next(self) → str

class PyOpenColorIO.ProcessorMetadata.LookIterator

self[arg0: int] → str

iter(self) → PyOpenColorIO.ProcessorMetadata.LookIterator

len(self) → int

next(self) → str