• Page
• Discussion
• View source
• History

From Odwiki

DISCLAIMER: This is an unsupported document and the IFD language is subject to change

Contents 1 Mantra Command Line Options 1.1 Rendering Options 1.2 Image Options 1.3 Control Options 2 Structure Of An IFD 2.1 Commands In An IFD 2.2 Image Plane Properties 2.3 Properties 2.3.1 Categories vs. Masks 2.3.2 Global Properties 2.3.3 Geometry Properties 2.3.4 Object Properties 2.3.5 Atmosphere Properties 2.3.6 Light Properties 3 Python And Mantra 3.1 Python Filtering 3.2 Tile Callbacks

Mantra Command Line Options

Though the rendering command line options typically just set properties in the IFD, they override the properties defined in the IFD (for the most part).

Rendering Options

-r	Set renderer:renderengine to "raytrace"
-q	Set render quality (deprecated in favour of -Q)
-Q arg	Set render quality. If the argument contains b - Motion blur will be disabled B - Ray-tracing motion blur will be disabled d - Depth of field will be disabled r - All ray-tracing will be disabled i - Irradiance/Occlusion will be disabledExample: -Q Bd
-s factor	Set the renderer:shadingfactor property
-L factor	Set the renderer:rayshadingfactor property
-M memory	Set the renderer:geocachesize property
-S splits	Specify the maximum splits for a single primitive (default 10)
-v variance	Set the image:variance to the value specified
-A	Set image:samples to (1,1)
-B size	Set the image:bucket property
-J jitter	Set the image:jitter property
-c coving	Set the object:coving property

Image Options

-i	Force interactive rendering (to mplay)
-I options	Set various imager options (using a comma separated list) resolution=WxH - set image:resolution jitter=V - set image:jitter subpixel=0|1 - set image:subpixel sample=WxH - set image:samples sample=N - equivalent to sample=NxNExample: -I resolution=100x80,bucket=16,sample=4,subpixel=1
-w width, -h height	Specify width/height of image (deprecated in favour of -I)
-b depth	Specify default quantization for image planes
-z	Render a depth image (average depth value for each pixel is used)
-Z	Render a depth image (closest depth value for each pixel is used)
-u object(:attrib)	Set the renderer:uvobject and optionally renderer:uvattribute properties.

Control Options

-H hostlist	Specify a comma separated list of hosts to perform rendering. For example -H chili,cayenne
-n val	Number of processes to render using network rendering (deprecated in favour of -j)
-N maj.min(.ren)	When network rendering, ensure that remote hosts will run at least this version of mantra.
-j val	Specify the number of threads (-j 0 uses maximum threads)
-f file	Read the IFD from the file given instead of from stdin
-F	Indicates that the first argument after all options specifies the name of the IFD file to render (instead of the output image)
-o file	Send verbose output to the file given
-p file	Append verbose output to the file given
-P pyfilter	Specifies a python filter program (see Python Filtering)
-V string	If the string contains 0-9 - Set the renderer:verbose property a - Set the renderer:alfprogress property p - Set the renderer:vexprofile to 1 P - Set the renderer:vexprofile to 2

Structure Of An IFD

1. Header Information

   Typically comments and the ray_version command

2. Retained Object Definitions
3. Renderer Settings
4. Camera Settings
5. Local Object Definitions (Geometry, Space, Light, Atmosphere or Instance)
6. Render command
7. Optionally, additional frames may be rendered

Geometry may be declared anywhere in the IFD, as long as it's declared prior to being referenced.

Commands In An IFD

Mantra uses a subset of the hscript scripting language to process IFDs. So some constructs like

• Variable expansion
• if statements
• looping constructs
• Expression evaluation

exist and can be used in processing IFDs.

• ray_loadotl path

  Loads the OTL given by the path. This allows assets within OTLs to be properly referenced by mantra.

• ray_start object_type

  Begins definition of an object. The object_type may be one of

  • material - Material object

    Stores properties which can be bound to geometry primitives using the shop_materialpath attribute.

  • geo - Geometry object

    Defines geometry used in rendering

  • light - Light object

    Defines a light source

  • fog - Fog object

    Defines a fog/atmosphere object

  • object/instance - Instance object

    Defines an instance of a geometry object

    Each object has properties associated which determine the rendering behaviour.

ray_detail

There are three ways of specifying geometry in mantra.ray_detail name filenameSet the geometry:name property to the name specified and load the geometry from the filename given. Often, the filename is "stdin" which allows geometry to be specified inline.ray_detail -v timestep name sourcenameInstead of loading geometry from a file, use an existing geometry (specified by sourcename) and offset the position based on the "v" (velocity) attribute. The geometry:name property will be set to the name given.ray_detail -m xmin ymin zmin -M xmax ymax zmax name filenameSpecify a bounding box for the geometry. Mantra is able to defer loading of the geometry until the bounding box specified is rendered. An alternative would be to use the "file" procedural.

ray_end

End declaration of an object

ray_property style token value...

Sets a global or object property. Each object has different properties (see below) 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_defplane and 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

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 Cf and Af variables will be output as an RGBA image.

• Z-Far (float)

  The Pz variable will be output as a single channel image

