Previous Topic (PRT File Format) Up (Particle File Formats) Next Topic (BIN File Format)

CSV File Format

The Comma-Separated Value file (.CSV) is a pure ASCII text file containing (nomen est omen) values separated by commas. 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 PRT file format.

Advantages

  • 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.
  • CSV files are easy to read and edit by humans.

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 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, Headers have to be defined in the first line.

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

For a bigger example, see KrakatoaExampleCSVFile.csv

  • 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.
  • 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.