IDLnetJPIP::GetData

Use this method to stream image data from a remote JPIP server, or to fetch any portion of the image. Whether you use this method in the asynchronous or synchronous mode, it does not return until it retrieves and locally decompresses all of the requested image data from the remote server.

Prior to calling GetData,you must set the SERVER_NAME property and call the Open method. IDL will throw an error if you do not call the Open method prior to calling GetData. You can call GetData multiple times to retrieve various portions of the image.

GetData has two modes of operation: asynchronous and synchronous. By default GetData operates in the asynchronous mode. See the SYNCHRONOUS keyword for details.

In the asynchronous mode GetData can make two different callbacks. The first callback provides progressive image updates to the user. The second callback provides status updates to the user. Both callbacks provide a way to cancel the GetData request.

Note: This method will throw an error if there is a failure. Use a catch statement to trap errors.

Syntax

Result = Obj->[IDLnetJPIP::]GetData( [, COMPONENT=value] [, DISCARD_LEVELS=value] [, INTERVAL=value][, MAX_LAYERS=value] [, N_COMPONENTS=value] [, ORDER=value] [, REGION=value] [, SYNCHRONOUS=value] )

Return Value

An array with two or three dimensions containing the image data streamed from the remote JPIP server. Dimensions of the result are: [3, Width, Height] if three components were requested or [Width, Height] if one component was requested.

The data type of the result is automatically determined using the bit-depth and signed properties of the returned components. For bit-depths <= 8, the result will be of type byte. For bit-depths >= 9 and <= 16, the result will be of type integer or uint. Components with differing bit-depths are not supported. Components which are a mix of signed and unsigned data are not supported.

Arguments

None

Keywords

COMPONENT

This keyword is optional integer input. Set this keyword to the desired starting component to be returned. The default is 0. The number of components can be determined by checking the value of the N_COMPONENTS property.

DISCARD_LEVELS

This keyword is optional integer input. Set this keyword to the level desired. The default is 0 which means no data will be discarded. For example, if the requested region has the dimensions of 1024 x 1024 and this keyword is 0, the returned data will be 1024 x 1024. If the requested region has the dimensions of 1024 x 1024 and this keyword is 1, the returned data will be 512 x 512. If the requested region has the dimensions of 1024 x 1024 and the discard level is 2 then the returned data will be 256 x 256.

The number of discard levels can be determined by checking the value of the N_LEVELS property.

INTERVAL

This keyword is an integer and optional. This keyword, in milliseconds, determines how frequently the progressive callback function is called. The default value is 1000 (1 second). To receive progressive callbacks, you must set the PROGRESSIVE_CALLBACK_FUNCTION property. The progressive callback function is called when the interval elapses and there is new data available. If the interval elapses and no new data is available, IDL does not call the progressive callback function. If the SYNCHRONOUS keyword is set,IDL will not make callbacks.

MAX_LAYERS

This keyword is optional integer input. Set this keyword to the highest quality layer desired. The default is the value of the N_LAYERS property, which means IDL combines all of the available layers. For example, when the MAX_LAYERS keyword is 1 then IDL returns only the data from the first layer. When the MAX_LAYERS keyword is 3, then IDL combines the data from the first, second, and third layers to form the returned data.

You can determine the number of quality layers in a image by checking the value of the N_LAYERS property.

N_COMPONENTS

This keyword is and optional integer with possible values of either 1 or 3. The starting component is set by the COMPONENT keyword.

ORDER

This keyword is optional integer input. JPEG2000 images are 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 JPEG2000 image data to match IDL's bottom-to-top order. Setting ORDER to a nonzero value will return the image data without doing a vertical flip.

REGION

Optional. Set this keyword to a four-element vector containing the rectangular region of the image to read. The region is specified as [StartX, StartY, Width, Height]. The region must lie with the image boundaries, otherwise IDL produces an error. If you do not set REGION, the StartX will be set to 0, StartY will be set to 0, Width will be set to the Image Width, and Height will be set to the Image Height.

SYNCHRONOUS

