mental ray

When started from a shell command line, the mental ray rendering software accepts a large number of options. Most of these correspond to similar commands or camera and options statements in the scene file. When an option is given on the command line it will override the related command or statement in the scene file, which in turn overrides the built-in default settings. Certain command line options given below have a default choice that applies only if the corresponding setting is not present in the scene file.

mental ray is started as

ray options [scenefile]

If no scene file is given, the scene is read from standard input. Scene file names normally end in .mi. If the extension is missing mental ray will read the name as specified, and if this fails, retry with .mi added.

The command-line options can be abbreviated as long as the given substring is unambiguous. mental ray checks for ambiguities and prints an error message listing the choices. For example, -resolution can be abbreviated as -res. For frequently-used options such as -verbose and -filename, short forms are available. The available options are:

-acceleration bsp|bsp2 3.6|largebsp

Selects the standard binary space partitioning ( BSP) algorithm, or the new bsp2 algorithm tobe used for the large scenes and scenes with assemblies. The largebsp algorithm is kept for the compatibility. The default is BSP. All these algorithms accelerate ray tracing.

-ao on|off 3.6

Can be used to disable ambient occlusion support completely. Default is on. Actual computation is performed on demand of shaders only.

-ao_rays nrays_int 3.6

Number of rays to compute ambient occlusion. The default is 256.

-ao_cache on|off 3.6

Toggle ambient occlusion cache precomputation. Default is off.

-ao_cache_density density 3.6

Maximum ambient occlusion cache points density per pixel. Default is 1.0.

-ao_cache_points points 3.6

Ambient occlusion cache points to lookup. The default value is 64.

-approx [options]--

Specifying override approximations on the command line. Override approximations override any object approximations in the scene file. They are primarily useful for fast preview rendering, where approximation accuracy is not required. The following options can be specified:

`view`	view-dependent approximation
`fine`	fine approximation with microtriangles
`sharp`	faceted, useful for fine displacement
`parametric` U V	rectangular grid of `U × V` triangles
`regular` U V	rectangular grid that spans patches
`length` L	triangle edge length less than D
`distance` D	distance from true surface less than D
`angle` A	angle between neighboring triangles less than A degrees
`any`	any of length, distance, and angle is satisfied
min max	subdivide at least min and at most max times, default 0 5

Except for any, which must be spelled out, all options can be abbreviated by their first letter. If no options are specified ( -approx -- ), parametric 0 0 is used, which produces a very fast low-quality approximation. See the scene description chapter for detailed information on approximations.

-approx_displace [options]--

This option is similar to -approx and accepts the same options, but sets the override approximation for displacement. If no options are given, it defaults to parametric 0 0, which is so low that most displacements turn into a vaguely bumpy surface. High-quality displacement requires an approximation like

-approx fine view length 0.25 0 7 --

-aperture aperture

The aperture is the width of the viewing plane. The height of the viewing plane is aperture divided by aspect.

-aspect aspect

This is the aspect ratio of the camera. The default is 1.33. In camera space, aperture is the width of the viewing plane, and aperture divided by aspect is the height. The viewing plane is divided into pixels as specified by the resolution viewdef, so the aspect will result in nonsquare pixels if it is not equal to the X resolution divided by the Y resolution.

-assembly_path "path1:path2:…" 3.6

Specifies a directory where assembly files are stored. By default, assembly files are searched in the current working directory.

-bsp_depth depth_int

The maximum number of levels in the BSP tree. This option is used only if binary space partitioning is enabled. Larger tree depths reduce rendering time but increase memory consumption, and also slightly increase preprocessing time. The default is 40.

-bsp_size size_int

The maximum number of primitives in a leaf of the BSP tree. Larger leaves will be subdivided unless the bsp_depth is reached. This option is used only if binary space partitioning is enabled. Larger leaf sizes reduce memory consumption but increase rendering time. The default is 10.

-bsp_shadow on|off

Allow mental ray to create a separate shadow BSP tree to accelerate raytraced shadows. It can greatly improve speed if shadows are cast by simplified shadow-only objects because it is no longer necessary to populate the master BSP tree with large hero objects. This mode is off by default.

-caustic on|off

Enable or disable the generation of caustics in an appropriately defined scene. The default is off.

-caustic_accuracy nphotons [radius]

The number of photons used to estimate caustics during rendering and the maximum radius to be used when picking up the photons. The number of photons may be set to 0, which means that all photons within the given radius are used. The defaults are 100 and a scene-size dependent radius.

-caustic_merge distance

To reduce photon map size, merge caustic photons which are closer than the specified distance.

-caustic_scale rgb[a]

Caustics are multiplied by the specified color. Factors greater than 1.0 make the caustic brighter.

-clip hither yon

The hither (near) and yon (far) planes are planes parallel to the viewing plane that delimit the rendered scene for scanline rendering. Raytracing is not affected. Points outside the space between the hither and yon planes will not be rendered. The defaults are 0.001 and 1000000.0.

-code "filename" ... --

The named filename is interpreted as a C source file (ending with the extension ".c") and compiled and linked into mental ray.

-colorclip rgb|alpha|raw

This option controls the rules used to clip an RGBA color before quantization to an 8-bit or 16-bit frame buffer. The rgb mode states that RGB are first to be clipped to the range [0,1] before A is clipped to [max(R,G,B),1]. This is the default mode. The alpha mode lets A first be clipped to [0,1] before RGB is clipped to [0,A]. Both of these modes ensure that all channels are within [0,1] and that A is no less than any of R, G, and B, which is is the valid domain of premultiplied colors. The third mode, raw, ignores all requirements, and clips both A and RGB to [0,1]. This is useful to make mental ray modify output colors as little as possible. Because the color output may be invalid, the raw mode overrides the premultiply off option if present. Desaturation is always applied if enabled. Since mental ray 3.5, color clipping is applied to the color averaged over the time if motion blur is rendered.

