Render from the command line using mental ray

 
 
 

To render from the command line

  1. Do one of the following:

    At the command prompt, shell, or Terminal window, type:

    Render -r <renderer name> <options> <filename>
    

    where <renderer name> is the name of the renderer:

    • mr = NVIDIA.mi®mental ray®
    • mi = exporting .mi files using the command line
    • sw = software renderer
    • hw = hardware renderer
    • vr = vector renderer
    • hw2 = hardware 2.0 renderer
    • file = use the renderer stored in the Maya file

    and where <filename> is (generally) a Maya ASCII or Maya Binary file, and <options> is one or more of the options or flags.

    This renders the image or animation using the renderer you specify in the command line.

    Note

    If you do not explicitly specify a renderer, Maya uses the renderer specified in the scene file. This behavior is different from that of Maya 2010.

  2. At the command prompt, type:
    Render <options> <filename>
    

    <filename> is (generally) a Maya ASCII or Maya Binary file, and <options> is one or more of the options or flags.

    This renders the image or animation using the renderer defined in the file.

mental ray for Maya renderer command line renderer flags

Below are all the flags and their descriptions unique to command line rendering with the mental ray for Maya renderer. You can also type Render -r mr -help in a shell or Terminal (Mac OS X) window to see this list.

See also Common flags for the command line renderer.

Flag Description
-v <int>

Set the verbosity level:

  • 0 turn off messages
  • 1 for fatal errors only
  • 2 for all errors
  • 3 for warnings
  • 4 for informational messages
  • 5 for progress messages
  • 6 for detailed debugging messages.
-rt <int>

Specify the number of rendering threads.

-art

Enable this option so that Maya automatically calculates the number of threads that should be used to best take advantage of the CPUs (or cores) on your workstation.

-mem <int>

Soft limit for the memory used by mental ray (in MB). A soft limit implies that mental ray may actually use more memory than indicated.

-aml

Enable this option so that Maya dynamically calculates the memory limit prior to the start of rendering. This feature can be enabled at all times to obtain better performance.

-ts <int>

Set the pixel width and height of render tiles.

-at

Enable this option to automatically determine the optimal tile size at render time.

-rnm <boolean>

Network rendering option. If true, mental ray renders almost everything on slave machines, thus reducing the workload on the master machine.

-lic

Obsolete flag.

-reg <int int int int>

Set sub- region pixel boundary of the final image (left, right, bottom, top).

-bakeSetDefault

Specifies a bake-set to include all objects not assigned to any other bake-set in the scene.

-rto

Render target only. Select this option to perform a 2D render and render only the render targets in your scene.

-ort

Omit render target. Select this option to perform a 3D render and render only the dependencies in your scene.

-rat

Render all targets. Select this option to include all renderable dependencies and render targets in the batch render.

-perframe

If mental ray does not render your animation correctly, use this flag to re-translate the frames from scratch. This feature is only available for batch rendering.

-sampling (-sa)

If you open a pre-Maya 2014 scene that renders using the mental ray for Maya renderer, your sampling settings are changed to use Unified Sampling. Some features, such as contour rendering, are not supported with Unified Sampling.

To render legacy scenes with their previously-saved legacy sampling settings using the command line renderer, use this flag with the following arguments:

0 - Unified Sampling

1 - Legacy Rasterizer

2 - Legacy Sampling

For example:

/path/to/Maya/bin/Render -r mr -v 5 -proj /path/to/proj -sampling 2 sceneName.ma

-unifiedQuality (-uq)

If you set -sampling 0 (unified sampling), or do not set the -sampling flag on pre-Maya 2014 scenes (in which case Unified Sampling is used), you can also set the Unified Sampling Quality using this flag.

For example:

/path/to/Maya/bin/Render -r mr -v 5 -x 1 -uq 1.25 old_2012_sceneFile.ma

Exporting MI files using the command line

You can use the command line to export your .mi file to be rendered with a mental ray Standalone renderer. Use this approach for the following purposes:

Example

Two examples of how to use the command line for exporting .mi files is as follows. For more information regarding the export options selected below, see Command Line Flags.

Example 1:

