========================== AIMS-specific file formats ========================== .. _gis_format: ``.ima`` GIS volume format ========================== .. todo:: to be continued... .. _mesh_format: ``.mesh`` surfacic mesh format ============================== 1. Introduction --------------- This document describes the main format used by *BrainVISA* and *Anatomist* to represent surfaces (composed of polygons such as triangles) and segment set. The aimed audience is programmers who wish to generate surfaces and/or segments with their own software and use them with *BrainVISA / Anatomist*. 2. Syntax --------- The format description is written with the following elements. A *field* (written in bold) represent an element that can be split in other elements. All fields are described in :ref:`section 4 `. In *ascii* mode fields can be separated by one or more **space**. Characters strings are represented in verbatim between quotes. For example, ``’string’`` represent six *ascii* characters (each one coded on one byte). 3. Format description --------------------- A mesh file contains the following fields: #. **mode** #. **textureType** #. **polygonDimension** #. **numberOfTimeSteps** #. **timeSteps** .. _mesh_fields_descr: 4. Fields description --------------------- **mode**: The format can be written either as an ascii text file or as a binary file. The **mode** is used to identify the representation it can have three values: * ``’ascii’``: the file is in text format. * ``’binarABCD’``: the file is in binary format and uses big-endian byte order for numbers (such as Motorola or Sun processors for example). * ``’binarDCBA’``: the file is in binary format and uses little-endian byte order for numbers (such as Intel processors for example). **textureType**: The file format was created with the possibility to include a texture. But this is never used since textures are represented in a separate format. In *ascii* mode his field should always contain ``’VOID’`` or, in binary mode, a **U32** containing ``4`` (which is the size of the following string) followed by the four characters ``’VOID’``. **polygonDimension**: This field is a **U32** containing the number of points of each polygon. The following values are supported in Anatomist and Aims: * ``3``: Polygons are composed of three points (they are triangles). This is the recomanded value for surfaces because other values may not be supported by all BrainVISA processing tools. * ``4``: Polygon are composed of four points. This is supported in Anatomist but may not be supported in every BrainVISA processing tools. * ``2``: This value is used to represent segments in a 3D space. Each ”polygon” is composed of two 3D points. **numberOfTimeSteps**: The mesh format can represent several meshes at different time steps. This is a *U32* representing the number of time steps. **timeSteps**: This field contains numberOfTimeSteps times the following structure: * **instant**: a **U32** representing a time instant. * **vectorOf**: contains all the vertices which are used to build polygons. * **vectorOf**: contains the normals of the surface at each vertex. It must have the same size as **vectorOf** or be empty. * **vectorOf**: must be an empty vector (i.e a **U32** containing ``0``). * **vectorOf**: contains the polygons which represent the surface. **vertex**: is 3D a point. * In *ascii* mode it has the following syntax: ``’(’`` **FLOAT** ``’,’`` **FLOAT** ``’,’`` **FLOAT** ``’)’``. * In binary mode it is represented by three **FLOAT**. **normal**: is a normalized vector. * In *ascii* mode it has the following syntax: ``’(’`` **FLOAT** ``’,’`` **FLOAT** ``’,’`` **FLOAT** ``’)’``. * In binary mode it is represented by three **FLOAT**. **polygon**: is a set of **polygonDimension** points. Each point is represented by a **U32** which is an index in **vectorOf**. The first vertex index is *zero*, the second is *one*, etc. * In *ascii* mode it has the following syntax: ``’(’`` **U32** ``’,’`` **U32** ``’,’`` ... ``’,’`` **U32** ``’)’``. * In binary mode it is represented by a series of **polygonDimension** elements of type **U32**. **U32**: A 32 bits wide unsigned integer (between 0 and 4294967295). * In *ascii* mode it is written as a decimal number. * In binary mode it is represented on four bytes with the chosen byte order (see **mode** above). **FLOAT**: A 32 bits wide real number (maximum 3.40282347e+38). * In *ascii* mode it is written as a decimal number. * In binary mode it is represented on four bytes with the chosen byte order (see mode above). **vectorOf**: where **field** is a field type. It represents a fixed length vector of elements of type **field**. It contains the size of the vector (i.e. the number of elements) as a **U32** followed by the elements. **space**: A byte with one of the *ascii* value for a space, a tabulation or a carriage-return. 5. Examples ----------- Here is an example of an ascii mesh file containing a tetrahedron. :: ascii VOID 3 1 0 4 (-0.8,0.8,0) (0.8,8e-1,0) (-1,-1,0) (0,0,1) 4 (-0.8,0.8,0) (0.8,8e-1,0) (-1,-1,0) (0,0,1) 0 4 (0,1,2) (0,3,1) (1,3,2) (2,3,0) Here is an example of an ascii mesh file containing a linear spiral. :: ascii VOID 2 1 0 16 (10, 0, 0) (7.07, 7.07, 0.4) (0, 10, 0.8) (-7.07, 7.07, 1.2) (-10, 0, 1.6) (-7.07, -7.07, 2.0) (0, -10, 2.4) (7.07, -7.07, 2.8) (10, 0, 3.2) (7.07, 7.07, 3.6) (0, 10, 4.0) (-7.07, 7.07, 4.4) (-10, 0, 4.8) (-7.07, -7.07, 5.2) (0, -10, 5.6) (7.07, -7.07, 6.0) 0 0 15 (0,1) (1,2) (2,3) (3,4) (4,5) (5,6) (6,7) (7,8) (8,9) (9,10) (10,11) (11,12) (12,13) (13,14) (14,15) :documents:`Additional example data can be found here `. .. _tex_format: ``.tex`` texture format ======================= 1. Syntax --------- The format description is written with the following elements. A field (written in bold) represent an element that can be split in other elements. All fields are described in :ref:`section 3 `. In *ascii* mode fields can be separated by one or more **space**. Characters strings are represented in verbatim between quotes. For example, ``’string’`` represent six ascii characters (each one coded on one byte). 2. Format description --------------------- A tex file contains the following *fields*: #. **mode** #. **textureType** #. **numberOfTimeSteps** #. **timeSteps** .. _tex_fields_descr: 3. Fields description --------------------- **mode**: The format can be written either as an *ascii* text file or as a binary file. The **mode** is used to identify the representation it can have three values : * ``’ascii’``: the file is in text format. * ``’binarABCD’``: the file is in binary format and uses big-endian byte order for numbers (such as Motorola or Sun processors for example). * ``’binarDCBA’``: the file is in binary format and uses little-endian byte order for numbers (such as Intel processors for example). **textureType**: * In *ascii* mode his field should contain the name of the texture type (``’FLOAT’``, ``’S16’``, ``’U32’``, ``’POINT2DF’``), * In binary mode, a **U32** containing the size of the typename string followed by the string itself (``’FLOAT’`` etc). **numberOfTimeSteps**: The texture format can represent several textures at different time steps. This is a **U32** representing the number of time steps. **timeSteps**: This field contains **numberOfTimeSteps** times the following structure : * **instant**: a **U32** representing a time instant. * **vectorOf**: contains all the texture values, each associated to a mesh vertex (in the same order). **U32**: A 32 bits wide unsigned integer (between 0 and 4294967295). * In *ascii* mode it is written as a decimal number. * In binary mode it is represented on four bytes with the chosen byte order (see mode above). **S16**: A 16 bits wide signed integer (between -32768 and 32767). * In *ascii* mode it is written as a decimal number. In binary mode it is represented on two bytes with the chosen byte order (see mode above). **FLOAT**: A 32 bits wide real number (maximum 3.40282347e+38). * In *ascii* mode it is written as a decimal number. * In binary mode it is represented on four bytes with the chosen byte order (see mode above). **vectorOf**: where **field** is a field type. It represents a fixed length vector of elements of type **field**. It contains the size of the vector (i.e. the number of elements) as a **U32** followed by the elements. **POINT2DF**: A **POINT2DF** is a couple of floating point numbers, ie 2 texture coords for a 2D texture. It is coded as a vector of two 32 bits wide real (**FLOAT**) numbers. 4. Example ---------- Here is an example of an ascii tex file containing a 2D texture of 2 timesteps, for a mesh of 4 vertices. :: ascii POINT2DF 2 0 4 (-0.2,0.8) (0.8,8e-1) (-1,0) (0,0) 1 4 (-0.8,0.7) (0.7,-0.3) (-0.9,0.1) (0.2,0.3) .. _bck_format: ``.bck`` "bucket" (voxels list) format ====================================== 1. Introduction --------------- This document describes the main format used by *BrainVISA* and *Anatomist* to represent a series of 3D voxel coordinates along with corresponding values. For historical reason this format is called *bucket* format. The aimed audience is programmers who wish to read or generate buckets files with their own software. 2. Syntax --------- The format description is written with the following elements. A *field* (written in bold) represent an element that can be splitted in other elements. All fields are described in :ref:`section 4 `. In ascii mode fields can be separated by spaces. Characters strings are represented in verbatim between quotes. For example, ``’string’`` represent six *ascii* characters (each one coded on one byte). 3. Format description --------------------- A bucket file contains the following fields: * **mode** * **textureType** * **voxelSize** * **numberOfTimeSteps** * **timeSteps** .. _bck_fields_descr: 4. Fields description --------------------- **mode**: The format can be written either as an *ascii* text file or as a binary file. The mode is used to identify the representation it can have three values: * ``’ascii’``: the file is in text format. * ``’binarABCD’``: the file is in binary format and uses big-endian byte order for numbers (such as Motorola or Sun processors for example). * ``’binarDCBA’``: the file is in binary format and uses little-endian byte order for numbers (such as Intel processors for example). **dataType**: The file format was created with the possibility to store several data types. However, in a single bucket file, all values must be of the same type. Recognized types are described below. The **dataType** field defines the data type. * In *ascii* mode his field contains ``’-type’`` followed by **spaces** and the data type name (see below). * In binary mode, it is a string containing the data type name. **voxelSize**: Contains x, y, z and t voxel sizes. * In ascii it is ``’-dx’`` **FLOAT** ``’-dy’`` **FLOAT** ``’-dz’`` **FLOAT** ``’-dt’`` **FLOAT**. * In binary, it is four **FLOAT**. **numberOfTimeSteps**: The bucket format can represent several series of coordinate/value at different time steps. **numberOfTimeSteps** contains the number of time steps. * In *ascii* mode, it is ``’-dimt’`` **U32** * In binary mode, it is a **U32** **timeSteps**: This field contains **numberOfTimeSteps** times the following structure: * **instant**: A **U32** representing a time instant. * In *ascii*: ``’-time’`` **U32**. * In binary: a **U32** **numberOfPoints**: Number of *(coordinate, value)* pairs. * In *ascii*: ``’-dim’`` **U32**. * In binary: a **U32** **pointsAndValues**: a series containing **numberOfPoints** times a **coordinate value** pair (**space**-separated in *ascii* mode). **coordinate**: A 3D coordinate. * In *ascii* mode it has the following syntax: ``’(’`` **S32** ``’,’`` **S32** ``’,’`` **S32** ``’)’``. * In binary it is three **S32**. **value**: The content of this field depends on the value of dataType. See below. **U32**: A 32 bits wide unsigned integer (between 0 and 4294967295). * In ascii mode it is written as a decimal number. * In binary mode it is represented on four bytes with the chosen byte order (see **mode** above). **S32**: A 32 bits wide signed integer (between -2147483648 and 2147483647). * In ascii mode it is written as a decimal number. * In binary mode it is represented on four bytes with the chosen byte order (see **mode** above). **FLOAT**: A 32 bits wide real number (maximum 3.40282347e+38). * In *ascii* mode it is written as a decimal number. * In binary mode it is represented on four bytes with the chosen byte order (see **mode** above). **string**: * In *ascii* mode it is a serie of non-space *ascii* bytes * in binary mode it is a **U32** containing the string size followed by the string content (*ascii* bytes series). **vectorOf**: where **field** is a field type. It represents a fixed length vector of elements of type **field**. It contains the size of the vector (i.e. the number of elements) as a **U32** followed by the elements. **spaces**: Valid only in *ascii* mode (in binary, a space can be considered as an empty string). One or more byte with one of the *ascii* value for a space, a tabulation or a carriage-return. 5. Data types ------------- The field **dataType** defines the type of value associated to each **coordinate**. Here is a list of the possible values for **dataType** and the corresponding value structure. * ``VOID`` * ``FLOAT`` * ``DOUBLE`` * ``U32`` * ``S32`` * ``U16`` * ``S16`` * ``POINT2DF`` 6. Examples ----------- Here should be an example of an *ascii* bucket file. .. todo:: To be continued... .. _arg_format: ``.arg`` graph format ===================== .. todo:: To be continued... .. _hie_format: ``.hie`` tree format ==================== .. todo:: To be continued... .. _bundles_format: ``.bundles`` bundles / fibers format ==================================== Definition of curve bundles format (``*.bundles``) used in Brainvisa 1. Introduction --------------- This document describes the main format used by *brainvisa* and *anatomist* to represent named sets of curves. 2. Format description --------------------- The bundle format is composed of two files. One human readable file with the extension ``.bundles`` and one data file with the extension ``.bundlesdata``. The ``*.bundles`` file contains a generic header with the same format as ``*.minf`` files of *brainvisa*. A ``*.bundles`` file contains the following fields : **format:** (required) Format identifier. A format identifier uses the following pattern: ``..``. To date, ``bundles_1.0`` value is required. **space_dimension:** (optional, default = 3) Space dimension. Must be 3 for ``bundles_1.0``. **curves_count:** (required) Number of fibers in data file (required). Must be > 0 for ``bundles_1.0``. **data_file_name:** (optional, default = ``*.bundlesdata``) File where to find the data. Must be ``*.bundlesdata`` for ``bundles_1.0``. A star (``*``) in the file name is replaced by the header file name without its extension. This file contains a series of curves. Each curve is a series of points. Each point is a series of ``space_dimension`` coordinates. In ascii mode: * *coordinate* is a decimal number. * A *point* is ``space_dimension`` space-separated *coordinates*. * A *curve* is a comma separated series of *points*. * There is one and only one *curve* per line. In binary mode: * A *coordinate* is a 8 bytes floating point number (a *double* in C or C++). * A *point* is the concatenation of ``space_dimension`` *coordinates*. * A *curve* is a 4 bytes integer representing the number of points and a series of points.