File Formats

This section describes some of the output file formats that MCell produces.

Molecule Visualization Data

MCell4 provides two output formats for molecule visualization. A textual and binary format. VizMode.ASCII mode selects a readable representation, VizMode.CELLBLENDER mode selects a binary representation that cannot be read using a text editor but is faster to generate and read. The code below shows an example of the VizOutput object with a selection of output file format.

viz_output = m.VizOutput(
    mode = m.VizMode.ASCII, # or m.VizMode.CELLBLENDER or m.VizMode.CELLBLENDER_V1
    output_files_prefix = './viz_data/seed_' + str(SEED).zfill(5) + '/Scene'
)
model.add_viz_output(viz_output)

Text Visualization Data

The text format is composed of lines where each line contains data on one molecule in the following format:

species id x y z nx ny nz

Here, species is the string representation of the molecule species, id is a unique integer identifier of the molecule, x y z represent the 3D location of the molecule in um (micrometers), and nx ny nz is the normal vector. For volume molecules, the normal vector is always 0 0 0. For surface molecules, it corresponds to the normal of the wall where the molecule is located and can be either identical (when the molecule’s orientation is UP), or negated (when the molecule’s orientation is DOWN).

Example:

va@CP 1 0.0601783518 -0.0796582 -0.0180513811 0 0 0
sb@PM 2 0.125 -0.115164035 0.066618027 1 0 0
sc@PM 3 -0.113072306 0.00838499159 0.125 0 0 1

Here we have three molecules, first is a volume molecule with species va@CP (compartment is a part of molecule’s species), then two surface molecules with species sb@PM and sc@PM with their normal vectors set.

Binary Visualization Data V2

The binary format has two versions with v2 being the most recent. All floating point-values (float) are encoded as 32-bit IEEE 745 single-precision floating-point format and the location uses the um (micrometer) unit. Values of indented addresses represent offset from the start of each block. It uses the following structure:

0x0: 2 (4 bytes, uint), constant, used to distinguish binary and ascii formats and to specify binary version
0x4: here start species blocks, each block contains:
     0x0:        name_len (4 byte, unsigned int)
     0x4:        name (sequence of 1-byte characters representing the species name without the terminating zero)
     name_len+4: species_type (1 byte, unsigned char), 0 for volume molecules and 1 for surface molecules
     name_len+5: num_mols (4 bytes, uint)
     name_len+9: molecule ids, repeated num_mols times
         0x0: id (4 bytes, uint)
     name_len+9+num_mols*4: x,y,z triplets, repeated num_mols times
         0x0: x (4 bytes, float)
         0x4: y (4 bytes, float)
         0x8: z (4 bytes, float)
     name_len+2+num_mols*12: if species_type is 1, on this address start nx,ny,nz triplets, otherwise empty (0 bytes)
         0x0: nx (4 bytes, float)
         0x4: ny (4 bytes, float)
         0x8: nz (4 bytes, float)

Example:

00000000  02 00 00 00 05 00 00 00  76 61 40 43 50 00 02 00  |........va@CP...|
00000010  00 00 00 00 00 00 01 00  00 00 37 67 95 3e 09 ac  |..........7g.>..|
00000020  02 3e 5e 01 a3 3e 23 c9  54 bd 37 14 ca be d2 82  |.>^..>#.T.7.....|
00000030  dd 3e 05 00 00 00 73 62  40 50 4d 01 02 00 00 00  |.>....sb@PM.....|
00000040  02 00 00 00 03 00 00 00  00 00 00 3f 3b 32 3c bd  |...........?;2<.|
00000050  ab 05 4b 3e f0 7d 77 3e  00 00 00 3f ea fa b8 bd  |..K>.}w>...?....|
00000060  00 00 80 3f 00 00 00 00  00 00 00 00 00 00 00 80  |...?............|
00000070  00 00 80 3f 00 00 00 00                           |...?....|
00000078

This hex dump shows a binary representation of molecule positions equivalent to ASCII output shown here:

va@CP 0 0.311161 0.145214365 0.32167688 0 0 0
va@CP 1 -0.0498850037 -0.415475712 0.426996041 0 0 0
sb@PM 2 0.5 -0.0639481536 0.170722492 1 0 0
sb@PM 3 0.307013747 0.5 -0.174133457 -0 1 0

In more detail, this is how the data is encoded:

00000000  02 00 00 00     - constant '2' (in little-endian representation)
00000004  05 00 00 00     - length of string 'va@CP' - 5
00000008  76 61 40 43 50  - characters of string 'va@CP'
0000000D  00              - '0' telling that these are volume molecules
0000000E  02 00 00 00     - 2 molecules
00000012  00 00 00 00  01 00 00 00 - IDs of molecules 0, 1
0000001A  7f 50 9f 3e  13 b3 14 3e  d5 b2 a4 3e - xyz position of the first molecule
00000026  38 54 4c bd  3c b9 d4 be  3a 9f da 3e - xyz position of the second molecule
00000032  05              - length of string 'sb@PM'
... (species name, positions, and normals of sb@PM molecules follow)

Binary Visualization Data V1

Version 1 of the binary visualization data uses the following structure:

0x0: 1 (4 bytes, uint), constant, used to distinguish binary and ascii formats
0x4: here start species blocks, each block contains:
     0x0:        name_len (1 byte, unsigned char)
     0x1:        name (sequence of 1-byte characters representing the species name without the terminating zero)
     name_len+1: species_type (1 byte, unsigned char), 0 for volume molecules and 1 for surface molecules
     name_len+2: num_float_positions (4 bytes, uint)
     name_len+6: x,y,z triplets, repeated num_float_positions/3 times
         0x0: x (4 bytes, float)
         0x4: y (4 bytes, float)
         0x8: z (4 bytes, float)
     name_len+2+num_float_positions*4: if species_type is 1, on this address start nx,ny,nz triplets, otherwise empty (0 bytes)
         0x0: nx (4 bytes, float)
         0x4: ny (4 bytes, float)
         0x8: nz (4 bytes, float)

The V1 format was changed to V2 by: 1) the first 4 bytes have value 2, 2) name_len is 4 bytes, and 3) num_float_positions was changed to num_mols having 3x lower value.