OP_RORE

OP_RORE: Basic Sequential JPEG Transformations

See the REORIENT:OP_RORE section for additional information.

OP_RORE is used for basic transformations of sequential JPEG images without requiring decompression followed by recompression. These transformations include:

Rotating and/or horizontally inverting the image.
Cropping the image.
Re-quantizing the image.
Joining two images, either up/down, side/side, or by insertion at a coordinate.
Changing the image file format to JFIF, Exif, or PIC2.
Changing to optimum Huffman encoding, default Huffman encoding, or "ELS" encoding.
Deleting or inserting comments and JPEG application marker (APP marker) data.
Establishing regions of interest within the image, each with specific quantization parameters.
Converting color to grayscale images, or grayscale to color images.
Adding or replacing IPTC metadata.

In addition, more advanced transformations are possible by providing OP_RORE with mapping tables, on a per component basis, which translate the sample values of the decompressed image prior to re-compression. These can be used for advanced non-linear brightness and contrast adjustments, as well as gamma correction, or a combination of all of these.

OP_RORE can also delete or insert comments and APP marker data in lossless JPEG images when the PF_NoImageChanges flag is set in u.ROR.PicFlags.

Also set PF_NoImageChanges for improved performance when a sequential JPEG image is not being rotated and the Huffman encoding is not to be changed. Otherwise the compressed image data will be losslessly recoded.

JpegType determines the format of the output images. Set JT_Raw for normal sequential JPEG output and set JT_RAW for all lossless JPEG output. Set JT_EXIF for Exif-format output. Set JT_PIC2 for Pegasus' PIC2-format output. For JT_EXIF output, set at least bit 1 in u.ROR.AppsToKeep so any input image Exif information is written to the output Exif image.

Set PF2_UseISOStandardHuffmanTbls in u.ROR.PicFlags2 to use default Huffman table encoding instead of computing and using the optimum Huffman codes for the image. Set PF2_OmitISOStandardHuffmanTbls in u.ROR.PicFlags2 to create a non-standard JPEG image that omits the Huffman tables from the output image. For example, Motion JPEG (MJPEG) frames are JPEG still images that are coded using the default Huffman tables for better performance during compression, and the tables are omitted from the frame to save space in each frame. In other applications, you would ordinarily not set either of these flags so the output image is as small as possible without introducing more loss.

For PIC2 format output images, set PF_ElsCoder in u.ROR.PicFlags to use the ELS entropy coder instead of Huffman coding. If this is set, the HuffmanTbls flags described above shall be ignored.

This opcode allows the image data to be encrypted using a key provided by the application. See details in the section describing the OP_RORE OutputKeyField field.

Editing Image Comments

Unless u.ROR.RemoveComments bit 0 is set, input image comments are returned in PIC2List as P2PktComment packets after REQ_INIT (see pic2file.h). The P2PktComment packets in PIC2List when REQ_EXEC is called are written to the output image. So between REQ_INIT and REQ_EXEC, input image comments can be deleted and new or modified comments can be inserted.

Unless bit 1 of u.ROR.RemoveComments is set, or there is already a comment beginning with the text "Accusoft" or "Pegasus Imaging" in PIC2List when REQ_EXEC is called, or PF_NoImageChanges is set, an 'Accusoft Corporation' comment will be added to the output image.

Editing Image APP Marker Data

A JPEG image can include binary application metadata that is not required to decompress the image - although it might be important to the most accurate reconstruction of the image in some circumstances - and whose format and meaning depends on the application writing and reading the data. This application data is embedded in 'APP' markers, and the markers are numbered APP0 through APP9 and APPA through APPF (0 through 15 in hexadecimal). For each marker type, there can be any number of instances of the marker in the JPEG image.

If a bit in the range 0 through 15 is set in u.ROR.AppsToKeep, then any correspondingly numbered input image APP markers are returned in PIC2List P2PktRawData packets after REQ_INIT with RawDescription 'APPn' where n is the hexadecimal APP marker number (see pic2file.h). Any P2PktRawData packets with a RawDescription like this that are in PIC2List when REQ_EXEC is called are written to the output image. So between REQ_INIT and REQ_EXEC, input image APP marker data can be deleted and new or modified APP marker data can be inserted.

