Skip to content

3ds Max reference

The submitter for 3ds Max is a plugin with a dialog that allows you to configure and submit render jobs to Conductor.

This document is a comprehensive reference for all features and concepts. If you want to get up and running fast, head over to the tutorial page.

Overview

A Conductor submission is a http request that contains all the details of your Job as a JSON payload. For example, it contains a title, a list of commands to run on each render node, a list of assets that the Job depends on, and a set of variables to be set in the remote environment.

The filesystem structure in the remote environment is based on the paths of assets you upload and therefore mirrors your local filesystem. The remote render nodes run Linux, so if you submit from a Windows computer, the structure is slightly different in that drive letters are removed from the paths.

There are four tabs to help you manage the submission:

  • Configure Set the submission parameters. The values you set here are saved in the scene file continuously. If you close and reopen the dialog, it will be in the same state you left it. The same is true if you close and reopen the scene.
  • Preview See the resolved payload at any time. We recommend you use this tab to check submission details, such as the syntax of render commands.
  • Validation On submission, we check the scene to ensure there's nothing that could cause unexpected render results and display the results in this tab. Validation messages can be errors, warnings, or informational. In case any messages are errors, the Continue submission button is disabled.
  • Response If the submission is successful, a link to the Conductor dashboard is displayed here.

As Conductor jobs do not run on Windows render nodes, the options for 3ds Max submissions are ass files for Arnold and vrscene files for Vray. We provide a mechanism to export these files on your local machine and include them in the submission.

Configure tab

Job Title

Job Title is the title that appears in the Conductor dashboard. You may use angle-bracket tokens to construct it. For example, if you want it to contain the scene name and the renderer name in uppercase, separated by a dash, enter the following expression.

3dsmax <scenenamex> - <upper renderer>

which resolves to something like:

3dsmax Vsphere_Max2013 - V-RAY NEXT, UPDATE 3.2

Note

Only tokens in the JOB scope are valid here. See the token table below.


Conductor project

This refers to one of the projects you created on the Conductor dashboard. The dropdown menu is populated or updated when the submitter connects to your Conductor account.


Instance Type

Specify the hardware configuration used to run your tasks. You are encouraged to run tests to find the most cost-efficient combination that meets your deadline. You can read about hardware choices and how they affect costs in this blog post.


Preemptible

Preemptible instances are less expensive to run than non-preemptible. The drawback is that they may be stopped at any time by the cloud provider. The probability of a preemption rises with the duration of the task. Conductor does not support checkpointing, so if a preemption occurs, the task starts from scratch on another instance. It is possible to change the preemptible setting in the dashboard for your account.


Destination path

On Conductor's render nodes, the directories that store your uploaded assets are read-only. Therefore you can't write out renders into those directories, and instead, the submission must specify a different directory to save. This destination path appears in the submission as output_path and is one of only three writable locations, the others being the home directory and the temp directory.

Also, be aware, the destination path must not contain any of the assets you upload.

If your render produces intermediate files such as texture conversions or GI caches, their paths should be below the destination path.

By default, the destination path is set to <project>/renderoutput.


Software

Choose the renderer that will render your Job. In most cases, the correct renderer version is detected automatically from Render Settings. If not, you can choose one here.


Chunk Size

A chunk is the set of frames handled by one task. If your renders are reasonably fast, it may make sense to render may frames per task because the time it takes to spin up instances, and sync can be significant by comparison.


Use Custom Range

When enabled, a text field appears, and we ignore the frame range specified in the Render Settings window. Instead, you enter a frame-spec.

A frame-spec is a comma-separated list of arithmetic progressions. In most cases, this will be a simple range:

1001-1200

However, any set of frames may be specified efficiently in this way.

1,7,10-20,30-60x3,1001

Negative numbers are also valid.

-7,-20--10


Scout Frames

Specify a set of frames to render first. We start any tasks that contain these frames. All others are put on hold. This allows you to check a subsample of your sequence before committing to the full render.

You can use a frame spec to specify scout frames, for example: 1-100x30. Alternatively, you can specify how many scout frames you want and let the submitter figure it out based on the current frame range. To specify three well-spaced scout frames automatically, enter auto:3.

Take note that the remote render nodes execute tasks in their entitity, so if you have chunk size set greater than 1, then all frames will be rendered in any task that contains a scout frame.


Info

This section displays information on the number of frames and scout frames calculated from the values in the Frames section above.


Extra Environment

By default, your job's environment variables are defined automatically based on the software and plugin versions you choose. Sometimes, however, it can be necessary to append to those variables or add more of your own.

