IDLffMJPEG2000 Properties
IDLffMJPEG2000 objects have the following properties in addition to properties inherited from any superclasses. Properties with the word “Yes” in the “Get” column of the property table can be retrieved via IDLffMJPEG2000::GetProperty. Properties with the word “Yes” in the “Init” column of the property table can be set via IDLffMJPEG2000::Init. Properties with the word “Yes” in the “Set” column in the property table can be set via IDLffMJPEG2000::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
An integer value between 1 and 24 that indicates the bit depth of a file component. All components in the file must have the same bit depth. For example, RGB frames have a bit depth of 8 bits, so this property would be set to 8.
This property must be set prior to the first call to IDLffMJPEG2000::SetData. The default value is 8 bits.
Note: When writing a MJPEG2000 file, the default BIT_DEPTH is 8 regardless of the data type supplied to SetData. If you are writing out short or long integer data, you must set BIT_DEPTH to the correct value for the data type.
|
Property Type |
Integer |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |
Note: You can set this property only for an MJ2 file that is open for writing (WRITE=1).
BIT_RATE
A floating-point vector specifying the bit rate for each layer. The BIT_RATE vector, if set, is used by the compression engine when writing files to control the size of each layer. The compression engine will compress each layer into the number of bytes calculated from the bit rate for the layer. If the bit rate is not set, the compression engine automatically calculates the number of bytes that will be used to store a layer.
The number of vector elements must be equal to one of the following:
- The number of quality layers (the N_LAYERS property value): Each vector element applies to one quality layer. The values may be given in any order and will be automatically sorted into ascending order.
- Two elements: The bit rates applied to each quality layer will be approximately logarithmically spaced between the two vector values.
A value of -1 anywhere within the BIT_RATE vector indicates that the highest quality layer should include all compressed bits. When the REVERSIBLE property is true, the last rate will be automatically set to -1 to ensure that the last layer contains the bits needed to recreate the original frame data.
An error will be thrown if the number of vector elements exceeds the number of layers. The value in the N_LAYERS property must always be equal to or greater than the number of vector elements in the BIT_RATE property (unless there are two elements).
|
Property Type |
Integer |
||
|
Name String |
not displayed |
||
|
Get: No |
Set: Yes |
Init: Yes |
Registered: No |
COLOR_SPACE
A string identifying the color space of the MJ2 file. Allowable values are:
|
Value |
Description |
|
sLUM |
The luminance (monochrome) space. |
|
sRGB |
The red, green, blue color space. This is a reasonably good model for color imagery which has been corrected for display on a monitor. |
|
sYCC |
A three-component color space derived by applying the standard YCbCr color transform to RGB data. The YCbCr transform is identical to the irreversible color transform defined by JPEG2000 at the code stream level. This property can be set to sYCC when you are writing RGB data and the YCC property is set to 1 (true). Note: Some players and codecs expect this COLOR_SPACE property to be set to sRGB even when the frames were compressed using YCC. |
When writing a file, this property must be set prior to the first call to IDLffMJPEG2000::SetData in order to take effect. A value set to this property before calling SetData is always honored. If you do not set this property before calling SetData, the property value will be automatically set based on the dimensions of the data passed to SetData as follows:
|
SetData Data Characteristics |
Resulting COLOR_SPACE |
|
Number of frame components equals 3 |
sRGB |
|
PALETTE property has been set |
|
|
Number of frame components not equal to 3 |
sLUM |
Note: If you are writing 3-band monochrome data, you must set COLOR_SPACE to sLUM prior to the first call to SetData.
|
Property Type |
String |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |
COMMENT
A string providing a descriptive comment for the MJ2 file. When writing a file, this property must be set prior to the first call to IDLffMJPEG2000::SetData. The maximum length is 65,534 characters.
|
Property Type |
String |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |
CURRENT_FRAME
A long value that contains the frame number of the last frame compressed (in a file open for writing) or decompressed (in a file open for reading).
|
Property Type |
Long |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: No |
Init: No |
Registered: No |
DIMENSIONS
A two element array giving the dimensions [width, height] of a frame.
In a file that is open for writing (WRITE=1), this property must be set prior to the first call to IDLffMJPEG2000::SetData in order to take effect. If you call SetData before specifying this property, the DIMENSIONS property value will be automatically set based on the dimensions of the data passed to SetData.
|
Property Type |
Long |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |
Regardless of whether the DIMENSIONS property is set before the first call to SetData or is set by default based on data dimensions, each subsequent data array must have dimensions identical to that which has been set in order to avoid a SetData error.
DURATION
A floating-point value that returns the length of a movie in seconds. When reading an MJ2 file, this property comes from the file. When writing an MJ2 file, this property is automatically calculated and set in the MJ2 file based on the number of frames written and the TIMESCALE property value.
|
Property Type |
Float |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: No |
Init: No |
Registered: No |
FILENAME
A string that specifies the full path and name of the file associated with the MJ2 file being read or written. The property can only be set as the Filename argument during IDLffMJPEG2000 object creation. See the IDLffMJPEG2000::Init method for details.
|
Property Type |
String |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: No |
Init: No |
Registered: No |
FRAME_BUFFER_LENGTH
A long value that specifies the number of frames that can be held in the frame buffer when doing a sequential playback or when writing an MJ2 file. This property is used by the background read or write processing thread. You can change this property value to enable high speed MJ2 file playback and creation
This property must be set prior to calling IDLffMJPEG2000::StartSequentialReading when reading a file, or prior to the first call to IDLffMJPEG2000::SetData when writing a file. If this property is not set then the default value of 3 is used.
|
Property Type |
Long |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |
FRAMES_IN_BUFFER
A long value that returns the number of frames in the read or write frame buffer. When sequentially reading an MJ2 file, this property indicates the number of decompressed frames currently available in the frame buffer. When writing an MJ2 file, this property indicates the number of frames in the write frame buffer waiting to be compressed by the processing thread.
|
Property Type |
Long |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: No |
Init: No |
Registered: No |
FRAME_PERIOD
A long value indicating the duration of a frame in ticks, which in conjunction with the TIMESCALE property, determines the playback rate.
When this property is set, it is applied to the current frame and every subsequent frame in an MJ2 file unless it is overridden by the IDLffMJPEG2000::SetData FRAME_PERIOD keyword. When retrieving this property, it returns the frame period of the first frame in the file (when a file is first opened for reading) or the frame period of the current frame that is being read or written.
MJ2 players will typically attempt to playback the frames using the FRAME_PERIOD property. However, the actual playback rate may be slower than the desired rate if it exceeds the rate at which the MJ2 player can actually decompress and display frames.
The default FRAME_PERIOD value is 1000.
|
Property Type |
Long |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |
Note: You should always append the value you set with “L” to ensure it is interpreted as a long value. For example, use FRAME_PERIOD=2000L.
Computing Playback Rate
To compute the playback rate, divide the FRAME_PERIOD value by the TIMESCALE property value. Take 1 (frame) over this value (seconds per frame) to get the number of frames per second. For example, the default FRAME_PERIOD (1000) and TIMESCALE (30,000) translate into a playback rate of approximately 30 frames per second:
Leaving the TIMESCALE property value unchanged, you can change the FRAME_PERIOD rate to control playback speed. A smaller FRAME_PERIOD rate speeds up playback; a larger FRAME_PERIOD rate slows playback.
N_COMPONENTS
A long value that indicates the number of components (also known as bands or channels) in a frame.
When writing a file, this property must be set prior to the first call to IDLffMJPEG2000::SetData in order to take effect. If you call SetData before specifying this property, the N_COMPONENTS property value will be automatically set based on the number of components in the first frame of data passed to SetData.
|
Property Type |
Long |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |
N_FRAMES
A long value that returns the number of frames in the file. This is either the total number of frames (in a file that is being read), or the number of frames added to the file prior to requesting this property (in a file that is being written).
|
Property Type |
Long |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: No |
Init: No |
Registered: No |
N_LAYERS
A long value that indicates the number of quality layers used to build each frame. Possible values range from 1 to 244. Each layer contains the information required to represent the frame at a higher quality, given the information from all the previous layers. When a frame has more than one layer, the previous layers are used to build the frame at the requested layer value.
When writing an MJ2 file:
- If N_LAYERS is greater than one and the BIT_RATE property is not set, the layers will be assigned roughly logarithmically-spaced bit rates
- If N_LAYERS is greater than one and the BIT_RATE property has been set, the BIT_RATE property vector governs the number of bytes allocated to each layer
- If the REVERSIBLE property is true, then the last layer, in conjunction with the previous layers (if there are any), will produce a lossless frame
Suppose you have specified 3 layers. The first layer will undergo the greatest compression and be of the lowest quality. Successive layers will be less compressed and contain more clarity. If the REVERSIBLE property is set, the last layer will be equivalent to the original data.
This property must be set prior to the first call to IDLffMJPEG2000::SetData to take effect. If it is not set before calling SetData, the property will be set to the default value, 1. The largest possible value is 244.
|
Property Type |
Long |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |
Note: When you are playing an MJ2 animation, you can set the MAX_LAYERS keyword to IDLffMJPEG2000::StartSequentialReading or IDLffMJPEG2000::GetData to control what quality layers will be displayed.
N_LEVELS
An integer that specifies the number of wavelet decomposition (resolution) levels, or stages, in the range of 0...15 where a value of zero indicates no wavelet transform (the full resolution image). For instance, if you have a 1024 by 1024 pixel image, the resolution of each successive level is half of the width and height of the preceding one:
|
level 0 |
1024 by 1024 |
|
level 1 |
512 by 512 |
|
level 2 |
256 by 256 |
Tip: This level/resolution scheme is similar to image pyramids.
If this property is not set prior to the first call to IDLffMJPEG2000::SetData then this property will be automatically set to the default value. If the PALETTE property has been set, the default value is 0. Otherwise, the default value is 5.
|
Property Type |
Long |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |
Note: When you are playing an MJ2 animation, you can set the DISCARD_LEVELS keyword to IDLffMJPEG2000::StartSequentialReading or IDLffMJPEG2000::GetData to control what level of data will be displayed.
N_TILES
A long value that returns the number of tiles in a component.
|
Property Type |
Long |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: No |
Init: No |
Registered: No |
PALETTE
A byte or integer array that specifies the red, green, and blue values of the color lookup table to be associated with the color indices found in the frame. An MJ2 file that contains a palette (also known as a color table) stores frames that have only a single component consisting of the color indices.
If reading a file that contains a palette, 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 file does not have a palette, this property will return a scalar zero.
When writing an MJ2 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. The value n must be a power of 2 and ≤ 256.
This property must be set prior to the first call to IDLffMJPEG2000::SetData if it is to be used.
Note: The default values of several properties depend upon the presence of a palette. When a palette is specified, N_LEVELS=0, REVERSIBLE=1, and YCC=0 are set by default.
|
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. Progression order may be LRCP, RLCP, RPCL, PCRL, or CPRL where the progression identifiers are L = layer, R = resolution, C = component, and P = position. The four progression identifiers have the following interpretations:
|
Value |
Meaning |
|
L |
Layer: A series of one or more quality layers, each contributing a quality increment for the entire frame at full resolution. The quality layers may be interpreted as sub-bitplanes containing the frame data at a specified, possibly fractional, bit-rate. |
|
R |
Resolution: Each resolution level of a frame, which corresponds to the N_LEVELS keyword used in encoding, and can be considered to contain the frame data at a given size or resolution. Each level adds another level of detail to the previous levels. |
|
C |
Component: Each frame component of the above. |
|
P |
Position: Each position (tile) within the frame component. |
Data is written to the output file iteratively over the four progression identifiers in this property string—that is, the output is written in four nested iteration levels. The first character refers to the outermost level of the iteration, while the last refers to the innermost level. For example, “LRCP” means that an image is encoded as shown in the preceding table, with quality being the outermost loop.
In the following PCRL example, if a frame consists of 2 quality layers, 5 resolution levels, 3 components, and 16 positions or tiles, the frame 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 frame at a given quality level before sending the next quality refinement.
Note: When encoding a large frame 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 using a progression order of CPRL.
Note: When writing frames with multiple components and the number of layers is greater than one, the progression order can be set to RPCL, PCRL, CPRL. The LRCP and RLCP progression orders are not usable in this case.
This property is ignored when MJ2 files are being read. The default value is LRCP.
|
Property Type |
String |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |
REVERSIBLE
A Boolean value that specifies whether or not you can get the original JP2 data from an MJ2 frame as follows:
|
0 |
Frames are irreversible (lossy). The default. |
|
1 |
Frames are reversible (lossless). |
Typically, it will be faster to compress and decompress lossy frames, but this is dependent upon image content.
To create reversible (lossless) frames, you must set this property to 1 prior to the first call to IDLffMJPEG2000::SetData. If the PALETTE property is set, this property is automatically set to 1 (reversible, lossless frames). If you have not set the PALETTE property, and you call SetData before setting this property, it will be set to the default value, 0 (irreversible, lossy frames).
|
Property Type |
Boolean |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |
SCAN_MODE
A long value that returns whether a frame is stored in a progressive format or in an interlaced format.
Note: The IDLffMJPEG2000 object only supports the progressive format—this object can only read and write MJ2 files in the progressive format.
In the progressive format, all the rows are returned or set in one call. In the interlaced format (not supported), the even rows are returned in one call and the odd rows are returned in the next call. Possible values are:
|
0 |
Progressive (supported) |
|
1 |
Interlaced with the top row first (not supported) |
|
2 |
Interlaced with the bottom row first (not supported) |
The default value is 0 and cannot be set.
|
Property Type |
Long |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: No |
Init: No |
Registered: No |
SIGNED
A long value that indicates whether the frame data is signed or unsigned as follows:
|
0 |
Unsigned frame data (the default) |
|
1 |
Signed frame data |
If IDLffMJPEG2000::SetData is called before setting this property, it will be set to the default value, 0.
|
Property Type |
Long |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |
STATE
A long value that returns whether or not a background read or write processing thread is currently running. Possible values are:
|
0 |
Background thread is idle |
|
Non-zero |
Background thread is running |
|
Property Type |
Long |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: No |
Init: No |
Registered: No |
TILE_DIMENSIONS
A two-element vector indicating the [width, height] of each tile. If a frame component contains only one tile, this property will be automatically set to the DIMENSIONS of the frame.
When writing frame component(s) with more than one tile, this property must be set prior to the first call to IDLffMJPEG2000::SetData.
|
Property Type |
Long vector |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |
TIMESCALE
This property indicates the number of ticks in a second. This property, in conjunction with the FRAME_PERIOD period property, controls the playback rate.
The default value is 30,000.
|
Property Type |
Long |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |
WRITE
A Boolean value that indicates whether a file is open for reading or writing as follows:
|
0 |
File is read-only (the default) |
|
1 |
File is open for writing |
This property can only be set during initialization (see IDLffMJPEG2000::Init) or retrieved.
|
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 MJ2 XML box. When creating a MJ2 file, call this property with a string value to add the corresponding XML to the MJ2 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 MJ2 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 MJ2 files.
Here are a few tips for working with XML in MJ2 files and IDLffMJPEG2000 objects:
- An XML box can hold plain text as well as XML text.
- There can be multiple XML boxes in MJ2 files. For example, in a MJ2 file, you could add an XML box for each frame.
- To parse the MJ2 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 MJ2 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.
|
Property Type |
String |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |
YCC
A Boolean value indicating whether a frame (that consists of 3 components) has or should undergo conversion from the RGB to the YCC Luminance-Chrominance color space as follows:
When reading a file:
|
0 (false) |
Data was not originally converted from the RGB color space to the YCC color space. |
|
1 (true) |
Data was converted from the RGB color space to the YCC color space. Consider returning all three frame components when calling IDLffMJPEG2000::GetData or IDLffMJPEG2000::StartSequentialReading so that the YCC data can be correctly transformed back to the RGB color space. |
When writing a file:
|
0 (false) |
Data should not be converted from the RGB color space to the YCC color space. When a PALETTE has been specified, YCC is automatically set to 0. |
|
1 (true) |
Convert RGB data to YCrCb. This is the default for a frame that has 3 components. The RGB components are automatically converted to YCrCb, and then written. Note: For the RGB-to-YCC conversion to occur, all three components must be provided at the same time. If the components are provided in separate calls to IDLffMJPEG2000::SetData, the YCC conversion is not performed. |
Note: The default action that converts RGB to YCC when writing a file may be overridden by explicitly setting YCC to zero.
If the frame 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 both compression and decompression performance for RGB frames. MJPEG2000 readers will then convert frame data back to RGB. The default value is 1 except as noted above.
|
Property Type |
Boolean |
||
|
Name String |
not displayed |
||
|
Get: Yes |
Set: Yes |
Init: Yes |
Registered: No |