Skip to content

Validate winding order for polygons in the geometry field #73

Open

Description

@thatbudakguy

The spec for the Geometry field allows both ENVELOPE(W,E,N,S) syntax and WKT POLYGON/MULTIPOLYGON geometries. It also says:

Note that WKT polygon vertices should be defined in counter-clockwise order.

...which corresponds to W,E,N,S, just like ENVELOPE uses.

However, this isn't enforced in any particular way – the JSON schema only validates that this field is a string, GeoCombine doesn't do any validation of it, and GeoBlacklight's own example solr schema includes an example that is clockwise (and thus invalid).

There's a good reason for it, though: the location_geo3d field definition in GeoBlacklight uses the Geo3D spatialContextFactory, which requires that polygons are "wound" counter-clockwise:

When using Geo3D, the order of polygon points matters! You must follow the so-called "right hand rule": the exterior ring must be counter-clockwise order and the interior holes must be clockwise. If the order is wrong then the interpretation is inverted, thus the polygon will be interpreted as encompassing most of the globe.

And indeed this is exactly what happens – for this search limited to a bounding box covering India, virtually all of the first-page results are largely unrelated items in the United States, because their bounding boxes in locn_geometry are clockwise instead, and so they effectively cover the entire world, matching any search.

This problem is widespread:

Repo Clockwise records Notes
edu.indiana 11,343  
edu.umn 5,447 1 is a multipolygon
edu.rutgers 4,538 every Aardvark record
edu.illinois 3,992 every Aardvark record but 1
edu.psu 3,559  
edu.uiowa 1,841  
edu.msu 1,333  
edu.umich 1,136 1 is a multipolygon
edu.unl 418  
edu.umd 268 every record
edu.osu 255  
edu.purdue 116 every record
edu.northwestern 94  
edu.uchicago 63  
edu.uwm 9 all multipolygons
geobtaa 4

Activity

  1. thatbudakguy commented on Sep 29, 2026

    @thatbudakguy
    MemberAuthor

    Some history I could find on this question:

    In 2017 we had the original request for GeoBlacklight to support filtering via geometry, not just bounding boxes. From that point onward there was discussion of adding support for JTS, which enables WKT geometries in solr but requires adding an external JAR to Solr.

    In 2021 we got support for complex geometries via either JTS or Geo3D, but it seemed like overlap boosting with JTS actually didn't work and by 2022 we ended up ultimately going with Geo3D because Solr support for it had stabilized by that time.

    Geoblacklight v4 debuted the split between the dedicated dcat_bbox field for boosting and the locn_geometry field for intersection/filtering, which used Geo3D (the design we have now). At that time, we updated the Aardvark spec to require that WKT POLYGONs use CCW winding.

  2. thatbudakguy commented on Sep 29, 2026

    @thatbudakguy
    MemberAuthor

    I think the source of many of these clockwise BTAA records might be some code that is no longer in use, and the new OGM Metadata Studio seems like it correctly winds polygons counterclockwise. So correcting these seems like a one-time task, although it leaves open the question of whether we should validate them going forward (or even change this requirement entirely).

    The records in edu.umd were updated last month, though, and they all have clockwise polygons, so I'm not sure what produced those.

  3. ewlarson commented on Sep 29, 2026

    @ewlarson
    Contributor

    For your eyes: @karenmajewicz

  4. thatbudakguy commented on Sep 29, 2026

    @thatbudakguy
    MemberAuthor

    Worth noting that, as of right now, there are zero non-rectangular WKT POLYGONs in locn_geometry fields in all of OGM, and only 12 MULTIPOLYGONs. So our support for filtering by complex geometry isn't really getting exercised, at least in GeoBlacklight.

    That said, that only reflects existing (mostly old) data. If we start pulling in lots more things like this map, we could actually leverage the geometry more.

  5. karenmajewicz commented on Sep 29, 2026

    @karenmajewicz
    Collaborator

    For nearly all of the maps from the BTAA, we enter 4 coordinates in dcat_bbox. When we upload them to GEOMG, locn_geometry is automatically calculated and filled in, so I the code for GBL Admin is still the source of this issue. (https://github.com/geobtaa/geoblacklight_admin/blob/main/app/models/document.rb#L427-L429)

    I have a newer set of records that is using polygons and multipolygons (in the BTAA Geoportal here). I will check the order of the coordinates and share them to OpenGeoMetadata.

  6. karenmajewicz commented on Oct 1, 2026

    @karenmajewicz
    Collaborator

    I made progress on this issue:

    • I consolidated all the BTAA collections into one repo: https://github.com/OpenGeoMetadata/geobtaa/. This will allow us to update the records more frequently
    • For most records, we just have rectangular bounding boxes, so I changed the locn_geometry field to use the ENVELOPE syntax
    • For the Polygons and Multipolygons, I reordered the coordinates.

    There are several polygons and multipolygons found under Datasets where the directory starts with b1g_. Some candidates for testing could be:

    Multipolygon (with holes): https://raw.githubusercontent.com/OpenGeoMetadata/geobtaa/refs/heads/main/metadata-aardvark/Datasets/b1g_17_12385/b1g_q4VciFpiMEmX.json

    Polygon (non rectangular: https://raw.githubusercontent.com/OpenGeoMetadata/geobtaa/refs/heads/main/metadata-aardvark/Datasets/b1g_24_51000/b1g_Ixjxcs1V3egs.json

  7. thatbudakguy commented on Oct 9, 2026

    @thatbudakguy
    MemberAuthor

    I just checked the EarthWorks search for US Army Corps of Engineers records in India that I used when reporting this issue, and it now (correctly) returns no results! Thanks for remediating all those records.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions