[gdal-dev] update to overview resampling methods?

[Etienne Tourigny]

also any objection I change the parameters to upper case in gdaladdo
docs, to be in line with the names in the code?

Etienne

On Fri, Oct 5, 2012 at 4:18 PM, Etienne Tourigny
<etourigny.dev at gmail.com> wrote:
> 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
>>>
>>
>>