= !MapGuide RFC 51 - Raster Re-projection =

This page contains an change request (RFC) for the !MapGuide Open Source project.  
More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.


== Status == 
 
||RFC Template Version||(1.0)|| 
||Submission Date|| July 14, 2008 ||
||Last Modified|| Tony Fang [[Timestamp]]||
||Author||Tony Fang||
||RFC Status||draft|| 
||Implementation Status||pending||
||Proposed Milestone||2.1||
||Assigned PSC guide(s)||(when determined)||
||'''Voting History'''|| ||
||+1|| ||
||+0|| ||
||-0|| ||
||-1|| ||
||no vote||  ||
 
== Overview ==

This is a proposal to add an efficient raster re-projection algorithm that is based on tessellating an image into smaller triangles and re-projecting the triangles.

== Motivation ==

!MapGuide does not currently support any form of raster re-projection. If a user has a raster feature source, it can only be displayed in a !MapGuide map that uses the same coordinate system as the raster data.

Previously, in order for application developers to use images in multiple coordinate systems, they needed to create copies of the images in each coordinate system.  The re-projection capability that we are adding will allow developers to not have to have multiple versions of the same image (re-projected to different coordinate systems) at the cost of about 25% degradation in performance.

== Proposed Solution ==

We will use a tessellation algorithm to re-project the raster data from one coordinate system to another.

We must first determine how much of the original image is required for our re-projection. The extents of the current viewport must be re-projected into the coordinate system of the original image. The extents of the re-projected viewport need to be determined. This is the portion of the original image that will be required to re-project the image into the current viewport.

The original image (the portion required for the re-projection) will be divided into a grid of triangles representing the raster in its own coordinate system. Each point on the grid (representing the corners of the triangles) will be transformed into the target coordinate system, and the raster data within each triangle will be transformed appropriately to fit within the new geometry.


||[[Image(raster_reprojection_viewport.PNG)]]||
||Figure 1. On the left we have the original image represented by the blue grid of triangles. The black represents the viewport projected into the image's coordinate system. On the right we have the image (blue grid of triangles) re-projected into the viewport's coordinate system. The viewport is represented by the black rectangle.||

Each triangle will then be rendered into the output image to produce the transformed raster. The balance between performance and accuracy of the transformation is controlled by the number of triangles created for each raster. The configuration settings will control the size and number of triangles created. Configuration will be done through the serverconfig.ini.

The category and setting names for this configuration are:

{{{
[RasterReprojectionProperties]
# *****************************************************************************
# R A S T E R  R E P R O J E C T I O N  P R O P E R T I E S 
#
# Property Name                    Description
# -----------------------------------------------------------------------------
# TileSize                         Size of tiles in pixels
# *****************************************************************************
TileSize = 100
}}}
Descriptive error messages will be logged to handle invalid configuration settings, invalid data, unsupported transformations etc.

In keeping with !MapGuide’s current behavior, if the re-projection fails for any reason, the map will still be rendered and returned, using any other layers that it contains, and the failed layer(s) will be skipped.

We will add an optimization if the re-projection is a simple datum shift. The image will simply be shifted, and the advanced algorithm will not be invoked.

We will support re-projecting raster in drawing sources.


== Implications ==

WMS is also a raster feature source and will be affected by this algorithm.

== Test Plan ==

Unit tests should cover:
 * The most common raster image formats (ECW, !MrSid, TIFF)
 * Re-projections between each of the main coordinate system types

Unit tests should also validate that error conditions are handled gracefully.

== Funding/Resources ==

Autodesk