FILEJ2KOPTIONS

typedef struct _FILEJ2KOPTIONS 
{ 
   L_UINT uStructSize; 
   L_BOOL bUseColorTransform; 
   L_BOOL bDerivedQuantization; 
   J2KCOMPRESSIONCONTROL uCompressionControl; 
   L_FLOAT fCompressionRatio; 
   L_OFFSET uTargetFileSize; 
   L_UINT uXOsiz; 
   L_UINT uYOsiz; 
   L_UINT uXTsiz; 
   L_UINT uYTsiz; 
   L_UINT uXTOsiz; 
   L_UINT uYTOsiz; 
   L_UINT uXRsiz [J2K_MAX_COMPONENTS_NUM]; 
   L_UINT uYRsiz [J2K_MAX_COMPONENTS_NUM]; 
   L_UINT uDecompLevel; 
   L_UINT uProgressOrder; 
   L_BOOL bUseSOPMarker; 
   L_BOOL bUseEPHMarker; 
   J2KREGIONOFINTEREST uROIControl; 
   L_BOOL bUseROI; 
   L_FLOAT fROIWeight; 
   L_RECT rcROI; 
   L_UINT uAlphaChannelActiveBits; 
   L_BOOL bAlphaChannelLossless; 
   J2KPRECINCTSIZE uPrecinctSize; 
} FILEJ2KOPTIONS, * pFILEJ2KOPTIONS; 

The FILEJ2KOPTIONS structure provides information for saving JPEG 2000 files.

Comments

The JPEG2000 image format offers both superior compression performance and robust file handling. Some J2K options can have a direct impact on compression performance, while others primarily affect resulting file size. Notes on Advanced options continue below.

Main options (listed above) include:

• Color Transforms

• Compression Settings

• Multiple resolution representation (Wavelet Decomposition Level)

• Random codestream access and processing (Progression Order)

• Progressive transmission (Advanced)

• Tile Size

• Error resilience for transmission in noisy environments, such as wireless and the Internet.

• Region-of-Interest coding.

Some functions which take this structure as a parameter require that the structure be initialized prior to the function call. You must set the uStructSize member to the total size, in bytes, of the structure. Use the sizeof() macro to calculate this value. Functions that do not require the structure to be initialized will take the total size of the structure, in bytes, as an additional function parameter.

Using this structure with FILE_CMW or FILE_TIF_CMW files:

When using this structure with FILE_CMW or FILE_TIF_CMW files, only the following data members are required:

uCompressionControl

fCompressionRatio

uTargetFileSize

uProgressOrder

The resulting file size/ compression ratio can be determined in several ways. Depending on the value set in the uCompressionControl member, the user can set the size of the target file, the actual compression ratio to use during compression or the quality factor to use during compression. If uCompressionControl is set to J2K_COMPRESSION_RATIO, then the compression to use is based on the compression ratio in the fCompressionRatio data member. If uCompressionControl is set to J2K_COMPRESSION_TARGETSIZE, the compression to use is based on the desired target file size in the uTargetFileSize data member. If uCompressionControl is set to J2K_COMPRESSION_QFACTOR, then compression is used based on the QFactor passed to the SaveXXX functions.

Lossless Compression

For lossless compression, set the uCompressionControl to J2K_COMPRESSION_LOSSLESS.

Lossy Compression Quantization

There are two types of quantization for Lossy compression: Scalar Derived Quantization and Scalar Expounded Quantization.

The exponent/mantissa pairs are either signaled in the codestream for every sub-band (expounded quantization) or else signaled only for the Low Pass sub-band and derived for all other sub-bands (derived quantization). In the case of derived quantization, all exponent/mantissa pairs are derived from the single exponent/mantissa pair corresponding to the Low pass sub-band.

 The quantization step size for a sub-band is calculated from the dynamic range of the sub-band using the following equation, where R = bpp for the sub-band:

Quantization Step = (2 (R - Exponent) ) * [1 + (Mantissa / 2048)]

