Keywords: main

Next: 5.2 Startup File Up: 5. Usage and Command Previous: 5. Usage and Command

# 5.1 Command Line Options

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`
  Selects the binary space partitioning ( BSP) rendering algorithm. This algorithm is often, but not always, the fastest. It is controlled by the `-bsp_size` and `-bsp_depth` options.

- `-acceleration grid`
  Selects the grid rendering algorithm. It provides faster preprocessing especially on multiprocessor systems. Memory usage is more conservative than with the BSP algorithm. Speed is comparable to BSP but more scene-dependent. It is controlled by the `-grid` option.

- `-acceleration raycl`
  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.

- `-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 `x` 576 pixels (equivalent to CCIR 601, also called D1), at an image ratio of 3:4 as defined by the PAL standard, pixels are slightly wider than tall, by a factor of . = 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). The NTSC standard has 486 instead of 576 lines.

- `-bsp_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 40.

- `-bsp_memory` memoryint
  The maximum memory in megabytes used in the BSP preprocessing. A value of zero indicates that there is no limit on the memory consumption, this is the default. This flag is useful only on multiprocessor machines since the memory consumption increases with the number of rendering threads. When the specified amount of allocated memory is reached, mental ray will prevent threads from being scheduled for preprocessing, thus reducing the memory requirements.

- `-bsp_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 10.

- `-caustic on|off`
  Enable or disable the generation of caustics defined in the scene. The default is `off`. To actually create caustics, lights must have an energy, and materials must have photon shaders.

- `-caustic_accuracy` nphotonsint`[`radius`]`
  Controls how caustics are estimated from the photon map during rendering. nphotons is the maximum number of photons to examine and radius the maximum radius to search. if nphotons = 0, all photons are examined up to the radius limit. radius = 0.0 means that a scene-size dependent radius will be used. The defaults are 100 and 0.0.

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

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

- `-colorclip rgb|alpha|raw`2.1
  This option controls how colors are clipped into a valid range [0, 1] before being written to a non-floating point frame buffer or file. The `rgb` mode is the default. In this mode, RGB is first clipped to [0, 1] and alpha subsequently to [max(R, G, B), 1]. In `alpha` mode, alpha is first clipped to [0, 1] and RGB subsequently to [0, A]. In `raw` mode, RGB and A are both clipped to [0, 1] independently of each other. In all modes, the RGB components are clipped as specified by the `desaturate` option. The `rgb` and `alpha` modes ensure that the resulting color is a valid premultiplied color. `rgb` should be used if the alpha channel is considered less important than preserving the RGB color and intensity. `alpha` mode is intended for alpha compositing, where the alpha channel is more important than the absolute color value to preserve correct transparencies. `raw` mode should only be used if no layering based on alpha is going to take place. This mode also forces the `premultiply` mode to `on`. It should be used with care because shaders might receive ``illegal'' colors (colors that cannot be composited in standard ways).

- `-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 `-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 12, 14, and so on. In general, the contrast is multiplied by 2level at the supersampling level level, which is bounded by `-samples`. See the Scene Description chapter for more information on how to optimize performance and quality with contrast values.

- `-cut_window` numint [ expand ]
  Cut a frame into num `x` num sub-frames, each of which is rendered individually. When all are finished, they are combined to the final image. This can greatly reduce memory consumption if the scene is built such that each sub-frame is much less complex than the entire frame, but it may take much longer to run all the extra rendering cycles. If the scene contains few polygons and many free-form surfaces and/or displacement maps, memory usage often goes down by factors of five or ten, while rendering time doubles. Mostly polygonal scenes usually do not benefit from cut windows, and in fact can behave worse. Tessellation caching in animations is disabled in cut window mode.

- Before deciding whether geometry outside the cut window frustum should be tessellated, the frustum is enlarged by 10% all around to catch geometry outside the frustum that is displaced into the frustum. This value can be changed with the optional expand argument, which is a factor of the cut window size. `0.1` expands the cut window by 10% all around, which increases its area by a factor of 1.44.

- This is a temporary feature in version 2.0 and 2.1 of mental ray and not supported in version 2.2 and later.

- `-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"`. The `-c` option is always inserted, as is `-o` if the compiler supports it.

- `-c_linker "`filename`"`
  If this option is given, the standard linker `"ld"` is replaced with filename. See the chapter on Writing Shaders for platform-specific information on compiling and linking.