-contrast r g b[a]

The contrast controls oversampling. If neighboring samples differ by more than the color r, g, b, a, oversampling is done as specified by the sampling options. The default is 0.1 0.1 0.1 0.1. If missing, the default for a is the average of r, g, and b. Note that this option has no effect with the rasterizer.

-c_compiler "filename"

If this option is given, the standard C compiler "cc" is replaced with filename.

-c_flags "options"

The options string replaces the standard options given to the C compiler. The defaults depend on the machine type. If the options begin with two plus signs^2.1, such as "++ -I.", it is inserted into the default options instead of replacing them.

-c_linker "filename"

If this option is given, the standard linker "ld" is replaced with filename.

-desaturate on|off

If a rendered sample returns an RGBA color whose components are outside the legal range, mental ray will clip the color into this legal range. This option determines how the clipping of R, G, and B is performed. If desaturation is turned off, which is the default, the components are clipped individually. If turned on, then if any of R, G, and B exceed the allowed range, the color is shifted towards the grayscale axis of the color cube in order to try to maintain the perceived brightness of that color, effectively bleaching out the color. The valid range of RGBA is controlled by the colorclip option.

-diagnostic bsp depth|size

This diagnostic mode can be used to visualize the parameters for BSP tree parameters (see -bsp depth and -bsp size options), to find the reason for unexpected large depths or sizes reported after rendering. This does not work in largebsp nor bsp2mode because they never create a single fixed BSP tree from which consistent diagnostics could be computed.

-diagnostic grid off|object|world|camera size

This diagnostic mode is intended for scene debugging. Unless set to off, it draws a colored grid on all objects in the scene that shows object, world, or camera space coordinates. Steps on the X, Y, and Z axes are shown with red, green, and blue grid lines, respectively. The distance between grid lines is size units. This is useful to estimate the size and distances between objects in mental ray, or to visualize object space coordinates. The off argument disables the grid, which is the default.

-diagnostic hardware solid|wire|window|debug

Hardware rendering diagnostics. The solid mode turns off shading and uses a default gray material. The wire mode does not shade at all but displays the wire-frame model only. The window mode pops up a window on the screen, showing rendering progress. The debug mode enables Cg compiler debugging. Disabled by default.

-diagnostic photon off|density|irradiance max

When rendering caustics or global illumination, this option disables all material shaders in the scene and produces a false-color rendering of photon density, or the average of the red, green, and blue irradiance components. Photon density is the number of photons per unit surface area. max is the density (or irradiance) that is assigned to 100%, or red. The colors are, from 0% to 100%: Blue, cyan, green, yellow, and red. Higher values fade to white. max can be given as zero in which case the appropriate maximum is automatically found. This is done after the whole image has been rendered. This mode is useful when tuning the number of photons in a photonmap and setting the various _accuracy options, since the density (or irradiance) is estimated using those settings. The default is off.

-diagnostic samples on|off

Switch to sampling visualization mode and create grayscale images representing sampling densities instead of color images. A black pixel has had no samples, whereas a white pixel has had the maximum amount as specified by the -samples option. In addition, a red grid shows task rectangle boundaries. Off by default.

-diagnostic finalgather

This mode shows final gathering points, as green dots for initial raster-space final gathering points, blue dots for final gathering points from per-object finalgather map files, and red dots for render-time final gathering points.

-displace on|off

Ignore all displacement shaders if set to off. The default is on.

-displace_presample on|off

Enables or disables presampling of displacement-mapped geometry. Presampling increases performance by introducing a preprocessing phase before tessellation, and is enabled by default. If turned off, rendering begins earlier but takes longer; this is sometimes useful for preview rendering.

-dither on|off

Ditheringdithering mitigates 8-bit and 16-bit color quantization errors by introducing noise into the pixel such that the round-off errors are randomly distributed. The default is off.

-echo "filename" [ascii] [source] [approx] [norendercommand] [textures] [incremental] [omit "S"] [norecurse "S"] [explode [N]] --

Echo the current scene to the file filename. The options specify the format of the echoed file. Allowed options are: ascii uses ASCII format for the vectors (default is binary), source prefers source geometry over triangles if available (default), approx prefers triangles over source geometry if available, norendercommand disables the echo of the render command, textures includes texture pixel data verbatim. incremental causes multiframe animations to be echoed in a more compact format, by omitting scene elements that did not change since the previous frame. omit specifies that certain types of elements, specified by S, should be omitted from the output. It is supported by mental ray 3.0 only. Note that both omit and norecurse will produce incomplete and nonrenderable scene files. These options are useful for extracting subsets of a scene. norecurse specifies that references of certain types of elements specified by S should be omitted from the output. It is supported by mental ray 3.0 only. For example, if S contains icil, instances of cameras and lights would be echoed (unless disabled by omit), but the instanced camera or light would not be echoed first. The S strings of the omit and norecurse attributes are sequences of the following codes:

code	element	affected statement
`g`	instance group	`instgroup`
`o`	geometric object	`object`
`c`	camera	`camera`
`l`	light source	`light`
`m`	material	`material`
`t`	texture	`texture`
`p`	option block	`options`
`s`	named shader	`shader`
`d`	declaration	`declare`
`u`	user data	`data`
`ig`	instance of an instance group	`instance`
`io`	instance of an object	`instance`
`ic`	instance of a camera	`instance`
`il`	instance of a light	`instance`
`is`	instance of a geometry shader	`instance`

