E Image Raw Pixel Format

E.1 Raw Pixel Introduction

Oracle Multimedia supports many popular image formats suitable for storing artwork, photographs, and other images in an efficient, compressed way, and provides the ability to convert between these formats. However, most of these formats are proprietary to at least some degree, and the format of their content is often widely variable and not suited for easy access to the pixel data of the image.

The Raw Pixel format is useful for applications that need direct access to the pixel data without the burden of the complex computations required to determine the location of pixels within a compressed data stream. This simplifies reading the image for applications that are performing pixel-oriented image processing, such as filtering and edge detection. This format is even more useful to applications that need to write data back to the image. Because changing even a single pixel in a compressed image can have implications for the entire image stream, providing an uncompressed format enables applications to write pixel data directly, and later compress the image with a single process( ) command.

This format is also useful to users who have data in a format not directly supported by Oracle Multimedia, but is in a simple, uncompressed format. These users can prepend a Raw Pixel identifier and header onto their data and import it into Oracle Multimedia. For users who need only to read these images (such as for import or conversion), this capability is built into Oracle Multimedia as "Foreign Image Support." How this capability is related to the Raw Pixel format is described in Section E.10.

In addition to supporting image types not already built into Oracle Multimedia, the Raw Pixel format also permits the interpretation of N-band imagery, such as satellite images. Using Raw Pixel, one or three bands of an N-band image may be selected during conversion to another image format, allowing easy visualization within programs that do not otherwise support N-band images. Note that images written with the Raw Pixel format still may have only one or three bands.

The current version of the Raw Pixel format is 1.0. This appendix is applicable to Raw Pixel images of this version only, as the particulars of the format may change with other versions.

E.2 Raw Pixel Image Structure

A Raw Pixel image consists of a 4-byte image identifier, followed by a 30-byte image header, followed by an arbitrary gap of 0 or more bytes, followed by pixel data.

It is worth noting that Raw Pixel images are never color-mapped, and therefore do not contain color lookup tables.

The Raw Pixel header consists of the Image Identifier and the Image Header. The Image Header is actually composed of several fields.

Note that the first byte in the image is actually offset 0. All integer fields are unsigned and stored in big endian byte order.

Table E-1 describes the raw pixel image header structure.

E.3 Raw Pixel Header Field Descriptions

This section describes the fields of the Raw Pixel header in greater detail.

Image Identifier

Occupying the first 4 bytes of a Raw Pixel image, the identifier string must always be set to the ASCII values "RPIX" (hex 52 50 49 58). These characters identify the image as being encoded in RPIX format.

This string is currently independent of the Raw Pixel version.

Image Header Length

The Raw Pixel reader uses the value stored in this field to find the start of the pixel data section within a Raw Pixel image. To find the offset of the pixel data in the image, the reader adds the length of the image identifier (always 4) to the value in the image header length field. Thus, for Raw Pixel 1.0 images with no post-header gap, the pixel data starts at offset 34.

For Raw Pixel version 1.0 images, this field normally contains the integer value 30, which is the length of the Raw Pixel image header (not including the image identifier). However, the Raw Pixel format allows this field to contain any value equal to or greater than 30. Any information in the space between the end of the header data and the start of the pixel data specified by this header length is ignored by the Raw Pixel reader. This is useful for users who wish to prepend a Raw Pixel header onto an existing image whose pixel data area is compatible with the Raw Pixel format. In this case, the header length would be set to 30 plus the length of the existing header. The maximum length of this header is 4,294,967,265 bytes (the maximum value that can be stored in the 4-byte unsigned field minus the 30-byte header required by the Raw Pixel format). This field is stored in big endian byte order.

Major Version

A single-byte integer containing the major version number of the Raw Pixel format version used to encode the image. The current Raw Pixel version is 1.0, therefore this field is 1.

Minor Version

A single-byte integer containing the minor version number of the Raw Pixel format version used to encode the image. The current Raw Pixel version is 1.0, therefore this field is 0.

Image Width

The width (x-dimension) of the image in pixels.

Although this field is capable of storing an image dimension in excess of 4 billion pixels, limitations within Oracle Multimedia require that this field be a value between 1 and 32767, inclusive. This field is stored in big endian byte order.

Image Height

The height (y-dimension) of the image in pixels.

Although this field is capable of storing an image dimension in excess of 4 billion pixels, limitations within Oracle Multimedia require that this field be a value between 1 and 32767, inclusive. This field is stored in big endian byte order.

Compression Type

