Maya - Exporting, Batch Rendering and Scripting

Owned by Mihnea Balta (Unlicensed)
Last updated: 03 Apr, 2012Version comment
8 min read

Exporting Scenes to MXS

There are several ways of exporting a Maya scene to Maxwell's MXS format:

  • Using the Export All and Export Selection commands in the File menu. This allows you to export animations (one MXS file per frame).
  • By enabling the Persistent MXS render option and rendering.
  • Using the Pack'n'Go () button in the Maxwell shelf. This also copies all the scene dependencies to the destination directory.
  • Using the Export Geometry To MXS () button in the shelf. Note that this will not write render options and environment settings, it will only export the selected objects and their materials.
  • Using the-eo flag in the command line when batch rendering (explained below).

When using the Export commands in the File menu, the following options are available:

  • Use active camera: the renderable camera will be the camera in the active (focused) viewport.
  • Camera to use: when the above option is off, this dropdown allows you to explicitly set which camera to make renderable.
  • Animation: export the sequence of frames defined in the Frame Range group in the render options panel. This setting is ignored if the Frame/Animation ext control does not include a frame number (is set to Single Frame). The frame number will be inserted into the file name typed in the export dialog, using all the format, padding and renumbering settings from the global render options.
  • Protect geometry: sets the protection flag in the output file. When this is on, Maxwell Studio will not allow objects to be exported individually from the resulting scene.
  • Pack'n'Go: copy the dependencies (textures, IES files etc.) next to the exported MXS file.
  • Will Use Sequence Render: enable this if you are exporting an animation and you wish to render it with Maxwell's sequence rendering feature. In that mode, Maxwell appends the frame number to the output image name by itself, so the plug-in must remove the frame field from the image name written in the MXS files (otherwise, the frame number would be inserted twice).

Batch Rendering

Maya's command line rendering utility can use Maxwell when you pass the -r maxwell flag. The following Maxwell-specific flags are available:

  • -q: sets the render quality. Use 0 for draft and 1 for production.
  • -rt: render time in minutes.
  • -sl: set the target sampling level.
  • -nt: set the number of threads. Use 0 for autodetect.
  • -ml: Multilight type. Use 0 to turn off, 1 for intensity ML, 2 for color ML.
  • -low: set the render process to use low priority.
  • -cmd: specify additional command line flags to pass to Maxwell.
  • -mxs: enable persistent MXS and set the MXS path to the flag argument.
  • -mxi: set the path for the output MXI file.
  • -dis: enable/disable displacement.
  • -dsp: enable/disable dispersion.
  • -sep: set the Separate Lights flag which tells Maxwell to produce one output image for each light in the scene.
  • -eo: export only. When set to true, the scene is exported but the render is not started, so this can be used for batch export. The flag is ignored if persistent MXS is disabled.
  • -od: output image depth. Use 0 for 8 bits, 1 for 16 bits, 2 for 32 bits.
  • -rc: enable/disable the color channel output.
  • -ac: enable/disable alpha channel output.
  • -oac: use opaque alpha.
  • -emc: embed all the channels in the output image file (if the format supports it).
  • -dc: enable/disable the depth channel.
  • -zmn: set the minimum Z value for the depth channel.
  • -zmx: set the maximum Z value for the depth channel.
  • -shc: enable/disable the shadow channel.
  • -mvc:enable/disable the motion vector channel.
  • -oc: enable/disable the object ID channel.
  • -mc: enable/disable the material ID channel.
  • -rhc: enable/disable the roughness channel.
  • -fc: enable/disable the Fresnel channel.
  • -rty: render type. Use 0 for normal, 1 for diffuse only, 2 for reflection only.
  • -dl: enable/disable direct light.
  • -il: enable/disable indirect light.
  • -dcl: enable/disable direct caustic reflections.
  • -dcr: enable/disable direct caustic refractions.
  • -icl: enable/disable indirect caustic reflections.
  • -icr: enable/disable indirect caustic refractions.

