RSS< Twitter< etc

 

PRT File Format

The Thinkbox Particle File Format (.PRT) format is the standard file format used in Krakatoa and Frost. It best supports all the options and capabilities that Krakatoa and Frost have to offer. The file format allows for the use of an arbitrary number of channels, each with a customizable type and name.

The file format is designed so the header is uncompressed while the particle data is compressed. This provides the ability to efficiently write a PRT file without knowing ahead of time how many particles will be written, by seeking back into the header and updating it with the correct particle count once all the particles have been written. When doing this, it is recommended that the value -1 be written to the particle count initially, so that Krakatoa and other programs can detect it as an error condition when loading the file.

Channel names are restricted, and should start with a letter or '_' character, and contain only letters, numbers and '_'. This restriction is imposed to provide for the possibility of implementing scripting support in Krakatoa and other systems where the channel names are directly used in the language to access those channels. Channel names are case sensitive.

For Frost and Krakatoa to work with a PRT file, the file must at minimum contain a Position channel which contains 3 values of a floating point type.

Format Specification

The PRT file format consists of:

  • A header for general file information.
  • A channel definitions section, detailing the channel-wise data included in each particle.
  • A block of binary data for the particles. This is compressed using zlib's deflate method.

All data is in little-endian byte order.

PRT File Header

(56 bytes)

(8 bytes)  Magic number that indicates the PRT file format. The number is defined by the following sequence of ASCII characters: 
           {192, 'P', 'R', 'T', '\r', '\n', 26, '\n'}
(4 bytes)  A 32 bit int indicating the length of the header (Has value 56).
(32 bytes) A human readable signature null-terminated string describing the file, currently "Extensible Particle Format".
(4 bytes)  A 32 bit int indicating version (Has value 1).
(8 bytes)  A 64 bit int indicating particle count.

Reserved Bytes

(4 bytes)

(4 bytes) A 32 bit int, should be set to the value 4.

Channels Definition Section

(Variable Length)

Header (8 bytes)
(4 bytes)  A 32 bit int indicating the number of channels.
(4 bytes)  A 32 bit int indicating the length of one channel definition structure (Has value 44).
Channel definitions (44 bytes each)
(32 bytes) A null-terminated string indicating the channel name.  Must match the regex "[a-zA-Z_][0-9a-zA-Z_]*".
(4 bytes)  A 32 bit int indicating channel data type.  Supported channel data types are indicated in the table below.
(4 bytes)  A 32 bit int indicating channel arity (number of data values that each particle has for this channel).
(4 bytes)  A 32 bit int indicating channel offset, relative to the start of the particle.
Data Type Integer Value
int16 0
int32 1
int64 2
float16 3
float32 4
float64 5
uint16 6
uint32 7
uint64 8
int8 9
uint8 10

Particle Data

(Variable Size)

The particle data is compressed using a zlib z_streamp object, with the basic zlib deflate API. In Frost and Krakatoa, this is implemented with the deflateInit, deflate, and deflateEnd functions for compression, and the inflateInit, inflate, and inflateEnd functions for decompression.

The particles are byte-packed one after another, in the layout specified by the channels definition section.

The float16 data type is the same as the half data type in OpenEXR. The most convenient way to work with them is using the half library component from OpenEXR.

Example

Here's an example PRT file saved from Krakatoa using the vertices from a box. It has 8 particles, and two channels "Position" and "Velocity".

; Magic number: {192, 'P', 'R', 'T', '\r', '\n', 26, '\n'}
000000 c0 50 52 54 0d 0a 1a 0a
; Header length: 56
000008 38 00 00 00
; Identification null-terminated string: "Extensible Particle Format"
00000c 45 78 74 65 6e 73 69 62 6c 65 20 50 61 72 74 69
00001c 63 6c 65 20 46 6f 72 6d 61 74 00 00 00 00 00 00
; Version number: 1
00002c 01 00 00 00
; Particle count: 8
000030 08 00 00 00 00 00 00 00

; Reserved 32-bit value: 4
000038 04 00 00 00

