tyPreview Utility

The tyPreview utility is a feature-rich replacement for 3ds Max’s built-in animation preview tool.

The tyPreview utility has many features not available in the built-in animation preview tool. Its image processing core is multithreaded, all of its settings are saved locally to each camera/viewport, it has settings for precise output resolution control, pathname symbols, text overlays, a full MAXScript API, and it can export h264-encoded video directly to an mp4 file.

tyPreview does not yet multiplex audio in its output mp4 streams. If you need to preview with audio, you will still have to use 3ds Max’s legacy preview tool.

When 3ds Max loads, tyPreview will automatically register itself to appropriate preview menus within Max. It also registers a macroscript (under category: tyFlow) that can be assigned to a custom menu or keyboard shortcut. The macroscript opens the tyPreview UI. To find tyPreview in the 3ds Max 2020 hotkey editor, simply type “tyPreview” into the action search box.


Camera

  • Camera list: this dropdown controls which camera will be previewed. Any changes made to the controls in the UI will be saved to the camera currently selected in this list. Selecting a different camera in this list will load that camera’s settings into the UI.

All max scene object cameras (legacy camera, physical, etc) are available for preview in this list at all times. However, only currently visible built-in viewports (top, front, back, perspective, etc) are available for preview at a given time. If you wish to preview from a built-in viewport, make sure that viewport is assigned to one of the view panels first.

Frame Range

  • Active time segment: all frames of the active time segment will be previewed.

  • Custom Range: a custom range of frames will be previewed.

  • Frame List: a range of frames parsed from a user-editable textbox will be previewed.

Separate groups of frames with commas, and denote ranges of frames with dashes. Ex: “10, 20, 30-50, 75-120, 125”

  • Reverse frame sequence: controls whether the preview will be made in reverse.

Display Filter

  • Object classes: these checkboxes control which viewport objects and elements will be visible in the preview.

Resolution

  • Percent of render resolution: the preview output resolution will be a percentage of the current render resolution.

  • Custom resolution: the preview output resolution will be an explicity-defined width and height.

  • Fixed aspect ratio: controls whether the custom resolution width/height values will be constrained to a particular aspect ratio.

The 3ds Max SDK does not give low-level access to viewport resolution control, so tyPreview native resolution is limited to the size of a maximized viewport (on a 2K display this is roughly 1650x850 pixels). Any output resolution higher than the size of a maximized viewport will be upscaled using a bilinear filtering algorithm.

Apperance

  • Mode: this dropdown controls the preview rendering mode.

  • Style: this dropdown controls the preview rendering style.

  • Default/scene lights: controls whether a default light or existing scene lights will be used as a light source.

  • Edged faces: when enabled, edged faces will be visible in the preview.

  • Anti-aliasing: when enabled, 8X anti-aliasing will be enabled for the preview.

  • Multi-pass effect: when enabled, applicable multi-pass effects (DOF or motion blur) of legacy cameras will be enabled for the preview.

  • Ambient Occlusion: when enabled (with progressive refinement), ambient occlusion will be computed.

  • Shadows: when enabled, shadows will be visible.

  • Prog. Refinement: when enabled, Nitrous progressive refinement will be enabled for the preview.

  • Iterations: controls the number of progressive refinement iterations to calculate for each frame.

  • Time (seconds): controls the amount of time to progressively refine the viewport each frame.

Use iterations mode for ensuring a certain level of progressive refinement quality is maintained per frame, regardless of how long the frame takes to render. Use time mode when you want to ensure the time taken to progressively refine frames stays under a certain threshold. Quality is not ensured in time mode, and total time is not limited in iterations mode.

  • Alpha channel controls whether the preview will save alpha channel values.

Alpha channel export will only work when exporting image sequences using a format that supports an alpha channel (exr, png, tif).

  • Safe frames: controls whether safe frames will be visible in the preview.

  • Textures: controls whether textures will be visible in the preview.

  • Transparency: controls whether material tranparency will be visible in the preview.

Overlay

  • Frame number: when enabled, the current frame number will be overlayed onto each frame.

  • Camera name: when enabled, the current camera name will be overlayed onto each frame.

  • Scene file path: when enabled, the file’s path will be overlayed onto each frame.

  • Scene file name: when enabled, the file’s name will be overlayed onto each frame.

  • MAXScript string: when enabled, a user-defined MAXScript string will be overlayed onto each frame.

The user-defined MAXScript string must evaluate to a MAXScript String object (ex: “localtime as string”). Multi-line strings are supported.

Output

