OpenEXR : BitmapIO

The OpenEXR class exposes an interface to access the settings of the OpenEXR Output plug-in introduced in 3ds Max 2011.

This BitmapIO is a complete replacement of the previously availbale MaxOpenEXR BitmapIO plug-in. The older plugin introduced in 3ds Max 8 has been completely removed.

Constructor:

Class instances not creatable by MAXScript

Aliases:

OpenEXR fopenexr

Interface: fopenexr

The fopenexr interface exposes no properties and the following methods:

Methods:

Defaults

<boolean>fopenexr.setDefaults ()

Ininitalizes OpenEXR handling and its default values.

<boolean>fopenexr.loadEXRParams <&String>exrName

exrName is In and Out parameter

Loads the EXR parameters from the specified EXR file name.

<boolean>fopenexr.saveEXRParams <&String>exrName

exrName is In and Out parameter

Saves the EXR parameters from the specified EXR file name.

<boolean>fopenexr.delAllAppDatas ()

Deletes all appData.

Returns true on success, false otherwise.

Main Render Output

The following methods give access to the Format and Type settings in the Main Render Output group of controls of the OpenEXR Output Settings dialog.

Format

Type

Global Options

The following methods give access to the Compression, Storage Type and Image Region settings of the OpenEXR Output Settings dialog.

Compression

<integer>fopenexr.getCompression ()

Returns an integer corresponding to the selection index of the Compression drop-down list.

Please see the table below for possible values.

Note that the selection index is 0-based.

<boolean>fopenexr.SetCompression <integer>compression

Sets the Compression drop-down list to the item specified by the integer argument.

The possible values are:

Code	Compression Type
0	No compression
1	Run-length encoding (RLE)
2	ZLIB compression, one scanline at a time
3	ZLIB compression, in blocks of 16 scanlines
4	PIZ-based wavelet compression
5	Lossy 24-bit float compression
6	Lossy 4-by-4 pixel block compression
7	Lossy 4-by-4 pixel block compression (fixed rate)

Storage Type

<boolean>fopenexr.getSaveScanline ()

Returns true if the Storage Type is set to "Store Image as Scanlines", false if it is set to "Store Image as Tiles".

<boolean>fopenexr.setSaveScanline <boolean>saveScanline

Sets the Storage Type to "Store Image as Scanlines" if the argument is true.

Sets the Storage Type to "Store Image as Tiles" if the argument is false.

<integer>fopenexr.getTileSize ()

Returns the tile size used when Storage Type is set to Scanline.

The tile size is not exposed to the User Interface.

Note: The Tile Size option is not exposed to the user interface.

<boolean>fopenexr.setTileSize <integer>tileSize

Sets the tile size used when Storage Type is set to Scanline.

The tile size is not exposed to the User Interface.

Note: The Tile Size option is not exposed to the user interface.

Image Region

<boolean>fopenexr.getSaveRegion ()

Returns true if the Image Region drop-down list is set to Save Region.

Returns false if the Image Region drop-down list is set to Save Full Image.

<boolean>fopenexr.setSaveRegion <boolean>saveRegion

Sets the Image Region option to Save Region if the Boolean argument is true.

Sets the Image Region option to Save Full Image if the Boolean argument is false.

OpenEXR Layers

<integer>fopenexr.numLayers ()

Returns the current number of layers in the EXR file.

<integer>fopenexr.getLayerType <integer>layer

Returns the type of the 0-indexed layer as an integer.

Possible values are:

0 - Main Render Layer - always returned for argument 0

1 - Render Element Layer

2 - G-Buffer Channel Layer

<Stringby value>fopenexr.getLayerName <integer>layer

Returns the name used in 3ds Max of the layer specified by the 0-based argument.

For the Main Render Layer (integer 0), the value is always an empty string ("").

For Render Elements , this is the name that appears in the Render Elements panel of the Render Setup dialog.

For G-buffer Channels, it is the standard name that appears in the user interface.

<boolean>fopenexr.setLayerName <integer>layer <&String>name

name is In and Out parameter

Sets the 3ds Max name for the specified layer.

