Usage and Command Line Options

When started from a shell command line, mental ray accepts a large number of options. Most of these correspond to similar commands or view statements as described in the Scene Description chapter. The relevant explanations there are repeated in this chapter. When an option is given on the command line, it overrides the corresponding command or view statement in the scene file, which in turn overrides the defaults. The defaults for certain options given in the option list below applies only if the corresponding command or statement is not present in the scene file.

For the option description, the same metasymbols as in the Scene Description chapter are used: a bar ``|'' denotes alternatives, items enclosed in tall square brackets ``[ ]'' are optional, and the ellipsis ``...'' denotes omission. Literal text is set in teletype, while variable metasymbols are set in italics. All other punctuation characters are literals. Strings are quoted with double quotes; this includes all names. The double quotes protect names from interpretation by the shell, they should be entered as shown here.

mental ray is started as

ray [options] [scenefile]

If no scene file is given, the scene is read from standard input. Scene file names must end in .mi; if the extension is missing mental ray will add it. The available options are:

-help

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

-verbose on|off

This command turns verbose messages on or off. Default is off. If verbose mode is enabled, objects found in the frame are listed as they are parsed, progress reports are printed during rendering, and time and memory statistics are printed after rendering has finished. Verbose messages can slow down mental ray significantly while parsing.

-code "filename" ... --

The named filename is interpreted as a C source file, ending with the extension ``.c'', is compiled and linked into mental ray. The shaders it defines are available in mental ray as shading functions. Multiple file names can be given. The list must be terminated with a double minus sign.

-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 dynamic shared object (DSO) files ending in ``.so''. Object files are linked, while DSOs are just attached without any preprocessing. DSOs are the fastest way of attaching an external shader, and require no compilers or development options, which are sometimes sold separately by system vendors.For system and development software requirements, see the Release and Installation Notes. However, not all systems support DSOs. If Dynamical Shared Objects are to be linked on SGI machines, the LD_LIBRARY_PATH environment variable must include the path of the .so file to be linked; see ``Dynamic Linking of Shaders''. The file name list must be terminated with a double minus sign.

-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 used; for example, the default option string for single-processor SGI IRIX machines is "-O2 -mips2 " (note the trailing blank). The -c option is always inserted, as is -o if the compiler supports it.

-linker "filename"

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

-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 highly machine dependent and operating system dependent and cannot be changed.

-imgpipe fdint

Normally mental ray prints connection information into the output image file that let programs like imf_disp connect and display pictures while being rendered. If -imgpipe is used, the relevant information is printed to the given file descriptor fd instead. This is mainly used by Softimage 3D, but can be used for command lines such as ``ray -imgpipe 1 scene.mi | imf_disp -''. The imf_disp program has been upgraded to allow image piping.

-nice niceint

This option sets the nice value of the process. Values greater than 0 reduce the process priority. Values less than 0 require root privileges and are normally ignored. The allowed range is operating system dependent, typically values between -20 and 106 can be used.

-threads nthreadsint

Normally, mental ray starts one thread for each CPU in the system. In a single-processor host, the default is always 1. This option changes the number of threads. There is normally no advantage in increasing the number of threads, but it may be lowered to reserve CPUs for other users, to avoid monopolizing a multi-processor machine.

-hosts "hostname" ... --

The host list overrides the host list taken from the .rayhosts file, if present. One slave is started on each host specified. Host names must be given as returned by the hostname Unix command on the respective machines. Machines used as slaves must be correctly configured; see the installation notes. The host list must be terminated by a double minus.

-server

If the server option is given, mental ray runs in server mode, also called slave mode. This option should only be used in the inetd configuration file inetd.conf; see the installation notes for details. Other options should be used with care if -server is given because they would override options given in the scene file, which may cause the parts of the image rendered by this server to look different from parts rendered on other hosts.

-binary

This option must be given if the scene file is in binary format, rather than the standard ASCII format. This option is for internal use only and not available in all versions of mental ray.

-log on|off

This option, if given on the shell command line, collects all output from other hosts in files named host.0.log, which can be inspected after mental ray terminates. This is useful for network debugging. Note that the syntax errors at the first token usually indicate that the versions of the master and slave (server) mental ray do not match. Logging is turned off by default.

-memory maxmemint

The memory command limits the maximum resident set of mental ray to maxmem megabytes, on systems that support resource limits. Only the maximum amount of physical RAM used is limited, not the maximum amount of virtual memory. This means that swapping to disk may be increased if RAM runs out. This can be used to partition available physical RAM among multiple processes, because it prevents mental ray from grabbing all available space.

-mc

