|On this page|
IFD is the scene description format produced by Houdini and consumed by mantra to produce a rendered image or animation sequence. The IFD file contains a complete description of the scene and how to render it.
Structure of an IFD
Typically comments and the ray_version command
Retained Object Definitions
Local Object Definitions (Geometry, Space, Light, Atmosphere or Instance)
Optional: additional frames
Geometry may be declared anywhere in the IFD, as long as it’s declared prior to being referenced.
Mantra uses a subset of the hscript scripting language to process IFDs. So some constructs like variable expansion,
if statements, looping constructs, expression evaluation can be used in IFD.
Loads the OTL given by the path. This allows assets within OTLs to be properly referenced by mantra.
Begins definition of an object. The object_type may be one of:
Stores properties which can be bound to geometry primitives using the
Defines geometry used in rendering
Defines a light source.
Defines a fog/atmosphere object.
Defines an instance of a geometry object
Defines a plane within an image.
New in 9.1. Previous versions used the
Each object has properties associated which determine the rendering behavior.
There are two ways of specifying geometry in mantra.
ray_detail [-T] name filename
geometry:name property to the name specified and load the geometry from the file name given. Often, the file name is
stdin which allows geometry to be specified inline.
-T option to indicate
filename is a temporary file. Mantra will delete the temporary file after reading the geometry. You cannot use this option when reading from
stdin, and it may not work properly with network rendering.
ray_detail [-v postblur| -V preblur postblur] name sourcename
Instead of loading geometry from a file, use an existing geometry (specified by sourcename) and offset the position based on the
v (velocity) attribute. Mantra sets the
geometry:name property to name.
End declaration of an object
ray_property style token value...
Sets a global or object property. Each object has different properties which may be set using this command.
ray_image image [optional settings]
Defines the output image for rendering a single frame. Image planes are defined using the
ray_planeproperty commands. A special image name
null: will cause the frame to be rendered, but not saved to any image. This is sometimes useful when rendering maps (deep shadow maps, photon maps or irradiance caches).
ray_defplane plane_name vex_variable vex_type
This command was replaced in Houdini 9.1 with
ray_start plane. The arguments to
ray_defplane are now settings on the image plane:
For versions prior to 9.1, the
ray_defplane command defines an output image plane for the image defined by
ray_image. Any number of planes may be given. If the output format doesn’t support multiple planes, each plane will be written to an individual file (using the
plane_name as the filename).
Any global or exported VEX variable may be used as the
vex_variable type. There are however, two special variables which can be used:
Cf+Af(vector4) – the combination of the
Afvariables will be output as an RGBA image.
Z-Far(float) – the
Pzvariable will be output as a single channel image.
ray_planeproperty token value
This command was replaced in Houdini 9.1 with
ray_property plane. For example:
ray_property plane pfilter "sinc 3 3" ray_property plane gamma 1.7
For versions prior to 9.1, sets the value for an image plane defined by
ray_defplane. See below for the known plane properties.
Specifies a transformation matrix.
This statement may be followed by an arbitrary number of
ray_mtransform statements. Each
ray_mtransform statement specifies the transform for an additional motion segment.
Specifies geometry for an instance object. This is the geometry which will be rendered for the instance. The geometry_object parameter refers to a geometry object which must already be defined in the IFD.
Only one of
ray_procedural should be specified in the definition of an instance.
ray_procedural (-m xmin ymin zmin -M xmax ymax zmax) procedural (arguments)
Defines a procedural function for generating geometry. The -m/-M options are used to define a bounding box for the procedural geometry and may be used to optimize rendering (since mantra may not have to generate any procedural geometry if the bounding box is not rendered). Procedurals may be written by users using the HDK.
ray_declare (-v array_size) style type name value...
Declares a user defined property.
style argument defines the type of property and may be one of
type may be one of
name is the name of the property. You can use this name to query the value.
ray_declare object int my_property 42
my_property can be queried using the renderstate() VEX function, or in python filtering.
Specifies the time (in seconds) which this frame represents. This is used as a random number seed when
image:samplelock is false.
ray_reset [-l] [-o] [-f]
Clear object definitions. Currently only:
-o– instance objects
-f– fog objects
…may be cleared. After a frame is rendered,
ray_reset should usually be called with all options.
ray_deviceoption type name value
Sets an option of the output device in the plane settings.
ray_deviceoption int JPEG.quality 75
This command is output when you use the pre-defined image output properties. You can also use the command in IFD to set arbitrary options, such as options on a custom device:
ray_deviceoption float MYFORMAT.Option value
iconvert utility on the command line to see the list of available options for the built-in format devices such as TIFF and JPEG.
Image plane commands
As of Houdini 9.1 these commands are no longer the preferred method for defining image plane settings. The preferred method is now to use the
ray_property plane command to set properties. See image plane properties in the properties documentation.
These commands will be supported for some time for backwards compatibility.
Specifies the gamma correction for the image (default is 1).
Each color value is multiplied by the gain prior to being quantized.
The amount of dithering to apply. The dither is specified as a fraction of the quantization step (i.e. 0.5 will be one half of a quantization step). The option is ignored for floating point output.
The white-point of the image used during quantization.
The storage type for output. The value should be one of:
8-bit unsigned integers.
16-bit unsigned integers.
32-bit unsigned integers.
16-bit floating point.
32-bit floating point.
16-bit floating point (de-normalized).
32-bit floating point (de-normalized).
De-normalization of floating point values will cause minimal rounding of the floating point values, preventing values like 0.4999999 or 0.5000001.
sfilter type [arguments]
Specifies the sampling filter used to composite sub-pixel samples. This determines how the individual surface samples will be composited to generate a single sub-pixel sample. The possible types are:
alpha– Composite using Of to determine opacity.
closest– Take the value from the closest surface.
min– Take the minimum value from any sample.
max– Take the maximum value from any sample.
pfilter type [arguments]
Specifies the pixel filter, used to combine sub-pixel samples to generate the value for the single pixel. There are several different pixel filters available.
The style may be one of:
min– Choose the value of the sample with the smallest z value (closest to camera).
max– Choose the value of the sample with the maximum z value (farthest from camera).
median– Choose the value of the sample that has the median z value of all samples.
edge– Filter using a unit box but only averages samples with object coverage. This filter will have the effect of disabling external edge antialiasing.
ocover– First, choose the object which covers most of the pixel, then take the average value from the sub-pixels of that object only. This filter is similar to
edgebut it also disables internal edge antialiasing between object boundaries.
idcover– First, choose the object which covers most of the pixel, then select a single sample from that object for the pixel value. This filter is similar to
ocoverbut it will not average any samples. Use this filter mode for planes that will be interpreted as integers, such as object or primitive identifiers. The sample chosen will be unordered.
omin– First, choose the object which covers most of the pixel, then choose a single sample from that object for the pixel value. Chooses the sample with the smallest z value (closest to camera).
omax– First, choose the object which covers most of the pixel, then choose a single sample from that object for the pixel value. Chooses the sample with the maximum z value (farthest).
omedian– First, choose the object which covers most of the pixel, then choose a single sample from that object for the pixel value. Chooses the sample with the median z value.
Choose the sub-pixel closest to the center of the pixel.
box [width height]
Use a box filter to combine the sub-pixels with a filter size given by width/height.
gauss [width height]
Use a Gaussian filter to combine the sub-pixels with a filter size given by width/height.
bartlett [width height]
Use a Bartlett (cone) filter to combine the sub-pixels with a size width given by width/height.
blackman [width height]
Use a Blackman filter to combine the sub-pixels with a filter size given by width/height.
catrom [width height]
Use a Catmull-Rom filter to combine the sub-pixels with a size width given by width/height.
hanning [width height]
Use a Hanning filter to combine the sub-pixels with a filter size given by width/height.
mitchell [width height]
Use a Mitchell filter to combine the sub-pixels with a filter size given by width/height.
The value for this output variable should be generated during the evaluation of
illuminance loops from the specified light. This allows the capture of specific contributions made by individual lights (if shaders are set up to support this).
Specifying properties in IFD
Properties may be set anywhere in the IFD. If object properties are set outside of an object block, they change the default value for all objects declared after the change. For example:
ray_property object shadingrate 2 ray_start object # Shading rate will be "2" ray_end ray_start object # Change the shading rate to 1 ray_property object shadingrate 1 ray_end
See the list of Houdini render properties for mappings to IFD properties.
Categories vs. Masks
Categories and masks provide ways to specify a set of objects or lights.
Masks use the object name to determine membership and use the same semantics as object globbing in Houdini, for example
Each object in mantra also may optionally have category membership assigned. These are arbitrary user tokens. Category selection works using a simple boolean algebra on the category names to determine membership. Category patterns are formed using simple expressions:
Matches any pattern which contains the name.
Matches patterns which do not contain the name.
Matches patterns which have any number of entries.
Matches patterns which do not have any names.
Matches all patterns (equivalent to
Matches the empty set (equivalent to
Multiple expressions may be joined by | (union) and & (intersection). Expression are processed from left to right with the intersection operator at a higher precedence than the union. No parentheses are supported.
a & b & c | d & e | f | g & h
…is interpreted as:
| | |
For example, the category pattern
- | foo will match any objects tagged with category
foo, or any uncategorized objects.
If you specify both a mask and categories, mantra uses the intersection of the two sets (that is, only objects which are in both sets).