- `-desaturate on|off`
  If a color is output to a frame buffer that does not have 32-bit (floating-point) precision, and its RGB components are outside the range [0, max], mental ray will clip the color to this legal range. If desaturation is turned off, the individual components are simply clipped into range. Otherwise, tries to maintain the brightness of the color by moving it towards the grayscale axis of the color cube, until the RGB components are in the legal range. max is determined by the `colorclip`2.1mode. Desaturation is turned off by default.

- `-diagnostic grid off|object|world|camera` size2.1
  This diagnostic mode is intended for scene debugging. Unless set to `off`, it draws a colored grid on all objects in the scene that indicate 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. The default is `off`.

- `-diagnostic photon off|density|irradiance` max2.1
  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`2.1 (p. )
  If set to `on`, 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 is drawn indicating task boundaries. The default is `off`.

- `-displace on|off`
  Ignore all displacement shaders if set to `off`. The default is `on`.

- `-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 off by default.

- `-echo "`filename`"` [`ascii`] [`source`] [`approx`] [`norendercommand`] [`textures`] `-`
  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.

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

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

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

- `-filter box|triangle|gauss|mitchell|lanczos` [width [height]]
  The - filter option specifies how multiple samples are to be combined into a single pixel value. The filter defaults to a box filter of width and height 1.0, optimized for speed. This option allows replacing the box filter, or its size (in pixels). If the size of the filter is not specified, default values are used. These are 1.0 for box, 2.0 for triangle, 3.0 for Gauss and 4.0 for Mitchell2.1and Lanczos2.1. If the height is omitted, it defaults to the width. Other values can be specified: larger filter sizes result in softer images. If the size is too small, artifacts may appear. Filters must be larger than 0.0 but sizes smaller than 1.0 are generally wasteful since they will discard some samples. Filters larger than 1.0 can reduce rendering speed. For further details on filtering, see the description of the `filter` statement in the Scene Description chapter.

- `-finalgather on|off`2.1
  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.

- `-finalgather_accuracy` nraysint`[`maxdist`[`mindist`]]`2.1
  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.

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

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

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

- `-globillum on|off`2.1
  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` nphotonsint [radius]2.1
  Controls how global illumination is estimated from the photon map during rendering. nphotons is the maximum number of photons to examine and radius the maximum radius to search. if nphotons = 0, all photons are examined up to the radius limit. radius = 0.0 means that a scene-size dependent radius will be used. The defaults are 500 and 0.0.

- `-grid_size` factor
  Adjust the scene-dependent default grid voxel size. The default is 1.0. Larger values increase the number of voxels and shrink each voxel accordingly.

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

- `-hosts "`hostname[`:`portnumber] [ remote parameters]`"` ... `-`
  The host list overrides the host list taken from the `.rayhosts` file, if present. One server is started on each host specified. Host names must be given as expected by the local name resolving method (such as `/etc/hosts`) or as a numeric internet address (`nnn.nnn.nnn.nnn`). Machines used as servers must be correctly configured; see the installation notes. The host list must be terminated by a double minus.

- `-I` path
  Overrides the path used to resolve `$include` statements in the .mi scene file. The default path is `/usr/include`. Note that only one `-I` option can be specified. It may contain a colon-separated (Unix only) or semicolon-separated (Unix and NT) list of directory paths that are tried in sequence if a `$include` statement 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` statement, for example because that path points to an obsolete (1.9) 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` 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 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.

- `-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 default, or by specifying a jitter of 0.0. Jittering works best in ray tracing mode. The jitter value is always set to 1.0 if jittering is turned on.

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

- `-ld_path "`path1;path2;...`"`
  Supply a list of paths that mental ray searches for dynamic shared objects (DSO) containing shader code. The paths given here precede those that can be given by an environment variable (`MI_LIBRARY_PATH`) and the built-in search path (`/usr/local/mi/lib;.`). `-ld_path` is synonymous with `-L`.

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

- `-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. On Windows NT, `.so` extensions are automatically converted to `.dll` for cross-platform compatibility.5.1 However, not all systems support DSOs; see ``Dynamic Linking of Shaders''. The file name list must be terminated with a double minus sign.

- `-merge on|off`
  Ignore all merge epsilons and all connections in the scene.

- `-message` moduleclass_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 -`

- `-o "`filename`"`
  This is an abbreviation for `-file_name`.

- `-offset` x y2.1
  Specifies an offset for the rendered image. The default is 0.0 for both values, 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.

