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.

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.

Scroll further down for important information about exporting audio inside an mp4.


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: controls whether the preview will be made in reverse.

  • Nth: controls the number of frame steps between previewed frames. A value of 1 is regular playback, 2 is every other frame, etc.

  • FPS multiplier: applies a multiplier to the current scene frames per second that allows you to implicitly increase playblast FPS.

Applying an FPS multiplier is an easy way to playblast scenes for slow motion effects without having to change scene frame range settings or adjust any animation keys. For example, if you have animation keyframes from frame 0-10 in a 30fps scene but you want to playblast an image sequence at 300 FPS (allowing you to slow down the footage 10x in an external editing application without the need for frame blending), then you’d simply set the FPS multiplier to 10 and tyPreview would export 10 times as many frames over the specified frame range by exporting frames at subframe intervals (so instead of exporting frame 0, 1, 2, 3…10, it would export frames 0, 0.1, 0.2, 0.3…10). To avoid decimal places in filenames, the effective frame range will be the specified frame range multiplied by the FPS multiplier. So, for example, a sequence of frames 50-75 with an FPS multiplier of 10 would be exported as frames 500-750.

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.

  • 1 light/2 lights/scene lights: controls whether default light(s) 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.


Exporting Audio

tyPreview now has the ability to include audio in its mp4 output. However, due to the fact that I have not found any open-source AAC encoders/muxers with a permissive-enough license for me to include them within tyFlow itself, audio export requires the user to point tyPreview to an installed version of ffmpeg.exe. FFmpeg is a free media transcoding/multiplexing program that can be used to pack and encode media together into a single mp4 file. Since ffmpeg’s license does not allow it to be bundled inside commercial, closed-source software, the user must install it manually in order for tyPreview to be able to use it to encode audio. Luckily, the install process is extremely simple: simply visit ffmpeg.org and download the ffmpeg executable (not the source code) for Windows. Once ffmpeg.exe is located on your drive, use the […] menu in the tyPreview window to tell tyPreview where ffmpeg.exe is located (under the “Audio” submenu of the […] button next to the mp4 output path). Once the location of ffmpeg.exe is specified, tyPreview will do the rest. The location only needs to be specified once, and it will be remembered the next time you open 3ds Max.


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:
  • frameRange_nth: integer

  • 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 = one_default; 1 = scene; 2 = two_default)

  • 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