Point events and drawing events on the route
LineEvents (ADR 0033) does the arithmetic on tables of events with a range. A route system also has events at a single M value: a bridge, a culvert, a damage report, a hydrant. Their questions are different: which speed limit holds at this bridge?, which bridges lie on this stretch?, which have no speed limit at all? And every table, of ranges or of points, has to be drawn on the map. This adds the type PointEvent<T>, the operations PointEvents.Between, Within and Outside, and LocateEvents, which draws a whole table on the route.
German version: 0040-punktereignisse-und-ereignisse-auf-der-karte.de.md
Consequences
Placement:
PointEvent<T>and the static classPointEventsinSpatialNET.Extensions(their own file), and the twoLocateEventsextension methods inLinearReferencing(ADR 0017), namespaceSpatialNET. For the package validation and the API tracking this is an addition only (ADR 0028).The data type:
readonly record struct PointEvent<T>(double M, T Value), the counterpart ofLineEvent<T>(ADR 0033): a plain value without validation in the constructor, with the attributes of the host's choice. As there, the library never reads a table and knows no route id (the host groups by route), and the M values are M values, not lengths.Operations (static, not extension methods, for the reason of ADR 0033; results are lists, sorted by M, and events with the same M keep the order of the input):
Method Meaning PointEvents.Between(points, from, to)the point events whose M lies in the closed range; swapped bounds are the same range PointEvents.Within(points, lines, combine)for every point event the line events that contain its M: one result per pair, at the M of the point, with the value combinemakes of the twoPointEvents.Outside(points, lines)the point events that lie in no line event The ranges of line events are closed, so a point exactly on the boundary of two neighbouring events lies in both and
Withingives two results (asLineEvents.At, ADR 0033); line events may overlap, and every overlapping one gives a result. A line event without length (From == To) is ignored andFromgreater thanTois read swapped, as there.NaNor an infinite M,FromorTois anArgumentOutOfRangeExceptionthat names the event; anulltable or function is anArgumentNullException.Outsideis the quality check: a bridge without a speed limit, a report off the surveyed stretch, a gap in a table. Together withWithinit splits the point events into those with and those without a line event, andLineEvents.Differenceof an event that covers the whole route and a line table gives the gaps of that table.LocateEventsdraws a table on the route, one entry per event, in the order of the input:IReadOnlyList<(LineEvent<T> Event, IPolyline2D Shape)> LocateEvents<T>(this IPolyline2D route, IEnumerable<LineEvent<T>> events, IGeometryFactory? factory = null) IReadOnlyList<(PointEvent<T> Event, IMultiPoint2D Points)> LocateEvents<T>(this IPolyline2D route, IEnumerable<PointEvent<T>> events, IGeometryFactory? factory = null)A line event becomes the stretch of
LocateBetween(ADR 0032), a point event the points ofLocateAlong(several where the route passes the value more than once). An event whose M the route does not reach keeps its entry, with an empty polyline or multipoint, so that the result can be matched to the input by position and by event. The index of the route is built once for the whole table, so a table of many events costs little more than one, where a loop ofLocateBetweenwould build it for each. The route needs M (as for those methods); an event with aNaNor infinite bound is anArgumentOutOfRangeException.The result is a tuple list, not a new type: the event and its geometry are all there is, and a tuple deconstructs in a
foreach. The geometries are created through the factory; the events are the host's own values.Playground (ADR 0011): a new parameter type
text(several lines) for the tables of events, and the entriesLocateEvents(a table drawn on the route) andIntersectEvents(two tables intersected, drawn on the route). The table is plain text, one event per line:from..to valuefor a line event,m valuefor a point event,#starts a comment. The examples are a road with speed limits, surfaces and bridges, and a hairpin where an M range and a value occur twice.Tests (ADR 0008):
[Covers]tests.Between(closed range, swapped bounds, sorted, equal M keep the input order);Within(a result per pair, two on a boundary, one per overlapping event, line events without length ignored, swapped bounds, unsorted input);Outside; a model test that comparesWithinandOutsidewith a brute-force check over random tables; errors;LocateEvents(the order and one entry per event, empty shapes, several points where the route passes a value twice, agreement withLocateBetweenandLocateAlong, errors).Not now: assigning a point event to the nearest route (a point on the map is
ProjectToM, ADR 0017, andLocateFeature, ADR 0034, gives the range of a line or area), several routes in one call (the host groups), and a tolerance for "near" a line event (a point event is exactly in a range or not).
Considered Options
- A point event as a line event with
From == To(rejected:LineEventsignores events without length because a piece without length is nothing, whereas a point event is exactly such a thing; and the types tell a reader which is which) - Extension methods on
IEnumerable<PointEvent<T>>(rejected for the reason of ADR 0033:Enumerablehas its ownWhere,Exceptand the like, and the operations are not a LINQ pipeline) Withinthat returns the line event's value only, or a pair type (rejected:combinegives the caller the choice, and a tuple or a record is one lambda; ADR 0033 does the same forIntersect)LocateEventsthat returns only the geometries (rejected: the association with the event is what the caller needs to style or label it, and matching by index is fragile when the input is a query)- Dropping the events that the route does not reach (rejected: one entry per event keeps the result aligned with the table, and an empty geometry says what it is; Voronoi does the same, ADR 0036)
- A
LocateEventsthat takes a table of any events through a function (rejected: the two kinds already differ in what they return, a polyline or a multipoint, and two overloads are clearer than a generic selector) - A text format for tables in the library (rejected: the library never reads tables, ADR 0033; the format belongs to the playground, which needs it to enter a table in a text box)