Utility

Location Group

Der Node prüft, in welchem der konfigurierten Gebiete ein Punkt liegt, zum Beispiel in welcher Gemeinde oder in welchem Landkreis. Die Gebiete suchen Sie im Editor über OpenStreetMap Nominatim und ordnen sie Gruppennamen zu. Im Betrieb schreibt der Node den Gruppennamen in eine Ausgabe-Eigenschaft oder lässt nur Nachrichten durch, die in einem Gebiet liegen. Die Prüfung erfolgt lokal mit Turf.js, ohne Anfrage an einen Dienst.

Gebietszuordnung
Point-in-Polygon
Filter

Node-Typ: location-group
Paket: @htag/node-red-contrib-hypertegrity-utility
Eingänge / Ausgänge: 1 / 1
Abhängigkeit: @turf/boolean-point-in-polygon; Nominatim nur im Editor

Wofür Sie den Node verwenden

In einer regionalen Datenplattform stammen Messwerte oft aus mehreren Gemeinden oder Kreisen. Der Location-Group-Node ordnet jeden Datenpunkt anhand seiner Koordinaten einem Gebiet zu, ohne dass Sie Polygone selbst pflegen müssen: Die Grenzen laden Sie direkt aus OpenStreetMap in den Node.

Typische Einsatzfälle sind:

Datenpunkte nach Gemeinde gruppieren: Sensoren eines Verbunds erhalten die Eigenschaft locationGroup, damit Dashboards nach Gemeinde filtern können.
Datenströme auf ein Gebiet begrenzen: Nur Fahrzeuge, Messungen oder Meldungen innerhalb des eigenen Stadtgebiets werden weiterverarbeitet.
Mehrere Gebiete zu einer Gruppe zusammenfassen: Mehrere Ortsteile oder Gemeinden erhalten denselben Gruppennamen, etwa für einen Versorgungsbereich.

So funktioniert der Node

Gebiete festlegen

Im Editor suchen Sie Verwaltungsgrenzen über Nominatim oder klicken auf die Karte. Die Polygone werden mit der Flow-Konfiguration gespeichert.

Koordinaten lesen

Im Betrieb liest der Node Breiten- und Längengrad oder ein Koordinaten-Array an den konfigurierten Pfaden, für jede Nachricht oder jeden Array-Eintrag.

Punkt gegen Polygone prüfen

Turf.js prüft lokal, ob der Punkt in einem der Polygone liegt. Das erste treffende Gebiet gewinnt.

Anreichern oder filtern

Je nach Modus wird der Gruppenname in die Ausgabe-Eigenschaft geschrieben oder die Nachricht beziehungsweise der Array-Eintrag verworfen.

Ergebnis: Nachrichten oder Array-Einträge mit einem normalisierten Gruppennamen, oder nur die Einträge, die in einem konfigurierten Gebiet liegen.

Der Node ist nachrichtengetrieben und arbeitet im Betrieb vollständig lokal. Nominatim wird nur im Editor beim Suchen von Gebieten angefragt. Sind keine Gebiete konfiguriert, reicht der Node jede Nachricht unverändert weiter. Der Gruppenname wird normalisiert: Umlaute werden umschrieben (ä → ae, ß → ss), Leerzeichen durch _ ersetzt und alle anderen Zeichen außer Buchstaben, Ziffern und _ entfernt. Ohne Treffer lautet der Wert unknown.

Konfiguration

Der Bearbeitungsdialog besteht aus den Registerkarten Regionen, Einstellungen und Daten-Erkennung. Das Feld Name steht oberhalb der Registerkarten.

Feld	Typ	Standard	Bedeutung
Name	Text	leer	Anzeigename des Nodes im Flow.

Registerkarte Regionen

Feld	Typ	Standard	Bedeutung
OSM Grenzen suchen	Suchfeld	leer	Sucht über den Admin-Endpunkt `/location-group/search` bei Nominatim nach Gebieten (bis zu 10 Treffer). Nur Treffer mit Polygon oder MultiPolygon werden angezeigt. Mit + übernehmen Sie das Gebiet in die Liste.
Ausgewählte Regionen	Liste	leer	Je Zeile ein Gebiet mit Gruppe (frei editierbar, Standard: erster Teil des Nominatim-Namens) und Gebiet (vollständiger Name, schreibgeschützt). Mehrere Gebiete dürfen denselben Gruppennamen tragen. Die Liste wird mit Polygon in der Node-Eigenschaft `regions` gespeichert.
Kartenvorschau	Karte	–	Leaflet-Karte mit allen gespeicherten Polygonen. Ein Klick auf die Karte fragt über `/location-group/find-at` die Verwaltungshierarchie an der Position ab (Zoomstufen 8, 10 und 14, also Kreis, Gemeinde und Ortsteil) und bietet die gefundenen Grenzen zur Übernahme an.

