IDLgrImage::Init

The IDLgrImage::Init function method initializes the image object.

Note: Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: if you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Syntax

Obj = OBJ_NEW('IDLgrImage' [, ImageData] [, PROPERTY=value] [ ,NO_COPY])

or

Result = Obj->[IDLgrImage::]Init([ImageData] [, PROPERTY=value] [ ,NO_COPY])     (In a lifecycle method only.)

Return Value

When this method is called indirectly, as part of the call to the OBJ_NEW function, the return value is an object reference to the newly-created object.

When called directly within a subclass Init method, the return value is 1 if initialization was successful, or zero otherwise.

Arguments

ImageData

An array of data values to be displayed as an image. Since by default IDL maintains the image data using the byte type, in most cases the input data values should range from 0 through 255. If this argument is not already of byte type, it is converted to byte type when the image object is created.

Note: The INTERNAL_DATA_TYPE property controls the type of data used to store ImageData. If the IDLgrImage object has an associated IDLgrShader object, it may be useful to use floating-point values to store the image data.

Image objects can have a single channel (one value per pixel—greyscale or color indexed), two channels (greyscale and alpha), three channels (red, green, and blue), or four channels (red, green, blue, and alpha). The alpha channel, if present, determines the transparency of the pixel. The BLEND_FUNCTION property controls the interpretation of the alpha channel values. With channels, the data value of 0 specifies minimum intensity and the data value of 255 specifies maximum intensity. The alpha channel values are also specified in the image data in the range 0 through 255, with an image data value of 0 corresponding to an alpha blend factor of 0 and an image data value of 255 corresponding to an alpha blend factor of 1.0. ImageData can be any of the following, where n is the width of the image, and m is the height:

• An n x m array of color lookup table indices.
• An n x m greyscale image, or a 2 x n x m, n x 2 x m, or n x m x 2 greyscale image with an alpha channel. (The alpha channel is ignored if the destination device uses indexed color mode.)
• A 3 x n x m, n x 3 x m, or n x m x 3 RGB image, or a 4 x n x m, n x 4 x m, or n x m  x 4 RGB image with an alpha channel.

If the array has more than one channel, the interleave is specified by the INTERLEAVE property.

Note: The value specified by the ImageData argument is used to initialize the value of the DATA property of the IDLgrImage object.

Keywords

Any property listed under IDLgrImage Properties that contains the word “Yes” in the “Init” column of the properties table can be initialized during object creation using this method. To initialize the value of a property, specify the property name as a keyword set equal to the appropriate property value.

All other keywords are passed to the superclass of this object.

NO_COPY

If this keyword is set to a non-zero value, it relocates the image data from the input variable to the image object, leaving the input variable ImageData undefined. Only the ImageData argument is affected. The following example illustrates that the data is moved from the input variable.

imgdata = BYTSCL(DIST(300))

oImg = OBJ_NEW('IDLgrImage', imgData, /NO_COPY)

HELP, imgdata

; IDL prints IMGDATA UNDEFINED = <Undefined>

If this keyword is omitted, the input image data will be duplicated and a copy will be stored in the object.

Version History

5.0	Introduced
6.2	Added NO_COPY keyword