ray_planeproperty token value

Sets the value for an image plane defined by ray_defplane. See below for the known plane properties.

ray_transform matrix4

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.

ray_geometry geometry_object

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_geometry and 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. These include:

• sprite
• image3d
• metapoly
• file
• fur
• program
• hscriptinstance
• image3dvolume

ray_odefprop (-v vector_size) name type value...

Declares a user defined property. These properties may be referenced by "user:name" from within VEX shaders.The type should be one of

• float
• bool
• int
• vector2
• vector3
• vector4
• matrix3
• matrix4
• stringThe optional -v argument may be used to specify an arbitrary vector size for the property. The property's value should be specified when the option is declared.

ray_time value

Specifies the time (in seconds) which this frame represents. This is used as a random number seed when image:samplelock is false.

ray_raytrace

Perform rendering

ray_reset (-l) (-o) (-f)

Clear object definitions. Currently only

• l = lights
• o = instance objects
• f = fog objectsmay be cleared. It is suggested that after a frame is rendered, ray_reset be called with all options.

Image Plane Properties

• gamma value

  Specifies the gamma correction for the image (default 1)

• gain value

  Each color value is multiplied by the gain prior to being quantized

• dither value

  The dither amount to be applied. 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.

• whitepoint value

  The white-point of the image used during quantization.

• quantize value

  The storage type for output. The value should be one of

  byte = 8-bit unsigned integers short = 16-bit unsigned integers int = 32-bit unsigned integers half = 16-bit floating point float = 32-bit floating point Half = 16-bit floating point (de-normalized) Float = 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.

• minmax style

  The style may be one of

  min = Choose the minimum value from all sub-pixels max = Choose the maximum value from all sub-pixels ocover = First, choose the object which covers most of

  the pixel, then take the value from the sub-pixels of that object only.

• point

  Choose the sub-pixel closest to the center of the pixel

• box (xwidth ywidth)

  Use a box filter to combine the sub-pixels with a filter width given by xwidth/ywidth.

• gauss

  Use a Gaussian filter to combine th sub-pixels with a filter width given by xwidth/ywidth.

• bartlett

  Use a Bartlett (cone) filter to combine th sub-pixels with a filter width given by xwidth/ywidth.

• blackman

  Use a Blackman filter to combine th sub-pixels with a filter width given by xwidth/ywidth.

• catrom

  Use a Catmull-Rom filter to combine th sub-pixels with a filter width given by xwidth/ywidth.

• hanning

  Use a Hanning filter to combine th sub-pixels with a filter width given by xwidth/ywidth.

• mitchell

  Use a Mitchell filter to combine th sub-pixels with a filter width given by xwidth/ywidth.

lightexport light_name

The value for this output variable should be generated during the evaluation of illuminace loops from the specified light. This allows the capture of specific contributions made by individual lights (if shaders are set up to support this).

Properties

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

Categories vs. Masks

Both categories and masks provide a means of selecting a set of objects or lights.

Masks use the object name to determine membership and use the same semantics as object globbing in Houdini.

An example of a mask might be "/obj/geo*,^/obj/geo1".

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

• name - Matches any pattern which contains the name
• -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 "+&-")

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

a & b & c | d & e | f | g & h

is equivalent to the following invalid (as parentheses are not supported) expression

( a & b & c ) | ( d & e ) | f | ( g & h )

An example of a category expression might be "- | foo"

The intersection of the sets defined by the mask and category selection is used to determine which objects or lights are members of the set.

Global Properties

renderer:name: ("mantra")

Read only variable holding the renderer's name

renderer:version: (9, 0, 614)

Read only variable holding the renderer's version

renderer:objroot: ("/obj/")

This is set to the "root" of the object tree. In Houdini, this is typically /obj. If object names are specified using relative paths (i.e. "light1" or "subnet1/light1"), then this is used to determine the full path. This will be deprecated in the future in favor or category selection.

renderer:houdiniportnum: ("0")

When Houdini starts a render, it creates a "port" which allows mplay or other applications to communicate information back. This is the port number that Houdini openned. This setting will be deprecated in the future and be passed as an image device option.

renderer:uvobject: ("")

Mantra is able to render an object in UV space rather than 3D space. Only one object may be rendered in UV space. This is the name of the object.

renderer:uvattribute: ("")

The name of the attribute used in UV un-wrapping.

renderer:networkqsize: (8)

When performing network rendering, this specifies the number of tiles queueued for each remote render.

renderer:octreestyle: (1)
renderer:kdcrossover: (100)
renderer:kdcostratio: (1)
renderer:kdmemfactor: (1)

These 4 properties are used to control the ray-tracing acceleration structures. Their defaults are typically quite reasonable and there is usually no reason to change their values.

renderer:shadingfactor: (1)

The shadingfactor setting is a global multiplier on all shading rates in the scene. Each object has a shadingrate property. The shading rate used for an object is determined by shadingrate = object:shadingrate * renderer:shadingfactor

renderer:rayshadingfactor: (1)

Mantra allows a separate shadingrate when ray-tracing is performed (compared with scanline rendering). The rayshadingfactor is a global multiplier on all ray-tracing shading rates in the scene. Each object has a rayshadingrate property. The ray-tracing shading rate used for an object is determined by rayshadingrate = object:rayshadingrate * renderer:rayshadingfactor

