Krakatoa Particle Data Viewer

Available in Krakatoa v1.6.0 and higher

Overview

  • The Krakatoa Particle Data Viewer (PDV) is a scripted utility based on the KrakatoaParticleIStream MAXScript Value which exposes the render-time data of Krakatoa PRT Loader objects, as well as Particle Flow and Thinking Particles systems.
  • The PDV lists all data from a user-defined range of particles and allows the custom filtering of the data using various methods.
  • The data is taken from the top of the object’s stack and represents the world state of the particles before being rendered, including all modifiers, KCMs, node transforms, Space Warps and Materials.
../../../_images/krakatoa152_particledataviewer_ui.png

User Interface

  • The PDV is implemented as a modeless floating dialog.
  • Any number of PDV instances can be opened in the same session and can display data of the same or different objects independently.
  • Each PDV instance will display the data from the frame it was opened or updated on, thus it is possible to compare values from the same object on two or more different frames side by side.
  • The PDV can be opened using one of the following access points:
    • Select “Launch the Particle Data Viewer utility” menu item from the Krakatoa menu in the 3ds Max Main Menu.
    • Press the “PD Viewer” button at the bottom of the Main Controls rollout of the Krakatoa GUI.
    • Click or right-click the Krakatoa Explorers button in the bottom panel of the Extended Rendered Frame Window (VFB) and select “Open [Krakatoa Particle Data Viewer] Dialog…”
    • Customize a toolbar, QuadMenu or keyboard shortcut by using the “Krakatoa Particle Data Viewer” MacroScript found in the Krakatoa category of the Customize User Interface dialog.
  • The PDV UI containing the following controls:

PRT Object drop-down list

  • This drop-down list contains the names of all supported particle sources the viewer can be used with.
  • Select an object from the list to display its particle data.

First, Count and Nth spinners

  • The three spinners can be used to define the range of particles to display (since filling a ListView with more than 100K records can take a really long time).
    • The First spinner defines the first particle to be displayed
    • The Count spinner defines the number of particles to display after the first particle
    • The Nth spinner defines the step to use when reading particles - for example Nth=3 will show every 3rd particle, skipping two particles in the process.
    • The Nth spinner is used within the defined interval, thus if First is 1000, the Count is 100 and Nth is 4, 25 particles will be displayed starting with 1000 and ending with 1096.

Selected checkbutton

  • This option is unchecked by default.
  • If checked, only particles that provide a Selection channel and have a Selection channel value greater than zero will be displayed.
  • This can be used for custom filtering of the display using arbitrary Krakatoa Channels Modifiers on top of the modifier stack of the object being explored, setting the Selection channel to 0 or 1 based on some boolean test.

Filter checkbutton and button

  • The Filter checkbutton is unchecked by default.
  • When checked, the custom filter set up in the Define Filter dialog of the PDV will be applied to the particles to limit the display only to those matching the defined rules.
  • Pressing the Filter… button will open the Define Filter dialog.

UPDATE Mode List and Button

  • The Update button can be used to refresh the Particle Data Viewer’s display.
  • The drop-down list in front of it can be used to switch the Update Mode between “Manual”, “Auto” and “Stats”.
    • In Auto mode, any changes to the First, Count, Nth, Selected and Filter controls will cause an automatic update of the display.
    • The button can also be used in Auto mode for example if the data was changed due to scene changes (object moved or modifier, new KCM added and so on).
    • In Manual mode, the button has to be pressed for any change to be reflected by the viewer’s lists, including changes to the First, Count, Nth, Selected and Filter controls as well as scene changes.
    • In Stats mode, the top list will not be updated, only the statistics in the bottom list will be populated, resulting in a much faster turnaround. This mode can be useful when you are interested in the overall distribution of the particles and not in the individual particle data.

Progress bar

  • The red progress bar will show the loading process.

Particle Data ListView

  • The ListView displays the actual particle data as one row per particle, one column per channel.
    • The first column shows the index of the particle inside the file.
  • The columns can be resized and will preserve their size between sessions based on the channel name - in other words, if you change the width of the 5th column which happens to contain the channel “Color”, the width will be applied to the column containing color in the future even if it is not in the 5th column anymore.

Status field

  • This text field shows the number of particles displayed, the total number of particles (if known) and information about any filters applied.

