Introduction to OGC filters

For many applications, you need to identify a particular subset of a data set by specifying a number of conditions, so that you can take further action on that subset only. LuciadLightspeed allows you to use OGC filters to identify that data subset.

An OGC Filter is a construct used to constrain the property values of an object type for the purpose of identifying a subset of object instances. It is based on the Filter Encoding standards available on the OGC website. The document describes a system-neutral representation of a query predicate, encoded in XML.

In addition, the specification document defines a set of OGC expressions that can also be used for expressing a computed property of a given object, which is a parametric value that depends on the given object.

A large class of OpenGIS web-based services require the ability to express filters in XML. The Web Feature Service (WFS) uses the OGC filters in GetFeature and Transaction operations to define query constraints. The Styled Layer Descriptor (SLD) specification uses OGC filters to condition the application of styling rules. It also uses OGC expressions to define variable parameters of styling rules. You can use an OGC expression to define how the stroke color depends on the object that is being painted, for example.

The OGC filter API in LuciadLightspeed

The LuciadLightspeed OGC filter API provides a Java object representation of OGC filters and expressions independently from the XML encoding. This representation is called the OGC filter model and is described in The OGC filter model. The OGC filter model offers the following advantages:

  • It is independent of any version of the OpenGIS Filter Encoding Implementation specification. It can be obtained by decoding documents conforming to several versions of the specification. The OGC filter model also details how filters can be encoded according several versions of the specification. Moreover, this abstraction layer can help to minimize the impact of the evolution of the specification.

  • It is easier to build and manipulate programmatically than an XML document. It can be used for the creation and the edition of conforming OGC filter XML documents.

  • It is decoupled from any of its possible usages. It can then be evaluated in different ways under different circumstances. But it could also be translated into any other query language like SQL or XQuery in order to be used for querying an external datastore.

For the evaluation of an OGC filter model, the LuciadLightspeed OGC filter API offers a configurable and extensible evaluator that supports most of the constructs of the OGC filter elements.

The OGC filter evaluator allows you to:

See Styling data with OGC SLD for more information.

For a better understanding of the following sections, it is recommended to read the OpenGIS Filter Encoding Implementation specification document first.

The OGC filter model

Overview

An OGC filter is represented by a TLcdOGCFilter object, which contains a filter condition. The filter is intended to only accept the objects that meet this condition.

The filter conditions are based on filter expressions and they are built using conditional operators. The OGC filter model has several kinds of conditional operators: comparison operators, logical operators, spatial operators, null check operator, and so on. Each of those conditions is represented by a class listed in Filter conditions.

The filter expressions are the basic constructs of a filter model. They can be either literals, object properties referenced by their name or an XPath expression, functions or the result of arithmetic operations. For those four kinds of filter expression, the OGC filter model contains classes that are described in Filter expressions.

The most commonly used conditions and expressions of the OGC filters can be constructed by using the static methods of the TLcdOGCFilterFactory.

Filter expressions

The filter expressions are the basic constructs of the filter conditions. They also allow to express computed properties, or parametric values, that depend on a given object.

Each XML element of the OpenGIS Filter Encoding Implementation specification that represents an expression is modeled by a class in the LuciadLightspeed OGC filter model. This mapping is detailed in Table 1, “LuciadLightspeed classes for OGC filter expression elements”.

The ILcdOGCExpression interface is the common marker for OGC filter model classes that represent a filter expression.

Table 1. LuciadLightspeed classes for OGC filter expression elements
XML element Corresponding LuciadLightspeed class

<ogc:expression>

ILcdOGCExpression

<ogc:PropertyName>

TLcdOGCPropertyName

<ogc:Literal>

TLcdOGCLiteral

<ogc:Function>

TLcdOGCFunction

<ogc:Add>

TLcdOGCBinaryOperator with operation type equal to TLcdOGCBinaryOperator.ADD

<ogc:Mul>

TLcdOGCBinaryOperator with operation type equal to TLcdOGCBinaryOperator.MULTIPLY

<ogc:Sub>

TLcdOGCBinaryOperator with operation type equal to TLcdOGCBinaryOperator.SUBSTRACT

<ogc:Div>

TLcdOGCBinaryOperator with operation type equal to TLcdOGCBinaryOperator.DIVIDE

