Next: 27. Command Line/Batch Mode Up: 8 Additional/Miscellaneous Topics Previous: 8 Additional/Miscellaneous Topics Contents

Subsections

26. File Formats

BioImage Suite uses a number of different file formats for storing different types of data such as images, surfaces, landmark collections, colormaps (palettes), setup files etc. While most users do not need to understand the internals of these formats, this page might be useful to advanced users who are trying to integrate BioImage Suite into their workflow and use it in conjunction with other software.

26.1 Images

BioImage Suite uses as its default file format the Mayo/Analyze 7.5 (and since 2.5 the NIFTI) file format. BioImage Suite supports more or less the complete specification of the NIFTI format. We recommend using this in preference to the Analyze format if possible.

26.1.1 NIFTI Format

This is a modernized version of the Analyze format described below. It has the advantage that the axis orientation is explicitly specified in the image header (unlike the old Analyze standard in which this was implicit).

NIFTI images are either stored as single .nii (or .nii.gz compressed) files or as pairs of (.hdr/.img) files as in the Analyze format.

BioImage Suite supports almost the entire NIFTI standard with the exception of images with non-orthogonal axis. When an image is loaded into BioImage Suite it may be flipped to conform to our internal convention (which is implicitly assumed in the case of Analyze images - more below). For example, if an image comes in left to right, it will be flipped to be right-to-left. The header is also changed to reflect this - the image is still a valid, appropriately labeled NIFTI image!

26.1.2 Analyze 7.5 format

In the case of the Analyze 7.5 format, while there are many other fields in the header, BioImage Suite relies on the following:

Image Dimensions: x,y,z,t
Voxel Dimensions: x,y,z (all assumed to be positive!)
Orientation: 0=axial, 1=coronal, 2=sagittal, 3=polar (ultrasound,local extension)
Data type, unsigned char, short, int ,float

The assumption made in BioImage Suite for the purpose of displaying the images is that the images are stored as follows:

Axial: x=right to left, y=anterior to posterior, z=inferior to superior
Coronal: x=right to left, y=superior to inferior, z=anterior to posterior
Sagittal: x=anterior to posterior, y=inferior to superior, z=left to right (this is for compatibility with the most common local acquisition which results in a non right-handed coordinate system - we suggest that Sagittal images be resliced to Axial before any serious processing)

Note: In particular, we do not use the origin field (SPM extension).

The File Header can be viewed/edited using Header Editor, under the File Menu. Images be reoriented using the Image Processing tools.

BioImage Suite can import a variety of other formats, under File/Image Import. However, these must be converted to Analyze/NIFTI format for use in the batch mode processing tools etc. DICOM import is limited to reading images in which the whole series is placed in its own directory in which there are no other files.

26.2 Surfaces

There a number of surface formats used in BioImage Suite. The most common are:

The b-spline stack surface format.sur - this is format used by the Surface Editor to store a surface as a stack of b-splines one per slice.
The triangulated stack surface format .tstack - this is primarily used by the cardiac tools to store triangulated surfaces and additional point attributes such as normals and curvature. It can also specify whether the surface is made up of a collection of planar contours and define these explicitly which is necessary for some of the cardiac mesh generation tools.
Standard VTK formats, in particular the one defined by its implementation in vtkPolyDataReader and vtkPolyDataWriter. BioImage Suite stores such surfaces using a .vtk extension. The BioImage Suite Surface Control use the .vtk file format is its primary format.

The .sur format

The first part of the file is the header. The first line must be reproduced exactly. The next four lines define the overall extend of the spline stack, each number being proceeded by the ``#'' sign. The second line (139) represents the maximum number of splines which is defined by the number of slices in the underlying image. The third line (#0) can take the values 0 or 1 depending on whether the user has explicitly defined the apex – in the case left ventricular surfaces. The fourth and fifth lines (#64 and #66) represent the actual extent of the surface, in this case there are splines for slices 64 to 66 (i.e. a total of 3 splines). The last line of the header defines the coordinates of the apex in mm (again for cardiac applications only)


#BFPSplineStackApex File , numsplines, has apex,trim_bottom,trim_top
#139
#0
#64
#66
 74.40 93.60 -0.50

After the header, the file stores each spline in order. In this file there are 3 splines. Each spline consists of its own header beginning with the line that starts with ``#FPBSpline''. The next line (#2) is the dimension of the spline, in this case the 2 signifies that this is a planar curve (which is always the case when the spline is part of a surface). The next number (#74.87) represents the z-coordinate of the spline in mm (or the same units as the voxel dimensions of the underlying image). The center of the bottom slice is at z=0.0. The next number is degree of the b-spline, in this case it is cubic (#3). Next there is the flag indicating whether the spline is closed (#1) or open, it is always closed in this format. Finally, the last item lists the number of unique control points which in this case is 6.