Note that triangle echos have displacement mapping already applied to the triangles, but the displacement shaders are not removed from the materials so the echoed file will get displaced twice when rendered. The echo option must be terminated with a double minus. explode causes all objects with more than N vertices to be written to a separate file with a name beginning with autoload. This file will be referenced by a placeholder object with an appropriate file statement in the main echo file. If omitted, N defaults to 1; a typical good value is 10000 to make sure that the overhead of opening a file is not wasted on really small objects.

-face front|back|both

The front side of a geometric object in the scene is defined to be the side its normal vector points away from. By specifying that only front-facing triangles are to be rendered, speed can be improved because fewer triangles need to be tested for a ray. The default is face both.

-fb_dir "directory"

Specifies a directory for temporarily storing frame buffer files. If this option is not provided, the environment variables TMPDIR and TEMP are examined. If they are also not defined the current working directory is used for storing memory mapped frame buffer files.

-fb_virtual on|off|cache 3.6

Controls storage of frame buffers in files on disk to conserve memory. Default is on, which enables disk storage in memory mapped files. The cache3.6 option enables frame buffer caching, which only stores frame buffer fragments in disk files on demand. This option may save significant amount of memory when rendering very high resolution images, especially on 32bit systems. File storage can be disabled completely by setting the option to off, for example to gain speed on systems where sufficient memory is available.

-file_dir "path"

If set then all output images are written to the given directory path. This is especially useful for animations with multiple frames.

-file_name "filename"

Overrides the file name given by the first file output statement in the camera definition in the scene file. The full file or path name must be given, including extension if desired.

-file_type "format"

Overrides the file format given by the first file output statement in the camera definition in the scene file. File formats include "pic" for Softimage image files, "rla" for Wavefront RLA files, and "ps" for PostScript files if contour mode is enabled.

-filter[clip] box|triangle|gauss|mitchell|lanczos width[height]

This option specifies how multiple samples in recursive sampling mode are to be combined. The filter defaults to a box filter of width and height 1. The filter size can also be specified, in pixel units. Good filter sizes are 1.0 for box, 2.0 for triangle, 3.0 for gauss, and 4.0 for mitchell and lanczos. mental ray 3.2 and up also support clip mitchell and clip lanczos to clip the filter result to the sample range under the filter, which avoids ringing in these filters because they contain negative coefficients. This option requires a sampling density of at least -1 0.

-finalgather on|off|only|fastlookup

Enables or disables final gathering. It is disabled by default. Final gathering is a rendering technique used for computing indirect illumination with a one-generation raytracing step. mental ray 3.0 added a third choice, fastlookup, that enables final gathering and also arranges for irradiance to be stored in the photon map. This slows down photon tracing but greatly accelerates final gathering. mental ray 3.3 added the only keyword, which computes the finalgather map and skips rendering.

-finalgather_accuracy[view] nrays_int [maxdist[mindist]]

nrays is the number of rays cast in a final gathering step during rendering. The default is 1000. maxdist is the maximum distance within which a final gather result can be reused. The default is scene dependent. mindist is the minimum distance within which final gather results must be reused. The default is scene dependent. Both distances are specified in world space units, or raster space units if view is specified.

-finalgather_contrast r g b[a]

Similar to contrast, but controls the adaptivity in the final gather pre-computing. The default value is contrast.

-finalgather_depth reflect_int [refract_int [diffuse_int [sum_int]]]

This option is similar to -trace_depth but applies only to finalgather rays. The defaults are all 0, which prevents finalgather rays from spawning subrays. This means that indirect illumination computed by final gathering cannot pass through glass or mirrors, for example. A depth of 1 (where the sum must not be less than the other two) would allow a single refraction or reflection. Diffuse bounces can also be controlled. It is not normally necessary to choose depths greater than 2. This is not compatible with mental ray 3.1 and earlier, which used the trace depth (which defaults to 2 2 4) for final gathering.

-finalgather_display on|off

Allows image previewing during the finalgather presampling stage if the imf_disp viewer is attached to the output image file. This is disabled by default. The quality of the preview image is very low, but it allows fast detection of illumination problems in a scene. This option has no impact on the final image. To improve performance it is recommended to disable this option for non-interactive rendering.

-finalgather_falloff[start]stop

Limits the length of final gather rays to a distance of stop in world space. If no object is found within a distance of stop, the ray defaults to the environment color. The start parameter defines the beginning of a linear falloff range; objects at a distance between start and stop will fade towards the environment color. This option is useful for reducing memory usage for the geometry cache.

-finalgather_file "name" ["name" "name" … ]−−

Tells mental ray to use the given file(s) for loading and saving final gather points. Only the first file is used for writing and upgrading, any additional files are only read and merged. If the finalgather file does not exist, it is created and the complete final gather map is saved. If mental ray creates extra final gather points, they are appended to the (first) file. This means that the file may grow without bounds. If first name is off the feature is disabled.

-finalgather_filter size_int

Final gathering uses an speckle elimination filter that prevents samples with extreme brightness from skewing the overall energy stored in a finalgather hemisphere. This is done by filtering neighboring samples such that extreme values are discarded in the filter size. The default is 1; 0 turns speckle elimination off and greater values remove more speckles and soften contrasts. Sizes greater than 4 or so are not normally useful.

-finalgather_modemode

Select one of the four finalgather modes. 3.4 and strict3.4 are the compatibility modes. The former one focuses on usage of the same argument set, but with rendering improvement, The latter focuses on rendering identical or very similar images as mental ray 3.4. The automatic mode primarily targets rendering of single still images. The multiframe mode targets rendering of the camera fly-through animations. Both use the finalgather points argument for the approximate resp. minimal number of final gather points used in interpolation. In both mode, all finalgather points are produced in the finalgather precomputing stage. For the multiframe mode, the finalgather accuracy max radius is used to limit the maximal validity distance of a finalgather point to avoid picking up illumination from remote objects if the density of finalgather points is insufficient. See also the functionality description and scene file syntax.