This keyword is an optional boolean input and defaults to 0. Set SYNCHRONOUS to 0 to operate GetData in asynchronous mode, and to 1 to operate in synchronous mode. Whether you use this method in the asynchronous or synchronous mode, it does not return until it retrieves and decompresses all of the requested image data from the server.

In the asynchronous mode, GetData can provide:

progressive image callbacks,
status callbacks,
and the ability to cancel the request.

In the synchronous mode, GetData does not provide any of the above functionality (progressive callbacks, status callbacks, or ability to cancel a request).

Additional Information on GetData

Canceling a GetData

You can cancel GetData via the return value of the callback function. See the callback operation description, below, for details.

Status Callback Operation

The caller must set the STATUS_CALLBACK_FUNCTION property to receive status callbacks from this method. GetData only issues callbacks in the asynchronous mode. The callback is made to a PRO code function which takes two IDL variables as input parameters and returns an integer.

Pro Code Callback Prototype

Function Callback_Function_Name, StatusInfo, CallbackData

: :

return vCancelFlag

Callback Prototype Details

Callback_Function_Name: The name of the PRO code function called is set in the STATUS_CALLBACK_FUNCTION property.
Status_Info: The first input parameter is an array of IDL strings that contain status information about GetData. When the caller is a user interface (UI), it will typically display the array of strings in a text widget.
Callback_Data: The second input parameter is the STATUS_CALLBACK_DATA property that can be set prior to calling GetData. The callback data property is passed onto the callback function unmodified. The contents of the callback data are determined by the user. When the caller is a UI, the callback data will typically contain a pointer to a structure containing all the info needed to display the status info strings. If the callback data property has not been set, the callback data will be an integer set to 0.
Return Value: The return value is an integer. You can use the return value to cancel GetData. When the return value is 1 GetData will continue and when 0, GetData will be canceled. When the return value indicates that the GetData is to be canceled this method will cancel the stream from the remote server. When the caller is a UI and it has a cancel button, the UI can check for a cancel widget event during each callback.

Progressive Callback Operation

The caller must set the PROGRESSIVE_CALLBACK_FUNCTION property to receive progressive callbacks from this method. GetData only issues callbacks in the asynchronous mode. The callback is made to a PRO code function. The function takes two IDL variables as input parameters and returns an integer.

Pro Code Callback Prototype

Function Callback_Function_Name, ImageBuffer, CallbackData

: :

return vCancelFlag

Callback Prototype Details

Callback_Function_Name: Set the name of the PRO code function called in the PROGRESSIVE_CALLBACK_FUNCTION property.
ImageBuffer: The first input parameter is an ImageBuffer containing the current state of the requested data. During each progressive callback, the image data will become progressively more complete. Display the progressive image updates in a UI so that the user sees the image build up to its final results as more of the image data is streamed from the remote JPIP server. The ImageBuffer is an array with two or three dimensions containing the image data streamed from the remote JPIP server. Dimensions of the result are: [3, Width, Height] if three components were requested or [Width, Height] if one component was requested. The data type of the ImageBuffer is automatically determined using the bit-depth and signed properties of the returned components. For bit-depths <= 8 the result will be of type byte. For bit-depths >= 9 and <= 16 the result will be of type integer or uint. Components with differing bit-depths are not supported. Components which are a mix of signed and unsigned data are not supported
Callback_Data: The second input parameter is the PROGRESSIVE_CALLBACK_DATA property that can be set prior to calling GetData. The callback data property is passed onto the callback function unmodified. The contents of the callback data is determined by the user. When the caller is a UI, the callback data will typically contain a pointer to a structure containing all the info needed to display the image data. If the callback data property has not been set then the callback data will be an integer set to 0.
Return Value: The return value is an integer. The return value can be used to cancel GetData. When the return value is 1 GetData will continue and when 0, GetData will be canceled. When the return value indicates that GetData is to be canceled this method will cancel the stream from the remote server. When the caller is a UI and it has a cancel button, the UI can check for a cancel widget event during each callback.

Version History

8.3	Introduced