FILEJ2KOPTIONS
typedef struct _FILEJ2KOPTIONS
{
L_UINT uStructSize;
L_BOOL bUseColorTransform;
L_BOOL bDerivedQuantization;
J2KCOMPRESSIONCONTROL uCompressionControl;
L_FLOAT fCompressionRatio;
L_SIZE_T 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_INT nCodBlockWidth;
L_INT nCodBlockHeight;
CODBLOCKSTYLE CodBlockStyleFlags;
L_UINT uGuardBits;
L_INT nDerivedBaseMantissa;
L_INT nDerivedBaseExponent;
L_BOOL bUseSOPMarker;
L_BOOL bUseEPHMarker;
J2KREGIONOFINTEREST uROIControl;
L_BOOL bUseROI;
L_FLOAT fROIWeight;
L_RECT rcROI;
L_UINT uAlphaChannelActiveBits;
L_BOOL bAlphaChannelLossless;
} FILEJ2KOPTIONS, * pFILEJ2KOPTIONS;
The FILEJ2KOPTIONS structure provides information for saving JPEG 2000 files.
|
Member |
Description |
|
|
uStructSize |
Size of this structure in bytes, for versioning. Use the sizeof() macro to calculate this value. |
|
|
|
Color Transform |
|
|
bUseColorTransform |
Flag that indicates whether to convert an RGB image to YUV space before compressing. YUV provides greater compression with higher image quality. Possible values are: |
|
|
|
Value |
Meaning |
|
|
TRUE |
Convert to YUV space before compressing. (Default) |
|
|
FALSE |
Do not convert to YUV space before compressing. |
|
|
General Settings (Advanced Users Only) |
|
|
uGuardBits |
Additional most significant bits that have been added to sample data (number of extra bits to consider when encoding an image). This prevents coding overflow. Possible values are 0 - 7. The default is 2. Value of 2 or 1 will produce best compression. |
|
|
bDerivedQuantization |
Flag that indicates whether to use derived quantization or expounded quantization, which determines quality and speed. Possible values are: |
|
|
|
Value |
Meaning |
|
|
TRUE |
Use derived quantization. |
|
|
FALSE |
Use expounded quantization. |
|
nDerivedBaseMantissa |
The base mantissa used for derived quantization. |
|
|
nDerivedBaseExponent |
The base exponent used for derived quantization. |
|
|
|
Main Compression Settings These options have direct results on the compression ratio. |
|
|
uCompressionControl |
Flag that indicates how to determine the resulting compression. The value of this member determines which structure member should be used for determining the compression. Possible values are: |
|
|
|
Value |
Meaning |
|
|
J2K_COMPRESSION_LOSSLESS |
Lossless compression. |
|
|
J2K_COMPRESSION_RATIO |
Compress the file based on the value of the fCompressionRatio member. |
|
|
J2K_COMPRESSION_TARGETSIZE |
Compress the file based on the target file size in the uTargetFileSize member. |
|
|
J2K_COMPRESSION_QFACTOR |
Compress the file based on the quality factor used by the L_SaveXXX function. |
|
fCompressionRatio |
Value that indicates the compression ratio to use. This value is used only if the uCompressionControl member is set to J2K_COMPRESSION_RATIO. |
|
|
uTargetFileSize |
Value that indicates the size of the target file, in bytes. This value is used only if the uCompressionControl member is set to J2K_COMPRESSION_TARGETSIZE. |
|
|
|
Tile Size Using a larger tile size allows the JPEG 2000 compression engine to find more similarities, resulting in better compression. |
|
|
uXTsiz |
Width of one reference tile, with respect to the reference grid. |
|
|
uYTsiz |
Height of one reference tile, with respect to the reference grid. |
|
|
|
Canvas Settings (Advanced Users Only) |
|
|
uXOsiz |
Horizontal offset from the origin of the reference grid to the left side of the image area. |
|
|
uYOsiz |
Vertical offset from the origin of the reference grid to the top of the image area. |
|
|
uXTOsiz |
Horizontal offset from the origin of the reference grid to the left side of the first tile. |
|
|
uYTOsiz |
Vertical offset from the origin of the reference grid to the top of the first tile. |
|
|
uXRsiz |
Reserved. |
|
|
uYRsiz |
Reserved. |
|
|
|
Wavelet Decomposition Level |
|
|
uDecompLevel |
Number of resolution levels in the compressed file. The maximum number of levels depends on the size of the image. Passing values that are too large will cause the save operation to fail. Each resolution level is one-half the size of the previous resolution, in both dimensions (width and height), starting with the full image resolution. The resolutions are not stored independently, and do not have a major impact on the compression results. The default value is 5, which produces the best compression ratios in most cases. |
|
|
|
Progression Order |
|
|
uProgressOrder |
Indicates the order of progression. Possible values are: |
|
|
|
Value |
Description |
|
|
J2K_LAYER_RESOLUTION_COMPONENT_POSITION |
[0] Quality–axis order. Image starts out blurry and becomes clearer and more detailed as additional data is decoded. |
|
|
J2K_RESOLUTION_LAYER_COMPONENT_POSITION |
[1] Resolution-axis order. Image starts out small and becomes larger as additional data is decoded. Higher compression ratios achieved by leaving lower resolutions in the file. |
|
|
J2K_RESOLUTION_POSITION_COMPONENT_LAYER |
[2] Resolution-axis order. Image starts out small and becomes larger as additional data is decoded. Higher compression ratios achieved by leaving lower resolutions in the file. |
|
|
J2K_POSITION_COMPONENT_RESOLUTION_LAYER |
[3] Position–axis order. Image starts out as a series of blocks starting from the top left corner. Additional portions of the image become visible as more data is decoded. Image data stored by spatial location. |
|
|
J2K_COMPONENT_POSITION_RESOLUTION_LAYER |
[4] Color-axis order. Image starts out gray. Color is added as more data is decoded. Image data stored by color channel, starting with channel Y, then U, then V. If the transform to YUV option is used, the lowest decompressed image level for RGB is grayscale. Otherwise, the output is only the red channel. |
|
|
Progressive Transmission Setting (Advanced Users Only) These variables control the size of the post wavelet code blocks. Values can range between 2 and 10, with the sum of the two values not to exceed 12. |
|
|
nCodBlockWidth |
Width of the code block, following wavelet transformation. The value must be a power of 2. It must be at least 4 and less than or equal to 1024. |
|
|
nCodBlockHeight |
Height of the code block, following wavelet transformation. The value must be a power of 2. It must be at least 4 and less than or equal to 1024. |
|
|
CodBlockStyleFlags |
Bit flags that indicate the behavior of the code block. For more information, refer to the CODBLOCKSTYLE structure. |
|
|
|
Error Resilient Settings Indicates whether to include markers at the "Start of Packet" and "End of Packet Header". These markers help detect file corruption during transmission. If these markers exist in the JPEG2000 compressed stream, it is easy for the decoder to find the packet boundary or, in case of a stream error, check the size. |
|
|
bUseSOPMarker |
Flag that indicates whether to use the SOP marker. Possible values are: |
|
|
|
Value |
Meaning |
|
|
TRUE |
Use the SOP marker. If TRUE, each packet in any given tile part will be prepended with an SOP marker segment. The SOP marker includes the size of the packet. |
|
|
FALSE |
Do not use the SOP marker. (Default) |
|
bUseEPHMarker |
Flag that indicates whether to use the EPH marker. Possible values are: |
|
|
|
Value |
Meaning |
|
|
TRUE |
Use the EPH marker. If TRUE, each packet header in any given tile part is postpended with an EPH marker segment. |
|
|
FALSE |
Do not use the EPH marker. (Default) |
|
|
Region of Interest |
|
|
bUseROI |
Flag that indicates whether to use a region of interest. Possible values are: |
|
|
|
Value |
Meaning |
|
|
TRUE |
Use a region of interest as specified in the uROIControl member. |
|
|
FALSE |
Do not use a region of interest. If you do not want to use a region of interest, set this to FALSE. Otherwise, there may be a significant compression and speed performance loss. |
|
uROIControl |
Flag that indicates the region of interest to use. For a list of possible values refer to J2KREGIONOFINTEREST. |
|
|
|
Value |
Meaning |
|
|
J2K_USE_OPTION_RECT |
Use the rectangle specified in the rcROI member of the FILEJ2KOPTIONS structure to define the region of interest. |
|
|
J2K_USE_LEAD_REGION |
Use the LEAD bitmap region to define the region of interest. (Any region shape is acceptable; it will be converted internally by the filter to a rectangle.) |
|
fROIWeight |
Reserved for future use. |
|
|
rcROI |
L_RECT structure that contains the boundaries of the region of interest within the image. |
|
|
|
Channels |
|
|
uAlphaChannelActiveBits |
Value that indicates how the active bits of alpha channel are controlled. Possible values are: |
|
|
|
Value |
Meaning |
|
|
1 |
The 256 levels of the 8-bit alpha channels will be
transformed into two levels of value 255 or 0, using simple threshold.
The threshold value is 127, so all values > 127 will be set to 255
and all values <= 127 will be set to 0. |
|
|
8 |
All the 256 levels of the 8-bit alpha channels will be compressed. This is the default value. |
|
|
This option should be used on a 32-bit bitmap otherwise it has no effect. |
|
|
bAlphaChannelLossless |
Flag that indicates whether to save J2K/JP2 lossy image with or without lossless alpha channel. Possible values are: |
|
|
|
Value |
Meaning |
|
|
TRUE |
Save with lossless alpha channel. This is the default value. |
|
|
FALSE |
Save without lossless alpha channel. |
|
|
The resultant image is 32-bit. The value of this member controls the compression type of alpha channel for J2K/JP2 lossy compression. This option should be used on a 32-bit bitmap; otherwise it has no effect. |
|
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.
For More Information, Refer To:
ISO/IEC JTC1/SC29/WG1 N1861: Coding of Still Pictures
