---
title: "Data-Layer-Referenz"
product: "LumiScan Area Detector"
component: "lumiscan-area-detector-de"
version: "1.2.0"
display_version: "1.2.0.6"
latest_version: true
language: "de"
url: "https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/datalayer-reference.html"
---

# Data-Layer-Referenz – LumiScan Area Detector

Jede Adresse unten ist relativ zu

```
hdvisionsystems/lumiscan-area-detector/
```

## Data Layer {#data-layer}

LumiScan Area Detector bietet seine Funktionen auf dem Data Layer unter `hdvisionsystems/lumiscan-area-detector` an.

Auf ctrlX OS (ctrlX CORE oder ctrlX IPC) nutzt LumiScan Area Detector den [ctrlX Data Layer](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/ctrlx-data-layer.html).

Auf einem PC mit Windows 11 oder Ubuntu 24.04 nutzt LumiScan Area Detector [LumiScan Keryx](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html).

Knotenadressen, Typen und Aufrufmuster sind auf beiden gleich. LumiScan Area Detector bietet:

- [Execute-Methoden](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html)
- ein [Stream](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html)-Abonnement auf eine Quelle (experimentell)

Wie Adressen aufgebaut sind, wie Funktionen aufgerufen werden, die Statuscodes und die Werkzeuge sind in [LumiScan Keryx](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/index.html) beschrieben.

## Anwendungsweite Knoten

| Adresse | Typ | Zugriff | Beschreibung |
| --- | --- | --- | --- |
| `system/modules` | string[] | lesen | Die Module, die gerade existieren |
| `system/create-module/execute` | Methode | schreiben | Ein Modul hinzufügen |
| `system/create-module/input/module-id` | string | lesen/schreiben | Name für das neue Modul |
| `system/remove-module/execute` | Methode | schreiben | Ein Modul entfernen |
| `system/remove-module/input/module-id` | string | lesen/schreiben | Zu entfernendes Modul |
| `system/save-current-modules/execute` | Methode | schreiben | Die Modulliste dauerhaft speichern |
| `system/save-module-inputs/execute` | Methode | schreiben | Die Einstellungen eines Moduls dauerhaft speichern |
| `system/save-module-inputs/input/module-id` | string | lesen/schreiben | Zu speicherndes Modul |
| `system/meta/subscription-schema` | string | lesen | Was der Knoten enthalten muss, den ein Modul abonniert, als JSON Schema (draft-04) seiner JSON-Form: hier ein `stream_image`, der Knoten `frame` des Stream-Ordners, mit `lineage` und `image`. Für jedes Modul gleich. Experimentell |

Jede Methode bedient außerdem `output/status-code` und `output/status-text`.

## Knoten pro Modul

Alle Adressen unten liegen unter `<module-id>/detect-area/`.

### Von jeder Methode verwendet

| Adresse | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `execute` | Methode | - | Eine Erkennung ausführen |
| `input/input-image-address` | string | (leer) | Adresse des zu durchsuchenden Bildknotens |
| `input/method` | string | FIXED | `FIXED` ist die einzige Methode, die diese Version anbietet; alles andere wird abgelehnt |
| `input/crop/startX` | uint16 | 0 | Linker Rand der zu durchsuchenden Region |
| `input/crop/startY` | uint16 | 0 | Oberer Rand |
| `input/crop/width` | uint16 | 0 | Breite; 0 reicht bis zum rechten Rand |
| `input/crop/height` | uint16 | 0 | Höhe; 0 reicht bis zum unteren Rand |
| `input/preprocess/method` | string | NONE | `NONE`, `LOG`, `DOG` oder `DOH` |
| `input/preprocess/log/sigma-x` | float64 | 1.0 | Muss > 0 sein |
| `input/preprocess/log/sigma-y` | float64 | 0.0 | 0 bedeutet gleich sigma-x |
| `input/preprocess/log/kernel-size-x` | uint32 | 0 | 0 berechnet sie aus dem Sigma, sonst ungerade |
| `input/preprocess/log/kernel-size-y` | uint32 | 0 | 0 berechnet sie aus dem Sigma, sonst ungerade |
| `input/preprocess/dog/sigma-first` | float64 | 1.0 | Muss sich von sigma-second unterscheiden |
| `input/preprocess/dog/sigma-second` | float64 | 2.0 | Muss sich von sigma-first unterscheiden |
| `input/preprocess/dog/kernel-size-x` | uint32 | 0 | 0 berechnet sie aus dem Sigma, sonst ungerade |
| `input/preprocess/dog/kernel-size-y` | uint32 | 0 | 0 berechnet sie aus dem Sigma, sonst ungerade |
| `input/preprocess/doh/kernel-size` | uint32 | 3 | Muss 1, 3, 5 oder 7 sein |