Examples of filter expressions are shown in Program: Representation of OGC filter expressions.

Program: Representation of OGC filter expressions (from samples/ogc/filter/model/OGCFilterModelSample) 
/*
  <ogc:PropertyName xmlns="http://someserver/myns">lastName</ogc:PropertyName>
*/
TLcdOGCPropertyName propertyName = property("lastName", "http://someserver/myns");

/*
  <ogc:PropertyName xmlns="http://someserver/myns">Person/lastName</ogc:PropertyName>
*/
TLcdOGCXPath xpath;
xpath = new TLcdOGCXPath("Person/lastName", "http://someserver/myns");
propertyName = new TLcdOGCPropertyName(xpath);

/*
  <ogc:Literal>John Smith</ogc:Literal>
*/
TLcdOGCLiteral literal = literal("John Smith");

/*
  <ogc:Literal>6000000</ogc:Literal>
*/
literal = literal(6000000);

/*
  <ogc:Function name="SIN" >
    <ogc:Literal>3.14159265359</ogc:Literal>
  </ogc:Function>
*/
TLcdOGCFunction function = function("SIN", literal(Math.PI));

/*
  <ogc:Add>
    <ogc:PropertyName xmlns="http://someserver/myns">lane</ogc:PropertyName>
    <ogc:Literal>-1</ogc:Literal>
  </ogc:Add>
*/
TLcdOGCBinaryOperator binaryOperator = add(property("lane", "http://someserver/myns"),
                                           literal(-1));

Filter conditions

The filter conditions are the filter constructs that return either true or false for a given object. They are used in TLcdOGCFilter for defining which object must be accepted or rejected.

Each XML element of the OpenGIS Filter Encoding Implementation specification that represents a condition is modeled by a class in the LuciadLightspeed OGC filter model. This mapping is detailed in Table 2, “LuciadLightspeed classes for OGC filter condition elements”.

The ILcdOGCCondition interface is the common marker for OGC filter model classes that represent a filter condition.

Table 2. LuciadLightspeed classes for OGC filter condition elements
XML element Corresponding LuciadLightspeed class

<ogc:PropertyIsEqualTo>

TLcdOGCBinaryComparisonOperator with comparison type equal to TLcdOGCBinaryComparisonOperator.EQUAL

<ogc:PropertyIsNotEqualTo>

TLcdOGCBinaryComparisonOperator with comparison type equal to TLcdOGCBinaryComparisonOperator.NOT_EQUAL

<ogc:PropertyIsGreaterThan>

TLcdOGCBinaryComparisonOperator with comparison type equal to TLcdOGCBinaryComparisonOperator.GREATER

<ogc:PropertyIsGreaterOrEqualThan>

TLcdOGCBinaryComparisonOperator with comparison type equal to TLcdOGCBinaryComparisonOperator.GREATER_OR_EQUAL

<ogc:PropertyIsLessThan>

TLcdOGCBinaryComparisonOperator with comparison type equal to TLcdOGCBinaryComparisonOperator.LESS

<ogc:PropertyIsLessOrEqualThan>

TLcdOGCBinaryComparisonOperator with comparison type equal to TLcdOGCBinaryComparisonOperator.LESS_OR_EQUAL

<ogc:PropertyIsBetween>

TLcdOGCIsBetweenOperator

<ogc:PropertyIsLike>

TLcdOGCIsLikeOperator

<ogc:PropertyIsNull>

TLcdOGCIsNullOperator

<ogc:BBOX>

TLcdOGCBBoxOperator

<ogc:Equals>

TLcdOGCBinarySpatialOperator with spatial interaction type equal to TLcdOGCBinarySpatialOperator.EQUALS

<ogc:Disjoint>

TLcdOGCBinarySpatialOperator with spatial interaction type equal to TLcdOGCBinarySpatialOperator.DISJOINT

<ogc:Touches>

TLcdOGCBinarySpatialOperator with spatial interaction type equal to TLcdOGCBinarySpatialOperator.TOUCHES

<ogc:Within>

TLcdOGCBinarySpatialOperator with spatial interaction type equal to TLcdOGCBinarySpatialOperator.WITHIN

