|Oracle interMedia User's Guide and Reference
Part Number A88786-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:
Section D.1, "Common Concepts" 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 of 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-hand 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 supported only if other operators are present or if other conditions are met. For example, the compressionQuality operator is supported only if the compression format of the destination image is JPEG. Other operators require that the source or destination image be a Raw Pixel or 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 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, which is a mnemonic for the new file format name. The list of allowable values for the file format operator is shown in Table 8-1. Appendix B contains basic information about each file format, including its mnemonic (file format), 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 FileFormat operator is not used in the process( ) command string, interMedia 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.
The ContentFormat operator determines the format of the image content. The content means 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 are described in Table 8-1.
The content formats that specify gray[scale] or grey[scale] 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 formats with "8bit" support 256 shades of gray. There is no distinction between grayscale and greyscale.
The content formats that specify RGB store pixel data as Red, Green, Blue triplets. The number of bits specified will determine how many colors are supported. If 8 or fewer bits are specified, most formats will default to a LUT representation. Otherwise, DRCT (direct) will be used.
The content formats that specify LUT use a color lookup table to support various colors. The "1bitlut" format allows 2 distinct colors, "4bitlut" supports 16 unique colors, and "8bitlut" supports 256 colors.
The content formats that specify DRCT store the color values directly in the pixel data as a Red, Green, Blue triplet or gray value. The total number of bits of data is specified separately 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. Not all bits are used by some image formats. Note that currently most formats allow only 8-bit gray or 24-bit RGB.
The monochrome content format allows only black and white to be stored, with no gray shades in between.
If the ContentFormat operator is not passed to the process( ) method, then interMedia 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 supported only by one file format.
The supported values for the CompressionFormat operator are listed in Table 8-1.
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 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 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 typically by discarding unimportant details. Because this format is optimized for compressing photographic and similarly noisy 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 interMedia.
The DEFLATE compression type is ZIP Deflate and is used by PNG image file formats. The DEFLATE-ADAM7 compression format is interlaced ZIP Deflate and is used by PNG image file formats. The ASCII compression type is ASCII encoding and the RAW compression type is binary encoding and both are for PNM image file formats.
If the CompressionFormat operator is not specified, then interMedia will use the default compression format; often this default is "None" or "No Compression."
If the CompressionFormat operator is not specified and the file format of the destination image is different from that of the source image, then a default compression format will be selected depending on the destination image file format. This default compression 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 therefore is not currently supported for any compression format except JPEG.
The CompressionQuality operator accepts integer values between 1 (lowest quality) and 99 (highest quality) in addition to 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 will default to MEDCOMP for medium quality.
The image processing operators supported by interMedia directly change the way the image looks on the display. The operators supported by interMedia represent only a fraction of all possible image processing operations, and 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, and 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 interMedia. The first technique is "scaling by sampling" and 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 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 cannot 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 is not dependent on whether 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, MaxScale).
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 is not dependent on whether 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, MaxScale).
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. MaxScale 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. MaxScale is even better suited to thumbnail image creation than the FixedScale operator because thumbnail images created using MaxScale 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 fit 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 or BMPF (ScanlineOrder operator only), with the exception of the InputChannels operator, which is supported only when the source image is Raw Pixel or a foreign image. It does not matter if the destination image format is set to Raw Pixel or BMPF explicitly using the FileFormat operator, or if the Raw Pixel or BMPF format is selected by interMedia automatically because the source format is Raw Pixel, BMPF, 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 determine the order of these channels within the output. The header of the Raw Pixel image will be written such that this order is not lost.
For more information about the Raw Pixel file format and the ordering of channels in that format, see Appendix E.
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 E.
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 E.
The ScanlineOrder operator controls the order of scanlines within a Raw Pixel or BMPF 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 BMPF, ScanlineOrder = inverse is the default and ordinary value.
For more information about the Raw Pixel or BMPF file format and scanline ordering, see Appendix E.
As stated in Section D.4, 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 one, and less than or equal to the total number of bands in the source image. Only the bands selected the by 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 E.
The Dither operator controls how dithering is done. Dithering happens whenever needed to accomodate the user's request for a change in content format; the Dither operator can be used to change how the dithering happens.
Dithering is the process of approximating colors that do not actually exist in an image by mixing pixels of other colors in a ratio that fools the eye into seeing the approximated color. interMedia will dither images when required to accomodate a requested ContentFormat that can specify fewer colors than are present in the input image, or when a change in ContentFormat is required to store an image in the requested FileFormat. The Dither operator can be used to select by value which of the available dithering algorithms is used to perform this approximation.
The ORDEREDDITHER algorithm is a fast method for approximating colors based on a conversion color table. The resulting image often contains areas of alternating pixel values, which may be objectionable in some cases.
The ERRORDIFFUSION algorithm produces a more accurate destination image by diffusing the error caused by changing one pixel value into neighboring pixels. The resulting image is usually of higher quality than the ordereddither algorithm, but this operator is slower and may produce poor results with certain images."
The Page operator selects a page from a multipage file and can only be used with TIFF file format images.
The Tiled operator forces the output image to be tiled and can only be used with TIFF file format images.