Registerkarte Einstellungen

Feld	Typ	Standard	Bedeutung
Modus	Auswahl	Anreichern (Eigenschaft anhängen)	`enrich` schreibt den Gruppennamen oder `unknown` in die Ausgabe-Eigenschaft. `filter` lässt nur Nachrichten beziehungsweise Array-Einträge durch, die in einem Gebiet liegen.
Auch beim Filtern anreichern	Kontrollkästchen	inaktiv	Nur im Modus Filtern: schreibt zusätzlich den Gruppennamen in die Ausgabe-Eigenschaft.
Filter Umkehren (Unbekannte behalten)	Kontrollkästchen	inaktiv	Nur im Modus Filtern: behält nur Nachrichten, die in keinem Gebiet liegen.
Ausgabe-Eigenschaft	Typed Input (`msg`)	`locationGroup`	Pfad, in den der Gruppenname geschrieben wird. Bei einzelnen Objekten relativ zu `msg`, bei Arrays relativ zu jedem Eintrag (siehe Ausgang).

Registerkarte Daten-Erkennung

Feld	Typ	Standard	Bedeutung
Beispiel JSON	Textfeld	leer	Beispiel-Payload (Objekt oder Array). Einstellungen automatisch erkennen sucht darin nach einem GeoJSON-Point, einem Objekt mit `lat`/`lon` oder einem Zahlenpaar und schlägt die Feldpfade vor; Apply to Form übernimmt sie. Die erkannten Pfade dienen zudem als Vorschläge in den Pfadfeldern.
Geo Type	Auswahl	Point	Geometrietyp der Eingabedaten: `Point`, `LineString`, `Polygon`, `MultiPoint`, `MultiLineString` oder `MultiPolygon`. Ausgewertet werden Point-Geometrien.
Position Type	Auswahl	Separate Lat/Lon Fields	Bei Geo Type Point: `separate` (zwei Felder) oder `array` (Koordinaten-Array).
Latitude Field	Pfad	leer	Pfad zum Breitengrad, zum Beispiel `location.coordinates[1]`.
Longitude Field	Pfad	leer	Pfad zum Längengrad, zum Beispiel `location.coordinates[0]`.
Array Field	Pfad	leer	Pfad zum Koordinaten-Array, zum Beispiel `location.coordinates`.
GeoJSON Field	Pfad	leer	Bei anderen Geo Types: Pfad zum `coordinates`-Array der Geometrie.
Coord Order	Auswahl	Longitude, Latitude	Reihenfolge im Koordinaten-Array: `lonlat` (GeoJSON-Standard) oder `latlon`.
Preview Map	Karte	–	Zeigt die aus dem Beispiel JSON gelesene Position und meldet ungültige oder fehlende Koordinaten.

Die Felder Geo Type, Position Type, Latitude/Longitude Field, Array Field, GeoJSON Field und Coord Order werden gemeinsam in der Node-Eigenschaft locationConfig gespeichert.

Pfade bei einzelnen Objekten

Pfade werden standardmäßig relativ zu msg.payload ausgewertet. Beginnt der Pfad des Breitengrad- oder Array-Feldes mit payload, wertet der Node relativ zu msg aus; beginnt er mit msg., relativ zum Nachrichtenobjekt. Bei Arrays sind Pfade immer relativ zum einzelnen Eintrag.

Eingang

Eigenschaft	Typ	Bedeutung
`msg.payload`	Objekt	Einzelner Datenpunkt. Die konfigurierten Pfade werden relativ zu `msg.payload` gelesen (Ausnahmen siehe Hinweis oben).
`msg.payload`	Array von Objekten	Liste von Datenpunkten. Jeder Eintrag wird einzeln geprüft; Pfade sind relativ zum Eintrag.
Koordinatenfelder	Zahl oder numerischer Text	Breiten- und Längengrad in Dezimalgrad oder ein Array mit mindestens zwei Zahlen in der konfigurierten Reihenfolge.

Ohne konfigurierte Regionen wird jede Nachricht unverändert weitergegeben.

