= FDO RFC 39 - Spatial operator combinations support =

This page contains an change request (RFC) for the FDO Open Source project.  
More FDO RFCs can be found on the [wiki:FDORfcs RFCs] page.


== Status == 
 
||RFC Template Version||(1.0)|| 
||Submission Date|| June 08, 2009 ||
||Last Modified|| Dan Stoica[[Timestamp]]||
||Author||Dan Stoica, Orest Halustchak ||
||RFC Status||draft|| 
||Implementation Status||draft||
||Proposed Milestone||3.5.0.0||
||Assigned PSC guide(s)||Greg Boone||
||'''Voting History'''|| ||
||+1|| ||
||+0|| ||
||-0|| ||
||-1|| ||
 
== Overview ==

This RFC is for adding spatial operator combinations support.

== Motivation ==

Allows implementation of the RELATE spatial filter.

[TODO]

== Proposed Solution ==

A number of changes in FDO are proposed:

1) Add new FdoSpatialOperations_Relate to FdoSpatialOperations enumeration.

2) Assign values to FdoSpatialOperations so they can be bitmapped:

{{{
enum FdoSpatialOperations
{
    FdoSpatialOperations_EnvelopeIntersects = 0x0000, 
    FdoSpatialOperations_Relate     = 0x0001,  
    FdoSpatialOperations_Contains   = 0x0002,
    FdoSpatialOperations_Crosses    = 0x0004,
    FdoSpatialOperations_Disjoint   = 0x0008,
    FdoSpatialOperations_Equals     = 0x0010,
    FdoSpatialOperations_Intersects = 0x0020,
    FdoSpatialOperations_Overlaps   = 0x0040,
    FdoSpatialOperations_Touches    = 0x0080,
    FdoSpatialOperations_Within     = 0x0100,
    FdoSpatialOperations_CoveredBy  = 0x0200, 
    FdoSpatialOperations_Inside     = 0x0400
};
}}}

3) Enhance FdoSpatialCondition class to handle a bitmapped mask of spatial operators. Avoid creating a new set of constructors just for RELATE, by adding an extra optional parameter to the existing constructors. Add setter and getter for the mask.


{{{
class FdoSpatialCondition : public FdoGeometricCondition
{
...
    /// \param relateMask 
    /// Input bitmapped FdoSpatialOperations mask for the RELATE spatial operation
    /// 
    /// \return
    /// Returns FdoSpatialCondition
    /// Throws "Invalid parameter" exception in case relateMask > 0 and the operation is not RELATE
    /// 

    FDO_API static FdoSpatialCondition* Create(FdoIdentifier* propertyName, FdoSpatialOperations operation, FdoExpression* geometry, FdoInt32 relateMask = -1);

////\\\\ NOTE: the same extra optional parameter will be added to all the constructors.

    /// Sets the bitmapped value of combined spatial operator(s) for RELATE usage.
    /// Throws "Invalid parameter" exception in case:
    ///     value > 0 and the spatial operation is not RELATE
    ///     value <= 0 and the spatial operation is RELATE
    ///     value is not a valid bitmapped FdoSpatialOperations mask

    FDO_API void SetRelateMask( FdoInt32 value );

    /// Gets the bitmapped value of combined spatial operators. 

    FDO_API FdoInt32 GetRelateMask();
}
}}}


4) Provide a common implementation for computing the pattern matrix in FdoSpatialUtility class. The matrixes for individual operations are available on the OGS site. Given a combination of operators, the method will perform an OR operation for each element of the matrix, interatively for each matrix involved.

{{{
class FdoSpatialUtility
{
...
    /// \brief
    /// Computes the pattern matrix DE-9IM compliant. 
    /// See the Extended Nine-Intersection Model (DE-9IM) of the spatial operation at
    /// http://portal.opengeospatial.org/files/?artifact_id=18241 , section 6.1.15. 
    /// 
    /// \param value 
    /// Input the bitmapped mask of FdoSpatialOperations.
    /// 
    /// \return
    /// Returns a valid 9 characters string representing the pattern matrix.
    /// Returns NULL in case the input is invalid.
    /// Example: 'T*F**F***' is returned for 'Within' spatial operation
    /// 
    FDO_API static FdoString* GetOGSPatternMatrix(FdoInt32 value);
}}}

== Implications ==

RDBMS providers supporting natively the RELATE spatial operator can implement the new API by examining the mask:

{{{
      FdoSpatialCondition*  pFilter = ...
      Int32  mask = pFilter->GetRelateMask();
}}}
 
SqlServer Spatial or PostGIS providers need the string pattern matrix to pass it as input for STRelate() and ST_Relate() respectively:
 
{{{
     FdoString* matrix = FdoSpatialUtility::GetOGSPatternMatrix( mask );

     // Build the SQL like: STRelate(' + matrix +');
}}}

Oracle providers will inspect the bitmapped mask and extract the spatial operators to build the SQL like:

{{{
     SDO_RELATE(... 'mask=touch+coveredby') = 'TRUE';
}}}


== Test Plan ==
[TODO]

== Funding/Resources ==

Autodesk to provide resources / funding.

== Referencies ==
[TODO]