Mark Dow

Space software native file format specification: Space Volume Type 1

There are several flavors of a native file format that Space software can read, and one flavor that any particular version of Space will write. Each flavor is similar in structure and content, primarily varying by the length of the header and the range of optional display parameters included in the header.

This table describes the shortest and simplest native Space file byte structure (Space Volume Type 1), which is characteristic of all Space file types and which all Space versions can read.  It consists of a 10000 byte header containing a volume/file description followed by uncompressed volume data.

This file type does not include specification of a coordinate system origin . Space uses the center of the volume for this file type.

The Matlab program write_Space_volume.m will write a 3-D Matlab array to a file of this type.
 
Contents Data type Number Length, bytes Byte offset from beginning of file Comments
          Little-endian byte ordering is assumed.
The text "mdvol" char, 1 byte 5 5 0 Identifier for any Space file type.
The text "1" char, 1 byte 1 1 5 Space Volume Type file version indicator.
10000 unsigned int, 4 bytes 1 4 6 Length of header, for a Space Volume Type 1 file.
Volume dimensions: xzy (in pixels) unsigned int, 4 bytes 3 12 10 Must correspond with the number of image values (see last row of this table).
Physical dimensions of each voxel: xzy (in mm) float, 4 bytes 3 12 22 Use 0.0, 0.0, 0.0 for unspecified dimensions. Should be positive.
Black point and white point for the initial display, with a range [0,1] float, 4 bytes 2 8 34 These values are used to construct a color LUT for display purposes. Use 0.0, 1.0 for default display. 
Gamma for the initial display,    > 0.0 float, 4 bytes 1 4 42 This value is used to construct a color LUT for display purposes. Use 1.0 for default linear display.
Color code:

The text "g08", "i08", or "c24"

 char, 1 byte 3 3 46 This color code specifies the color format that the image values represent: grayscale 8 bit, *indexed 8 bit , or color 24 bit (3 bytes in RGB order) respectively.
Text description of the Space Volume Type 1 file format char, 1 byte 4900 4900 49 **See footnote for text to use . Fill unused length with space characters. This text is only used for human readable self documentation of the file structure.
Text title for the volume char, 1 byte 151 151 4949 Fill unused length with space characters.
Text description of the volume char, 1 byte 4900 4900 5100 Fill unused length with space characters.
Image values:

(Color code – value order)

g08 – -x/-z/-y order
 


i08 – -x/-z/-y order
 

c24 – rgb/-x/-z/-y order

 byte (8 bit integer),
1 byte
 
 
 

g08 – x*y*z
 


i08 – x*y*z
 

c24 – 3*x*y*z
 
 
 

x*y*z
 


x*y*z
 

3*x*y*z

 10000
 
 
 

One byte/voxel (8 bit integer), x varies fastest.

One bytes/voxel (8 bit integer)

One byte/color, three bytes/voxel, color then x varies fastest.


* The Space Volume Type 1 file type does not include or define a color table for indexed 8 bit data format. Later Space Volume file types do include an 8 bit x 3 byte color table.


** Insert the following, without quote marks, as the "Text description of the Space Volume Type 1 file format":

"  This is a simple file, of Space Volume Type 1, consisting of a header followed by a set of image value bytes, for storing volume image data and basic image display parameters. The header (which should be in little-endian byte order) is a total of 10000 bytes long. The first five characters (mdvol, 5 x 1 byte) identify the file as volume with this file type. One character, 1 byte, serves as a file type version indicator -- this file is of type 1. One integer, 4 bytes, is the total length of the header. Three integers are dimensions, xzy in pixels, of the volume. Three floats, 3x4 bytes, are physical dimensions, xzy in mm, of each voxel. Two floats indicate a reasonable black point and white point for the initial display color transform, with a range [0,1]. One float indicates a reasonable gamma (>0) for the initial display. Three characters, the color code, specifies the color format that the image values represent: gray 8 bit (g08), indexed 8 bit (i08) or color 24 bit (c24). 4900 characters, 4900 x 1 byte, of text is this description of the file format. 151 characters are a text title. 4900 characters are a text description of the volume image content. The rest are image value bytes (8 bit integers), describing the volume image. If the color code is g08, there are x*y*z bytes of image values, in -x/-z/-y order. If the color code is i08, there are x*y*z bytes of image values, in -x/-z/-y order. If the color code is c24, there are 3*x*y*z bytes of image color values, in rgb/-x/-z/-y order.  Specified by Mark Dow, May 2004. "