IDLffJPEG2000 Properties
IDLffJPEG2000 objects have the following properties. Properties with the word "Yes" in the "Get" column of the property table can be retrieved via IDLffJPEG2000::GetProperty. Properties with the word "Yes" in the "Init" column of the property table can be set via IDLffJPEG2000::Init. Properties with the word "Yes" in the "Set" column in the property table can be set via IDLffJPEG2000::SetProperty.
Note
For more information about the "Property Type", "Name String", and "Registered" columns, see About Object Property Descriptions.
Objects of this class have the following properties.
BIT_DEPTH
An integer vector containing the bit depth for each image component. Values must be in the range 1 ... 24.
Note
When writing out JPEG2000 files, the default BIT_DEPTH is 8 for all components, regardless of the data type supplied to SetData. If you are writing out short or long integer data, you may wish to set BIT_DEPTH to a larger value for those components.
BIT_RATE
A floating-point vector containing the bit rate for each layer, measured in bits per pixel per component (or band). The number of elements in BIT_RATE must be equal to the number of quality layers or, alternatively, may be two.
When writing files, the values in BIT_RATE may be given in any order, and will be automatically sorted into ascending order. A value of -1 anywhere within the BIT_RATE vector indicates that the highest quality layer should include all compressed bits. BIT_RATE may also be set to a two-element vector, in which case the rates will be approximately logarithmically spaced between the two values.
When the /REVERSIBLE switch is set the last rate will be automatically set to -1 to ensure that the last layer contains the bits needed to recreate the original image data.
When the number of rates being set exceeds the number of layers being set an error is thrown. The value in the N_LAYERS property must always be equal to or greater than the number of bit rates in the BIT_RATE property (unless the number of bit rates is two).
COLOR_SPACE
A string containing one of the following values:
- sLUM - a luminance (monochrome) space.
- sRGB - the sRGB space is a reasonably good model for color imagery which has been corrected to look good on a monitor.
- sYCC - a three-component color space derived by applying the standard YCbCr color transform to sRGB data; the YCbCr transform is identical to the irreversible color transform defined by JPEG2000 at the code stream level.
- iccLUM - a monochrome color space defined by an embedded ICC profile.
- iccRGB - an RGB color space defined by an embedded ICC profile.
- <Null string> - none of the above. A null string will result if the source is not a JP2 source.
COMMENT
A string vector containing an element for each comment associated with the object. If the object has no associated comments, the result will be a scalar null string.
DIMENSIONS
A two-element 64-bit integer array giving the width and height of the image. Values for DIMENSIONS should be in the range 1 ... 232-1.
DISPLAY_RESOLUTION
A two-element floating-point vector giving the default horizontal and vertical display resolution (in samples per meter). This property will return a value of [0.0, 0.0] if the file has no display resolution specified. This keyword is only valid for JP2 files.
Note
The JPEG2000 code stream stores the display resolution values using only 24 bits of precision. When writing files, you may notice slight differences between your input values and the values returned when reading the file.
FILENAME
A string containing the name of the file associated with the object
Note
This property can only be set via the Filename argument to the IDLffJPEG2000::Init method.
JP2
A boolean value indicating whether the JPEG2000 file consists of only a codestream (usually referred to as a .j2c file) or of a codestream and metadata information (usually referred to as a .jp2 or .jpx file).
Note
This property can only be set when the IDLffJPEG2000 object is created.
When writing a JPEG2000 file (that is, when the WRITE property is set to 1):
- If the JP2 property is set to 1, the file created will contain a codestream and metadata (
.jp2file type), regardless of the file extension specified. - If the JP2 property is set to 0, the file created will contain only a codestream (
.j2cfile type), regardless of the file extension specified. - If the JP2 property is not set when the IDLffJPEG2000 object is created:
When reading a JPEG2000 file:
N_COMPONENTS
An integer containing the number of image components (or channels) in the entire file or code stream. If N_COMPONENTS is not supplied in the first call to Init or SetProperty, it will be the same as the number of components contained in the image parameters in the first call to SetData.
N_LAYERS
A positive integer specifying the number of quality layers. A quality layer is one quality increment for the entire image at full resolution. Each layer contains the information required to represent the image at a higher quality, given the information from all the previous layers. All image data bits may be encoded in one layer, or may be broken up into a larger number of layers, each containing a further quality refinement.
When writing, the default is one. If N_LAYERS is greater than one, the layers will be assigned roughly logarithmically-spaced bit rates, with the last layer containing all of the compressed bits. A larger number of layers takes longer to encode and produces a larger file, but provides more flexibility when decoding.
When setting N_LAYERS, the value is limited to 244
N_LEVELS
An integer specifying the number of wavelet decomposition levels, or stages, in the range of 0...15. Higher values will typically give better compression.
When writing files, a value of zero indicates that no wavelet transform will be used. If this keyword is omitted, then the default value of 5 is used. When writing JP2 files, if the PALETTE property is set then the default is N_LEVELS=0.
N_TILES
An integer specifying the number of tiles within the file.
OFFSET
A two-element integer array giving the X and Y offsets of all image components. Values for OFFSET should be positive, in the range of a 32-bit integer 0 ... 231-2 .
PALETTE
JP2 files may contain a "palette", or color table, which efficiently stores images with only a few distinct colors. The palette associates a color index with each distinct color present in the image. Images stored in JP2 files with a palette consist of only one component which contains the color indices.
When writing a JP2 file, set this property to a 3-by-n or an n-by-3 array of byte or integer values, where n is the number of intensity values, for the three color channels of red, green, and blue. In this case n must be a power of 2 and ≤ 256.
When reading JP2 files, this property will return an n-by-m array of byte or integer values, where n is the number of intensity values, and m is the number of lookup tables (m is usually 3, indicating red, green, and blue). If the associated object has no palette, this property will return a scalar zero.
Note
When writing JP2 files, if PALETTE is present, then the default values for other properties are N_LEVELS=0, REVERSIBLE=1, and YCC=0.
| Property Type |
Byte or Integer Array |
||
| Name String |
not displayed |
||
| Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |
PROGRESSION
A string defining the progression order of the output. Progression order may be one of the following: LRCP, RLCP, RPCL, PCRL, CPRL. The four character identifiers have the following interpretation: L = layer; R = resolution; C = component; P = position. Data is written to the output file iteratively over the four progression identifiers in this string, that is, the output is written in four nested iteration levels. The first character in the identifier refers to the outermost level of the iteration, while the last refers to the innermost level. The default is LRCP. This property is ignored when used with files opened for reading.
For example, "LRCP" means that an image is encoded in the following order, with quality being the outermost loop:
- L - a series of one or more quality layers, each contributing a quality increment for the entire image at full resolution. The quality layers may be interpreted as sub-bitplanes containing the image data at a specified, possibly fractional, bit-rate.
- R - each resolution level of the image, which corresponds to the N_LEVELS keyword used in encoding, and can be considered to contain the image data at a given size or resolution. Each level adds another level of detail to the previous levels.
- C - each image component of the above.
- P - each position (tile) within the image component.
In this example, if an image consists of 2 quality layers, 5 resolution levels, 3 components, and 16 positions or tiles, the image would be encoded in a series of packets as follows:
P0C0R0L0, P1C0R0L0, P2C0R0L0, ..., P15C0R0L0 P0C1R0L0, P1C1R0L0, P2C1R0L0, ..., P15C1R0L0 P0C2R0L0, P1C2R0L0, P2C2R0L0, ..., P15C2R0L0 P0C0R1L0, P1C0R1L0, P2C0R1L0, ..., P15C0R1L0 P0C1R1L0, P1C1R1L0, P2C1R1L0, ..., P15C1R1L0 P0C2R1L0, P1C2R1L0, P2C2R1L0, ..., P15C2R1L0 ... ... ... ... ... ... ... ... ... P0C2R4L0, P1C2R4L0, P2C2R4L0, ..., P15C2R4L0 P0C0R0L1, P1C0R0L1, P2C0R0L1, ..., P15C0R0L1 P0C1R0L1, P1C1R0L1, P2C1R0L1, ..., P15C1R0L1 P0C2R0L1, P1C2R0L1, P2C2R0L1, ..., P15C2R0L1
This encodes all components over the entire image at a given quality level, before sending the next quality refinement.
When encoding a large image with a large number of components, memory requirements will be minimized by sending each component by means of a separate call to SetData, and by specifying a progression order of "CPRL".
QUIET
A boolean that when set to a non-zero value suppresses the printing of warnings for this object. The default is not to suppress warnings.
READ
A boolean set to 1 if the file is to be accessed for reading. The default is to open the file for reading.
REVERSIBLE
A boolean that specifies the type of compression that should be used. A non-zero value indicates that reversible (lossless) compression should be used. The default is to use irreversible compression. When writing JP2 files, if the PALETTE property is set then the default is REVERSIBLE=1.
SIGNED
An n-element boolean vector where n is the number of components. A value of one indicates pixels in that component are interpreted as signed numbers, otherwise the pixels are interpreted as unsigned numbers. The default is to interpret the numbers as unsigned.
Note
When writing out JPEG2000 files, the default is SIGNED=0 for all components, regardless of the data type supplied to SetData. If you are writing out signed integer data, you should set SIGNED to 1 for those components.
SUBSAMPLING
A 2 by N_COMPONENTS integer array containing the subsampling factors in the horizontal and vertical dimensions for each image component. The dimensions of each component will be the ceiling of the image dimensions divided by the respective subsampling factor.
TILE_DIMENSIONS
A 2-element integer vector defining the width and height of each tile. When writing files, the default is to write one tile with the same dimensions as the image parameter. Values for TILE_DIMENSIONS should be in the range 1 ... 232-1.
TILE_OFFSET
A 2-element integer vector containing the X and Y offset of the first tile on the canvas.
When reading, the TILE_OFFSET will return the X and Y offset of the first tile. The GetTileProperty method may be used to retrieve the TILE_OFFSET for other tiles.
When writing, the default is TILE_OFFSET=[0,0]. The values of TILE_OFFSET must be less than or equal to the corresponding values of the OFFSET property. Values for TILE_OFFSET should be positive, in the range 0 to (2^31)-2.
TILE_RANGE
A two-element integer vector giving the number of tiles in the X and Y directions.
UUIDS
This property provides a mechanism to retrieve the Universally Unique Identifiers (UUIDs) for the UUID boxes in the JPEG2000 file.
A JPEG2000 file can contain 0-n number of UUID boxes. A UUID is a 16 byte value. Each UUID box is made up of a UUID field and a user data field. A UUID box allows the user to store application specific data inside a JPEG2000 file using a universally unique identifier.
The property returns one of the following:
For example, if the file contains 10 UUID boxes then this property returns a 16x10 byte array.
WRITE
A boolean that is 1 if the object is open for writing, 0 if not.
XML
A string vector, with each element containing the XML string of a corresponding JP2 XML box. When creating a JP2 file, call this property with a string value to add the corresponding XML to the JP2 file. This property can be set multiple times. Each time it is set, the corresponding string will be added to a separate XML box.
When reading a JP2 file, if the file does not contain any XML boxes, the property returns a null string. If the file contains a single XML box, the property will return a single string containing the entire contents of the XML box. If the file contains multiple XML boxes, the property will return an array of strings, each containing the contents of an entire XML box.
This keyword is only valid for JP2 files.
Here are a few tips for working with XML in JP2 files and IDLffJPEG2000 objects:
- An XML box can hold plain text as well as XML text.
- There can be multiple XML boxes in JP2 files.
- To parse the JP2 file XML tag with the IDL SAX parser, read the XML tag and store the XML string in a variable. You can then parse the variable directly with the IDLffXMLSAX::ParseFile method.
- To parse the JP2 file XML tag with the IDL DOM parser, read the XML tag and save the XML string in a temporary file. You can then pass the file to IDLffXMLDOMDocument.
- You cannot pass a J2K file directly to an IDL parser.
YCC
When reading files, this property indicates whether the data was originally converted from the RGB color space to the YCC color space. If YCC is true, then when calling GetData, you may wish to return all three image components so that the YCC data can be correctly transformed back to RGB.
When writing files, set this property to a boolean which specifies whether RGB data should be converted to YCrCb before being written. If the image being written has three components, the default is to assume the image contains RGB components, which are automatically converted to YCrCb, and then written. The default action to convert RGB to YCC may be overridden by explicitly setting the YCC keyword to zero. When writing JP2 files, if the PALETTE property is set then the default is YCC=0. If the image being written does not have three components, this property is ignored.
Transforming the color coordinates from RGB to YCC decorrelates the three color components and improves compression performance for RGB images. JPEG2000 readers will then convert back to RGB.
Note
For the RGB-to-YCC conversion to occur, all three components must be provided at the same time (either the entire image or as separate tiles). If the components are provided in separate calls to SetData, the YCC conversion is not performed.
