FDO RFC 2 - Support Raster Min/Max Fetching

This page contains a change request (RFC) for the FDO Open Source project. More FDO RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	Mar 21, 2007
Last Modified	Timestamp
Author	Frank Warmerdam
RFC Status	Draft
Implementation Status	pending
Proposed Milestone	3.3.0.0
Assigned PSC guide(s)	Greg Boone/Frank Warmerdam
Voting History	TBD
+1
+0
-0
-1

Overview

The purpose of this RFC is to allow FDO users to determine the dynamic range of a raster so that they can do effective scaling for display purposes when interfacing with FDO providers that support the FdoIRaster and FdoIRasterDataModel interface.

Motivation

The FDO API FdoRasterDataModel class currently includes a property to determine the number of bits per pixel returned in an FdoIRaster data stream. The FdoIRaster data stream contains the raw raster image data.

/ \brief
/ The FdoRasterDataModel specifies the data type and organization
/ of raster data retrieved and stored. Using this class and the image
/ extents in width and length, the binary format of the image data returned
/ by and accepted by the FdoIStreamReader class can be interpreted.
class FdoRasterDataModel: public !FdoIDisposable
{
public:

…
…

/ \brief
/ Get the number of bits per pixel.
/
/ \return
/ Returns the number of bits for each pixel. For multi-channel
/ data the bits per channel will be this value devided by the numer of
/ channels. For example, RGB data has three channels, so if this
/ method returns twelve, each channel is four bits.
/
FDO_API virtual !FdoInt32 GetBitsPerPixel ();

/ \brief
/ Set the number of bits per pixel.
/
/ \param bpp
/ The number of bits per pixel desired.
/ Values of 1, 4, 8, 16, 24, 32, 48 and 64 bits per channel may
/ be supported. Others values (i.e. indivisible by the number of channels)
/ are likely to raise a FdoException.
/
FDO_API virtual void SetBitsPerPixel (!FdoInt32 bpp);

…
…

};

However, returning only the bits per pixel is not sufficient to quickly and efficiently scale the raster for display in cases where dynamic contrast stretching is appropriate. In cases where stetching is needed (for instance 16bit greyscale images or 4bit images represented as 8bit) it is often the case that the full dynamic range of the data type is not being used. In order to scale the raster to 0-255 for display it is necessary to know what actual range of values is used. For some data types (floating point elevations for instance) there is no obvious range implicit in the data type.

Client application can work out the range by making a first pass reading the whole dataset to scan for a min/max, and then pulling out subareas they are actually interested in and scaling those. But this is very expensive, and discards any opportunity to use pre-existing metadata from the datasource to establish the value min/max range.

This issue was identified by IKonus, a corporate user of the FDO API.

Proposed Solution

The FDO FdoRasterDataModel class will be extended to export the number of bits used per pixel.

/ \brief
/ The FdoRasterDataModel specifies the data type and organization
/ of raster data retrieved and stored. Using this class and the image
/ extents in width and length, the binary format of the image data returned
/ by and accepted by the FdoIStreamReader class can be interpreted.
class FdoRasterDataModel: public !FdoIDisposable
{
public:

…
…

/ \brief
/ Get the number of bits per pixel.
/
/ \return
/ Returns the number of bits for each pixel. For multi-channel
/ data the bits per channel will be this value devided by the numer of
/ channels. For example, RGB data has three channels, so if this
/ method returns twelve, each channel is four bits.
/
FDO_API virtual !FdoInt32 GetBitsPerPixel ();

/ \brief
/ Set the number of bits per pixel.
/
/ \param bpp
/ The number of bits per pixel desired.
/ Values of 1, 4, 8, 16, 24, 32, 48 and 64 bits per channel may
/ be supported. Others values (i.e. indivisible by the number of channels)
/ are likely to raise an FdoException.
/
FDO_API virtual void SetBitsPerPixel (!FdoInt32 bpp);

/ \brief
/ Get the number of bits used per pixel.
/
/ \return
/ Returns the number of bits used for each pixel. For multi-channel
/ data the bits used per channel will be this value devided by the numer of
/ channels. For example, RGB data has three channels, so if this
/ method returns twelve, each channel uses four bits.
/
FDO_API virtual !FdoInt32 GetBitsUsedPerPixel ();

/ \brief
/ Set the number of bits used per pixel.
/
/ \param bpp
/ The number of bits per used per pixel.
/
/ \remarks
/ This method is primarily being defined for object construction purposes
/ within the provider and would not be called by client applications.
FDO_API virtual void SetBitsUsedPerPixel (!FdoInt32 bpp);

…
…

};

The new property will also be added to the FDO Managed API.

Notes

This API change is applicable for all raster formats. Image formats who do not explicitly advertise their bitsUserPerPixel will have this value set to the value of bitsPerPixel.

This ECO is being written in order to better support ongoing development using the FDO Raster providers. Existing customers such as AutoCAD Map and MapGuide have implemented work-arounds to calculate the bitsUsedPerPixel manually. While this calculation affects performance, the cost is slight.

Test Plan

Raster Provider unit tests should be expanded to include usage of the new GetBitsUsedPerPixel Property

Impact of Not Implementing this ECO

If this ECO is not implemented, clients such as IKonus will have to calculate the number of bits used manually and accept the impact on performance.

Funding/Resources

Autodesk to provide resources / funding.