3ds Max Sanity Checker Customization

  • Tutorial

INTRODUCTION

The integrated 3ds Max Submitter ("Submit Max To Deadline", a.k.a. SMTD) provides an optional sanity checker subsystem which can be used to validate the scene content before submitting a job to Deadline and even fix some of the detected issues automatically.

The Sanity Checker was designed to be flexible and expandable by 3rd parties. The following tutorial demonstrates the workflows involved in defining custom sanity check and repair functions. read this blog for more information on Autodesk 3DS Max.

SANITY CHECKER OVERVIEW

Running Sanity Checks

The SMTD Sanity Checker can be enabled via the "Run Sanity Check Automatically Before Submission" checkbox in the "Sanity Check" group of controls located just above the tabs and below the Priority slider.

The Sanity Check functions will be run when the SUBMIT button is pressed if the option is checked. If the test returns no errors, the scene will be submitted to Deadline. If the test returns errors, no submission will be performed. If the "Run Sanity Check Automatically Before Submission" checkbox is not checked, the scene will be submitted without performing any tests.

Alternatively, pressing the "Run Now!" button will trigger the tests manually without submitting a job.

If there are errors, the Sanity Checker dialogue will pop up and list the results of those tests that the scene failed to pass.

The top half of the dialogue lists the detected problems, the bottom half logs the performed operations. The color indicator in the middle right is red when the job cannot be submitted and green when the job can be submitted (for example if there were non-fatal errors and they were unchecked and thus ignored).

In this case, the top FATAL error tells us the scene contains no objects which makes it a bad candidate for rendering on Deadline.

The other errors report that the render output path was not set, the scene was never saved and is thus Untitled, the current Viewport is not a Camera and the Render Setup dialog is set to render a single frame.

All but the first error are not fatal and could be ignored in some cases. For example, rendering a single frame, while not typical, is still possible on Deadline. Rendering the current view is also not completely out of the question, it is just assumed that in a production environment 99.9% of the cases the viewport would be set to a valid camera. So when it comes to non-fatal errors, it is up to the user to decide whether to fix the reported issues or to ignore them.

Error Types

In general, the Sanity Checker recognizes three error levels:

  • FATAL - if the error is not fixed, the scene cannot be submitted to Deadline. Disabling the checkbox in front of the error report line will NOT ignore the error.
  • Can Be Fixed - this is an error that will prevent the scene from submitting to Deadline unless the error is fixed or the checkbox in front of it is disabled. Right-clicking the error report line will attempt a fix by calling a function designed to deal with the particular issue.
  • Warning - this is not a blocking error, just a warning that some conditions in the scene could be unexpected or undesired. Warnings don't block the submission, regardless of their checkbox state. They assume that the user has specified some uncommon settings on purpose and try to ensure the user is aware of them.

To see an example of a Warning, right-click the line reading "The Render Output Path is NOT DEFINED!" in the Sanity Checker. This will open the Render Setup dialog. Enter the file name "test.avi" as the Render Output and click anywhere in the area between the list views to update the dialog. You will see a new Warning message saying "The Render Output is set to a MOVIE format."

Fixing Fatal Errors

As mentioned above, FATAL errors must be fixed before submitting a job to Deadline. In this case, let's create a Teapot in the scene, then click anywhere outside the list views to force an update.

Fixing Non-Fatal Errors

Let's fix the Render Time Output error - right-clicking the third error from the list will execute the repair function associated with it. In this particular case, the Render Setup dialog will be opened and the Render Time Output will be set to the Current Segment. The Sanity Check will be performed again and the error related to the single frame rendering will disappear since it was successfully fixed.

Note that the log at the bottom reports the result of the fix in green.

Ignoring Non-Fatal Errors

Let's assume that we are ok with rendering a non-camera viewport in an untitled scene. If we would uncheck the Can Be Fixed errors, the color indicator will turn green and pressing the SUBMIT button would be allowed even if the Sanity Check option is checked.

Remember that the Warnings are not counted towards the red/green status, they are just a reminder about settings that could be potentially wrong, but don't interfere with the submission process.

SANITY CHECKER IMPLEMENTATION OVERVIEW

Just like SMTD, the Sanity Checker was implemented using MAXScript. Its source files are fully editable and available to interested users to study and modify. There are three relevant files, all located in the \submission\3dsmax\ folder of the Repository:

  • SubmitMaxToDeadline_SanityCheck.ms - this file declares the User Interface and the main test function.
  • SubmitMaxToDeadline_SanityCheck_General.ms - this file defines the sanity check functions implemented by Thinkbox Software and shipping with Deadline. This file will be updated when new versions of Deadline are deployed and should not be modified to avoid the loss of changes.
  • SubmitMaxToDeadline_SanityCheck_Private.ms - this file can be used to define custom sanity check functions. It will be installed by Deadline only if it does not exist yet and will never be overwritten by updates. Its initial shipping version contains only some boilerplate code and no functions at all.

