Image File Format for Alvey Vision Consortium 2

Working Version 14.5.85 by C. R. Brown.
Derived from 2nd Draft 12.9.84 by A Blake.

The following specifies a file format (called IFF) for images.
It is meant to be comprehensive without being unduly pedantic,
and to cater for projected needs of stereo image interpretation.
Images may be mono or stereo, produced by a camera or by an
image synthesizer or other process. The image consists of a
header followed by data. Here is the structure of the file as
a sequence of fields:


  Field          Allowed          Meaning                         See
no.  name        values                                           note

1  header_length 0..32000         Length of header in words       1
2  image_type    BYTE/WORD/       image type                      2,3
                 BOOLEAN
3  height        0..32000         image height (pixels)
4  width         0..32000         image width  (pixels)
5  signed        TRUE/FALSE       signed/unsigned data
6  fov_height    0..32000         field of view height (mrad)     4
7  fov_width     0..32000         field of view width (mrad)      4
8  stereo        TRUE/FALSE       stereo pair/mono image
9  baseline      0..32000         optical centres separation (mm) 4
10 vergence      -1571..1571      vergence angle (mrad)           4
11 gaze          -1571..1571      gaze angle (mrad)               4
12 source_id     0..32000         i.d. of camera or synthesizer   5
13 processed     TRUE/FALSE       true if image not directly from 5
                                  source - i.e. processed since.
14 date          STRING           date of generation (dd/mm/yy)   6
15 time          STRING           time of generation (hh:mm:ss)   6
16 stop          0..32000         lens stop (f no. x 100)
17 focus         0..32000         lens focal length (mm)
18 magic         8516 hex         magic number                    7
19 title         STRING           image title                     8
[unspecified bytes, to fill remainder of header block]
20 data_left                      image - left half if stereo     3
21 data_right                     right image (stereo only)       3

NOTES

The header will usually be 512 bytes long.

The header fields (except those marked 'STRING') consist of
16-bit integers representing coded types or integer values.
An integer value normally lies in the range -32000..32000 but
may have the special value UNKNOWN (32767).
Fields 1-4 must NOT be UNKNOWN. Coded values are:

TRUE            1
FALSE           0
BYTE            0
WORD            1
BOOLEAN         2

Other types (in addition to BYTE/WORD/BOOLEAN) may be defined
for other formats.

The data for an image consists simply of a sequence of bits,
bytes or words representing the values of pixels in raster scan
order; that is, scanning from left to right then top to bottom.
BOOLEAN images occupy one bit per pixel, packed into bytes,
least significant bit first. WORD images occupy 2 bytes per
pixel, stored as LS byte then MS byte.

Viewing Geometry parameters are defined in the accompanying
figures.

If the image has been through a subsequent process since capture
the original camera i.d. and date/time are retained, but the
processed flag is set. An image synthesizer program also has a
source i.d., each and every executable version of the
synthesizer having a unique i.d..

Date and time are stored as strings of 8 consecutive bytes.
These strings are not null-terminated.

The magic field should always have the value 8516 hex. Programs
may use this field to determine (a) that the file they are
reading is really in IFF format, and (b) whether the file needs
byte reversing to suit the local processor. This is intended to
apply only to the header; byte ordering for the images is
defined above.

The title field is a null terminated text title up to 80
characters long.

Subsequent changes to the header must be compatible with this
specification - i.e., extra fields may be added to the end of
the header but the existing fields should not change.


SOFTWARE SUPPORT FOR IFF HANDLING

It is the policy of this site that all programs which deal with
images stored in files should accept and/or produce IFF files,
providing this is appropriate for the type of data being stored.
Software support for this is provided at several levels.

The file /usr/include/image/iff.h defines a C structure for the
IFF header and defines the coded values used therein.

The library file /usr/lib/libiff.a contains the routines
make_header, read_header, and write_header which do most of the
work of creating, reading and writing iff headers. These are
documented in iff(3). To load them, use the flag -liff on your
cc command line.

The program /usr/bin/iffshow converts the header of an iff file into a
readable text form, or vice versa. This may be used simply to
display the header, or to produce a text file for manual editing
and subsequent conversion back to an iff header.
This is documented in iffshow(1).

The shell script /usr/bin/iffedit provides a convenient way to
manually edit an iff header. It invokes iffshow to convert the
header to text format, passes this to vi for editing, then
passes the result back to iffshow to re-write the modified
header. Usage is simply:

iffedit IFFfilename