Unless bit 16 is set in u.ROR.AppsToKeep, or there is already an APP0/JFIF marker in PIC2List when REQ_EXEC is called, or PF_NoImageChanges is set, an APP0/JFIF marker will be added to the output image.

Unless bit 17 is set in u.ROR.AppsToKeep, or there is already an APP1/PIC marker win PIC2List when REQ_EXEC is called, or PF_NoImageChanges is set, an APP1/PIC marker with Pegasus application data will be added to the output image.

Editing Exif Image Data

If bit 1 is set in u.ROR.AppsToKeep, then input image APP1/Exif marker information is returned in P2PktTiffTag packets in PIC2List after REQ_INIT (see pic2file.h). If the output format is JT_EXIF, then any P2PktTiffTag packets in PIC2List when REQ_EXEC is called are written to the output image. The Location field in the P2PktTiffTag packet is LOC_PRIMARYIMAGEIFD for Exif primary image information, LOC_THUMBNAILIFD for Exif thumbnail image information, and LOC_EXIFIFD, for other Exif meta data in the Exif Image File Directory (IFD). If the output format is JT_EXIF, then between REQ_INIT and REQ_EXEC input image Exif information can be deleted and new or modified Exif information can be inserted.

Exif image Kodak Picture CD information sometimes occurs in an APP3/Meta marker. If bit 3 is set in u.ROR.AppsToKeep, that information is also returned in P2PktTiffTags. The Location field in the P2PktTiffTag packet is LOC_APP3IFD for this information.

Editing IPTC Data

If bit 13 is set in u.ROR.AppsToKeep, then input image APP13/IPTC marker information is returned in P2PktIPTCDataSet packets in PIC2List after REQ_INIT (see pic2file.h). Only the first IPTC Resource Block encountered is returned. If an IPTC Resource Block spans multiple APP13 marker segments, the IPTC Resource Block will be ignored and not returned in the PIC2List. IPTC information can then be edited as follows:

IPTC data can be edited by adding, deleting, or modifying IPTC data in the PIC2List. See the PIC2List IPTCDataSet Packet Functions. Any P2PktIPTCDataSet packets in PIC2List when REQ_EXEC is called are merged into the APP13 marker segment and written to the output image.
When IPTC data is edited, the following processing takes place:
- Multiple IPTC packets are combined into a single IPTC resource block.
- Duplicate IPTC data is removed.
- When possible, mandatory IPTC data is added if it is not already present.
- XMP data present in an APP13 segment will be removed.
- XMP data present in an APP1 segment will be removed.
- Caption Digest data present in an APP13 segment will be removed.
The IPTC data that is present in the PIC2List as P2PktIPTCDataSet packets always takes precedent over any IPTC data that may be embedded in APP13 marker segments. For example:
- If the PIC2List contains an APP13 segment that does not contain IPTC data, but IPTC data is present as P2PktIPTCDataSet packets, then that IPTC data will be added to the APP13 segment.
- If the PIC2List contains an APP13 segment that does contain IPTC data, but IPTC data is not present as P2PktIPTCDataSet packets, then the IPTC data will be removed from the APP13 segment.
- If the PIC2List contains an APP13 segment that does contain IPTC data, and IPTC data is present as P2PktIPTCDataSet packets, but this data differs from the IPTC data in the APP13 segment, then IPTC data in the APP13 segment will be replaced with the IPTC data in the P2PktIPTCDataSet packets.
If multiple APP13 marker segments are provided, the opcode will attempt to combine the segments into a single APP13 segment. If the single APP13 segment exceeds the maximum allowed segment size, it will be divided into smaller segments as needed.
It is possible, though unlikely, for an IPTC packet to be constructed by this opcode that spans multiple APP13 segments. If this happens, this IPTC packet will not be able to be read by this opcode or by the OP_S2D, OP_SE2D, or OP_SE2DPLUS opcodes.

Sequential JPEG Image Requantization

Input images may be requantized using several methods (see REORIENT:OP_RORE for detail):

