[gdal-dev] update to overview resampling methods?

[Etienne Tourigny]

Hi Even, thanks for you time

On Fri, Oct 5, 2012 at 1:36 PM, Even Rouault
<even.rouault at mines-paris.org> wrote:
> 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

ok

>
>>
>>
>> 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

I understand that these are set internally when a certain condition is met?

>
>>
>> 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.

ok

>
>>
>> 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.

ok I will remove it, should it be removed/commented from the code also?

>
>>
>> 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.

ok thanks, if someone has official documentation/information on
average_magphase please let me know.

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