This field contains the compression type of the Raw Pixel image. This field may contain the following values:

For grayscale, RGB, and N-band images, the image is always uncompressed, and only a value of 0 is valid. If the compression type is value 1 or 2, then the image is presumed to be monochrome. In this case, the image is presumed to contain only a single band, and must specify normal pixel order, normal scanline order, and BIP interleave.

Pixel Order

This field describes the pixel order within the Raw Pixel image. Typically, pixels in a scanline are ordered from left to right, along the traditional positive x-axis. However, some applications require that scanlines be ordered from right to left.

This field may contain the following values:

This field cannot contain 0, as this indicates an unspecified pixel order; this would mean the image could not be interpreted. For images with CCITT G3 and G4 compression types, this field must contain the value 1.

Scanline Order

This field describes the scanline order within the Raw Pixel image. Typically, scanlines in an image are ordered from top to bottom. However, some applications require that scanlines are ordered from bottom to top.

This field may contain the following values:

This field cannot contain 0, as this indicates an unspecified scanline order; this would mean the image could not be interpreted. For images with CCITT G3 and G4 compression types, this field must contain the value 1.

Interleave

This field describes the interleaving of the various bands within a Raw Pixel image. See Section E.5.3 for more information about the meaning of the various interleave options.

This field may contain the following values:

This field cannot contain 0, as this indicates an unspecified interleave; this would mean the image could not be interpreted. For images with CCITT G3 and G4 compression types, this field must contain the value 1.

Number of Bands

This field contains the number of bands or planes in the image, and must be a value between 1 and 255, inclusive. This field may not contain the value 0.

For CCITT images, this field must contain the value 1.

Red Channel Number

This field contains the number of the band that is to be used as the red channel during image conversion operations. This may be used to change the interpretation of a normal RGB image, or to specify a default band to be used as red in an N-band image. This default may be overridden using the inputChannels operator in the process( ) or processCopy( ) methods.

If the image has only one band, or only one band from an N-band image should be selected for display, then the band number should be encoded as the red channel. In this case, the green and blue channels should be set to 0.

This field may not contain the value 0; it must contain a value between 1 and the number of bands, inclusive.

Green Channel Number

This field contains the number of the band that is to be used as the green channel during image conversion operations. This may be used to change the interpretation of a normal RGB image, or to specify a default band to be used as green in an N-band image. This default may be overridden using the inputChannels operator in the process( ) or processCopy( ) method.

If the image has only one band, or only one band from an N-band image should be selected for display, then the band number should be encoded as the red channel. In this case, the green and blue channels should be set to 0.

This field may contain a value between 0 and the number of bands, inclusive.

Blue Channel Number

This field contains the number of the band that is to be used as the blue channel during image conversion operations. This may be used to change the interpretation of a normal RGB image, or to specify a default band to be used as blue in an N-band image. This default may be overridden using the inputChannels operator in the process( ) or processCopy( ) method.

If the image has only one band, or only one band from an N-band image should be selected for display, then the band number should be encoded as the red channel. In this case, the green and blue channels should be set to 0.

This field may contain a value between 0 and the number of bands, inclusive.

Reserved Area

The application of these 8 bytes titled Reserved Area is currently under development, but they are reserved even within Raw Pixel 1.0 images. These bytes must all be cleared to 0. Failure to do so will create undefined results.

E.4 Raw Pixel Post-Header Gap

Apart from the image identifier and the image header, Raw Pixel version 1.0 images contain an optional post-header gap, which precedes the actual pixel data. Unlike the reserved area of the image header, the bytes in this gap can contain any values you want. This is useful to store additional metadata about the image, which in some cases may be the actual image header from another file format.

However, because there is no standard for the information stored in this gap, take care when storing metadata in this area as other users may interpret this data differently. It is also worth noting that when a Raw Pixel image is processed, information stored in this gap is not copied to the destination image. In the case of the process( ) method, which writes its output to the same location as the input, the source information will be lost unless the transaction in which the processing took place is rolled back.

E.5 Raw Pixel Data Section and Pixel Data Format

The data section of a Raw Pixel image is where the actual pixel data of an image is stored; this area is sometimes called the bitmap data. This section describes the layout of the bitmap data.

For images using CCITT compression, the bitmap data area stores the raw CCITT stream with no additional header. The rest of this section applies only to uncompressed images.