- `-photonvol_accuracy` nphotonsint`[`radius`]`
  Controls how global illumination2.1or caustics in participating media are estimated from the photon map during rendering. nphotons is the maximum number of photons to examine and radius the maximum radius to search. if nphotons = 0, all photons are examined up to the radius limit. radius = 0.0 means that a scene-size dependent radius will be used. The defaults are 30 and 0.0.

- `-photon_depth` reflectint [refractint [sumint]]
  `photon_depth` is similar to `trace_depth` except that it applies to photons. reflect thus limits the number of recursive reflection photons. If it is set to 0, no photons will be reflected; if it is set to 1, one level is allowed but a photon cannot be reflected again, and so on. Similarly, refract controls the maximum depth of refracted photons. Additionally, it is possible to limit the sum of reflected and refracted photon levels with sum. Note that custom shaders may override these values. The default value is 5 5 5.

- `-premultiply on|off`
  Premultiplication means that colors are stored with alpha multiplied to R, G, and B. 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). This is the standard method in computer graphics to represent colors; mental ray always uses it internally and in all shaders. One implication is that R, G, and B can never exceed A. mental ray normally enforces this when storing color values into frame buffers. The `-premultiply off` option instructs mental ray to always store colors unpremultiplied into frame buffers and files. It does this by undoing the internally applied premultiplication. (mental ray internally always works with premultiplied colors to present a uniform interface to shaders; since this is done with floating-point values there is no precision penalty.) This option is ignored if the `-colorclip raw`2.1mode is in effect.

- `-raycl_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.

- `-raycl_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.

- `-render` beginint [endint [incint]]
  Render only frames begin through end5.2. 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` xint yint
  Specifies the width and height of the output image in pixels.

- `-samplelock on|off`
  Whether to let the sampling of area light sources, motion blur, and depht-of-field be static or depend on the frame number. The default is on, meaning static sampling.

- `-samples` minint maxint
  This option determines the minimum and maximum sample rate. Each pixel is sampled at least 22 . min times in each direction. 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 has default -2, which means that at least one sample per 4 `x` 4 pixels is taken. 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` camera statement is used to set a filter other than `box 1 1`, min must be set to -1 or greater (mental ray 2.1) or 1 or greater (mental ray 2.0).

- The max value 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 22 . max samples per pixel are taken. If a filter camera statement or option is used to set a filter other than `box 1 1`, max must be set to 0 or greater (mental ray 2.1) or 1 or greater (mental ray 2.0).

- `-scanline on|off|opengl`
  This statement controls the scanline rendering algorithm. By default, mental ray uses the scanline algorithm to compute rays traveling in a straight line from the camera, such as primary rays. In most cases this gives better performance than pure ray tracing. Turning scanline off forces mental ray to rely entirely on ray tracing. This will generally slow down rendering but in some cases, for example when the `task size` is very small, the overhead of initializing the scanline algorithm may outweigh its benefit and turning it off can result in a speed improvement.

- `-scanline opengl`2.1mode will cause mental ray to use OpenGL hardware if available to further accelerate rendering. OpenGL is not used to compute actual colors but only projection and intersection information, so the full mental ray shader feature set remains available. However, there may be a precision loss. Since OpenGL rendering is typically extremely fast compared to network transfer times, only the client host uses its OpenGL hardware. The results are broadcast to server hosts if present. Server hosts never use their OpenGL hardware. Also see `-task_size` below.

- OpenGL rendering makes certain demands on the OpenGL hardware present. If a 24 bit frame buffer with a Z buffer is not present, OpenGL rendering may fail. OpenGL may also fail or become slow if the image to be rendered is larger than the workstation display. The max parameter to the `-samples` option should not be higher than 0, or image artifacts may appear. During rendering with OpenGL, a window may briefly appear containing seemingly random colors. On Unix workstations, mental ray will need access to the X server and OpenGL hardware for OpenGL rendering to work. This is usually achieved through the use of the `DISPLAY` environment variable. See your workstation manuals for details. Finally, OpenGL rendering does not work with motion blurring. If, for any reason, OpenGL rendering is not possible on the client host, mental ray falls back on regular scanline rendering.

- `-shadow off`
  All shadowing is disabled.

- `-shadow on`
  This flag enables simple shadowing. 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. In `shadow on` mode (the default), shadows are computed. Shadow shaders are called in random order.

