VIFF

Also Known As: Khoros Visualization/Image File Format

Type Bitmap

Colors Unlimited

Compression None, RLE

Maximum Image Size Unlimited

Multiple Images Per File Yes

Numerical Format Any

Originator Khoral Research

Platform UNIX (X Window)

Supporting Applications Khoros

See Also None

Usage
Used by the Khoros System as its native format.

Comments
The VIFF format is capable of storing any type of information generated by the Khoros System, making VIFF a very diverse and feature-rich format.

Vendor specifications are available for this format.

Code fragments are available for this format.

Sample images are available for this format.

VIFF (Khoros Visualization/Image File Format) is the native file format of the Khoros System environment. Khoros is a visual programming and software development environment used to create image processing and visualization tools for commercial and scientific research. Khoros is implemented using UNIX and the X Window System.

Contents:
File Organization
File Details
For Further Information

Khoros contains a complete visual programming language, code generators, and a user interface editor. Khoros' capabilities include interactive image display; image, numerical, and signal processing and analysis functions; and 2D and 3D plotting.

Khoros is especially useful for conducting research in the areas of image and signal processing, pattern recognition, machine vision, remote sensing, and geographic information systems. Khoros is capable of converting many image file formats to and from VIFF, including TIFF, TGA, FITS, PBM, XBM, DEM, DLG, MATLAB, BIG, ELAS, Sun raster, ASCII, and raw binary. This capability makes the Khoros source code distribution a prime source of image file format information (see "For Further Information" later in this article).

File Organization

All VIFF files contain a header, which is followed by either image data or one or more data (color) maps, or both. If both image and colormap data is present, the image data precedes the map data. VIFF image data need not use a colormap to be valid, and colormaps may be stored in VIFF files with only a header and no image data.

The VIFF specification uses the term "bands" to indicate color channels. An RGB image divided into its component color planes (R,G,B) is said to contain "three bands" of data. Also, multiband data is stored "by pixel" rather than "by plane." In other words, each pixel is stored as an RGB triplet, rather than three separate color planes.

Single-band VIFF images contain a single channel (or plane) of index values and a colormap. Many of the Khoros image-processing functions require that three-band images be converted into single-band pseudocolor images before they can be used.

File Details

This section describes the VIFF header, the data maps, and the location and image data in a VIFF file.

Header

The VIFF header is 1024 bytes in size and has the following format:

typedef struct _ViffHeader
{
 CHAR  FileId;            /* Khoros file ID value (always ABh)*/
 CHAR  FileType;          /* VIFF file ID value (always 01h) */
 CHAR  Release;           /* Release number */
 CHAR  Version;           /* Version number */
 CHAR  MachineDep;        /* Machine dependencies indicator */
 CHAR  Padding[3];        /* Structure alignment padding (always 00h)*/
 CHAR  Comment[512];      /* Image comment text */
 DWORD NumberOfRows;      /* Length of image rows in pixels */
 DWORD NumberOfColumns;   /* Length of image columns in pixels */
 DWORD LengthOfSubrow;    /* Size of any sub-rows in the image */
 LONG  StartX;            /* Left-most display starting position */
 LONG  StartY;            /* Upper-most display starting position */
 FLOAT XPixelSize;        /* Width of pixels in meters */
 FLOAT YPixelSize;        /* Height of pixels in meters */
 DWORD LocationType;      /* Type of pixel addressing used */
 DWORD LocationDim;       /* Number of location dimensions */
 DWORD NumberOfImages;    /* Number of images in the file */
 DWORD NumberOfBands;     /* Number of bands (color channels) */
 DWORD DataStorageType;   /* Pixel data type */
 DWORD DataEncodingScheme;/* Type of data compression used */
 DWORD MapScheme;         /* How map is to be interpreted */
 DWORD MapStorageType;    /* Map element data type */
 DWORD MapRowSize;        /* Length of map rows in pixels */
 DWORD MapColumnSize;     /* Length of map columns in pixels */
 DWORD MapSubrowSize;     /* Size of any subrows in the map */
 DWORD MapEnable;         /* Map is optional or required */
 DWORD MapsPerCycle;      /* Number of different maps present */
 DWORD ColorSpaceModel;   /* Color model used to represent image */
 DWORD ISpare1;           /* User-defined field */
 DWORD ISpare2;           /* User-defined field */
 FLOAT FSpare1;           /* User-defined field */
 FLOAT FSpare2;           /* User-defined field */
 CHAR  Reserve[404];      /* Padding */
} VIFFHEADER;