All these flags with the exception of -eo override the corresponding attribute in the global render options. When they are not present, the value configured in the render options panel is used.

For example, to render frames 30 to 40 from the file animation.mb and force the maximum sampling level to 5, you could use a command similar to this:

    render -r maxwell -s 30 -e 40 -sl 5 animation.mb

Maxwell will use a node license (when available) when rendering from the command line.

In batch/command line mode, Maxwell will render one image for each renderable camera defined in the global render settings. This is implemented by first exporting and rendering each frame for the first render camera, then repeating the process for the second camera and so on.

Scripting

The main interface between the UI and the plug-in is the maxwell MEL command. The following flags can be useful for scripting:

  • -render: export the current frame and render. A few additional flags can be used to control the process:
    • -width, -height: override the resolution set in the render options
    • -camera: use the specified camera instead of the active one.
  • -sendJobToNetwork: exports the scene and passes it to the Maxwell network job wizard. Supports the same additional flags as -render.
  • -importMaterial: import the MXM file given as the second argument into the Maxwell Layered Material node given as the first argument.
  • -exportMaterial: export the Maxwell Layered Material node given as the first argument to the MXM file given as the second argument. The command brings up a dialog which prompts the user to also copy the material dependencies to the destination path.
  • -batchRender: start a batch render. The name of the renderable camera must be passed as the first argument. This does not create a second process used for rendering, as the Batch Render menu command does, but performs all the operations in the current process.
  • -getMxHomeDir: returns the path to the Maxwell installation directory.
  • -cancelBatchRender: stops a running render started with the Batch Render menu command.
  • -dryRun: performs all the operations of a normal export, but does not create output files and does not start Maxwell. Prints diagnostic messages in the script editor window.
  • -loadSkyPreset: loads the sky preset file given as the first argument.
  • -saveSkyPreset: imports the values from the preset file given as the first argument into the environment options.
  • -saveSkyHDR: produces a panoramic image of the sky defined by the environment options. Takes 3 arguments: output image path, width and height.
  • -locateFile: searches for the file given as the first argument into the alternative resource locations.
  • -exportMXS: exports the selected objects as a MXS file. Takes 6 arguments: output file path, export animation boolean, start and end frame, export camera boolean, camera name. The command does not export environment settings and render options (it's the flag used internally by the Export Geometry To MXS shelf button).
  • -getSDKVersion: returns the version of the Maxwell SDK which was used to build the plug-in.
  • -readML: import the Multilight settings from the MXI file given as the argument into the scene.
  • -listExtensions: prints the available Maxwell extensions such as hair, particles etc. Takes a boolean argument which determines if the extension parameters should also be listed.
  • -restartFire: restarts all the running FIRE instances.
  • -freezeFireState: freeze the scene state for all FIRE instances.
  • -setAPIDebug: takes a boolean argument which turns on or off debug messages from the plug-in API layer. Equivalent to the API call MaxwellMayaAPI::EnableDebugMessages.
  • -getCurrentAPIVer: returns the plug-in API version number. Equivalent to the API call MaxwellMayaAPI::GetCurrentAPIVersion.
  • -getLowestAPIVer: returns the lowest supported API version. Equivalent to the API call MaxwellMayaAPI::GetLowestSupportedAPIVersion.

There are a few other flags as well which can be listed by typing help maxwell in the script command line, but they are used internally by the plug-in.

As explained in the camera documentation, custom Maxwell attributes such as camera ISO or object render flags are only added the first time they are set to a non-default value. If you need to set these attributes from a script, you can use the maxwellSetCustomScalar function instead of setAttr, to make sure the attributes are created first.

    maxwellSetCustomScalar("double", "cameraShape1", "mxFstop", 8.0);
    maxwellSetCustomScalar("long", "cameraShape1", "mxIso", 200);

The first parameter specifies the type of the attribute. Valid values are "long" for integers and enums, "double" for floating point numbers and "bool" for booleans. The following parameters are the node name, attribute name and value. For the complete list of custom attribute names, see the file maxwellCustomAttrs.mel in the scripts/others subdirectory of the Maya installation path.

To export a MXS file in the same way as the Export commands from the File menu, you can run the following MEL snippet:

    file -force -options "useActiveCam=1;animation=0;protection=0;packngo=0;maxwellSeqRender=0;" -type "MaxwellScene" -pr -ea "/path/to/file.mxs"

The options string specifies the flags that are described above in the Export section.

Option Variables

The plug-in uses the following option variables:

  • maxwellLastMXMDir: the directory containing the last imported or exported MXM file.
  • rfrtLastParticleDir: the directory containing the last imported particle BIN file. This variable is shared with the Realflow RenderKit for Maya plug-ins.
  • maxwellLastBINMeshDir: the directory containing the last referenced mesh BIN file.
  • maxwellLastSkyPresetDir: the directory containing the last imported or exported sky preset file.
  • maxwellLastRefDir: the directory containing the last MXS file that was referenced into a scene.
  • maxwellInteractiveRes: the resolution scaling used by FIRE. Possible values range from 0 to 4 and stand for 100%, 75%, 50%, 25% and 10%.
  • maxwellInteractiveThreads: the number of thread used by FIRE.
  • maxwellInteractiveSL: maximum SL for FIRE.
  • maxwellInteractiveTime: maximum render time for FIRE.
  • maxwellInteractiveAllowSel: set to true to allow selecting objects by clicking them in the FIRE viewport.
  • maxwellInteractiveShowHUD: enable or disable drawing the HUD (polygon counts, camera gate etc.) in the FIRE viewport.
  • maxwellPreviewScene: the path to the MXS file used for material previews (swatches).
  • maxwellSwatchMode: the swatch update mode. Possible values are 0 for On Demand and 1 for Automatic.
  • maxwellSwatchQuality: the render quality used for material previews. Possible values are 0 for Draft and 1 for Production.
  • maxwellSwatchSL: maxmimum SL for swatches.
  • maxwellSwatchTime: maximum render time for swatches.
  • maxwellSwatchThreads: number of threads used for material preview renders.
  • maxwellSwatchResolution: resolution at which the swatches are rendered.
  • maxwellSpecifyTempDir: set to 1 to override the temporary path used by the plug-in.
  • maxwellTempDir: temporary path used when maxwellSpecifyTempDir is true.
  • maxwellVerbose: set to 0 to suppress warnings printed to the script editor during scene export.
  • maxwellBringIntoRV: control if the rendered images are brought into the render view.
  • maxwellOpenRV: control if the render view is automatically opened after a render is finished.
  • maxwellAutoCheck: set to 0 to disable automatic update checks at startup.
  • maxwellIgnoreVersion: the plug-in update specified by this variable will be ignored in update checks.
  • maxwellExpandEnvVars: set to 0 to disable expansion of environment variables in the paths written to MXM/MXS files.
  • maxwellNoExpandInMxm: when environment expansion is enabled, set this to 1 to disable it only for exported MXM files.
  • maxwellMatViewportRes: resolution for the viewport preview of the Maxwell Layered Material node. Possible values range from 0 to 3 and stand for 256x256, 512x512, 1024x1024 and 2048x2048.
  • maxwellMaxTextureSize: maximum resolution for textures loaded from disk. Possible values range from 0 to 6 and stand for GPU Maximum, 256x256, 512x512, 1024x1024,  2048x2048, 4096x4096 and 8192x8192.
  • mxSearchPaths: a list of semicolon-separated search paths used when looking for missing resources (textures, IES files etc.)
  • maxwellMergeCreateNewMat: when set to true, the merge materials command creates a new material. When false, the source layers are merged into the destination material.
  • maxwellMergeAddBelow: when set to true, the merge materials command adds the source layers after the layers in the destination material. When false, the source layers are placed first.
  • mxShelfVersion: the version of the existing Maxwell shelf. Used to detect when the shelf must be updated. You can remove this variable to cause the shelf to be recreated.