### Was als Region zählt

| Adresse | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `input/detect-dark` | boolean | false | Dunkle Regionen auf hellem Hintergrund |
| `input/connectivity` | int32 | 8 | 4 oder 8; 8 verbindet diagonale Nachbarn |
| `input/fill-holes` | boolean | false | Eine Region als die Form messen, die ihr Umriss einschließt |

Ein Flächenfenster gibt es nicht zu konfigurieren. Jede Region, die der Detektor getrennt hat, wird gemeldet, wie klein oder groß sie auch ist; ob eine davon zu klein für ein Teil oder zu groß für ein einzelnes ist, ist eine Entscheidung über die Teile - und die gehört demjenigen, der `output/result` liest.

### Der Schwellwert

| Adresse | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `input/method-specific/fixed/level` | float64 | 128 | Der Schwellwert selbst, 0-255 |

Der Ordner behält seinen Namen, damit die Adresse erhalten bleibt, falls die Methoden zurückkehren, die ihren Schwellwert aus dem Bild bezogen.

### Ausgaben

| Adresse | Typ | Beschreibung |
| --- | --- | --- |
| `output/result` | flatbuffers | Regionen des letzten Durchlaufs |
| `output/status-code` | int16 | Ausgang als Zahl |
| `output/status-text` | string | Ausgang in Worten |
| `output/blob-labels/{data,width,height,pixel-type}` | Bild (`data` ist `raw`) | Mono16, eine Regionsnummer pro Pixel; 0 ist Hintergrund |

Das Label-Bild umfasst den ganzen Frame und enthält die `blobs[].label`-Nummern, sodass sich eine gemeldete Fläche bis zu den Pixeln zurückverfolgen lässt, aus denen sie gemessen wurde. Es wird geleert, wenn der nächste Durchlauf beginnt. Siehe [Das Label-Bild](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/the-label-image.html).

### Eine Szene analysieren

Unter `system/analyse-scene/` - die Analyse beschreibt ein Bild, kein Modul. Siehe [Eine Szene analysieren](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/analysing-a-scene.html).

| Adresse | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `execute` | Methode | - | Das Bild messen und melden, wie hoch ein fester Schwellwert sein müsste |
| `input/input-image-address` | string | (leer) | Der zu analysierende Bildknoten; ihr eigener, nicht der eines Moduls |
| `input/crop/startX` .. `height` | uint16 | 0 | Die zu analysierende Region; lauter Nullen bedeuten das ganze Bild |
| `input/bin-size` | int32 | 0 | Eine verkleinerte Kopie messen; 0 verkleinert nur, was nötig ist, 1 erzwingt volle Größe |
| `input/histogram-bins` | int32 | 256 | Klassen in `output/histogram`, 2-256. Nicht dieselbe Stellschraube wie `bin-size` |
| `output/histogram` | uint32[] | (leer) | Pixel pro Grauwertklasse, dunkelste zuerst, in voller Größe |
| `output/recommended-settings` | string[] | (leer) | `node=value`-Zeilen, relativ zum `detect-area/input/` eines Moduls |
| `output/findings` | string[] | (leer) | Warum, in Worten, mit den Zahlen darin |
| `output/parts-are-dark` | boolean | false | Ob die Regionen dunkler als ihr Hintergrund sind |
| `output/parts-touching` | boolean | false | Ob Regionen in Wirklichkeit mehrere zusammenhängende Teile sind |
| `output/region-count` | int32 | 0 | Gefundene Regionen |
| `output/expected-region-count` | int32 | 0 | Wie viele Teile diese Regionen vermutlich enthalten |
| `output/illumination-spread` | float64 | 0 | [Grauwerte] Schwankung des Hintergrunds über das Bild |
| `output/separability` | float64 | 0 | Wie sauber sich das Bild trennt, 0 bis 1 |
| `output/feature-thickness` | float64 | 0 | [Pixel] Halbe Breite eines typischen Merkmals |
| `output/area-sensitivity` | float64 | 0 | [pro Grauwert] Wie stark sich die Fläche mit dem Schwellwert bewegt. Kleiner ist besser; über `0.05` ist ein fester Schwellwert nicht sicher einzustellen |

## Bild-Stream-Knoten pro Modul (experimentell)

Alle Adressen unten liegen unter `<module-id>/`, neben `detect-area/`. Der Stream durchsucht jeden Frame mit den Eingaben von `detect-area`, allen außer `input/input-image-address`, und veröffentlicht nur die Messwerte: Es gibt kein Stream-Gegenstück zu `output/blob-labels`. Siehe [Flächen auf einem Bild-Stream erkennen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html).

