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