renderer:vexprofile: (0)

VEX profiling provides a tool to do performance analysis of shader execution. Turning on VEX profiling will affect performance of shading adversely. Especially when NAN detection is turned on.

• 0 = No VEX profiling
• 1 = Performance analysis of VEX execution
• 2 = Performance analysis of VEX execution with NAN detection

When NAN detection is turned on, each instruction executed in VEX will be checked for invalid arithmetic operations. This will check for division by 0, numeric overflow, invalid operations. Errors like this will typically result in white or black pixels in the resulting image.

renderer:verbose: (0)

Determines the verbose level of the renderer. Higher values will cause mantra to print out more information about the rendering process. Typically a level of 1 or 2 is sufficient.

renderer:threadcount: (1)

The number of threads used for rendering.

renderer:renderengine: (0)

Mantra has several different methods of rendering an image. The rendering engine determines which algorithm will be used to generate the image. Though this token has an integer value, it's also possible to set the value through a string value. Possible values are

• micropoly - Micropolygon scanline rendering (default)
• raytrace - All rendering will be performed using ray-tracing
• pbrmicropoly - Physically Based Rendering using micro-polygon

  scanline rendering

• pbrraytrace - Physically Based Rendering using raytracing only
• photon - Photon map generation
• viewpohoton - View dependent photon map generation
• irradiance - Irradiance cache creation (partially implemented)
• metropolis - Phystically Based Rendering using metropolis

  integration (partially implemented)

renderer:geocachesize: (32)

The number of megabytes used for the geometry cache.

renderer:texcachesize: (32)

The number of megabytes used for texture caching. This includes all texture caching

• 2D .rat file caching
• 3D point cloud caching
• 3D volume caching

renderer:alfprogress: ("false")

Output progress in a format which can be processed by Pixar's Alfred render queue.

renderer:tilecallback: ("")

This property specifies a python callback which can be called at the completion of each tile rendered. There is a "built-in" "mantra" module which allows information to be queried. There is a single function available in the mantra module. The "property" function allows querying of any global rendering propery as well as some other special properties. The result of the property call is always a list of values. The special properties queried may be

• tile:ncomplete - The number of tiles which have been completed
• tile:ntiles - The total number of tiles in the image
• tile:laptime - The number of seconds taken to render the last tile
• tile:totaltime - The total number of seconds to render since the render began. This does not include time to load the scene, but rather is defined as the time since the first tile began rendering.
• tile:coords - The tile bounding box (in pixels).
• tile:memory - The amount of RAM in use by mantra

import mantra import sys tile = mantra.property("tile:ncomplete")(0) if tile == 1 print mantra.property("renderer:name") print mantra.property("renderer:version")

renderer:networkcompress: ("true")

Turns on compression when network rendering. This cuts down on network bandwidth significantly. This should not usually be changed.

renderer:networkbalance: ("true")

Enable network load balancing. This should not usually be changed.

renderer:dsmoptimize: ("true")

Deep shadow map optimization. This value should not usually be changed.

renderer:fogbackground: ("true")