| Adresse | Typ | Standard | Beschreibung |
| --- | --- | --- | --- |
| `control/subscribe/input/enable` | boolean | wie angewendet | Stream-Modus: `true` lässt den Stream laufen, `false` stoppt ihn |
| `control/subscribe/input/address` | string | wie angewendet | Die eine Quelle, der Stream-Ordner einer Kamera, z. B. `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`. Eine andere Adresse ersetzt sie |
| `control/subscribe/input/tag` | string | wie angewendet | Das Tag auf den Ergebnissen des Moduls: Der Schritt des Moduls in der Lineage jedes Stream-Ergebnisses trägt es. Leer: die Modul-ID, z. B. `module-1`. Ein neues Tag behält die Quelle; das nächste Ergebnis trägt es |
| `control/subscribe/input/queue-size` | uint32 | wie angewendet | Frames, die warten dürfen, während einer durchsucht wird, 1-64 |
| `control/subscribe/input/keep-latest-output` | boolean | wie angewendet | `true` schreibt jedes Stream-Ergebnis zusätzlich auf `detect-area/output/result` |
| `control/subscribe/execute` | Methode | - | Prüft die Eingaben von `control/subscribe` gemeinsam, speichert sie in `<module-id>.json` als `stream` und wendet sie dann an. Eine Eingabe allein zu schreiben ändert nichts |
| `control/unsubscribe/execute` | Methode | - | Entfernt die in `control/unsubscribe/input/address` genannte Quelle, was den Stream-Modus beendet; das Tag bleibt. Wird wie ein Subscribe in `<module-id>.json` gespeichert |
| `control/unsubscribe/input/address` | string | (leer) | Die zu entfernende Quelle, so wie `setting/stream/address` sie zeigt |
| `setting/stream/{enable, address, tag, queue-size, keep-latest-output}` | wie die Eingaben | `stream` in `<module-id>.json` | Was `control/subscribe/execute` oder `control/unsubscribe/execute` zuletzt angewendet hat. Schreibgeschützt |
| `setting/settings-hash` | string | - | Hash dessen, womit die Ergebnisse erzeugt werden, 16 Hexadezimalziffern. Schreibgeschützt |
| `control/subscribe/output/stream/active` | boolean | false | `true`, solange der Stream läuft |
| `control/subscribe/output/stream/result` | flatbuffers | leer | Ein `stream_areas` pro durchsuchtem Frame. Abonnieren, um jedes zu erhalten |
| `control/subscribe/output/stream/last-failure` | string | (leer) | Warum der letzte Frame, der nicht durchsucht werden konnte, fehlgeschlagen ist; nennt die Quelle über ihre Adresse |
| `control/subscribe/output/stream/statistics/elapsed-ms` | uint64 | 0 | Millisekunden seit dem Start des Streams |
| `control/subscribe/output/stream/statistics/received-frames` | uint64 | 0 | Frames, die das Abonnement geliefert hat |
| `control/subscribe/output/stream/statistics/processed-frames` | uint64 | 0 | Durchsuchte Frames, jeder mit einem Ergebnis |
| `control/subscribe/output/stream/statistics/skipped-frames` | uint64 | 0 | Frames, die aus der Warteschlange verdrängt wurden oder warteten, als die Quelle ersetzt oder entfernt wurde |
| `control/subscribe/output/stream/statistics/failed-frames` | uint64 | 0 | Frames, die nicht durchsucht werden konnten |
| `control/subscribe/output/stream/statistics/lost-frames` | uint64 | 0 | Frames, die verloren gingen, bevor sie ankamen |
| `control/subscribe/output/stream/statistics/processing-us` | uint64 | 0 | Erkennungszeit aller durchsuchten Frames, summiert, Mikrosekunden |

Die Eingaben von `control/subscribe` beginnen mit dem, was angewendet ist, und nur `control/subscribe/execute` wendet sie an. `control/subscribe/execute` wird für den Stream-Modus ohne Adresse oder mit einer Warteschlangengröße außerhalb von 1-64 abgelehnt, `control/unsubscribe/execute` für eine Adresse, die nicht die Quelle ist. Kann `<module-id>.json` nicht geschrieben werden, antworten beide mit `DL_CREATION_FAILED` (auf einem PC `CreationFailed`) und ändern nichts.

## Der Ergebnis-Flatbuffer

`output/result` enthält `hdv.area_detect.Result`:

