MS RFC 5: MapServer Horizon Reprojection Improvements

Date:

2005/09/16

Author:

Frank Warmerdam

Contact:

warmerdam at pobox.com

Status:

Adopted

Version:

MapServer 4.8

Purpose

To provide a practical solution to MapServer Bug 411 - Clipping Issue with Ortho Projection:

Approach

The msProjectShape() function would be altered support reprojection of shapes where some, but not all, vertices fail to transform due to issues such as falling over the horizon. An iterative method would be used to preserve a reduced geometry approximating the portion that can be transformed.

Point Features

  • Point features will be handled as they are now. The either transform successfully or not. Those that fail to transform are dropped.

Line Features

  • Line strings would potentially be split into multiple line strings, if there were more than one discontinuous portion of a line string that transforms.

  • Interpolated (horizon) points would be computed by transforming points along the line segment between the last successful point and the first unsuccessful point. A binary search algorithm will be used to find the closest point within our tolerance distance.

  • Line strings where no vertices transform successfully will still be dropped.

Area Features

  • Each ring will be treated distinctly, without regard to the other rings. This means no there is no assurance that an inner ring will remain completely within the outer ring after clipping. In particular, where the horizon passes through an area and a hole in the area, it is likely that the hole edge will touch over even overlap the outer area edge a bit. Generally this should not matter much in the MapServer context since a simple scanline rasterization (winding number based) technique is used. So polygon „correctness“ is not paramount.

  • A similar technique to that for lines is used to interpolate the edge vertices when clipping is to be applied.

  • For polygons there will be two (or possibly 4, 6, 8…) interpolated horizon points. These will be connected with a straight line segment. For very large polygons spanning a significant portion of the horizon (ie. dozens of degrees of arc of the horizon) this will result in part of the circle of the horizon getting clipped off. Optionally an iterative method could be applied to address this curvature issue (not priced into this proposal).

Tolerances

MapServer will need make a decision on how detailed to get when doing the iterative horizon determination. The tolerance will be fixed as half the size of a pixel in the current map rendering. In normal map drawing this should mean that the final rendering is effectively exact.

However, communicating the tolerance into msProjectShape() will require substantial work as the msProjectShape() function does not normally know anything about the map or current rendering information. To communicate this information to msProjectShape(), I will add a transformation options structure with this information (and possibly other flags controlling transformation) which will be passed into msProjectShape(). If NULL particular defaults will be used.

All appropriate uses of msProjectShape() will need to be updated to reflect this change, and to setup the transformation options information ahead of time. layerObj level PROCESSING options will also be provided to control (override) the default transformation options.

Caveats

  1. msProjectShape() may produce slightly invalid polygons from a GIS point of view, though it shouldn’t matter much for rendering purposes.

  2. The straight line segment for „area horizon edges“ will result in visible „clipping“ of the horizon for very large polygons (ie. the Soviet Union).

  3. This change is too disruptive to back port to the stable 4.6.x release, so it would only be available as part of CVS based MapServer builds (aka 4.7) until such time as the 4.8 release is made, likely in December or January.

Mapfile Implications

There will be no changes to the mapfile.

MapScript Implications

There will be no changes to MapScript.

Backward Compatibility Issues

Some maps that previous dropped incompletely reprojected features will now produce clipped features. I don’t foresee this causing obvious problems other than a slight change (improvement!) in appearance.

Staffing and Timeline

The new feature will be implemented by October 15th, 2005, in time for inclusion in MapServer 4.8. It will be implemented by Frank Warmerdam with generous funding from TMC Technologies.