Summary Info ListView (Stats)

  • This control displays summary info about the channels currently displayed.
    • Each row represents a component of a channel or a whole channel.
    • The columns show the Channel Name, Type and Arity, Value Component (1,2,3 of X,Y,Z or R,G,B) and the Minumum, Maximum and Average of the displayed values.
    • NOTE: Other than the Debugger of the Krakatoa Magma Modifier which reads the complete stream before displaying data, the Min/Max values of the PDV are collected only from the displayed particles - changing the number or range of particles to be displayed will affect the results in the Minimum, Maximum and Average columns!
  • The columns can be resized and will remember their last width between sessions.

Define Filter Dialog

  • The Define Filter Dialog is a floating modeless dialog (it does not block the Krakatoa Particle Data Viewer or 3ds Max) and can be opened by pressing the “Filter…” button in the PDV floater.
  • If the Filter checkbox in the PDV dialog is checked, any changes to the Define Filter settings will be applied to the displayed data automatically.
  • The Define Filter dialog lets you create one or more rules which can be applied to particle data from specific channels.

Load Filter drop-down list

  • The large drop-down list in the upper left corner of the dialog can be used to load a pre-saved filter from disk.
    • The filter definitions are stored in a sub-folder of the Krakatoa local settings folder which is shared between all installations of 3ds Max for the current user.

Save Filter… button

  • The Save Filter button can be used to open the Save File dialog and store the currently defined filter to disk.
    • While the Save File dialog can be used to save in any folder, only filters saved in the default location will appear on the Load Filter drop-down list.

Channel drop-down list

  • The Channel drop-down list is the first of four controls used to define a new filter.
  • It specifies the Channel name to be used as the input for the current Rule.
  • It will show only the channel names currently available in the PDV view.
  • If the Filter is currently empty, setting this list and then pressing the Add New Rule button will create the new rule with the selected channel as data source.
  • If the Filter has rules and a rule is selected, changing the selection of the drop-down list will update the currently selected Rule.

Value/Component drop-down list

  • The second drop-down list used in the definition of a Rule controls what part of the Channel’s data will be used in the comparison.
  • The available options are:
    • Value or Magnitude
      • If the channel has Arity of 1 (Float or Integer value), the Value will be used as is.
      • If the channel is of Arity above 1, the Magnitude (Length) of the value will be used for numeric comparison (Is Greater Than, Is Less Than etc.)
      • If the comparison mode is Is Equal To, Is Not Equal To, Contains, Does Not Contain, Starts With or Ends With, the whole value will be taken as string and compared using Pattern Matching regardless of Arity.
    • Component 1
      • This causes the first component of a value with Arity 2, 3 or 4 to be used in the comparison.
      • This is typically the X axis or Red component of float[3] values.
    • Component 2
      • This causes the second component of a value with Arity 2, 3 or 4 to be used in the comparison.
      • This is typically the Y axis or Green component of float[3] values.
    • Component 3
      • This causes the third component of a value with Arity 3 or 4 to be used in the comparison.
      • This is typically the Z axis or Blue component of float[3] values.
    • Component 4
      • This causes the fourth component of a value with Arity 4 to be used in the comparison.
      • This is typically the W component of float[4] Quaternion values.

Comparison Rule drop-down list

  • The third drop-down list of the Rule definition controls how the value defined by the previous two lists will be compared to the value entered in the Value text field.
  • The available options are:
    • Is Greater Than - performs a numeric comparison between the selected channel’s value or its magnitude (if Arity>1) and the Value from the text field.
    • Is Less Than - performs a numeric comparison between the selected channel’s value or its magnitude (if Arity>1) and the Value from the text field.
    • Is Greater Or Equal To - performs a numeric comparison between the selected channel’s value or its magnitude (if Arity>1) and the Value from the text field.
    • Is Equal To - performs a string comparison between the selected channel value taken as string and the Value from the text field taken as string.
    • Is Not Equal To - performs a string comparison between the selected channel value taken as string and the Value from the text field taken as string.
    • Contains - performs a patten matching of the selected channel value taken as string using the pattern *Value*
    • Starts With - performs a patten matching of the selected channel value taken as string using the pattern Value*
    • Ends With - performs a patten matching of the selected channel value taken as string using the pattern *Value
    • Does Not Contain - performs a patten matching of the selected channel value taken as string using the pattern *Value* and takes the inverse result (NOT).