Use Monte Carlo methods for sampling of area light sources, motion blur, and depth of field as implemented by the lens_depth_of_field shader.

-qmc

Use Quasi-Monte Carlo methods for sampling of area light sources, motion blur, and depth of field as implemented by the lens_depth_of_field shader. For details on the -mc and -qmc options, see the Sampling Algorithms section in the Functionality chapter.

-base_name "filename"

Overrides the file name given by the first file output statement in the view 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 view in the scene file. File formats include "pic" for SOFTIMAGE image files, "rla" for Wavefront RLA files, or "ps" for PostScript files if contour mode is enabled. For a complete list, see the Output Shaders subsection in the Functionality chapter.

-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. However, objects between the camera and the viewing plane will still be rendered; a common approach is to place the viewing plane in the middle of the interesting objects in the scene and then set the aperture such that it is a bit larger than the horizontal extent of the objects in camera space. If infinity is used in place of the distance, an orthographic view is rendered. An orthographic view turns off perspective, all camera rays are parallel. View-dependent surface tessellation is not possible in orthogonal mode.

-aperture aperture

The aperture is the width of the viewing plane. The height of the viewing plane is aperture divided by aspect. Together with the focal and aspect viewdefs, aperture defines the lens of the camera.

-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. For example, to render a PAL image at a resolution of 720 *576 pixels, at an image ratio of 3:4 as defined by the PAL standard, pixels are slightly wider than tall, by a factor of 576 /720 *4 /3 = 1.0667. If this number is specified as aspect, objects will appear undistorted on a PAL video display (but not on a computer display with square pixels).

-resolution xint yint

Specifies the width and height of the output image in pixels.

-window x_lowint y_lowint x_highint y_highint

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.

-min_samples minint

This option determines the minimum sample rate. Each pixel is sampled at least 2^2 *min times. If min is 0, each pixel is sampled at least once. Positive values increase the minimum sample rate; negative numbers reduce the sample rate to less than one initial sample per pixel (infrasampling). min must be at least -2, which means that at least one sample per 4 *4 pixels is taken. -2 is the default. If min is chosen too small, small features may be lost if all samples happen to miss it (if it is found just once in any pixel of a task, mental ray will analyze the feature and render it correctly). If a filter view statement is used to set a filter other than box 1 1, min must be set to -1 or greater. If depth, normal, or label frame buffers are used by an appropriate output statement, the min parameter should be set to 0 or greater to avoid gaps.

-max_samples maxint

This option sets the maximum sample rate. If neighboring samples find a difference in contrast exceeding the contrast limit, the area that contains the contrast is subdivided until the maximum recursion depth specified by max is reached. At most 2^2 * max samples per pixel are taken. mental ray will also automatically analyze features once detected in one pixel, which permits choosing a very low minimum number of samples (such as -2). If a filter view statement or option is used to set a filter other than box 1 1, max must be set to 1 or greater.

-recursive on|off

This flag controls the recursive sampling method that takes image samples at pixel corners, and recursively subdivides pixels into subpixels where contrasts exceeding the contrast threshold are detected. Recursive sampling uses the -min_samples and -max_samples parameters. It is enabled by default unless contour rendering or motion blurring is enabled. If it is disabled, the sampling method is chosen based on the -adaptive option; see below.

-samples samplesint

The samples option exists for backwards compatibility only. It sets the maximum number of samples to samples^2 for the non-recursive supersampling algorithm, which is currently used only when contour rendering is enabled. This option may be removed from later versions of mental ray.

-adaptive on|off

The adaptive option, like the -samples option, is obsolete. If contour rendering or motion blurring is enabled, or if there is a -recursive off option, an algorithm that uses -samples and -adaptive is used. If -adaptive is off, the number of samples is always samples^2; if it is on, the number of samples is either 1 or samples^2. The -min_samples and -max_samples options offer a more flexible way of controlling the number of samples.

-contrast r g b [ a ]

The contrast controls supersampling. If neighboring samples differ by more than the color r, g, b, a, supersampling is done as specified by the sampling options (see above). Default for a is the average of r, g, and b. The recursive supersampling algorithm controlled by -min_samples and -max_samples modifies the contrast based on the recursion level: at sample level 0, the contrast is used directly; at sample level 1, the contrast is doubled (effectively requiring a higher contrast to force another subdivision), and so on. Negative levels divide the contrast, i.e. use a fraction 1 /2, 1 /4, and so on. In general, the contrast is multiplied by 2^level at the supersampling level level, which is bounded by -min_samples and -max_samples.

-time_contrast r g b [ a ]

