Changes between Version 2 and Version 3 of FDORfc2


Ignore:
Timestamp:
03/21/07 13:26:30 (18 years ago)
Author:
warmerdam
Comment:

First pass complete.

Legend:

Unmodified
Added
Removed
Modified

  • FDORfc2

    v2 v3  
    2828The 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.
    2929
    30 /// \brief[[BR]]
    31 /// The !FdoRasterDataModel specifies the data type and organization[[BR]]
    32 /// of raster data retrieved and stored. Using this class and the image[[BR]]
    33 /// extents in width and length, the binary format of the image data returned[[BR]]
    34 /// by and accepted by the FdoIStreamReader class can be interpreted.[[BR]]
    35 class !FdoRasterDataModel: public !FdoIDisposable[[BR]]
    36 {[[BR]]
    37 public:[[BR]]
     30{{{
     31/// \brief
     32/// The FdoRasterDataModel specifies the data type and organization
     33/// of raster data retrieved and stored. Using this class and the image
     34/// extents in width and length, the binary format of the image data returned
     35/// by and accepted by the FdoIStreamReader class can be interpreted.
     36class FdoRasterDataModel: public FdoIDisposable
     37{
     38public:
     39...
     40    /// \brief
     41    /// Get the number of bits per pixel.
     42    ///
     43    /// \return
     44    /// Returns the number of bits for each pixel. For multi-channel
     45    /// data the bits per channel will be this value devided by the numer of
     46    /// channels. For example, RGB data has three channels, so if this
     47    /// method returns twelve, each channel is four bits.
     48    ///
     49    FDO_API virtual FdoInt32 GetBitsPerPixel ();
    3850
    39 …[[BR]]
    40 …[[BR]]
    41 
    42     /// \brief[[BR]]
    43     /// Get the number of bits per pixel.[[BR]]
    44     /// [[BR]]
    45     /// \return[[BR]]
    46     /// Returns the number of bits for each pixel. For multi-channel[[BR]]
    47     /// data the bits per channel will be this value devided by the numer of[[BR]]
    48     /// channels. For example, RGB data has three channels, so if this[[BR]]
    49     /// method returns twelve, each channel is four bits.[[BR]]
    50     /// [[BR]]
    51     FDO_API virtual !FdoInt32 !GetBitsPerPixel ();
    52 
    53     /// \brief[[BR]]
    54     /// Set the number of bits per pixel.[[BR]]
    55     /// [[BR]]
    56     /// \param bpp [[BR]]
    57     /// The number of bits per pixel desired.[[BR]]
    58     /// Values of 1, 4, 8, 16, 24, 32, 48 and 64 bits per channel may[[BR]]
    59     /// be supported. Others values (i.e. indivisible by the number of channels)[[BR]]
    60     /// are likely to raise a !FdoException.[[BR]]
    61     /// [[BR]]
    62     FDO_API virtual void !SetBitsPerPixel (!FdoInt32 bpp);
    63 
    64 …[[BR]]
    65 …[[BR]]
    66 
    67 };[[BR]]
     51    /// \brief
     52    /// Set the number of bits per pixel.
     53    ///
     54    /// \param bpp
     55    /// The number of bits per pixel desired.
     56    /// Values of 1, 4, 8, 16, 24, 32, 48 and 64 bits per channel may
     57    /// be supported. Others values (i.e. indivisible by the number of channels)
     58    /// are likely to raise a FdoException.
     59    ///
     60    FDO_API virtual void SetBitsPerPixel (FdoInt32 bpp);
     61...
     62};
     63}}}
    6864
    6965However, 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.
    … …  
    7773The FDO !FdoRasterDataModel class will be extended to export the number of bits used per pixel.
    7874
    79 /// \brief[[BR]]
    80 /// The !FdoRasterDataModel specifies the data type and organization[[BR]]
    81 /// of raster data retrieved and stored. Using this class and the image[[BR]]
    82 /// extents in width and length, the binary format of the image data returned[[BR]]
    83 /// by and accepted by the FdoIStreamReader class can be interpreted.[[BR]]
    84 class !FdoRasterDataModel: public !FdoIDisposable[[BR]]
    85 {[[BR]]
    86 public:[[BR]]
     75{{{
     76/// \brief
     77/// The FdoRasterDataModel specifies the data type and organization
     78/// of raster data retrieved and stored. Using this class and the image
     79/// extents in width and length, the binary format of the image data returned
     80/// by and accepted by the FdoIStreamReader class can be interpreted.
     81class FdoRasterDataModel: public FdoIDisposable
     82{
     83...
     84    FdoDouble         m_min;
     85    FdoDouble         m_max;
     86    FdoBoolean        m_minMaxSet;
     87    FdoBoolean        m_minMaxApproximate;
     88...
     89public:
     90...
     91    /// \brief
     92    /// Get the raster min/max.
     93    ///
     94    /// Returns min/max raster values suitable to use for linearly scaling this
     95    /// raster for display purposes.  For RGB or RGBA images the min/max values
     96    /// are considered to be approximate for red, green and blue samples, but
     97    /// should not be applied to the alpha sample.
     98    ///
     99    /// If the force parameter is true, this call may result in a substantial
     100    /// delay while the provider scans the image to compute appropriate min/max
     101    /// values.  If force is false then the provider is expected to do only
     102    /// minimal work to produce a value, or to fail. 
     103    ///
     104    /// Note that failing to return requested values will not trigger an
     105    /// exception if the force argument is false.
     106    ///
     107    /// If the approx_ok argument is false, then any scan to compute min/max
     108    /// values will scan the whole image.  If approx_ok is true then
     109    /// computation of min/max by the provider may be accelerated by using
     110    /// overview images, or a sampling of the full image as deemed appropriate
     111    /// by the provider as long as the result is likely to still be suitable
     112    /// for scaling the image.
     113    ///
     114    /// \param min the returned minimum
     115    /// \param max the returned maximum
     116    /// \param force true if computation should be forced even if it is expensive
     117    /// \param approx_ok true if an approximate min/max is acceptable, or false if an exact value is required
     118    /// \return
     119    /// true if min/max have been set with appropriate values, or false if not.
     120    ///
     121    FDO_API virtual bool GetMinMax( FdoDouble &min, FdoDouble &max,
     122                                    bool force, bool approx_ok );
    87123
    88 …[[BR]]
    89 …[[BR]]
    90 
    91     /// \brief[[BR]]
    92     /// Get the number of bits per pixel.[[BR]]
    93     /// [[BR]]
    94     /// \return[[BR]]
    95     /// Returns the number of bits for each pixel. For multi-channel[[BR]]
    96     /// data the bits per channel will be this value devided by the numer of[[BR]]
    97     /// channels. For example, RGB data has three channels, so if this[[BR]]
    98     /// method returns twelve, each channel is four bits.[[BR]]
    99     /// [[BR]]
    100     FDO_API virtual !FdoInt32 !GetBitsPerPixel ();[[BR]]
    101 
    102     /// \brief[[BR]]
    103     /// Set the number of bits per pixel.[[BR]]
    104     /// [[BR]]
    105     /// \param bpp [[BR]]
    106     /// The number of bits per pixel desired.[[BR]]
    107     /// Values of 1, 4, 8, 16, 24, 32, 48 and 64 bits per channel may[[BR]]
    108     /// be supported. Others values (i.e. indivisible by the number of channels)[[BR]]
    109     /// are likely to raise an !FdoException.[[BR]]
    110     /// [[BR]]
    111     FDO_API virtual void !SetBitsPerPixel (!FdoInt32 bpp);[[BR]]
    112 
    113     /// \brief[[BR]]
    114     /// Get the number of bits used per pixel.[[BR]]
    115     /// [[BR]]
    116     /// \return[[BR]]
    117     /// Returns the number of bits used for each pixel. For multi-channel[[BR]]
    118     /// data the bits used per channel will be this value devided by the numer of[[BR]]
    119     /// channels. For example, RGB data has three channels, so if this[[BR]]
    120     /// method returns twelve, each channel uses four bits.[[BR]]
    121     /// [[BR]]
    122     FDO_API virtual !FdoInt32 !GetBitsUsedPerPixel ();[[BR]]
    123 
    124     /// \brief[[BR]]
    125     /// Set the number of bits used per pixel.[[BR]]
    126     /// [[BR]]
    127     /// \param bpp [[BR]]
    128     /// The number of bits per used per pixel.[[BR]]
    129     /// [[BR]]
    130     /// \remarks[[BR]]
    131     /// This method is primarily being defined for object construction purposes[[BR]]
    132     /// within the provider and would not be called by client applications.[[BR]]
    133     FDO_API virtual void !SetBitsUsedPerPixel (!FdoInt32 bpp);[[BR]]
    134 
    135 …[[BR]]
    136 …[[BR]]
    137 
    138 };[[BR]]
     124    /// \brief
     125    /// Set the raster min/max.
     126    ///
     127    /// \param min the minimum raster value
     128    /// \param max the maximum raster value
     129    ///
     130    /// \remarks
     131    /// This method is primarily being defined for object construction purposes
     132    /// within the provider and would not normally be called by client
     133    /// applications.
     134    FDO_API virtual void SetMinMax( FdoDouble min, FdoDouble max );
     135...
     136};   
     137}}}
    139138
    140139'''''The new property will also be added to the FDO Managed API.'''''
    … …  
    142141== Notes ==
    143142
    144 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.
     143This 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.
    145144
    146 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. 
     145This 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 scaling range manually.
     146
     147== Unresolved ==
     148
     149* It is questionable whether a method that can trigger a good deal of processing work belongs in a property oriented class like FdoRasterDataModel.
     150
     151* 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).
    147152
    148153== Test Plan ==
    … …  
    156161== Funding/Resources ==
    157162
    158 Autodesk to provide resources / funding.
    159 
    160 
     163Autodesk to provide resources / funding to update FDO core, and proprietary raster provider.  Frank Warmerdam to implement required changes to GDAL based raster provider.