Add geometry metadata in `gpf_wfs_get_features` response

[esgn]

• Geometry surface (when polygon)
• Geometry length (when linear)
• Distance to spatial filter reference (geom to geom distance)
• Intersection area with spatial filter reference

[LionelZoubritzky-IGN]

Could be added as options to geometry_keep if the design of #155 is accepted.

In that case, the geometry could be replaced by a feature field, being a GeoJSON.Feature object including different aspects of the returned object (centroid as geometry, bbox, surface, length, distance to spatial filter, etc.). We could also include a description field to that feature to explain to the LLM what is stored in the resulting object, that could be helpful.

[esgn]

Ok so we did not define anything clearly here. It's never too late.

The current available filters are :

• bbox_filter
• dwithin_point_filter
• intersects_feature_filter
• intersects_point_filter
• travel_time_filter

What we want to add as spatial extras :

• bbox
  • Except for single point
  • What we need this for : unclear but might help LLM to do further tool call with bbox_filter
• centroid
  • Mean of the vertices, may fall outside a concave geometry
  • Kept for single point : it is the point itself
  • What we need this for : unclear but might help LLM to do further tool call with dwithin_point_filter, intersects_point_filter and travel_time_filter
• area : only available for polygons, in m²
  • Polygon : area of the single polygon
  • MultiPolygon : sum of the polygon areas
  • GeometryCollection : sum of the polygon areas even if other geometry types are in GeometryCollection (overlapping parts counted twice)
  • What we need this for : prevent the LLM from calculating areas by itself.
• length : only available for linestrings in meters
  • LineString : length of the single linestring
  • MultiLinestring : sum of the linestring lengths
  • GeometryCollection : sum of the linestring lengths even if other geometry types are in GeometryCollection
  • Polygon boundaries are not counted (no perimeter)
  • What we need this for : prevent the LLM from calculating lengths by itself.