A quantization table may be supplied by the application. Intervals are specified for 64 frequency coefficients, one set for Luminance, one set for the chrominance Cb channel, which may be shared by the Cr channel, or optionally, a third set may be provided for the Cr channel. Set u.ROR.Requantize to the desired mode and provide the Q-table address in u.ROR.QTableReq. One of three modes may be specified in Requantize:

a. Use a value that is an odd multiple of the existing value and closest to the value in Q-table.

b. Use the value in Q-table if larger than the existing value.

c. Use the value in the Q-table.
A compression factor (0 to 255) may be specified for the luminance channel and the chrominance channel. OP_RORE will determine the quantization. Use u.ROR.LumFactorReq and ChromFactorReq to specify the factors. These fields will be ignored if a Q-table address is provided in u.ROR.QTableReq. Set u.ROR.Requantize to the desired mode. One of three modes may be specified in Requantize:

a. Use a value that is an odd multiple of the existing value and closest to the value calculated using the compression factor.

b. Use the value calculated using the compression factor if larger than the existing value.

c. Use the value calculated using the compression factor regardless of the value in the original image.

It is possible that a Requantization using method c (above), can result in an output image with out-of-range DC coefficients with respect to the JPEG specification. This can occur if the original input image was compressed by an implementation that computes out-of-range pre-quantized DC values and if the application chooses a quantization step (via a very high quality luminance quality factor, i.e., 0) that results in a quantization value that remains out-of-range. In this case, OP_RORE will complete the requantization, but will return a warning status, i.e., RES_DONE, with a Status of ERR_BAD_DATA. In addition, u.ROR.PicFlag2 will contain the flag PF2_DcCoeffOutOfRange set to true.
The image may be subdivided into multiple regions whereby the quantization may be specified for each region using a set of 2 or more (up to MAX_REGIONS) REGION_INFO structures. Each region may be assigned to a specific REGION_INFO structure. For each of the REGION_INFO structures, the application may provide a set of Q-tables , or a set of Luminance and Chrominance compression factors (compression factors greater than 255, where up to 2 bytes are allowed). See REORIENT:OP_RORE for additional detail. The REGION_INFO structures are concatenated such that the first one becomes index 0 followed by ascending index numbers. A RegionMap is then appended to the set of REGION_INFO structures. The map consists of an array of bytes in row-scan order whereby each byte corresponds to an 8x8 block of image samples. The value in each byte assigns the 8x8 block to one of the REGION_INFO structures. Use u.ROR.NumRegions to specify the number of REGION_INFO structures being used. Use u.ROR.RegionInfo to point to the first REGION_INFO structure. Use u.ROR.RegionMapOffset to indicate the offset of the RegionMap from the start of the REGION_INFO structures. Use u.ROR.RegionMapWidth and RegionMapHeight to specify the dimensions of the map. Each dimension must be >= (width+7)/8 and (height+7)/8.

Regions are not compatible with rotation, join, or other requantization operations.
If two images are being Joined (see Sequential JPEG Image Joining below) the quantization of the joined image may be determined by the application using either the Q-table method above or the Luminance/Chrominance compression factor specification above. In this case, the user should set the JF_UseRequestedQuantization along with the JF_DoJoin bits in u.ROR.JoinFlags.

Sequential JPEG Image Cropping

Set the F_Crop flag in the PIC_PARM Flags field to crop the image according to CropXoff, CropYoff, CropWidth, and CropHeight.

For JT_EXIF output, be sure to set u.ROR.ExifThumbnailToMake on supported platforms so a correspondingly cropped thumbnail is written to the output image. (See the description of the u.ROR.ExifThumbnail field in the REORIENT:OP_RORE discussion for other platforms.)

A JPEG image is compressed in MCU (minimum-coded-unit) blocks. An MCU block for an image component is always 8x8 component samples, but if the component is subsampled, these samples correspond to up to more than 8x8 pixels. The MCU block is 8x8 for SS_111, 16x8 for SS_211, 16x16 for SS_411, and 8x16 for SS_411v.

If not at an MCU boundary, CropXoff, CropYoff, CropWidth, or CropHeight are trimmed or padded to the above or below MCU boundary depending on the value of u.ROR.Pad and depending on any rotation that has been specified.

