PICTools Programmer's Reference
OP_S2D, OP_SE2D, OP_SE2DPLUS
Operations > OP_S2D, OP_SE2D, OP_SE2DPLUS

OP_S2D, OP_SE2D, OP_SE2DPLUS: Expand sequential JPEG to DIB or RAW

This opcode contains optimizations specific to Pentium 3 / 4 processors that may need to be disabled using the PF2_P3OptDisable flag. See the section entitled "Intel P 3 / 4 Specific Notes".

See the DIB_OUTPUT: OP_S2D section for additional information.

DICOM YBR_FULL_422 Output from Color JPEG Image Input

To decompress a color JPEG input image to a YBR_FULL_422 decompressed output image: 

DICOM YBR_PARTIAL_422 Output From Color JPEG Image Input

To decompress a color JPEG input image to a YBR_FULL_422 decompressed output image:

Color JPEG Input Image

A. Creating a 16, 24 or 32 bit color DIB

B. Creating a 4- or 8-Bit Color DIB with Optimum Colors

C. Creating a 4- or 8-Bit Color DIB with an External Palette

D. Creating a 4- or 8-Bit Gray Scale DIB

E.     Creating a YUV Output Image

CMYK Color JPEG Input Image

CMYK JPEG images may only be decompressed to interleaved CMYK.

Gray Scale JPEG Input Image

A. Input is 12-bit gray scale JPG

1.    Create a 12-bit image
2.    Create an 8-bit image

Notes - Using J2D.GrayMap12Bit

The lookup table J2D.GrayMap12Bit may be constructed to map the 12 bits to either a 16-bit or 8-bit field in any way desired. The function BuildTranslationTable12 which is included in the test program jetest.c illustrates this for a choice of brightness, contrast, gamma-correction, output bits of precision, and effective input bits of precision.  Ordinarily the effective input bits of precision would be 12, since the data was supposedly 12-bit.  But the user may know, for example, that the original data was really 10 bits right-justified.  The jpeg decompressor does not know this, and since it is lossy, some of the decompressed data may exceed 10 bits.  So the user should set Num = 2^10 in the input of BuildTranslationTable12.  The table will then accept inputs up to 12 bits, but the input values >= 2^10 will be clipped to have the same output as 2^10 - 1 has.  This is the option   -VS#  in the command line test program; in this example # would be set to 10.  For example if  -VP8 and -VS10 are set in the command-line test program, the high 8 bits of the alleged 10-bit data are mapped to the output bytes, and anything above  10 bits gets mapped to the same value as 2^10 - 1 does.

B. Input is 8-Bit Gray Scale JPG  - Creating a 4- or 8-Bit Gray Scale DIB

Metadata

JPEG Metadata contained in the input GET queue is returned in the PIC2List. The following metadata is returned:

Notes

Alternative Legacy Approach for Retrieving Comments and Application Data: Separate Comment and AppField Buffers

OP_S2D and OP_P2D support an alternative approach for retrieving comments and other data from an image and making it available to the application. This is a legacy approach and is more restrictive than the use of the newer PIC2List functions. When using this approach, an application would allocate a buffer where the data of interest will be eventually placed by Pegasus. There are two possibilities according to when the buffer space is allocated.

Application Pre-allocates a Buffer before Pegasus Operation

This technique is also supported by PegasusQuery. In fact, it is the only choice for retrieving comments and other data via PegasusQuery.

In most cases, the application doesn't know how much data may be included in the comment or application data. In some cases an application either knows a probable maximum size or knows that it is acceptable to truncate the data over some maximum size.  In these cases, the application may choose to pre-allocate a buffer for the data before calling Pegasus for initialization.

The application sets PIC_PARM.Comment (PIC_PARM.u.S2D.AppField) to the address of the buffer.  PIC_PARM.CommentSize (PIC_PARM.u.S2D.AppFieldSize) is set to the allocated size of the buffer.  When Pegasus encounters comment data or application data in the image, it copies as much of the data to the appropriate buffer as will fit.  PIC_PARM.CommentLen (PIC_PARM.u.S2D.AppFieldLen) is set to the length of the copied data.