Bitmap data in a Raw Pixel image is stored as 8-bit per plane, per pixel, direct color, packed data. There is no pixel, scanline, or band blocking or padding. Scanlines may be presented in the image as either topmost first, or bottommost first. Within a scanline, pixels may be ordered leftmost first, or rightmost first. All these options are affected by interleaving in a relatively straightforward way; see the following sections for examples.

1111111111…
2222222222…
3333333333…
4444444444…

…1111111111…2222222222…3333333333…4444444444…

…4444444444…3333333333…2222222222…1111111111…

…123456789…

…123456789…

…987654321…

scanline 1: RGBRGBRGBRGBRGBRGBRGB… 
scanline 2: RGBRGBRGBRGBRGBRGBRGB… 
scanline 3: RGBRGBRGBRGBRGBRGBRGB… 
…

scanline 1: RRRRRRRRRRRRRRRRRRRRR…
            GGGGGGGGGGGGGGGGGGGGG…
            BBBBBBBBBBBBBBBBBBBBB…
scanline 2: RRRRRRRRRRRRRRRRRRRRR…
            GGGGGGGGGGGGGGGGGGGGG…
            BBBBBBBBBBBBBBBBBBBBB…
scanline 3: RRRRRRRRRRRRRRRRRRRRR…
            GGGGGGGGGGGGGGGGGGGGG…
            BBBBBBBBBBBBBBBBBBBBB…
…

plane 1: RRRRRRRRRRRRRRRRRR…  (part of scanline 1)
         RRRRRRRRRRRRRRRRRR…  (part of scanline 2)
         RRRRRRRRRRRRRRRRRR…  (part of scanline 3)
…
plane 2: GGGGGGGGGGGGGGGGGG…  (part of scanline 1)
         GGGGGGGGGGGGGGGGGG…  (part of scanline 2)
         GGGGGGGGGGGGGGGGGG…  (part of scanline 3)
…
plane 3: BBBBBBBBBBBBBBBBBB…  (part of scanline 1)
         BBBBBBBBBBBBBBBBBB…  (part of scanline 2)
         BBBBBBBBBBBBBBBBBB…  (part of scanline 3)
…

E.6 Raw Pixel Header - C Language Structure

The following C language structure describes the Raw Pixel header in a programmatic way. This structure is stored unaligned in the image file (that is, fields are aligned on 1-byte boundaries) and all integers are stored in big endian byte order.

struct RawPixelHeader
{
unsigned char identifier[4]; /* Always "RPIX" */

unsigned long   hdrlength; /* Length of this header in bytes */
/* Including the hdrlength field */
/* Not including the identifier field */
/* &k.hdrlength + k.hdrlength = pixels */

unsigned char majorversion; /* Major revision # of RPIX format */
unsigned char minorversion; /* Minor revision # of RPIX format */

unsigned long width;  /* Image width in pixels */
unsigned long height; /* Image height in pixels */
unsigned char comptype;   /* Compression (none, FAXG3, FAXG4, ... ) */
unsigned char pixelorder; /* Pixel order */
unsigned char scnlorder;  /* Scanline order */
unsigned char interleave; /* Interleaving (BIP/BIL/BSQ) */

unsigned char numbands; /* Number of bands in image (1-255) */
unsigned char rchannel; /* Default red channel assignment */
unsigned char gchannel; /* Default green channel assignment */
unsigned char bchannel; /* Default blue channel assignment */
/* Grayscale images are encoded in R */
/* The first band is 1, not 0 */
/* A value of 0 means "no band" */

unsigned char reserved[8]; /* For later use */
};

E.7 Raw Pixel Header - C Language Constants

The following C language constants define the values used in the Raw Pixel header:

#define RPIX_IDENTIFIER "RPIX"

#define RPIX_HEADERLENGTH 30

#define RPIX_MAJOR_VERSION 1
#define RPIX_MINOR_VERSION 0

#define RPIX_COMPRESSION_UNDEFINED 0
#define RPIX_COMPRESSION_NONE 1
#define RPIX_COMPRESSION_CCITT_FAX_G3 2
#define RPIX_COMPRESSION_CCITT_FAX_G4 3
#define RPIX_COMPRESSION_DEFAULT RPIX_COMPRESSION_NONE

#define RPIX_PIXEL_ORDER_UNDEFINED 0
#define RPIX_PIXEL_ORDER_NORMAL 1
#define RPIX_PIXEL_ORDER_REVERSE 2
#define RPIX_PIXEL_ORDER_DEFAULT RPIX_PIXEL_ORDER_NORMAL