The time contrast controls temporal supersampling for motion blurred scenes. It works similar to the spatial contrast parameter explained above: If neighboring samples in time differ by more than the color r, g, b, a, supersampling is done. Default for a is the average of r, g, and b. Using values for -time_contrast that are higher than -contrast can speed up motion blur rendering at the price of more grainy images without degrading the quality of spatial antialiasing.

-filter box|triangle|gauss width [height]

The -filter 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 box filter can be replaced with a triangle filter or a gaussian filter centered on the pixel. The filter size in pixel units can also be specified; if no height is given the width is used. Larger filter sizes result in softer images. Typical values are 1.0 for box filters, 2.0 for triangle filters, and 3.0 for gaussian filters. For details on filtering, see the description of the filter statement in the Scene Description chapter.

-jitter jitter

The jittering factor introduces systematic variations into sample locations. Without jittering, samples are taken at the corners of pixels or subpixels. Jittering displaces the samples by an amount calculated by lighting analysis, limited to jitter pixels. This is used to reduce artifacts. Jittering is turned off by specifying a jitter of 0.0. Jittering works best in ray tracing mode.

-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 shutter value scales the motion vectors attached to object vertices; if shutter is 1.0, each vertex moves the distance given by its motion vector, and is blurred in the image over this distance. Values less than 1.0 reduce this path.

-trace_depth reflectint [refractint [sumint]]

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 (which implement transparency with and without index of refraction). Additionally, it is possible to limit the sum of reflection and refraction rays with sum. For example, if 3 3 4 is given, an eye ray may be reflected 3 times, or refracted 3 times, or reflected twice and then refracted twice, or any other combination that sums up to at most 4.

-shadow_sort on|off

This flag controls the way shadow shaders are called. Shadow shaders determine how much light from a light source passes through a shadow-casting object between the light source and an illuminated point on some other object. If the sorting flag is off (the default), the shadow shaders are called in random order. If sorting is on, the shadow-casting objects are sorted such that the shadow shader of the object closest to the light source is called first. This slows down rendering slightly, but is required if certain complex shaders such as fur shaders are used.

-acceleration spatial_subdivision

Selects the binary space partitioning (BSP) rendering algorithm. This algorithm is often, but by no means always, faster. It is controlled by the -max_size and -max_depth options.

-acceleration ray_classification

Selects the ray classification rendering algorithm. This algorithm is recommended for very large scenes. It operates with a constant acceleration memory size, controlled by the -subdivision_memory and -subdivision options.

-max_size sizeint

The maximum number of primitives in a leaf of the BSP tree. This option is used only if binary space partitioning is enabled, it has no effect on the ray classification algorithm. Larger leaf sizes reduce memory consumption but increase rendering time. The default is 4.

-max_depth depthint

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

-subdivision subdivint subdiv_2dint

mental ray uses a ray tracing algorithm that subdivides the space of all rays. The optimal subdivision is determined automatically by a built-in scene analysis. The -subdivision option can be used to modify the result of this analysis; arguments of 0 leave the calculated subdivision unchanged, positive numbers increase and negative numbers reduce the subdivision. subdiv controls general subdivision; subdiv_2d controls primary (eye) and shadow rays. This option has no effect if the BSP algorithm is used.

-subdivision_memory memoryint

This option sets the amount of memory to be used by the ray space subdivision algorithm for acceleration data structures to memory megabytes on each CPU. It has no effect if the BSP algorithm is used. mental ray allows presetting the amount of rendering acceleration memory independently of scene complexity without sacrificing speed. The default is set to 6 megabytes, which is sufficient for most scenes. Even for extremely large scenes, little can be gained from memory sizes greater than 12 megabytes. Note that this option does not affect the amount of memory used for the scene description, which depends on the complexity of the geometry in the current frame. Compare also the -memory option; see above.

-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. This works well unless there are objects whose back side is seen by refracted or reflected rays -- with face front, the back side would not be visible. The default is face both.

-clip hither yon

The hither (near) and yon (far) planes are planes parallel to the viewing plane that delimit the rendered scene. Points outside the space between the hither and yon planes will not be rendered (this does not apply to the infinite-radius environment maps because they are not geometric objects). The clip statement specifies the distance of the hither and yon planes from the camera. The defaults are 0.0001 for the hither distance and 1000000.0 for the yon plane.

-shadow on|off

By default, shadows are enabled. The -shadow option can be used to turn shadows off globally.

-trace on|off

Normally, mental ray will use a combination of a scanline 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. Without ray tracing, reflection rays and refraction rays cannot be cast. However, scanline transparency that, unlike refractions, does not support changing the direction of the ray based on the index of refraction of the material, and environment maps will work when ray tracing is turned off. Ray tracing is turned on by default.