Ausgang

Im Modus Anreichern mit einem Array in msg.payload sieht die Ausgabe zum Beispiel so aus:

[
  {
    "id": "urn:ngsi-ld:WeatherObserved:station-01",
    "location": {"type": "Point", "coordinates": [8.6, 49.5]},
    "locationGroup": "Beispielgemeinde"
  },
  {
    "id": "urn:ngsi-ld:WeatherObserved:station-02",
    "location": {"type": "Point", "coordinates": [9.9, 50.8]},
    "locationGroup": "unknown"
  }
]

Feld	Bedeutung
`<Ausgabe-Eigenschaft>` auf jedem Array-Eintrag	Normalisierter Gruppenname des ersten treffenden Gebiets oder `unknown`. Wird mit Punkt-Notation relativ zum Eintrag gesetzt, Zwischenobjekte werden angelegt.
`msg.<Ausgabe-Eigenschaft>` bei einzelnem Objekt	Bei einem einzelnen Objekt wird die Ausgabe-Eigenschaft über `RED.util.setMessageProperty` relativ zu `msg` gesetzt. Mit dem Standard `locationGroup` entsteht also `msg.locationGroup`; für einen Wert in der Payload tragen Sie `payload.locationGroup` ein.
`msg.payload`	Im Modus Filtern enthält das Array nur noch die durchgelassenen Einträge; eine einzelne Nachricht ohne Treffer wird gar nicht gesendet. Mit Filter Umkehren bleiben nur Einträge ohne Treffer; ist zusätzlich Auch beim Filtern anreichern aktiv, erhalten sie den Wert `unknown`.

Beispiel-Flow

Das Paket bringt einen Beispiel-Flow mit. Sie importieren ihn in Node-RED über Menü → Importieren → Beispiele → @htag/node-red-contrib-hypertegrity-utility → location-group. Alternativ laden Sie die Datei location-group.json herunter und importieren sie über Menü → Importieren. Die Datei enthält das vollständige Gemeindepolygon aus OpenStreetMap und ist deshalb umfangreich.

Schritt 1

Inject und Function

Ein Inject-Node löst eine Function aus, die ein Array mit einer NGSI-LD-ähnlichen Entität samt GeoJSON-Punkt erzeugt.

Schritt 2

Location Group

Der Node liest location.coordinates, prüft den Punkt gegen das gespeicherte Gemeindepolygon und schreibt locationGroup.

Schritt 3

Debug

Ein Debug-Node zeigt das angereicherte Array in der Seitenleiste an.

Beispiel-Flow als JSON anzeigen (Polygon gekürzt)

[
  {"id": "tab1", "type": "tab", "label": "location-group", "disabled": false, "info": ""},
  {"id": "inject1", "type": "inject", "z": "tab1", "name": "Go!", "props": [{"p": "payload"}], "repeat": "", "once": false, "payload": "", "payloadType": "date", "x": 90, "y": 120, "wires": [["fn1"]]},
  {"id": "fn1", "type": "function", "z": "tab1", "name": "Input", "func": "msg.payload = [{\"id\":\"urn:ngsi-ld:1\",\"location\":{\"type\":\"Point\",\"coordinates\":[8.6,49.5]}}];\nreturn msg;", "outputs": 1, "x": 250, "y": 120, "wires": [["lg1"]]},
  {"id": "lg1", "type": "location-group", "z": "tab1", "name": "", "groupingMode": "enrich", "enrichOnFilter": false, "invertFilter": false,
    "locationConfig": "{\"type\":\"Point\",\"posType\":\"array\",\"latField\":\"\",\"lonField\":\"\",\"arrayField\":\"location.coordinates\",\"polyField\":\"\",\"order\":\"lonlat\"}",
    "sampleJson": "[{\"id\":\"urn:ngsi-ld:1\",\"location\":{\"type\":\"Point\",\"coordinates\":[8.6,49.5]}}]",
    "outputProperty": "locationGroup",
    "regions": [
      {"name": "Beispielgemeinde, Beispielkreis, Baden-Württemberg, 68542, Deutschland", "group": "Beispielgemeinde",
       "polygon": {"type": "Polygon", "coordinates": [[[8.57, 49.49], [8.63, 49.49], [8.63, 49.52], [8.57, 49.52], [8.57, 49.49]]]}}
    ],
    "x": 460, "y": 120, "wires": [["dbg1"]]},
  {"id": "dbg1", "type": "debug", "z": "tab1", "name": "Output", "active": true, "tosidebar": true, "complete": "payload", "targetType": "msg", "x": 690, "y": 120, "wires": []}
]

