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 divided by the number 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 stretching is needed (for instance 16bit grey scale 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 applications can work out the range by making a first pass reading the whole dataset to scan for a min/max, and then pulling out sub areas they are actually interested in and scaling those. But this is very expensive, and discards any opportunity to use pre-existing metadata from the data source to establish the value min/max range.

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

Proposed Solution

The FDO !FdoIRaster interface will be extended to export the min and max values supported by the raster.

/// \brief
/// The !FdoIRaster 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 FdoIoStreamReader class can be interpreted.
class FdoIRaster : public FdoIDisposable
{
public:
...
    FdoDouble         m_min;
    FdoDouble         m_max;
    FdoBoolean        m_minMaxSet;
    FdoBoolean        m_minMaxApproximate;
...
public:
...
    /// \brief
    /// Get the raster band’s min/max values.
    ///
    /// Returns min/max raster values suitable to use for linearly scaling this
    /// raster for display purposes.  For RGB or RGBA images the min/max values
    /// are considered to be approximate for red, green and blue samples, but
    /// should not be applied to the alpha sample. 
    /// 
    /// If the force parameter is true, this call may result in a substantial
    /// delay while the provider scans the image to compute appropriate min/max
    /// values. If force is false then the provider is expected to do only
    /// minimal work to produce a value, or to fail.  
    ///
    /// Note that failing to return requested values will not trigger an
    /// exception if the force argument is false. 
    ///
    /// If the approx_ok argument is false, then any scan to compute min/max
    /// values will scan the whole image.  If approx_ok is true then 
    /// computation of min/max by the provider may be accelerated by using
    /// overview images or a sampling of the full image as deemed appropriate
    /// by the provider as long as the result is likely to still be suitable
    /// for scaling the image. 
    /// 
    /// \remarks
    /// The min and max values will change depending on the current band set 
    /// through the SetCurrentBand method. By default, the current band is set
    /// to the first band.
    /// 
    /// \param min 
    /// Output. The returned minimum
    /// 
    /// \param max 
    /// Output. The returned maximum
    ///
    /// \param force 
    /// Input. True if computation should be forced even if it is expensive
    ///
    /// \param approx_ok 
    /// Input. True if an approximate min/max is acceptable, 
    /// or false if an exact value is required
    /// 
    /// \return
    /// true if min/max have been set with appropriate values, or false if not.
    /// 
    FDO_API virtual bool GetMinMaxValues( FdoDouble &min, 
                                          FdoDouble &max, 
                                          bool force, 
                                          bool approx_ok ) = 0;

    /// \brief
    /// Sets the raster band’s min/max values.
    /// 
    /// \remarks
    /// The min and max values will change depending on the current band set 
    /// through the SetCurrentBand method. By default, the current band is set
    /// to the first band. 
    ///
    /// This value should not be called by client applications.
    ///
    /// \param min 
    /// Input. The minimum raster value
    /// 
    /// \param max 
    /// Inout. The maximum raster value
    /// 
    /// \remarks
    /// This method is primarily being defined for object construction purposes
    /// within the provider and would not normally be called by client 
    /// applications.
    ///
    FDO_API virtual void SetMinMaxValues( FdoDouble min, 
                                          FdoDouble max ) = 0;
...
};   

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

Notes

This API change is applicable for all raster formats. For raster formats where the min/max cannot be deduced from the dataset, the provider should provide a mechanism to scan the image for min/max values if forced computation is requested.

This RFC 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 scaling range manually.

Unresolved

• When the raster data model bitsPerPixel is changed to 8, it is unclear how the provider is expected to convert the image to this number of bits per pixel. Should it scale using the min/max described here? Currently the FDO provider just truncates values outside the target pixel type range (as does the underlying GDAL RasterIO() API).

Test Plan

Raster Provider unit tests should be expanded to include usage of the new MinMaxValues 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 to update FDO core, and proprietary raster provider. Frank Warmerdam to implement required changes to GDAL based raster provider.