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
|largebsp
- Selects the standard binary space partitioning ( BSP) algorithm, or the new
bsp2 algorithm to be 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
- Can be used to disable ambient occlusion support completely.
Default is on. Actual computation is performed on demand of shaders
only.
- -ao_rays nraysint
- Number of rays to compute ambient occlusion. The default is
256.
- -ao_cache on|off
- Toggle ambient occlusion cache precomputation. Default is
off.
- -ao_cache_density density
- Maximum ambient occlusion cache points density per pixel.
Default is 1.0.
- -ao_cache_points points
- 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:…"
- Specifies a directory where assembly files are stored. By
default, assembly files are searched in the current working
directory.
- -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_size sizeint
- 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 signs2.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
- Controls storage of frame buffers in
files on disk to conserve memory. Default is
on, which
enables disk storage in memory mapped files. The cache
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]
nraysint
[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 reflectint
[refractint
[diffuseint
[sumint]]]
- 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 sizeint
- 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_pointsPint
- 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 nphotonsint
[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 multiint
superint
- 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 fdint
- 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
- Control the emission of importons. The default is off.
- -importon_density density
- 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
- 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
- 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 nraysint 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 nint
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 modeint |
"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_interppointsnint
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 nraysint
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.
- -iray on|off3.8
- If set to
on, mental ray will use the iray rendering mode to render the scene.
The default value is off.
- -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".
- -M "path1:path2:…" 3.8
- This is an abbreviation for -map_path.
- -map_cache_size sizeint 3.8
- The size of the global cache for all maps currently present in
memory, where size is the amount in Megabytes. The
default is 10 (MB).
- -map_page_size sizeint 3.8
- The internal memory for storing maps is subdivided in pages,
whose size is controlled by this option, where size is
the amount in Kilobytes. The default is 16 (KB).
- -map_path "path1:path2:…"
3.8
- File search path for map data files.
- -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 stepsint
- 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 fly-throughs.
- -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 nphotonsint
[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 reflectint
[refractint
[sumint]]
- 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.
- -progressive on|off
3.7
- Enable progressive
rendering if set to
on. Default is
off.
- -progressive_error_threshold threshold
3.8
- -progressive_max_samples numint
3.8
- Set criteria for automatic stop of progressive rendering and iray. See related scene options for detailed
description.
- -progressive_min_samples numint
3.7
- -progressive_subsampling_size
sizeint 3.7
- Control progressive
rendering behavior and performance. See related scene options for detailed
description.
- -rast_motion_factor
factor
- 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
- 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
- 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 beginint
[endint
[incint]]
- 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
xintyint
- 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
minintmaxint
[defminint
defmaxint]
- This option determines the minimum and maximum sample rate given as powers of 2. Each
pixel is sampled at least 22·min and at most
22·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
defminint and defmaxint
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 22·min and more than
22·max samples, and in areas with no object
sample settings it will further reduce that range to
22·defmin through 22·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 numint
- 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 pass
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.
- -stereomethod
eyedistance
- This option controls stereoscopic rendering. It sets or
overrides the existing stereo
parameters on the (first) render camera in the scene.
- -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.
- -task_order
hilbert|spiral|rightleft|leftright
|topdown|bottomup
- 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_sizeint
- 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 nthreadsint
- 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
nthreadsint 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 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. Additionally, it is
possible to limit the sum of reflection and refraction rays with
sum. The defaults are 2 2 4.
- -v
on|off|levelint
- An abbreviation for -verbose.
- -verbose
on|off|levelint
- 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_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. 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.
Copyright © 1986-2010 by
mental images GmbH