<Stringby value>fopenexr.getLayerOutputName <integer>layer

Returns the name used in the EXR file of the layer specified by the argument.

This is the name that appears in the Layer column of the Render Elements and G-Buffer Channels lists.

<boolean>fopenexr.setLayerOutputName <integer>layer <&String>name

name is In and Out parameter

Sets the name used in the EXR file for the layer specified by the 0-based first argument, where 0 is the Main Render Layer.

This is the name that appears in the Layer column of the Render Elements and G-Buffer Channels lists.

<integer>fopenexr.getLayerOutputType <integer>layer

Returns the output type of the specified layer.

Possible layer output types are:

0 - RGBA

1 - RGB

2 - Mono

3 - XYZ (G-Buffer Channels only)

4 - XY (G-Buffer Channels only)

5 - UV (G-Buffer Channels only)

<boolean>fopenexr.setLayerOutputType <integer>layer <integer>type

Sets the output type of the layer specified by the first argument to the value of the second argument.

When the first argument is specified as 0, the Main Render Layer's type will be set.

Possible values of the second argument are:

0 - RGBA

1 - RGB

2 - Mono

3 - XYZ (G-Buffer Channels only)

4 - XY (G-Buffer Channels only)

5 - UV (G-Buffer Channels only)

<integer>fopenexr.getLayerOutputFormat <integer>layer

Returns the output format for the specified layer.

Possible values are

0 - FLOAT32

1 - FLOAT16

2 - INT32

<boolean>fopenexr.setLayerOutputFormat <integer>layer <integer>format

Sets the output format of the layer specified by the first argument to the type specified by the second argument.

When the first argument is specified as 0, the Main Render Layer's format will be set.

Possible values for the second argument are

0 - FLOAT32

1 - FLOAT16

2 - INT32

EXAMPLE:

Here is an example of setting the Main Layer's Output Format and Type:
   fopenexr.setLayerOutputFormat 0 0 -- set Main Render to FLOAT32
   fopenexr.setLayerOutputType 0 1 -- set Main Render to RGB

Render Element Layers

<maxObject>fopenxr.getRenderElementByLayer <integer>layer

Returns the render element as a MAXObject at the specified layer. Available in in 3ds Max 2017 and higher.

<boolean>fopenxr.getLayerEnabled <integer>layer

Returns true if the layer specified is enabled. Available in in 3ds Max 2017 and higher.

<boolean>fopenexr.isAutoAddRenderElements ()

Returns the current state of the "Automatically Add/Remove Render Elements" option.

<boolean>fopenexr.setAutoAddRenderElements <boolean>add

Sets the state of the "Automatically Add/Remove Render Elements" option.

<boolean>fopenexr.addRenderElementLayer <&String>name <&String>outname <integer>type <integer>format 

name is In and Out parameter
outname is In and Out parameter

Adds a render element layer. You must specify the (3ds Max) name, output (EXR) name, type, and format.

<boolean>fopenexr.delRenderElementLayer <&String>name 

name is In and Out parameter

Deletes a render element layer, specified by its (3ds Max) name.

<boolean>fopenexr.addRenderElementLayerRef <maxObject>element <&String>outname <integer>type <integer>format 

outname is In and Out parameter

Adds a render element specified as a MAXObject obtained from the standard Render Element manager.

<boolean>fopenexr.delRenderElementLayerRef <maxObject>element

Deletes the specified render element layer, passed as a MAXObject.

EXAMPLE:

Here is an example of using a MAXObject variable to add a render element layer:
   reMgr = maxOps.GetCurRenderElementMgr ()
   el = reMgr.getRenderElement 1
   fopenexr.addrenderelementlayerref el "diffuse" 0 0

Note:

With the two Ref functionsabove, you can manage render element layers that have identical names.

<integer>fopenexr.delAllRenderElementLayers ()

Deletes all render element layers.

Returns the number of layers that were deleted.

G-Buffer Channel Layers

<boolean>fopenexr.addGBufferChannelLayer <integer>channel <&String>name <integer>type <integer>format 

name is In and Out parameter

Adds a G-buffer channel layer. You must specify the channel, (3ds Max) name, type, and format.