-finalgather_pointsP_int

In the automatic and multiframe finalgather modes, the number of finalgather points used for interpolation of the indirect illumination.

-finalgather_presample_densityT

This option controls the density of initial finalgather points created during preprocessing (green dots in the diagnostic image). It increases (decreases if T < 1) the number of precomputed finalgather points approximately T times.

-finalgather_rebuild on|off|freeze

If a filename is specified using the -finalgather_file option, it is normally loaded and used if the file exists. -finalgather_rebuild on causes existing files to be ignored, all final gather points will be recomputed and an existing file will be overwritten. freeze is equivalent to on, except that the final gather map, once created by reading it from a file or building it in the first frame, will never be modified. Extra finalgather points created during rendering will not be appended, and the finalgather file on disk will not be modified.

-finalgather_scale r g b[a]

The irradiance obtained from first bounce final gathering is multiplied by the specified color, making the irradiance effect brighter for factors greater than 1.0. Note that this option applies to a single bounce only.

-finalgather_secondary_scale r g b[a]

The irradiance obtained from secondary bounce final gathering is multiplied by the specified color, making the irradiance effect brighter for factors greater than 1.0.

-focal distance|infinity

The focal distance is set to distance. The focal distance is the distance from the camera to the viewing plane. The viewing plane is the plane in front of the camera that the rendered scene is projected onto; its edges correspond to the edges of the rendered image. If infinity is used in place of the distance, an orthographic view is rendered.

-gamma gamma_factor

Gamma correction can be applied to rendered color pixels to compensate for output devices with a nonlinear color response. All quantized R, G, B, and alpha component values (ie. not if the frame buffer is floating-point or RGBE) are raised to gamma_factor. The default gamma factor is 1.0, which turns gamma correction off. The reverse correction is applied to all quantized texture images.

-geometry on|off

Ignore all geometry shaders if set to off. The default is on.

-globillum on|off

Enable or disable the computation of global illumination. The default is off. To actually compute global illumination, lights must have an energy, and materials must have photon shaders.

-globillum_accuracy nphotons_int [radius]

The number of photons used to estimate global illumination during rendering and the maximum radius to be used when reading photons during rendering. The defaults number of photons is 500. If nphotons is set to 0, all photons within the given radius are used. The default radius is scene size dependent.

-globillum_merge distance

To reduce photon map size, merge globillum photons which are closer than the specified distance.

-globillum_scale r g b[a]

The irradiance obtained from the globillum photonmap lookup is multiplied by the specified color, making the effect brighter for factors greater than 1.0.

-H "path"

Specifies the directory where hardware shaders are located. This is a shorthand for hardware_path.

-hair on|off

Hair rendering can be enabled or disabled from the commandline with this switch. This can be useful for faster test renders without the full effects. The default is on.

-hardware off|on|all --

Specify which objects should be rendered with hardware rendering: off disables hardware rendering (this is the default), on uses hardware rendering for all materials that specify a hardware shader, and all uses hardware rendering for all objects and tries to find hardware substitutes for materials that do not specify an explicit hardware shader. The most useful mode is all. Note that this option only selects which objects are eligible for hardware rendering, but mental ray may still fall back on software rendering for objects for which no appropriate hardware shaders are available. This is controlled separately by the following options.

-hardware cg|native|fast* -- [force]

This option controls how hardware shaders are selected for an object that is eligible for hardware rendering, as specified by the previous option. mental ray will try all approaches allowed by this option in turn: cg means that mental ray will first look for shaders implemented in NVIDIA's Cg 1.2 shader programming language. This is the default. native looks for shaders implemented in the OpenGL 2.0 native shader programming language, which is less powerful than Cg. fast uses hardcoded OpenGL materials that do not involve programmable shaders at all. This is limited to simple Gouraud models. force specifies that the search stops here, and objects that cannot use any of the above methods use a simple gray default material. If force is not specified, mental ray will fall back on software rendering for the object. The hardware options can be combined. For example, -hardware all cg native fast force -- will render all objects with the best available hardware shading method but never with software; this is useful for fast preview rendering. The option -hardware all cg native -- is best for quality rendering, and so on.

-hardware_echo [error]"path"

Write the Cg source code as it is passed to the Cg compiler and the resulting assembly code to disk, to the directory path. If the error option is specified, only those files are written for which compilation has failed. This is useful for debugging, and to extract shader code from mental ray for use in game engines or other standalone applications.

-hardware_path "path"

Specifies the directory where hardware shaders are located. Can also be abbreviated as -H.

-hardware_samples multi_int super_int

Specify the multisampling and supersampling rates to be used for hardware rendering. Multisampling is done by the hardware pixel pipeline, which takes more samples per triangle and writes the result to the frame buffer. Supersampling is done by mental ray, by increasing the frame buffer size and rendering at a higher resolution, and then downfiltering to the requested frame buffer resolution. Multisampling is much faster and does not increase hardware video memory usage (or even exceed the GPU resolution capacity), but supersampling looks better.

-help

Print a summary of all options with their allowed parameters, and terminate.

-hosts "hostname [:portnumber] [remote parameters]"… --

The machine list overrides the machine list taken from the .rayhosts file, if present. One slave is started on each machine specified. Machine names must be given as expected by the local name resolving method (such as /etc/hosts) or as a numeric IP address ( nnn.nnn.nnn.nnn).

-I "path1:path2:…"