<ogc:Overlaps>

TLcdOGCBinarySpatialOperator with spatial interaction type equal to TLcdOGCBinarySpatialOperator.OVERLAPS

<ogc:Crosses>

TLcdOGCBinarySpatialOperator with spatial interaction type equal to TLcdOGCBinarySpatialOperator.CROSSES

<ogc:Intersects>

TLcdOGCBinarySpatialOperator with spatial interaction type equal to TLcdOGCBinarySpatialOperator.INTERSECTS

<ogc:Contains>

TLcdOGCBinarySpatialOperator with spatial interaction type equal to TLcdOGCBinarySpatialOperator.CONTAINS

<ogc:DWithin>

TLcdOGCDistanceBuffer with spatial test type equal to TLcdOGCDistanceBuffer.DWITHIN

<ogc:Beyond>

TLcdOGCDistanceBuffer with spatial test type equal to TLcdOGCDistanceBuffer.BEYOND

<ogc:And>

TLcdOGCBinaryLogicOperator with logic operation type equal to TLcdOGCBinaryLogicOperator.AND

<ogc:Or>

TLcdOGCBinaryLogicOperator with logic operation type equal to TLcdOGCBinaryLogicOperator.OR

<ogc:Not>

TLcdOGCNotOperator

<ogc:After>

TLcdOGCBinaryTemporalOperator with temporal interaction type equal to TLcdOGCBinaryTemporalOperator.AFTER

<ogc:Before>

TLcdOGCBinaryTemporalOperator with temporal interaction type equal to TLcdOGCBinaryTemporalOperator.BEFORE

<ogc:Begins>

TLcdOGCBinaryTemporalOperator with temporal interaction type equal to TLcdOGCBinaryTemporalOperator.BEGINS

<ogc:BegunBy>

TLcdOGCBinaryTemporalOperator with temporal interaction type equal to TLcdOGCBinaryTemporalOperator.BEGUN_BY

<ogc:TContains>

TLcdOGCBinaryTemporalOperator with temporal interaction type equal to TLcdOGCBinaryTemporalOperator.T_CONTAINS

<ogc:During>

TLcdOGCBinaryTemporalOperator with temporal interaction type equal to TLcdOGCBinaryTemporalOperator.DURING

<ogc:EndedBy>

TLcdOGCBinaryTemporalOperator with temporal interaction type equal to TLcdOGCBinaryTemporalOperator.ENDED_BY

<ogc:Ends>

TLcdOGCBinaryTemporalOperator with temporal interaction type equal to TLcdOGCBinaryTemporalOperator.ENDS

<ogc:TEquals>

TLcdOGCBinaryTemporalOperator with temporal interaction type equal to TLcdOGCBinaryTemporalOperator.T_EQUALS

<ogc:Meets>

TLcdOGCBinaryTemporalOperator with temporal interaction type equal to TLcdOGCBinaryTemporalOperator.MEETS

<ogc:MetBy>

TLcdOGCBinaryTemporalOperator with temporal interaction type equal to TLcdOGCBinaryTemporalOperator.MET_BY

<ogc:TOverlaps>

TLcdOGCBinaryTemporalOperator with temporal interaction type equal to TLcdOGCBinaryTemporalOperator.T_OVERLAPS

<ogc:OverlappedBy>

TLcdOGCBinaryTemporalOperator with temporal interaction type equal to TLcdOGCBinaryTemporalOperator.OVERLAPPED_BY

<ogc:AnyInteracts>

TLcdOGCBinaryTemporalOperator with temporal interaction type equal to TLcdOGCBinaryTemporalOperator.ANY_INTERACTS

<ogc:rid>

TLcdOGCResourceId with comparison type equal to TLcdOGCResourceId.RID_PROPERTY

<ogc:previousRid>

TLcdOGCResourceId with comparison type equal to TLcdOGCResourceId.PREVIOUS_RID_PROPERTY

<ogc:version>

TLcdOGCResourceId with comparison type equal to TLcdOGCResourceId.VERSION_PROPERTY

<ogc:startDate>

TLcdOGCResourceId with comparison type equal to TLcdOGCResourceId.START_DATE_PROPERTY

<ogc:endDate>

