PRT Loader (File Particle Source)

Introduction

The Krakatoa renderer supports several particle file formats for caching particles to disk and reloading them in the viewports and at render time for direct frame access without the need to pre-roll a simulation each time.

The PRT Loader is the implementation-specific object which connects the file sequence with the renderer and allows the transformation, retiming etc. of the cached particles.

The Krakatoa File Particle Source class implements the PRT Loader object in the Krakatoa for CINEMA 4D plugin. It is currently in a preliminary form which should be enhanced gradually to provide all features already available in other Krakatoa implementations like in 3ds Max and Maya.

Creation

To create a new PRT Loader, select the Menu > Plugins > Krakatoa > Krakatoa PRT Loader item.

User Interface

Basic Tab

The Basic tab implements the regular CINEMA 4D object controls and does not contain any Krakatoa-specific settings.

Coord. Tab

The Coord. tab implements the regular CINEMA 4D Transformation controls which apply to the Krakatoa particles loaded by the PRT Loader, including Translation, Scale and Rotation.

• In order to load a particle sequence exactly as it was saved, the PRT Loader should be aligned to the World Origin.
• If the particles are in a different coordinate system (e.g. PRT saved from Krakatoa MX, MY and Stoke MX etc.), the conversion of the coordinates will be performed automatically as long as the file is saved in the PRT 1.1 format with Metadata.
• If the PRT file is saved with RealFlow, or with an older version of Krakatoa MX, Krakatoa MY in 1.0 PRT file format, an additional rotation and/or scaling might be required to reorient the coordinate system.
• If the scene scale is different, and the PRT file is in 1.1 file format with Metadata, it will rescale automatically.
• If the PRT file is in 1.0 format, an additional Scale factor might be necessary.
• The PRT 1.1 file format also includes hints for the function of each channel, allowing the correct transformations of Position, Velocity, Normal and other channels. In the case of the PRT 1.0 file format, the information is not provided by the file itself and will be applied to some hard-coded channels like Positiom, Velocity, Normal and Tangent.
• For more information, see the PRT 1.1 File Format Specification.

Setup Tab

The Setup tab contains the standard Krakatoa Particle Source controls available in all Krakatoa objects.

Particle File Tab

File Path (prt, bin, csv) filename picker

• Defines the file or file sequence name to be loaded.
• When loading a file sequence, ANY of its frames can be selected as a representative file - the frame number will be replaced or added as needed.

Sequence checkbox

• When checked (default), the file name will be loaded as a file sequence, replacing the frame number with the current time automatically.
• When unchecked, the exact file name picked in the above control will be loaded on every frame without modifications.

Load Additional Partitions checkbox

• Unchecked by default.
• When checked, if the file name specified contains a Partitions token ( _partXXofYY_ ), one or more additional sequences from that Partition set can be loaded to increase the particle count.

Partitions To Load spinner

• Default is 1.
• When set to a higher value and the Load Additional Partitions checkbox is checked, multiple partitions will be loaded (if available).

Partitions Found value

• This control is for display purposes only.
• It will display the number of Partitions defined by the second part of the token (ofYY).
• Note that the value does NOT represent the actually existing partitions on disk - they might be still saving, sitting queued on Deadline, or might never be created.
• This means that you can set the expected number of partitions based on the file name token before the final partitions have finished saving.

Keep Velocity Channel checkbox

• When checked (default), a single file (Sequence unchecked) will render on each frame with correct Velocity channel and will produce Motion Blur.
• When unchecked, a single file will render with zero velocity (because technically it is not moving over time).

Interpolate Sub-Frames checkbox

• When unchecked (default), the closest frame will be loaded and the particle Positions will be extrapolated along the Velocity channel when using Playback Graph to retime the sequence.
• When checked, the closest two frames will be loaded and the particle Positions will be interpolated using cubic interpolation based on the two frames’ Positions and Velocities to produce smooth curved motion.

Enable Playback Graph checkbox and Playback Graph spinner

• When unchecked (default), the frame sequence will be advanced according to the scene time.
• When checked, the value of the Playback Graph spinner can be keyframed to provide the current time per frame, allowing for ramping up and down the speed, playing backwards and so on.
• Note that currently only Positions and Velocities will be interpilated between frames - other channels like Color or Density will not be interpolated and could produce stepping effects.

Frame Offset spinner

• Defaults to 0.
• When set to a Positive value, the frame sequence’s time will be shifted to the left (interpretted as “what frame will play on frame 0?”. In other words, the Offset is added to the frame number,
• When set to a Negative value, the frame sequence will be shifted forward (later in time).
• This value will also influence a Playback Graph curve, allowing the shifting of the already retimed sequence.

Use Custom Range

• Unchecked by default.
• When checked, the Range Start and End values and Modes will be respected, loading only a sub-set of existing frames.

Range Start value

• Defines the first frame to be loaded.

Range End value

• Defines the last frame to be loaded.

Range Start Mode drop-down list

• When Use Custom Range is checked, controls the behavior on frames before the Start frame.
• When set to Hold First (default), the frame specified by the Range Start value will be displayed on all frames before it.
• When set to Blank, no particles will be loaded on frames before the Range Start frame.

Range End Mode drop-down list

• When Use Custom Range is checked, controls the behavior on frames after the End frame.
• When set to Hold Last (default), the frame specified by the Range End value will be displayed on all frames after it.
• When set to Blank, no particles will be loaded on frames after the Range Start frame.

Available Channels list

• Displays a list of all channels found in the current PRT frame.
• It is intended for exploring the content of PRT files.
• You can copy channel names to paste in relevant locations in the UI.

Display Tab

Display Load Mode drop-down list

• Controls the order of loading if less than 100% of the particles have been requested.
• Possible values are
  • Use Render Settings - will load according to the settings in the Render tab. This way changing the render settings will always affect both the viewport and the renderer. This is very useful when animating the render percentage in order to get the correct preview in the viewports.
  • First N Particles - starts loading from the beginning of the file and stops when the Percentage Limit has been reached, or the Particle Limit count has been reached. This can only be applied to .PRT and .BIN files, .CSV files always load in Every Nth Particle mode due to lack of total particle count in the header.
  • Every Nth Particle - loads the requested percentage of particles by reading through all files and skipping undesired particles. This mode is much slower because the complete ZLib stream of a PRT file has to be decompressed. If the particle count is changing due to particle birth and death, the actual particles displayed could change between frames, resulting in flickering - see the next mode for a solution.
  • Every Nth Particle By ID - Same as Every Nth Particle, but uses the ID channel to always display the same particles between frames. If no valid ID channel can be found, it will function exactly like Every Nth Particle.

Percent Of Render Count value

• Defines the percentage of renderable particles to be loaded and displayed in the viewport.
• If the Render Percentage specified in the Render tab is less then 100%, the Display Percentage will be a fraction of it. If the Render Percentage is keyframed to animate the count up or down, and the Display Percentage is not animated, the viewport display will still be animated. In other words, the display particles are always a fraction of the render particles.
• The default is 100, allowing the PRT Loader to attempt to load all renderable particles regardless of the Display Load Mode, unless the Particle Limit is enabled and reached (see below).

Enable Particle Limit checkbox

• When checked (default), the viewport particle count will be limited to the specified number of particles times 1000.
• This is to avoid the accidental loading of hundreds of millions of particles in the viewport and the related performance hit / potential lockup of the host application.
• When unchecked, the viewport will display all requested particles, even if the count is excessive. Use at your own risk.

Particle Limit x1000 value

• When the Enable Particle Limit checkbox is checked, this value defines the total number of particles this PRT Loader may display in the viewport.
• The default value is 1000, resulting in a limit of one million particles.

The following Color Gradient controls were available in the initial release v2.3.1. In v2.3.2 and higher, a more general Channel Gradient Operator Tag provides the same functionality for both PRT Loaders and all other Source objects. Existing scenes with PRT Loaders using a custom Gradient will be converted to a Channel Gradient Tag automatically when loading into a newer version of Krakatoa C4D.

Color Gradient

• Defines the color gradient to map to the specified particle data channel if Color Mode is not set to None.
• The default gradient is Blue - Red.

Color Gradient Source drop-down list

• Defines the particle data channel to map to a custom gradient for viewport display purposes.
• The default value is None, producing no viewport gradient.
• When a Scalar channel is specified, it will be used As Is.
• When a Vector channel is specified, the Gradient Input From control will define how it will be used.
• The value can be normalized between 0 and the Maximum value found in all particles, or left As Is and then Scaled using the Scale Gradient Input value.
• When normalizing, if the Maximum value changes between frames, the gradient will also adapt.
• It is meant mainly for quick data visualization to get a feeling of the particle data values in the file.

Custom Source Channel text field

• When the Color Gradient Source list is set to , this field provides the custom channel to use.
• Default is Color, this allowing the remapping of an existing Color to a new Color Gradient.
• Any existing channel can be entered manually - consult the Available Channels list in the Particle File tab to see which channels exist in the current file.

Gradient Input From drop-down list

• Defines the mapping from a Vector Source Channel to the Float value controlling the Gradient color to be used.
• Possible values are:
  • Magnitude Squared (default) - uses the length of the Vector to the power of two.
  • Magnitude - uses the length of the vector.
  • X - uses the first component of the vector.
  • Y - uses the second component of the vector.
  • Z - uses the third component of the vector.

Normalize Gradient Input checkbox

• When checked (default), the input value will be normalized in the range from 0.0 to 1.0 based on the largest value found in all particles.
• When unchecked, the input value will remain As Is.

Scale Gradient Input value

• This value becomes available when the Normalize Gradient Input checkbox is unchecked.
• It can be used to scale the Input value up or down and thus perform custom normalization.
• Default is 1 (no scale).

Offset Gradient Input value

• This value becomes available when the Normalize Gradient Input checkbox is unchecked.
• It can be used to offset the Input value .
• Default is 0 (no offset).

Use Display Color In Render checkbox

• When checked, the viewport gradient (if any) will be set as the render-time particle color. It could still be overwritten by the local overrides under the Setup tab, by Channel tags, Texture Tags, or Global Overrides.
• When unchecked (default), the gradient will only be displayed in the viewports.

Viewport Display Mode drop-down list

• Controls the display of the particles in the viewport.
• Possible values are:
  • Display As Small Dots - draws particles as pixel-sized dots.
  • Display As Large Dots - draws particles as 4x4 pixels squares.
  • Display Velocities - draws particles as lines with direction and lenght based on the Velocity channel (if available). If no Velocity can be found or if the Magnitude (length) of the Velocity is 0, the particle will not be displayed.
  • Display Normals - draws particles as lines according to the Normal channel (if available). If no Normal channel can be found, the particles will not be displayed.
  • Display Tangents - draws particles as lines according to the Tangent channel (if available). If no Tangent channel can be found, the particles will not be displayed.

Render Tab

Render Load Mode drop-down list

• Controls the particle loading mode at render time when the Percent Of Disk Count is less than 100.
• Possible values are:
  • First N Particles - calculates the percentage of the total count of all particles scheduled to be loaded by the PRT Loader (including Partitions), and starts loading from the beginning of the first Partition until the calculated maximum count is reached (unless the Enable Render Particle Limit is enabled and that limit is reached first). This method is faster than the other two because the data is read sequentially and unneeded data is never decompressed, but it would generally show only the beginning of the stream which might not represent the full shape of the particle cloud. This mode does not work with CSV files because the final count is not known in advance - a CSV file is always read in Every Nth mode.
  • Every Nth Particle - calculates a step based on the percentage value and reads every Nth particle based on that step, skipping all other particles. This method produces a a better representation of the full shape of the particle cloud, but is slower than First N Particles because it decompresses and then discards a lot of data. Also, if the particle count is changing between frames due to birth and death, the actual particles being shown could change between frames, producing some flickering.
  • Every Nth Particle By ID - same as Every Nth Particle, but the actual particles shown are determined using their ID, ensuring that the same particles are displayed on every frame as the particle count changes. If there is no valid ID channel, this mode behaves like the Every Nth Particle mode.

Percent Of Disk Count spinner and slider

• This value defines the percentage of particles to be loaded from disk.
• This value can be animated over time to reveal more or less particles.
• Note that the Display Percentage found in the Display tab is relative to this value - changing or animating this value will also change the percentage in the viewport!

Enable Render Particle Limit checkbox

• When unchecked (default), all particles requested for loading according to the Percent Of Disk Count value will be loaded and rendered.
• When checked, the loading will stop if the threshold specified by the following control is reached.

Particle Limit x1000 spinner and slider

• Defines the render time particle load limit used when Enable Render Particle Limit checkbox is checked.
• The value represents thousands of particles.
• The default is 1,000 which represents 1,000,000 (one million) particles.