CSV File Format

  • The Comma-Separated Value file (.CSV) is a pure ASCII text file containing (nomen est omen) values separated by commas.
  • In Krakatoa v2.1.x and higher / Frost 1.3 and higher, in addition to the comma separator, the data in the file to load can be delimited by the following characters:
    • semicolon “;”
    • colon “:”
    • tab “t”
    • space ” “
  • Probably the closest thing to a “standard” for CSV files is the RFC 4180.
  • For a CSV file to also work as a particle file, you have to follow the additional requirements described below.
  • Krakatoa allows the use of CSV as particle data input and output alternative to the PRT file format.

Advantages

  • CSV files are easy to read and edit by humans.
  • CSV files can be written and parsed by any application (3D, 2D or even MS Excel) that can read text files.
    • Thus, it can be used as the Least Common Denominator for particle data exchange between Krakatoa and these applications.

Disadvantages

  • CSV files are much larger than the binary zipped PRT files.
  • Loading ASCII text files is generally slower than loading from PRT files.
  • Krakatoa cannot know the number of particles in a CSV file until it is finished reading the file.
    • To avoid performance degradation, Krakatoa disables features which depend on knowing the count (e.g. the “Load First N Particles” option in PRT Loader) rather than reading the CSV file twice.

Format Variations

  • Each particle is written to the CSV file as a single line of comma-separated values.
  • The following rules apply:
    • When the CSV contains NO headers and 3 float values per line, these are loaded as X,Y and Z position.
    • When the CSV contains NO headers and 6 float values per line, these are loaded as X,Y and Z position and R,G,B color.
    • When the CSV has to contain more information, a Header can be defined in the first line.
    • In Krakatoa v2.1.x and higher: When the CSV contains more information and no Header is specified, the PRT Loader will automatically import all columns beyond the first 3 as “DataN” where N is an integer counter, e.g. “Data1”, “Data2” etc. All colums will be considered of type float32[1] and you can use a Magma modifier to remap these Data channels to any supported named channels like Color, Density etc.

Using Headers

  • The following example shows a typical header definition written from Krakatoa and one particle saved according to these headers:
float32 Position[0], float32 Position[1], float32 Position[2], float16 Velocity[0], float16 Velocity[1], float16 Velocity[2]
9.72161, -63.355, 262.092, 23.2188, -68.25, 291.25
  • The headers can be specified in shorter form containing only the type:
  • If the float32/float16 definition is missing, the type will default to float32.
  • If the [#] part is missing, Krakatoa will attempt to resolve it automatically based on the headers order.
  • See Krakatoa Particle Channels for information on which channels Krakatoa uses.
  • Thus, the following is also a valid header definition:
Position, Position, Position, Velocity, Velocity, Velocity
9.72161, -63.355, 262.092, 23.2188, -68.25, 291.25

NOTES

  • Header names are Case-Sensitive!
  • Position values are in Generic Units in World Space.
  • Velocity values are in Generic Units per Second.
  • Color values’ components are expected to be in the 0.0 to 1.0 range.
  • Empty lines are not supported.

KNOWN ISSUES

  • On non-US systems (e.g. German), the Comma and Dot symbols for Number Display are swapped in the Regional Settings of Windows.
    • This can cause problems reading CSV files into Krakatoa correctly.
    • Please be sure to set the Decimal Delimiter to Dot if you are using a non-US setup.