#define RPIX_SCANLINE_ORDER_UNDEFINED 0
#define RPIX_SCANLINE_ORDER_NORMAL 1
#define RPIX_SCANLINE_ORDER_INVERSE 2
#define RPIX_SCANLINE_ORDER_DEFAULT RPIX_SCANLINE_ORDER_NORMAL

#define RPIX_INTERLEAVING_UNDEFINED 0
#define RPIX_INTERLEAVING_BIP 1
#define RPIX_INTERLEAVING_BIL 2
#define RPIX_INTERLEAVING_BSQ 3
#define RPIX_INTERLEAVING_DEFAULT RPIX_INTERLEAVING_BIP

#define RPIX_CHANNEL_UNDEFINED 0

Note that the various macros for the UNDEFINED values are meant to be illustrative and not necessarily used, except for "RPIX_CHANNEL_UNDEFINED," which is used for the green and blue channels of single-band images.

E.8 Raw Pixel PL/SQL Constants

The following PL/SQL constants define the values used in the raw pixel information. The constants represent the length of the RPIX image identifier plus the length of the RPIX header.

CREATE OR REPLACE PACKAGE ORDImageConstants AS 
  RPIX_HEADER_LENGTH_1_0   CONSTANT INTEGER := 34; 
END ORDImageConstants; 

E.9 Raw Pixel Images Using CCITT Compression

Although the Raw Pixel format is generally aimed at uncompressed direct color images, provision is also made to store monochrome images using CCITT Fax Group 3 or Fax Group 4 compression. This is useful for storing scans of black and white pages, such as for document management applications. These images are generally impractical to store even as grayscale, as the unused data bits combined with the very high resolution used in these images would use excessive disk space.

Raw Pixels images using CCITT compression are treated as normal Raw Pixel images, with the following restrictions:

• The compression type field must contain the value 1 or 2 as outlined in Section E.3 (FAX3 or FAX4).

• The pixel order field must contain the value 1 (normal pixel order).

• The scanline order field must contain the value 1 (normal scanline order).

• The interleave field must contain the value 1 (BIP interleave).

• The number of bands field must contain the value 1 (one band).

• The red channel number field must contain the value 1.

• The green channel number and the blue channel number fields must contain the value 0 (no band).

In addition to these restrictions, applications that attempt to access pixel data directly will need to understand how to read and write the CCITT formatted data.

E.10 Foreign Image Support and the Raw Pixel Format

Oracle Multimedia provides support for reading certain foreign images that can be described in terms of a few simple parameters, and whose data is arranged in a certain straightforward way within the image file. There is no list of the supported formats because the list would be very large and continually changing. Instead, there are some simple guidelines to determine if an image can be read using the foreign image support in Oracle Multimedia. These rules are summarized in the following sections.

Header

Foreign images may have any header (or no header), in any format, as long as its length does not exceed 4,294,967,265 bytes. As has been noted before, all information in this header will be ignored.

Image Width

Foreign images may be up to 32,767 pixels wide.

Image Height

Foreign images may be up to 32,767 pixels high.

Compression Type

Foreign images must be uncompressed or compressed using CCITT Fax Group 3 or Fax Group 4. Other compression schemes, such as run-length encoding, are not currently supported.

Pixel Order

Foreign images may store pixels from left-to-right or right-to-left. Other pixel ordering schemes, such as boustrophedonic ordering, are not currently supported.

Scanline Order

Foreign images may have top-first or bottom-first scanline orders. Scanlines that are adjacent in the image display must be adjacent in the image storage. Some image formats stagger their image scanlines so that, for example, scanlines 1,5,9, and so forth, are adjacent, and then 2,6,10 are also adjacent. This is not currently supported.

Interleaving

Foreign images must use BIP, BIL, or BSQ interleaving. Other arrangements of data bands are not allowed, nor may bands have any pixel, scanline, or band-level blocking or padding.

Number of Bands

Foreign images may have up to 255 bands of data. If there are more bands of data, the first 255 can be accessed if the interleaving of the image is band sequential. In this case, the additional bands of data lie past the accessible bands and do not affect the layout of the first 255 bands. Images with other interleaving types may not have more than 255 bands because the additional bands will change the layout of the bitmap data.

Trailer

Foreign images may have an image trailer following the bitmap data, and this trailer may be of arbitrary length. However, such data is completely ignored by Oracle Multimedia, and there is no method (or need) to specify the presence or length of such a trailer.

If an image with such a trailer is modified with the process( ) or processCopy( ) methods, the resulting image will not contain this trailer. In the case of the processCopy( ) method, the source image will still be intact.