Render -r mi -im "cmdrenderTest" -of "gif" -binary 0 -file "C:/temp/test.mi" mayascene.ma

This command creates and exports the mi file C:/temp/test.mi (set by -file flag) in ASCII format (-binary flag). When the test.mi file is rendered with a Standalone renderer, the output image is in gif format (-of flag), with the filename cmdrenderTest (-im flag), and stored in the current directory.

Example 2:

Render -r mi -rd "C:/images" -im "cmdTest" -of "tif" -s 10 -e 15 -b 1 -binary 0 -perframe 0 -exportPathNames "1111111111" -file "C:/temp/test.mi" mayascene.ma

The command above exports frames 10 to 15 (-s, -e, and -b flags), and exports one .mi file for the entire animation (-perframe flag). The exported .mi file is in ASCII format (-binary flag), with the path and filename C:/temp/test.mi. The .mi file uses the absolute path for its full name (-exportPathNames flag).

When the test.mi file is rendered with a Standalone renderer, the output image file is in tif format (-of flag) with the filename cmdTest (-im flag), and stored in the c:/images directory (-rd flag).

Command Line Flags

Below are all the flags and their descriptions unique to exporting .mi files using the command line. You can also type Render -r mi -help in a command prompt (Windows) or Terminal window (Linux, Mac OS X) to see this list. (Note that the Render command is used even though you are exporting a file for rendering with a Standalone renderer.)

See also Common flags for the command line renderer.

Export flags

Flag Definition
-file <string>

Name of the exported .mi file. If not specified, the scene name is used.

-binary <boolean>

Export .mi file in binary or ASCII format.

0=ASCII

1=binary

-tabstop <int>

Tab size to be used in the .mi file. Use this option to set the number of space characters used to indent lines in your .mi file. This feature improves the readability of your file. For use with .mi files of ASCII format only.

-perframe <int>

Controls per-frame .mi file export of animations.

  • 0: export a single .mi file containing the whole animation, exploiting incremental changes
  • 1 or 2 or 3: export one .mi file per frame not using incremental changes. The .mi filename used for each option varies and is as follows:
    • 1: Each .mi file is named name.mi.#
    • 2: Each .mi file is named name.#.mi
    • 3: Each .mi file is named name.#

Incremental changes are the scene modifications between the first frame and each successive frame of an animation. Mental Ray renders the first frame and keeps this frame, then edits it with the appropriate scene modifications for the next successive frame. These scene modifications are incremental changes.

-padframe <int>

Set frame number padding (fixed field width) used to generate file name extensions during per-frame export. Padded numbers are frame numbers that have a specified number of digits, where 0s are used to fill the unused digits.

-perlayer <bool>

When on, exports a .mi file for each render layer. Default is 1.

-exportPathNames <string>

Specify file path option. Each character in the string specifies the file path option for a different type of file, the order of which is as follows: link library, include .mi file, texture file, lightmap, light profile, output image, shadow map, final gather map, photon map, demand load object .mi file.

The file path options available are:

  • 0-no change; 1-absolute; 2-relative; 3-no path, or
  • 0-no change; a-absolute; r-relative; n-no path

Example: -xp aarrararra will use absolute path for link library, include file, light profile, shadow map, and demand load object .mi file; relative path for texture file, lightmap, output image, final gather map, and photon map.

Default: No change.

See Mayatomr for more information.

-fragmentExport

Enable fragment export. This option exports the selected nodes with further options to also export the related or connected nodes. Use this option to create an .mi file that contains only the selected objects or nodes.

Default: Export the entire scene.

This flag is equivalent to the Export Selection option in the Maya interface.

Should be used in conjunction with flags:-fragmentMaterials, -fragmentIncomingShdrs, -fragmentChildDag

Example:

mayatomr -mi -active -fragmentExport -fragmentChildDag -file “text.mi”

Note that the -fragmentMaterials, -fragmentIncomingShdrs, and -fragmentChildDag flags must be used on conjunction with -fragmentExport. In addition, you must activate the flags by using -active.

See Mayatomr for more information.

-fragmentMaterials

Used in combination with fragment export to also export materials for the shape/transform nodes found in the current selection. Must be used in conjunction with -fragmentExport.

Default: Ignore attached materials.