If the value of uCompressionControl is J2K_COMPRESSION_RATIO, J2K_COMPRESSION_QFACTOR or J2K_COMPRESSION_TARGETSIZE, and the value of bAlphaChannelLossless is TRUE, the compressed J2K/JP2 file will have three lossy components (red, green and blue) in addition, the lossless alpha component.

If the value of uCompressionControl is J2K_COMPRESSION_LOSSLESS, the value of bAlphaChannelLossless will be ignored and all the components will be lossless.

The alpha channel can be dithered using L_ColorREsBitmap and L_DynamicBinaryBitmap externally, and before saving a J2K/JP2 file, in case a better alpha channel quality is desired.

Tile and Canvas Settings

The values of the uXOsiz, uYOsiz, uXTsiz, uYTsiz, uXTOsiz and uYTOsiz structure members are used to create tiles within the image. Arbitrary tile sizes are allowed. All tiles are the same size, except for the border tiles. Each tile can be compressed individually. This can decrease memory usage while the program is running, but can also generate artifacts at the edges of the tiles. Artifacts generally increase as the size of the tile decreases. By default, there is one tile that contains the entire image.

The various parameters defining the reference grid appear in the figures below.

The reference grid is a rectangular grid of points with the indices from (0, 0) to (Xsiz-1, Ysiz-1). An "image area" is defined on the reference grid by the dimensional parameters, (Xsiz, Ysiz) and (XOsiz, YOsiz).

Specifically the image area on the reference grid is defined by its upper left hand reference grid point at location (XOsiz, YOsiz), and its lower right hand reference grid point at location (Xsiz-1, Ysiz-1).

Progression Order

For a given tile-part, the packets contain all compressed image data from a specific layer, a specific component, a specific resolution level, and a specific precinct. The order in which these packets are found in the codestream is called the progression order. The ordering of the packets can progress along four axes: layer, component, resolution and position.

1. LAYER-RESOLUTION -COMPONENT-POSITION

A progression of this type might be useful when low sample accuracy is most desirable, but information is needed for all components.

2. RESOLUTION -LAYER-COMPONENT-POSITION

A progression of this type might be useful in providing low-resolution level versions of all image components.

3. RESOLUTION -POSITION-COMPONENT-LAYER

To use this progression, XRsiz and YRsiz values must be powers of two for each component. A progression of this type might be useful in providing low-resolution level versions of all image components at a particular spatial location.

4. POSITION-COMPONENT-RESOLUTION -LAYER

A progression of this type might be useful in providing high sample accuracy for a particular spatial location in all components.

5. COMPONENT-POSITION-RESOLUTION -LAYER

A progression of this type might be useful in providing high accuracy for a particular spatial location in a particular image component.

Precincts definition and recommendation

This feature is available in version 16 or higher.

Precincts are rectangular regions in the wavelet domain, within a given resolution level and image component that represent a spatial region on the image.

They are used for limiting the size of JPEG 2000 compressed packets and to provide a means to random access into a JPEG 2000 compressed stream.  For this reason, they should be used for interactive transfer of JPEG 2000 files as in JPIP applications.  In general, dividing the image into precincts is better than tiling it. So it is recommended that users compress the image as one tile and use precincts to divide the spatial region. This will give better compression ratios and image quality.

Using smaller precinct dimensions provides finer access to the compressed stream yet increases the compressed stream size. It is best to use J2KPRECINCTSIZE_HIERARCHICAL1_128 and no tiling to generate JPEG 2000 files for any purpose.  

To save or convert to large dimensions J2K files (above 5000 lines) use the "J2kLargeImageSave" demo. This demo will save large images without excessive memory, disc or CPU usage. Unlike other demos which load the entire image/bitmap to memory and then save them, this demo loads and saves one line at time.

For More Information, Refer To:

ISO/IEC JTC1/SC29/WG1 N1861: Coding of Still Pictures