E Image Raw Pixel Format for Use With Oracle Multimedia

This appendix describes the Oracle Raw Pixel image format and is intended for developers and advanced users who want to use the Raw Pixel format to import unsupported image formats into Oracle Multimedia, or as a means to directly access the pixel data in an image.

Much of this appendix is also applicable to foreign images.

This appendix includes these sections:

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 must 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." Section E.10 describes how this capability is related to the Raw Pixel format.

In addition to supporting image types not 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 can be selected during conversion to another image format, enabling easy visualization within programs that do not otherwise support N-band images. 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 can 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.

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.

Table E-1 Raw Pixel Image Header Structure

Name Byte(s) Description

Image Identifier

0:3

4-byte character array containing ASCII values for RPIX.

This array identifies the image as a Raw Pixel image.

Image Header Length

4:7

Length of this header in bytes, excluding the identifier field.

The value of this field can be increased to create a gap between the header fields and the pixel data in the image.

Major Version

8

Major version number of the Raw Pixel format used in the image.

Minor Version

9

Minor version number of the Raw Pixel format used in the image.

Image Width

10:13

Width of the image in pixels.

Image Height

14:17

Height of the image in pixels.

Compression Type

18

Compression type of the image: None, CCITT FAX Group 3, or CCITT FAX Group 4.

Pixel Order

19

Pixel order of the image: Normal or Reverse.

Scanline Order

20

Scanline order of the image: Normal or Inverse.

Interleave

21

Interleave type of the image: BIP, BIL, or BSQ.

Number of Bands

22

Number of bands in the image. Must be in the range 1 to 255.

Red Channel Number

23

The band number of the channel to use as a default for red.

This field is the grayscale channel number if the image is grayscale.

Green Channel Number

24

The band number of the channel to use as a default for green.

This field is zero if the image is grayscale.

Blue Channel Number

25

The band number of the channel to use as a default for blue.

This field is zero if the image is grayscale.

Reserved Area

26:33

Not currently used. All bytes must be zero.


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" (hexadecimal 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 enables 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 want 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 can store 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 can store 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 can contain the following values:

Value Name Compression
1 NONE No compression
2 FAX3 CCITT Group 3 compression
3 FAX4 CCITT Group 4 compression

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 can contain the following values:

Value Name Pixel Order
1 NORMAL Leftmost pixel first
2 REVERSE Rightmost pixel first

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 can contain the following values:

Value Name Scanline Order
1 NORMAL Topmost scanline first
2 INVERSE Bottommost scanline first

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 can contain the following values:

Value Name Interleave
1 BIP Band Interleave by Pixel, or "chunky"
2 BIL Band Interleave by Line
3 BSQ Band SeQuential, or "planar"

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 cannot 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 number can 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 can 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 is to be selected for display, then the band number must be encoded as the red channel. In this case, the green and blue channels are set to 0.

This field cannot 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 number can 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 can 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 is to be selected for display, then the band number must be encoded as the red channel. In this case, the green and blue channels are set to 0.

This field can 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 number can 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 can 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 is to be selected for display, then the band number must be encoded as the red channel. In this case, the green and blue channels are set to 0.

This field can 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 can 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 is 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 can be presented in the image as either topmost first, or bottommost first. Within a scanline, pixels can be ordered leftmost first, or rightmost first. All these options are affected by interleaving in a relatively straightforward way.

The following subsections provide examples for these topics related to Raw Pixel data:

E.5.1 Scanline Ordering

On the screen, an image may look like this:

1111111111…
2222222222…
3333333333…
4444444444…

Each digit represents a single pixel; the value of the digit is the scanline that the pixel is on.

Generally, the scanline that forms the upper or topmost row of pixels is stored in the image data stream before lower scanlines. The preceding image would appear as follows in the bitmap data stream:

…1111111111…2222222222…3333333333…4444444444…

The first scanline appears earlier than the remaining scanlines. The Raw Pixel format refers to this scanline ordering as normal.

However, some applications prefer that the bottommost scanline appear in the data stream first:

…4444444444…3333333333…2222222222…1111111111…

The Raw Pixel format refers to this scanline ordering as inverse.

E.5.2 Pixel Ordering

On the screen, a scanline of an image may look like this:

…123456789…

Each digit represents a single pixel; the value of the digit is the column that the pixel is in.

Generally, the data that forms the leftmost pixels is stored in the image data stream before pixels toward the right. The preceding scanline would appear as follows in the bitmap data stream:

…123456789…

The left pixel appears earlier than the remaining pixels. The Raw Pixel format refers to this pixel ordering as normal.

However, some applications prefer that the rightmost pixel appear in the data stream first:

…987654321…

The Raw Pixel format refers to this pixel ordering as reverse.

E.5.3 Band Interleaving

Band interleaving describes the relative location of different bands of pixel data within the image buffer.

Bands are ordered by their appearance in an image data stream, with 1 being the first band, n being the last band. Band 0 would indicate no band or no data.

Band Interleaved by Pixel (BIP), or Chunky

BIP, or chunky, images place the various bands or channels of pixel data sequentially by pixel, so that all data for one pixel is in one place. If the bands of the image are the red, green, and blue channels, then a BIP image might look like this:

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

Band Interleaved by Line (BIL)

BIL images place the various bands of pixel data sequentially by scanline, so that data for one pixel is spread across multiple notional rows of the image. This reflects the data organization of a sensor that buffers data by scanline. If the bands of the image are the red, green, and blue channels, then a BIL image might look like this:

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

Band Sequential (BSQ), or Planar

Planar images place the various bands of pixel data sequentially by bit plane, so that data for one pixel is spread across multiple planes of the image. This reflects the data organization of some video buffer systems, which control the different electron guns of a display from different locations in memory. If the bands of the image are the red, green, and blue channels, then a planar image might look like this:

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.5.4 N-Band Data

The Raw Pixel format supports up to 255 bands of data in an image. Section E.5.3 describes the relative location of these bands of data in the image, including examples of interleaving for 3 bands of data.

In the case of a single band of data, there is no interleaving; all three schemes are equivalent. Examples of interleaving other numbers of bands are provided in the following table. All images in the examples have three scanlines and four columns. Each band of each pixel is represented by a single-digit band number. Numbers that are unenclosed and are displayed in normal text represent the first scanline of the image, numbers that are enclosed in parentheses and are displayed in italic text represent the second scanline of the image, and numbers that are enclosed in brackets ([ ]) and are displayed in boldface text represent the third scanline of the image.

Bands BIP BIL BSQ
2 12121212
(12121212)
[12121212]
11112222
(11112222)
[11112222]
1111(1111)[1111]
2222(2222)[2222]
4 1234123412341234
(1234123412341234)
[1234123412341234]
1111222233334444
(1111222233334444)
[1111222233334444]
1111(1111)[1111]
2222(2222)[2222]
3333(3333)[3333]
4444(4444)[4444]
5 12345123451234512345
(12345123451234512345)
[12345123451234512345]
11112222333344445555
(11112222333344445555)
[11112222333344445555]
1111(1111)[1111]
2222(2222)[2222]
3333(3333)[3333]
4444(4444)[4444]
5555(5555)[5555]

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:

Various macros for the UNDEFINED values are meant to be descriptive, and should not be used. The exception, "RPIX_CHANNEL_UNDEFINED," 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 these 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 must 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 can have any header (or no header), in any format, if its length does not exceed 4,294,967,265 bytes. As has been noted before, all information in this header is ignored.

Image Width

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

Image Height

Foreign images can 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 can 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 can 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 on, 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 permitted, nor can bands have any pixel, scanline, or band-level blocking or padding.

Number of Bands

Foreign images can 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 cannot have more than 255 bands because the additional bands change the layout of the bitmap data.

Trailer

Foreign images can have an image trailer following the bitmap data, and this trailer can 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 does not contain this trailer. In the case of the processCopy( ) method, the source image is still intact.