See Mayatomr for more information.

-fragmentIncomingShdrs

Used in combination with fragment export to also export shading nodes that are connected to nodes found in the current selection (i.e. driving nodes). Must be used in conjunction with -fragmentExport.

Default: Ignore connections.

See Mayatomr for more information.

-fragmentChildDag

Used in combination with fragment export to also export any child dag of the transform node found in the current selection. Must be used in conjunction with -fragmentExport.

Default: Export only the selected object/instance.

See Mayatomr for more information.

-exportFilter <int>

Filters certain types of mental ray entities from the .mi file using an integer argument. The integer argument is a bitmap where each bit represents a single filter entry. See Mayatomr for a list of entities that can be filtered and their corresponding bit value.

Default: No filter.

-exportFilterString <string>

Filters certain types of mental ray entities from the .mi file using a string argument. Each character of the string represents a corresponding filter entry. See Mayatomr for a list of entities that can be filtered and their corresponding bit value.

Default: No filter.

-reg <int int int int>

Set sub-region pixel boundary of the final image (left, right, bottom, top).

Generating lightmaps using the command line

The lightmap command uses mental ray lightmap rendering to bake lighting into textures. Use this approach to increase rendering efficiency and save time required for your project. Illumination calculations are expensive and time-consuming. Therefore, if the lighting conditions in your scene do not change, or if you have a particularly complex shading network, you can precompute and store your lightmap in advance so that lighting calculations are not performed at rendering time.

Using the lightmap command, global settings such as output directory, camera name, shadow, objects can be specified. Unless overridden, the texture bake-set assigned to each object is used by default to control color mode, image format etc.

Example

An example of how to use the command line to render a lightmap is as follows. For more information regarding the export options selected below, see Command Line Flags.

Render -r lightmap -rd "C:/output" -sel pSphere1 -sel pSphere2 -override 1 -colorMode 3 -occlusionRays 16 

The above command bakes both pSphere1 and pSphere2 and saves lightmaps in C:/output.

Command Line Flags

Below are all the flags and their descriptions unique to command line rendering with the lightmap renderer. You can also type Render -r lightmap -help in a command prompt (Windows) or Terminal window (Linux, Mac OS X) to see this list.

See also Common flags for the command line renderer.

General purpose flags

Flag Definition
-rd <string>

Absolute path to the lightmap directory. If not specified, mentalray directory is used.

-camera <string>

Select the desired view by specifying the corresponding camera name. Features such as reflection and specular highlights are view dependent and thus you may wish to change your view by selecting this option.

-shadow <boolean>

Specify whether or not to bake shadows (shadow should be enabled in the scene if you want to bake shadows). If 1, bake shadows.

Default: 0. No shadow baking.

-all <boolean>

Bake all objects in the scene. If 0, bake selected objects.

-sel <name>

Select which objects, groups and/or sets to bake.

Texture bake-set setting flags

Flag Definition
-override <boolean>

Use the following settings, overriding the texture Bakeset attributes saved in the scene.

-colorMode <int>

Color mode option. Specifies the lighting information to be computed.

  • 0 : Light and Color. Computes both the incoming light and surface color to produce the final color.
  • 1 : Light only. Computes both direct and indirect incoming light.
  • 2 : Global Illumination only. Computes global illumination (indirect light) only.
  • 3 : Occlusion. Computes grey scale value of the amount of light that reaches a point.
  • 4 : Custom Shader. Bakes the specified custom shading network into the bake-set.

Default: 0

See Texture bake set attributes for more information.

-occlusionRays <int>

Number of occlusion rays. Increasing the number of occlusion rays improves quality, but reduces performance speed. Used if color mode is set to occlusion.

Default: 64.

See Texture bake set attributes for more information.

-occlusionFalloff <float>

Occlusion falloff. Determines the maximum length of an occlusion ray. Rays longer than this value are not considered for occlusion. Used if color mode is set to occlusion.

Default: 0.

See Texture bake set attributes for more information.

-normalDirection <int>

Normal Direction.