Overrides the path used to resolve $include commands in the .mi scene file. The default path contains the directories ., {_MI_REG_INCLUDE}, /usr/local/mi/rayinc, /usr/include, and /usr/include/mi. Note that only one -I option can be specified. It may contain a colon-separated ( Unix only) or semicolon-separated (Unix and Windows NT) list of directory paths that are tried in sequence if a $include command using angle brackets is used in the .mi scene file. Paths introduced with an exclamation point are special; they are applied to quoted $include paths too, and substitute the entire directory path. This can be used to force mental ray to use a specified path regardless of the path specified in the $include command, for example because that path points to an obsolete version of a declaration file. For example, -I /a:/b:!/new tries to find a path <x/y/z> first as /a/x/y/z, then /b/x/y/z, then /new/z.

-imgpipe fd_int

Normally mental ray prints connection information into the output image file that let programs like imf_disp connect and display images while being rendered. If -imgpipe is used, the relevant information is printed to the given file descriptor fd instead. This can be used for command lines such as

ray -imgpipe 1 scene.mi | imf_disp -

The imf_disp program is a viewer provided by mental images that supports image piping.

-importon on|off 3.6

Control the emission of importons. The default is off.

-importon_density density 3.6

The density of importons that are emitted from the camera per pixel, on average. The default is 1.0, which means that one importon for each pixel will be emitted on average. Values lower than 1.0 mean less importons and thus coarser photon distribution for more speed but less quality. Values greater than 1.0 create more importons and thus finer photon distribution.

-importon_trace_depth depth 3.6

The maximum number of bounces that are allowed for importons. The default is 0 (that is, no diffusion). The higher this value, the more importons will get diffused in the scene. Note though that photon shaders might decide not to diffuse them anyway.

-importon_traverse on|off 3.6

Enables the complete traversal of the scene for importons, that is they will be stored for all intersections of the ray with the objects of the scene from the camera to infinity. The default is on. This means that more importons are being stored in the scene (and hence more photons later during photon shooting) to remove or reduce artifacts due to photon distribution discontinuities.

-ip on|off 3.7

Enables irradiance particles. This may enforce other options in mental ray which are not compatible to be disabled or ignored. The default is off.

-ip_rays nrays_int 3.7

Controls the number of rays shot while estimating the irradiance. This value has similar meaning to the number of rays used for final gathering, but specifies a maximum number. Irradiance particels typically deliver better quality compared to final gathering used with the same number of rays. The minimum is 2. The default value is 256.

-ip_indirect_passes n_int 3.7

Sets the number of possible passes of indirect lighting. If this number is 0 then irradiance particles will carry just direct illumination. Higher values enable computation of a sequence of passes to collect the irradiance coming from multiple indirect illumination bounces, which will be added to the irradiance particles. The default value is 0.

-ip_scale [r g b]a 3.7

This is a global scale factor applied to the intensity of the irradiance during rendering. Values different from default do not lead to a physically correct rendering but are useful for artistic purposes. A single value may be specified which is applied to all R, G, and B color components, or individual values can be given for each color component. The default value is 1.0.

-ip_interpolate mode_int | "string" 3.7

Control the use of interpolation. It can either be a numeric value or a string. 0 means no interpolation, 1 means interpolate always, and 2 means interpolate only for secondary rays (that is, no interpolation for eye rays and interpolation for reflections, retractions, etc). Alternatively, the strings "never", "always" or "secondary" may be used. The default value is "always".

-ip_interppointsn_int 3.7

Sets the number of irradiance particles used for the lookup interpolation. The default value is 64.

-ip_env on|off 3.7

This flag enables the use of the environment maps for irradiance computation. If enabled then a separate particle map is built just for the environment (if an environment shader is present) and used during rendering for image based lighting. The default value is on.

-ip_env_rays nrays_int 3.7

Controls the number of rays used for the computation of irradiance coming from the environment map. This number can be greater than the number of rays used for normal irradiance computation, especially if most of the environment is covered by scene geometry (like in a room with just one or two windows). For outdoor scenes, a smaller number of rays is often sufficient. The default is equal to the number of irradiance particle rays.

-ip_env_scale [r g b]a 3.7

A global scale factor applied just to the irradiance contribution from the environment. The resulting irradiance will be further scaled by the global irradiance particle scale value. A single value or individual values per color component may be given, in the same way as for the general scale. The default value 1.0.

-ip_file "name" 3.7

Specifies the file name for the irradiance particle map on disk. If the file exists, mental ray will try to read the irradiance particle map from it unless the rebuild option is enabled. If the irradiance particle map can't be read from the file mental ray will compute it and save it to a file with the given name. This is consistent with the option for photon maps, for example. The default is no name, i.e. irradiance particles are not associated with a file.

-ip_rebuild on|off3.7

If set to on, mental ray will compute the irradiance particle map even if a file with a name given with the previous string option exists. If set to off, then mental ray will either read it from a file if specified, or it will reuse the irradiance particle map coming from the previous frame in an animation, useful to avoid flickering in fly-throughs. Note, the irradiance particle map may lose quality if objects or camera are moving. The default value is on.

-jitter jitter

The jittering factor introduces systematic variations into spatial sample locations if jitter is set to 1.0, which is the default. Jittering can be disabled by specifying a jitter of 0.0.

-L "path1:path2:…"

This is an abbreviation for -ld_path.

-ld_libs "libraries "

The libraries string replaces the standard library options given to the linker. The defaults depend on the machine used, typically "-lm -lc". Linker options are machine dependent and operating system dependent and cannot be changed.

-ld_path "path1:path2:…"

Supply a list of library search paths that mental ray searches for shader libraries containing shader code. The paths given here precede those that can be given by the environment variable MI_LIBRARY_PATH and the built-in search path (consisting of the directories {_MI_REG_LIBRARY}, /usr/local/mi/lib, and .; see page regpath).

