RFC 24: GDAL Progressive Data Support

Author: Norman Barker
Contact: nbarker@…
Status: Development

Summary

Provide an interface for data streaming support in GDAL. The RFC focuses on JPIP, but should be generic enough to apply to other streaming / progressive formats.

Definitions

JPIP: JPEG 2000 Interactive Protocol

Objective

To provide an interface to a streaming data source in a convenient manner for RasterIO operations within GDAL and to expose this interface via swig.

Note this RFC originally explored using an Observer pattern as per implementations in Java ​imageio update but after detailed discussions with ​Tamas Szekeres, Even Rouault and Adam Nowacki a simpler interface is proposed to reduce the potential for problems by having the callback implemented by another thread.

Each swig wrapper language will have its own design pattern for event handling (the image updates) and the proposed interface will allow that pattern implementation to be provided, even if simulated.

Implementation

The implementation is a definition of an interface for streaming support data support within GDAL. Concrete implementations of this interface will follow. Currently the most convenient JPIP streaming developer library is ​Kakadu however since GDAL is also a developer library, only stubs can be distributed to conform to Kakadu licensing (JP2KAK). Vendors are also interested in using GDAL for streaming support and a standard interface will allow these plugins to be incorporated. e.g. ​ECW, ​MrSID.

To support reading streaming data from a progressive server it will be necessary to communicate between different threads. In general it's safer not to do this by shared memory, but by explicit message passing using asynchronous queues. e.g. ​Glib Asynchronous Queues, ​Wikipedia Message Queues

This interface results in a subclass of GDALDataset, and currently supports dataset level access only, not raster band access. Access to the stream per band is not precluded by this design and can be added as a later RFC.

Class Diagram

Implementing GDALAsyncDataset allows the user application to decide when and how often the updates occur, and reduces the potential negative impacts of threading by providing a clear synchonization point, NextAsyncRasterIOMessage().

GDALAsyncRasterIOMessage contains a buffer that is described the getParameters() function which returns a struct with the parameters passed into ProgressiveRasterIO. Note that no lock() / unlock() on the buffer is required as each buffer represents a call to the server and is a separate instance.

Each GDALAsyncRasterIOMessage will be small, it only contains the data for the currently requested window at a particular resolution level. These requests are usually proportional, i.e small window implies high resolution, large window implies low resolution.

Sequence of Events

1. GDALOpen calls Open(Xxx) on all registered drivers with a jpip:// parameter and the first driver that returns a response is the format driver for that user.
2. Streaming image servers are usually session based so that the server knows which data has already been sent to the client.
3. ProgressiveRasterIO requests a region of the image from the driver. In the specific case of JPIP, the dimensions of the input buffer, bufXSize, bufYSize and the region Xoff, yOff, xSize, ySize are used to calculate the best resolution level and the corresponding fsiz and rsiz parameters to the server. i.e. bufXSize and bufYSize are the desirable screen size, and the region size is at the base resolution of the image.
4. Check whether we need to stop making requests to the server.
5. In response to the ProgressiveRasterIO call the format driver makes an asynchronous request to the server for data matching the requested resolution and window.
6. The driver parses the response from the server and sets the buffer on GDALAsyncRasterIOMessage.
7. GDALAsyncRasterIOMessage object is added to the format driver internal data queue. If the queue size limit is exceeded the last message drops off. Note the data for this message is still retained in the wavelet cache for the driver - just the rendering is discarded.
8. Check there is a data message to render.
9. Retrieve the next data message and render / process.
10. Finished with the data message, release the resource associated with it.