You may want to adjust the direction of your normals depending on whether you are baking from the outside or the inside of a room. For example, if you are baking from the outside of a room, and you do not wish the lighting in your scene to be affected by the lighting inside the room, then set your normal direction to Surface Back (if your normals are currently pointing inwards the room).

  • 0 : Face Camera (towards the camera)
  • 1 : Surface Front (outwards from the object surface)
  • 2 : Surface Back (inwards from the object surface).

Default: 1.

See Texture bake set attributes for more information.

-orthogonalReflection <boolean>

Use surface normal as a reflection direction. Reflection is view dependent because reflection changes depending on viewing angle. It is therefore undesirable to bake the reflection from a particular viewing angle, especially if the lightmap information is used in a camera-fly environment. Using this option, a surface normal rather than an eye ray is used to calculate reflection. The result of the computation is a reflection that is like an environment map. Set to 1 to select this option.

Default: 0.

See Texture bake set attributes for more information.

-customShader <string>

Name of a custom shader to compute lighting. Used if colorMode is set to Custom Shader.

See Texture bake set attributes for more information.

-prefix <string>

The lightmaps generated by this baking will have names beginning with this prefix.

-xResolution <int>

Lightmap X resolution.

-yResolution <int>

Lightmap Y resolution.

-fileFormat <int>

File format:

  • 1 : tiff
  • 2 : iff
  • 3 : jpg
  • 4 : rgb
  • 5 : rla
  • 6 : tga
  • 7 : bmp.
-bitsPerChannel <int>

Number of bytes per channel: 1, 2, or 4.

-samples <int>

Number of samples per pixel. Increasing the number of samples will improve the accuracy of your rendered result; however, it will also increase the cost of your computation.

-bakeToOneMap <boolean>

Generate one lightmap for all the objects. Ensure that UV of the objects do not overlap. Set to 1 to select this option.

Default: 0.

-bakeAlpha <boolean>

Include alpha in the resulting texture baking process. Set to 1 to select this option.

Default: 0.

See Texture bake set attributes for more information.

-alphaMode <int>

How to compute alpha channel.

  • 0 : Pass Through. Leaves alpha channel unaffected. Alpha channel contains the output from the shading network. Use for custom shaders only.
  • 1 : Surface Transparency. Alpha channel will contain surface transparency value.
  • 2 : Luminance of Surface Color. Alpha channel will contain the luminance of the surface color.
  • 3 : Coverage. The alpha channel will store the coverage of the point sampled.

Default: 1.

See Texture bake set attributes for more information.

-finalGatherQuality <float>

Final gather precompute quality.

When rendering from the camera, mental ray precomputes a final gather pass before actually rendering the scene. This precomputation pass is disabled by default for baking. You can use this option to perform the same precomputation pass when baking from the command line.

Default: 1.

See Mayatomr for more information on how to set the float argument to obtain the final gather quality that you desire.

-finalGatherReflect <float>

Final gather precompute quality for reflection.

Use this option to calculate the reflectivity of your object when precomputing the final gather pass for your lightmap. Use the float argument to set the fraction of final gather points that are precomputed, not on the object being baked, but instead on objects hit by the reflection rays cast from the object being baked.

Default: 0.

See Mayatomr for more information.

-uvRange <int>

Bake only specified UV range to lightmap.

  • 0 : 0 to 1
  • 1 : Entire UV space
  • 2 : User specified space range. (uMin uMax vMin vMax).

Default: 0.

-uMin <float>

Min U value for lightmap. Used if uvRange is set to User Specified. Only specified UV range is baked to lightmap.

Default: 1.

-uMax <float>

Max U value for lightmap. Used if uvRange is set to User Specified. Only specified UV range is baked to lightmap.

Default: 1.

-vMin <float>

Min V value for lightmap. Used if uvRange is set to User Specified. Only specified UV range is baked to lightmap.

Default: 1.

-vMax <float>

Max V value for lightmap. Used if uvRange is set to User Specified. Only specified UV range is baked to lightmap.

Default: 1.

-overrideUvSet <boolean> Use in conjunction with the -uvSetName flag to override the currently assigned UV set and use the specified UV set instead.

Set to 1 to enable this option and use the -uvSetName flag to specify the name of the UV set.

Default: 0.

-uvSetName <string>

Name of UV set to use.

Creative Commons License Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License