<boolean>fopenexr.delGBufferChannelLayer <&String>name 

name is In and Out parameter

Deletes a G-buffer channel layer, specified by (3ds Max) name.

<integer>fopenexr.delAllGBufferLayers ()

Deletes all G-buffer layers.

Returns the number of layers that were deleted.

Custom Attributes

Using MAXScript, you can save custom attributes, also known as "metadata" to an OpenEXR file. These attributes cancontain arbitrarydataandare ignored by 3ds Max.

The attributes might be data (such as thecamera attributesdescribedhere) that can be read and used by other OpenEXR applications.

Note:

While the purpose is similar to the custom attributes you can define in the 3ds Max user interface and MAXScript as parameter blocks to store additional object properties, custom attributes for EXR files are completely independent of object attributes.

Each custom attribute has a name and an index.

The name is auser-definedstring.

The index is the0-based indexof the attribute in the order it was added to the file.

Getting Custom OpenEXR Attributes

<integer>fopenexr.numAttributes ()

Returns the number of custom attributes in the EXR file.

<Stringby value>fopenexr.getAttributeName <integer>attribute

Returnsthe name ofthe 0-based indexedattribute.

<integer>fopenexr.getAttributeType <integer>attribute

Returnsthe attribute typeof the 0-based indexed attribute as an integer value.

The attribute type codes are as follows:

FOPENEXR_ATTRIB_STRING=0

FOPENEXR_ATTRIB_FLOAT=1

FOPENEXR_ATTRIB_INT=2

FOPENEXR_ATTRIB_MATRIX=3

<Stringby value>fopenexr.getAttributeStringValue <integer>attribute

Returns the value of the specified 0-based indexedstring attribute.

<float>fopenexr.getAttributeFloatValue <integer>attribute

Returnsthe value of the specified0-based indexedfloating-point attribute.

<integer>fopenexr.getAttributeIntValue <integer>attribute

Returnsthe value of the specified0-based indexedinteger attribute.

<matrix3 by value>fopenexr.getAttributeMatrixValue <integer>attribute

Returnsthe value of the specified0-based indexedtransform matrix attribute.

Adding Custom OpenEXR Attributes

<boolean>fopenexr.addStringAttribute <&String>attribute <&String>value 

attribute is In and Out parameter
value is In and Out parameter

Adds an attribute with a string value, and specifies the name and value.

<boolean>fopenexr.addFloatAttribute <&String>attribute <float>value 

attribute is In and Out parameter

Adds an attribute with a floating-point value, and specifies the name and value.

<boolean>fopenexr.addIntAttribute <&String>attribute <integer>value 

attribute is In and Out parameter

Adds an attribute with an integer value, and specifies the name and value.

<boolean>fopenexr.addMatrixAttribute <&String>attribute <matrix3 by value>value 

attribute is In and Out parameter

Adds an attribute with a transform matrix value, and specifies the name and value.

Removing Custom OpenEXR Attributes

<boolean>fopenexr.delAttribute <&String>attribute 

attribute is In and Out parameter

Deletes the specified attribute.

<integer>fopenexr.delAllAttributes ()

Deletes all custom attributes from the EXR file.

Returns the number of attributes that were deleted.

SavingCamera Attributes

Camera attributescan be savedwith an EXR file.

The rendering must be made from a Camera viewport.

Note: Camera Attributes Saving is not exposed to the user interfaceand is only accessible through MAXScript.

These are the camera attribute values saved in the EXR file:

cameraTransform
cameraProjection
cameraFov
cameraAperture
cameraNearClip
cameraFarClip
cameraNearRange
cameraFarRange
cameraTargetDistance

Camera attributes are a special case of custom attributes.

<boolean>fopenexr.getSaveCameraAttributes ()

Returns the current state of the Save Camera Attributes option.

True means the Camera Attributes will be saved with the OpenEXR file.

False means the Camera Attributes will not be saved with the OpenEXR file.

<boolean>fopenexr.setSaveCameraAttributes <boolean>saveCamera

Sets the state of Save Camera Attributes option to the Boolean argument.