IDLffJPEG2000::GetData

The IDLffJPEG2000::GetData function method returns image data from the IDLffJPEG2000 object.

Syntax

Result = Obj->[IDLffJPEG2000::]GetData( [, COMPONENT=value] [, DISCARD_LEVELS=value] [, MAX_LAYERS=value] [, N_COMPONENTS=value] [, ORDER=value] [, REGION=value] [, /RGB] [, TILE_INDEX=value])

Return Value

An array with two or three dimensions containing the image data from the object. Dimensions of the result are: [3, Width, Height] if the RGB keyword is set; or [nComponents, Width, Height] if the RGB keyword is not set. nComponents is the number of components present in the file. Images with only one component (which are read with RGB not set) return a two dimensional array [Width, Height].

The data type of the result is automatically determined using the bit-depth and signed properties of the returned components. For bit-depths ≤ 8 (or if RGB is set) the result will be of type byte. For bit-depths ≥ 9 and ≤ 16 the result will be of type integer or uint. For bit-depths > 16 the result will be long or ulong. Components with differing bit-depths will be returned using the largest bit-depth. Components which are a mix of signed and unsigned will be returned as signed.

Note: If the PERSISTENT keyword was set to zero when the object was created, the object may not be accessed after GetData is called, with the exception of the GetProperty and Cleanup methods.

Note: If the data in the file was transformed from RGB to YCC before saving, the library will only transform back from YCC to RGB if all three components are read in simultaneously. Reading in each component separately will return the data in the YCC space. The YCC property may be used to determine if the RGB-to-YCC conversion took place. If YCC is true, you may wish to avoid using the COMPONENT or N_COMPONENTS keywords.

Keywords

COMPONENT

Set this keyword to an integer giving the index of the component at which to start reading. The number of components to read may be specified using the N_COMPONENTS keyword. The default is COMPONENT=0.

DISCARD_LEVELS

Set this keyword to an integer that indicates the number of resolution levels to be discarded, starting with the highest resolution level (the full image).

For example, setting this keyword equal to 2 will discard the two highest resolution levels, the full- and half-resolution images. The returned array will contain the quarter-resolution image.

The resulting image dimensions are given by:

CEIL((Dimensions + Offset)/(2^DL)) - CEIL(Offset/(2^DL))

where Dimensions and Offset are the image dimensions and offset, and DL is the value of DISCARD_LEVELS.

MAX_LAYERS

Set this keyword to the maximum number of quality layers which will appear to be present. 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. A value of 0, the default, implies that all layers should be retained. For example, specifying MAX_LAYERS = 4 processes only the first four quality layers. The number of quality layers in a file may be determined by checking the value of the N_LAYERS property.

N_COMPONENTS

Set this keyword to an integer giving the number of components to read, starting at the component index given by the COMPONENT keyword. If neither COMPONENT nor N_COMPONENTS is specified then all components will be read. If COMPONENT is specified then the default is N_COMPONENTS=1.

ORDER

JPEG2000 images are assumed to be stored in top-to-bottom order, while IDL usually assumes images are in bottom-to-top order. By default (ORDER = 0), GetData will automatically flip the result to match IDL’s bottom-to-top order. Setting ORDER to a nonzero value will return the JPEG2000 image without doing the vertical flip.

Tip: If you are reading a tiled image and displaying the tiles in an IDLgrImage object, using IDL’s default ordering will result in the individual tiles being correctly oriented, but displayed out of sequence. To ensure that tiles and displayed in the correct sequence, set both the ORDER keyword to the GetData method and the ORDER property of the IDLgrImage object to one.

REGION

Set this keyword to a four-element vector containing the rectangular region of the image to read in the canvas coordinate system. The region is specified as [StartX, StartY, Width, Height] ], where StartX and StartY must be in the range 0 ... 2³²-2, and Width and Height must be in the range 1 ... 2³²-1. The region must contain at least some portion of the image, or an error will occur. If the region is larger than the image, or extends outside of the image, then only that portion that lies within the image will be returned.

Note: The region parameters should be specified in the canvas coordinate system, taking into account the canvas offset and canvas dimensions.

RGB

If this keyword is set, the data stream will be interpreted as RGB imagery and all details concerning color transformations (for example: sRGB, sLUM and sYCC), together with restricted ICC-profiles for specifying more general 3-color “RGB-like” spaces, plus indexed color with palettes, are handled automatically. If this keyword is set, the result of this function will always have three components, red, green, and blue; and the dimensions of the result will be [3, Width, Height].

The JPEG2000 standard allows a decorrelating color transformation to be applied to the first three image components. This transformation is identical or similar to the conventional YCbCr color transformation. To determine if this transform has been applied, examine the YCC keyword returned by the ::GetTileProperty method.

If RGB is set and the file contains more than three components, only the first three components are returned. If RGB is set and the file contains less than three components an error is issued.

If RGB is not set, and three components are transferred, and a color transformation has been applied to the input stream, the three components which are encoded in a form of YCC will automatically be converted to RGB. If it is desired to avoid this conversion, then the user should transfer more or less than three components in the call or calls to GetData.

If RGB is not set and the number of components is not three, then each component in the data stream will be placed in the result without interpretation. Result will have dimensions: [N_COMPONENTS, Width, Height].

The RGB keyword may not be specified if the COMPONENT or N_COMPONENTS keywords are present.

TILE_INDEX

Set this keyword to an integer giving the tile index to read. If this keyword is specified then the REGION keyword is ignored.

Examples

This example illustrates the use of GetData to read an image a number of different ways:

;Create object, open file.

a = OBJ_NEW('IDLffJPEG2000', 'boat2.jp2')

 

;Read the entire image.

b = a->GetData()

 

;Read a 512x512 portion of the image, starting

;at column 100, row 200.

b = a->GetData(REGION = [100, 200, 512, 512])

 

;Read the portion of the above, but sub-sample it down by a

;factor of 2, returning an nComponents x 256 x 256 image.

b = a->GetData(REGION = [100, 200, 512, 512], DISCARD_LEVELS=1)

 

;Read only the 2nd component.

;The result will have two dimensions.

b = a->GetData(COMPONENT = 1)

Version History

6.1	Introduced