tyPreview uses multiple threads to process images and save files. While viewport DIB capture is single-threaded, tyPreview’s gamma correction, RGB to YUV converter (mp4) and bilinear upscaling algorithms are multi-threaded. tyPreview also uses multiple threads to write the resulting files to disk. If you notice stuttering while exporting previews at large resolutions, that’s because the multi-threaded file write function has a limiter in place which restricts the number of writer threads that can work together simultaneously. The stuttering is caused by the preview algorithm waiting for the latest batch of writes to complete before updating the time slider (in other words, stuttering is caused by disk writes happening slower than viewport updates). Stuttering is not a sign that your preview is slowing down, but instead that it’s going so fast your disk cannot keep up.

  • $version: controls the version number which will be assigned to ‘$version’ symbols within output path names.

  • Increment version after preview: when enabled, the version number will be incremented by 1 after each successfully completed preview. Canceled/failed previews will not trigger an increment.

  • MP4: when selected, the preview output will be saved to an h264-encoded mp4 file.

No mp4 encoder settings are exposed in the tyPreview UI. The hard-coded mp4 encoder settings are designed to achieve a reasonable bitrate while reducing artifacts in exports.

  • MP4 path: the output path where mp4 files will be saved.

  • Image Sequence: when selected, the preview output will be saved to a sequence of image files.

The available image-sequence filetypes are jpg, png, tif and exr. No image encoder settings are exposed in the tyPreview UI. All hard-coded image encoder settings are set to ensure maximum output quality, and alpha channel output (where applicable).

  • Image sequence path: the output path where images will be saved.

Path values can contain various symbols to denote built-in path variables. Click the “?” button beside each path box to see the list of available symbols. The textbox below the editable path inputs contains the resulting fully-parsed output path.

MAXScript access

  • tyPreviewWindow(): this function loads the tyPreview UI.

The tyPreview utility can also be executed purely through MAXScript, without having to open the UI.

  • tyPreview(): this function executes a tyPreview export, using settings for the currently active viewport.

For tyPreview customization, the tyPreview MAXScript API gives you full control over all tyPreview settings. All of these settings can be called as arguments for the base tyPreview() MAXScript function. For example, instead of “tyPreview()”, you might call “tyPreview frameRange_reverse:true displayFilter_geometry:false appearance_alpha:true”.

The “tyPreviewWindow()” function can also be called with all of the same function arguments available to the “tyPreview()” function. Instead of immediately executing a preview with those arguments, it will adjust controls in the UI to match your inputs.

All of the tyPreview function arguments correspond to settings already described in the documentation above, so while they will be listed below, redundant descriptions for them are not included.

tyPreview function arguments:

  • camera_name: (name of target camera node)
  • camera_node (target camera node)

If camera_node is specified, tyPreview will attempt to preview from that camera. If camera_name is specified, tyPreview will attempt to preview from the camera with that name. If neither is specified, tyPreview will preview from the camera of the current active viewport. Export settings will be taken from whichever camera is ultimately chosen. Those settings can be overridden using the function arguments listed below.

  • frameRange_list: (ex: “10, 20, 30-50, 75-120, 125”)
  • frameRange_reverse:

  • displayFilter_geometry: true|false

  • displayFilter_shapes: true|false

  • displayFilter_lights: true|false

  • displayFilter_cameras: true|false

  • displayFilter_helpers: true|false

  • displayFilter_spacewarps: true|false

  • displayFilter_particles: true|false

  • displayFilter_bones: true|false

  • displayFilter_grid: true|false

  • displayFilter_background: true|false

  • displayFilter_selection: true|false

  • resolution_width: integer

  • resolution_height: integer

  • appearance_mode: integer (0-based index of modes listed in tyPreview UI)

  • appearance_style: integer (0-based index of styles listed in tyPreview UI)

  • appearance_lights: integer (0 = default; 1 = scene)

  • appearance_edgedFaces: true|false

  • appearance_alpha: true|false

  • appearance_antiAliasing: true|false

  • appearance_safeFrames: true|false

  • appearance_multipass: true|false

  • appearance_textures: true|false

  • appearance_transparency: true|false

  • appearance_ao: true|false

  • appearance_shadows: true|false

  • appearance_progressiveRefinement: true|false

  • appearance_progressiveRefinement_type: integer (0 = iterations; 1 = time)

  • appearance_progressiveRefinement_iterations: integer

  • appearance_progressiveRefinement_time: float

  • overlay_frame: true|false

  • overlay_camera: true|false

  • overlay_sceneFile: true|false

  • overlay_scenePath: true|false

  • overlay_maxscript: true|false

  • overlay_maxscript_script: string

  • output_version: integer

  • output_type: integer (0 = mp4; 1 = images)

  • output_framerate: float

output_type:1 must be specified for image sequence export.

  • output_filename: string