FileId is a magic number indicating that this is a VIFF file. This value is always ABh.

FileType is a value indicating the type of Khoros file. This value is always 01h, indicating a VIFF file.

Release indicates the release number of the viff.h file in which the VIFF file information structure is defined. This value is currently 01h and does not necessarily match the Khoros system release number.

Version indicates the version number of the viff.h file in which the VIFF file information structure is defined. This value is currently 03h and does not necessarily match the Khoros system version number.

MachineDep contains a value indicating the format of the image data and how the image data was last processed. Values currently defined for this field are:

02h IEEE and big-endian byte ordering

04h Digital Equipment Corporation/VAX byte ordering

08h NS32000 and little-endian byte ordering

0Ah Cray byte size and ordering

Padding is a 3-byte field containing the values 00h 00h 00h. This field is used only to word-align the header structure.

Comment is a 512-byte field typically containing ASCII plain-text information documenting the contents of a VIFF image data. This field may also be used for other purposes, but such uses are strictly user-defined and are not supported by Khoros.

NumberOfRows and NumberOfColumns indicate the size of the image data in pixels (the number of data items). If these two values are set to 00h, then no image data is present in the file, but a colormap may still exist.

LengthOfSubrow is the length in pixels of any subrows that may exist in the image data.

StartX and StartY specify the location of a sub-image within a parent image. The home coordinate (0,0) is always the upper-left corner of the image. If these values are equal to 00h, then the image is not a sub-image.

XPixelSize and YPixelSize indicate the actual size of the pixels in meters. The ratio of these two values gives the aspect ratio of the pixels in the image data.

LocationType indicates whether the image data contains implicit (01h) or explicit (02h) locations.

LocationDim has a value of 00h if the locations are stored implicitly (LocationType is 01h); in this case, there is no location data stored in the VIFF file. Location data is present in the image file if the locations are stored explicitly (LocationType is 02h); in this case, LocationDim indicates the number of dimensions represented by the location data (typically 00h, 01h, or 02h for 1-, 2-, and 3-dimensional data).

NumberOfImages contains a value equal to the number of images stored in the VIFF file.

NumberOfBands indicates the number of bands per image (or dimensions per vector). A three-band RGB image would have a value of 03h in this field.

DataStorageType specifies the data type used to store each pixel. Supported values include:

00h Bit

01h BYTE

02h WORD

04h DWORD

05h Single-precision float

06h Complex float

09h Double-precision float

0Ah Complex double

Note that when pixels are stored as bits, eight pixels are packed per BYTE, least significant bit first, and are padded out to end on a BYTE boundary.

DataEncodingScheme indicates the type of encoding used to compress the image data. Defined values for this field include:

00h No compression

01h ALZ

02h RLE

03h Transform-based

04h CCITT

05h ADPCM

06h User-defined

Only values 00h and 01h are currently supported by Khoros 1.0.

MapScheme indicates the type of mapping present in the VIFF file. Possible values are:

01h Each image band uses its own map

02h The image is displayed by cycling through two or more maps

03h All bands share the same map

04h All bands are grouped together to point into one map

The mapping scheme indicated by a MapScheme value of 04h is not supported by Khoros 1.0.

MapStorageType specifies the type of data in the map or the resulting pixel data type after the mapping has been performed. Valid values for this field are:

00h No data type

01h Unsigned CHAR

02h Short INT

04h INT

05h Single-precision float

06h Complex float

07h Double-precision float

MapRowSize and MapColumnSize indicate the width and height of the map.

MapSubrowSize stores the number of sub-rows in the map, if any.

MapEnable indicates whether the image data is valid if it is not mapped. Possible values for this field are:

01h Image data may be used without first mapping it

02h Map data must be applied to the image data before it can be used.

MapsPerCycle is the number of maps used to cycle the image when it is displayed. The value of this field is valid only if MapScheme is equal to a value of 02h.

ColorSpaceModel specifies the color model used to interpret the image data. The recognized values for this field are:

00h No color space model used

01h NTSC RGB

02h NTSC CMY