Following the divider line ``#--------'', the next line lists the knot positions. BioImage Suite can use non-uniform splines. After that, the positions of the control points are listed. Since this is a closed spline, there are three control points which repeat, to yield the periodic constraint.


#----------------------
#FPBSpline File header= dimension,zlevel,degree,closed,numpoints
#2
#74.879997
#3
#1
#6
#----------------------
#-0.50000 -0.33333 -0.16667 0.00000 0.16667 0.33333 0.50000 0.66667 0.83333 1.00000 1.16667 1.33333 1.50000 
 86.86 68.37 
 95.78 93.25 
 87.11 119.31 
 64.55 124.11 
 53.84 96.50 
 58.25 72.18 
 86.86 68.37 
 95.78 93.25 
 87.11 119.31

Following the first spline, there are the rest of the splines. Two more are given here to complete this file.


#FPBSpline File header= dimension,zlevel,degree,closed,numpoints
#2
#76.049995
#3
#1
#12
#----------------------
#-0.44684 -0.29066 -0.13710 0.00000 0.04604 0.08276 0.16831 0.26755 0.33929 0.36480 0.37926 0.44892
#0.55316 0.70934 0.86290 1.00000 1.04604 1.08276 1.16831 
 89.49 78.72 
 95.52 91.12 
 92.51 100.27 
 85.26 102.16 
 78.19 93.16 
 68.64 93.45 
 61.40 100.72 
 57.08 101.01 
 54.08 99.36 
 55.15 90.30 
 57.36 77.48 
 73.49 64.66 
 89.49 78.72 
 95.52 91.12 
 92.51 100.27

Note: For those who are looking at the code, this file format can be read/saved using the vtkpxSplineStackSource class in the Legacy directory.

The .tstack format

The first part of the file is again the header, with the usual caveat that the first line must be reproduced exactly. The next few lines list, in order, the number of planar contours in the stack (11 in this case), the number of points (1221) and the number of triangles (2220). The next item in the header is the maximum number of (first-order) neighbors that any-given point in this tstack has (6). The final two flags identify whether points in this file have associated valid normals (1) and curvatures (0). In this specific file the points do have normals, but the principal curvatures have not been computed, hence their values are set to zero.


#TriangulatedStack File,numcontours,numpoints,numtriangles,maxconnection,hasnormals,hascurvatures
#3
#314
#416
#21
#1
#0

The next section contains the index of the first point and z-coordinate for each of the planar contours. For example, the third contour starts at point 222 and has z-coordinate 77.220. (This example is of a cylinder surface, hence the regularity!)


#--------------Contour Indices-------------------------------------
0      74.880  
111    76.050  
222    77.220  
333    78.390  
444    79.560  
555    80.730  
666    81.900  
777    83.070  
888    84.240  
999    85.410  
1110   86.580

Next, each point is listed (we list the first 4 here). Each point is represented by nine items, (i) the index, (ii) the x,y,z coordinates, (iii) the x,y and z components of the surface normal and (iv) the first and second principal curvature of the surface at this point.


#--------------Points-----------------------------------------------
     0  93.000  93.637  74.880  1.000 0.010 0.000   0.000000   0.000000
     1  92.977  94.808  74.880  0.999 0.044 0.000   0.000000   0.000000
     2  92.908  96.012  74.880  0.996 0.083 0.000   0.000000   0.000000
     3  92.792  97.206  74.880  0.992 0.123 0.000   0.000000   0.000000

Next, the triangles are listed. Each triangle is represented by four numbers, (i) the index, (ii) the indices of the three points that make up the triangle.


#--------------Triangles--------------------------------------------
     0      0    112    111
     1      0      1    112
     2      1    113    112
     3      1      2    113

Finally, for the purpose of fast searching, the neighbors of each point are listed. Each line consists of (i) the index of the specific point, (ii) the number of neighbors it has, and (iii) the indices of its neighbors.


#--------------Neighbors-------------------------------------------
0       4 112    111    1      110    
1       4 0      112    113    2      
2       4 1      113    114    3      
...
424     6 312    423    313    425    535    536    
425     6 313    424    314    426    536    537

Note: For those who are looking at the code, this file format can be read/saved using the vtkpxTriangulatedStack class in the Legacy directory. The vtkpxTStackReader class can also be used to read this class.

The .vtk format

The interested reader is referred to the documentation of the Visualization Toolkit for more details on this format.

26.3 Landmark Collections

This format stores collections of points and is primarily used by the Landmark Control. The points (landmarks) are stored in voxel coordinates with the information above them in the header giving the position of the (0,0,0) voxel and the dimensions of each voxel (1.2,1.17,1.17). The first line ``#Landmark Data'', must be reproduced exactly. The other part of the header (line 3) lists the number of points (4 in this case) and the Mode. The Mode flag is 2 if this represents a closed curve or 1 otherwise.

#Landmark Data
#Number of Landmarks Mode
4 1
#Origin
  0.000  0.000  0.000