| Feld | Typ | Bedeutung |
| --- | --- | --- |
| `blobs` | Blob[] | Alle Regionen, nach Fläche absteigend sortiert |
| `blobs[].x`, `.y` | float | [Pixel] Mittelpunkt der Region |
| `blobs[].area` | float | [Pixel^2] Pixel, die die Region bedeckt, gezählt |
| `blobs[].label` | uint | Welche Region dies in `output/blob-labels` ist; 0 kommt nie vor |
| `blobs[].bbox_x/y/width/height` | int | Eng anliegendes Rechteck um die Region |
| `blob_count` | uint | Anzahl der Regionen |
| `total_area` | float | [Pixel^2] Summe über alle Regionen |
| `largest_index` | ulong | Index der größten Region |
| `largest_area` | float | [Pixel^2] Ihre Fläche |
| `image_width`, `image_height` | uint | Der Frame, in dem die Koordinaten liegen |
| `preprocess_method` | string | NONE, LOG, DOG oder DOH, wie angewendet |
| `timestamp` | ulong | Mikrosekunden seit der Epoche |

`control/subscribe/output/stream/result` enthält `hdv.stream.StreamAreas` (`stream_areas`, registriert als `types/hdvisionsystems/lumiscan-area-detector/stream_areas`): `lineage`, woher der Frame kam, und `result`, das obige `hdv.area_detect.Result`. Zu seinem `blobs[].label` gibt es kein Label-Bild zum Nachschlagen.

## Konfigurationsdatei {#configuration-file}

Die Anwendungs-Einstellungsdatei ist `lumiscan-area-detector.json` im Konfigurationsverzeichnis der Anwendung:

| Plattform | Datei |
| --- | --- |
| ctrlX OS | `<active solution>/lumiscan-area-detector/lumiscan-area-detector.json`, wobei die aktive Solution `/var/snap/rexroth-solutions/common/solutions/activeConfiguration` ist |
| PC (Windows) | `%APP_RESOURCE_DIR%\etc\lumiscan-area-detector\lumiscan-area-detector.json`; ohne `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-areadetect\etc\lumiscan-area-detector\lumiscan-area-detector.json` |

```json
{
    "system": { "logLevel": "INFO" },
    "modules": [ { "id": "module-1", "advanced": false } ]
}
```

`logLevel` akzeptiert `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` und `OFF`, gelesen beim Start. Die gespeicherten Einstellungen jedes Moduls liegen daneben in `<module-id>.json`, und ebenso Modus, Quelle, Warteschlangengröße und keep-latest-output seines Bild-Streams, unter `stream`.

## Mit einem Beispiel beginnen (PC) {#generate-settings}

Auf einem PC schreibt der Area Detector ein Beispiel seiner Einstellungen in einen Ordner Ihrer Wahl und beendet sich, ohne zu starten. Unter Windows:

```shell
lumiscan-areadetect --generate-settings C:\work\area-detector-settings
```

Ohne Ordner (`-g` allein) schreibt er in den aktuellen Ordner. Das Beispiel besteht aus der Anwendungs-Einstellungsdatei `lumiscan-area-detector.json`, die das Modul `module-1` nennt, und der Moduldatei `module-1.json` daneben: jede Eingabe von `detect-area` mit ihrem Standardwert, außer der Bildadresse, die `camera1` des Cam Driver ist. Daneben, in `schemas/`, liegen die Schemas, die die beiden Dateien in `"$schema"` nennen: `lumiscan-area-detector.schema.json`, `lumiscan-area-detector-module.schema.json` und `stream.schema.json` für den Abschnitt `stream` einer Moduldatei. Sie beschreiben jeden Schlüssel, den der Area Detector liest - jede Eingabe von `detect-area` mit ihrem Typ, ihrem Standardwert und dem Bereich, den ein Durchlauf akzeptiert -, sodass ein Editor, der JSON Schema versteht, die Dateien prüfen und anzeigen kann, was jeder Wert bedeutet. Kopieren Sie den Ordner `schemas` zusammen mit den Dateien: `system/save-module-inputs` behält das `"$schema"` einer Moduldatei, die es speichert. Vorhandene Dateien werden nie überschrieben: Liegt eine davon bereits im Ordner, wird nichts geschrieben, und der Area Detector sagt, welche.

Der Area Detector nennt dann den Ordner, aus dem er seine Einstellungen liest, unter Windows standardmäßig `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-areadetect\etc\lumiscan-area-detector`. Bearbeiten Sie das Beispiel, kopieren Sie es dorthin, und starten Sie den Area Detector. Siehe auch [Wo die Dateien liegen](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html#files).