[fdo-internals] FDO RFC 1 - Support PropertyFdoIRaster::BitsUsedPerPixel

[Frank Warmerdam]

Greg Boone wrote:
> Hi Frank,
> 
> The change request came from Ikonos. The following information was
> extracted from an email exchange I had with them...
> 
> "Ikonos has images that are in 16 bit, unsigned integer format. In
> reality, only 11 bits out of this 16 are used. When their application
> renders it, if this information is not available, it will render it as
> 16 bit, which results in a totally black image, using the default color
> map. Ikonos fully depends on the data model to completely describe the
> properties of the image."
> 
> "Currently, Ikonos works around this issue by examining all pixels and
> manually determining the used bits field by the number of bits actually
> used, which needless to say is inefficient. Their example data set does
> have this property set (number of data bits) but this information is not
> exposed through FDO."
> 
> "The used bits are useful in the case of stylization if the code takes
> advantage of it. This is true not only for 16 bit images with 11 bits
> used like the Ikonos, but other formats as well. Both TIFF and PNG can
> encode grayscales with less than 8 bits (2 and 4 bit). Some raster
> engines will promote these to 8 bit automatically, but it will report
> the lower bits used count so that applications can make use of it during
> modification and UI presentation (like Histograms). "

Greg,

OK, I think this use case - linear stretches of 11bit ikonos data is
more generally handled by the ability to query a raster for min/max
values.  This is a quite a common situation, but it does not always
take the form of 11 or 12 bit sensors put into 16bit pixel values.
Similar issues arise with elevation data that might all be between
1000 and 2000 meters for instance.

I would add that Space Imaging (GeoEye now I guess?) formats
their Ikonos GeoTIFF products like this:

TIFF Directory at offset 0x1ce0008 (30277640)
   Image Width: 1728 Image Length: 2761
   Tile Width: 256 Tile Length: 256
   Resolution: 300, 300 pixels/inch
   Bits/Sample: 16
   Compression Scheme: None
   Photometric Interpretation: RGB color
   Samples/Pixel: 3
   Min Sample Value: 0
   Max Sample Value: 2047
   Planar Configuration: single image plane
   ImageDescription: DefaultImageDescription
   DateTime: 1999:10:24 19:10:20
   Copyright: copyright SII Incorporated 1996 All Rights Reserved
   Tag 33550: 4.000000,4.000000,0.000000
   Tag 33922: 0.000000,0.000000,0.000000,625733.108344,4279994.858126,0.00000
   Tag 34735: 1,1,0,5,1024,0,1,1,1025,0,1,1,3072,0,1,32610,3073,34737,25,0,30
,1,9001
   Tag 34737: UTM Zone 10 N with WGS84|

As you can see, they also indicate the number of bits used by
embedding a minimum and maxmium in the Min/Max Sample Values.
On the other hand Ikonos images in NITF format use the ABPP
(Actual Bits Per Pixel) flag since that is the only mechanism
provided for reporting raster min/max in NITF format.

So I would like to encourage re-writing this RFC to have methods
to return the min/max instead of the less general used bits per pixel.
I think it would be more general, and map on the facilities provided
in more raster formats.

I would be willing to do a first draft update in this direction
if you are willing.

In my experience with GDAL I have come to the conclusion that
two extra flags are very useful in this sort of request.

  - bApproxOK - Letting the provider know whether an approximate
    min/max would be ok.  When it is being used for linear stretching
    for display approximate min/max values are generally fine.
    Approximate value are computed by using overviews, and possibly
    by only sampling the data available as opposed to scanning it all.

  - bForce - I use this to indicate whether the provider (driver in
    my case) should force a potentially expensive computation of the
    min/max values.  If this is false, and the image has no existing
    min/max metadata then I just return an indication of failure along
    with default min/max values for the data type.  If this is true then
    the provider will actually go ahead and compute the values by
    sampling or scanning all the data.

> 3) For many file formats there isn't any way to find out how many bits
> are actually being used.  Is this going to be a problem?  Is there going
> to be a way for providers to return an indicator that they don't
> know how many bits are actually being used?
> [GB] In this case bitsUsedPerPixel == bitsPerPixel

This still leaves the application not knowing when it actually needs
to scan the whole image to compute the number of used bits.

> [GB] Yes. That sounds appropriate. On a side note, does the GDAL
> provider support data model conversion? I thought not. If so, it would
> have to deal with this issue at that time. 

Even though it was not part of the phase 1 specification, the GDAL
raster provider does support a wide variety of data model conversions.
Much of this is inherent in GDAL and so it was easy to implement.

> Overall, I'd like to understand the rationale better (is it just for
> linear
> stretches).
> [GB] Well, I am not in the best position to explain the exact rationale
> of the customer other than what is stated above. If you would like I can
> start an external thread with that customer that may help answer your
> questions. That being said, the bottom line is that the customer expects
> to have access to the NBITS metadata that is published with the image
> and does not wish to manually determine this information by examining
> the data stream.

 From the request info you supplied it is clear it for linear stretching
of the imagery for display.

I would add that when data model conversion is done by the provider it
is unspecified (as far as I know) how the provider should do the
conversion.  For instance, if the real image data is 16bit (as with ikonos)
and the request is for 8bit per sample RGB imagery, should the provider
provide the conversion by stretching the 16bit value range to 8bit, or
just by resetting all values larger than 255 to 255 (which is what the
conversion in the GDAL provider does).  If the customer is expecting
that the new UsedBits (or min/max) will affect how data model conversion
is done within the provider then perhaps that should be discussed in the
RFC.

Honest - I won't normally provide this much feedback on every RFC, but you
have stepped into an area of raster handling I have lots of experience
with and fairly strong opinions on. :-)

Best regards,
-- 
---------------------------------------+--------------------------------------
I set the clouds in motion - turn up   | Frank Warmerdam, warmerdam at pobox.com
light and sound - activate the windows | http://pobox.com/~warmerdam
and watch the world go round - Rush    | President OSGeo, http://osgeo.org