Status und Fehler

Der Node zeigt keinen Status an. Hinweise erscheinen als Warnungen im Protokoll und in der Debug-Seitenleiste.

Anzeige	Bedeutung
Warnung „location-group matches points against regions. The configured Geo Type is not supported for Point-in-Polygon.“	Als Geo Type ist eine Geometrie konfiguriert, die kein Punkt ist. Der Eintrag erhält `unknown` beziehungsweise wird gefiltert.
Warnung „Error evaluating polygon for region '…': …“	Ein gespeichertes Polygon konnte nicht ausgewertet werden, zum Beispiel wegen ungültiger Geometrie. Die übrigen Gebiete werden weiter geprüft.
Konsolenwarnung „Location Group Node: Missing @turf/boolean-point-in-polygon dependency.“	Die Abhängigkeit fehlt in der Installation; es gibt dann keine Treffer.
Hinweis im Editor „Search failed. Proxy or API error.“ oder „Search failed. Are you offline or is the proxy down?“	Die Nominatim-Suche über das Node-RED-Backend ist fehlgeschlagen.

Hinweise

Nominatim nur im Editor: Gebietssuche und Kartenklick fragen die öffentliche Instanz nominatim.openstreetmap.org über das Node-RED-Backend an, mit dem User-Agent Node-RED-Location-Group-Node. Ein Kartenklick löst drei Anfragen aus. Beachten Sie die Nutzungsrichtlinie der öffentlichen Instanz (maximal eine Anfrage pro Sekunde) und vermeiden Sie schnelle Klickfolgen.
Externe Ressourcen im Editor: Die Karte lädt Leaflet von unpkg.com und Kacheln von tile.openstreetmap.org. In Netzen ohne Internetzugang bleibt die Kartenvorschau leer; Polygone können dann nicht gesucht werden. Der Betrieb des deployten Nodes ist davon nicht betroffen.
Proxy: Für die Backend-Anfragen an Nominatim ist keine Proxy-Einstellung vorgesehen.
Flow-Größe: Polygone werden vollständig im Flow gespeichert. Gemeinde- oder Kreisgrenzen aus OpenStreetMap umfassen schnell mehrere hundert Kilobyte.
Reihenfolge der Gebiete: Überlappen sich Gebiete, gewinnt das erste in der Liste.
Datenschutz: Standortdaten einzelner Personen oder Fahrzeuge sind personenbezogene Daten. Der Node selbst speichert keine Nachrichten, sendet im Betrieb nichts an Dritte und schreibt nur den Gruppennamen. Prüfen Sie dennoch, ob die Zuordnung zu einem Gebiet im jeweiligen Zweck zulässig ist. Im Editor eingegebene Suchbegriffe und Klickpositionen werden an OpenStreetMap übermittelt.
Einheiten: Koordinaten in Dezimalgrad (WGS 84); GeoJSON-Reihenfolge [Längengrad, Breitengrad].

Location Group

Wofür Sie den Node verwenden

So funktioniert der Node

Gebiete festlegen

Koordinaten lesen

Punkt gegen Polygone prüfen

Anreichern oder filtern

Konfiguration

Registerkarte Regionen

Registerkarte Einstellungen

Registerkarte Daten-Erkennung

Eingang

Ausgang

Beispiel-Flow

Inject und Function

Location Group

Debug

Status und Fehler

Hinweise

Weiterführende Themen

Referenzen

Wofür Sie den Node verwenden​

So funktioniert der Node​

Gebiete festlegen

Koordinaten lesen

Punkt gegen Polygone prüfen

Anreichern oder filtern

Konfiguration​

Registerkarte Regionen​

Registerkarte Einstellungen​

Registerkarte Daten-Erkennung​

Eingang​

Ausgang​

Beispiel-Flow​

Inject und Function

Location Group

Debug

Status und Fehler​

Hinweise​

Weiterführende Themen​

Referenzen​

Wofür Sie den Node verwenden

So funktioniert der Node

Konfiguration

Registerkarte Regionen

Registerkarte Einstellungen

Registerkarte Daten-Erkennung

Eingang

Ausgang

Beispiel-Flow

Status und Fehler

Hinweise

Weiterführende Themen

Referenzen