Changes between Version 2 and Version 3 of MapGuideRfc116


Ignore:
Timestamp:
Jun 16, 2011, 4:16:21 PM (13 years ago)
Author:
NormOlsen
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • MapGuideRfc116

    v2 v3  
    3737Achieving this level of improvement is deemed possible by four distinct tasks involving the API.
    3838
    39 == Removing the Requirement for a Crtitical Section ===
     39=== Removing the Requirement for a Crtitical Section ===
    4040
    41 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.
     41Currently, 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.
    4242
    4343Please 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.
    … …  
    4646The 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:
    4747
    48 {{{MgCoordinateSystemTransform::IsReentrant ()}}}
     48{{{ bool MgCoordinateSystemTransform::IsReentrant () }}}
    4949
    5050The signature of this proposed new method of the MgCoordinateSystemTransform object would
    … …  
    5353
    5454=== Refactor the MgCoordinateSystemTransformation::Transform Functions ===
     55
    5556It 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.
    5657
    … …  
    6061However, 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.
    6162
    62 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.
    63 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.
     63Thus, 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.
    6464
    6565Upon 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.
    … …  
    6767
    6868Thus, the following additional member functions to the MgCoordinateSystemTransformation object are proposed:
    69 {{{INT32 MgCoordinateSystemTransform::GetConversionStatus (INT32 failPercentage);}}}
     69
     70{{{ INT32 MgCoordinateSystemTransform::GetConversionStatus (INT32 failPercentage); }}}
     71
    7072The 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.
    71 {{{INT32 MgCoordinateSystemTransform::GetTotalPointCount (void);}}}
     73
     74{{{ INT32 MgCoordinateSystemTransform::GetTotalPointCount (void); }}}
     75
    7276Returns the total number of points converted.
    73 {{{INT32 MgCoordinateSystemTransform::GetSourceWarningCount (void);}}}
     77
     78{{{ INT32 MgCoordinateSystemTransform::GetSourceWarningCount (void); }}}
     79
    7480Returns the number of warning statuses returned by the source projective CRS phase.
    75 {{{INT32 MgCoordinateSystemTransform::GetDatumWarningCount (void);}}}
     81
     82{{{ INT32 MgCoordinateSystemTransform::GetDatumWarningCount (void); }}}
     83
    7684Returns the number of warning statuses returned by the datum shift stage.
    77 {{{INT32 MgCoordinateSystemTransform::GetTargetWarningCount (void);}}}
     85
     86{{{ INT32 MgCoordinateSystemTransform::GetTargetWarningCount (void); }}}
     87
    7888Returns the number of warning statuses returned by the target projective CRS phase.
    7989
    8090The 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.
     91
    8192The 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.
    8293
    … …  
    8596A 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.
    8697It is, therefore proposed, that two new functions be added to the MgCoordinateSystemTransformation object be added which will have signatures suggested by the following:
    87 {{{     void MgCoordinateSystemTransform::Transform2D (double [][2],INT32 pointCount);
    88         void MgCoordinateSystemTransform::Transform3D (double [][3],INT32 pointCount);}}}
     98{{{ void MgCoordinateSystemTransform::Transform2D (double [][2],INT32 pointCount); }}}
     99{{{ void MgCoordinateSystemTransform::Transform3D (double [][3],INT32 pointCount); }}}
    89100These 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.
    90101