IDLffJPEG2000::GetData

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

Syntax

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.

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 indicate the number of highest resolution levels which will not appear in the result. Image dimensions are divided by 2 to the power of this number. For example, if the image in the object has dimensions of 1024 x 1026, and DISCARD_LEVELS is set to 3, the resulting image will have dimensions of 128 x 129, which is the ceiling of [1024, 1026] divided by 2³. The number of resolution levels in a file may be determined by checking the value of the N_LEVELS property.

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.

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.

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, data from the first component is duplicated in the other components.

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