These files will be loaded by the Submit To Deadline launcher MacroScript which also loads the SMTD UI and the SMTD Functions and Settings. The Private tests will be added to the General test list at loading time, so when the Sanity Check is launched, both sets of tests will be run despite their source.

The definition of a Sanity Check test consists of an array entry in the form

#(checkFunction, #errortype, "Error Message", FixFunction, checked)

For example, the test for empty scene looks like this:

#(SMTD_SanityCheckFunctions.CheckForEmptyScene, #fail, "The scene does not contain ANY objects!", SMTD_RepairFunctions.cannotFix, true )

  • The first element of the array defines the function to call to perform the test. If the function returns true, the scene has passed the test and the error will not be displayed. If it returns false, the scene failed the test and the error will be displayed.
  • The second element of the array is a name value (prefixed with #) defining the error severity. The supported names are #fail, #fix and #warn.
  • The third element of the array is the text to display in the Sanity Check dialog if the test failed.
  • The forth element of the array contains the function to call when attempting to fix the error automatically by right-clicking the error.
  • The last, firth element of the array defines the initial state of the checkbox used to skip "Can Be Fixed" type errors. By default all test definitions have this set to true.

DEFINING A PRIVATE FRAME RATE TEST

Let's see how a new Private test can be added to the Sanity Checker by editing the Repository file SubmitMaxToDeadline_SanityCheck_Private.ms.

  • Open a Windows Explorer and navigate to the Repository.
  • Go into the folder \submission\3dsmax\
  • Locate the file SubmitMaxToDeadline_SanityCheck_Private.ms and open it in a text editor like Notepad or the MAXScript Editor.
  • Change the function definition in the first struct from fn Blank = ( ) to fn CheckFilmFrameRate = ( FrameRate==24 )
  • Change the function definition in the second struct from fn Blank = ( ) to  
fn FixFilmFrameRate = 
(
FrameRate=24 
SMTD_SanityCheck_errorReportRollout.log_action "Fixed" (color 0 155 0) true "Frame Rate Changed To 24 fps." 
)

  • Save the file to disk.

NOTE: If you are adding more functions to both structs, be sure to add a comma after the closing parenthesis of each function exept for the last function in the struct!

The two new functions perform the checking and the fixing of the Frame Rate.

The first function returns true if the 3ds Max Frame Rate is 24 fps, false if not.

The second function sets the Frame Rate to 24 and adds a log message to the Sanity Checker log window with type "Fixed", green color, true for success, and the message text "Frame Rate Changed To 24 fps."  The true argument tells the system whether the fix was applied successfully or not.

IMPORTANT

In Deadline 5.0 and earlier, restarting SMTD will NOT enable the new Private Test immediately unless you restart 3ds Max or perform some other steps to enforce a full update. This has been fixed for Deadline 5.1 and above as the fixed script can be downloaded from the Thinkbox Support Forums.

Here is some background information about the issue and how to work around it manually:

In order to speed up the startup of SMTD which includes the finding of the Repository path, copying and loading of all libraries and components, the SMTD files are cached in the #userscripts folder of 3ds Max and are forced to load on 3ds Max statup by a startup script. When the Submit To Deadline MacroScript launcher is called again, it checks to see if each file in this cache folder matches the date and size of the respective file in the Repository and only copies and loads the file again if there is a difference.

Unfortunately, when only the Private sanity check file is modified, the other two components of the Sanity Check system are assumed already loaded. The result of this is that the Private definition is not merged with the General definition unless all three script files mentioned earlier on this page are reloaded.

The simplest way to reload them all is to restart 3ds Max, but this is also the slowest way.

A faster way would be to open each of the three Sanity Check scripts in the Repository and modify and resave each of them, for example by inserting a new line to the end of the file. Then, if SMTD is restarted, the files will be detected as modified and all three of them will be reloaded, making the Private defintion visible.

The fastest way to enforce the reloading of all SMTD scripts is to set to false a global flag variable which determines whether the cache files have been loaded correctly:

SMTD_AutoLoadSuccessful=false

After setting the variable, simply restart SMTD and all changes to the Private definitions will be loaded correctly.

Of course, right-clicking the new Frame Rate error will set the Scene Frame Rate to 24 and remove the error from the list. Keep in mind that changing the Frame Rate with existing animation in the scene might not always be a good idea!

CONCLUSION

The Sanity Checker of the Submit Max To Deadline script can be extended by 3rd parties to provide any custom tests that would reduce the number of user errors when submitting jobs to Deadline.

A set of Private tests can be implemented independently from the factory default testing and fixing functions shipping with Deadline, and the creation of new rules requires only basic scripting knowledge.