Interface: ColorPipelineMgr

This interface exposes properties and methods for color management (legacy gamma and OCIO-based) in 3ds Max. For more information about OpenColorIO (OCIO) see OCIO Overview.

Example

/* Uses some ColorPipelineMgr methods to get information about the
current configuration and print out description strings for color
spaces, displays and views. */

renderingSpaces = ColorPipelineMgr.GetRenderingColorSpaceList()
fileSpaces = ColorPipelineMgr.GetFileIOColorSpaceList()
displays = ColorPipelineMgr.GetDisplayList()


format "Render Space Descriptions:\n"
for rs in renderingSpaces do (
    dsc = ColorPipelineMgr.GetColorSpaceDescription rs
    format "% : %\n" rs dsc
)

format "File Space Descriptions:\n"

for rs in fileSpaces do (
    dsc = ColorPipelineMgr.GetColorSpaceDescription rs
    format "% : %\n" rs dsc
)

format "Display View Descriptions:\n"

for dsp in displays do (
    format "Display: %\n" dsp
    vs = ColorPipelineMgr.GetViewList dsp 
    for v in vs do(
        append views v    
        format "  view % : %\n" v (ColorPipelineMgr.GetDisplayViewDescription dsp v)    
    )

)

Properties:

    .Mode : enum : Read|Write
       Mode enums: {#Unmanaged|#Gamma|#OCIO_Default|#OCIO_Custom}

Gets or sets the Color Managment mode, where:

#Unmanaged - no color management.
#Gamma - OCIO configuration that emulates the legacy gamma mode in versions prior to 3ds Max 2024. This mode assumes that the primaries of the monitor are Rec.709/sRGB and those primaries are also used as the rendering space.
#OCIO_Default - OCIO-based color management mode, using the built-in 3ds Max default configuration file.
#OCIO_Custom - OCIO-based color management mode, using a user-specified OCIO configuration file.

    .OCIOConfigPath : string : Read|Write

Gets or sets the configuration file that specifies Open Color IO settings. Note that this path can only be changed if the mode is not locked. See the .Locked property below.

    .Status : enum : Read
       Status enums: {#Normal|#FallbackRaw|#Invalid}

Returns the initialization state of Color Mangement, where:

#Normal - color management is initialized and working properly
#FallbackRaw - color management initialization failed for some reason (eg missing or incorrect configuration file), and 3ds Max falls back to "unmanaged".
#Invalid - something terrible happened, the system may be unstable. Ideally, this state is never reached.

    .Locked : boolean : Read|Write

Gets or sets whether color management settings are locked. This means the mode and configuration path cannot be changed via code (though they can still be changed using the UI).

    .RenderingColorSpace : string : Read|Write

Gets or sets the string specifying the rendering color space. Available color space configurations are:

"ACEScg"
"ACES2065-1"
"scene-linear Rec.709-sRGB"
"scene-linear DCI-P3 D65"
"scene-linear Rec.2020"

    .DisplayGamma : float : Read|Write

Gets or sets the display gamma value. The default is 2.2.

Methods:

    <boolean>LoadSystemDefaults()
       LoadSystemDefaults - no automatic redraw after invoked

Loads the color management system defaults. This is equivalent to clicking the Load System Defaults button on the Color Management preferences tab.

    <boolean>SaveSystemDefaults()
       SaveSystemDefaults - no automatic redraw after invoked

Saves the current color management settings to the system defaults file. This is equivalent to clicking the Save As System Defaults button on the Color Mangement preferences tab.

    <string>OCIODumpInfo()
       OCIODumpInfo - no automatic redraw after invoked

Returns a string containing Open Color IO system information, including the currently loaded active configuration. Mostly useful for debugging.

    <string>GetModeDescription()
       GetModeDescription - no automatic redraw after invoked

Returns the description string for the current color management mode. This is the description field in the currently active configuration file. Produces a runtime error if no matching color space name is found.

    <string>GetColorSpaceDescription <string>colorSpace
       GetColorSpaceDescription - no automatic redraw after invoked

Returns the description string for the color space in the current configuration with a name that matches the specified colorSpace.

    <string>GetDisplayViewDescription <string>display <string>view
       GetDisplayViewDescription - no automatic redraw after invoked

Gets the description string for the specified view and display.

    <boolean>SetDefaultOutputConversion <enum>conversion colorSpace:<&string> display:<&string> viewTransform:<&string> fileType:<enum>
       SetDefaultOutputConversion - no automatic redraw after invoked
       conversion enums: {#NoConversion|#ColorSpaceConversion|#DisplayViewtransform}
       colorSpace default value: ""
       colorSpace is In and Out parameter
       display default value: ""
       display is In and Out parameter
       viewTransform default value: ""
       viewTransform is In and Out parameter
       fileType enums: {#GammaEncoded|#Linear}
       fileType default value: #GammaEncoded

Sets the current output conversion settings. For #ColorSpaceConversion a colorSpace name must be specified. For #DisplayViewTransform, a colorSpace, display, and viewTransform must be specified. Returns true on succes, false otherwise.

The optional keyword arguments fileType available in 3ds Max 2026 provide a separate set of parameters to control the automatic output transform: one for gamma-encoded file formats one for the others.

#GammaEncoded: is the transform that is applied when Automatic is selected for JPEG, PNG, BMP, and other gamma-encoded image formats.

#Linear: is the transform that is applied when Automatic is selected for linear and logarithmic image formats, including EXR and HDR.

    <enum>GetDefaultOutputConversion colorSpace:<&string> display:<&string> viewTransform:<&string>
       GetDefaultOutputConversion enums: {#NoConversion|#ColorSpaceConversion|#DisplayViewtransform
       GetDefaultOutputConversion - no automatic redraw after invoked
       colorSpace default value: ""
       colorSpace is Out parameter
       display default value: ""
       display is Out parameter
       viewTransform default value: ""
       viewTransform is Out parameter

Gets the current default output conversion settings as an enum, and returns the color space, display, and view transform settings if the output conversion type is #DisplayViewTransform, and the color space if it is #ColorSpaceConversion.

    <string array>GetRenderingColorSpaceList()
       GetRenderingColorSpaceList - no automatic redraw after invoked

Returns an array of color spaces available in the currently loaded configuration.

    <string array>GetFileIOColorSpaceList()
       GetFileIOColorSpaceList - no automatic redraw after invoked

Returns an array of File IO Color Spaces in the currently loaded configuration.

    <string array>GetDisplayList()
       GetDisplayList - no automatic redraw after invoked

Returns an array of the names of displays in the currently loaded configuration.

    <string array>GetViewList <string>display [colorSpace:<string>]
       GetViewList - no automatic redraw after invoked
       colorSpace default value: ""

Returns an array of views for the specified display and optionally the specified colorSpace.

    <boolean>ReInitialize()

Re-initializes the color management system.

    <point4>ConvertColor <point4>sourceColor <string>sourceColorSpace (targetColorSpace:<string> | targetDisplay:<string> viewTransform:<string>) inverse:<boolean> optimization:<enum>
       ConvertColor - no automatic redraw after invoked
       targetColorSpace default value: ""
       targetDisplay default value: ""
       viewTransform default value: ""
       inverse default value: false
       optimization enums: {#Optimization_Normal|#Optimization_None|#Optimization_Lossless}
       optimization default value: #Optimization_Lossless

Converts the sourceColor from the sourceColorSpace to a target color space, and returns it. The target color space is specified either as a targetColorSpace name, or as a targetDisplay and viewTransform pair. The method generates a runtime exception if the target color space is not specified correctly.

The inverse parameter specifies whether to convert from the source to the target. It is useful for doing inverse Display/View transform. The inverse parameter can also be used with targetColorSpace, in that case it will have the same effect as swapping "sourceColorSpace" and "targetColorSpace".

The optimization parameter specifies how to optimize the conversion. It defaults to #Optimization_Losless which is more precise and eliminates over- and under-shoots, especially with gamma curves (such as sRGB to linear).

Both the source color and returned color are Point4 values. See the section Important Notes on Color Operations in Color Values to understand why this is so.

Some examples of various color conversions:

cpm = colorPipelineMgr
cpm.mode=#ocio_default
cslist = cpm.GetFileIOColorSpaceList()

cs1 = "sRGB"
cs2 = "ACEScg"
cs3 = "scene-linear Rec.709-sRGB"

c1 = [0.1, 0.2, 0.3, 1.0]

-- "ACEScg" to "scene-linear Rec.709-sRGB" and back to "ACEScg"
c2 = cpm.convertColor c1 cs2 targetColorSpace:cs3
c3 = cpm.convertColor c2 cs3 targetColorSpace:cs2

-- "scene-linear Rec.709-sRGB" to "ACEScg" and back to "scene-linear Rec.709-sRGB"
c4 = cpm.convertColor c1 cs3 targetColorSpace:cs2
c5 = cpm.convertColor c4 cs3 targetColorSpace:cs2 inverse:true

-- "sRGB" to "ACEScg" and back to "sRGB" with optimization turned off
c6 = cpm.convertColor c1 cs1 targetColorSpace:cs2 inverse:false optimization:#Optimization_None
c7 = cpm.convertColor c6 cs1 targetColorSpace:cs2 inverse:true  optimization:#Optimization_None

-- "sRGB" to "ACEScg" and back to "sRGB" with lossy optimization turned on: lower precision
c8 = cpm.convertColor c1 cs1 targetColorSpace:cs2 inverse:false optimization:#Optimization_Normal
c9 = cpm.convertColor c8 cs1 targetColorSpace:cs2 inverse:true  optimization:#Optimization_Normal

-- "ACEScg" to sRGB/un-tone-mapped display/view transform and back to "ACEScg"
c10 = cpm.convertColor c1  cs2 targetDisplay:"sRGB" viewTransform:"un-tone-mapped" inverse:false 
c11 = cpm.convertColor c10 cs2 targetDisplay:"sRGB" viewTransform:"un-tone-mapped" inverse:true

    <boolean>ImportInputRules <string>configFilePath

Replaces the color-space assignment rules with those from another OCIO config file (*.ocio or *.ocioz) specified by configFilePath.

    <boolean>ExportInputRules <string>configFilePath
       ExportInputRules - no automatic redraw after invoked

Exports the current rules into a new .ocio file specified by configFilePath, together with the spaces, transforms, and other settings of the current config.

    <boolean>GetInputRule <index>ruleIndex name:<&string> colorSpace:<&string> pattern:<&string> extension:<&string> regex:<&string>
       GetInputRule - no automatic redraw after invoked
       name default value: ""
       name is Out parameter
       colorSpace default value: ""
       colorSpace is Out parameter
       pattern default value: ""
       pattern is Out parameter
       extension default value: ""
       extension is Out parameter
       regex default value: ""
       regex is Out parameter

Gets the name, pattern, extension, regex, or colorSpace of the current rule at the specified ruleIndex in the Input Image Files section of the Color Management Settings.

cpm = colorPipelineMgr
rule_name = ""
rule_colorSpace = ""
rule_pattern = ""
rule_extension = ""
rule_regex = ""

cpm.GetInputRule 2 name:&rule_name colorSpace:&rule_colorSpace pattern:&rule_pattern extension:&rule_extension regex:&rule_regex
format "name: %\ncolorSpace: %\npattern: %\nextension: %\nregex: %\n" rule_name rule_colorSpace rule_pattern rule_extension rule_regex

--> name: jpg
--> colorSpace: sRGB
--> pattern: *
--> extension: jpg
--> regex: 
--> OK

    <boolean>SetInputRule <index>ruleIndex name:<string> colorSpace:<string> pattern:<string> extension:<string> regex:<string>
       SetInputRule - no automatic redraw after invoked
       name default value: ""
       colorSpace default value: ""
       pattern default value: ""
       extension default value: ""
       regex default value: ""

Overwrites the rule at the specified ruleIndex with the provided arguments in the Input Image Files section of the Color Management Settings.

    <boolean>InsertInputRule <index>ruleIndex <string>name <string>colorSpace pattern:<string> extension:<string> regex:<string>
       InsertInputRule - no automatic redraw after invoked
       pattern default value: ""
       extension default value: ""
       regex default value: ""

Inserts the rule at the specified ruleIndex with the provided arguments in the Input Image Files section of the Color Management Settings.

    <boolean>DeleteInputRule <index>ruleIndex
       DeleteInputRule - no automatic redraw after invoked

Deletes the rule at the specified ruleIndex

    <boolean>ResetInputRules()
       ResetInputRules - no automatic redraw after invoked

Resets input file IO rules to the rules read from the active OCIO config file, reverting any custom modifications.

    <void>SetDefaultDisplayViewTransform <enum>target <boolean>auto display:<string> viewTransform:<string>
       SetDefaultDisplayViewTransform - no automatic redraw after invoked
       target enums: {#Global|#Viewport|#FrameBuffer|#MtlEditor|#ColorPicker|#ColorSwatch}
       display default value: ""
       viewTransform default value: ""

Sets the current default Display and Views Transform settings of the chosen target.

    <void>GetDefaultDisplayViewTransform <enum>target <&boolean>auto <&string>display <&string>viewTransform
       GetDefaultDisplayViewTransform - no automatic redraw after invoked
       target enums: {#Global|#Viewport|#FrameBuffer|#MtlEditor|#ColorPicker|#ColorSwatch}
       auto is Out parameter
       display is Out parameter
       viewTransform is Out parameter

Gets the current default Display and Views Transform settings of the chosen target as an enum, and returns the auto , display, and viewTransform settings.

Interface: ColorPipelineMgr

Example

Properties:

Methods:

Was this information helpful?