= FDO RFC 65 - Implement Resampling for GDAL Provider =

This page contains a request for comments document (RFC) for the FDO Open Source project.  
More FDO RFCs can be found on the [wiki:FDORfcs RFCs] page.

== Status == 
 
||RFC Template Version||1.1||  
||Submission Date||Oct 12, 2012|| 
||Last Modified||Trevor Wekel - Oct 22, 2012|| 
||Author||Trevor Wekel|| 
||RFC Status||Adopted|| 
||Implementation Status||Completed|| 
||Proposed Milestone||3.8|| 
||Assigned PSC guide(s)|||| 
||'''Voting History'''||October 23, 2012|| 
||+1||Greg Boone, Haris Kurtagic, Jackie Ng, Orest Halustchak || 
||+0|||| 
||-0|||| 
||-1|||| 
 
== Overview ==

This proposal adds GDAL resampling support using a layered approach over the existing GDAL Provider.  This maintains nearly identical behaviour with the current provider implementation if resampling is not turned on while still providing access to GDAL library resampling capabilities for cases where it is useful.

== Motivation ==

The GDAL Provider defaults to nearest neighbour resampling.  This resampling method is problematic for imagery with embedded symbology or text. 

== Proposed Solution ==

A new class !FdoRfpStreamReaderByTileResample is introduced to implement resampling behaviour.  It maintains a member instance of the existing !FdoRfpStreamReaderByTile to perform the reading and resampling from the GDAL library.  The member reader samples at 2x the required pixel density.  This data is then downsampled to the required pixel density using one of resampling methods supported by GDAL warp:
 * BILINEAR - Bilinear resampling
 * CUBIC - Cubic resampling
 * CUBICSPLINE - Cubic spline resampling
 * LANCZOS - Lanczos windowed sinc resampling

The resampling method is specified by a new "!ResamplingMethod" parameter in the connection string for the provider.  The parameter values can be enumerated and are case sensitive.

{{{
m_connection->SetConnectionString(L"DefaultRasterFileLocation=../../TestData/pci_eg/acea.tif;ResamplingMethod=BILINEAR");
}}}

The internal reader uses a memory buffer to supply the GDAL warp operation with data.  This eliminates any performance issues caused by writing temporary data to disk.

The !FdoRfpStreamReaderByTileResample reader automatically upgrades all bit depths and color to 32 bit RGBA.  A 32 bit color space is generally required to accurately display the blended pixels resulting from the resampling.

See attachment:RasterResample20121012.patch for an initial implementation of the RFC.  This patch can be applied directly to trunk.

Updated attachment:RasterResample20121022.patch contains CPLPrintPointer modification suggested by Frank Warmerdam, !ResamplingMethod enumeration suggested by Jackie Ng, and updates for Linux build.

== Implications ==

Current performance of the provider is unaffected when using the default nearest neighbour behaviour.  Performance will be slower when any of the resampling methods is employed.  Requesting 30+ megapixel views (5600x5600 pix) could lead to out of memory conditions on a 32 bit platform. 

== Test Plan ==

A single unit test will be created to validate that the resampling is functioning and generating 32bit RGBA imagery. 

== !Funding/Resources ==

OTX Systems is developing this feature with support from Linknode.