Processors¶
Processor¶
-
class
PyOpenColorIO.
Processor
¶ The :ref:`Processor` represents a specific color transformation which is the result of
Config::getProcessor()
.-
Processor
(*args, **kwargs)¶ Initialize self. See help(type(self)) for accurate signature.
-
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
:ref:`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 family, 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.
getOptimizedCPUProcessor(self: PyOpenColorIO.Processor, oFlags: PyOpenColorIO.OptimizationFlags) -> PyOpenColorIO.CPUProcessor
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.
getOptimizedProcessor(self: PyOpenColorIO.Processor, oFlags: PyOpenColorIO.OptimizationFlags) -> PyOpenColorIO.Processor
Run the optimizer on a Processor to create a new
:ref:`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.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
:ref:`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¶
-
len
(self) → int¶
-
next
(self) → PyOpenColorIO.FormatMetadata¶
-
self
-
class
OpenColorIO_v2_0
::
Processor
¶ The Processor represents a specific color transformation which is the result of :cpp:func:
Config::getProcessor
.Public Functions
-
bool
isNoOp
() const¶
-
bool
hasChannelCrosstalk
() const¶ True if the image transformation is non-separable. For example, if a change in red may also cause a change in green or blue.
-
const char *
getCacheID
() const¶
-
ConstProcessorMetadataRcPtr
getProcessorMetadata
() const¶ The ProcessorMetadata contains technical information such as the number of files and looks used in the processor.
-
const FormatMetadata &
getFormatMetadata
() const¶ Get a FormatMetadata containing the top level metadata for the processor. For a processor from a CLF file, this corresponds to the ProcessList metadata.
-
int
getNumTransforms
() const¶ Get the number of transforms that comprise the processor. Each transform has a (potentially empty) FormatMetadata.
-
const FormatMetadata &
getTransformFormatMetadata
(int index) const¶ Get a FormatMetadata containing the metadata for a transform within the processor. For a processor from a CLF file, this corresponds to the metadata associated with an individual process node.
-
GroupTransformRcPtr
createGroupTransform
() const¶ 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.
-
DynamicPropertyRcPtr
getDynamicProperty
(DynamicPropertyType type) const¶ 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.
-
bool
hasDynamicProperty
(DynamicPropertyType type) const noexcept¶ True if at least one dynamic property of that type exists.
-
bool
isDynamic
() const noexcept¶ True if at least one dynamic property of any type exists and is dynamic.
-
ConstProcessorRcPtr
getOptimizedProcessor
(OptimizationFlags oFlags) const¶ Run the optimizer on a Processor to create a new :cpp:class:
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.
-
ConstProcessorRcPtr
getOptimizedProcessor
(BitDepth inBD, BitDepth outBD, OptimizationFlags oFlags) const¶ Create a :cpp:class:
Processor
that is optimized for a specific in and out bit-depth (as CPUProcessor would do). This method is provided primarily for diagnostic purposes.
-
ConstGPUProcessorRcPtr
getDefaultGPUProcessor
() const¶ Get an optimized GPUProcessor instance.
-
ConstGPUProcessorRcPtr
getOptimizedGPUProcessor
(OptimizationFlags oFlags) const¶
-
ConstCPUProcessorRcPtr
getDefaultCPUProcessor
() const¶ Get an optimized :cpp:class:
CPUProcessor
instance.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);
- 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 family, 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:
-
ConstCPUProcessorRcPtr
getOptimizedCPUProcessor
(OptimizationFlags oFlags) const¶
-
ConstCPUProcessorRcPtr
getOptimizedCPUProcessor
(BitDepth inBitDepth, BitDepth outBitDepth, OptimizationFlags oFlags) const¶
-
~Processor
()¶ Do not use (needed only for pybind11).
-
bool
CPUProcessor¶
-
class
PyOpenColorIO.
CPUProcessor
¶ -
CPUProcessor
(*args, **kwargs)¶ Initialize self. See help(type(self)) for accurate signature.
-
apply
(*args, **kwargs)¶ Overloaded function.
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
orapplyRGBA
are preferred for processing a NumPy array. The PythonImageDesc
implementation requires copying all values (once) in order to own the underlying pointer. The dedicated packedapply*
methods utilizeImageDesc
on the C++ side so avoid the copy.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
orapplyRGBA
are preferred for processing a NumPy array. The PythonImageDesc
implementation requires copying all values (once) in order to own the underlying pointer. The dedicated packedapply*
methods utilizeImageDesc
on the C++ side so avoid the copy.
-
applyRGB
(*args, **kwargs)¶ Overloaded function.
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.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.
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.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¶
-
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.
-
-
class
OpenColorIO_v2_0
::
CPUProcessor
¶ Public Functions
-
bool
isNoOp
() const¶ The in and out bit-depths must be equal for isNoOp to be true.
-
bool
isIdentity
() const¶ Equivalent to isNoOp from the underlying Processor, i.e., it ignores in/out bit-depth differences.
-
bool
hasChannelCrosstalk
() const¶
-
const char *
getCacheID
() const¶
-
DynamicPropertyRcPtr
getDynamicProperty
(DynamicPropertyType type) const¶
-
void
apply
(ImageDesc &imgDesc) const¶ Apply to an image with any kind of channel ordering while respecting the input and output bit-depths.
-
void
applyRGB
(float *pixel) const¶ Apply to a single pixel respecting that the input and output bit-depths be 32-bit float and the image buffer be packed RGB/RGBA.
- Note
This is not as efficient as applying to an entire image at once. If you are processing multiple pixels, and have the flexibility, use the above function instead.
-
void
applyRGBA
(float *pixel) const¶
-
CPUProcessor
(const CPUProcessor&) = delete¶
-
CPUProcessor &
operator=
(const CPUProcessor&) = delete¶
-
~CPUProcessor
()¶ Do not use (needed only for pybind11).
-
bool
-
typedef std::shared_ptr<const CPUProcessor>
OpenColorIO_v2_0
::
ConstCPUProcessorRcPtr
¶
-
typedef std::shared_ptr<CPUProcessor>
OpenColorIO_v2_0
::
CPUProcessorRcPtr
¶
GPUProcessor¶
-
class
PyOpenColorIO.
GPUProcessor
¶ -
GPUProcessor
(*args, **kwargs)¶ Initialize self. See help(type(self)) for accurate signature.
-
extractGpuShaderInfo
(shaderDesc: PyOpenColorIO.GpuShaderDesc) → None¶ Extract & Store the shader information to implement the color processing.
-
getCacheID
() → str¶
-
hasChannelCrosstalk
() → bool¶
-
isNoOp
() → bool¶
-
-
class
OpenColorIO_v2_0
::
GPUProcessor
¶ Public Functions
-
bool
isNoOp
() const¶
-
bool
hasChannelCrosstalk
() const¶
-
const char *
getCacheID
() const¶
-
void
extractGpuShaderInfo
(GpuShaderDescRcPtr &shaderDesc) const¶ Extract & Store the shader information to implement the color processing.
-
void
extractGpuShaderInfo
(GpuShaderCreatorRcPtr &shaderCreator) const¶ Extract the shader information using a custom GpuShaderCreator class.
-
GPUProcessor
(const GPUProcessor&) = delete¶
-
GPUProcessor &
operator=
(const GPUProcessor&) = delete¶
-
~GPUProcessor
()¶ Do not use (needed only for pybind11).
-
bool
-
typedef std::shared_ptr<const GPUProcessor>
OpenColorIO_v2_0
::
ConstGPUProcessorRcPtr
¶
-
typedef std::shared_ptr<GPUProcessor>
OpenColorIO_v2_0
::
GPUProcessorRcPtr
¶
ProcessorMetadata¶
-
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
OpenColorIO_v2_0
::
ProcessorMetadata
¶ This class contains meta information about the process that generated this processor. The results of these functions do not impact the pixel processing.
Public Functions
-
int
getNumFiles
() const¶
-
const char *
getFile
(int index) const¶
-
int
getNumLooks
() const¶
-
const char *
getLook
(int index) const¶
-
void
addFile
(const char *fname)¶
-
void
addLook
(const char *look)¶
-
ProcessorMetadata
(const ProcessorMetadata&) = delete¶
-
ProcessorMetadata &
operator=
(const ProcessorMetadata&) = delete¶
-
~ProcessorMetadata
()¶ Do not use (needed only for pybind11).
Public Static Functions
-
ProcessorMetadataRcPtr
Create
()¶
-
int
-
typedef std::shared_ptr<const ProcessorMetadata>
OpenColorIO_v2_0
::
ConstProcessorMetadataRcPtr
¶
-
typedef std::shared_ptr<ProcessorMetadata>
OpenColorIO_v2_0
::
ProcessorMetadataRcPtr
¶