************ 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. .. code-block:: python 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: .. code-block:: text 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: .. code-block:: text 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: .. code-block:: text 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: .. code-block:: text 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: .. code-block:: text 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: .. code-block:: text 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: .. code-block:: text 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.