-lens on|off

Ignore all lens shaders if set to off. The default is on.

-lightmap on|off|only

This mode enables rendering of lightmaps. By default, lightmaps are enabled. If this option is set to only, only the lightmaps but not the camera images are rendered.

-lightprofile_path "path1:path2:…"

File search path for light profiles.

-link "filename" … --

Like the code command, the link command attaches external shaders to mental ray, which can then be used as shading functions. While the code command accepts ".c" files as filename, the link command expects either object files ending in ".o" or ".obj", or shader library files ending in ".so" or ".dll".

-maxdisplace dist

This option overrides all max displace values in scene objects with dist if dist > 0. This is useful to render old scene files built for mental ray 1.x or 2.x, which did not support max displace, and so would fail to show any displacement when rendered with mental ray 3.x.

-memory limit

The limit argument specifies the size of mental ray's total memory usage in megabytes, including heap (non-scene data), scene database, and virtual memory. The default is 1000 (~1GB) on 32bit systems, and 0 (unlimited) on 64bit systems. Note, that high values can result in out-of-memory situations with very large scenes, and should be set to be somewhat lower than the actual amount of memory that is available to a process on the specific machine. 20% less than the maximum available memory is a good starting point. Swap space specified with -swap_limit is not included. Memory limits have no effect on slave hosts.

-message module class_list … --

Enable or disable individual message classes, per module. The module names are printed at the beginning of every message printed by mental ray; all can be used to modify the message classes of all modules. The class_list is a comma-separated list of classes to print. Supported message classes are phase, progress, vprogress, time, scene, memory, render, vrender, resources, network, files, and debug. The special words default, all, and none are also supported. A class can be inverted by prepending an exclamation point. For example, to print less verbose RC progress messages and make all modules report every file accessed, specify

-message rc default,!vprogress all default,files --

The message codes that perform useful actions are listed in the following table:

module	class	default	action
all	msgtrans	-	network transfers
echo	debug	-	add comments to `-echo incremental` output
gapmi	progress	on	tessellation and displacement sampling
geomi	tessellate	-	triangles created by tessellation
img	files	-	opened image files, texture caching
job	debug	-	job execution, slave transfers, status
job	resources	-	post-render job execution statistics
mi	files	-	opened include files
mi	progress	on	line numbers every 50000 lines
msg	network	-	slave host rendezvous details
msg	progress	on	host list, connecting hosts
phen	debug	-	check shader results for NaN (Not a Number) values
rc	phase	on	rectangle rendering begin and end
rc	scene	on	camera/option dump before rendering
rci	debug	-	BSP subtree creation
scene	phase	on	preprocessing, geometry shaders
scene	resources	-	postprocessing statistics
spdl	debug	-	echo MI declaration equivalents

-motion on|off

Normally the -shutter option controls whether motion blurring is enabled, and turns it on if there is a nonzero shutter interval. The -motion option overrides this and turns motion blurring on or off explicitly. For example, it is useful to define a zero shutter interval and then (order is important) turn motion blurring on, so that shaders get a correct state→motion vector. If motion blurring is turned off, this vector is not computed.

Note: to turn motion blur off, the command line option -shutter 0 should be used.

-motion_steps steps_int

Approximate instance motion transformations with steps segments. This results in a smooth motion path, as if a similar number of motion vectors had been specified. steps must be a number between 1 and 15; 1 is the default. If objects with motion transformations also specify motion vectors, the number of motion vectors per vertex must agree with the motion steps value.

-nomaster

When rendering with multiple hosts, schedule all jobs on slaves only, if possible. For example, the master host will not render, tessellate, compute shadow maps, etc, if possible; but it will still load textures of the slaves, and will also collect and save rendered images. The master may execute certain rendering jobs only if the slaves run out of resources. This is useful if the master host also runs front-end applications that must remain responsive even under heavy load.

-o "filename"

This is an abbreviation for -file_name.

-offset x y

An offset for the rendered image. The default is 0.0 for both x and y, which means that the image will be centered on the camera's Z axis. Positive values translate the image up and to the right. The offset is measured in pixel units.

-output on|off

Ignore all output shaders if set to off. The default is on. File output statements are not affected.

-photonmap_file "filename"

Use filename for the photon map, in all frames. If the photon map file does not exist, it is created and saved. If it exists, it is loaded and used. For multiple frames it is only created for the first frame and then loaded for the remaining frames, which can greatly speed up rendering in scenes where the illumination does not change much, such as camera flythroughs.

-photonmap_only on|off

If this option is set, only the photon maps but not the camera images are rendered. The default is off.

-photonvol_accuracy nphotons_int [radius]

Controls how global illumination or caustics in participating media are estimated by looking up the photon map during rendering. nphotons is the maximum number of photons to examine and radius the maximum radius to search. if nphotons is 0, all photons are examined up to the radius limit. A radius of 0 means that a scene size dependent radius will be used. The defaults are 30 and 0.0.

-photonvol_merge distance

To reduce photon map size, merge volume photons which are closer than the specified distance.

-photonvol_scale r g b[a]

The illumination contributed by volume photons is multiplied by the specified color, making the effect brighter for factors greater than 1.0.

-photon_depth reflect_int [refract_int [sum_int]]

photon_depth is similar to trace_depth except that it applies to photons. If set to 0, no photons will be reflected; if set to 1, one level is allowed but a photon cannot be reflected again, and so on. The defaults are 5 5 5.

-premultiply on|off

Premultiplication means that colors are stored with alpha multiplied to R, G, and B. This is the default. For example, white at 10% opacity is not stored as (1, 1, 1, 0.1) but as (0.1, 0.1, 0.1, 0.1). If turned off, mental ray writes the colors without premultiplication; in this case color clipping should also be switched to raw mode.

