Format of SPIDER 2D and 3D image files

SPIDER uses NX to denote number of pixels (voxels) per row, NY to denote number of rows, and NZ to denote the number of slices or planes in a volume. A 2D image is considered to be a single slice of a volume. The first pixel in an image represents the upper left corner of the image. (Note: this is important for correct handedness when converting volumes.) All SPIDER image files consist of unformatted, direct access records. Each record contains NX 4-byte words which are stored as floating point numbers.

There are three types of SPIDER image files: Simple images/volumes. Image stack files, and Indexed image stack files.

The image data is preceeded by a header. There are LABREC records in the header, where LABREC = ceiling of (256/NX). Note that the total length of the header in SPIDER images is always >= 1024 bytes and is calculated as follows (in FORTRAN) when a new SPIDER image is created:

LENBYT = NX * 4
LABREC = 1024 / LENBYT
IF (MOD(1024,LENBYT) .NE. 0) LABREC = LABREC + 1
LABBYT = LABREC * LENBYT

Where LENBYT is the record length in bytes, and the MOD function returns the remainder of dividing 1024 by LENBYT. This variable length header is used for compatibility with FORTRAN direct access unformatted file I/O.

Current Layout of the SPIDER Header (Label) Record

Location Name Content
1NZ Number of slices (planes) in volume (=1 for an image) In some ancient 2D images this may be -1)
2NY Number of rows per slice.
3IREC Total number of records (including header records) in each image of a simple image or stacked image file.
4UNUSEDUnassigned
5IFORM File type specifier.
1 R 2D image.
3 R 3D volume.
-11 FO 2D Fourier, odd
-12 FE 2D Fourier, even
-21 FO 3D Fourier, odd
-22 FE 3D Fourier, even
6IMAMIMaximum/minimum flag = 0 when the file is created, and = 1 when the maximum, minimum, average, and standard deviation have been computed and stored into this header record (see following locations).
7FMAX Maximum data value.
8FMIN Minimum data value.
9AV Average data value.
10SIG Standard deviation of data. A value of -1.0 or 0.0 indicates that SIG has not been computed.
11UNUSED No longer used.
12NX Number of pixels (samples) per line.
13LABREC Number of records in file header (label).
14IANGLE Flag that following three tilt angles are present.
15PHI Tilt angle: phi (See note #2 below).
16THETA Tilt angle: theta.
17GAMMA Tilt angle: gamma (also called psi).
18XOFF X translation.
19YOFF Y translation.
20ZOFF Z translation.
21SCALE Scale factor.
22LABBYT Total number of bytes in header.
23LENBYT Record length in bytes.
24ISTACK/
MAXINDX
Position has a value of 0 in simple 2D or 3D (non-stack) files. In an "image stack" there is one overall stack header followed by a stack of images, in which each image has its own image header. A value of >0 in this position in the overall stack header indicates a stack of images. A value of <0 in this position in the overall stack header indicates an indexed stack of images and gives the maximum image number (MAXINDX) allowed in the index.
25UNUSEDUnused now. Prior to release 9.0, a '-1' at this location in an overall stack indicated a valid stack and in the stacked images, a value of 1 indicated that this image was in use (existed).
26MAXIMPosition is only used in the overall header for a stacked image file. There, this position contains the number of the highest image currently used in the stack. This number is updated, if necessary, when an image is added or deleted from the stack.
27IMGNUMPosition is only used in a stacked image header. There, this position contains the number of the current image or zero if this image is unused.
28LASTINDXPosition is only used in overall header of indexed stacks. There, this position is the highest index location currently in use.
29UNUSEDUnassigned
30UNUSEDUnassigned
31KANGLEFlag that additional rotation angles follow in header. 1 = one additional angle set is present, 2 = two additional angle sets.
32PHI1 Angle.
33THETA1 Angle.
34PSI1 Angle.
35PHI2 Angle.
36THETA2 Angle.
37PSI2 Angle.
38PIXSIZ Pixel size (Angstroms).
39EV Electron voltage used.
40PROJ Project number.
41MIC Micrograph number.
42NUM Micrograph window number.
43GLONUM Global image number.
44-47UNUSED Unassigned.
48-76 - Reserved for XMIPP or other local transforms
77-100- Unassigned.
101 PSI3 Projection angle: Psi (From 'PJ 3Q').
102 THETA3 Projection angle: Theta (From 'PJ 3Q').
103 PHI3 Projection angle: Phi (From 'PJ 3Q').
104 LANGLE If = 1 then projection angles: PSI3, THETA3 & PHI3 are present in header.
105-211 - Unassigned
212-214CDATCharacter *11 Creation date e.g. 27-MAY-1999
215-216CTIMCharacter *8 Creation time e.g. 09:43:19
217-256 CTITCharacter *160 Title

Types of Image/Volume Files

There are three types of SPIDER image files: Simple images/volumes. Image stack files, and Indexed image stack files.

  1. Simple image / volume with: NX x NY x NZ voxels.
    Unformatted, direct access file containing a total of LABREC + NY * NZ records.

    Record No. ---> Record No. Contents
    1 LABREC Image/volume header
    LABREC+1 LABREC+NY Slice No. 1
    LABREC+NY+1 LABREC+2*NY Slice No. 2
    .. .. Further slices
    LABREC+NY*(NZ-1) LABREC+NZ*NY Slice No. NZ

  2. Stack of images / volumes with: NX x NY x NZ voxels in each image.
    Unformatted, direct access file containing a total of LABREC + MAXIM * (LABREC + NY * NZ) records.

    Record No. ---> Record No. Contents
    1 LABREC Overall stack header
    LABREC+1 2*LABREC First stacked image/volume header
    2+LABREC+1 2*LABREC+NY*NZ) Image/volume No. 1
    2*LABREC+NY*NZ+1 3*LABREC+NY*NZ Second stacked image/volume header
    3*LABREC+NY*NZ+1 3*LABREC+2*NY*NZ Image/volume No. 2
    .. .. Further sets of headers & images/volumes
    MAXIM*LABREC+(MAXIM-1)*NY*NZ+1 (MAXIM+1)*LABREC+(MAXIM-1)*NY*NZ Last stacked image/volume header
    (MAXIM+1)*LABREC+(MAXIM-1)*NY*NZ+1 (MAXIM+1)*LABREC+MAXIM*NY*NZ Last stacked image/volume

  3. Indexed Stack of images / volumes with: NX x NY x NZ voxels in each image.
    Unformatted, direct access file containing a total of LABREC +INDXREC + MAXIM * (LABREC + NY * NZ) records.

    The image data is preceeded by an overall file header and an additional index header. There are INDXREC records in the header, where INDXREC = ceiling of (MAXINDX/NX). The user must specify a value for MAXINDX whenever an indexed stack file is originally created. (For programmers attempting to write conversion utilities, I advise them to ignore indexed stacks. They are mainly in use at only a couple of sites with specialized large data requirements.)

    Record No. ---> Record No. Contents
    1 LABREC Overall stack header
    LABREC+1 LABREC+INDXREC Overall index header
    INDXREC+LABREC+1 INDXREC+2*LABREC First stacked image/volume header
    INDXREC+2+LABREC+1 INDXREC+2*LABREC+NY*NZ) Image/volume No. 1
    INDXREC+2*LABREC+NY*NZ+1 INDXREC+3*LABREC+NY*NZ Second stacked image/volume header
    INDXREC+3*LABREC+NY*NZ+1 INDXREC+3*LABREC+2*NY*NZ Image/volume No. 2
    .. .. Further sets of headers & images/volumes
    INDXREC+MAXIM*LABREC+(MAXIM-1)*NY*NZ+1 INDXREC+(MAXIM+1)*LABREC+(MAXIM-1)*NY*NZ Last stacked image/volume header
    INDXREC+(MAXIM+1)*LABREC+(MAXIM-1)*NY*NZ+1 INDXREC+(MAXIM+1)*LABREC+MAXIM*NY*NZ Last stacked image/volume

