PICTools Programmer's Reference
REORIENT
Operation Structures > REORIENT

REORIENT: OP_RORE

The REORIENT structure definition is used by OP_RORE.

 
Copy Code 
typedef struct {
   DWORD                          Reserved0;
   BYTE PICHUGE*                  RegionInfo;
   BYTE PICHUGE*                  QtableReq;
   BYTE PICHUGE*                  ExifThumbnail;
   BYTE PICHUGE*                  MapY;
   BYTE PICHUGE*                  MapCb;
   BYTE PICHUGE*                  MapCr;
   BYTE PICHUGE*                  Reserved7;
   BYTE PICHUGE*                  Reserved8;
   PICFLAGS                       PicFlags;
   PICFLAGS                       PicFlags2;
   LONG                           Pad;
   LONG                           KeepColors;
   LONG                           LumFactorReq;
   LONG                           ChromFactorReq;
   LONG                           Requantize;
   LONG                           RequantizationDone;
   LONG                           AppsToKeep;
   LONG                           RemoveComments;
   JPEG_TYPE                      JpegType;
   BYTE                           OutputKeyField[8];
   LONG                           JoinOffset;
   DWORD                          JoinFlags;
   DWORD                          InsertTransparencyLum;
   DWORD                          InsertTransparencyChrom;
   LONG                           NumRegions;
   DWORD                          RegionMapOffset;
   WORD                           RegionMapWidth;
   WORD                           RegionMapHeight;
   SHORT                          YShift;
   SHORT                          YScale;
   SHORT                          CbShift;
   SHORT                          CbScale;
   SHORT                          CrShift;
   SHORT                          CrScale;
   DWORD                          ExifThumbnailLen;
   THUMBNAIL                      ExifThumbnailToMake;
   LONG                           MaxRqtblSize;
} REORIENT;

typedef struct {
   WORD                           LumFactor;
   WORD                           ChromFactor;
   LONG                           NumTables;
   WORD                           QTbls[1];
} REGION_INFO;

REORIENT Fields:

Name Description

Reserved0

This field is not currently used and must be set to 0.

RegionInfo

Allocated by the user. NULL unless specifying regions-of-interest. Refer to REGION_INFO structure above. Points to a concatenation of NumRegions (see below) REGION_INFO structures, which is followed by the RegionMap (whose offset from RegionInfo is specified by RegionMapOffset). RegionMap is an array of bytes corresponding to the 8x8 blocks in the image in row-scan order. The value in each byte specifies a region number from 0 through NumRegions – 1. For each region number, REGION_INFO specifies the quantization parameters for the 8x8 blocks assigned to it.

QtableReq

Allocated by the user. Ignored unless Requantize (below) is set to 1, or JoinFlags indicates that 2 images are to be joined, and that quantization information is being supplied by the user via Q-table. Points to a Q-table (quantization table) consisting of 64 bytes for the luminance channel, and if the image is not grayscale, followed by 64 bytes for Cb. If the 128 bytes is followed by a zero byte, it is assumed that the same quantization is used for Cr, otherwise the next 64 bytes is used for Cr. Thus, for grayscale images, the table is 64 bytes, and for color, the table is either 129 bytes or 192 bytes long.            

ExifThumbnail

If JpegType is JT_EXIF, and ExifThumbnailLen is not 0 and ExifThumbnail is not NULL and ExifThumbnailToMake is THUMB_NONE, then this is a pointer to a buffer of ExifThumbnailLen bytes containing a thumbnail image to be embedded in the output Exif image. In that case, be sure to delete all input image LOC_THUMBNAILIFD P2PktTiffTag packets in PIC2List before REQ_EXEC and be sure to insert appropriate output image LOC_THUMBNAILIFD P2PktTiffTag packets into PIC2List before REQ_EXEC. The thumbnail image is copied directly to the output image and without any OP_RORE transformations.

MapY

Allocated by the user. Points to an 8-bit, 256-entry translation table for the Y component that is normally used to apply gamma correction and/or brightness and/or contrast adjustment. If used, takes precedence over YScale and YShift.

MapCb