03h NTSC YIQ

04h HSV

05h HLS

06h IHS

07h CIE RGB

08h CIE CMY

09h CIE YIQ

0Ah CIE UCS UVW

0Bh CIE UCS SOW

0Ch CIE UCS Lab

0Dh CIE UCS Luv

0Eh User-defined

0Fh User-defined RGB

ISpare1, ISpare2, FSpare1, and FSpare2 are spare fields included for use by a user application. These fields are typically used to store data while the header is stored in memory and may not contain any information when the format is stored to a disk file.

Reserve is a chunk of padding which fills out the VIFF header to 1024 bytes in length. The bytes in this field are normally set to 00h, but may contain user-defined data as well.

Maps

Following the header may be a collection of one or more data maps. A data map contains information that is used to transform the image data in a specified way. By far the most common example of a map is a simple colormap, where each pixel contains an index value that references a color value stored in the map. Although VIFF data maps may contain any type of data necessary to interpret the image data properly, the image data always contains index values if a data map is present in the file.

All maps are stored as 1-dimensional data, and all map values are referenced as elements in an array. The size of the map is indicated in the MapRowSize and MapColumnSize header fields. The size of each element of the map is specified by the MapStorageType field.

Although there may be only one physical map data structure per VIFF file, the map may be divided into two more logical maps, each containing specific data. For example, 3-band image data might use three separate maps (one for each band), or it might use a single map for all three bands. Multiple maps may also be stored that are continually read in sequence as the image is displayed. Such a technique is used to render the image as an animation rather than as a still image.

Maps may also be specified as optional or forced. An optional map need not be used in the interpretation of the image data. A forced map is data that is required in order for the image data is to have any real validity. Forced maps are more common and usually indicate that the map contains color data and that the image data contains map index values.

Location and Image Data

Following any map data in a VIFF file may be a block of data called the location data. This data, if present, stores the coordinate information for each pixel in the image. Location data is a 1-dimensional array of float values and may contain one or more bands (dimensions) of location data. Each location value corresponds to a pixel in the image data. But before we can talk of pixel locations, we must understand how VIFF expresses the pixel data itself.

Pixels may be addressed as if they reside either in a 1-dimensional or in a multi-dimensional space. These addressing types are called implied locations and explicit locations, respectively. The implied location of a pixel is a reference to a pixel stored in a 1-dimensional array, but using the canonical 2-dimensional XY coordinates. For example, if we have a 256x256 image stored in a 1-dimensional array and we need to reference the value of the pixel at location 100x135, we use its implicit coordinates:

WORD ImageWidth = 256;               /* Number of pixel in X axis */
WORD ImageLength = 256;              /* Number of pixel in Y axis */
BYTE PixelArray[ImageWidth * ImageLength];       /* 256x256 image */
BYTE PixelValue;
/* Get the value of the pixel at 100x135 */
PixelValue = PixelArray[ (100 * ImageWidth) + 135 ];

You can see that the formula array [(X * ImageWidth) + Y] yields the value we need. Note that this formula assumes that the pixels in the array are stored by row. If the pixel data is stored by column, then ImageLength value should be used in place of the ImageWidth.

Explicit pixel locations are used to reference pixel data stored in two or more dimensions. If explicit pixel locations are indicated, a block of location data appears in the VIFF file just prior to the image data. This location data stores the coordinates of each pixel in the rendered space. For example:

WORD  ImageWidth = 256;           /* Number of pixel in X axis */
WORD  ImageLength = 256;          /* Number of pixel in Y axis */
WORD  NumberOfDims = 2;           /* Dimensions of pixel locations */
BYTE  PixelArray[ImageWidth * ImageLength];    /* 256x256 image */
FLOAT LocationArray[ImageWidth * ImageLength * NumberOfDims];
BYTE  PixelValue;
FLOAT LocationX;
FLOAT LocationY;
/* Get the value of the pixel at 100x135 */
PixelValue = PixelArray[ (100 * ImageWidth) + 135 ];
/* Get the location of the pixel at 100x135 */
LocationX = LocationArray[ (100 * ImageWidth) + 135 ];
LocationY = LocationArray[ (100 * ImageWidth) + 135 
            + (ImageWidth * ImageLength)];