; Number of channels: 2
00003c 02 00 00 00
; Channel definition entry length: 44
000040 2c 00 00 00

; Name of channel 0: "Position"
000044 50 6f 73 69 74 69 6f 6e 00 00 00 00 00 00 00 00
000054 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
; Data type of channel 0: float32
000064 04 00 00 00
; Arity of channel 0: 3
000068 03 00 00 00
; Data offset of channel 0: 0
00006c 00 00 00 00

; Name of channel 1: "Velocity"
000070 56 65 6c 6f 63 69 74 79 00 00 00 00 00 00 00 00
000080 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
; Data type of channel 1: float32
000090 04 00 00 00
; Arity of channel 1: 3
000094 03 00 00 00
; Data offset of channel 1: 12
000098 0c 00 00 00

; Zlib compressed binary particle data
00009c 78 9c e3 d8 3e e3 60 c1 f9 15 07 19 d0 c0 05 ad
0000ac 33 8e d8 c4 39 80 ea 27 78 55 3b 62 53 8f 4d 9c
0000bc 03 6a 7e 63 c1 7f 47 74 f5 d8 c4 61 e6 63 53 8f
0000cc 4d 1c 00 cb 5d 2a 39

The compressed binary particle data will consist of 24 bytes per particle, 12 for the position triplet and 12 for the velocity triplet:

[float32][float32][float32][float32][float32][float32][float32][float32][float32][float32][float32][float32]...
|_________________________||_________________________||_________________________||_________________________|
         position                    velocity                  position                    velocity
|____________________________________________________||____________________________________________________|
                      particle 1                                            particle 2

As mentioned above, it is recommended that when the particle count isn't known ahead of time, the value -1 be written to the particle count initially. This way, Frost, Krakatoa and other programs can detect it as an error condition of an incomplete file when loading the file if the count value didn't get fixed up to the correct value on completion. Once the per particle information has been packed into the file, the particle count in the header can then be updated to the true value.

 

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.

Frost allows the use of CSV as a particle data input alternative to the PRT file format. The file format allows for the use of an arbitrary number of channels, each with a customizable type and name.

Advantages

  • CSV files can be written and parsed by any application (3D, 2D or even MS Excel) that can read text files.
  • 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.
  • The total particle count is unknown at the beginning of the file loading, which means that the "Load First N" mode is unsupported and no automatic memory pre-allocation can be performed.

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
  • 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, Frost will attempt to resolve it automatically based on the headers order.

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 Frost correctly. Please be sure to set the Decimal Delimiter to Dot if you are using a non-US setup.

 

BIN File Format

The RealFlow Particle BIN file (.BIN) is a binary file format developed by Next Limit and used for data exchange between RealFlow and other 3D applications.

Frost allows the loading of RealFlow version 3, 4  and 5 Particle BIN files.

Format Variations

  • It is important to be aware that RealFlow supports two different file formats with the BIN extension - a Particle BIN file and a Geometry BIN file. Frost supports only the Particle variation of the BIN file format.
  • The BIN file format has gone through many revisions.

Format Specification

The BIN file format specifications are provided by Next Limit in PDF format as part of the RealFlow application (included in the evaluation version). Please download the evaluation version of RealFlow or purchase the full product if you need the specs.

Peculiarities

  • In the RealFlow application, file names are expected to have EXACTLY 5 trailing digits (no more, no less). Anything else will fail to load in RealFlow or its associated I/O plug-ins for 3D application, but will load in Frost without problems.
  • When RealFlow saves particle files, it appends the digits immediately after the emitter name. This can produce files like Circle0100014.bin, which Frost will interpret as at frame 100014 rather than at frame 14.
    • One possible precaution measure to avoid this is adding an underscore after the emitter's name in RealFlow, for example Circle01_ will output Circle01_00014.bin and will cause no problems in Frost.
    • If the BIN files have already been saved without a trailing underscore, you can load the BIN sequence in Frost and use the Offset field to shift the animation by as many frames as needed. In the above example, entering 100000 in the Offset field will play frame 100000 on frame 0, causing the file Circle0100014.bin to be loaded correctly on frame 14.