#Spacing
  1.200  1.170  1.170
#Landmarks
 62.00  48.77  97.34
 62.00  88.95  86.71
 62.65  68.87  87.00
 33.47  69.00  79.26

26.4 Transformations

There a number of transformation file formats in BioImage Suite. The two most important ones are the linear transformations (.matr) and the non-linear transformations (.grd).

The .matr file format

This is simply a 4x4 matrix stored in a text file with no additional information, e.g.

  0.996   0.059  -0.061 -16.756 
 -0.054   0.994   0.094  -0.724 
  0.066  -0.091   0.994 -20.989 
  0.000   0.000   0.000   1.000

The .grd nonlinear transformation file format

The .grd file contains a combined linear and non-linear transformation. The first line is ``#vtkpxNewComboTransform File'' and must be reproduced exactly. The third line defines whether in transforming a point, the non linear transformation is applied first, when combining the two transformations. Next is the linear transformation, which is the usual 4x4 matrix.

#vtkpxNewComboTransform File
#NonLinearFirst
1
#Linear Component
  0.997   0.072  -0.064  -4.009 
 -0.070   0.980  -0.114  21.625 
  0.049   0.139   0.987 -63.856 
  0.000   0.000   0.000   1.000

After the specification of the linear transformation, the file contains the specification of the non-linear component. This is a tensor spline. The first term (Origin) is the position of the first control point (in the corner of the tensor grid). Next follows the spacing of the tensor grid in x,y and z directions respectively. Following this, the dimensions of the grid (15x15x12) are specified. The final header term is the interpolation mode. This can take values: 0=nearest neighbor, 1=trilinear, 3=tricubic, and 4=tensor b-spline - the last one is the most common. After the header, the displacements of each control point are given, each line list the index of the control point followed by its displacement.

#vtkpxBaseGridTransform2 File
#Origin
 -15.4000 -16.0273 -63.8557
#Spacing
 19.8390 20.1219 20.2082
#Dimensions
 15 15 12
#Interpolation Mode
4
#Displacements
0 -0.0351 -0.0093 0.0486
1 -0.0394 -0.0048 0.0240
2 -0.0439 0.0023 -0.0098

Note: For those who are looking at the code, this file format can be read/saved using the vtkpxComboTransform class in the Registration directory. A generic transformation reader for all the file formats in BioImage Suite is available in the vtkpxTransformationUtil class in the same directory &ndash look at the method LoadAbstractTransform.

26.5 Colormaps

Colormaps are used to map a scalar intensity value into RGBA space. They are typically implemented as lookup tables. The Colormap Editor supports two colormap formats, the native ``.cmap'' format, and the Analyze ``.lkup'' format. These are described next.

The .cmap colormap file format

This consists of a short header that defines (i) the number of colors (256 in this case) and the input range (0.0 to 255.0 in this case). Much like the rest of the custom file formats, the first line must be reproduced exactly. If the intensity to be mapped has value below the lower range level (e.g. anything less than 0.000 in this case) then it gets mapped to the same intensity as the lower range level. Similarly, if it has value above the upper level (e.g. anything greater than 255.0), it will get mapped to the same intensity as the upper range level.

 #IPAGRGBAColormap
#Number of Colors
256
#Range
0.000 255.000
#Colors
#Index R G B Alpha

Following the header, the file includes the RGBA mapping for each level. Each line has 5 elements: (i) the index, (ii) the RGBA value, each value being in the range of 0.0 to 1.0.

   0 0.000 0.000 0.000 0.502
   1 0.004 0.004 0.004 1.000
   2 0.008 0.008 0.008 1.000
   3 0.012 0.012 0.012 1.000
   4 0.016 0.016 0.016 1.000
....
 251 1.000 1.000 0.529 1.000
 252 1.000 1.000 0.557 1.000
 253 1.000 1.000 0.584 1.000
 254 1.000 1.000 0.612 1.000
 255 1.000 1.000 0.639 1.000

The Analyze .lkup colormap file format

This is an extremely simple format, retained for compatibility reasons. It consists of exactly 256 lines, each of which has an RGB (note: no Alpha/Transparency Channel) value, where the range is between 0 and 255. For example, for the same colormap above, this has the form:

  0   0   0 
  1   1   1 
  2   2   2 
  3   3   3 
  4   4   4 
...
255 255 135 
255 255 142 
255 255 149 
255 255 156 
255 255 163

26.6 Setup Files

Different components of BioImage Suite have their own setup files for storing complex information, such as lists of filenames and associated transformations etc. While, some of these are easy to read, the only one that users should consider editing in a text editor is the Multisubject Control setup file which is described in detailed in the Multisubject manual page.

Next: 27. Command Line/Batch Mode Up: 8 Additional/Miscellaneous Topics Previous: 8 Additional/Miscellaneous Topics Contents