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 a discussion of the property description tables shown below, see Modifying Object Property Descriptions.

Objects of this class have the following properties.

BIT_DEPTH	N_LEVELS	SUBSAMPLING
BIT_RATE	N_COMPONENTS	TILE_DIMENSIONS
COLOR_SPACE	N_TILES	TILE_OFFSET
COMMENT	OFFSET	TILE_RANGE
DIMENSIONS	PALETTE	UUIDS
DISPLAY_RESOLUTION	PROGRESSION	WRITE
FILENAME	QUIET	XML
GML_ROOT_INSTANCE	READ	YCC
JP2	REVERSIBLE
N_LAYERS	SIGNED

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.

Property Type	Integer Vector
Name String	not displayed
Get: Yes	Set: Yes	Init: Yes	Registered: No

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).

Property Type	Float Vector
Name String	not displayed
Get: No	Set: Yes	Init: Yes	Registered: No

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.
<Empty string> - none of the above. An empty string will result if the source is not a JP2 source.

Property Type	String
Name String	not displayed
Get: Yes	Set: No	Init: No	Registered: No

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.

Property Type	String Vector
Name String	not displayed
Get: Yes	Set: Yes	Init: Yes	Registered: No

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 ... 2³²-1.

Property Type	Integer Vector
Name String	not displayed
Get: Yes	Set: Yes	Init: Yes	Registered: No

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.

Property Type	Float Vector
Name String	not displayed
Get: Yes	Set: Yes	Init: Yes	Registered: No

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.

Property Type	String
Name String	not displayed
Get: Yes	Set: No	Init: No	Registered: No

GML_ROOT_INSTANCE

A string containing the Geography Markup Language (GML) entry from the gml.root-instance box in a JPEG2000 file. This box typically contains georeferencing information. Call this property to add GML when creating a JPEG2000 file.

Property Type	String
Name String	not displayed
Get: Yes	Set: Yes	Init: Yes	Registered: No

If a JPEG2000 file does not contain a gml.root-instance box when IDL reads it, this property returns an empty string. If the file contains a gml.root-instance box, the property returns a single string containing the entire contents of the box.

Here are some tips for parsing GML information in JPEG2000 files:

You can read the GML tag (an XML string) into a string variable and parse the variable directly with the IDLffXMLSAX:ParseFile method.
You can read the GML tag (an XML string), save the string to a temporary file, then pass the file to IDLffXMLDOMDocument.
You cannot pass a JPEG2000 file directly to an IDL parser.

Reference:

Open Geospatial Consortium, Inc. GML in JPEG 2000 for Geographic Imagery (GMLJP2) Encoding Specification, Version 1.0.0, Document # 05-047r3, 20 January 2006. Accessed June 2012.

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 (.jp2 file type), regardless of the file extension specified.
If the JP2 property is set to 0, the file created will contain only a codestream (.j2c file type), regardless of the file extension specified.
If the JP2 property is not set when the IDLffJPEG2000 object is created:
If the file extension specified is either .jp2 or .jpx, the file created will contain both codestream an metadata (.jp2 file type).
If the file extension is anything other than .jp2 or .jpx, the file created will contain only the codestream (.j2c file type).

When reading a JPEG2000 file:

The JP2 property will be set to 1 if the file contains both codestream and metadata.
The JP2 property will be set to 0 if the file contains only the codestream.

Property Type	Boolean
Name String	not displayed
Get: Yes	Set: No	Init: Yes	Registered: No

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.

Property Type	Integer
Name String	not displayed
Get: Yes	Set: Yes	Init: Yes	Registered: No

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

Property Type	Integer
Name String	not displayed
Get: Yes	Set: Yes	Init: Yes	Registered: No

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.

Property Type	Integer
Name String	not displayed
Get: Yes	Set: Yes	Init: Yes	Registered: No

N_TILES

An integer specifying the number of tiles within the file.

Property Type	Integer
Name String	not displayed
Get: Yes	Set: No	Init: No	Registered: No

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 ... 2³¹-2 .

Property Type	Integer Vector
Name String	not displayed
Get: Yes	Set: Yes	Init: Yes	Registered: No

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”.

Property Type	String
Name String	not displayed
Get: Yes	Set: Yes	Init: Yes	Registered: No

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.

Property Type	Boolean
Name String	not displayed
Get: No	Set: Yes	Init: Yes	Registered: No

READ

A boolean set to 1 if the file is to be accessed for reading. The default is to open the file for reading.

Property Type	Boolean
Name String	not displayed
Get: Yes	Set: No	Init: Yes	Registered: No

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.

Property Type	Boolean
Name String	not displayed
Get: Yes	Set: Yes	Init: Yes	Registered: No

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.

Property Type	Boolean Vector
Name String	not displayed
Get: Yes	Set: Yes	Init: Yes	Registered: No

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.

Property Type	Integer Array
Name String	not displayed
Get: Yes	Set: No	Init: No	Registered: No

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 ... 2³²-1.

Property Type	Integer Vector
Name String	not displayed
Get: Yes	Set: Yes	Init: Yes	Registered: No

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.

Property Type	Integer Vector
Name String	not displayed
Get: Yes	Set: Yes	Init: Yes	Registered: No

TILE_RANGE

A two-element integer vector giving the number of tiles in the X and Y directions.

Property Type	Integer Vector
Name String	not displayed
Get: Yes	Set: No	Init: No	Registered: No

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 box and a user data box. 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:

a scalar value of 0 when the file does not contain any UUID boxes
a 16 x n byte array, where n is the number of UUIDs included. UUID boxes that exist in the file but do not contain any data are not included in the returned array.

For example, if the file contains 10 UUID boxes then this property returns a 16x10 byte array.

Property Type	Byte array
Name String	not displayed
Get: Yes	Set: No	Init: No	Registered: No

WRITE

A boolean that is 1 if the object is open for writing, 0 if not.

Property Type	Boolean
Name String	not displayed
Get: Yes	Set: No	Init: Yes	Registered: No

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 an empty 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.

Property Type	String Vector
Name String	not displayed
Get: Yes	Set: Yes	Init: Yes	Registered: No

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.

Property Type	Boolean
Name String	not displayed
Get: Yes	Set: Yes	Init: Yes	Registered: No