|Oracle Visual Information Retrieval User's Guide and Reference
Part Number A85335-01
This appendix describes the command options, or operators, used in the process and processCopy methods.
The available operators fall into three broad categories, each described in its own section. Those categories are Section C.2, "Image Formatting Operators", Section C.3, "Image Processing Operators", and Section C.4, "Format-Specific Operators". An additional section describes the relative order of these operators.
This section describes concepts common to all the image operators and the
process( ) and processCopy( ) methods.
The process( ) and processCopy( ) methods operate on one image, called the source image, and produce another image, called the destination image. In the case of the process( ) method, the destination image is written into the same storage space as the source image, replacing it permanently. For the processCopy( ) method, the storage for the destination image is distinct from the storage for the source image.
The process( ) and processCopy( ) methods are functionally identical except for the fact that process( ) writes its output into the same BLOB from which it takes its input while processCopy( ) writes its output into a different BLOB. Their command string options are identical, and no distinction is drawn between them.
For the rest of this appendix, the names process( ) and processCopy( ) are used interchangeably, and the use of the name process implies both process( ) and processCopy( ), unless explicitly noted otherwise.
All the process( ) operators appear in the command string in the form <operator> = <value>. No operator takes effect merely by being present in the command string. The right side of the expression is called the value of the operator, and determines how the operator will be applied.
In general, any number of operators can be combined in the command string passed into the process( ) method if the combination makes sense. However, certain operators are only supported if other operators are present or if other conditions are met. For example, the compressionQuality operator is only supported if the compression format of the destination image is JPEG. Other operators require that the source or destination image be a raw pixel image or a foreign image.
The flexibility in combining operators allows a single operation to change the format of an image, reduce or increase the number of colors, compress the data, and cut and/or scale the resulting image. This is highly preferable to making multiple calls to do each of these operations sequentially.
At the most abstract level, the image formatting operators are used to change the layout of the data within the image storage. They do not change the semantic content of the image, and unless the source image contains more information than the destination image can store, they do not change the visual appearance of the image at all. Examples of a source image with more information than the destination image can store are:
The FileFormat operator determines the image file type, or format, of the output image. The value of this operator is a 4-character code that is a mnemonic for the new file format name. The list of allowable values for the file format operator is shown in Table 4-5. Appendix A contains basic information about each file format, including its mnemonic, typical file extension, allowable compression and content formats, and other notable features.
The value given to the file format operator is the single most important detail when specifying the output for process( ). This value determines the range of allowable content and compression formats, whether or not compression quality will be useful, and whether or not the format specific operators will be useful.
If the file format operator is not used in the process( ) command string, Visual Information Retrieval will determine the file format of the source image and use that as the default file format value. If the file format of the source image does not support output, then an error will occur. If the source image is a foreign image then the output image will be written as raw pixel data.
The ContentFormat operator determines the format of the image content. The content is taken to mean the number of colors supported by the image and the manner in which they are supported. Depending on which file format is used to store the output image, some or most of the content formats may not be supported.
The supported values for the ContentFormat operator fall into three broad classes with three additional special values. The actual mnemonics for these values are listed in Table 4-5.
The content formats whose names include grayscale or greyscale support only shades of gray. The differences between these content formats is how many shades are allowed. The 4bit formats support 16 shades, while the 8bit formats support 256 shades of gray. There is no distinction between grayscale and greyscale.
The content formats whose names include LUT use a color look-up table to support various colors. The 1bitlut format allows two distinct colors; the 2bitlut format supports 4 colors; the 4bitlut format supports 16 unique colors; and the 8bitlut format supports 256 colors.
The content formats whose names include RGB store the color values directly in the pixel data as a red, green, blue triplet. The number of bits of total RGB data is specified in the format name, and individual formats allocate these bits to red, green, and blue in different ways. However, more bits of data allow for finer distinctions between different shades in any case. Not all bits are used by some image formats.
The monochrome content format allows only black and white to be stored, with no gray shades in between. The raw and 24bitplanar formats are not currently supported.
If the ContentFormat operator is not passed to the process( ) method, then Visual Information Retrieval attempts to duplicate the content format of the source image, if it is supported by the file format of the destination image. Otherwise, a default content format is chosen depending on the destination file format.
The CompressionFormat operator determines the compression algorithm used to compress the image data. The range of supported compression formats depends heavily upon the file format of the output image. Some file formats support but a single compression format, and some compression formats are only supported by one file format.
The supported values for the CompressionFormat operator are listed in Table 4-5.
All compression formats that include RLE in their mnemonic are run-length encoding compression schemes, and work well only for images that contain large areas of identical color. The PACKBITS compression type is a run-length encoding scheme that originates from the Macintosh system, but it is supported by other systems. It has limitations that are similar to other run-length encoding compression formats. Formats that contain LZW or HUFFMAN are more complex compression schemes that examine the image for redundant information, and they are more useful for a broader class of images. FAX3 and FAX4 are the CCITT Group 3 and Group 4 standards for compressing facsimile data and are useful only for monochrome images. All the compression formats mentioned in this paragraph are lossless compression schemes, which means that compressing the image does not discard data. An image compressed into a lossless format and then decompressed will look the same as the original image.
The JPEG compression format is a special case. Developed to compress photographic images, the JPEG format is a lossy format, which means that it compresses the image by discarding unimportant details. Because this format is optimized for compressing photographic and similarly complex images, it often produces poor results for other image types, such as line art images and images with large areas of similar color. JPEG is the only lossy compression scheme currently supported by Visual Information Retrieval.
If the CompressionFormat operator is not used, then Visual Information Retrieval will attempt to use the compression format of the source image if it is supported by the destination image file and content format. Otherwise, a default compression scheme is used depending on the destination file format. This default scheme is often none or no compression.
The CompressionQuality operator determines the relative quality of an image compressed with a lossy compression format. This operator has no meaning for lossless compression formats, and hence is not currently supported for any compression format except JPEG.
The CompressionQuality operator accepts five values, ranging from most compressed image (lowest visual quality) to least compressed image (highest visual quality): MAXCOMPRATIO, HIGHCOMP, MEDCOMP, LOWCOMP, and MAXINTEGRITY. Using the MAXCOMPRATIO value allows the image to be stored in the smallest amount of space, but may introduce visible aberrations into the image. Using the MAXINTEGRITY value keeps the resulting image more faithful to the original, but will require more space to store.
If the CompressionQuality operator is not supplied and the destination compression format supports compression quality control, the quality defaults to MEDCOMP.
The image processing operators supported by Visual Information Retrieval directly change the way the image looks on the display. The operators supported by Visual Information Retrieval represent only a fraction of all possible image processing operations, and the operators are not intended for users performing intricate image analysis.
The Cut operator is used to create a subset of the original image. The values supplied to the cut operator are the origin coordinates (x,y) of the cut window in the source image, and the width and height of the cut window in pixels. This operator is applied before any scaling that is requested.
If the Cut operator is not supplied, the entire source image is used.
The Scale operator enlarges or reduces the image by the ratio given as the value for the operator. If the value is greater than 1.0, then the destination image will be scaled up (enlarged). If the value is less than 1.0, then the output will be scaled down (reduced). A scale value of 1.0 has no effect, but is not an error. No scaling is applied to the source image if the Scale operator is not passed to the process( ) method.
There are two scaling techniques used by Visual Information Retrieval. The first technique is scaling by sampling and it is used only if the requested compression quality is MAXCOMPRATIO or HIGHCOMP, or if the image is being scaled up in both dimensions. This scaling technique works by selecting the source image pixel that is closest to the pixel being computed by the scaling algorithm and using the color of that pixel. This technique is faster, but results in a poorer quality image.
The second scaling technique is scaling by averaging, and it is used in all other cases. This technique works by selecting several pixels that are close to the pixel being computed by the scaling algorithm and computing the average color. This technique is slower but results in a better quality image.
If the Scale operator is not used, the default scaling value is 1.0. This operator may not be combined with other scaling operators.
The XScale operator is similar to the scale operator but only affects the width (x-dimension) of the image. The important difference between XScale and Scale is that with XScale, scaling by sampling is used whenever the image quality is specified to be MAXCOMPRATIO or HIGHCOMP, and XScale is not dependent on if the image is being scaled up or down.
This operator may be combined with the YScale operator to scale each axis differently. It may not be combined with other scaling operators (Scale, FixedScale,
The YScale operator is similar to the scale operator but only affects the height (y-dimension) of the image. The important difference between YScale and Scale is that with YScale, scaling by sampling is used whenever the image quality is specified to be MAXCOMPRATIO or HIGHCOMP, and YScale is not dependent on if the image is being scaled up or down.
This operator may be combined with the XScale operator to scale each axis differently. It may not be combined with other scaling operators (Scale, FixedScale,
The FixedScale operator provides an alternate method for specifying scaling values. The Scale, XScale, and YScale operators all accept floating-point scaling ratios, while the FixedScale (and MaxScale) operators specify scaling values in pixels. This operator is intended to simplify the creation of images with a specific size, such as thumbnail images.
The two integer values supplied to the FixedScale operator are the desired dimensions (width and height) of the destination image. The supplied dimensions may be larger or smaller (or one larger and one smaller) than the dimensions of the source image.
The scaling method used by this operator will be the same as used by the Scale operator in all cases. This operator cannot be combined with other scaling operators.
The MaxScale operator is a variant of the FixedScale operator that preserves the aspect ratio (relative width and height) of the source image. The MaxScale operator also accepts two integer dimensions, but these values represent the maximum value of the appropriate dimension after scaling. The final dimension may actually be less than the supplied value.
Like the FixedScale operator, this operator is also intended to simplify the creation of images with a specific size. The MaxScale operator is even better suited to thumbnail image creation than the FixedScale operator because thumbnail images created using the MaxScale operator will have the correct aspect ratios.
The MaxScale operator scales the source image to fit within the dimensions specified while preserving the aspect ratio of the source image. Because the aspect ratio is preserved, only one dimension of the destination image may actually be equal to the values supplied to the operator. The other dimension may be smaller than or equal to the supplied value. Another way to think of this scaling method is that the source image is scaled by a single scale factor that is as large as possible with the constraint that the destination image fits entirely within the dimensions specified by the MaxScale operator.
If the Cut operator is used in conjunction with the MaxScale operator, then the aspect ratio of the cut window is preserved instead of the aspect ratio of the input image.
The scaling method used by this operator is the same as used by the Scale operator in all cases. This operator cannot be combined with other scaling operators.
The following operators are supported only when the destination image file format is raw pixel, with the exception of the InputChannels operator, which is supported only when the source image data is raw pixel or a foreign image. It does not matter if the destination image format is set to raw pixel explicitly using the FileFormat operator, or if the raw pixel format is selected by Visual Information Retrieval automatically because the source format is raw pixel or a foreign image.
The ChannelOrder operator determines the relative order of the red, green, and blue channels (bands) within the destination raw pixel image. The order of the characters R, G, and B within the mnemonic value passed to this operator determines the order of these channels within the output. The header of the raw pixel image will be written such that this ordering is not lost.
For more information about the raw pixel file format and the ordering of channels in that format, see Appendix D.
The Interleaving operator controls the layout of the red, green, and blue channels (bands) within the destination raw pixel image. The three mnemonic values supported by this operator (BIP, BIL, and BSQ) force the output image to be band interleaved by pixel, band interleaved by line, and band sequential respectively.
For more information about the raw pixel file format, the interleaving of channels in that format, or the meaning of these interleaving values, see Appendix D.
The PixelOrder operator controls the direction of pixels within a scanline in a raw pixel image. The value Normal indicates that the leftmost pixel of a scanline will appear first in the image data stream. The value Reverse causes the rightmost pixel of the scanline to appear first.
For more information about the raw pixel file format and pixel ordering, see Appendix D.
The ScanlineOrder operator controls the order of scanlines within a raw pixel image. The value Normal indicates that the top display scanline will appear first in the image data stream. The value Inverse causes the bottom scanline to appear first.
For more information about the raw pixel file format and scanline ordering, see Appendix D.
As stated previously, the InputChannels operator is supported only when the source image is in raw pixel format or if the source is a foreign image.
The InputChannels operator assigns individual bands from a multiband image to be the red, green, and blue channels for later image processing. Any band within the source image can be assigned to any channel. If desired, only a single band may be specified, and the selected band will be used as the gray channel, resulting in a grayscale output image. The first band in the image is number 1, and the band numbers passed to the Input Channels operator must be greater than or equal to 1 and less than or equal to the total number of bands in the source image. Only the bands selected by the InputChannels operator are written to the output. Other bands are not transferred, even if the output image is in raw pixel format.
It should be noted that every raw pixel or foreign image has these input channel assignments written into its header block, but that this operator overrides those default assignments.
For more information about the raw pixel file format and input channels, see Appendix D.