As you can see, the image data is referenced in the same way for explicit data as it is for implicit data. If a map is present, the pixel values serve as indices into that map. If no map is present, then the pixel values are the actual color or intensity values of the image data.

Location data is stored as bands, but in a planar fashion. In the case of 2-dimensional data, all of the X location values are stored first, followed by all of the Y location values. And although a VIFF image can support thousands of dimensions, 1-, 2-, and 3-dimensional pixel locations are the most common.

For Further Information

For further information about VIFF, see the documentation and sample code included on the CD-ROM.

The Khoros System is owned and copyright by Khoral Research, Inc. and is maintained by the Khoros Consortium. To obtain further information on the Khoros package and its distribution, or to support further research and development of software environments for data processing and visualization, contact:

Khoral Research, Inc.
6001 Indian School Road NE
Suite 200
Albuquerque, NM 87110
Voice: 505-837-6500
FAX: 505-881-3842
WWW: http://www.khoros.unm.edu/khoros/
Email: khoros-request@chama.eece.unm.edu

You can also contact the Khoros User Group at:

khoros@chama.eece.unm.edu

You can join the Khoros mailing list by sending email to:

khoros-request@bullwinkle.eece.unm.edu.

Khoros information may also be found posted in the USENET newsgroup comp.soft-sys.khoros, which is the home of the Khoros FAQ, posted weekly to this group and to news.answers. This and other Khoros FAQs, in addition to the complete Khoros distribution, may also be found in the /release directory of the Khoros System distribution at the following FTP sites:

ftp://ftp.eece.unm.edu/pub/khoros
ftp://ftp.uu.net/pub/window-sys/khoros
ftp://popeye.genie.uottawa.ca/pub/khoros
ftp://ipifidpt.difi.unipi.it/pub/khoros
ftp://ftp.waseda.ac.jp/pub/khoros

Your best source of further VIFF information is the Khoros package itself. The Khoros System distribution is quite large (65 megabytes, not including executables), and it is not practical to download the entire package just to find VIFF information. Instead, you should obtain the files you need from an installed Khoros System or one of the distribution sites previously listed. Information specifically about the VIFF format can be found in the following directories:

src/file_formats/no_format

Programs for converting VIFF files to and from raw binary and ASCII data

src/file_formats/remote_gis

Programs for converting VIFF files to and from remote sensing and GIS file formats.

src/file_formats/standard

Programs for converting VIFF files to and from many other file formats

include/viff.h

VIFF format header file

data/images data/kernels data/lut

Sample VIFF image files

The VIFF format is also described in Chapter 1 of Volume II, Programmer's Manual, of the Khoros Manual Set. Both Chapter 1 and the viff.h file are included on the CD-ROM.

Type	Bitmap
Colors	Unlimited
Compression	None, RLE
Maximum Image Size	Unlimited
Multiple Images Per File	Yes
Numerical Format	Any
Originator	Khoral Research
Platform	UNIX (X Window)
Supporting Applications	Khoros
See Also	None

02h	IEEE and big-endian byte ordering
04h	Digital Equipment Corporation/VAX byte ordering
08h	NS32000 and little-endian byte ordering
0Ah	Cray byte size and ordering

00h	Bit
01h	BYTE
02h	WORD
04h	DWORD
05h	Single-precision float
06h	Complex float
09h	Double-precision float
0Ah	Complex double

00h	No compression
01h	ALZ
02h	RLE
03h	Transform-based
04h	CCITT
05h	ADPCM
06h	User-defined

01h	Each image band uses its own map
02h	The image is displayed by cycling through two or more maps
03h	All bands share the same map
04h	All bands are grouped together to point into one map

00h	No data type
01h	Unsigned CHAR
02h	Short INT
04h	INT
05h	Single-precision float
06h	Complex float
07h	Double-precision float

01h	Image data may be used without first mapping it
02h	Map data must be applied to the image data before it can be used.

00h	No color space model used
01h	NTSC RGB
02h	NTSC CMY
03h	NTSC YIQ
04h	HSV
05h	HLS
06h	IHS
07h	CIE RGB
08h	CIE CMY
09h	CIE YIQ
0Ah	CIE UCS UVW
0Bh	CIE UCS SOW
0Ch	CIE UCS Lab
0Dh	CIE UCS Luv
0Eh	User-defined
0Fh	User-defined RGB