This appendix describes the Oracle Raw Pixel image format and is intended for developers and advanced users who wish to use the Raw Pixel format to import unsupported image formats into Oracle interMedia ("interMedia"), or as a means to directly access the pixel data in an image.
Much of this appendix is also applicable to foreign images.
Oracle interMedia 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 interMedia, but is in a simple, uncompressed format. These users can prepend a Raw Pixel identifier and header onto their data and import it into interMedia. For users who need only to read these images (such as for import or conversion), this capability is built into interMedia 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 interMedia, 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.
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.
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 may 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. |
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 interMedia require that this field be a value between 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 interMedia 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:
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 may 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 may 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. For more information about the meaning of the various interleave options, see Section E.5.3.
This field may 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 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.
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.
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 sections that follow for examples.
On the screen, an image may look like the following:
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…
Note that 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.
On the screen, a scanline of an image may look like the following:
…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…
Note that 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.
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) …
The Raw Pixel format supports up to 255 bands of data in an image. The relative location of these bands of data in the image is described in Section E.5.3, which gives 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 given 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] |
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 */ };
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.
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;
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.
Oracle interMedia 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 interMedia. 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 interMedia, 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.