Notes

  1. All character arrays are retrieved from the floating point buffer array containing the header record(s) by equivalence assignments. Thus character arrays are stored in the header without any conversion.
  2. The angle, offset & scale factor locations contained in the SPIDER header are available to communicate between different SPIDER operations. Currently they are NOT used in the code distributed with SPIDER, but some outside labs make extensive use of these positions. The angles are usually in Euler format and are given in degrees.
  3. SGI Irix, most IBM, and Sun Unix machines usually use a different native byte ordering from GNU/Linux on Intel, or HP Alpha machines. SPIDER contains the "CP TO OPEND" operation to interconvert these files. However SPIDER can read/write either byte ordering now.
  4. If you are creating a conversion program to read SPIDER images we advise that is simpler if you only implement support for simple 2D and 3D real images. It is almost never necessary to convert Fourier images. If you must implement stacked image conversion we advise skipping conversion of Indexed stacks.
  5. If you are creating a conversion program to create SPIDER images we again advise that is simpler if you only implement support for simple 2D and 3D real images. The only essential non-zero image header positions in a simple image or volume are: 1,2,5,12,13,22,23. For neatness: positions: 212-256 may be filled with 'blanks'.


Source: image_doc.html     Last update: 30 Oct. 2013     ArDean Leith


© Copyright Notice /       Enquiries: spider@wadsworth.org