Mantra only runs atmosphere shaders after surface shaders have been run. This means that there are no atmosphere shaders run if there are no objects rendered. When this setting is true, a giant box is created surrounding the scene. The box has a matte shader applied. The size of the box is determined by sqrt(1/3)*far_clip (the camera's far clipping plane)

renderer:usemaxthreads: ("true")

Set renderer:threadcount to the number of CPUs of the rendering machine.

renderer:hidden: ("true")

Perform hidden surface removal. When hidden surface removal is disabled, all surfaces in the camera's frustum will be rendered, regardless of whether they are occluded. This can impact render time significantly.

renderer:blurquality: ("true")

Whether to enable motion blur sampling for scanline rendering.

renderer:rayblurquality: ("true")

Whether to enable motion blur sampling for ray-traced rendering.

renderer:dofquality: ("true")

Whether to enable depth of field sampling.

renderer:rayquality: ("true")

Whether to enable ray-tracing. By disabling ray-tracing no ray-traced shadows, reflections, refractions, etc. will be performed.

renderer:giquality: ("true")

Whether to enable the irradiance and occlusion VEX functions. This also controls whether irradiance caching will be enabled.

renderer:pbrprimarycache: ("")

Specifies the method of caching for primary rays in PBR mode. This may be set to either "icache" or "photon".

renderer:pbrsecondarycache: ("")

Specifies the method of caching for secondary rays in PBR mode. This may be set to either "icache" or "photon".

renderer:pbrcausticcache: ("")

Specifies the method of caching for caustic rays in PBR mode. This may be set to either "icache" or "photon"

renderer:pbrcachedirect: (1)

The cache file will store direct illumination as well as indirect illumination.

renderer:pbrpathtype: ("diffuse")

The type of path tracing to perform in PBR mode. This may be set to one of

• diffuse - Only diffuse paths are traced
• specular - Diffuse & specular paths are traced
• caustic - Diffuse, specular and caustic paths are traced
• all - All paths are traced

renderer:pbrreflectlimit: (10)

The maximum specular bounces allowed in PBR mode.

renderer:pbrdiffuselimit: (0)

The maximum diffuse bounces allowed in PBR mode.

renderer:pbrphotonsamples: (10)

The number of photon samples in PBR mode.

renderer:pbrbias: (0.001)

The ray-tracing bias used when the PBR rendering engines are used.

image:resolution: (256, 256)

The output image resolution

image:field: (0)

The video field to render. The value may be

0 = Both even & odd fields 1 = Odd field 2 = Even field

image:bucket: (16)

The tile size of buckets used to render the image.

image:pixelaspect: (1)

The pixel aspect ratio of the output image.

image:crop: (0, 1, 0, 1)

This specifies a rectangle in screen space as (xmin, xmax, ymin, ymax), where the values are between 0 and 1. Only pixels within this region will be rendered.

image:window: (0, 1, 0, 1)

This is used in determining the camera projection. Like the crop window, this specifies a rectangle in the screen. Unlike the crop window, the window is expanded to fill the full image.

image:samples: (3, 3)

The number of x and y samples per-pixel.

image:jitter: (1)

A floating point value which adds noise to sampling patterns.

image:subpixel: ("false")

Normally, sub-pixel samples are filtered using the pixel filter defined on an image plane. When image:subpixel is true, each sub-pixel is output without any pixel filtering performed. The image:resolution property will be scaled by the image:samples property to determine the actual output image resolution. For example, if image:resolution was (1024,512) and image:samples was (4,6), the image rendered would have a resolution of 4096 by 3072. Each pixel would represent a single unfiltered sub-pixel sample.

image:samplelock: ("true")

This property will "lock" the sampling patterns from frame-to-frame. This minimizes the buzzing caused by noise when rendering animations. The noise is still present, but is more consistent frame-to-frame.

image:opacitythresh: (0)

After shading of a surface, if the Of variable is less than this threshold, mantra will consider that the surface doesn't exist and samples will be ignored.

image:opacitylimit: (0.995)

When compositing layers of transparent surfaces, when the cumulative opacity of the transparent layers is more than this threshold, the pixel will be considered opaque, allowing mantra to ignore objects which are occluded.

image:colorlimit: (1000)

When performing shading, mantra places no limits on values which may be returned. However, when performing Physically Based Rendering, it's possible to get very large values for some rays. These extrema will show cause color spikes which cannot be smoothed out without sending huge numbers of rays. The color limit is used to clamp the value of the Cf variable to avoid these spikes.

image:deepresolver: ("")

When generating an image, mantra runs the sample filter to composite samples to a single color. Mantra then runs the pixel filter to produce the final color for a pixel. A deep resolver is used to store information about each sample prior to sample filtering. This allows the image resolver to store information about each individual sample before compositing. The image:deepresolver specifies the resolver and any arguments to the resolver shadow: Deep Shadow Map Resolver Options

• filename (default = "")

  The filename to output the deep shadow information.

• ofstorage (default = "real16")

  The storage format for Of. The value should be one of

  real16 - 16 bit floating point values real32 - 32 bit floating point values real64 - 64 bit floating point values

• pzstorage (default = "real32")

  The storage format for Pz. The value should be one of

  real16 - 16 bit floating point values real32 - 32 bit floating point values real64 - 64 bit floating point values

• ofsize (default = 3)

  The number of components to store for opacity. This may either be

  1 = Monochrome (stored as the average value) 3 = Full RGB color

• compression (default = 4)

  The compression should be a value between 0 and 10. It's used to limit the number of samples which are stored in a lossy compression mode.

• zbias (default = 0.001)

  Used in compression to "merge" samples which are closer than some threshold.

• depth_mode (default = "nearest")

  Used in compression to determine whether to keep the nearest, the farthest or the midpoint of samples. The possible choices for depth_mode are

  nearest - Choose the smallest Pz value farthest - Choose the largest Pz value midpoint - Choose the midpoint of Pz values

• depth_interp (default = "discrete")

  discrete - Each depth sample represents a discrete surface. continuous - Each depth sample is part of a continuum

  (i.e. volume).

Example: "shadow filename test.rat ofsize 1"

photon:photongfile: ("global.pmap")

When renderer:renderengine is "photon", this determines the photon map file for diffuse photons (irradiance)

photon:photoncfile: ("caustic.pmap")

When renderer:renderengine is "photon", this determines the photon map file for caustic photons (specular bounces)

photon:photoncount: (100000)

The number of photons sent when renderer:renderengine is set to "photon".

photon:photongfilter: (50)

The number of photons used in pre-filtering the global map.

photon:photoncfilter: (50)

The number of photons used in pre-filtering for the caustic map.

photon:photongradius: (1)

The search radius when pre-filtering photons for the global map.

photon:photoncradius: (1)

The search radius when pre-filtering photons for the caustic map.

photon:photongratio: (1)

The probability for discarding photons during pre-filtering of the global map.

photon:photoncratio: (1)

The probability for discarding photons during pre-filtering of the caustic map.

photon:photongprefilter: ("true")

A boolean to determine whether pre-filtering should be performed on the global photon map.

photon:photoncprefilter: ("false")

A boolean to determine whether pre-filtering should be performed on the caustic photon map.

photon:photonshaders: ("false")

This property determines whether object shaders will use shaders defined by the photon contex or by the surface context when shading.

camera:projection: (0)

The camera's projection model. This may be one of

"perspective" - Perspective projection "orthographic" - Orthographic projection "polar" - Polar (spherical) panoramic projection "cylindrical" - Cylindrical panoramic projection

camera:orthowidth: (1)

When camera:projection is "orthographic", this determines the width of the projection.

camera:clip: (0.001, 1000)

Near and far clipping planes for the projection.

camera:zoom: (1)

The zoom is the ratio of the focal length to the aperture of the camera. It is used to determine the field of view of the camera.

camera:focal: (50)
camera:focus: (1)
camera:fstop: (3.402823e+38)

The camera:focal, camera:focus and camera:fstop settings control depth of field controls.

camera:curvature: (0)

Mantra is able to render using a non-flat projection plane. When the curvature is non-zero, ray-tracing will be used for primary rays. The curvature may either be greater or less than zero to mimic a wide angle or fish-eye lens.

camera:bokeh: ("radial")

Bokeh determines the "quality" of depth of field. There are three different bokeh settings

null - No depth of field box - Box shaped depth of field radial - Radial shadped depth of field.

Geometry Properties

Most of the geometry properties are set using the ray_detail statement, though it is possible to explicitly set the values.

geometry:name: ("undefined")

The name associated with the geometry. This is the name which instance objects use to access the geometry.

geometry:computeN: ("true")

Whether mantra should compute the N attribute automatically. If the N attribute exists, the value will remain unchanged. However, if no N attribute exists, it will be created. This allows polygon geometry which doesn't have the N attribute already computed to be smooth shaded.
Not supported for per-primitive material assignment (material SOP).

geometry:timescale: (1)

When the -v option is specified on the ray_detail line, this determines the time scale for velocity based motion blur.

geometry:basepath: ("")

Materials may be specified on a per-primitive basis. However, since materials refer to SHOP paths, it's sometimes important to be able to resolve relative paths.

Object Properties

Unless specified, each object property may be attached to a primitive by binding a material object to the primitive using the shop_materialpath attribute.

object:name: ("undefined")

The name of the object.
Not supported for per-primitive material assignment (material SOP).

object:categories: ("")

The space or comma separated list of categories to which this object belongs.
Currently not supported for per-primitive material assignment (material SOP).

object:id: (0)

An integer value which can be queried from within shaders.
Not supported for per-primitive material assignment (material SOP).

object:renderable: ("true")

If this option is turned off, then the instance will not be rendered. The object's properties can still be queried from within VEX, but no geometry will be rendered. This is roughly equivalent to turning the object into a transform space object.

object:phantom: ("false")

When object:phantom is turned on, the object will not be rendered by primary rays. Only secondary rays will hit the object.

object:rmbackface: ("false")

Perform backface removal on surfaces.

object:rendersubd: ("false")

Render polygons as a subdivision surface. The "creaseweight" attribute is used to perform linear creasing. This attribute may appear on points, vertices or primitives.

object:renderpoints: ("false")

Render only the points of the geometry. Two attributes control the point primitives if they exist

orient

A vector which determines the normal of the point geometry. If the attribute doesn't exist, points are oriented to face the incoming ray (the VEX I variable).

width - Determines the 3D size of the points (defaults to 0.005)

object:metavolume: ("false")

Render metaballs as volumes as opposed to surfaces.

object:overridedetail: ("false")

When geometry has shaders defined on a per-primitive basis, this parameter will override these shaders and use only the object's shader. This is useful when performing matte shading on objects.
Not supported for per-primitive material assignment (material SOP).

object:surface: ("")

The surface shader attached to the object.

object:reflectlimit: (1)

The maximum reflection bounces.

object:refractlimit: (10)

The maximum refraction bounces.

object:rayweight: (0.001)

As rays propagate through the scene, they contribute less and less to the final color of the surface. When the contribution becomes less than the rayweight, no further rays will be sent. This is similar to the renderer:opacitylimit.

object:reflectmask: ("*")
object:reflectcategories: ("*")

These parameters determine the set of objects which will be visible in reflection rays.

object:refractmask: ("*")
object:refractcategories: ("*")

These parameters determine the set of objects which will be visible in refraction rays.

object:lightmask: ("*")
object:lightcategories: ("*")

These parameters determine the set of light sources which are used to illuminate the surface.

object:biasnormal: ("false")

When biases are used in VEX shaders, the bias can either be performed along the ray direction or along the surface normal. If this parameter is turned on, biasing will be along the surface normal (in the correct direction).

object:gridedgebias: (0.01)

When shading grid edges, this bias will move the edge points slightly away from the actual grid edge. This improves bad shadowing artifacts which might be seen where two primitives meet. This is only used when micro-polygon rendering.

object:displace: ("")

The displacement shader attached to the shader

object:displacebound: (0)

The maximum bounds that the displacement shader will move geometry. This is defined in "camera" space. Note, that the absolute value is used to determine the bounds.

object:redice: ("false")

With extreme displacement, it's possible to get micro-polygons which are stretched far out of shape. Turning re-dicing on will cause the geometry to be re-diced after the geometry has been displaced. This will result in micro-polygons which have a much more uniform size and will most likely provide higher quality images. This is more costly since the displacement shader may be run multiple times during the projection process.

object:binarysplit: ("false")

When spliting primitives, this ensures that primitives are split into grids containing a power of 2 micro-polygons. This minimizes patch cracks.

object:truedisplace: ("true")

When running displacement shaders when micro-polygon rendering, this option will determine whether the VEX variable P is actually moved or whether bump mapping will be performed.

object:raytruedisplace: ("true")

When running displacement shaders when ray-tracing, this option will determine whether the VEX variable P is actually moved or whether bump mapping will be performed.

object:raypredice: ("false")

When ray-tracing, it's more efficient to pre-dice all the geometry in the scene, rather than caching portions of the geometry and re-generating the geometry on the fly. This is especially true when global illumination is being computed (since there is less coherency among rays). The object:raypredice property will cause this object to generate all the micro-polygons before the render begins. Ray tracing can be significantly faster at the cost of potentially huge memory requirements.
Currently not supported for per-primitive material assignment (material SOP).

object:perspective: ("false")

When micro-polygon rendering, motion can either be sampled in screen space or in 3D space. Turning on object:perspective will cause sampling to occur in perspective projected space. This will not match ray-traced motion blur, which is always done in 3D space.

object:rayshade: ("false")

When micro-polygon rendering, shading normally occurs at micro-polygon vertices at the beginning of the frame. To determine the color of a sample, the corner vertices are interpolated. Turning on object:rayshade will cause the ray-tracing shading algorithm to be invoked. This will cause each sample to be shaded independently. This means that the shading cost may be significantly increased. However, each sample will be shaded at the correct time, and location.
Currently not supported for per-primitive material assignment (material SOP).

object:smoothcolor: ("true")

When micro-polygon rendering, shading normally occurs at micro-polygon vertices at the beginning of the frame. This option causes the vertex colors to be Gouraud shaded to determine the color for a sample. When trying to match a background plate exactly, it's desirable to eliminate any filtering which might occur on the plate. The Gouraud interpolation will cause a softening of the map, and thus, this option should be turned off.

object:geometrygroup: ("")

Each object references a geometry object. Houdini geometry allows multiple primitive groups to be defined. If the object:geometrygroup parameter is set to a string, only the primitives which are members of the named group will be rendered by this instance. This allows multiple objects to instance the same geometry, but render different parts.
Not supported for per-primitive material assignment (material SOP).

object:shadingquality: (1)

The shading quality for scanline rendering. A higher quality will generate smaller micro-polygons meaning more shading and sampling will occur, but the quality will be higher.

object:rayshadingquality: (1)

The shading quality when ray-tracing.

object:coving: (1)

Whether crack-prevention will be performed. There are three possible levels

0 = No coving 1 = Only displaced surfaces and sub-division surfaces will be coved 2 = All primitives will be coved

object:motionfactor: (0)

Increasing the motion factor of an object will dynamically adjust the shading quality based on the rate of motion. This can significantly speed up renderings of rapid moving objects. It also affects depth of field and may improve speed of scenes with deep depth of focus.

object:flatness: (0.1)

This property controls the tesselation levels for nearly flat primitives. By increasing the value, more primitives will be considered flat and will be sub-divided less.

object:measure: ("nonraster -z 0")
object:raymeasure: ("nonraster -z 1")

When primitives are rendered in mantra, they are split into smaller primitives if they are "too big" to be rendered. The primitives are measured to determine if they are to big using the measurer. There are several different measurers available, each which take some optional arguments uniform (-s size)

Generates uniform divisions. The -s option can be used to scale the size of the micro-polygons. A larger scale will result in smaller micro-polygons.

raster

Measures geometry in screen space. This is roughly equivalent to the "nonraster -z 0" measurer, so is deprectated in favour of that approach.

nonraster (-z importance)

This measures geometry in 3D. The z-importance can be used to bias the z-component of the surface. A z-importance of 0 means that the x and y components of the object will be the only metric in determining the size of the object. This is roughly equivalent to raster space measurement. By increasing the z-importance to 1, the z measurement becomes more meaningful. It is possible to increase the z-importance beyond 1. If you think of a grid in the XY plane, the z-importance has no effect. However, if the grid is nearly in the XZ plane, z-importance has more influence on the dicing. With a z-importance of 0, only the projected measurements will be used, which will result in long, thin strips being created. With a z-importance of 1, the grid will be more uniformly sub-divided. With a value greater than 1, more divisions will be performed in Z. This is important when displacement mapping is being performed. Increasing the z-importance will improve quality on displacement shaded ground planes (for example).

object:pbrdiffusemask: (2)

When PBR samples the diffuse illumination for the surface, this determines how the illumination should be computed. Possible values are

"none" - No illumination "direct" - Direct illumination (from light sources) only "indirect" - Both direct and indirect illumination

object:pbrglossymask: (2)

When PBR samples the glossy illumination for the surface, this determines how the illumination should be computed. Possible values are

"none" - No illumination "direct" - Direct illumination (from light sources) only "indirect" - Both direct and indirect illumination

object:pbrspecularmask: (2)

When PBR samples the specular illumination for the surface, this determines how the illumination should be computed. Possible values are

"none" - No illumination "direct" - Direct illumination (from light sources) only "indirect" - Both direct and indirect illumination

object:volumestepsize: (1)

The step size used when rendering volumes. The size is specified in camera space.

object:useshadowstep: ("false")

Enable the use of a separate step size when computing shadows for volumes.

object:shadowstepsize: (1)

When computing shadows, use this step size instead of the object:volumestepsize property.

object:filter: ("box")

Some volume primitives (Image3D, Houdini Geometry Volumes) can use a filter during evaluation of volume channels. This specifies the filter and may be one of

• point
• box
• gauss
• bartlett
• blackman
• catrom
• hanning
• mitchell

object:filterwidth: (1)

This specifies the filter width for the object:filter property. The filter width is specified in number of voxels.

object:gienable: ("false")

Enable irradiance cache generation for this object.

object:gifile: ("")

The file to store the irradiance cache. If multiple objects specify the same file, the cache file will contain samples from all objects.

object:gifilemode: ("")

The read-write mode for the file. This may be either

"r" - Read only "w" - Write only "rw" - Read and write

object:gisample: (256)

The default number of samples used to compute irradiance when the shader doesn't specify it. In most cases, the shader does specify the value.

object:gierror: (0.1)

The error used to determine whether a new irradiance sample needs to be computed. Smaller values will lead to larger, but more accurate irradiance cache files.

object:giminspacing: (1.5)
object:gimaxspacing: (20)

The minimum and maximum number of pixels between nearby irradiance cache samples.

object:dorayvariance: ("true")

When ray-tracing VEX functions are invoked, send out additional rays to perform anti-aliasing of ray-traced effects. This will typically generate higher quality ray-tracing. The sampling is determined by image:minraysamples and image:maxraysamples.

object:variance: (0.05)

The variance threshold to send out additional anti-aliasing rays. When near-by samples are very similar, fewer anti-aliasing rays will be sent out. When near-by samples are different, more rays will be sent.

object:minraysamples: (1)

The minimum number of ray-tracing samples used in variance anti-aliasing.

object:maxraysamples: (9)

The maximum number of ray-tracing samples used when variance anti-aliasing.

object:traceblur (false)

Enable or disable raytrace motion blur for micropolygon rendering and photon map generation. By default, raytrace motion blur is disabled. This setting has no effect on the ray tracing rendering engines.

Atmosphere Properties

fog:name: ("undefined")

The name of the fog object.

fog:categories: ("")

The category membership list for the fog object.

fog:lightmask: ("*")

A pattern of lights (by name) which are used to illuminate the fog object.

fog:lightcategories: ("*")

A pattern of lights (by category) which are used to illuminate the fog object.

fog:shader: ("")

The VEX shader used to shade the fog object.

Light Properties

light:name: ("undefined")

The name of the light source.

light:categories: ("")

The category membership list for the light object

light:shader: ("")

The shader used to compute the illumination of the light source

light:shadow: ("")

The shader used to compute occlusion of light from the light source.

light:shadowmask: ("*")

The pattern of object names which are considered for ray-traced shadows.

light:shadowcategories: ("*")

The pattern of object categories which are considered for ray-traced shadows.

light:projection: (0)
light:zoom: (1, 1)
light:orthowidth: (1, 1)

These parameters determine the projection of the light source. These are used when computing NDC (Normalized Device Coordinates) from within VEX shaders.

light:activeradius: (-1)

The active radius of the light source can be used to optimize renders. When illuminating a surface, only surfaces within the active radius will be considered. Example: Consider a car tunnel with lights every 10 meters. If the light has a sharp falloff, then it's possible to have 1000's of lights and still render in a reasonable amount of time. No shaders will be run (neither the illumination nor the shadow shader).

light:__nondiffuse: ("false")
light:__nonspecular: ("false") light:__nondirect: ("false")

These three controls allow the behaviour of the light shader to be fine tuned.

__nondiffuse: The light will not contribute to diffuse() calls __nonspecular: The light will not contribute to specular() calls __nondirect: The light is only used on secondary GI bounces

light:areashape: ("")

The area shape for the light. The choices are

"point" - No area shape "line" - Line light (unit line along x-axis) "grid" - Grid light (unit square in XY plane) "disk" - Circle shaped light (radius 0.5 in XY plane) "sphere" - Sphere shaped light (radius 0.5) "environment" - Sphere shaped light (infinite radius)

light:areasize: (0, 0)

The size of the area light. The sizes are interpreted slightly differently for each shape

line - Only the X size is used grid - The X & Y size of the grid disk - The X & Y radii of the circle sphere - The average of the sizes is used as the radius environment - Ignored

light:areasamples: (16)

The number of illumination samples to be used for the light source.

light:areafullsphere: ("false")

For the environment light, whether the light source represents the full sphere or the upper hemi-sphere

light:areausemap: ("false")

Only used for the environment light. This determines whether the the light:areamap parameter will be used.

light:areamap: ("")

Only used for the environment light. This specifies an environment map which is used for illuminating the scene. The map may be an HDRI map.

light:pbrsampled: ("true")

If this is true, the map attached to the environment area light will be analyzed to determine the best sample locations for illumination points. This should be turned on for maps which have very sharp discontinuities in illumination levels. For maps which are fairly uniform in color, the toggle should be turned off. With the toggle turned off, the sphere geometry will be used (which provides less noise for smooth maps).

light:photontarget: ("*")

When sending photons from this light source, this is the category expression to determine which objects will receive photons.

Python And Mantra

There are two places where mantra can call Python. This allows users to fine-tune mantra's processing of data.

The first place Python may be invoked is during the processing of the IFD. As the IFD is parsed, a filtering callback may be invoked to query and change properties.

Python may also be called at the completion of every tile. This allows more sophisticated statistical analysis of the rendering process to be performed.

When python is invoked from mantra, it's possible to import the "mantra" module. The mantra module has two functions

• property(name)

  This returns the value associated with the property name. The value will always be returned in a list, even if there's a single scalar value.

• setproperty(name, value)

  This function will set the named property to the value given. The function only works in filtering callbacks (not tilecallbacks). For properties which expect multiple arguments (like object:surface), the value should be given as a list or tuple of arguments. For properties which take a single value, the value can be passed verbatim (see the example below)

Python Filtering

The -P option on mantra is used to specify a python program which is invoked during parsing of the IFD. Multiple python programs may be specified by separating the programs using semi-colons. The program may also take arguments which are passed in the first time the program is invoked. These arguments may be used to control the IFD callbacks.

There are 7 separate callbacks which may exist in the filter program

1. filterGeometry()

   If the module contains this function, it will be called just prior to the ray_end statement which locks off a geometry object. This allows the program to query geometry: settings and alter them if they choose.

2. filterMaterial()

   Mantra has material blocks which can be applied on a per-primitive basis. If the filter module has this function, it will be called before a material is locked off. Properties may be added or changed to materials at this time.

3. filterInstance()

   If the module contains this function, it will be called just prior to the ray_end statement which locks off the settings for an instance object. This allows the program to query object: settings and alter them if they choose.

4. filterLight()

   If the module contains this function, it will be called just prior to the ray_end statement which locks off the settings for a light object. This allows the program to query light: settings and alter them if they choose.

5. filterFog()

   If the module contains this function, it will be called just prior to the ray_end statement which locks off the settings for a fog object. This allows the program to query fog: settings and alter them if they choose.

6. filterCamera()

   If the module contains this function, it will be called just before the global properties are locked off for the render. This is usually prior to the declaration of any objects in the IFD. If global properties are changed after this, they most likely will have no effect.However, since this callback is invoked before any lights or instances are declared, it's possible to set any light or instance properties in this callback. Instance/Light properties set here will be applied to all objects which do not declare the property explicitly.

7. filterRender()

   If the module contains this function, it will be called just before the ray_raytrace command is run. It's not possible to change any properties at this time in the IFD processing. However, for statistics or validation, it might be useful to have this method available.

    #
    # Simple Example Filter
    #

    import sys, mantra

    Verbose = False

    # Process any arguments during initialization of the module
    for arg in sys.argv[1:]:
        if arg == '-v':
            Verbose = True

    # A callback to change the surface shader of all objects
    def filterInstance():
        if Verbose:
            print 'Filtering:', mantra.property('object:name')
        catstr = mantra.property('object:categories')[0]
        categories = catstr.split(', ')
        mantra.setproperty('object:surface',
                           'plastic diff 1 0 0'.split())
        for c in categories:
            if c == 'pass1':
                mantra.setproperty('object:renderable', 0)
            elif c == 'pass2:
                mantra.setproperty('object:surface', 'matte')
                mantra.setproperty('object:overridedetail', 1)

Tile Callbacks

The renderer:tilecallback property is used to specify a python program (and arguments) which is invoked after each tile is completed. Unlike the Python filters, only one callback may be specified (commands may not be semi-colon separated). The tile callback is not permitted to call mantra.setproperty(). However, there are some additional properties which can be queried which might be useful for statistics

• tile:ntiles - The total number of tiles in the image
• tile:laptime - The number of seconds taken to render the last tile
• tile:totaltime - The total number of seconds to render since the render began. This does not include time to load the scene, but rather is defined as the time since the first tile began rendering.
• tile:coords - The tile bounding box (in pixels).
• tile:memory - The amount of RAM in use by mantra

    import sys,mantra

    tile = mantra.property('tile:ncomplete')[0]
    if tile == 1:
        # This is the first tile rendered in the image
        print mantra.property('renderer:name')
        ntiles = mantra.property('tile:ntiles')[0]
        prev_pct = -1
        lap = 0
        lsum = 0

    lap += mantra.property('tile:laptime')[0]
    pct = tile*100/ntiles
    if pct != prev_pct:
        mem = mantra.property('tile:memory')[0]
        total = mantra.property('tile:totaltime')[0]
        fpct = float(tile)/float(ntiles)        # Percent complete
        prev_pct = pct
        print('%03d%% Complete - Laptime %g/%g - ETA %g seconds\n' %
                (pct, lap, total, total/fpct))
        lap = 0         # Reset the lap counter