• intersection_area
  • Incompatible with intersects_point_filter
  • travel_time_filter with minutes==0 and a bbox_filter corresponding to a point (xmin==xmax and ymin==ymax) cannot happen in our implementation. So no need to reject these explicitely 😄
  • null when the reference of intersects_feature_filter is not a polygon
  • Incompatible with geometry of the following type : point, multipoint, linestring, multilinestring, geometrycollection which only contains geometry of the previous types.
  • 0 means no overlap, which can happen, for now, for returned features with bbox_filter (Document how bbox_filter works #196)
  • What we need this for : Unclear for the moment. Probably something to do with urban regulations ?
• distance_to_filter_center (renamed from distance_to_filter)
  • Filter center : the point for dwithin_point_filter and intersects_point_filter, the starting point for travel_time_filter, the centroid for bbox_filter and intersects_feature_filter
  • Three possible approaches : filter geometry to geometry (closest points), filter centroid to geometry centroid, filter centroid to geometry (closest point).
  • I'm leaning towards this : Distance from the filter center to the closest point of the feature, like ST_Distance(geom, center). 0 when the feature contains the center.
  • Rejected approaches : filter geometry to geometry is always 0 (every returned feature touches the filter, yeah except for Document how bbox_filter works #196) ; centroid to centroid misranks extended features (a river 10 m away can have its centroid km away) and exceeds distance_m with dwithin_point_filter
  • Incompatible with intersects_point_filter (always 0)
  • travel_time_filter with minutes==0 and a bbox_filter corresponding to a point (xmin==xmax and ymin==ymax) cannot happen in our implementation. So no need to reject these explicitely 😄
  • What we need this for => Being able to answer "what are the 5 closest swimming pools from IGN location ?"
  • This will only help the LLM to get reliable distances but won't give him a tool that solves this use case directly. no server-side sort on a spatial extra (follow-up : dedicated nearest tool ?)
  • What should happen : dwithin_point_filter around IGN with distance_to_filter_center, check numberReturned == numberMatched (else raise limit or shrink the radius), sort and keep 5, widen the radius if fewer than 5 are found

General rules :

• Error when the problem is known before the query (input, or layer geometry type from the catalog), null when a value cannot be computed for a feature, a number (0 included) means the computation ran
• Computed after the query, on returned features only : not usable in where or order_by
• distance_to_filter_center and intersection_area require a spatial filter and are only available in gpf_get_features

[esgn]

Current version

Truth table of spatial_extras as implemented at 63f06b1 (branch 136/more-spatial_extras, PR #187). "Error" means the call fails before the main query: "(input)" at input validation, "(catalog)" because of the catalog format of the queried layer, "(reference)" because of the intersects_feature_filter reference. A feature with a missing or empty geometry gets null for every extra.

1. Extras that do not depend on the filter, by geometry of the queried layer (catalog format)

extra	Point	MultiPoint	linear	areal	type not pinned (geometry-any)
centroid	the point itself	number	number	number	number
bbox	error (catalog)	box (degenerate for a single point)	box	box	box (degenerate for a point)
length	error (catalog)	error (catalog)	number	error (catalog)	number, null without a linear part
area	error (catalog)	error (catalog)	error (catalog)	number	number, null without an areal part

2. intersection_area, by spatial filter (rows) and geometry of the queried layer (columns)

filter	Point	MultiPoint	linear	areal	type not pinned (geometry-any)
none	error (input)	error (input)	error (input)	error (input)	error (input)
bbox_filter	error (catalog)	error (catalog)	error (catalog)	number, 0 possible (#196)	number, null without an areal part
dwithin_point_filter	error (catalog)	error (catalog)	error (catalog)	number (disc approximated by a 64-gon)	number, null without an areal part
intersects_point_filter	error (input)	error (input)	error (input)	error (input)	error (input)
intersects_feature_filter, areal reference	error (catalog)	error (catalog)	error (catalog)	number, 0 for a neighbour that only touches	number, null without an areal part
intersects_feature_filter, linear, MultiPoint or Point reference	error (catalog)	error (catalog)	error (catalog)	null for every feature	null for every feature
intersects_feature_filter, GeometryCollection reference	error (reference)	error (reference)	error (reference)	error (reference)	error (reference)
travel_time_filter	error (catalog)	error (catalog)	error (catalog)	number	number, null without an areal part

3. distance_to_filter_center, by spatial filter (the same for every queried geometry)

filter	result
none	error (input)
bbox_filter	number, from the box center
dwithin_point_filter	number, from the point
intersects_point_filter	error (input), would always be 0
intersects_feature_filter, areal or linear reference, or MultiPoint reference with several points	number, from the mean of the reference's vertices
intersects_feature_filter, Point reference or MultiPoint reference with a single point	0 for every feature (each one contains the point)
intersects_feature_filter, GeometryCollection reference	error (reference)
travel_time_filter	number, from the starting point

Notes:

• "Number" includes 0: a distance is 0 when the feature contains the filter center, an intersection area is 0 when there is no overlap.
• Type not pinned: the catalog format is geometry-any (or geometry-geometrycollection, unused today), so nothing is checked before the query; each feature is measured on its parts of the required dimension, which covers GeometryCollection features.
• A layer without geometry in the catalog (e.g. wfs_scot:doc_urba) is an error (catalog) for every extra.
• A queried layer or a reference that is not in the catalog, or a reference feature without a usable geometry, fails before the main query, whatever the extras.
• A MultiPoint with a single point is a Point in practice: every feature of localisant and borne_limite_propriete is one.
• gpf_get_feature_by_id: only table 1 applies; the two filter-dependent extras are rejected at input.
• Layer tools have no spatial_extras at all.

Proposed change

Truth table of spatial_extras after the decision on non-areal intersects_feature_filter references. Changed cells show the current value at 63f06b1 struck through, followed by the new one. "Error" means the call fails before the main query: "(input)" at input validation, "(catalog)" because of the catalog format of the queried layer, "(reference)" because of the intersects_feature_filter reference. A feature with a missing or empty geometry gets null for every extra.

1. Extras that do not depend on the filter, by geometry of the queried layer (catalog format)

extra	Point	MultiPoint	linear	areal	type not pinned (geometry-any)
centroid	the point itself	number	number	number	number
bbox	error (catalog)	box (degenerate for a single point)	box	box	box (degenerate for a point)
length	error (catalog)	error (catalog)	number	error (catalog)	number, null without a linear part
area	error (catalog)	error (catalog)	error (catalog)	number	number, null without an areal part

2. intersection_area, by spatial filter (rows) and geometry of the queried layer (columns)

filter	Point	MultiPoint	linear	areal	type not pinned (geometry-any)
none	error (input)	error (input)	error (input)	error (input)	error (input)
bbox_filter	error (catalog)	error (catalog)	error (catalog)	number, 0 possible (#196)	number, null without an areal part
dwithin_point_filter	error (catalog)	error (catalog)	error (catalog)	number (disc approximated by a 64-gon), 0 possible (#188)	number, null without an areal part
intersects_point_filter	error (input)	error (input)	error (input)	error (input)	error (input)
intersects_feature_filter, areal reference	error (catalog)	error (catalog)	error (catalog)	number, 0 for a neighbour that only touches	number, null without an areal part
intersects_feature_filter, linear, MultiPoint or Point reference	error (catalog)	error (catalog)	error (catalog)	null for every feature error (reference)	null for every feature error (reference)
intersects_feature_filter, GeometryCollection reference	error (reference)	error (reference)	error (reference)	error (reference)	error (reference)
travel_time_filter	error (catalog)	error (catalog)	error (catalog)	number	number, null without an areal part

3. distance_to_filter_center, by spatial filter (the same for every queried geometry)

filter	result
none	error (input)
bbox_filter	number, from the box center
dwithin_point_filter	number, from the point, can exceed distance_m (#188)
intersects_point_filter	error (input), would always be 0
intersects_feature_filter, areal or linear reference, or MultiPoint reference with several distinct points	number, from the mean of the reference's vertices
intersects_feature_filter, reference reduced to a single position (Point, or MultiPoint whose points are all the same)	0 for every feature error (reference)
intersects_feature_filter, GeometryCollection reference	error (reference)
travel_time_filter	number, from the starting point

Notes:

• "Number" includes 0: a distance is 0 when the feature contains the filter center, an intersection area is 0 when there is no overlap.
• "Error (reference)" for the new cases: the reference type is known before the main query, from the catalog when its format is precise, otherwise from the reference geometry, which is fetched before the main query. A reference reduced to a single position can only be detected from its geometry: the catalog format geometry-multipoint does not give the number of points.
• For intersects_feature_filter and travel_time_filter, "before the main query" means after the reference or the isochrone has been fetched.
• A MultiPoint with a single point is a Point in practice: every feature of localisant and borne_limite_propriete is one.
• Type not pinned: the catalog format is geometry-any (or geometry-geometrycollection, unused today), so nothing is checked before the query; each feature is measured on its parts of the required dimension, which covers GeometryCollection features.
• A layer without geometry in the catalog (e.g. wfs_scot:doc_urba) is an error (catalog) for every extra.
• A queried layer or a reference that is not in the catalog, or a reference feature without a usable geometry, fails before the main query, whatever the extras.
• gpf_get_feature_by_id: only table 1 applies; the two filter-dependent extras are rejected at input.
• Layer tools have no spatial_extras at all.

[LionelZoubritzky-IGN]

This table calls for different validation points. I see four of them:

• at zod-level for the error (input).
• for intersection_area and distance_to_filter_center, one validation after fetching the geometry type of the filter from the catalog, and another validation after fetching the actual filter if the catalog returns a geometry-any.
• after fetching the catalog of the returned geometries.

As discussed, there is no validation after the main query however, any surviving type mismatch gets a null.

[esgn]

Agreed on the four points. One remark on the order: points 1, 2 and 4 need no network, so they should all run before the reference or isochrone fetch; today the catalog check of the queried layer (4) runs after it, which is the "catalog checks before network" follow-up of #201. Point 3 then only covers what the catalog cannot tell: a geometry-any reference, and a geometry-multipoint reference reduced to a single position for distance_to_filter_center.