[gdal-dev] update to overview resampling methods?

[Even Rouault]

Selon Etienne Tourigny <etourigny.dev at gmail.com>:

> Hi list,
>
> I would like to know if the overview resampling methods listed on help
> pages are really up-to-date, because I found some discrepancies in the
> docs and code:
>
>
> - gdaladdo utility page / http://www.gdal.org/gdaladdo.html
>
> nearest,average,gauss,cubic,average_mp,average_magphase,mode
>
>
> - GDALDataset::BuildOverviews /
> http://www.gdal.org/classGDALDataset.html#a2aa6f88b3bbc840a5696236af11dde15
>
> "NEAREST", "GAUSS", "CUBIC", "AVERAGE", "MODE", "AVERAGE_MAGPHASE" or "NONE"

"NONE" is a provision for drivers/users that would need to create the overview
bands but don't want them to be initialized, because they use their own
resampling method.

>
>
> - searching the code I found the following undocumented resampling
> methods (there may be others)
>
> AVERAGE_BIT2GRAYSCALE, AVERAGE_BIT2GRAYSCALE_MINISWHITE, AVERAGE_BIT2,
> AVERAGE_BIT2GR, NO_REGEN

Internal implementation details of drivers.

>
>
> - gtiff overviews (in frmts/gtiff/gt_overviews.cpp)
>
> only mentions the following, does it also support all others?
> AVERAGE_BIT2, NEAR, AVERAGE, GAUSS

They are specific cases it handles (some for optimizations), but they are not
the only ones

>
>
> So I have a few questions:
>
> 1) why are some methods not listed in GDALDataset::BuildOverviews and
> gdaladdo docs
> average_mp, AVERAGE_BIT2*, NO_REGEN  (there may be others)

- average_mp is documented in gdaladdo as not ready for use in production, so
could be likely "undocumented" in gdaladdo man page
- AVERAGE_BIT2* stuff is internal implementation detail for computing overviews
of 1-bit raster as a 8-bit band. Must not be documented in user doc.
- NO_REGEN: implementation hack for Imagine overviews. Must not be documented in
user doc

>
> 2) are there some methods which are not supported in specific drivers,
> such as e.g. CUBIC in the gtiff driver?

The generic overview code is in gcore/overview.cpp. Unless some driver has a
very specific implementation of IBuildOverview() not relying on
gcore/overview.cpp, all methods should be available. GTiff and HFA have
implementations of IBuildOverviews(), but that's to create the overview
bands/files : at the end, they fallback to gcore/overview.cpp to compute the
pixel values.

>
> 3) why is AVERAGE_MP considered unfit for use in the gdaladdo docs?
> and why is it still available?

Historical remain ? Could likely be undocumented.

>
> 4) AVERAGE_MAGPHASE has been reported as buggy by some QGIS users,
> could someone comment?
> see http://hub.qgis.org/issues/284

I've never used it, but my understanding of the code is that it is (should be)
restricted to images whose datatype is one of the complex types, like CInt16,
CInt32, CFloat32 or CFloat64. For other datatypes, I would tink it is
interpreted as standard average, but my understanding of the code might be
insufficient.

>
> 5) should the docs be updated and harmonized, including any
> driver-specific options, or are they too obscure to worry about?

Some precision could be perhaps given by knowleagable people on what
average_magphase does exactly (my undersanding is that it averages the real and
imaginary components of source pixels, and then does some kind of
re-normalization of the result), but no need to document the other internal
stuff that are implementation details of drivers.

>
>
> regards,
> Etienne
> _______________________________________________
> gdal-dev mailing list
> gdal-dev at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/gdal-dev
>