Allocated by the user. Points to an 8-bit, 256-entry translation table for the Cb component that is normally used to apply gamma correction and/or brightness and/or contrast adjustment. If used, takes precedence over CbScale and CbShift.                          

MapCr

Allocated by the user. Points to an 8-bit, 256-entry translation table for the Cr component that is normally used to apply gamma correction and/or brightness and/or contrast adjustment. If used, takes precedence over CrScale and CrShift.

Reserved7

Reserved8

These fields are not currently used and must be set to 0.

PicFlags
Value Meaning

PF_EOIFound

This flag is set by OP_RORE if a JPEG image EOI marker was encountered while processing the input JPEG image.

PF_ConvertToColor

Set this flag to convert an input JPEG one-component grayscale image to an output JPEG three-component color image.

PF_ConvertGray

Set this flag to convert an input JPEG three-component color image to an output JPEG one-component grayscale image.

PF_BigEndian

If JpegType is JT_EXIF, set this flag if the EXIF Image File Directories' (IFD's) data should be in big-endian (Motorola) order with a 'MM' signature instead of the default little-endian (Intel) order with a 'II' signature.

PF_NoImageChanges

Set this flag to ignore all options that would require the input compressed data to be re-processed.  When this flag is set, the JpegType can be changed, comments and APP markers and Exif tag data can be deleted or inserted, but the input compressed data itself is unconditionally copied directly to the output without change.

PF_YieldPut

Set this flag for periodic returns of RES_PUT_DATA_YIELD from Pegasus while processing the input image.

PicFlags2
Value Meaning

PF2_UseISOStandardHuffmanTables

Use the ISO standard Huffman tables for encoding instead of computing and using the optimum Huffman tables.

PF2_OmitISOStandardHuffmanTables

If PF2_UseISOStandardHuffmanTables is set, then do not emit the Huffman tables to the output image. MJPEG video frames are JPEG still images that, among other things, use the ISO standard Huffman tables but omit them from the image data.

PF2_ExifInputIsBigEndian

Set when REQ_INIT returns RES_DONE if the input image is Exif with big endian tags, and u.ROR.AppsToKeep bit 1 is set, and u.ROR.JpegType is JT_EXIF.  Then you can set PF_BigEndian for the output file based on whether or not PF2_ExifInputIsBigEndian is set and you'll get the same Exif tag endian for output as you had for input.

PF2_DcCoeffOutOfRange Set when Requantize (below) is set to 3, and when the LumFactorReq is set to a value that is low enough (high quality) to produce out-of-range DC Coefficients for images where the original unquantized coefficients are out-of-range.

Pad

If rotating (Orientation != O_normal), with reference to the image width and height before any rotation:

0

Trim width and height to MCU boundary if needed

1

Pad width and height to MCU boundary if needed

2

Pad width and trim height to MCU boundary if needed

3

Trim width and pad height to MCU boundary if needed

Padding or trimming of width (height) may be needed when the original right edge (bottom edge) of the image is rotated/inverted to become the left or top edge of the image.

KeepColors

0

Discard an input image color table.

1

Write an input image color table to an output image APP1/PIC marker.

LumFactorReq

Ignored unless Requantize (below) is set to 1 or higher, or JoinFlags indicates that 2 images are to be joined and that quantization information is being supplied by the user, and QtableReq is NULL. Explicitly specifies compression factor (0 to 255) for the luminance channel.

ChromFactorReq

Ignored unless Requantize (below) is set to 1 or higher, or JoinFlags indicates that 2 images are to be joined and that quantization information is being supplied by the user, and QtableReq is NULL. Explicitly specifies compression factor (0 to 255) for the chrominance channels.

Requantize

0

Do not requantize.

1

Change the quantization interval size for each DCT coefficient to the odd multiple of the existing value that is nearest to the value in QTableReq if this is present, or to the one implied by LumFactorReq and ChromFactorReq otherwise. This produces the same quantized DCT coefficients that would have been obtained starting from the raw image using this quantization.

2

For each DCT coefficient, use requested quantization value when larger than the one in input file, otherwise use the one in input file. 

This does not produce same JPEG file as if we had started with the raw image using this quantization!

