| 35 | | 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 when using the most efficient Transform functions. |
| | 35 | 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 when using the most efficient of the Transform function overloads. |
| 60 | | 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. |
| 61 | | 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. |
| | 58 | 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 proper 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. |
| 63 | | 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. |
| | 60 | The default behavior of the API is to throw an exception whenever such a warning is received from the CS-MAP library. This default behavior can be, and often is, modified at run-time using the IgnoreDatumShiftWarning and IgnoreOutsideDomainWarning members of the MgCoordinateSystem interface. Thus, it is recommended that applications using the API disable the exception throwing behavior of the API. 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. |
| 72 | | The argument to this function would indicate the threshold as the percentage of points |
| | 70 | The argument to this function would indicate the threshold as the percentage of points converted 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. |
| 96 | | 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. |
| | 94 | 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 single dimensional array of doubles, the northing/Y/Latitude coordinates in a separate single dimension 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. |
| | 95 | |
| | 96 | Thus, to take advantage of the batch conversion facility currently in place, the traditional form of coordinate data (e.g. a two dimensional array of doubles: ''double []![3]'') has to be reformatted (i.e. marshalled) into the distinct array form prior to conversion, and then reformatted back to the traditional form after the conversion has been performed. Thus, what performance improvement is provided by the batch conversion facility is typically consumed, and probably then some, by the formatting and reformatting processes. |
| | 97 | |
| 114 | | 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. |
| 115 | | 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. |
| 116 | | 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). |
| | 116 | 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. That is, even in the event of an exception, all coordinates requested to be convrted will have been conververted. |
| | 117 | 2. The four status values returned in the m_nTransformStatus member of the MgCoordinateSystemTransform object may be adjusted to form a severity level sequence which rates a geodetic datum “outside range” as 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. |
| | 118 | 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 (per the severity level described in 2 above) in the transformation of the array (as opposed to the status of the last conversion perfromed as is currently done). |
| 123 | | * A function capable of performing all conversions in the table |
| 124 | | * 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). |
| | 125 | * A function capable of performing all conversions in the table, in sequence, using the MgCoordinateSystemTransform pointer in each test case, shall be written. |
| | 126 | * The host test application will create threads causing each individual thread to execute the test conversion function using the exact same test data and, specifically, a pointer to the same Transformation objects. |