The application data should appear only once in the image.  Comment data may appear more than once.  When the application pre-allocates a comment buffer according to this section, the last comment data encountered prior to Pegasus returning a response is the comment data which appears in the PIC_PARM.Comment buffer any other prior comments are lost.

Application Allocates a Buffer during Pegasus Operation

When an application does not know the size of the image comment data, and must retrieve all available comment data, the application sets PIC_PARM.CommentSize to 0 and sets the PF_AlllocateComment flag in the PicFlags field of the operation-specific PIC_PARM union structure.

For application data, the application sets the PIC_PARM.u.S2D.AppFieldSize field to -1 and doesn't set a PicFlags flag.

When Pegasus encounters the comment (application data) it sets the PIC_PARM.CommentLen (PIC_PARM.u.S2D.AppFieldLen)  field and returns to the application with a response of RES_ALLOCATE_COMMENT_BUF (RES_ALLOCATE_APP2_BUF).  At this time the application can allocate a buffer and set PIC_PARM.Comment (PIC_PARM.u.S2D.AppField) and PIC_PARM.CommentSize (PIC_PARM.u.S2D.AppFieldSize).  The comment is retrieved when the operation is continued by returning 0 from the application's DeferFn function.

Pegasus returns the RES_HAVE_COMMENT response when the PF_AllocateComment flag is set, and an image comment is encountered, and an image comment was previously retrieved. This response gives the application an opportunity to save the previous comment before overwriting it by retrieving the current comment.  When the application continues the operation after saving the previous comment, a RES_ALLOCATE_COMMENT_BUF response is returned so a buffer can be allocated for the current comment.

The following example demonstrates this by storing the first 100 comments and their length in two, previously allocated, arrays: CommentsData and CommentsLen.   

 
Copy Code

PicParm.u.S2D.PicFlags |= PF_AllocateComment;

    PicParm.u.S2D.AppFieldSize = -1;

    resp = Pegasus(&PicParm, REQ_INIT);

    if ( resp == RES_DONE )

      resp = Pegasus(&PicParm, REQ_EXEC);

    if ( resp == RES_DONE )

      Pegasus(&PicParm, REQ_TERM);

 

  


 ///////////////////////////////////////////

    LONG DeferFn(PIC_PARM* pp, RESPONSE resp)

    {

        switch (resp) {

            case RES_GET_NEED_DATA:

                Status = GetData(pp);

                break;

            case RES_PUT_NEED_SPACE:

                Status = PutSpace(pp);

                break;

            case RES_ERR:

                Status = pp->Status;

                break;

            case RES_ALLOCATE_APP2_BUF:

                pp->u.S2D.AppFieldSize = pp->u.S2D.AppFieldLen;

                pp->u.S2D.AppField = malloc(pp->u.S2D.AppFieldSize);

                if ( pp->u.S2D.AppField == 0 ) {

                    pp->Status = ERR_OUT_OF_SPACE;

                    return ( 1 );  // abort the operation

                }

                break;

            case RES_HAVE_COMMENT:

                if (ncomments < 100) {

                    CommentsData[ncomments] = pp->Comment;

                    CommentsLen[ncomments++] = pp->CommentLen;

                }

                pp->CommentSize = 0;

                break;

            case RES_ALLOCATE_COMMENT_BUF:

                pp->CommentSize = pp->CommentLen;

                pp->Comment = malloc(pp->CommentSize);

                if ( pp->Comment == 0 ) {

                    pp->Status = ERR_OUT_OF_SPACE;

                    return ( 1 );  // abort the operation

                }

                break;

        }

        // abort if Status != ERR_NONE

        return ( Status != ERR_NONE  );

    }

 

 

 

 

©2022. Accusoft Corporation. All Rights Reserved.

Send Feedback