3

For each DCT coefficient, always use requested quantization.

RequantizationDone

Set by OP_RORE.  If 0, no change to quantization was made. If 1, some change was made to the quantization.

AppsToKeep

When any of the bits 0 through 15 are set, then the corresponding input image JPEG APP markers APP0 through APP15 are not returned in PIC2List and therefore they will not be written to the output file.  Otherwise, they are returned in PIC2List after REQ_INIT and any that remain in PIC2List at REQ_EXEC will be written to the output image.

If bit 16 is set, then an APP0/JFIF marker is not added to the output image.

If bit 17 is set, then an APP1/PIC marker is not added to the output image.

Bit 1 must be set to return input image Exif data in PIC2List after REQ_INIT and if it is to be written to the output file.

Bit 3 should also be set if the input image is Exif and the output image is to be Exif because some vendors, for example Kodak, place additional Exif-style meta-data in APP3 markers.

Adobe puts information in APP 13 and APP 14 markers.

RemoveComments

If bit 0 is set, then input image comments are not returned in PIC2List, therefore input image comments will not be written to the output image.  Otherwise input image comments are returned in PIC2List after REQ_INIT and those that remain in PIC2List at REQ_EXEC will be written to the output image.

If bit 1 is set, then an "Accusoft Corp." comment is not added to the output image.  Otherwise, an "Accusoft Corp." comment is written to the output image unless a comment in PIC2List at REQ_EXEC begins "Accusoft".

JpegType

Set by user to indicate required output format.

Value

Meaning

JT_PIC2

PIC2 format

JT_RAW

JFIF-compliant JPEG

JT_EXIF

EXIF-compliant JPEG

OutputKeyField

If any byte is not 0, then this is a key used to scramble the output image in such a way that it cannot be easily viewed or reprocessed without supplying the same 8-byte key value.

JoinOffset

If a Join is specified in JoinFlags, this is the offset from the start of the Get Queue to the second image in the Get Queue to be joined to the first. If set to zero, OP_RORE will scan the Get Queue to find the second image. The Get Buffer must be large enough to hold all of the first image and at least up to the first scan header of the second image.

JoinFlags

These flags are set to cause two images to be joined:

Value Meaning

JF_DoJoin

Set if two images are to be joined. All other Join flags are ignored if this is not set. Join is not allowed unless Requantize is zero, F_Crop is not set in PicParm Flags, and VisualOrient is zero in PicParm.

JF_LeftRight

Set if images are to be joined left-right rather than top-bottom (the default is top-bottom).

JF_UseSecondSubsampling

Set if subsampling is to be taken from second image in Get buffer; default is from first image. 

If the two images do not have the same subsampling, some inverse and forward DCT operations are required on the chrominance components.

JF_UseRequestedQuantization

Set if quantization of joined image is to be specified by the user; either by supplying a non-null pointer for QTableReq above, or, if that is null, OP_RORE will use LumFactorReq and ChromFactorReq above.

JF_UseSecondQuantization

Ignored if JF_UseRequestedQuantization is set. If set to 1, the quantization is to be taken from second image in the Get Buffer. The default is to take quantization from the first image.

If the joined image quantization is different from the input quantization for either image, some new error may be introduced, larger than would have been expected from the indicated quantization table. Even when an output quantization interval is larger than the input one, the error in a coefficient is no longer guaranteed to be no more than half of the output quantization interval size. This has to do with rounding.

JF_Insert

Set if one image is to be inserted into the other rather than placed side-by-side. The first image in the Get buffer will be inserted in the second image unless the flag JF_SecondOnTopLeftInsert is set. If JF_Insert is set, then CropXoff and CropYoff in the PIC_PARM structure must be set. This gives the location of where to put the upper left corner of the inserted image. This will be rounded down to the nearest multiple of MCU width and height of the surrounding image. The width and height of the inserted image will be rounded down to a multiple of MCU width and height, and made to fit in the surrounding image if too large. Also if JF_Insert is set, InsertTransparencyLum and InsertTransparencyChrom must be given a value between 0 and 256 inclusive.

JF_SecondOnTopLeftInsert

