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:

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 ... 232-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:

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

When reading a JPEG2000 file:

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 ... 231-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:

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 ... 232-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:

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:

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