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.

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:

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

1

NZ

Number of slices (planes) in volume (=1 for an image)
In some ancient 2D images this may be -1)

2

NY

Number of rows per slice.

3

IREC

Total number of records (including header records)
in each image of a simple image or stacked image file.

Maximum/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).

7

FMAX

Maximum data value.

8

FMIN

Minimum data value.

9

AV

Average data value.

10

SIG

Standard deviation of data. A value of
-1.0 or 0.0 indicates that SIG has not been computed.

11

UNUSED

No longer used.

12

NX

Number of pixels (samples) per line.

13

LABREC

Number of records in file header (label).

14

IANGLE

Flag that following three tilt angles are present.

15

PHI

Tilt angle: phi (See note #2 below).

16

THETA

Tilt angle: theta.

17

GAMMA

Tilt angle: gamma (also called psi).

18

XOFF

X translation.

19

YOFF

Y translation.

20

ZOFF

Z translation.

21

SCALE

Scale factor.

22

LABBYT

Total number of bytes in header.

23

LENBYT

Record length in bytes.

24

ISTACK/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.

25

UNUSED

Unused 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).

26

MAXIM

Position 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.

27

IMGNUM

Position 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.

28

LASTINDX

Position is only used
in overall header of indexed stacks. There, this position is
the highest index location currently in use.

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

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.

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.

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.

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.

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'.