Value text field

  • The last component of the Rule definition is a text field where the user can enter the value to compare to.
  • The field will be evaluated by MAXScript, thus it is possible to type any valid MAXScript expression in it.
    • For example, entering 1.23 will result in the floating point value 1.23, but entering pi will result in the value 3.14159.
    • Entering $Box01.pos.x will evaluate to the X position of the scene object Box01 (if it exists).
    • If the entered value is not a valid MAXScript expression, the value of 0 will be used instead. In the above example, if Box01 does not exist, the expression will evaluate to 0.
  • The expression will be evaluated only on Enter (or on leaving the text field).

Add New Rule button

  • Pressing this button will add a new rule using the current settings of the above four controls.
  • The rule will be added to the end of the filter list.
  • The new rule will be active by default (+ sign in front)

Clone Selected Rule button

  • Pressing this button will duplicate the currently highlighted rule.
  • The new rule will be inserted right after the selected one.
  • Alternatively, you can select an existing rule and press the Add New Rule button - this will insert the new rule at the end of the list.

Remove Selected Rule button

  • Pressing this button will delete the highlighted rule from the Filter list.
  • NOTE that there is no undo for this operation!

Start New Filter… button

  • Pressing this button will open a prompt asking for confirmation.
  • Confirming with Yes will clear the current Filter list.
  • Answering with No will cancel the operation and keep the current Filter definition.

Filter list

  • The largest area of the Define Filter dialog, this list contains the currently defined Rules.
  • Selecting a Rule from the list will automatically update the four Rule definition controls above.
  • Double-clicking a Rule will toggle its active state between ON (+) and OFF (–).
    • OFF Rules will be ignored and not applied.
    • This is useful for temporarily disabling Rules without completely removing them from the Filter.

Comparison Mode radio buttons

  • Match All Rules - when selected (default), for a particle to be displayed, it has to match all active Rules in the Filter.
  • Match Any Rule - when selected, for a particle to be displayed, it has to match at least one of the active Rules.
  • Match No Rules - when selected, for a particle to be displayed, it has to fail the test against all active Rules (the inverse of Match All Rules)

Example:

../../../_images/krakatoa152_particledataviewer_definefilter.png
  • In the above example, the filter is set to only show particles whose X component is greater than 0 AND their ID channel is greater than 80.
  • The filter is set to logical AND (Match All Rules), but the first rule was double-clicked and thus turned off (denoted by –), so only the second rule will be applied (denoted by +).

Particle Sorting

  • Starting with Krakatoa 1.6.1, the content of the Particle Data Viewer can be sorted by any column.
  • To sort by a column, left-click the Column header. The letter [A] will appear next to the Channel Name meaning Ascending order. Clicking again will change the letter to [D] for Descending. Repeating the click will toggle between A and D modes.
  • To return to default sorting, click the Index column’s header.
  • The sorting of Vectors can be performed by Magnitude, by any of the 3 components (e.g sorting by Z component), or by string comparison. These options are exposed in the View menu item.

Selected Particles Viewport Display

  • The Particle Data Viewer will mark the particles highlighted in the Particle Data View with red circles and will include the index number next to them.
  • In the following example, 4 particles were highlighted in the Particle Data Viewer
../../../_images/krakatoa16_particledataviewer_selectedineditor.png
  • In the viewport, the 4 particles were circled in red and their indices are shown in yellow.
../../../_images/krakatoa16_particledataviewer_selectedinviewport.png
  • Note that since the PDV displays the content of the render-time particle stream and not the viewport stream, the display could be off if the viewport is using different settings than the renderer.
    • In the above screenshot, both the viewport and the renderer were using the same Spacing of 5.0 units.
    • In the screenshot below, the viewport was set to Spacing of 7.0, thus producing a completely different set of particles, but the red circles still show where the render-time particles would be:
../../../_images/krakatoa16_particledataviewer_selectedinviewport2.png
  • In Krakatoa 1.6.1 and higher, holding SHIFT and clicking a Column in the PDV will toggle the display of the particle data in the viewport - the name of the channel and its value will be drawn in yellow next to the particle.
  • Any number of channels can be displayed at the same time next to the particle.

SEE ALSO

  • KrakatoaParticleIStream MAXScript Value