- `-shadow sort`
  This flag also turns on shadowing, but alters the way shadow shaders are called. The shadow-casting objects are sorted such that the shadow shader of the object closest to the illuminated point is called first and the one closest to the light is called last (unless the sequence terminates early because light is completely blocked).

- `-shadow segments`
  Like with `shadow sort`, the shadow shaders are called in a sorted fashion. Shadows are computed by tracing the segments between the illumination point, the occluding objects and the light source and applying volume shaders to these segments ( shadow segments). This slows down rendering, but is required if volume effects should cast shadows (as for certain complex shaders such as fur shaders).

- `-shadowmap` [`on`] [`off`] [`opengl`] [`only`] [`rebuild`] [`reuse`] [`motion`] [`nomotion`] `-`
  This option can be used to control shadow maps: The allowed options are:

- `on` activates use of shadow maps.

- `off` disables use of shadow maps. This is the default.

- `only` causes only shadow maps to be rendered, without rendering a color image. By default the color image is rendered also.

- `rebuild` causes all shadow maps to be recomputed, even if they are found in memory or on disk. By default `reuse` is in effect, meaning that shadowmaps are computed only if they are not found in memory or on disk.

- `reuse` causes shadowmaps to be reused. First, internal memory is searched for shadowmaps from a previous frame. If they are not found, a search is made on disk in the current directory, according to the filenames specified in the .mi file if given. If neither is found, the shadowmaps are recomputed.

- `motion` activates motion blurred shadow maps. This is the default.

- `nomotion` disables motion blurred shadow maps. This improves rendering speed.

- `opengl`2.1causes mental ray to try to use OpenGL acceleration when rendering shadow maps. The same limitations apply as mentioned with the `-scanline opengl` option. Additionally, because of the difference of the rendering algorithm, shadow maps rendered with this option contain slightly different information from those generated with the regular algorithm, and the resulting shadows may look different. In particular, soft areas of shadows tend to be smaller and some areas may incorrectly be determined to be not in shadow due to the lower precision of OpenGL acceleration. When OpenGL rendering of shadow maps is enabled, only the client host will participate, since the computation cost of the map is so small that the network transfer time would be prohibitive.

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

- `-task_size` task_sizeint
  This option specifies the size of the image tasks during rendering. Smaller task sizes are convenient for previewing, but also increase the overall rendering time. This option can also be used in order to optimize load balancing for parallel rendering. Note that very small task sizes can cause the scanline algorithm to perform poorly and in such cases it may be desirable to turn it off. See `-scanline` above. If the `task_size` is not specified, an appropriate default value is 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. Note that Convex machines do not make the number of CPUs in the system available to user programs, so `-threads` should always be used.

- `-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; the default for r, g, and b is 0.2. 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.

- `-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. Since the scanline algorithm can only compute straight rays from the pinhole camera, reflection rays cannot be cast and refraction rays are computed like transparent rays, which do not allow control over the ray direction based on the index of refraction of the material. Lens shaders cannot alter ray origin and direction. However, reflections onto environment maps do work. Motion blurring and shadows are also affected if ray tracing is turned off. Ray tracing is turned on by default.

- `-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. Shaders may override this setting. The default is 1 1 1.

- `-v on|off|`levelint
  An abbreviation for `-verbose`.

- `-verbose on|off|`levelint
  This command controls verbose messages. There are seven levels: fatal errors (0), errors (1), warnings (2), progress reports (3), informational messages (4), debugging messages (5), and verbose debugging messages (6). All message categories numerically 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).

- `-view_samples on|off`2.1
  Toggles the sample view mode. When `on`, the rgb image will be replaced with an image that shows where samples were collected during rendering. This is useful for tuning the `-samples` and `-contrast` parameters and identifying troublesome areas in the image. A pixel's intensity reflects the number of samples collected within the pixel and on its lower and left edges. It is normalized to the maximum number of samples per pixel. In addition, task boundaries are shown as red in the image.

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

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

- `-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; it consists of seven characters describing the severity level (fatal, error, warning, info, progress, debug, and vdebug). Each character is one of k (black), r (red), g (green), y (yellow), b (blue), m (magenta), c (cyan), w (white), or a dot (no color).

#### Footnotes

... compatibility.5.1
  For system and development software requirements, see the Release and Installation Notes.
...end5.2
  The -render option was introduced in mental ray 2.1.36.

Next: 5.2 Startup File Up: 5. Usage and Command Previous: 5. Usage and Command