MapGuide RFC 116 - Coordinate System COnversion Perfromance Upgrade

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	16 June 2011
Last Modified	Norm Olsen 16 June 2011`
Author	Norm Olsen
RFC Status	Not ready for review
Implementation Status	pending
Proposed Milestone	2.3
Assigned PSC guide(s)	Bruce Dechant
Voting History	(vote date)
+1
+0
-0
-1
no vote

Overview

Geodetic coordinate system conversion is involved in a large portion of MapGuide data processing at both the server and client levels. Presuming the acceptance and implementation of CS-MAP RFC #5, it is proposed that the MgCoordinateSystem Application Programmers Interface (API) be enhanced to increase the performance of coordinate conversions at both the server and client levels of MapGuide without changing the behavior of any existing member of the API.

Motivation

Regardless of how fast anything on the Internet is, it is never fast enough. Hardware available at both the server and client level is now multi-core capable thus enabling higher performance. Software developments such as cloud computing provide the demand for higher performance. The changes proposed in this RFC are intended to address these issues.

Proposed Solution

The proposed submission would not change any existing functionality or method signatures. The proposal introduces five new members to the currently existing MgCoordinateSystemTransform interface. This RFC includes an outline of the recommended usage of the API which will provide the optimum performance of the API.

Using the metric of the number of conversions per second from UTM27-13 to CO83-C in a pure measurement environment (i.e. no coordinate retrieval or delivery code), the underlying CS-MAP library is capable of producing approximately 1 million conversions per second. Changes in the MapGuide API, therefore, cannot get us beyond this limit. Thus, in this RFC, we will write of performance in terms of the percentage of this theoretical maximum which the API can/will deliver. The current implementation of the API delivers performance of approximately 80% of this maximum. Research and test implementations indicate that it is not unreasonable to expect an improvement to 91% of the theoretical maximum.

Achieving this level of improvement is deemed possible by four distinct tasks involving the API. Removing the Requirement for a Crtitical Section Currently, there are specific transformations within the CS-MAP library which are not reentrant. Therefore, to insure proper operation in a multi-threaded environment, a critical section is used for all datum shift calculations. It is the intent of this RFC to remove this requirement. Assuming the acceptance and implementation of OsGeo MetaCRS RFC #5, CS-MAP will enable the API to query CS-MAP and determine if a critical section is necessary for a specific transformation. The API will be modified to use this information and invoke the critical section only as necessary.

Please note that the referenced CS-MAP RFC includes two phases. The first phase includes only the identification of those transformations which are known to be reentrant and those which are not. The first phase is a relatively simple task which is easily completed with available resources. The second phase includes some, perhaps non-trivial, efforts to make reentrant most, if not all, CS_MAP conversions and transformations which are known to be non-reentrant. Thus, as this work progresses, further performance enhancements will inure to applications without and code changes required.

Further, it is proposed that the MgCoordinateSystemTransform object provide this information to the consuming application, and thus applications will be able to determine if multi-threading a large conversion will provide any benefits. The performance enhancement of removing the Critical Section will be enjoyed automatically by all applications using the API without code change. However, the following API will be added to the MgCoordinateSystemTransform object to enable applications to further improve the performance of large coordinate conversions:

MgCoordinateSystemTransform::IsReentrant ()

The signature of this proposed new method of the MgCoordinateSystemTransform object would bool MgCoordinateSystemTransform::IsReentrant (void); The function would return true only in the case where all conversions and transformations referenced by the transformation object are known to be reentrant.

Refactor the MgCoordinateSystemTransformation::Transform Functions

It is proposed that the existing implementation of all of the Transform overloads in the existing MgCoordinateSystemTransformation object be refactored for performance purposes. It is contemplated that by : a) reducing the number of changes of the form of a coordinate takes, b) removing some internal function calls by replicating code to a small degree, and c) reducing the overhead implied by several layers of try {} catch blocks; that significant performance enhancements can be achieved. This work will introduce some minor changes in behavior which are considered to be improvements in consistency and usefulness of the API and only affects behavior in extraordinary cases. These changes are detailed below.

Conversion Status Accumulation

CS_MAP issues warnings for coordinates outside the useful range of the coordinate systems (and the datums referenced by them) used to construct the MgCoordinateSystemTransformation object. These are warnings and do not mean that the returned coordinates are invalid. It should not be considered abnormal for a small sub-set of the coordinates in a large conversion to be outside the useful range of a Transformation object. In the event that a large number of coordinates in a conversion are found to be outside the useful range, it is valid to question the validity of the conversion. Such a case is a strong indication that the user may not have selected the proper coordinate system for a specific conversion. However, currently the default behavior of the API is to throw an exception in whenever such a warning is received from the CS-MAP library. Applications then either consider the conversion to be a failure, or essentially ignore the exception. In the former case, this is not always the correct conclusion. It is not uncommon for a geometry or map of a large region to occasionally stray outside the useful range of a coordinate system. The results CS-MAP returns, even in the case of a warning are totally appropriate given the coordinate values it has been asked to convert. In the latter case, in the event of the user choosing an incorrect coordinate system for the data in use, the application can appear to hang as measurements indicate that disposing of an exception in this case can consume 15 milliseconds of clock time for each point.

Thus, it is recommended that applications using the API disable the exception throwing behavior of the API, and it is further proposed that the MgCoordinateSystemTransformation object be enhanced to provide a status accumulation feature. By status accumulation, we refer to the concept of: a)counting each point converted, b) counting all source projective CRS warnings issued, c) counting all datum shift warnings issued, and d) counting all target projective CRS warnings.

Upon construction, or upon use of the SetSourceAndTarget member, or upon use of the ResetLastTransformStatus member function, all counters of the status accumulation mechanism will be reset to zero. Each point converted by the MgCoordinateSystemTransformation object will cause the all appropriate counts to be advanced based on the status of the conversion. Upon completion of the conversion of a map or data source, the application will then query the Transformation object and make a determination as to the validity of the result. For example, a conversion where the target CRS warning count exceeds, say, 33% of the total number of points suggests that the target CRS chosen by the user is incorrect. On the other hand, warning counts which are less than, say, 10% of the total point count suggest a perfectly normal conversion.

Thus, the following additional member functions to the MgCoordinateSystemTransformation object are proposed: INT32 MgCoordinateSystemTransform::GetConversionStatus (INT32 failPercentage); The argument to this function would indicate the threshold as the percentage of points which are to be considered a transformation failure. The returned integer would be zero for a successful conversion. A non-zero bitmap of would be returned in the event of a failure (i.e. a warning count excess the specified percentage of the total point count), the individual bits indicating the phase, or phases, (i.e. source CRS, datum shift, target CRS) which accumulated sufficient warning counts to indicate failure. INT32 MgCoordinateSystemTransform::GetTotalPointCount (void); Returns the total number of points converted. INT32 MgCoordinateSystemTransform::GetSourceWarningCount (void); Returns the number of warning statuses returned by the source projective CRS phase. INT32 MgCoordinateSystemTransform::GetDatumWarningCount (void); Returns the number of warning statuses returned by the datum shift stage. INT32 MgCoordinateSystemTransform::GetTargetWarningCount (void); Returns the number of warning statuses returned by the target projective CRS phase.

The above new functions can be used at anytime during a large conversion to determine the accumulated status of the conversion. Thus, a very large conversion can be terminated prematurely if it appears that after a significant number of conversions have been performed the ultimate failure appears to be likely. The addition of this improved status monitoring capability is expected to make the disabling of exception processing while performing large conversions an acceptable practice and is, therefore, considered to be and important contribution to providing higher performance levels. Provide Additional Batch Coordinate Conversion Capability A batch coordinate conversion capability currently exists in the MgCoordinateSystemTransformation object. The performance of this capability is expected to increase due to the refactoring of the Transform code proposed immediately above. However, this function requires that, for example, 3D coordinates are provided in three distinct arrays; specifically the easting/X/Longitude coordinates in one distinct array of doubles, the northing/Y/Latitude coordinates in a separate distinct array of doubles, and a third separate and distinct array of double for the elevation/Z/height coordinate. There are few, if any, applications which maintain or utilize coordinate data in this form. Thus, to take advantage of the batch conversion facility currently in place, the tradition form of coordinate data (i.e. double [][3]) has to be reformatted into the distinct array form prior to conversion, and then reformatted back to the traditional form after conversion. Thus, what performance improvement is provided by the batch conversion facility is used up, and then some, by the reformatting process. It is, therefore proposed, that two new functions be added to the MgCoordinateSystemTransformation object be added which will have signatures suggested by the following: {{{ void MgCoordinateSystemTransform::Transform2D (double [][2],INT32 pointCount);

void MgCoordinateSystemTransform::Transform3D (double [][3],INT32 pointCount);}}}

These new member functions would convert the point arrays in place, and do so without the need for reformatting the coordinate storage for several widely used applications.

Implications

CriticalSection Still Required

It would be nice to assume that all current CS-MAP coordinate conversion algorithms can be made reentrant without a serious affect on resources and/or performance, and that all future additions to the CS-MAP library can be implemented in a reentrant manner. The ability to have non-reentrant conversion/transformation methods in the CS-MAP library is reserved. Thus, we retain the CriticalSection to keep multiple threads from using a non-reentrant conversion or transformation at the same time. However, given the implementation of CS-MAP RFC #5, we will only need to actually use it when truly necessary.

Behavior Modifications

A substantial portion of the increased performance to be achieved will be derived from a refactoring of the coordinate system conversion code. Over the years, this code has become somewhat inefficient using several nested function calls with non-trivial signatures. In refactoring this code, the following changes in behavior (more like corrections) will be made:

1. In the existing code, the behavior of the API with regard to the status of returned results in the event of an exception being thrown is inconsistent. In the proposed code, the basic CS-MAP contract will be honored: “Regardless of status returned and/or exceptions thrown, any and all Transform member calls will always produce rational converted results.” Thus, the proposed behavior will provide consistent return results and also contribute to higher performance levels.
2. The four status values returned in the m_nTransformStatus member of the MgCoordinateSystemTransform object may be adjusted to conform a severity level sequence which rates a geodetic datum “outside range” more severe than a projected “outside range”. The names used will not change, only the numeric values assigned to them; so this should not require any coding changes.
3. The overloads of the MgCoordinateSystemTransform::Transform which deal with arrays will now always complete the conversion of the entire array before throwing any exception with regard to non-normal status encountered in the conversion. Also, these overloads will be modified so that the value of the m_nTransformStatus member, upon return, will always reflect the worst status encountered in the transformation of the array (as opposed to the last status as is currently done).
4. All overloads of the TransformM variety will now always calculate and return the ‘m’ value. Currently, when an exception is thrown, the XYZ coordinate values would be converted, but the ‘m’ value would not always be.

Test Plan

Normal regression testing will apply to insure that existing numerical results are preserved. Additionally, a multi-core specific test module shall be developed which, given a table of test cases specifically constructed to include several different conversion and transformation objects (directly or indirectly), shall:

• Construct for each unique conversion pair in the test data table an MgCoordinateSystemTransform object, copying the pointer as necessary to provide a pointer for each occurrence in the table.
• A function capable of performing all conversions in the table in sequence, using the MgCoordinateSystemTransform pointer in each test case, shall be written.
• The host test application will, create threads causing each individual thread to execute the test conversion function using the exact same test data (specifically, a pointer to the same Transformation objects).
• The host test application will cause up to 16 threads to be active at any given time.
• Continue this test for a specified amount of time, defaulting to 20 seconds.
• In the event of an error, the test application will record the specific transformation which failed.

Successful operation of 16 randomly started threads for a period of 20 seconds (an average of 20 executions of the test sequence by 16 different threads, producing 320 executions of each test sequence) will be considered success. Clearly, the test would be more conclusive if run on a machine with more than two cores.

Funding/Resources

Funding and developer resources to be provided by Autodesk.