-rast_motion_factor factor 3.6

Takes a positive floating point value which divides the shading samples taken proportional to the speed of the motion of the object in screen space. It can be used to improve rendering performance for motion scenes without a visual quality decrease. The default value is 0.0, which disables this feature. A good starting value for many scenes would be 1.0.

-rast_transparency_depth depth 3.6

When set to a positive integer, the transparency compositing will end at the depth specified. The default is 250. This is a performance tuning parameter for scenes where it is known that the main colour information is provided by the first few depth layers.

-rast_useopacity on|off 3.6

When enabled then transparency/opacity compositing is performed by the rasterizer on all user color frame buffers (i.e. non-primary color buffers), regardless of the individual setting on user frame buffers. By default, this compositing is only performed on the primary color buffer, and on user frame buffers that have been marked for compositing explicitly.

-reload bytes

If this option is specified then mental ray attempts to avoid keeping geometric objects in memory permanently, and instead re-reads them from disk as needed. Only objects larger than bytes are considered for this optimization. This may save large amounts of memory on certain complex scenes. Note that it is not possible to reload objects in some cases, for example when the input scene is piped into mental ray or if objects contain multiple merge groups.

The recommended size for bytes is about 30000, corresponding to an object with about 1,000 vertices. The default of 0 disables reloading of objects.

Reloadable objects occupy memory only for a short period of time. They are read from the .mi file only when needed (intersection hit) and not already present in memory. The mental ray cache manager may decide to flush such objects when sufficient memory is not available.

It is recommended to specify object bounding boxes in the .mi file, otherwise mental ray must calculate them when an object is made reloadable.

-render begin_int [end_int [inc_int]]

Render only frames begin through end. If end is omitted, begin and all following frames are rendered. If inc is given, only every inc-th frame is rendered. Frame 1 is considered the first render statement in the scene file; camera frame specifiers are not considered. For example, 4 8 2 will skip the first three frames, then render frame 4, 6, and 8, and omit the rest. It is not an error if the scene file has fewer frames than requested.

-resolution x_inty_int

Specifies the width and height of the output image in pixels. The default is 768 576.

-samplelock on|off

This option selects whether sampling of area light sources, motion blur, and depth-of-field is static or dependent on the frame number. The default is on (static).

-samples min_intmax_int [defmin_int defmax_int]

This option determines the minimum and maximum sample rate given as powers of 2. Each pixel is sampled at least 2^2·min and at most 2^2·max times. Positive values increase the sample rate; negative numbers reduce it. The default is −2 0. This option has no effect with the rasterizer. The two optional extra parameters set the default object sample limits. Objects may constrain sampling of the pixels they cover. The defmin_int and defmax_int parameters apply to pixels where no objects are seen, or all the objects that are seen have no samples limit. mental ray will never take fewer than 2^2·min and more than 2^2·max samples, and in areas with no object sample settings it will further reduce that range to 2^2·defmin through 2^2·defmax. The defaults are −2 0 −128 127; the latter two are markers for "no further restrictions" because they are outside the −2 0 range.

-shading_samples num

Rasterizer (formerly called Rapid Motion) sampling is controlled by the -shading_samples option. The units are shading samples per pixel, and the default is 1.0.

-samples_collect num

The rasterizer adds a separate collection phase after tile rendering that combines subpixel samples to pixels. The num argument controls how many shading points should be used for compositing one pixel. Unlike the -samples arguments, the num argument is a linear count per pixel dimension, x and y. The default is 4, which gives 16 samples per pixel. The rasterizer (formerly known as Rapid Motion) no longer uses the -samples option. Rasterizer sampling is not adaptive.

-samples_motion num_int

Determines at how many points in time a moving object is shaded in rasterizer (Rapid Motion) mode. The default is 1, which means that a moving object is sampled once at shutter open time, and this result is blurred across the motion path. Higher values than 1 sample at more points during the shutter interval. This option does not apply to regular scanline rendering because it does not cache shading results.

-scanline on|off|opengl|rasterizer|rapid

Mode off allows turning off the scanline rendering algorithm to force mental ray to rely exclusively on ray tracing. This will slow down rendering in most cases. The rasterizer mode enables a different algorithm that greatly improves motion blurring speed. It is synonymous with rapid; the term "Rapid Motion" is deprecated in favor of "rasterizer" because the rasterizer is a full rendering algorithm, not only a motion blurring accelerator. The opengl mode uses local OpenGL hardware to accelerate rendering, which sacrifice some accuracy for a large speed gain. If shadow mapping is also used, -shadowmap opengl should also be chosen. See page opengl for more information. The default scanline mode is on.

-shadow off|on|sort|segments

Choose the shadow mode, or disable shadows. The default is on. off disables all shadows, including shadow maps. on enables standard shadows. sort enables shadows and sorts shadow intersections before calling shadow shaders. Some shadow shaders require this. segments enables shadows and traces shadow rays like visible rays. Some shadow shaders require this.

-shadowmap [on|off|opengl] [only] [rebuild] [reuse] [motion] [nomotion]--

