Support for three dimensional envelopes and bounding box filters - STEMLab/geotools GitHub Wiki

Description

The goal is to enable a geoserver WFS request with a 3D bounding box so that we receive only geometries not disjoint with that 3D bounding box.
In other words, there is a min and max for the third coordinate as well as the first two.

In 2D we have in KVP:

BBOX=x0,y0,x1,y1 However, in 3D we get:

BBOX=x0,y0,z0,x1,y1,z1

Only 3d geometries that qualify for the min and max pairs for all three axes are returned.

Furthermore, OGC filters in POST requests will also support 3D BoundingBoxes, as for example:

<ogc:Filter>" 
 <ogc:BBOX>" 
  <gml:Envelope srsName=\"EPSG:4979\">
    <gml:lowerCorner>-200 -200 0 </gml:lowerCorner>
    <gml:upperCorner> 200 200 50 </gml:upperCorner>
   </gml:Envelope>
 </ogc:BBOX>
</ogc:Filter>

In order to accomplish this, Geotools must support

  • 3D Envelopes: a 3D envelope geometry class and a 3D referenced envelope geometry class.
  • 3D Bounding Boxes: a 3D Bounding Box has two additional attributes (min z and max z) and filters geometries using all three dimensions.

Status

Voting has started:

Tasks

This section is used to make sure your proposal is complete (did you remember documentation?) and has enough paid or volunteer time lined up to be a success

  1. Update ReferencedEnvelope hierarchy

    • ✅NC: Define ReferencedEnvelope3D and a BoundingBox3D interface

    • ✅NC: Update ReferencedEnvelope.reference method to appropriately cast

    • ✅NC: Test cases for the above

    -:white_check_mark:NC: pull request / patch

2. Update BBox filter interface
- ✅NC: Add BBox.getBounds() and javadocs, the deprecated methods can refer to bbox.getBounds() above

 - :white_check_mark:NC: Update FilterFactory2 if needed (it works as a

literal expression, but javadocs may need a note)

 - :white_check_mark:NC: pull request / patch

3. Initial Filter support

- :white_check_mark: NC: initially implement as a "post" filter


- :white_check_mark: NC: test on property datastore (ie

AbstractDataStore base class)

  • ⚠️ test on property-ng datastore (ie. ContentDataStore base class)
- :white_check_mark: NC: test on postgis and oracle

4. Update documentation - before tagging in others so there are working examples

 - :white_check_mark: JG: review javadocs


 - :white_check_mark: NC: [gt-main filter

examples](http://docs.geotools.org/latest/userguide/library/opengis/filter.html) - prep code example or update existing example

 - :white_check_mark: NC: [gt-opengis filter

api](http://docs.geotools.org/latest/userguide/library/opengis/filter.html) update ObjectAID diagram and describe the new class
5. XML Encoding / Decoding

 - ? Update Filter 2 bindings


 - :white_check_mark: Update Filter 1.1 bindings


 - ? Update Filter 1.0 bindings


 - :white_check_mark: WFS POST/GET request Encoding\
 - :white_check_mark: BCD: Ensure OGC Standard supports n-dimensional

bounding boxes

6. Pull request

- :white_check_mark: submit pull request


- :white_check_mark: AA :review

7. Update and test downstream applications

  • ✅ NC: GeoServer patch

  • JG: uDig Patch

8. ⚠️ Support SQL encoding of 3D Bounding Boxes

- split the 3D bbox filter into two. PRE: reduce to a 2D bbox to take advantage of spatial

index. POST: Client side check of the Z values

- proof of concepts using jdbc-hsql


- roll out to remaining implementations: jdbc-postgis, jdbc-oracle etc...

9. QA Run to confirm existing datastore implementations do not fail when provided a 3D BBox to test against

  • ⛔ provide a sample test using shapefile
  • ⛔ cut and paste the test in for shapefile-ng, wfs and so on
  • ✅ JG: sample property file provided, with tests, showed several problems

10. ReferencedEnvelope fails when provided a 3D CRS

  • ✅ JG: GEOT-4325 Introduce factory method ReferencedEnvelope.create

11. FeatureCollection getBounds() implementations fail when provided a 3D CRS

  • ✅ JG: Fix PropertyDataStore so we have a working example
  • ✅ JG: GEOT-4331 Fix OracleDataStore (customer funded)
  1. Finish and cleanup

  • NC: revise based on integration with downstream applications (usually just javadocs, or the occasional bug report)

  • NC: Close the jira, news announcement, possible milestone release (depending on what you need for your deadline)

API Changes

The changes are API additions, rather than changes.
There will be the following new interfaces in geoapi:

  • BBOX3D, for the 3D bbox filter, subinterface of BBOX
  • BoundingBox3D, a subinterface of BoundingBox specifying bounding box coordinates

Furthermore, the existing BBOX as well as BBOX3D will support a new method BoundingBox getBounds() which returns a BoundingBox object representing the boundaries of the filter (BoundingBox3D if it is a BBOX3D).

There will be the following new classes in main

  • BBOX3DImpl, implementation of filter interface
  • ReferencedEnvelope3D, Extension of ReferencedEnvelope3D, extends JTS Envelope methods to use 3D coordinates and provides referenced envelope support for 3D coordinates

The FIlterFactory interfaces will be extended with the following methods:

  • BBOX3D bbox(String propertyName, BoundingBox3D bbox);
  • BBOX3D bbox( Expression geometry, BoundingBox3D bbox);
  • BBOX3D bbox( Expression geometry, BoundingBox3D bbox, MatchAction matchAction);

Furthermore, the implementation of the existing bbox( ..., BoundingBox bbox) methods will be extended to automatically call the 3D methods if the supplied BoundingBox is in fact a BoundingBox3D.

The existence of BBOX3D filter has implications for FilterVisitors. Although the APi does not change, the visitor method bbox must support BBOX3D if it wants to regenerate the filter without loosing information.

Because of the generic bbox( ..., BoundingBox bbox) and getBounds() methods it is possible to copy a BBOX filter in a generic way (see last example below).

These implications must all be documented.

Filter

BEFORE:

Envelope env = new ReferencedEnvelope(minx, maxx, miny, maxy, crs)



BBOX filter = filterfac.bbox(propertyName, minx, miny, minz, maxx, maxy, maxz, srs);
boolean result = filter.eval(geom);


BBOX otherFilter = ...
BBOX filter = filterfac.bbox(propertyName, otherfilter.getMinX(), ... , srs);

AFTER:

BoundingBox3D env = public ReferencedEnvelope3D(x1, x2, y1, y2, z1, z2, crs)
BBOX3D filter = filterfac.bbox(propertyName, env);
boolean result = filter.eval(geom);

BBOX otherFilter = ...
BBOX filter = filterfac.bbox(propertyName, otherfilter.getBounds());

Documentation Changes

list the pages effected by this proposal

Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️