For example, you may have a script you want to upload and run without entering its full path. In that case, you can add its location to the PATH variable.

Add an entry with the Add button and enter the Name of the variable: PATH, the Value /my/scripts/directory. Make sure Exclusive is switched off to indicate that the variable should be appended.

You can also enter local environment variables in the value field itself. They will then be active in the submission. You might use $MY_SCRIPTS_PATH (if it's defined) for the value in the above example.

You can always check the resolved value of the entire submission in the Preview tab.


Extra Assets

The submitter interrogates the 3ds Max scene file to find paths to the textures and other files on which the render depends. However, you may want to upload a script, a color profile, or some other asset that 3ds Max's asset scraper doesn't find. In these cases, you should explicitly browse the missing files to make sure they are available on the render nodes.


Metadata

Metadata consists of arbitrary Key/Value pairs that are attached to your submission. The purpose of metadata is to allow you to filter information in the Conductor web UI.

Example: To break down costs by shot number, you can add a metadata key called shot and enter the shot number in the Value field. You can also enter environment variables in the value field that resolve in the submission. In the above example, you might use $SHOT for the value.


Advanced


Pre-submission script

If enabled, the pre-submission script runs automatically before the Job is submitted. It provides an opportunity to make preparations for the submission. It can make use of tokens to specify both the location of the script and the parameters sent to it.

Since Conductor currently runs on Linux only, we provide default scripts for exporting ass files for Arnold and vrscene files for Vray. The appropriate entry is populated when you first open the dialog based on the renderer selected in Render Setup.

The default script entries consist of 2 parts: 1. The path to the script. 2. The prefix for the exported file.

If you change the prefix, for example, remove the timestamp token in the Vray path, then be sure to remove it in the task template.

Write a custom pre-submission script.

If the default scripts are not suitable for your needs and you want to write your own, you should follow these guidelines.

  • The script must be a Python script with a main() function.
  • Place it anywhere you like on your filesystem.
  • The first argument is always the dialog object itself. This allows you to query the value of any setting contained in the dialog. You don't need to specify the dialog in the pre-submission script field as it we insert it automatically.
  • You may add any number of extra arguments.
  • The main() function should return a list of files that you want to add to the assets uploaded to Conductor.

Example script:

def main(dialog, *args):
   """Export assets needed for a render."""
   renderable_files = []
   prefix = args[0]

   main_sequence = dialog.main_tab.section("FramesSection").main_sequence

   for frame_number in main_sequence:
      filename = export_one_file(prefix, frame_number)
      renderable_files.append(filename)

    return renderable_files

The Execute button is for development and testing purposes. It will execute the script in its entirety.


Task Template

This is a template for the commands to run on remote instances. It uses tokens in angle brackets similar to those used in the Job title above, but with the addition of frame number tokens such as <start>, <end>, and <step>.

If you examine the task template and then check the Preview tab, you'll see how task commands are resolved.

Example Vray template and resolved task commands

vray  -display=0 -verboseLevel=4 -sceneFile="<posix project>/vray/<timestamp>_<scenenamex>.vrscene"  -remapPathFile="<posix project>/vray/<timestamp>_<scenenamex>.xml"   -imgFile="<posix project>/renderoutput/<scenenamex>.exr" -frames=<start>-<end>

vray  -display=0 -verboseLevel=4 -sceneFile="/Users/julian/Documents/3ds Max 2021/vray/210225_111805_Vsphere_Max2013_jpm.vrscene"  -remapPathFile="/Users/julian/Documents/3ds Max 2021/vray/210225_111805_Vsphere_Max2013_jpm.xml"   -imgFile="/Users/julian/Documents/3ds Max 2021/renderoutput/Vsphere_Max2013_jpm.exr" -frames=1-2
vray  -display=0 -verboseLevel=4 -sceneFile="/Users/julian/Documents/3ds Max 2021/vray/210225_111805_Vsphere_Max2013_jpm.vrscene"  -remapPathFile="/Users/julian/Documents/3ds Max 2021/vray/210225_111805_Vsphere_Max2013_jpm.xml"   -imgFile="/Users/julian/Documents/3ds Max 2021/renderoutput/Vsphere_Max2013_jpm.exr" -frames=3-4

Let's beak it down:

  • <posix project>. The project token resolves to the 3ds Max project. The posix modifier strips away any drive letter and converts backslashes to forward slashes for the Linux render nodes.
  • <timestamp>_<scenenamex>.vrscene. Here we refer to the name of the vrscene file that the pre-submission script exported. Each submission generates a timestamp that can provide a unique tag to any aspect of a submission. You'll notice how we construct the export filename from the same tokens in the pre-submission script field. The <scenenamex> token refers to the current 3ds Max scene filename, without the .max extention. We can then add the .vrscene extension to the filename.
  • <timestamp>_<scenenamex>.xml. This refers to an xml file that tells Vray how to translate any Windows paths in the file to their Posix counterparts on the Linux filesystem. The pre-submission script created this file alongside the .vrscene. For more info, see the vray documentation.
  • <posix project>/renderoutput/<scenenamex>.exr. The output filename. Note that Vray automatically inserts a 4-padded frame number in the filename just before the .exr extension.
  • -frames=<start>-<end>. In the example, we have set the the frame spec to 1-4, and the chunk-size to 2. Therefore the submission contains two tasks, each rendering a maximum of 2 frames. The start and end parameters refer to the chunk range and are substituted into the template accordingly.

Preempted retries

A task may fail if the machine is preempted by the cloud provider. Set a value above 0 if you would like to try the task again automatically in this situations.

Notifications

Add one or more email addresses, separated by commas to receive an email when the job completes.


Location Tag

Attach a location to this submission for the purpose of matching to an uploader and/or downloader process.

If your organization is distributed in several locations, you can enter a value here, for example, London. Then when you run a downloader daemon you can add the location option to limit downloads to only those that were submitted in London.


Use Upload Daemon

If Use upload Daemon is off, then the task of uploading assets happens within the 3ds Max session itself. Although this requires no extra setup, if you have a large number of assets, 3ds Max will be blocked until the upload completes.

A better solution may be to turn on Use Upload Daemon. An upload daemon is a separate background process. It means assets are not uploaded in the application. The submission, including the list of expected assets, is sent to Conductor, and the upload daemon continually asks the server if there are assets to upload. When your job hits the server, the upload daemon will get the list and upload them, which allows you to continue with your work.

You can start the upload daemon either before or after you submit the job. Once started, it will listen to your entire account, and you can submit as many jobs as you like.

To run an upload daemon, open a terminal or command prompt, and run the following command.

~/Conductor/bin/conductor uploader
%userprofile%/Conductor/bin/conductor uploader

Once started, the upload daemon runs continuously, uploading files for all jobs submitted to your account.


Preview tab

The preview tab shows how all the other settings combine to create a submission. Its purpose is to help you check over the final submission properties to avoid mistakes. The data in the preview panel is updated every time you show it.

Note

The Preview panel doesn't run any pre-submission script, and therefore the JSON it displays does not contain any assets it generated.

Validation

When you press Submit, we check the scene to ensure there's nothing that could cause unexpected render results. You'll notice the dialog displays the Validation tab, and if it contains critical errors the Continue Submission button will be inactive. If it includes warnings, you should read them before you continue.

Response

If you press Continue submission on the Validation tab, the Job is sent to Conductor, and the dialog switches to the Response tab, which displays a link to the Job on the Conductor web dashboard.

Tokens

Tokens exist at two different scopes:

  • Job. A value that is constant for the Job. Example project
  • Task. A different value for each generated task. Example chunk_length

All available tokens are listed below.

Token name Example value Scope
conductor C:/Users/you/Conductor Job
scenefile C:/projects/SampleFiles/my_scene.max Job
scenedir C:/projects/SampleFiles Job
scenenamex my_scene Job
scenename my_scene.max Job
project C:/projects/SampleFiles Job
renderer Arnold Job
timestamp 210225_111805 Job
start 1 Task
end 5 Task
step 2 Task
chunk_length 3 Task

Token modifiers

Sometimes it can be useful to modify the value of a token. For example, .ass files are exported with frame numbers that are 4-padded. When referring to those ass files in the task command, we need some mechanism to build the filename with padded numbers. The pad modifier does this:

The template below inserts the chunk's start frame and pads it with zeros to a width of 4.

/path/to/images/<scenenamex>.<pad start 4>.exr

To give the following result:

/path/to/images/myfile.0037.exr

All modifier uses begin with the modifier, followed by the token, and then any other values needed.

Modifier Syntax Example template Example result
pad token width <pad start 5> 00037
posix token <posix C:/path/to/myfile> /path/to/myfile
upper token <upper Hello> HELLO
lower token <lower HELLO> hello
basename token <basename /path/to/myfile.ext> myfile.ext
basename_x token <basename /path/to/myfile.ext> myfile