-scanline on|off

This statement allows turning the scanline algorithm off to force mental ray to rely exclusively on ray tracing. This will slow down rendering in most cases. By default, scanline is turned on unless motion blurring, the BSP algorithm, or lens shaders are used.

-desaturate on|off

If a first-generation material shader returns a color whose RGB components are outside the range [0, 1], mental ray will clip the color to a legal range. Negative component values are clipped to 0. If any of R, G, and B exceed 1, they are either set to 1 (if desaturation is turned off), or R, G, and B are faded towards white (if desaturation is turned on). Alpha is always set to 1 if it exceeds 1, or to the maximum of R, G, and B if any of them exceed alpha. Desaturation is turned off by default.

-dither on|off

mental ray supports both 8 and 16 bits per color component. In some cases, 8 bits per pixel, as supported by all popular picture file formats, can cause visible banding when the floating-point color values calculated by the material shader are quantized to the 8-bit values used in the picture file. Dithering mitigates the problem by introducing noise into the pixel such that the round-off errors are randomly distributed. Note that this can cause run-length encoded picture files to be larger than without dithering. Dithering is turned on by default.

-gamma gamma_factor

Gamma correction can be applied to rendered color pixels to compensate for output devices with a nonlinear color response. All R, G, B, and alpha component values are raised to gamma_factor. The default gamma factor is 1.0, which turns gamma correction off.

-field even|odd|both

Field rendering is a technique that allows smooth animations on interlaced video displays. To reduce flicker, video displays first display only every other scanline of the picture, and then the remaining scanlines in a second sweep. Each sweep is called a field. Two fields are one frame. Since sweeps occur at one half of the frame rate, animated objects may have moved between sweeps. Not taking this into account results in rough animations. By default, mental ray renders full frames, resulting in a non-interlaced output picture. If field rendering is set to even, every consecutive pair of rendered frames is combined such that the first frame contributes the even scanlines (counted from the top), and the second frame contributes the odd scanlines. This is reversed if field rendering is set to odd. The decision of which frame is the first or second is based on the frame number; the first field has an odd frame number (usually 1). If field rendering is enabled, there must be an even number of frames in the input file.

-frame frameint

The given frame number overrides the first frame number given in the scene file, using the frame statement. The next frame number in the scene file, if present, will be overridden woth frame + 1, then frame + 2, and so on. The frame number is available to shaders. The frame time, which is also available to shaders, cannot be overridden.

-contour on|off

If contour rendering is turned on, mental ray will render contour lines based on the visibility, self-occlusion, transparency, and normal vectors instead of color images. This option is useful for cartoon animation. Contour rendering is turned off by default. If it is turned on, the output statements at the beginning of the view statement or the -file_type option must either specify PostScript output files (filetype "ps"), or must specify an RGB or RGBA file type together with a datatype "contour".

-paper_size "format"

If contour rendering is turned on and the output is a PostScript file, format determines the paper size. Available paper sizes are a3, a4, a5, a6, b4, b5, b6, 11x17 (or b), letter (or a), executive, or legal. All paper size strings are case-insensitive. The default is 11x17.

-paper_scale scale

The paper scale is a correction factor for the size of the contour drawing on paper. The default is 1.0; numbers greater then 1.0 enlarge the drawing and numbers less than 1.0 reduce it.

-discontinuity angle

Determines the angle discontinuity required to produce a contour line, in degrees. Any two triangles forming an angle of more than the specified number will produce a contour line segment between them. A value of 0.0 will outline every triangle. The default is 60.0.

-contour_line_width width

This option determines the contour line width in points for PostScript output, and in pixels for picture output. The default is 0.5.

-contour_depth depth

The contour depth controls contours around occluded or self-occluding objects. A contour line will be drawn between two triangles in the same object if their z depths differ by more than depth. The depth is also used to decide whether to draw a contour line or not between two objects if only one of them has the nocontour flag set in its material. In this case, the Z depths of the two objects are compared, with depth being a threshold: if the two objects differ in Z by less than depth then --- assuming intersection or touching --- no contour line is drawn. If the two objects differ in z by more than depth, draw the contour line if contour generation for the foremost object is enabled; otherwise no contour line is drawn. depth must be positive. The default is 0.0.

-paper_transform b d

The paper transformation defines a transformation that corrects distortions introduced by the printer. The PostScript coordinates expressed in points are transformed according to the matrix (1 b 0 d). The default is the identical transformation, i.e. no distortion correction.