PICTools Programmer's Reference
OP_J2KTRANSCODE
| Operations > OP_J2KTRANSCODE |
OP_J2KTRANSCODE: Transcode JPEG2000
OP_J2KTRANSCODE (see opcode specific data structure) may be used to directly transcode one JPEG2000 image into another with different characteristics in a more efficient manner than by doing a decode followed by an encode with the new parameters.
The transcoding process follows the familiar REQ_INIT - REQ_EXEC - REQ_TERM sequence of calls to Pegasus. Before REQ_INIT, image data is placed in a Get buffer and a PIC_PARM structure is allocated and the basic structure members are initialized (PicParm.ParmSize = sizeof(PIC_PARM), PicParm.ParmVer = CURRENT_PARMVER, PicParm.ParmVerMinor = 3, PicParm.Op = OP_J2KTRANSCODE). It is recommended that a DeferFn function be defined and F_UseDeferFn be OR'ed into PicParm.Flags. REQ_INIT then returns JPEG2000 image information in the u.J2KT structure.
Following REQ_INIT, the application sets values in the u.J2KT structure to instruct OP_J2KTRANSCODE how to create the transcoded output JPEG2000 image and then calls REQ_EXEC. Note that any fields into which the application is not setting new values must remain unchanged between REQ_INIT and REQ_EXEC. New values entered into any fields must be valid values as described in the J2KT_UNION section. Further, note that OP_J2KTRANSCODE always removes tile parts beyond the first for each tile and always removes pointer marker segments. In order to create additional tile parts, the application must set one or more flags in u.J2KT.TileFlags.In order to add TLM, PPM, and/or PLT pointer marker segments, set the corresponding flag in u.J2KT.PICFlags2 or u.J2KT.TileFlags, as appropriate.
The JPEG2000 compressed image can be input in either the JPEG2000 raw codestream format or in the JPEG2000 JP2 file format and can be output in either format. Set u.J2KT.JPEG2000FileFormat to JPEG2000FileFormat_J2K to instruct OP_J2KTRANSCODE to output in the JPEG2000 raw codestream format. Set u.J2KT.JPEG2000FileFormat to JPEG2000FileFormat_JP2 to instruct OP_J2KTRANSCODE to output in the JPEG2000 JP2 file format.
The image can be transcoded to a thumbnail size by setting u.J2KT.Thumbnail to a value other than 0. The output image height and width will be reduced by 2u.J2KT.Thumbnail by discarding higher resolution levels and adjusting the image dimensions accordingly. If no other parameters that affect image size and quality are modified, then the output image will be smaller but with the same relative quality when viewed at the smaller size.
To reduce the image file size and quality without changing the image dimensions, the application can either discard higher quality layers or set a target size or rate smaller than the original. Set u.J2KT.DiscardLayers before REQ_EXEC to the number of highest-detail layers for OP_J2KTRANSCODE to discard before proceeding with other transcode parameters. Or set either a target rate in bits/pixel * 1000 (set in u.J2KT.Rate) or a target size in bytes (set in u.J2KT.CompFileSize).
The application can set targets for the individual layers of the output image by setting u.J2KT.LayerRates to point to an array containing one value per layer plus one additional entry containing the value 0 to terminate the array. Layer targets are cumulative values; each value indicates the count of bytes to use to encode the corresponding layer plus all previous layers, and the first value indicates the count of bytes to use to encode the first layer plus the main headers.
The application may set fewer values in the array than one per layer, in which case OP_J2KTRANSCODE will determine the sizes of the unspecified layers subject to the values in u.J2KT.Rate and u.J2KT.CompFileSize. If the application either does not specify a size for the final layer or the size that it does specify for the final layer is sufficiently large, and the application sets values in u.J2KT.Rate and u.J2KT.CompFileSize that are either zero or sufficiently large, then there will be no loss of quality in the output image and OP_J2KTRANSCODE determines the output image overall file size. If the application sets more values in u.J2KT.LayerRates than there are layers, the extraneous values will be ignored.
In case the application sets both u.J2KT.Rate and u.J2KT.CompFileSize to nonzero values, OP_J2KTRANSCODE uses the value in u.J2KT.CompFileSize and ignores the value in u.J2KT.Rate. If both fields are set to zero and there is a nonzero value in u.J2KT.LayerRates for the final layer, then that final layer size is the target for the output image overall file size. If either field is nonzero and there are fewer values in u.J2KT.LayerRates than the number of layers to be created, then the nonzero value in u.J2KT.Rate or u.J2KT.CompFileSize is used only if it is larger than the size of the last specified layer; otherwise, it is increased to the size of that last specified layer, that size becomes the target for the output image overall file size, and the number of layers to be created is reduced to match the number of layers in the u.J2KT.LayerRates array.
The application can set u.J2KT.NumLayers to request a number of quality layers that OP_J2KTRANSCODE should try to create in the output image that is different from the number of layers in the input image. Note that for some images and some combinations of parameters, the output image will contain fewer layers than requested. If u.J2KT.NumLayers is left unchanged between REQ_INIT and REQ_EXEC and no other parameters that affect image size and quality are modified, then OP_J2KTRANSCODE will retain the same layers in the output image that were in the input image.
If the application sets u.J2KT.DiscardLayers to a nonzero value, then the layers in the output image will be the same as those of the input image that remain after the requested number of layers are discarded. Note that if the application sets u.J2KT.DiscardLayers to a nonzero value, then it must not change u.J2KT.NumLayers, nor set nonzero values in u.J2KT.Rate, u.J2KT.CompFileSize, or u.J2KT.LayerRates.
Set TCF_Bypass is set in u.J2KT.TileCompFlags to use the EBCOT encoder selective coding bypass mode. This makes transcoding and decoding faster, but at the cost of a few percent larger compressed image. If the original image was encoded in bypass mode, TCF_NoBypass can be set to recode in normal mode; otherwise the original setting is retained.
For fastest transcoding and subsequent decompression, set PF2_FavorSpeed In u.J2KT.PicFlags2. Note that when this flag is set, lossless encoded files may become slightly larger and lossy rate-controlled encoded files may decode to slightly lower quality. The advantage of an image created with this flag will be lost if it is transcoded again without this flag set and the operation requires running the EBCOT encoder, as in a change to the layer configuration.
ParmVerMinor must be at least 2 for OP_J2KTRANSCODE. If ParmVerMinor is 3 or greater, then errors or warnings returned from the underlying JPEG 2000 technology library optionally return additional descriptive text in PIC2List if there is enough space or if the application reacts to RES_EXTEND_PIC2LIST responses. In that case, ERR_PIC2LIST_HAS_DESCRIPTION is returned in Status and the information about the error appears in P2PktErrorText packets with Type P2P_ErrorText. See include\pic2file.h and the PIC2List section of Accessing Comments and Other Auxiliary Data in the PICTools Programmer's Guide for more information about PIC2List packets.
OP_J2KTRANSCODE REQ_INIT returns image file comments to the application using PIC2List P2P_Comment packets if the PIC2Listexists. If the PIC2List has not been defined (PicParm.PIC2List = NULL), then no comments are returned to the application but they are all passed unchanged to the output image. If the PIC2List exists, then OP_J2KTRANSCODE provides these three options for the application to control what comments are put in the output JPEG2000 image:
See the J2KT_UNION:OP_J2KTRANSCODE section for additional information and the complete set of parameters that can be modified in a JPEG 2000 image using OP_J2KTRANSCODE.