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

Depending on your account's orchestrator setup, you may be able to target Windows machines, Linux, or both. Only Arnold and Vray scenes can be rendered on Linux. To achieve this we export either ass files or a vrscene file respectively. To use renderers that are built into 3ds Max, or other Windows only renderers, you must be on a Windows or multi-platform orchestrator.

In the cases above where you target Linux, the remote filesystem structure is slightly different in that drive letters are removed from the paths. Therefore the render commands kick or vray will refer to filenames that have no drive letters. C:\\some\path becomes /some/path. In order for the render processes to find assets, we ship path-mapping files along with the jobs assets. These file formats are renderer dependent. Vray uses XML, while Arnold uses JSON.

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.

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¶

Specify the location where files are written to. When tasks are complete, you'll be able to download rendered files to this folder on your computer.

There are some constraints to be aware of:

All files produced by the job must be written to a location below the output_path, otherwise they won't be available.
None of the assets you upload may exist anywhere below the output 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 many 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, which 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 select how many scout frames you want and let the submitter calculate scout frames from the current frame range. To specify three well-spaced scout frames automatically, enter auto:3.

Note

The remote render nodes execute tasks in their entirety, so if you have chunk size set greater than 1, then all frames are rendered in any task containing 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¶

The pre-submission script is a hook that 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.

We provide default scripts for exporting ass files for Arnold, vrscene files for Vray, and we export the Max scene and some additional files for native Windows renders. 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, as they work in concert with each other.

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 and an amendments() 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 is injected automatically.
You may add any number of extra arguments.
The main() function is called before submission. Do whatever you need to here, such as write intermediate files. It should return an object with a list of files that you want to add to the uploaded assets, and any environment amendments. Environment amendments are a list of dictionaries, containing the variable name, value, anda merge_policy to secify whether the variable is exclusive or should be appended to any existing value.
The amendments() function is called on it's own in order to populate the preview window with whatever additions would be generated by main(). Do not write any files in this function. Ideally, the main() function's return value is the same as that of the amendments() function, and it may be possible to call the amendments function from main(). However, in some cases it's impossible to know for example the names of intermediate files before they are generated. In this case it would be acceptable to return dummy data from the amendments() function, so long as main() returns the real payload amendments before submission.

For more information, check out the the export_ass.py and export_vray.py scripts in the distribution.

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 {
        "upload_paths": renderable_files,
        "environment": [ 
            {
                "name": "VARNAME",
                "value": "/some_value",
                "merge_policy": "exclusive"
            }
        ]
    }

def amendments(dialog, *args):
     return {
        "upload_paths": ["Other upload filenames will be determined on submission"],
        "environment": [ 
            {
                "name": "VARNAME",
                "value": "/some_value",
                "merge_policy": "exclusive"
            }
        ]
    }

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

Note

You must have Conductor Core installed in order to use the upload daemon and other command line tools. See the installation page for options.

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

    conductor uploader

Once started, the upload daemon runs continuously and uploads 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