MapGuide RFC 76 - Grid/Graticule implementation in the MgCoordinateSystem API

This page contains an change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	8 July 2009
Last Modified	Norm Olsen Timestamp
Author	Norm Olsen
RFC Status	adopted
Implementation Status	pending
Proposed Milestone	2.2
Assigned PSC guide(s)	Bruce Dechant
Voting History
+1	Andy, Bruce, Tom
+0	Jason, Kenneth
-0
-1
no vote	Bob, Haris, Paul

Overview

There exists a need for the production of graticules, grids, tic marks, and the labeling thereof in Mapping and GIS applications. This RFC seeks approval to add new functions and API’s to the MgCoordinateSystem API in support of this need. The proposal includes support for specific grids (e.g. MGRS) and grids and graticules in general. Being introduced at the MgCoordinateSystem API level, the proposed changes will simply generate in binary form the information necessary to render such grids and graticules, but no capability to render such is included in this proposal.

Motivation

Military organizations around the world want to use the MapGuide API to read and write MGRS designations and map related grids and cannot do that with the current API. Many governmental agencies in the US at all levels desire to produce maps an obtain grid references which adhere to the United States National Grid standard.

Terminology

Isoline refers to an entity which defines the locus of points in a coordinate space which all share a specific value. An isoline can be a single straight line segment or a highly complex curve, and may also be interrupted.

Graticule refers to a series of isolines which represent graphically the loci of points which share a common coordinate value.

Grid refers to refer to a graticule in which the common coordinate values are in linear units, and thus suitable for interpolation on the display surface. We will use the term grid to refer to both grids and graticules as in this implementation there is little difference between the two.

Generator refers to the functionality proposed for implementation by this RFC in the MgCoordinateSystem API.

Consumer refers to the application which requests grid information generation for the typical purpose of rendering such information on a display or paper map.

Source coordinate system or grid coordinate system both refer to the coordinate system upon which the coordinates of the isolines are based.

Target coordinate system, frame coordinate system, and/or viewport coordinate system all refer to the coordinate system of the actual drawing or map upon which the isolines are to be drawn.

Specialized grid refers to any one of the several identified grid systems which have unique properties such as the Military Grid Reference System (MGRS) and the United States National Gird (USNG).

Generic grid refers to a grid which is generated based solely on the coordinate systems involved and user specified input, for which general conventions may exist but a standard specification does not exist.

Region refers to a geographical region defined by a specialized grid specification where such specification also defines a textual designation for the region.

Zone refers to a region of a specialized grid which is based on a single coordinate system. Thus, a specialized grid for a grid boundary which crosses zone boundaries must deal with multiple grid coordinate systems; i.e. one coordinate system for each zone included in the grid boundary.

Proposed Solution

The solution is to create several new interfaces:

Interface Name	Description
MgCoordinateSystemGridBoundary	MgPolygon based extents of the grid. In the initial implementation, this will be expected to be a rectangle. Always supplied in the target coordinate system. This is the extents of the grid, not the viewport.
MgCoordinateSystemGridBase	Abstract interface between generator and consumer for all types of grids.
MgCoordinateSystemGridGeneric	Derives from MgCoordinateSystemGridBase and generates generic (i.e. non-specialized) grids (SPCS,UTM, Lat/Long, etc.).
MgCoordinateSystemGridMgrs	Derives from MgCoordinateSystemGridBase and contains all MGRS related intelligence.
MgCoordinateSystemGridUsng	Derives from MgCoordinateSystemGridBase and contains all USNG related intelligence.
MgCoordinateSystemGridSpecification	Conveys all grid generation parameters between objects, generator and consumer alike.
MgCoordinateSystemGridLineCollection	A collection of MgCoordinateSystemGridLine objects which represents a complete grid, in the target coordinate system and clipped to the grid boundary.
MgCoordinateSystemGridRegionCollection	A collection of MgCoordinateSystemGridRegion objects which defines the boundaries and designations of all specialized regions which exist within the grid boundary.
MgCoordinateSystemGridTickCollection	A collection of MgCoordinateSystemGridTick objects.
MgCoordinateSystemGridLine	A grid value and a collection of MgCoordinateSystemGridLineSegment objects (commonly just one). The grid value (a double) is in the source coordinate system and the line itself is in target target coordinate system. This collection is designed to support grid isolines which may be interrupted by the boundary.
MgCoordinateSystemGridLineSegment	A segment of a grid isoline resulting from clipping a complete grid line to grid boundary.
MgCoordinateSystemGridRegion	A designation and a MgPolygon which defines a specialized grid region boundary and associated designation.
MgCoordinateSystemGridTick	A position in viewport coordinates and a grid value as a double identifying the location of the tick mark and the the grid system cooridnate value associated with it.

In general, to draw a graticule or a grid, the consuming application establishes the boundary of the grid/graticule in target coordinates, populates a parameter structure with selections such as grid density, constructs the grid object for the type of grid desired, and requests the desired components (such as an MgCoordinateSystemGridLineCollection) from the grid object.

Design objecives are:

1. After construction of the grid object by the factory object, most interaction with the grid object could/should be independent of the grid type.
2. The abstract interface will return the specialized grid type for those applications which need to know.
3. Adding additional specialized grids should not require changes to code dealing with existing specialized grids.
4. MGSR/USNG type trackers are supported without having to render a grid.
5. It will be possible to cache all grid calculations for subsequent reuse if the grid specifications have not changed.
6. All coordinate conversion calculations would be performed by two new functions in the existing MgCoordinateSystemTransform object.
7. A grid based on any coordinate system can be drawn on a map based on any other coordinate system (Arbitrary CS excepted).
8. Specialized grid generation can and will properly deal with the possibility of multiple grid coordinate systems used in specialized grids (e.g. MGRS).
9. The issue of muliple specialized grid zones within the grid boundary will be (to the degree possible) transparent to the consuming application.

Factory functions are proposed for generic, MGRS, and USNG objects at this time. As there is no known significant difference between MGRS and USNG, iIn the initial implementation the USNG object will essentially be a duplicate of the MGRS object, enabling support of any future differences without disturbing existing code.

Implications

This API implies that all remarkable conditions will be handled with the use of exceptions. Exceptions require milliseconds to process through the MgCoordinateSystem API. Applications using this API need to be aware of this and refrain from continuing a loop which is producing exceptions frequently.

Test Plan

There are public domain products which convert coordinates into MGRS form, some from the military itself. While this will require significant manual labor, a table of geographic coordinates and the associated MGRS string should be devised based on the results produced by these products. This table will be hard coded into the object, compiled into the product whenever the __TEST__ manifest constant is defined, and made part of a self test function. In the absence of the __TEST__ macro, the self test function will always succeed.

Funding/Resources

Provided by Autodesk.