Set if second image in Get buffer goes on top or left or is inserted into first. Default is first on top or left or first is inserted into second.

InsertTransparencyLum

Used when joining images by inserting (JF_Insert set). A value between 0 and 256, inclusive, which determines how much of the luminance comes from the pixels of the original image when inserting an image.  A value of 0 means the INSERTED image determines the luminance in its region. A value of 256 means the original image completely determines the luminance.

InsertTransparencyChrom

A value between 0 and 256, inclusive, which determines how much of the chrominance comes from the pixels of the original image when inserting an image. A value of 0 means the INSERTED image determines the chrominance in its region. A value of 256 means the original image completely determines the chrominance.

NumRegions

The number of RegionInfo structures that are allocated for defining the quantization of regions from the RegionMap by assigning the regions to a particular RegionInfo structure (1 to MAX_REGIONS).

RegionMapOffset

The offset from the start of the first RegionInfo structure to the RegionMap.

RegionMapWidth

The width of the region map where each byte specifies the assigned RegionInfo for an 8x8 block of the image. Must be >= (image_width + 7)/8.  Any extra columns are skipped over.

RegionMapHeight

The height of the region map where each byte specifies the assigned RegionInfo for an 8x8 block of the image. Must be >= (image_height + 7)/8. Any extra rows are ignored.

YShift

0 if not transforming luminance. -256 ... 255 otherwise. YShift represents increase (decrease if < 0) in brightness for entire image.

YScale

0 if not transforming luminance. -128 ... 127 otherwise. YScale represents increase (decrease if < 0) in contrast for the entire image. Usually the contrast needs to be increased if the brightness is increased, so these two are often used together.

CbShift

0 if not transforming chrominance (Cb). -256 ... 255 otherwise. Represents increase (decrease if < 0) in brightness for Cb.

CbScale

0 if not transforming chrominance (Cb). -128 ... 127 otherwise. Represents increase (decrease if < 0) in contrast for Cb.

CrShift

0 if not transforming chrominance (Cr). -256 ... 255 otherwise. Represents increase (decrease if < 0) in brightness for Cr.

CrScale

0 if not transforming chrominance (Cr). -128 ... 127 otherwise. Represents increase (decrease if < 0) in contrast for Cr.

ExifThumbnailLen

See ExifThumbnail. If JpegType is JT_EXIF and ExifThumbnailToMake is THUMB_NONE, and ExifThumbnail is not NULL, then ExifThumbnailLen is the length in bytes of the image pointed to by ExifThumbnail.

ExifThumbnailToMake

In supported platforms (Win32/x64 and Linux only at this time), and if a required PICTools sequential JPEG decompressor and compressor are available, then this can be set to THUMB_4, THUMB_4F, THUMB_16, THUMB_64, or another value not equal to THUMB_NONE and a corresponding thumbnail for the output image is created and written to the output image.  The thumbnail is created by decompressing the image to the requested thumbnail size, then recompressing to create the thumbnail.  If a value 5 or greater is specified, then a thumbnail is created whose maximum dimension is ExifThumbnailToMake.  In this case, the image is decompressed to the next larger thumbnail size, then shrunk to the requested size before recompression and the OP_ZOOM or OP_ZOOM2 opcodes must be available.

MaxRqtblSize

Not used for OP_RORE. 

REGION_INFO Fields:

Name Description

LumFactor

Ignored if NumTbls (below) is non-zero or 255. Explicitly specifies compression factor (0 to 65535) for the luminance components.

ChromFactor

Ignored if NumTbls (below) is non-zero or 255. Explicitly specifies compression factor (0 to 65535) for the chrominance components.

NumTbls

Number of quantization tables being specified. 0 means use LumFactor and ChromFactor. 255 means do not change quantization for this region. Otherwise, 1 for Grayscale images, 2 if a single table is shared by the two chrominance components, 3 if each chrominance component uses a unique table.

QTbls[1]

If NumTbls is non-zero and not 255, there should be NumTbls * 64 words here comprising the quantization tables.

 

 

©2022. Accusoft Corporation. All Rights Reserved.

Send Feedback