TLcdOGCResourceId with comparison type equal to TLcdOGCResourceId.END_DATE_PROPERTY

Examples of filter conditions are shown in Program: Representation of OGC filter comparison conditions, Program: Representation of OGC filter spatial conditions and Program: Representation of OGC filter logic conditions.

Program: Representation of OGC filter comparison conditions (from samples/ogc/filter/model/OGCFilterModelSample) 
/*
  <ogc:PropertyIsGreaterThan>
    <ogc:PropertyName xmlns="http://someserver/myns">elevation</ogc:PropertyName>
    <ogc:Literal>0</ogc:Literal>
  </ogc:PropertyIsGreaterThan>
*/
TLcdOGCBinaryComparisonOperator binaryComparisonOperator =
    gt(property("elevation", "http://someserver/myns"), literal(0));

/*
  <ogc:PropertyIsLike wildCard="*" singleChar="?" escapeChar="\">
    <ogc:PropertyName xmlns="http://someserver/myns">lastName</ogc:PropertyName>
    <ogc:Literal>John*</ogc:Literal>
  </ogc:PropertyIsLike>
*/
TLcdOGCIsLikeOperator isLikeOperator =
    like(property("lastName", "http://someserver/myns"), "John*");
Program: Representation of OGC filter spatial conditions (from samples/ogc/filter/model/OGCFilterModelSample) 
/*
  <ogc:BBOX>
    <ogc:PropertyName>Geometry</ogc:PropertyName>
    <gml:Envelope srsName="EPSG:4326">
      <gml:lowerCorner>13.0983 31.5899</gml:lowerCorner>
      <gml:upperCorner>35.5472 42.8143</gml:upperCorner>
    </gml:Envelope>
  </ogc:BBOX>
*/
TLcdOGCBBoxOperator bboxOperator = new TLcdOGCBBoxOperator(
    property("Geometry", "http://www.opengis.net/ogc"),
    new TLcdLonLatBounds(13.0983, 31.5899, (35.5472 - 13.0983), (42.8143 - 31.5899)),
    new TLcdGeodeticReference(new TLcdGeodeticDatum()));

/*
  <ogc:Intersects>
    <ogc:PropertyName>Geometry</ogc:PropertyName>
    <gml:Envelope srsName="EPSG:4326">
      <gml:lowerCorner>13.0983 31.5899</gml:lowerCorner>
      <gml:upperCorner>35.5472 42.8143</gml:upperCorner>
    </gml:Envelope>
  </ogc:Intersects>
*/
TLcdOGCBinarySpatialOperator binarySpatialOperator = new TLcdOGCBinarySpatialOperator(
    TLcdOGCBinarySpatialOperator.INTERSECTS,
    property("Geometry", "http://www.opengis.net/ogc"),
    new TLcdLonLatBounds(13.0983, 31.5899, (35.5472 - 13.0983), (42.8143 - 31.5899)),
    new TLcdGeodeticReference(new TLcdGeodeticDatum()));
Program: Representation of OGC filter logic conditions (from samples/ogc/filter/model/OGCFilterModelSample) 
/*
  <ogc:And>
    <ogc:Not>
      <ogc:PropertyIsNull>
        <ogc:PropertyName xmlns="http://someserver/myns">elevation</ogc:PropertyName>
      </ogc:PropertyIsNull>
    </ogc:Not>
    <ogc:PropertyIsEqualTo>
      <ogc:PropertyName xmlns="http://someserver/myns">elevation</ogc:PropertyName>
      <ogc:Literal>0</ogc:Literal>
    </ogc:PropertyIsEqualTo>
  </ogc:And>
*/
TLcdOGCBinaryLogicOperator binaryLogicOperator =
    and(not(isNull(property("elevation", "http://someserver/myns"))),
        eq(property("elevation", "http://someserver/myns"), literal(0)));

Limitations

The TLcdOGCFilterEvaluator supports spatial operators with the following limitations:

  • If the Advanced GIS Engine component is not available in your LuciadLightspeed installation, only the BBOX operator is supported.

  • With the exception of the BBOX operator, the spatial evaluators do not perform georeference transformations. As a consequence, they cannot compare geometries with two distinct georeferences.

  • The Crosses and Overlaps operators only work for 2D curves.