FDO RFC 49 - API change to pass tolerance in evaluate spatial operations

This page contains a request for comments document (RFC) for the FDO Open Source project. More FDO RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	(Jun. 02 2010)
Last Modified	(Romica Dascalescu) Timestamp
Author	(Romica Dascalescu)
RFC Status	(draft)
Implementation Status	(draft)
Proposed Milestone	(3.6.0.0)
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1
+0
-0
-1

Motivation

Using a default hard-coded tolerance in spatial operation evaluation, user can get wrong results.

Overview

Spatial queries are evaluated using a default hard-coded value (see below the used values). The issue is for certain spatial contexts we might miss features or find more features than we should. The tolerance should be set by the user when the data base is created (at create spatial context time) and use that value in spatial queries.

	//those numbers are very small and provide
	//the tolerance needed for "exact" computations,
	//i.e. CAD style non-FDO geometry intersection.
	#define EPSILON 1e-10
	#define NEGEPSILON -EPSILON
	#define SQREPSILON 1e-20

The idea is to add support in FDO API for passing the tolerance into the spatial utility. FDO has already support for those tolerances, so user can provide them when a new spatial context is created. Also those values can later be obtained using a spatial context reader. Each class in FDO has a dedicated spatial context reader. The provider can get those tolerances (XY and Z) by getting the spatial context of the class before running the spatial evaluation. Since providers might want to have 0.0 tolerances we cannot pass default values as 0.0, so we can pass 1e-10 same as before this RFC, which is the default value used by FDO API. If the spatial condition is a 2D evaluation the Z tolerance will be ignored.

Proposed Solution

Add two new parameters which by default will be 1e-10. In case this parameter is NaN it will use the default tolerance (1e-10). We can modify SQLite and possible SDF providers only, rest of the providers will remain unchanged and if needed will be changed later. All internal functions from spatial FDO module will be updated to add extra parameters for tolerance.

	/// \brief
	/// Spatial utility class.
	class FdoSpatialUtility
	{
	public:
	    /// \brief
	    /// Evaluates if two FDO geometric objects spatially interact with each other based on a user supplied spatial operator.
	    /// For example: Contains, Crosses, Disjoint, Equals, Intersects, Overlaps, Touches, Within, CoveredBy, Inside, EnvelopeIntersects.
	    /// 
	    /// \param g1 
	    /// Input Left hand Geometry to Evaluate
	    /// \param op 
	    /// Input The spatial operation to apply to the left and right hand geometries 
		    /// \param g2 
	    /// Input Right hand Geometry to Evaluate
	    /// 
	    /// \param toleranceXY
	    /// Input XY tolerance to evaluate the spatial condition
	    /// 
	    /// \param toleranceZ
	    /// Input Z tolerance to evaluate the spatial condition
	    /// in case we have 3D geometries
	    /// 
	    /// \return
	    /// Returns the evaluation of spatial operation.
	    /// 
	    FDO_SPATIAL_API static bool Evaluate(FdoIGeometry* g1, FdoSpatialOperations op, FdoIGeometry* g2, double toleranceXY = 1e-10, double toleranceZ = 1e-10);  

Managed FDO API

The FDO Managed Interfaces will be updated in a similar manner to reflect the proposed changes (adding a new function which takes an additional parameter named tolerance).

Provider Implementation

Initially, we need this for SQLite provider. Other provider developers can use it and use it as needed. No change is required in other providers. SQLite provider must be changed in order to be able to store those tolerances. Right now the provider keeps just a few values for spatial context like srid, name, WKT, auth_Text, auth_srid, and we have to add tolerances. The old versions of provider will ignore those new columns, and the new provider in case will not find these tolerances will use the default values. All other providers don’t have to be changed and 1e-10 will be passed. Each provider will handle tolerances as they want. This RFC will not force providers to use the tolerance from spatial context (even that should be the right thing to do). This RFC will just add to the spatial FDO functions two new parameters, having as default values the values used till now (hard-coded values) in order to make possible that some providers which cares about tolerance to be able to use it. FDO spatial API had no way to pass tolerances and it used an internal hard-coded one making impossible for providers like SQLite to evaluate spatial queries having a certain tolerance.

Test Plan

Run existing FDO core unit tests and expand SQLite unit tests to test the proposed enhancements defined above.

Funding/Resources

Autodesk to provide resources / funding.