This option can be used to control shadow maps. The option list is a sequence of one or more keywords. on activates use of shadow maps. off disables use of shadow maps. This is the default. opengl enables use of shadow maps, and uses local OpenGL hardware to accelerate shadow map rendering, at a small accuracy loss. See also page opengl and -scanline opengl above; it often makes sense to enable OpenGL in both options. only causes only shadow maps to be rendered, without rendering a color image. By default the color image is rendered also. This is useful to precompute shadow maps before the actual color rendering passes begin. This does not work with detail shadowmaps because detail shadowmap files only store shadowmap tiles that were needed during rendering. rebuild causes all shadow maps to be recomputed, even if they exist in memory from a previous frame or are found on disk. By default shadow maps are computed only if they are found neither in memory nor on disk. reuse allow the reuse of shadowmaps. This is the default. If a shadowmap is found in memory or on disk it is used instead of recomputing it. This only works if object space mode is selected in the options block of the scene. motion activates motion blurred shadow maps. This is enabled by default if shadow maps are turned on. nomotion disables motion blurred shadow maps. This improves rendering speed. merge specifies that if the shadowmap was saved to disk (using a shadowmap file statement in the light description), this file should be read. Whenever a regular shadowmap computation shows that a shadow-casting object is closer to the light than the shadowmap on disk specifies, the closer value is used; otherwise the shadowmap remains unchanged at that point. This can be used to build up shadowmaps for multipass rendering.

-shutter[delay] shutter

This option controls motion blurring. The camera shutter opens at time delay and closes at time shutter. The defaults are both 0.0. If shutter is equal to delay, motion blurring is disabled; if shutter is greater than delay, motion blurring is enabled. The normal range is (0, 1), which uses the full length of the motion vectors or motion vector paths. It can be useful to set delay and shutter both to 0.5, which disables motion blurring but renders with an offset of one half frame, which allows bidirectional post-blurring in an output shader.

-swap_dir "directory"

Specifies a directory for disk swapping. When mental ray runs out of memory, it can push memory objects to disk, and load them back when they are needed again. mental ray does this much more efficiently than the operating system, which has no semantic knowledge of the data. For example, source geometry is not likely to be needed anytime soon, or at all, after it has been tessellated. The directory should be on a local disk, not a file server. This option should be used together with -swap_limit, and given before -swap_limit on the command line.

-swap_limit size

Specifies the number of megabytes to write to the swap directory specified with -swap_dir. This space effectively becomes an extension of system memory. The default is 0, which turns off swapping. Good numbers are in the low thousands.

-shutter shutter

This option specifies the shutter open time. A shutter value of 0.0 turns motion blurring off, values greater than 0.0 turn motion blurring on. The standard value for enabling motion blurring is 1.0; larger values increase the blur length. The default is 0.0.

-T "path1:path2:…"

Specifies a list of directories where texture files will be searched. The default is the current directory. The list is colon-separated (Unix only) or semicolon-separated (Unix and Windows NT). As with the -I option, paths introduced with an exclamation point are special: they substitute the entire directory path of the texture name and keep only the last component (the file name) when searching.

Controls the order of image rectangles to be rendered. The default is hilbert, which is rendering surrounding tiles first to benefit from caching of data from close objects in neighboring tiles. This option can have impact on performance which is related to the distribution of objects in the final image.

-task_size task_size_int

This option specifies the size of the image rectangles during rendering. Smaller task sizes are convenient for previewing, but also increase the overall rendering time and reduce the effectiveness of edge following. This option can also be used to optimize load balancing for parallel rendering. If the task_size is not specified, an appropriate default value such as 32 is used.

-texture_continue

Normally, standalone versions of mental ray abort as early as possible when a texture file cannot be read, to avoid spending a lot of time on unusable images and letting the farm controller know as soon as possible. If this option is specified, mental ray will continue and use transparent black or red-and-black checkerboard defaults (depending on the shader) for missing texture files.

-threads nthreads_int

Normally, mental ray starts one thread for each processor in the system. The number of threads can be changed with this option. mental ray will create more threads than specified, but only nthreads_int will perform compute-intensive tasks simultaneously. In mental ray 3.3 and later, this includes threads on hyperthreaded Intel CPUs, which do not consume licenses. For example, a two-processor hyperthreaded Xeon system would run four threads and pull two licenses.

-time_contrast r g b [a]

The time contrast controls temporal oversampling for motion blurred scenes. It works similar to the spatial contrast parameter explained above but applies to motion blur only; the number of temporal samples is approximately proportional to the inverse of the time contrast value. The default is 0.2 0.2 0.2 0.2. For fast motion blur, the time contrast must be set to 0 0 0 and minimum and maximum sampling must have the same value, such as 2 2.

-trace on|off

Normally, mental ray will use a combination of a scanline rendering algorithm and ray tracing to calculate samples of the scene. If -trace off is specified, ray tracing is disabled, and mental ray will rely exclusively on the scanline algorithm.

-trace_depth reflect_int [refract_int [sum_int]]

reflect limits the number of recursive reflection rays. If it is set to 0, no reflection rays will be cast; if it is set to 1, one level is allowed but a reflection ray can not be reflected again, and so on. Similarly, refract controls the maximum depth of refraction and transparency rays. Additionally, it is possible to limit the sum of reflection and refraction rays with sum. The defaults are 2 2 4.

-v on|off|level_int

An abbreviation for -verbose.

-verbose on|off|level_int

This command controls verbose messages. There are seven levels: fatal errors (1), errors (2), warnings (3), informational messages (4), progress reports (5), debugging messages (6), and verbose debugging messages (7). All message categories numerically equal to or less than level are printed. Verbose off is equivalent to level 2 (fatal errors and errors); verbose on is equivalent to level 5 (everything except debugging messages).

-version

Print version information and exit.

-volume on|off

Ignore all volume shaders if set to off. The default is on.

-window x_low_int y_low_int x_high_int y_high_int

Only the sub-rectangle of the image specified by the four bounds will be rendered. All pixels that fall outside the rectangle will be left black. This option does not have an affect on the size of the frame buffer or saved image files; it merely suppresses rendering pixels outside the window.

-xcolor["control "]

Print colored messages. Error messages, for example, are printed in red, which makes them stand out much better in verbose reports. The control string allows customization.