Krakatoa Birth Channel Generator Utility

Available in Krakatoa v2.5.0 and higher.

Overview

  • The Krakatoa Birth Channel Generator utility is a command-line tool for processing existing PRT file sequences.
  • It reads an input file sequence containing a specified source channel as well as an ID channel for tracking particles over time between multiple frames in a file sequence.
  • It outputs a new file sequence which contains a “Birth” version of the specified source channel in addition to all other channels.
  • The Birth Channel will contain on all frames the value that the particle had in the specified channel when it was born or first “seen” by the tool.
  • Alternatively, the Birth Channel can be set to the value the specified channel had at a custom reference frame, with the data propagating both forward and backward in time.
  • In addition to the command line tool which is universal and could be used by all Krakatoa users regardless of specific integration with a DCC application, Krakatoa MX 2.5.0 also introduces a MAXScript-based UI wrapper to the tool to simplify the picking of the input and output files, reference channels and reference time options.

The Command Line Tool

  • The Command Line tool is implemented by the file BirthChannelGenerator.exe located in the \Utilities sub-folder of the Krakatoa MX installation folder
    • Typically it is under “C:\Program Files\Thinkbox\Krakatoa MX\Utilities\BirthChannelGenerator.exe”
  • The Command Line tool can be executed from a Windows Command Line prompt.
  • Executing the program without any arguments will report an error and suggest using the –help argument to learn more.
  • Executing with the –help flag will print the following information:
      C:\Program Files\Thinkbox\Krakatoa MX\Utilities>BirthChannelGenerator.exe --help

      Allowed Options:
        -h [ --help ]          Produce a help message.
        -i [ --inseq ] arg     The input PRT files.
        -o [ --outseq ] arg    The output PRT files.
        -s [ --sourcech ] arg  The input channel (eg. Position).
        -d [ --destch ] arg    The output channel (eg. BirthPosition).
        --idch arg             The ID channel (eg. ID).
        --frame arg            The start frame.
        --ignore               Ignore per-frame errors and continue to next frame.
        --overwritechannel arg Takes a boolean parameter. Always overwrites an
                               existing birth channel if true, never overwrites if
                               false.
        --overwritefile arg    Takes a boolean parameter. Always overwrites any
                               existing PRT files if true, never overwrites if false.

The Birth Channel User Interface

  • The Birth Channel Generator is wrapped by a scripted User Interface.
  • It can be accessed via the Krakatoa menu, or by customizing a toolbar from the Krakatoa category.
  • All relevant settings will be stored in a configuration file and will be restored when the UI is opened again.
../../../_images/KMX25_BirthChannelGenerator_UI.png

File Sequence group of controls

Input… button and text field

  • The text field shows a single file from the source file sequence to process.
  • A valid file name can be pasted into the text field or entered manually.
  • If the file name is invalid, the field will revert to the last known valid file name stored in an INI file.
  • Pressing the Input… button will open a file dialog to pick a frame from an existing PRT file sequence.
  • The [>>] menu to the right offers only one menu option - EXPLORE Input Folder. When selected, a Windows Explorer will be opened at the location of the input file sequence.

Output… button and text field

  • The text field shows the output file name.
  • The output file name may not be the same as the input file name.
  • A file name can be pasted into the text field or entered manually.
  • The file name or path does not have exist yet - if the path does not exist, an attempt will be made to create it when the generation starts.
  • Pressing the Ouput… button will open a file dialog to define a file name.
  • The [>>] menu to the right offers three menu options
    • EXPLORE Output Folder - When selected, a Windows Explorer will be opened at the location of the output file sequence, if it exists.
    • COPY Output To Input File Sequence - When selected, the Output Path will become the Input Path, and if >Auto-Suggest Output Path is checked, a new Output Path will be generated. This can be useful when performing multiple iterations using different channels.
    • AUTO-GENERATE The Output Sequence Filename - When selected, the Output Filename will be generated once - useful when the >Auto-Suggest Output Path option is unchecked.

Channels group of controls

Input Channel drop-down list

  • The drop-down list will contain all valid channels found in the Input file sequence.
  • It will default to the “Position” channel which is the typical source for generating a Birth channel.
  • Any existing channel can be selected from the list, however some channels like ID will not be listed as they are constant anyway.

Output Channel text field

  • The text field will list the name of the Birth channel to generate.
  • It will be generated automatically from the selection in the Input Channel list, with a “Birth” prefix.
  • However, once it is auto-suggested, it can be changed to any valid channel name, e.g. “MyBirthPlace” or “Position0”.
  • It will also be used by the Auto-Suggest Output Path feature as the name of the sub-folder for the output files.

>Auto-Suggest Output Path checkbutton

  • When checked (default), any change to the Input and Output Channel name or Input file sequence will automatically set the Output filename according to the tool’s rules - the same file name will be used, but one folder deeper, using the BirthChannel’s name as the name of the sub-folder.
  • When unchecked, the user can freely specify the output path and file name.

>Overwrite Existing Channel checkbutton

  • When checked, the option to overwrite an existing Birth channel of the same name will be set to True.
  • This corresponds to the –overwritechannel command line option.
  • This is useful when the Input File Sequence already contains a Birth Channel, but it needs to be generated again using different settings (e.g. source channel or reference time).

Options group of controls

ID Channel drop-down list

A valid ID channel is required by the utility to track particles between frames. By default, the ID channel will be used. If no channel named ID is available, but another integer channel contains the same data (e.g. some PRT files saved by RealFlow might contain the channel “id” in lower case which has the right values, but the wrong name), you can select it from the list. If no ID Channel can be specified, the GENERATE… button will remain disabled.

Base Frame spinner

  • Defines the reference time to generate the Birth Channel from.
  • Default is 0.
  • If a particle was born later than the reference time, its value at its specific birth time will be used.
  • If a particle was born before the reference time, its value at the specified reference time will be propagated backwards and forward in time.

>Do Not Wait For External Utility To Complete checkbutton

  • When checked (default), the Birth Channel Utility command line executable will be run in a background thread without blocking the 3ds Max Main Thread, allowing you to continue working on the scene (e.g. by picking the newly generated files in a PRT Loader)
  • When unchecked, the UI will remain blocked until the external utility exists.

>Ignore Per Frame Errors checkbutton

  • When checked, if a frame throws an error while processing, it will be ignored and the processing wil continue with the next frame.
  • When unchecked, such errors will be considered fatal and the utility will exit.
  • This corresponds to the –ignore command line argument.

GENERATE BIRTH CHANNEL [XXX]… button

  • This button launches the external utility.
  • It will be grayed out if the UI settings are invalid.
  • A Windows Explorer will be opened at the output path, showing the progress of the file conversion.
  • The external utility will process in the background if the >Do Not Wait For External Utility To Complete checkbutton is checked, allowing you to continue working in 3ds Max.