Sequential JPEG Image Rotation

Set the VisualOrient field in PicParm to O_r90, O_r180, or O_r270 to rotate the image right the corresponding number of degrees. Also set the O_inverted bit to invert the image top-for-bottom after any rotation. The O_r90_in, O_r180_in, O_r270_in constants have the O_inverted bit set.

For JT_EXIF output, be sure to set u.ROR.ExifThumbnailToMake on supported platforms so a correspondingly rotated thumbnail is written to the output image. (See the description of the u.ROR.ExifThumbnail field in the REORIENT:OP_RORE discussion for other platforms.)

On the right edge, and bottom edge, of the image, the blocks may extend past the edge of the image, but since the image width and height are known, the corresponding pixels past the edge will be discarded. However, when rotating the image so that the original right edge or bottom edge becomes the new top edge or left edge, there is no way to signal these extra pixels. In that case u.ROR.Pad determines whether the width or height will be padded or trimmed before rotation to an MCU boundary in these cases.

Sequential JPEG Image Joining

Two images residing in the GetQueue may be joined. The user can select whether the images are joined:

Top-to-bottom or side-by-side
By inserting the second image at a specified coordinate of the first image

Use the u.ROR.JoinFlags to specify the parameters for the join operation:

Set JF_DoJoin to enable the join operation.
Set JF_LeftRight to do a side-by-side join instead of the default top-bottom join.
Set DF_Insert to cause one image to be inserted into the other at the coordinates specified by CropXoff and CropYoff in the PicParm structure.
The default join operation is to place the first image in the buffer on top or left or to insert the first. Set JF_SecondOnTopLeftInsert if the second image in the buffer is to go on top, or left, or to insert the second image into the first.

In addition, if an image is being joined via insertion, the user can specify how much of the luminance comes from the original image vs how much comes from the inserted image. A similar specification can be made for the chrominance. Use u.ROR.InsertTransparencyLum and InsertTransparencyChrom. Values of 0 to 256 are used, where 0 means the inserted image determines the luminance/chrominance, and 256 means the original image determines the luminance/chrominance. Values in between can be used to vary the degree of blending.

Quantization and subsampling for the joined set is determined as follows:

The default join operation will cause the quantization as well as the subsampling method of the first image to determine the quantization and subsampling method for the joined set.
Set JF_UseSecondQuantization to allow the second image to determine the quantization of the joined set.
Use JF_UseSecondSubsampling to use the subsampling method of the second image for the joined set.
Specify the quantization for the joined set (as described in the Sequential JPEG Image Requantization section above). Set JF_UseRequestedQuantization to perform the join using a Q-table or specified compression factors as outlined above.

Additional Transformations

The user can specify additional transformations. These include:

Individual brightness adjustments for the luminance (Y), and chrominance (Cb and Cr) components. Specify the adjustments by setting u.ROR.YShift, u.ROR.CbShift, u.ROR.CrShift to a value from 1 to 255. (0 means no transformation).
Individual contrast adjustments for the luminance (Y), and chrominance Cb and Cr channels. Specify the adjustments by setting u.ROR.YScale, u.ROR.CbScale, u.ROR.CrScale to a value from 1 to 255. (0 means no transformation).
The luminance (Y), chrominance (Cb, and/or Cr) channels can be individually translated by providing mapping tables to OP_RORE. Translations could include brightness adjustment, contrast adjustment, gamma correction, or a combination of all of these. The translations can be non-linear, and are therefore applied to the component samples in the spatial domain. Thus, the values in the tables correspond to an 8-bit mapping value for each possible component-sample value. For each of the components that is to be translated, the application can specify a pointer to an 8-bit, 256 entry mapping table using u.ROR.MapY, u.ROR.MapCb, u.ROR.MapCr. If any of these pointers are specified, the corresponding channel's Shift and Scale values are ignored.
Color images may be converted to gray images by setting u.ROR.PicFlags, PF_ConvertGray. Grayscale images may be converted to color images (replicated components) by setting u.ROR.PicFlags, PF_ConvertToColor.