# LumiScan Area Detector 1.2.0.6 – complete documentation

> All pages of the LumiScan Area Detector 1.2.0.6 manual (language: de) by HD Vision Systems GmbH, in navigation order. Each page starts with a level-1 heading followed by its URL; cite that URL. Manual: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/

# Beschreibung – LumiScan Area Detector

URL: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/description.html

LumiScan Area Detector findet Regionen in einem Kamerabild und meldet, wie groß jede davon ist.

Die Anwendung läuft auf ctrlX OS (ctrlX CORE oder ctrlX IPC) mit dem ctrlX Data Layer und auf einem PC (Windows 11 oder Ubuntu 24.04) mit LumiScan Keryx, dem Data Layer von HD Vision Systems für PCs. Ihre Knoten sind auf beiden gleich, siehe [Data-Layer-Referenz](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/datalayer-reference.html).

Was für alle LumiScan-Apps gleich ist - wie Adressen aufgebaut sind, die Aufrufmuster Handshake, Execute und Stream, Statuscodes, Einstellungen und Werkzeuge -, ist im Handbuch [LumiScan Keryx](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/index.html) beschrieben. Dieses Handbuch behandelt nur das, was für LumiScan Area Detector spezifisch ist; seine eigenen Knoten sind in der [Data-Layer-Referenz](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/datalayer-reference.html) aufgeführt.

Anders als die anderen LumiScan-Matching-Anwendungen benötigt sie **kein Referenzbild**. Sie beschreiben, was als Region zählt - wie hell, wie groß, wie rund -, und die Anwendung meldet jede Region, die dieser Beschreibung entspricht, mit ihrer Fläche und Position.

Das eignet sich zum Zählen von Teilen, zum Prüfen von Bedeckung oder Verunreinigung, zum Messen eines Füllstands und für jede Prüfung, bei der das Gemessene kein festes Aussehen hat: ein Fleck, ein Kratzer, eine Lücke.

> [!NOTE]
> Wenn Sie ein **bestimmtes bekanntes Teil** suchen, passen die Schwester-Apps besser: LumiScan Template Finder findet ein gespeichertes Bild in einem Bereich von Skalierungen und Drehungen, und LumiScan Object Finder findet die Form eines Objekts. Area Detector beantwortet die Frage "Was ist hier, und wie groß ist es?", nicht "Wo ist dieses Ding?".

## Wie eine Region gefunden wird

Jede Methode misst - die gemeldete Fläche ist immer eine Pixelzahl. Was `input/method` wählt, ist, wie eine Region überhaupt gefunden wird:

`input/method` ist `FIXED`: Das Bild wird einmal mit einem von Ihnen eingestellten Schwellwert binarisiert, und jede zusammenhängende Region wird durch Zählen ihrer Pixel gemessen, unabhängig von ihrer Form. Es ist die einzige Methode, die diese Version anbietet; alles andere, was auf diesen Knoten geschrieben wird, wird abgelehnt und nicht ignoriert.

Eine Region zählt als die Pixel, die den Schwellwert passiert haben; ein Loch in einem Teil wird also **nicht** mitgezählt, sofern `fill-holes` nicht gesetzt ist - das ist eine Entscheidung darüber, was die Fläche einer Unterlegscheibe bedeutet, keine Korrektur.

Um den Schwellwert zu finden, führen Sie [Eine Szene analysieren](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/analysing-a-scene.html) aus: Die Analyse misst das Bild, schlägt einen Schwellwert vor und veröffentlicht das Grauwert-Histogramm, in dessen Tal der Schwellwert liegen sollte.

## Woher die Bilder kommen

Die Anwendung kommuniziert nicht selbst mit einer Kamera. Sie liest einen Bildknoten, den eine andere Anwendung auf dem Data Layer veröffentlicht, angegeben als Adresse, zum Beispiel:

```
hdvisionsystems/lumiscan-cam-driver/camera1/output/image
```

Der Knoten muss `data`, `width`, `height` und `pixel-type` veröffentlichen - genau das, was LumiScan Cam Driver bereitstellt.

## Module

Ein **Modul** ist eine konfigurierte Instanz der Erkennung: mit eigener Kameraadresse, eigenen Einstellungen und eigenen Ergebnissen unter einer eigenen Data-Layer-Adresse. Eine Installation kann mehrere Module betreiben, um mehrere Kameras gleichzeitig zu überwachen. Auf ctrlX OS deckt eine Lizenz zehn davon ab. Siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/module-management.html).

Module teilen sich nichts: Es gibt kein gespeichertes Referenzbild, also auch nichts, was anwendungsweit zu konfigurieren wäre.

# Voraussetzungen – LumiScan Area Detector

URL: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/requirements.html

## Lizenz {#licence}

Wie LumiScan Area Detector lizenziert wird, hängt davon ab, wo Sie es gekauft haben und wo es läuft:

| Gekauft bei | Läuft auf | Lizenzierung |
| --- | --- | --- |
| HD Vision Systems | Windows 11 oder Ubuntu 24.04 | Die Lizenz liegt auf Ihrem LumiScan Key. Sie ist ein Einmalkauf und wird nicht verlängert.<br><br>[Lizenzierungsweg: gekauft bei HD Vision Systems](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/path-hdvs.html) |
| ctrlX Store | Windows 11 | Die Lizenz liegt in ctrlX WORKS. Zusätzlich ist der LumiScan Key erforderlich; er schützt die Software vor Reverse Engineering.<br><br>[Lizenzierungsweg: ctrlX Store, Windows](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/path-ctrlx-windows.html) |
| ctrlX Store | ctrlX OS (ctrlX CORE oder IPC) | ctrlX-Lizenz `SWL-W-XCx-AxxDETECTxHDVSx-V1NN`, eine Lizenz pro zehn Module.<br><br>[Lizenzierungsweg: ctrlX Store, ctrlX OS](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/path-ctrlx-os.html) |

Jedes Gerät, auf dem LumiScan Area Detector gleichzeitig läuft, benötigt einen eigenen LumiScan Key. Keys können zwischen Geräten ausgetauscht werden.

Wie Sie die CodeMeter Runtime installieren und Lizenzen anfordern, verlängern und an einem anderen PC verwenden, steht in [LumiScan Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/index.html).

Auf ctrlX OS beendet sich die Anwendung kurz nach dem Start, wenn die Lizenz fehlt; der Grund wird in das Systemprotokoll geschrieben.

## Eine Plattform und ihr Data Layer

| Plattform | Data Layer |
| --- | --- |
| ctrlX OS (ctrlX CORE oder ctrlX IPC) | ctrlX Data Layer, bereitgestellt von ctrlX OS |
| ein PC mit Windows 11 oder Ubuntu 24.04 | LumiScan Keryx, der Data Layer von HD Vision Systems für PCs |

Auf ctrlX OS ist für den Data Layer nichts zu installieren.

Auf einem PC startet die Anwendung den LumiScan-Keryx-Broker, wenn keiner läuft; Installation und Einrichtung von LumiScan Keryx sind in [LumiScan Keryx auf einem PC](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html) beschrieben.

## Eine Bildquelle auf demselben Gerät

Die Anwendung liest ihre Bilder vom Data-Layer-Bildknoten einer anderen Anwendung. Diese Anwendung muss auf **demselben Gerät** laufen wie der Area Detector - demselben ctrlX CORE oder ctrlX IPC oder demselben PC. Ein Zugriff auf einen entfernten Data Layer wird nicht unterstützt.

In der Praxis ist das LumiScan Cam Driver, aber jede Anwendung funktioniert, solange ihr Bildknoten diese vier Kindknoten bereitstellt:

| Knoten | Typ | Beschreibung |
| --- | --- | --- |
| `data` | Array aus uint8 | Rohe, unkomprimierte Pixeldaten |
| `width` | uint64 | Bildbreite in Pixeln |
| `height` | uint64 | Bildhöhe in Pixeln |
| `pixel-type` | string | Name des GenICam-Pixelformats |

### Unterstützte Pixelformate

`Mono8`, `Mono12`, `RGB8`, `RGB12`, `BGR8`, `BGR12`, `BayerGR8`, `BayerGR12`, `BayerRG8`, `BayerRG12`.

Bayer-Bilder werden vor der Erkennung in Farbe umgewandelt und 12-Bit-Bilder auf 8 Bit herunterskaliert; ein Schwellwert, der auf einem Format eingestellt wurde, gilt also auch für ein anderes.

Jedes andere Pixelformat wird mit Statuscode `-3` abgelehnt.

## Speicher

Die Anwendung speichert nichts außer ihrer Modulliste und deren Einstellungen - einige Kilobyte JSON im Konfigurationsverzeichnis der Anwendung. Auf ctrlX OS ist dieses Verzeichnis Teil der aktiven Solution. Wo es auf jeder Plattform liegt, steht unter [Konfigurationsdatei](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/datalayer-reference.html#configuration-file). Es gibt kein Referenzbild, das aufbewahrt werden müsste, also ist auch kein Speicherplatz einzuplanen.

Der Bild-Stream (experimentell) legt daneben einen Ordner an, `settings-history/`: eine kleine JSON-Datei für jeden Einstellungs-Hash, den ein Modul veröffentlicht, nie gelöscht. Siehe [Einen Bild-Stream verarbeiten](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html).

## Zeitverhalten

Die Erkennung ist **synchron**: Der Aufruf von `execute` kehrt zurück, wenn die Suche abgeschlossen ist. Wie lange das dauert, hängt von der Bildgröße und vom Modus ab. Das Messen (`input/method`) besteht aus einem Schwellwert und einem Durchlauf der Zusammenhangskomponenten-Analyse und skaliert daher mit dem Bild. Das Schätzen wiederholt die Erkennung einmal pro Schwellwertstufe und skaliert daher mit dem Bild **und** mit der Anzahl der Stufen, die `method-specific/circle/threshold/step` erzeugt - deshalb ist `method-specific/circle/threshold/step` die Einstellung, die Sie zuerst vergrößern sollten, wenn ein Zyklus zu langsam ist.

Siehe [Die Erkennung abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/tuning-the-detection.html).

# Eine Methode ausführen – LumiScan Area Detector

URL: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/execute-a-method.html

Jede Operation dieser Anwendung - Erkennung, Szenenanalyse und Modulverwaltung - wird auf dieselbe Weise gestartet und meldet ihren Ausgang auf dieselbe Weise. Es sind Execute-Methoden des Data Layer; wie Execute-Methoden allgemein funktionieren, ist in [Execute-Methoden](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html) beschrieben.

## Der Aufbau einer Operation

Eine Operation liegt unter einer eigenen Adresse und hat immer drei Teile:

```
<operation>/execute                 write here to run it
<operation>/input/...               the values it works on
<operation>/output/status-code      what happened, as a number
<operation>/output/status-text      what happened, in words
```

Manche Operationen haben unter `output/` mehr - ein Erkennungsergebnis, ein Label-Bild oder ein Histogramm -, aber `execute`, `status-code` und `status-text` sind immer vorhanden.

## Eine Operation ausführen

1. Schreiben Sie die Eingabeknoten.
2. Schreiben Sie auf `execute`. Der Wert spielt keine Rolle; der Schreibvorgang selbst löst die Operation aus.
3. Lesen Sie `output/status-code`, um zu erfahren, ob sie erfolgreich war.

Das Schreiben auf `execute` ist ein **blockierender Aufruf**: Er kehrt zurück, wenn die Operation abgeschlossen ist. Sie müssen also weder ein "ready"-Flag pollen noch in Ihrem Programm einen Zustand verfolgen. Eingaben behalten ihre Werte zwischen den Durchläufen, eine wiederholte Operation braucht also nur Schritt 2.

## Den Ausgang prüfen

`output/status-code` ist eine vorzeichenbehaftete Zahl, und **allein das Vorzeichen sagt Ihnen, ob die Operation erfolgreich war**:

| Wert | Bedeutung |
| --- | --- |
| größer als 0 | Die Operation war erfolgreich |
| 0 | Die Operation ist seit dem Start der Anwendung nicht ausgeführt worden |
| kleiner als 0 | Die Operation ist fehlgeschlagen und hat nichts erzeugt |

Die Prüfung in einer SPS ist also einfach `status-code < 0`. Einen bestimmten Code brauchen Sie nur, wenn Sie auf verschiedene Fehler unterschiedlich reagieren wollen - etwa auf eine ungültige Eingabe anders als auf eine Kamera, die nicht antwortet.

`output/status-text` enthält denselben Ausgang als Satz und benennt den fehlerhaften Wert, wenn es einen gibt:

```
error: crop/startX + crop/width (100 + 900 = 1000) exceeds the image width 640
```

Lesen Sie ihn, wenn etwas schiefgeht; bauen Sie keine Logik darauf auf, denn der Wortlaut kann sich zwischen Releases ändern. Die vollständige Liste der Codes steht unter [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/execution-status.html).

> [!NOTE]
> Der Grund kommt auf `output/status-text` an, nicht in der Antwort auf den Schreibvorgang auf `execute` selbst. Ein fehlgeschlagener Schreibvorgang antwortet nur mit einem Statuscode - über REST mit einem bloßen `400`. Der Data Layer verwirft jedes Detail, das ein Provider an einen fehlgeschlagenen Aufruf anhängt; `output/status-text` anschließend zu lesen ist daher der Weg, um herauszufinden, was falsch war. Die Ergebnisse, mit denen ein Schreibvorgang antworten kann, und ihre Namen auf dem ctrlX Data Layer und auf LumiScan Keryx sind in [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results) aufgeführt.
>
> Derselbe Text wird in das Protokoll der Anwendung geschrieben, sodass sich ein Fehler auch ganz ohne den Data Layer diagnostizieren lässt: auf ctrlX OS über das ctrlX Logbook oder `journalctl`, auf einem PC über die Konsolenausgabe der Anwendung. Sind mehrere Eingaben falsch, erhält jede ihre eigene Warnzeile.

## Eine Operation zur Zeit

Ein Modul führt jeweils eine Operation aus. Eine zweite zu starten, während die erste noch läuft, stellt sie nicht in eine Warteschlange - sie kehrt sofort mit Statuscode `-1` (belegt) zurück und tut nichts. Der Schreibvorgang selbst antwortet mit `TooManyOperations` (ctrlX: `DL_TOO_MANY_OPERATIONS`), siehe [Eine Operation zur Zeit](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html#busy).

Die Sperre gilt pro Modul, verschiedene Module erkennen also parallel - eine zweite Kamera wird von der ersten nicht aufgehalten. `system/analyse-scene` hat eine eigene Sperre; eine Szenenanalyse blockiert daher keine Erkennung, und zwei Analysen können nicht miteinander in Konflikt geraten.

## Die Ausgaben gehören zum startenden Durchlauf

Jede Methode leert ihre eigenen Ausgabeknoten, sobald sie beginnt - `detect-area` sein `output/result`, `analyse-scene` sein `output/histogram`. Sie werden geleert, **bevor** irgendetwas fehlschlagen kann; ein Durchlauf, der aus welchem Grund auch immer fehlschlägt, hinterlässt sie also leer, statt das Ergebnis eines früheren Durchlaufs zu behalten.

Deshalb ist es sicher, eine Ausgabe zu lesen, ohne vorher `output/status-code` zu prüfen: Was Sie sehen, ist entweder das Ergebnis dieses Durchlaufs oder nichts, nie ein veralteter Wert von einem früheren Bild.

`output/status-code` und `output/status-text` sind die Ausnahme - sie beschreiben immer den letzten Versuch, und genau dafür sind sie da.

> [!WARNING]
> **Lesen Sie eine Ausgabe, bevor Sie den nächsten Durchlauf auslösen.** Die Ausgaben beschreiben den jüngsten Durchlauf, und der nächste Aufruf leert sie in dem Moment, in dem er beginnt. Erneut `execute` aufzurufen und dann das vorherige Ergebnis zu lesen liefert nichts.
>
> Der einzige Fall, der **nichts** leert, ist ein als `-1` (belegt) abgelehnter Aufruf: Er ist nie gelaufen und lässt die Ausgaben der laufenden Operation unberührt. Ein zweites `execute`, das unmittelbar nach dem ersten abgesetzt wird, hat also zwei mögliche Ausgänge, und sie unterscheiden sich:
>
> - Der erste Durchlauf **läuft noch** - der zweite wird mit `-1` abgelehnt, und die Ausgaben enthalten weiterhin den Durchlauf davor;
> - der erste Durchlauf ist **gerade fertig** - der zweite wird angenommen und leert die Ausgaben, die der erste Durchlauf gerade erst geschrieben hat.
>
> Warten Sie, bis `execute` zurückkehrt, lesen Sie die Ausgaben, und lösen Sie erst dann den nächsten Durchlauf aus.

# Ausführungsstatus – LumiScan Area Detector

URL: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/execution-status.html

Jede Operation meldet ihren Ausgang auf zwei Knoten neben ihr: `output/status-code` für Ihr Programm und `output/status-text` für einen Menschen. Diese Codes sind der Ausführungsstatus der Finder, nicht der Modulstatus von Cam Driver, AI Object Matching oder Calibration; siehe [Ausführungsstatus der Finder](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#execution-status).

## Statuscodes

| Code | Bedeutung | Wann er auftritt |
| --- | --- | --- |
| `0` | Idle | Die Operation ist seit dem Start der Anwendung nicht ausgeführt worden |
| `1` | OK | Die Operation wurde abgeschlossen. Eine Suche kann dennoch nichts gefunden haben - das ist ein normales Ergebnis, kein Fehler |
| `-1` | Belegt | Eine andere Operation desselben Moduls lief noch. Es wurde nichts getan; versuchen Sie es erneut, wenn sie abgeschlossen ist |
| `-2` | Ungültige Eingabe | Ein Eingabewert kann nicht verwendet werden - ein leer gelassener Pflichtknoten, ein unbekanntes `input/method` oder `input/preprocess/method`, ein Parameter außerhalb seines Bereichs oder eine Bildadresse, die auf diese Anwendung selbst zeigt |
| `-3` | Bild konnte nicht gelesen werden | Der Bildknoten unter der angegebenen Adresse fehlt, ist leer oder inkonsistent oder verwendet ein nicht unterstütztes Pixelformat. Prüfen Sie, ob die Kameraanwendung läuft und ein Bild aufgenommen hat |
| `-4` | Quelle nicht gefunden | Eine benötigte Datei oder ein benötigtes Verzeichnis fehlt oder ist nicht lesbar |
| `-5` | Ungültige Ausschnittsregion | Die Region of Interest passt nicht in das Bild. Die Meldung nennt die tatsächliche Bildgröße |
| `-6` | Schreiben fehlgeschlagen | Eine Datei konnte nicht geschrieben werden - meist ein Berechtigungsproblem oder ein voller Datenträger |
| `-7` | Algorithmus fehlgeschlagen | Die Erkennung selbst ist fehlgeschlagen |
| `-8` | Veröffentlichen fehlgeschlagen | Das Ergebnis konnte nicht auf den Data Layer zurückgeschrieben werden |
| `-9` | Modul nicht gefunden | Das genannte Modul existiert nicht. Prüfen Sie `system/modules` für die aktuelle Liste |
| `-10` | Modul existiert bereits | Ein Modul mit diesem Namen ist bereits vorhanden |
| `-11` | Lizenz nicht verfügbar | Keine Lizenz deckt das Modul ab. Siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/module-management.html) |

> [!NOTE]
> Diese Zahlen sind Teil der Schnittstelle der Anwendung. In späteren Releases können neue Codes hinzukommen, aber bestehende ändern nie ihre Bedeutung; Logik, die auf ihnen aufbaut, funktioniert also nach einem Update weiter.
>
> Auch deshalb ist die Prüfung des **Vorzeichens** der robustere Test: `status-code < 0` bleibt korrekt, auch wenn ein Release einen Fehler einführt, den Ihr Programm noch nie gesehen hat.

## Welche Operation welche Codes meldet

| Operation | Mögliche Codes |
| --- | --- |
| `detect-area` | `1`, `-1`, `-2`, `-3`, `-7`, `-8` |
| `system/analyse-scene` | `1`, `-1`, `-2`, `-3`, `-7` |
| `system/save-module-inputs` | `1`, `-6`, `-9` |

## Statustext

`output/status-text` beginnt immer mit `ok:` oder `error:` und nennt den Grund in Worten. Er wird gleichzeitig mit dem Statuscode geschrieben, beide stimmen also immer überein.

Jede Operation hat ihr eigenes Knotenpaar, und die Werte bleiben erhalten, bis diese Operation erneut ausgeführt wird. Eine fehlgeschlagene Szenenanalyse stört daher nicht das Ergebnis der letzten Erkennung.

# Flächen erkennen – LumiScan Area Detector

URL: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/detecting-areas.html

`<module>/detect-area` durchsucht ein Bild, einmal, und meldet die Regionen, die es findet.

## Ausführen

Setzen Sie die Bildadresse und führen Sie aus:

```
module-1/detect-area/input/input-image-address = hdvisionsystems/lumiscan-cam-driver/camera1/output/image
write module-1/detect-area/execute
```

Lesen Sie dann `output/status-code` und `output/result`.

Alles andere hat einen funktionierenden Standardwert, dieser erste Durchlauf zeigt Ihnen also, ob überhaupt etwas gefunden wird. Das Abstimmen folgt: siehe [Die Erkennung abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/tuning-the-detection.html) und [Eine Szene analysieren](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/analysing-a-scene.html) zum Einstellen des Schwellwerts.

## Das Ergebnis

`output/result` ist ein `area_detect_result`-Flatbuffer.

| Feld | Bedeutung |
| --- | --- |
| `blobs[].x`, `.y` | Mittelpunkt der Region. |
| `blobs[].area` | [Pixel^2] Pixel, die die Region bedeckt, gezählt - nie aus einer angepassten Form abgeleitet. |
| `blobs[].label` | Welche Region dies in `output/blob-labels` ist - so wird eine gemeldete Fläche ihren Pixeln zugeordnet. |
| `blobs[].bbox_x/y/width/height` | Eng anliegendes Rechteck um die Region. |
| `blob_count` | Wie viele Regionen, für ein Steuerungsprogramm, das nur eine Anzahl braucht. |
| `total_area` | [Pixel^2] Summe über alle Regionen - die zentrale Zahl für eine Bedeckungsprüfung. |
| `largest_index`, `largest_area` | Die größte Region. |
| `image_width`, `image_height` | Der durchsuchte Bereich - das ganze Bild, sofern kein Crop gesetzt war. |
| `preprocess_method` | `NONE`, `LOG`, `DOG` oder `DOH`, wie angewendet. |
| `timestamp` | Mikrosekunden seit der Epoche, wann der Durchlauf abgeschlossen wurde. |

Die Regionen sind nach Fläche sortiert, `blobs[0]` ist also die größte.

`total_area` ist meist die Zahl, auf die Sie reagieren: Bedeckungs-, Verunreinigungs- und Füllstandsprüfungen fragen alle "wie viel", nicht "wie viele".

## Farbbilder

Es kann ein Grau- oder ein Farbbild hineingehen. Schwellwertbildung und Zusammenhangskomponenten sind Einkanal-Operationen, ein Farbbild wird also umgewandelt und wie jedes andere gemessen. Auf ctrlX OS liefert ein ctrlX-Bildknoten drei Farbkanäle, egal welche Kamera angeschlossen ist; eine Graustufenkamera erzeugt also drei identische Kopien. Es gibt kein Flag, und eine Region wird einmal gemeldet, wie viele Kanäle auch immer ankamen.

## Die Suche einschränken

`input/crop/{startX, startY, width, height}` beschränkt die Suche auf einen Teil des Bildes. Eine Breite oder Höhe von null reicht bis zum entsprechenden Rand; die Standardregion mit lauter Nullen durchsucht also alles, und `startX=100` mit Nullgrößen sucht von dort bis zur unteren rechten Ecke.

Zwei Gründe, sie zu verwenden: Geschwindigkeit, und das Ausschließen von Bereichen, in denen keine Region sein kann, was das Zählen von Hintergrundstörungen vermeidet.

Eine Region, die über einen Rand hinausreicht, wird abgelehnt und nicht beschnitten; die Meldung nennt die Eingabe und die Grenze, die sie verletzt hat.

## Vorverarbeitung

`input/preprocess/method` wendet vor der Erkennung einen Filter an:

| Methode | Was sie tut |
| --- | --- |
| `NONE` | Der Standard. |
| `LOG` | Laplacian of Gaussian - Weichzeichnen, dann eine zweite Ableitung; hebt Regionen einer durch das Sigma festgelegten Größe hervor. |
| `DOG` | Difference of Gaussians - zwei Weichzeichnungen voneinander abgezogen, ein Bandpass. `sigma-first` muss sich von `sigma-second` unterscheiden. |
| `DOH` | Determinant of Hessian - kombinierte zweite Ableitungen. `kernel-size` muss 1, 3, 5 oder 7 sein. |

Nur die Parameter der gewählten Methode werden gelesen, und nur sie werden geprüft.

## Die Regionen selbst

Das Ergebnis enthält Zahlen, keine Pixel. Die Pixel stehen in `output/blob-labels`, das jeder Durchlauf veröffentlicht: eine Regionsnummer pro Pixel, und `blobs[].label` sagt, welche Nummer welche Region ist. Siehe [Das Label-Bild](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/the-label-image.html).

## Ein leeres Ergebnis

Eine leere `blobs`-Liste mit `status-code` 1 bedeutet, dass **keine Regionen zutrafen** - sonst nichts. Jeder andere Grund, aus dem ein Durchlauf nichts erzeugen könnte, wird vor der Erkennung abgefangen und als negativer Statuscode gemeldet. Siehe [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/execution-status.html).

# Das Label-Bild – LumiScan Area Detector

URL: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/the-label-image.html

Jeder Durchlauf veröffentlicht `output/blob-labels`, und sonst nichts. Es ist ein gewöhnlicher Bildknoten - `data`, `width`, `height`, `pixel-type` - mit einer Zahl pro Pixel: die Region, zu der das Pixel gehört, oder `0` für Hintergrund.

## Warum eine Ausgabe und keine Wahl

Der Detektor findet Regionen über Zusammenhangskomponenten, ein Label-Bild **ist** also das Ergebnis. Konturen, Polygone und Masken pro Region waren alles Arten, dieselbe Sache weniger direkt zu beschreiben, und `input/publish` war ein Menü, um zwischen diesen Beschreibungen zu wählen. Eine einzige Ausgabe kann sich nicht selbst widersprechen.

## Lesen

`pixel-type` ist **Mono16**, nicht Mono8 - ein Bild kann mehr als 255 Regionen enthalten, und ein Label ist eine Nummer, keine Helligkeit; ein Überlauf bei 255 würde also stillschweigend zwei Regionen zu einer verschmelzen.

Die Zahlen sind die `blobs[].label`-Werte in `output/result`. Das macht das Bild nützlich statt bloß dekorativ: Von einer gemeldeten Fläche kommen Sie zu genau den Pixeln, aus denen sie gemessen wurde.

```none
blobs[2].label == 7   ->   every pixel of blob-labels holding 7 is that region
```

Eine Binärmaske, falls Sie nur die brauchen, ist `labels > 0`.

## Was enthalten ist und was nicht

Das Bild umfasst den **ganzen Frame**, in der Größe des Eingabebildes - nicht des Crops. Schneiden Sie es mit `crop_x/crop_y/crop_width/crop_height` aus `output/result` zu, wenn Sie nur die durchsuchte Region wollen.

Jede Region, die `output/result` meldet, ist hier markiert, und keine andere. Bild und Zahlen beschreiben immer dieselben Regionen; eine Region, die Sie sehen können, ist also eine, die Sie nachschlagen können.

Labels werden **nicht** neu nummeriert. `blobs[].label` muss weiterhin dieselben Pixel adressieren; die Nummern sind daher die des Detektors und keine Position in der gemeldeten Liste - die nach Fläche sortiert ist und deshalb nicht in Label-Reihenfolge läuft.

## Im Cockpit

Das Cockpit färbt jede Region in einer anderen Farbe über dem Kamerabild ein. Deshalb gibt es das Label-Bild und keine einfache Maske: Benachbarte Regionen erscheinen in **verschiedenen Farben**, sodass sich eine gemeldete Fläche bis zu genau den Pixeln zurückverfolgen lässt, aus denen sie gemessen wurde. Ein umschließendes Rechteck könnte das nie zeigen - zwei überlappende Rechtecke sagen nichts darüber, welche Pixel zu welcher Region gehören.

# Flächen auf einem Bild-Stream erkennen (experimentell) – LumiScan Area Detector

URL: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html

> [!IMPORTANT]
> Der Bild-Stream ist **experimentell**. Seine Knoten und Einstellungen können sich noch ändern. Verwenden Sie ihn zur Evaluierung, und prüfen Sie ihn mit Ihren Kameras und Ihrem Data Layer, bevor Sie sich darauf verlassen.

`detect-area` durchsucht ein Bild pro Aufruf: Ihr Programm setzt `input/input-image-address` und schreibt auf `execute`. Ein Bild-Stream funktioniert umgekehrt. Der Cam Driver veröffentlicht jedes Bild, das er aufnimmt, auf `<camera name>/control/publish/output/stream/frame`, mit seiner Größe, seinem Pixelformat und seiner Lineage (siehe das Handbuch des Cam Driver, *Bilder streamen*). Ein Modul abonniert den Stream einer Kamera, erkennt die Regionen in jedem Frame, sobald er eintrifft, und veröffentlicht ein Ergebnis pro Frame auf `control/subscribe/output/stream/result`. Der Stream funktioniert auf dem ctrlX Data Layer und auf LumiScan Keryx gleich; das Konzept, das alle LumiScan-Apps teilen, ist in [Streams](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html) beschrieben. Diese Seite beschreibt, was beim Area Detector besonders ist.

Jeder Frame wird mit den Eingaben von `detect-area` durchsucht, wie sie in diesem Moment sind: der Schwellwert, die Vorverarbeitung, die Ausschnittsregion und jeder andere Knoten unter `detect-area/input/`. Die eine Eingabe, die der Stream nicht verwendet, ist `input/input-image-address`: Der Frame tritt an ihre Stelle. Ändern Sie eine Eingabe, während der Stream läuft, wird der nächste Frame mit dem neuen Wert durchsucht.

> [!IMPORTANT]
> Der Stream veröffentlicht nur die Messwerte. Das Label-Bild, das `detect-area` auf `output/blob-labels` veröffentlicht, hat kein Stream-Gegenstück. `blobs[].label` wird weiterhin gefüllt, aber es gibt kein Bild, in dem es sich nachschlagen ließe.

Jedes Ergebnis trägt die Lineage seines Frames - welche Kamera ihn aufgenommen hat, in welchem Lauf des Kamera-Streams, als welcher Frame des Laufs - ergänzt um den eigenen Schritt des Moduls. Siehe [Die Lineage eines Ergebnisses](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#lineage).

Standardmäßig bleibt das Modul nie hinter seiner Kamera zurück. Treffen Frames schneller ein, als das Modul sie durchsucht, nimmt es jedes Mal den neuesten Frame, sobald die vorherige Suche abgeschlossen ist. Die Frames dazwischen werden als übersprungen gezählt. Wie viele Frames warten dürfen, wird mit der Warteschlangengröße festgelegt, siehe [Die Warteschlangengröße](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#queue-size).

Ein Modul nimmt den Stream einer Kamera. Für eine andere Kamera oder andere Einstellungen verwenden Sie ein anderes Modul.

## Die Knoten des Streams {#addresses}

Jedes Modul hat die Knoten des Streams, ob es einen Stream abonniert oder nicht. Um sie zu verwenden, ist kein Neustart nötig. Alle Adressen unten beginnen mit `hdvisionsystems/lumiscan-area-detector/<module-id>/`. Sie liegen neben `detect-area/`, nicht darin.

**Tabelle 1. Methoden**

| Adresse | Bedeutung |
| --- | --- |
| `control/subscribe/execute` | Prüft die fünf Eingaben von `control/subscribe` gemeinsam, speichert sie in der Einstellungsdatei des Moduls und wendet sie dann an: Ein laufender Stream folgt mit seinem nächsten Zyklus, ohne Neustart. Eine Eingabe allein zu schreiben ändert nichts. Siehe [Die Quelle ändern](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#subscribing). |
| `control/unsubscribe/execute` | Entfernt die in `control/unsubscribe/input/address` genannte Quelle, was auch den Stream-Modus beendet. Das Tag bleibt. Wird wie ein Subscribe in der Einstellungsdatei des Moduls gespeichert. |

**Tabelle 2. Eingaben von control/subscribe**

| Adresse | Typ | Bedeutung |
| --- | --- | --- |
| `control/subscribe/input/enable` | bool | Stream-Modus: `true` lässt den Stream laufen, `false` stoppt ihn. |
| `control/subscribe/input/address` | string | Die eine Quelle: der Stream-Ordner einer Kamera, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`. Das Modul liest dessen Knoten `frame`. Eine andere Adresse ersetzt die Quelle. |
| `control/subscribe/input/tag` | string | Das Tag, das das Modul auf seine Ergebnisse setzt: Der Schritt des Moduls in der Lineage jedes Ergebnisses trägt es, sodass jeder, der ein Ergebnis weiter unten in der Kette liest, sieht, welches Modul es erzeugt hat. Leer: die Modul-ID, das letzte Segment der Moduladresse, zum Beispiel `module-1`. Ein neues Tag markiert das nächste Ergebnis; die Quelle bleibt abonniert. |
| `control/subscribe/input/queue-size` | uint32 | Wie viele Frames warten dürfen, während ein Frame durchsucht wird: `1` bis `64`. Siehe [Die Warteschlangengröße](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#queue-size). |
| `control/subscribe/input/keep-latest-output` | bool | `true`, um jedes Stream-Ergebnis zusätzlich auf `detect-area/output/result` zu schreiben. Siehe [Die neueste Ausgabe behalten](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#keep-latest-output). |

Die Eingaben beginnen mit dem, was beim Start der Anwendung angewendet ist; ein Client kann also eine davon ändern und ausführen.

Was die Quelle enthalten muss: Lesen Sie `hdvisionsystems/lumiscan-area-detector/system/meta/subscription-schema`, für jedes Modul gleich. Es ist ein JSON Schema des Knotens `frame` der Quelle, ein `stream_image` mit seiner `lineage` und seinem `image`, in seiner JSON-Form. Siehe [Data-Layer-Referenz](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/datalayer-reference.html).

**Tabelle 3. Eingabe von control/unsubscribe**

| Adresse | Typ | Bedeutung |
| --- | --- | --- |
| `control/unsubscribe/input/address` | string | Die zu entfernende Quelle: die Adresse, die `setting/stream/address` zeigt. Ein `/` an einem der beiden Enden zählt nicht. |

**Tabelle 4. Einstellungen**

| Adresse | Typ | Bedeutung |
| --- | --- | --- |
| `setting/stream/enable`, `setting/stream/address`, `setting/stream/tag`, `setting/stream/queue-size`, `setting/stream/keep-latest-output` | wie die Eingaben | Was `control/subscribe/execute` oder `control/unsubscribe/execute` zuletzt angewendet hat, so wie die Einstellungsdatei es enthält. Schreibgeschützt. |
| `setting/settings-hash` | string | Der Hash dessen, womit die Ergebnisse erzeugt werden, als 16 Hexadezimalziffern. Schreibgeschützt. Siehe [Der Einstellungs-Hash](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#settings-hash). |

**Tabelle 5. Ausgaben**

| Adresse | Typ | Bedeutung |
| --- | --- | --- |
| `control/subscribe/output/stream/active` | bool | `true`, solange der Stream läuft. |
| `control/subscribe/output/stream/result` | flatbuffers `stream_areas` | Die in jedem Frame gefundenen Regionen und die Lineage des Frames. Abonnieren Sie den Knoten, um jedes Ergebnis zu erhalten. Siehe [Das Ergebnis eines Frames](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#result). |
| `control/subscribe/output/stream/last-failure` | string | Warum der letzte Frame, der nicht durchsucht werden konnte, fehlgeschlagen ist. Nennt die Quelle über ihre Adresse, siehe [Das Ergebnis eines Frames](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#result). Wird beim Start des Streams geleert. |
| `control/subscribe/output/stream/statistics/…` | uint64 | Zähler des aktuellen oder des letzten Streams, siehe [Die Statistik lesen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#statistics). |

Der Stream veröffentlicht seine Ergebnisse auf `control/subscribe/output/stream/result`. Von den Knoten von `detect-area` schreibt er nur `detect-area/output/result`, und nur mit eingeschaltetem `keep-latest-output`: `output/blob-labels`, `status-code` und `status-text` behalten, was der letzte Aufruf der Methode dort hinterlassen hat.

## Einrichten {#setting-up}

1. Stellen Sie sicher, dass der Stream des Cam Driver läuft: Sein `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/publish/output/stream/active` ist `true`.
2. Setzen Sie die Eingaben von `detect-area` wie für eine einzelne Erkennung, siehe [Flächen erkennen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/detecting-areas.html). Ein Aufruf von `detect-area/execute` auf dem `output/image` der Kamera ist ein schneller Weg, sie zu prüfen.
3. Schreiben Sie den Stream-Ordner der Kamera, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`, auf `control/subscribe/input/address`. Lassen Sie `control/subscribe/input/tag` leer, um die Ergebnisse mit der Modul-ID zu markieren, oder schreiben Sie ein eigenes Tag darauf.
4. Abonnieren Sie `control/subscribe/output/stream/result`.
5. Setzen Sie `control/subscribe/input/enable` auf `true`, und schreiben Sie dann auf `control/subscribe/execute`. Warten Sie, bis `control/subscribe/output/stream/active` `true` ist. Ab dann treffen die Ergebnisse ein.
6. Zum Stoppen setzen Sie `control/subscribe/input/enable` auf `false` und schreiben erneut auf `control/subscribe/execute`. Der gerade durchsuchte Frame wird zuerst abgeschlossen.

Auf ctrlX OS verwenden Sie für diese Schritte die Data-Layer-Ansicht der ctrlX OS-Weboberfläche oder Ihr SPS-Programm.

Auf einem PC dieselben Schritte mit `krxclient`, dem Kommandozeilen-Client von LumiScan Keryx, der die Rolle einer SPS übernimmt (siehe [Werkzeuge](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/tools.html#krxclient)). Ergänzen Sie die Optionen `--keryx-backend` und `--keryx-url`, die Ihr Broker benötigt:

```none
krxclient write hdvisionsystems/lumiscan-area-detector/module-1/control/subscribe/input/address hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream
krxclient write hdvisionsystems/lumiscan-area-detector/module-1/control/subscribe/input/enable true
krxclient execute hdvisionsystems/lumiscan-area-detector/module-1/control/subscribe/execute
krxclient subscribe hdvisionsystems/lumiscan-area-detector/module-1/control/subscribe/output/stream/result --count 5
```

`krxclient subscribe` zeigt einen Flatbuffer nur über seine Größe an. Es sagt Ihnen, dass Ergebnisse eintreffen, nicht, was sie enthalten.

Gut zu wissen:

- Der Stream-Modus ist ein **Pegel**, kein Befehl: Der Stream läuft, solange das angewendete `enable` `true` ist.
- Der Stream kann vor dem Stream des Cam Driver gestartet werden. Ergebnisse treffen ein, sobald Frames eintreffen.
- Was `control/subscribe/execute` anwendet, wird in der Einstellungsdatei des Moduls gespeichert. Nach einem Neustart der Anwendung startet das Modul, wie es war: Eines, das gestreamt hat, streamt sofort wieder, ohne dass Ihr Programm etwas ausführt. Siehe [In der Einstellungsdatei erhalten](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#saving).

## Die Quelle ändern {#subscribing}

Ein Modul nimmt eine Quelle. Eine SPS oder ein anderer Client ändert sie, während die Anwendung läuft, mit oder ohne laufenden Stream:

1. Schreiben Sie die neuen Werte auf die Eingaben von `control/subscribe` - nur die, die Sie ändern: Die anderen enthalten, was angewendet ist.
2. Schreiben Sie auf `control/subscribe/execute`. Die Eingaben werden gemeinsam geprüft, in der Einstellungsdatei des Moduls gespeichert und erst dann angewendet: `setting/stream/` zeigt sie sofort, und ein laufender Stream folgt mit seinem nächsten Zyklus. Eine andere Adresse ersetzt die Quelle; die Frames, die bei der alten warteten, werden als übersprungen gezählt. Ein neues Tag, eine neue Warteschlangengröße oder ein neues `keep-latest-output` braucht kein neues Abonnement: Ein neues Tag markiert das nächste Ergebnis.
3. Um die Quelle zu entfernen, schreiben Sie ihre Adresse auf `control/unsubscribe/input/address` und dann auf `control/unsubscribe/execute`. Damit endet der Stream-Modus. Die Eingaben von `control/subscribe` werden auf das gesetzt, was angewendet wurde: Stream-Modus aus, keine Adresse. Das Tag bleibt: Es markiert die Ergebnisse des Moduls, nicht die Quelle.

Kann die Einstellungsdatei nicht geschrieben werden, ändert sich nichts. Siehe [In der Einstellungsdatei erhalten](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#saving).

Die Methoden antworten mit einem Ergebnis des Data Layer. Sein Name unterscheidet sich zwischen den beiden Data Layern, siehe [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results):

| ctrlX OS | PC (LumiScan Keryx) | Wann |
| --- | --- | --- |
| `DL_OK` | `Ok` | Erledigt. |
| `DL_INVALID_VALUE` | `Rejected` | `control/subscribe/execute`: Stream-Modus ohne Adresse oder eine Warteschlangengröße außerhalb von `1` bis `64`. `control/unsubscribe/execute`: Die Adresse ist nicht die Quelle, oder es gibt keine Quelle. |
| `DL_CREATION_FAILED` | `CreationFailed` | Die Einstellungsdatei konnte nicht geschrieben werden, zum Beispiel weil sie kein gültiges JSON ist. Nichts wurde geändert. |

Diese Methoden haben keinen `status-text`. Der Grund für eine Ablehnung wird in das Protokoll der Anwendung geschrieben.

Kann die Quelle nicht abonniert werden, versucht es das Modul alle 5 Sekunden erneut, solange der Stream läuft, und protokolliert den ersten Fehlschlag.

## Das Ergebnis eines Frames {#result}

`control/subscribe/output/stream/result` enthält eine FlatBuffers-Tabelle vom Typ `stream_areas` (Datei-Identifier `HSAR`), auf dem Data Layer registriert als `types/hdvisionsystems/lumiscan-area-detector/stream_areas`. Ihr kompiliertes Schema ist als `bfbs/stream_areas.bfbs` installiert.

| Feld | Bedeutung |
| --- | --- |
| `lineage` | Woher das Ergebnis kam, siehe [Die Lineage eines Ergebnisses](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#lineage). |
| `result` | Die Regionen, als `hdv.area_detect.Result`: dieselbe Tabelle, die `detect-area` für dasselbe Bild auf `output/result` schreibt, beschrieben in [Flächen erkennen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/detecting-areas.html). |

Ein Lesen von `control/subscribe/output/stream/result` liefert das neueste Ergebnis; vor dem ersten Frame ein leeres. Das letzte Ergebnis bleibt erhalten, nachdem der Stream gestoppt wurde.

Ein Frame wird so dekodiert, wie `detect-area` den Bildknoten dekodiert; es werden also dieselben Pixelformate akzeptiert, siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/requirements.html). Ein Frame und dasselbe Bild, gelesen über `input/input-image-address`, ergeben dieselben Regionen.

Ein Frame, der nicht durchsucht werden kann, liefert kein Ergebnis. Er wird in `statistics/failed-frames` gezählt, und `control/subscribe/output/stream/last-failure` sagt, warum, zum Beispiel:

```
a frame of 'hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream' failed: invalid input: preprocess/method 'LAPLACE' is unknown; expected NONE, LOG, DOG or DOH
```

Die Gründe sind dieselben, die `detect-area` in seinem `status-text` nennt: eine Eingabe, die es ablehnen würde, eine Ausschnittsregion, die nicht in den Frame passt, eine fehlgeschlagene Erkennung.

## Die Lineage eines Ergebnisses {#lineage}

`lineage.steps` listet auf, woher das Ergebnis kam, Ursprung zuerst:

1. Der Schritt der Kamera, wie der Cam Driver ihn erzeugt hat: `producer` ist die Adresse der Kamera, `hdvisionsystems/lumiscan-cam-driver/<camera name>`; `run`, wann der Stream der Kamera gestartet wurde; `sequence` die Nummer des Frames in diesem Lauf; `external_id` die eigene Frame-Nummer der Kamera; `settings_hash` die Einstellungen der Kamera; `tag` das Tag des Cam Driver für die Kamera, standardmäßig ihre Modul-ID, zum Beispiel `camera1`.
2. Der Schritt des Moduls: `producer` ist die Adresse des Moduls, `hdvisionsystems/lumiscan-area-detector/<module-id>`; `run`, wann der Stream des Moduls gestartet wurde (jeder Start ist ein neuer Lauf); `sequence` die Nummer des Ergebnisses im Lauf, ab `1`; `settings_hash` die Einstellungen des Moduls, siehe [Der Einstellungs-Hash](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#settings-hash); `elapsed_us` die Mikrosekunden vom Eintreffen des Frames beim Modul bis zu seinem Ergebnis, Wartezeit eingeschlossen; `time_us`, wann das Ergebnis erzeugt wurde, in Mikrosekunden seit der Epoche; `tag` das Tag des Moduls, `control/subscribe/input/tag`, oder die Modul-ID, wenn es leer ist.

Ein Ergebnis benennt seinen Frame also genau: die Kamera über `producer`, den Frame über `run` und `sequence`. Um zu erfahren, von welcher Kamera ein Ergebnis kam, lesen Sie den `producer` seines ersten Schritts. Eine Lücke in der `sequence` des Kameraschritts zwischen zwei Ergebnissen derselben Kamera sind Frames, die übersprungen wurden, fehlgeschlagen sind oder verloren gingen.

Eine Lineage enthält höchstens 16 Schritte. Eine längere behält den Ursprung und die neuesten Schritte, und `dropped` zählt die ausgelassenen Schritte.

Ein Frame ohne Lineage ergibt ein Ergebnis mit dem Schritt des Moduls allein. Ein Wert auf dem Knoten `frame` eines Streams, der kein `stream_image` ist, wird ignoriert und einmal protokolliert.

## Der Einstellungs-Hash {#settings-hash}

`setting/settings-hash` und der `settings_hash` des Modulschritts in jedem Ergebnis identifizieren, womit die Ergebnisse erzeugt werden. Der Knoten zeigt den Hash als 16 Hexadezimalziffern; der Schritt enthält denselben Wert als Zahl. Der Hash umfasst:

- jede Eingabe von `detect-area`, die die Erkennung liest, genau so, wie sie für den Frame gelesen wurde - alle außer `input/input-image-address`;
- den Namen und die Version der Anwendung.

Keine Eingabe von `detect-area` nennt eine Datei, also ist keine Datei Teil des Hashs. Stream-Modus, Quelle, Warteschlangengröße und keep-latest-output sind ebenfalls nicht Teil davon: Sie wählen und takten die Frames, sie ändern nicht, was darin gefunden wird.

`setting/settings-hash` wird etwa jede halbe Sekunde aktualisiert, auch wenn der Stream aus ist. Wenn ein Hash zum ersten Mal erscheint, schreibt das Modul die Einstellungen, für die er steht, nach `settings-history/<module-id>-<hash>.json` im Konfigurationsverzeichnis der Anwendung, sodass sich ein in einem Ergebnis gefundener Hash später nachschlagen lässt. Die Anwendung löscht diese Dateien nicht. Eine Datei sieht so aus, gekürzt:

```json
{
    "format": 1,
    "settings": {
        "detect-area/input/method": "FIXED",
        "detect-area/input/method-specific/fixed/level": 128.0,
        "detect-area/input/preprocess/method": "NONE",
        "software.name": "lumiscan-area-detector",
        "software.version": "<version>"
    },
    "settingsHash": "<16 hex digits>"
}
```

> [!NOTE]
> Ein Ergebnis trägt nur den Hash. Ein anderer Hash sagt, dass sich etwas geändert hat, womit die Ergebnisse erzeugt werden, nicht, was sich geändert hat. Um das herauszufinden, vergleichen Sie die beiden Dateien in `settings-history`, die die Hashes benennen, von Hand.

Der Hash umfasst die Parameter jeder Vorverarbeitungsmethode, nicht nur der gewählten. Das Bearbeiten von `input/preprocess/dog/…`, während `input/preprocess/method` `NONE` ist, ändert den Hash, aber keine einzige Region.

## Die Statistik lesen {#statistics}

Die Zähler beginnen bei jedem Start des Streams bei null, werden etwa viermal pro Sekunde aktualisiert, solange er läuft, und behalten ihre letzten Werte, nachdem er gestoppt wurde. Alle Adressen beginnen mit `control/subscribe/output/stream/statistics/`.

| Zähler | Bedeutung |
| --- | --- |
| `elapsed-ms` | Millisekunden seit dem Start des Streams. Teilen Sie einen Zähler dadurch, um eine Rate zu erhalten. |
| `received-frames` | Frames, die das Abonnement geliefert hat. |
| `processed-frames` | Durchsuchte Frames, jeder mit einem auf `control/subscribe/output/stream/result` veröffentlichten Ergebnis. |
| `skipped-frames` | Nie durchsuchte Frames: von neueren aus der Warteschlange verdrängt, während ein Frame durchsucht wurde (siehe [Die Warteschlangengröße](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#queue-size)), oder wartend, als die Quelle ersetzt oder entfernt wurde. |
| `failed-frames` | Frames, die nicht durchsucht werden konnten. `control/subscribe/output/stream/last-failure` sagt, warum der letzte fehlgeschlagen ist, und das Protokoll nennt die Fehlschläge, höchstens eine Zeile alle 5 Sekunden. |
| `lost-frames` | Frames, die verloren gingen, bevor sie ankamen, ermittelt aus Lücken in der `sequence` der Kamera innerhalb eines Laufs ihres Streams. Eine neue Quelle oder ein neuer Lauf des Kamera-Streams beginnt die Zählung von vorn. |
| `processing-us` | Mikrosekunden, die alle Erkennungen gedauert haben, summiert, ohne die Zeit, die ein Frame auf `detect-area` gewartet hat. Teilen Sie durch `processed-frames` für den Mittelwert. |

Frames, die beim Stoppen des Streams noch warten, werden verworfen, ohne gezählt zu werden.

## In der Einstellungsdatei erhalten {#saving}

Stream-Modus und Quelle sind Einstellungen des Moduls. Sie werden im Member `stream` der Einstellungsdatei des Moduls aufbewahrt, `<module-id>.json` im Konfigurationsverzeichnis der Anwendung - der Datei, in die `system/save-module-inputs` die Eingaben schreibt.

`control/subscribe/execute` und `control/unsubscribe/execute` speichern dort selbst, was sie anwenden, alle fünf Werte in einem Schreibvorgang, bevor sie sie anwenden. Kann die Datei nicht geschrieben werden, antwortet die Methode mit `DL_CREATION_FAILED` (auf einem PC `CreationFailed`), und nichts ändert sich. Nach einem Neustart abonniert das Modul dieselbe Quelle und startet, wenn `stream.enable` `true` ist, seinen Stream sofort: Niemand muss etwas ausführen.

Das Speichern ändert nur den Member `stream`; der Rest der Datei bleibt, wie er war. Das Modul legt die Datei an, wenn es noch keine gibt - ein Modul, dessen Eingaben nie gespeichert wurden, hat keine. `system/save-module-inputs` wiederum behält den Member `stream`, wenn es die Datei neu schreibt; die Eingaben von `control/subscribe` werden nicht als Eingaben des Moduls gespeichert.

Das Konfigurationsverzeichnis ist:

| Plattform | Konfigurationsverzeichnis |
| --- | --- |
| ctrlX OS | `/var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-area-detector` |
| PC (Windows) | `%APP_RESOURCE_DIR%\etc\lumiscan-area-detector`; ohne `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-areadetect\etc\lumiscan-area-detector` |

Der Member `stream`, neben den Eingaben von `detect-area` (hier gekürzt):

```json
{
    "detect-area": {
        "method-specific/fixed/level": 128.0
    },
    "stream": {
        "enable": true,
        "address": "hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream",
        "queueSize": 1,
        "keepLatestOutput": false
    }
}
```

| Schlüssel | Erforderlich | Bedeutung |
| --- | --- | --- |
| `enable` | Nein | Stream-Modus: `true` startet den Stream beim Start der Anwendung. Benötigt eine `address`. `false`, wenn weggelassen. |
| `address` | Nein | Die eine Quelle: der Stream-Ordner einer Kamera. |
| `tag` | Nein | Was die Ergebnisse des Moduls markiert: das `tag` des Modulschritts in ihrer Lineage. Die Modul-ID, wenn weggelassen. |
| `queueSize` | Nein | Wie viele Frames warten dürfen: `1` bis `64`, `1`, wenn weggelassen. |
| `keepLatestOutput` | Nein | `true`, um jedes Stream-Ergebnis zusätzlich auf `detect-area/output/result` zu schreiben. `false`, wenn weggelassen. |
| `onEntry` | Nein | Die Schritte, die auf jeden eintreffenden Frame angewendet werden, jeder ein Objekt mit einem `kind`, wie das `stream` jeder LumiScan-Anwendung sie hat. Diese Anwendung hat noch keine: Lassen Sie ihn weg oder leer (`[]`). Ein Schritt startet das Modul außerhalb des Stream-Modus, mit einer Warnung im Protokoll; das Speichern behält ihn. |

`control/subscribe/execute` und `control/unsubscribe/execute` schreiben alle fünf.

Gut zu wissen:

- Die Datei wird einmal gelesen, wenn das Modul beim Start der Anwendung wiederhergestellt wird: ein Modul in der gespeicherten Modulliste oder `module-1` bei einer frischen Installation. Von Hand an der Datei vorgenommene Änderungen wirken beim nächsten Start.
- Ein mit `system/create-module` angelegtes Modul beginnt mit ausgeschaltetem Stream, ohne Quelle, mit einer Warteschlangengröße von `1` und ausgeschaltetem `keep-latest-output`, was auch immer eine Datei seines Namens enthält. Was es von da an anwendet, wird in diese Datei gespeichert.
- Um ein Modul und seinen Stream nach einem Neustart zurückzubekommen, speichern Sie auch die Modulliste, mit `system/save-current-modules`. Das Speichern einer Liste, die ein Modul nicht mehr nennt, löscht die Datei dieses Moduls und damit seine Stream-Einstellungen. Siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/module-management.html).
- Ein Wert, der nicht verwendet werden kann, wird ignoriert und protokolliert: ein `enable` oder `keepLatestOutput`, das nicht `true` oder `false` ist, eine `address` oder ein `tag`, das kein String ist, eine `queueSize` außerhalb von `1` bis `64` (`1` wird verwendet). Stream-Modus ohne `address` wird ignoriert: Das Modul startet außerhalb des Stream-Modus.
- Der Member `subscriptions` früherer Versionen wird nicht mehr gelesen, und das Modul protokolliert, dass er umgezogen ist: Geben Sie die Quelle als `address` an.

> [!WARNING]
> Fügen Sie `<module-id>.json` keine Kommentare hinzu. Der Stream liest eine Datei mit Kommentaren, aber die Eingaben des Moduls werden dann beim Start nicht wiederhergestellt: Das Protokoll meldet die Datei als unlesbar.

## Die Warteschlangengröße {#queue-size}

`control/subscribe/input/queue-size` legt fest, wie viele Frames warten dürfen, während ein Frame durchsucht wird: `1` bis `64`, standardmäßig `1`. Sie wird als `stream.queueSize` gespeichert, und `setting/stream/queue-size` zeigt den verwendeten Wert. Ein Frame, der eintrifft, wenn so viele warten, verdrängt den ältesten von ihnen, was in `statistics/skipped-frames` gezählt wird. Eine neue Warteschlangengröße gilt ab dem nächsten eintreffenden Frame, ohne neues Abonnement.

| Warteschlangengröße | Wirkung |
| --- | --- |
| 1 (Standard) | Das Modul durchsucht den neuesten Frame. Es bleibt nie zurück; ist die Suche langsamer als die Kamera, überspringt es Frames. |
| Mehr als 1 | Kurze Frame-Schübe werden alle durchsucht, und weniger werden übersprungen. Ist die Suche länger langsamer als die Kamera, bleibt das Modul zurück: Es durchsucht Frames, die bis zu so viele Suchen alt sind. Jeder wartende Frame hält ein ganzes Bild im Speicher. |

## Die neueste Ausgabe behalten {#keep-latest-output}

Mit `control/subscribe/input/keep-latest-output` `true` - angewendet durch `control/subscribe/execute`, gespeichert als `stream.keepLatestOutput` - schreibt das Modul jedes Stream-Ergebnis zusätzlich auf `detect-area/output/result`, so wie `detect-area/execute` es schreibt, sobald das Ergebnis auf `control/subscribe/output/stream/result` veröffentlicht ist. Ein Client, der `detect-area/output/result` liest, hat dann das Ergebnis des neuesten Frames, ohne den Stream zu abonnieren. `output/blob-labels`, `status-code` und `status-text` werden nicht geschrieben: Sie behalten, was der letzte Aufruf von `detect-area` dort hinterlassen hat. Das kostet eine Kopie jedes Ergebnisses. Standardmäßig aus.

## detect-area, während der Stream läuft {#while-streaming}

Der Stream und `detect-area` verwenden dieselben Eingaben, und sie laufen auf einem Modul nie gleichzeitig:

- Ein Frame, der eintrifft, während `detect-area` läuft, wartet, bis die Methode abgeschlossen ist. Er ist verzögert, nicht fehlgeschlagen.
- Ein Aufruf von `detect-area/execute`, während ein Frame durchsucht wird, antwortet mit belegt: `output/status-code` ist `-1`, der Schreibvorgang antwortet mit `DL_TOO_MANY_OPERATIONS` (auf einem PC `TooManyOperations`), und nichts wird getan. `output/result` und `output/blob-labels` behalten ihre Werte, wie bei jedem belegten Aufruf (siehe [Eine Methode ausführen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/execute-a-method.html)). Bei einer streamenden Kamera passiert das oft. Stoppen Sie den Stream, bevor Sie die Methode aufrufen, oder rufen Sie sie erneut auf.
- `system/remove-module` antwortet ebenfalls mit belegt (`-1`), während ein Frame dieses Moduls durchsucht wird. Stoppen Sie zuerst den Stream. Das Entfernen eines Moduls stoppt seinen Stream.
- `system/analyse-scene` hat eine eigene Sperre und wird vom Stream nicht aufgehalten.

Andere Module sind nicht betroffen: Jedes Modul hat seine eigene Sperre und seinen eigenen Stream.

## Einschränkungen {#limitations}

- Das Label-Bild wird nicht gestreamt, siehe oben.
- Der Stream wurde nur unter Windows mit LumiScan Keryx und mit simulierten Bildern getestet. Er wurde weder unter Linux noch auf dem ctrlX Data Layer noch mit einer echten Kamera verifiziert.
- LumiScan Cockpit zeichnet die Ergebnisse des Streams noch nicht.
- Von Hand an der Einstellungsdatei vorgenommene Änderungen wirken beim nächsten Start der Anwendung.
- Der Hash umfasst jede Eingabe, die die Erkennung liest, einschließlich der Parameter nicht gewählter Vorverarbeitungsmethoden. Er ändert sich bei manchen Änderungen, die kein Ergebnis ändern.

# Eine Szene analysieren – LumiScan Area Detector

URL: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/analysing-a-scene.html

`system/analyse-scene` misst ein Bild und sagt Ihnen, auf welchen Wert ein fester Schwellwert eingestellt werden müsste, um die Teile darin zu messen. Die Analyse berichtet; sie ändert nichts.

Sie liegt unter `system/` und nicht in einem Modul, weil die Antwort das **Bild** betrifft. Zehn Module, die auf dieselbe Kamera schauen, hätten dieselbe Frage zehnmal gestellt und dieselbe Antwort zurückbekommen.

## Was sie braucht

| Knoten | Typ | Standard | Bedeutung |
| --- | --- | --- | --- |
| `input/input-image-address` | string | `""` | 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: Jeder Block von `bin-size` × `bin-size` wird zu einem Pixel. 0 verkleinert nur, was verkleinert werden muss. Alles Gemeldete bleibt in den Einheiten **Ihres** Bildes. |
| `input/histogram-bins` | int32 | 256 | Wie fein `output/histogram` die Grauwerte zählt, 2 bis 256. |

> [!NOTE]
> `bin-size` und `histogram-bins` sind verschiedene Stellschrauben. `bin-size` verkleinert das Bild, das die Analyse misst, und will eine kleine Zahl. `histogram-bins` legt nur fest, wie die Grauwerte in Klassen eingeteilt werden, und 256 - eine Klasse pro Grauwert - ist meist richtig.

## Was sie meldet

`output/recommended-settings` ist die praktische Ausgabe: eine Liste von `node=value`-Zeilen, relativ zum `detect-area/input/` eines Moduls, mit dem einzustellenden Schwellwert, der Angabe, welche Seite das Teil ist, und ob eine Region als die Form gemessen werden muss, die ihr Umriss einschließt. Nichts wird für Sie geschrieben - lesen Sie die Zeilen und setzen Sie die Werte bewusst.

`output/histogram` ist das Mittel, um diesen Rat zu prüfen. Ein fester Schwellwert sollte im Tal zwischen dem Buckel des Teils und dem des Hintergrunds liegen, und eine einzelne vorgeschlagene Zahl kann Ihnen nicht zeigen, ob es ein Tal gibt, zwei oder gar keines. Es wird auf dem zugeschnittenen Bild in voller Größe gezählt, vor jeder mit `bin-size` angeforderten Verkleinerung, und beschreibt daher das Bild und nicht eine Neuabtastung davon.

Die übrigen Ausgaben beschreiben das Bild: `parts-are-dark`, `parts-touching`, `region-count`, `expected-region-count`, `illumination-spread`, `separability`, `feature-thickness` und `area-sensitivity`. `output/findings` sagt in Worten alles Wissenswerte, einschließlich der Fälle, in denen kein Schwellwert funktionieren wird.

## Die Ausgabe, die Sie zuerst lesen sollten

`area-sensitivity` beantwortet die Frage "Hält ein fester Schwellwert hier?". Sie gibt an, wie stark sich die gemessene Fläche bewegt, wenn sich der Schwellwert um einen Grauwert verschiebt - **kleiner ist besser**, und unter `0` gibt es nichts anzustreben.

| Wert | Was er bedeutet |
| --- | --- |
| `0.006` | Eine harte Kante. Der Schwellwert liegt in einem leeren Tal; ein fester Schwellwert ist sicher. |
| `0.01` | Immer noch komfortabel. |
| **`> 0.05`** | **Spröde.** Ein Grauwert kostet 5 % des Messwerts. Ein fester Schwellwert ist hier **nicht** sicher einzustellen, und die Anwendung sagt das in `output/findings`. |
| `0.15` | Ein Bild, das überhaupt nicht stillhält. |

Die entscheidende Rechnung ist `area-sensitivity × Drift in Grauwerten = relativer Fehler`. Bei `0.05` verschiebt eine Lampe, die über eine Schicht um zehn Grauwerte altert, Ihren Messwert um die Hälfte.

### Es kostet Sie nur etwas, wenn sich etwas bewegt

Ein hoher Wert unter einer **stabilen** Lampe ist ein konstanter Versatz: Er lässt sich aus einem absoluten Messwert herauskalibrieren und hebt sich vollständig auf, wenn Sie ein Teil mit einem anderen vergleichen. Er schadet, wenn sich die Beleuchtung oder der Schwellwert bewegt. Lesen Sie diese Zahl also zusammen damit, wie stabil Ihre Zelle tatsächlich ist.

### Ein sprödes Bild beheben

Nichts in `detect-area/input/` behebt es. Diese Anwendung bietet eine Schwellwertmethode, `FIXED`; es gibt also keinen durchlaufenden oder adaptiven Schwellwert, hinter dem man sich verstecken könnte - ein sprödes Bild wird an der Kamera behoben.

Die Empfindlichkeit ist ungefähr `Umfang × Breite der Kantenrampe / (Kontrast × Fläche)`, woraus sich drei Hebel ergeben. Arbeiten Sie die Tabelle von oben nach unten ab:

| Hebel | Was die Zahl erhöht | Was zu tun ist |
| --- | --- | --- |
| **Kantenweichheit** | Defokussierung, Bewegungsunschärfe, Sensorrauschen bei hoher Verstärkung. Meist die größte Ursache und die am wenigsten vermutete - dieselbe Szene defokussiert, mit unveränderter Beleuchtung, lässt diese Zahl auf mehr als das Doppelte steigen. | Neu fokussieren. Belichtungszeit verkürzen oder das Teil ruhigstellen, um Bewegungsunschärfe zu beseitigen. Verstärkung senken und stattdessen Licht hinzufügen. Bessere Optik. |
| **Kontrast** | Ein schmaler Grauwertabstand zwischen Teil und Hintergrund, sodass der Kantenübergang flach verläuft. | Beleuchtung: Durchlicht, Winkel ändern, einen Diffusor oder Polarisator hinzufügen, den Hintergrund ändern. |
| **Merkmalsgröße** | Dünne oder filigrane Teile - viel Umfang bei sehr wenig Fläche. Liegt am Teil, nicht an Ihrem Aufbau. | Mehr Pixel auf dem Teil: Vergrößerung, ein kürzerer Arbeitsabstand oder ein Sensor mit höherer Auflösung. |

### Welcher Hebel Ihrer ist

Raten Sie nicht - die anderen Ausgaben benennen ihn, und sie haben in dieser Reihenfolge Vorrang voreinander:

1. `illumination-spread`, gemessen am Abstand zwischen Teil und Hintergrund. Variiert das Licht um mehr als etwa ein Drittel dieses Abstands, ist ungleichmäßige Beleuchtung das eigentliche Problem, und kein einzelner Schwellwert passt zum ganzen Bild. Beheben Sie das zuerst.
2. `feature-thickness`. Unter etwa 8 px sind die Merkmale schlicht fein, und keine Lampenabstimmung ändert daran etwas - Sie brauchen mehr Pixel auf dem Teil.
3. Erst dann ist es Kantenweichheit oder Kontrast.

`output/findings` sagt in Worten, welchen der drei es getroffen hat, den wichtigsten zuerst.

# Die Erkennung abstimmen – LumiScan Area Detector

URL: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/tuning-the-detection.html

Die Standardwerte finden in den meisten Bildern **irgendetwas**. Diese Seite beschreibt, wie sie das Richtige finden.

## Die Einstellungen, auf die es ankommt

Nur drei, was einen großen Teil des Reizes ausmacht:

- **`method-specific/fixed/level`:** Die Helligkeit, die ein Pixel überschreiten muss, um als Teil einer Region zu zählen. Stellen Sie sie mit [Eine Szene analysieren](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/analysing-a-scene.html) ein, statt zu raten - die Analyse schlägt einen Schwellwert vor und zeigt Ihnen das Histogramm, in dem der Schwellwert liegen muss.
- **`detect-dark`:** Einschalten, wenn die Teile dunkler als der Hintergrund sind.
- **`fill-holes`:** Einschalten, um eine Region als die Form zu messen, die ihr Umriss einschließt. Eine Unterlegscheibe misst sich ausgeschaltet als Ring und eingeschaltet als Scheibe, und beides sind richtige Antworten.

Ein Flächenfenster gibt es hier nicht. Jede Region wird gemeldet, und das Verwerfen derjenigen, die zu klein oder zu groß für ein Teil sind, geschieht dort, wo das Ergebnis gelesen wird - nur dort ist bekannt, was ein Teil ist.

## Vorverarbeitung

Probieren Sie `preprocess/method`, wenn Regionen weiche oder verrauschte Kanten haben. `LOG` und `DOG` heben beide Merkmale einer bestimmten Größe hervor - setzen Sie die Sigmas ungefähr auf die Größe dessen, was Sie suchen -, und `DOH` reagiert auf blob-artige Strukturen. Alle drei normalisieren ihre Ausgabe, die oben genannten Intensitäts-Schwellwerte müssen nach dem Einschalten eines Filters also eventuell neu gesetzt werden.

## Wenn kein Schwellwert funktioniert

Wenn sich der Messwert nicht stabilisiert, prüfen Sie `system/analyse-scene/output/area-sensitivity`, bevor Sie die Einstellungen anfassen. Über `0.05` ist das Bild spröde - ein Grauwert kostet 5 % der gemessenen Fläche -, und kein Wert in `input/` behebt das. Es wird an der Kamera behoben: schärfere Kanten, mehr Kontrast oder mehr Pixel auf dem Teil. Siehe [Eine Szene analysieren](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/analysing-a-scene.html), um zu erfahren, welches von den dreien es ist.

## Geschwindigkeit

In der Reihenfolge ihrer Wirkung:

1. **Schränken Sie den Bereich ein** mit `input/crop`.
2. **Erhöhen Sie den Schwellwert**, damit Sensorrauschen und Staub den Schwellwert gar nicht erst überschreiten. Das ist günstiger, als diese Regionen zu melden und anschließend zu verwerfen.

# Modulverwaltung – LumiScan Area Detector

URL: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/module-management.html

Ein **Modul** ist eine konfigurierte Instanz der Anwendung. Es besitzt die Erkennungsoperation mit eigenen Einstellungen und eigenen Ergebnissen:

```
hdvisionsystems/lumiscan-area-detector/<module-id>/detect-area/...
```

Module können angelegt und entfernt werden, während die Anwendung läuft. Eine frische Installation bedient ein Modul namens `module-1`.

> [!IMPORTANT]
> **Auf ctrlX OS deckt eine Lizenz zehn Module ab.** Das elfte Modul belegt eine zweite Lizenz desselben Schlüssels, und ein Modul wird mit Status `-11` abgelehnt, wenn keine Lizenz auf dem Gerät es abdeckt.

Der Verwaltungsknoten liegt außerhalb der Module:

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

## Knoten

| Knoten | Typ | Beschreibung |
| --- | --- | --- |
| `modules` | string-Array | Die Module, die derzeit existieren |
| `create-module/execute` | Methode | Legt ein Modul und seinen Knoten-Teilbaum an |
| `create-module/input/module-id` | string | Name des anzulegenden Moduls. Nur Kleinbuchstaben, Ziffern, `-` und `_`; darf nicht `system` sein und darf nicht bereits existieren |
| `remove-module/execute` | Methode | Entfernt ein Modul und seinen Knoten-Teilbaum |
| `remove-module/input/module-id` | string | Name des zu entfernenden Moduls |
| `save-current-modules/execute` | Methode | Speichert die Modulliste dauerhaft, damit beim nächsten Start dieselben Module wieder angelegt werden |
| `save-module-inputs/execute` | Methode | Speichert die Einstellungen eines Moduls dauerhaft |
| `save-module-inputs/input/module-id` | string | Name des Moduls, dessen Einstellungen gespeichert werden sollen |

Jede Methode hat außerdem `output/status-code` und `output/status-text`. Wie sich diese Module von denen der anderen LumiScan-Apps unterscheiden, ist in [Einstellungen, Module und Neustart](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/settings-and-modules.html#registry-apps) beschrieben.

## Ein Modul anlegen

1. Setzen Sie `system/create-module/input/module-id` auf den neuen Namen
2. Schreiben Sie auf `system/create-module/execute`
3. Prüfen Sie, dass `system/create-module/output/status-code` `1` ist

Das Modul ist sofort aktiv, mit Standardeinstellungen, und erscheint in `system/modules`. Es ist **nicht** dauerhaft, bis die Modulliste gespeichert wird.

Das Entfernen eines Moduls ist das Spiegelbild, über `remove-module`. Ein Modul wird mit `-1` (belegt) abgelehnt, solange eine seiner eigenen Operationen läuft, statt dass seine Knoten mitten in der Ausführung zerstört werden.

> [!NOTE]
> Ein jetzt angelegtes Modul ist ein **neues** Modul: Es beginnt mit den Standard-Eingabewerten, auch wenn vorher ein Modul dieses Namens existierte und seine Einstellungen gespeichert wurden. Diese Einstellungen bleiben auf dem Datenträger, bis das Entfernen dauerhaft gemacht wird - `save-current-modules` löscht die gespeicherten Eingaben jedes Moduls, das die neue Liste nicht mehr nennt, denn bis die Liste geschrieben ist, ist ein Entfernen nicht dauerhaft, und ein Neustart bringt das Modul mit unveränderten Einstellungen zurück.

## Speichern

Zwei Dinge werden getrennt gespeichert, und beide müssen gespeichert werden, um einen Neustart zu überstehen:

- **die Modulliste** - `save-current-modules`, damit dieselben Module wieder angelegt werden;
- **die Einstellungen jedes Moduls** - `save-module-inputs`, einmal pro Modul.

So speichern Sie die Einstellungen eines Moduls:

1. Setzen Sie `system/save-module-inputs/input/module-id`
2. Schreiben Sie auf `system/save-module-inputs/execute`
3. Prüfen Sie, dass `system/save-module-inputs/output/status-code` `1` ist

Jede Eingabe dieses Moduls wird in das Konfigurationsverzeichnis der Anwendung geschrieben und beim nächsten Start wiederhergestellt. Ergebnisse werden nicht gespeichert - sie werden vom nächsten Durchlauf erzeugt.

Eine Einstellung, deren Knoten nach einem Software-Update nicht mehr existiert, wird mit einem Protokolleintrag übersprungen; eine ältere Konfiguration verhindert also nie den Start der Anwendung.

## Warum die Adresse auch bei einem Modul ein Modul enthält

Die Ebene `<module-id>` ist immer vorhanden, damit sich Adressen nicht ändern, wenn ein zweites Modul hinzukommt: Ein heute gegen `module-1` geschriebenes Programm funktioniert weiter. Das entspricht auch der Pfadkonvention, die die anderen LumiScan-Anwendungen dokumentieren.

## Was Module gemeinsam haben

Module sind vollständig unabhängig: Jedes hat seine eigene Kamera, seine eigenen Erkennungseinstellungen und seine eigenen Ergebnisse, und die Anwendung hält keinen gemeinsamen Zustand, um den sie konkurrieren könnten. Die Erkennung braucht kein gespeichertes Referenzbild, es gibt also nichts anwendungsweit zu konfigurieren.

# Data-Layer-Referenz – LumiScan Area Detector

URL: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/datalayer-reference.html

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).

# Anleitung: Teilefläche aus einem Kamerabild messen – LumiScan Area Detector

URL: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/how-tos/measure-part-area-from-a-camera-image.html

Von Anfang bis Ende: eine echte Flächenmessung aus einer laufenden Kamera gewinnen und dafür sorgen, dass sie einen Neustart übersteht.

## Bevor Sie beginnen

- LumiScan Cam Driver ist installiert und veröffentlicht ein Bild, zum Beispiel unter `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`.
- LumiScan Area Detector ist installiert, und `system/modules` führt `module-1` auf. Auf ctrlX OS ist die Anwendung außerdem lizenziert, siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/requirements.html).
- Die Teile liegen vor der Kamera, in der Beleuchtung, die die Installation tatsächlich verwenden wird.

## Schritt 1: Sehen, was mit den Standardwerten gefunden wird

```
module-1/detect-area/input/input-image-address = hdvisionsystems/lumiscan-cam-driver/camera1/output/image
write module-1/detect-area/execute
```

Prüfen Sie, dass `output/status-code` `1` ist, und lesen Sie dann `output/result`. Sehen Sie sich `blob_count` an: zu viele bedeutet, dass Rauschen mitgezählt wird, null bedeutet, dass nichts zutraf.

Die Flächen sind bereits echte Pixelzahlen. Was der nächste Schritt ändert, ist, wie die Regionen gefunden werden.

## Schritt 2: Den Schwellwert einstellen

Die eine Einstellung, die entscheidet, ob das funktioniert, ist die Helligkeit, die ein Pixel überschreiten muss. Raten Sie nicht - messen Sie das Bild:

```
system/analyse-scene/input/input-image-address = "hdvisionsystems/lumiscan-cam-driver/camera1/output/image"
write system/analyse-scene/execute
read  system/analyse-scene/output/recommended-settings
read  system/analyse-scene/output/histogram
```

`recommended-settings` liefert Ihnen einen Schwellwert, welche Seite das Teil ist und ob Löcher gefüllt werden sollen. Mit `histogram` prüfen Sie das: Der Schwellwert sollte im Tal zwischen dem Buckel des Teils und dem des Hintergrunds liegen. Zwei Buckel mit einer Lücke bedeuten, dass sich das Bild sauber trennt; ein Buckel bedeutet, dass kein Schwellwert es rettet und stattdessen die Beleuchtung korrigiert werden muss.

Setzen Sie ihn dann am Modul:

```
module-1/detect-area/input/method-specific/fixed/level = 128
write module-1/detect-area/execute
```

Sind die Teile dunkler als der Hintergrund, ergänzen Sie:

```
module-1/detect-area/input/detect-dark = true
```

## Schritt 3: Kein Rauschen mehr zählen

Sehen Sie sich die kleinsten Einträge in `blobs` an. Die App meldet jede Region, die sie getrennt hat - es gibt kein Flächenfenster, das sich anheben ließe -, Rauschen und Staub werden daher an einer von zwei Stellen behandelt:

- **Am Schwellwert.** `method-specific/fixed/level` so weit anzuheben, bis das Rauschen den Schwellwert nicht mehr überschreitet, ist die bessere Lösung, weil das Finden dieser Regionen dann nichts mehr kostet.
- **In Ihrem Steuerungsprogramm.** Ignorieren Sie jeden `blobs[]`-Eintrag, dessen `area` unter dem liegt, was ein Teil sein kann. Ein Viertel der Fläche des kleinsten Teils, das Sie interessiert, ist ein guter Ausgangspunkt. Diese Entscheidung liegt bei Ihnen: Nur Sie wissen, was ein Teil ist.

## Schritt 4: Die Zahl gegen etwas Bekanntes prüfen

Messen Sie ein Teil, dessen echte Fläche Sie kennen - oder zählen Sie seine Pixel einmal in einem Bildbetrachter -, und vergleichen Sie sie mit `blobs[0].area`. Beide sollten eng übereinstimmen. Ist die Messung durchgehend zu niedrig, schneidet der Schwellwert in das Teil hinein: Senken Sie `method-specific/fixed/level`, und probieren Sie `detect-dark`, wenn das Teil das dunklere von beiden ist.

## Schritt 5: Dauerhaft machen

```
system/save-module-inputs/input/module-id = module-1
write system/save-module-inputs/execute
write system/save-current-modules/execute
```

Beide sollten `1` melden. Das Modul und seine Einstellungen überstehen jetzt einen Neustart.

## Schritt 6: Aus einem Steuerungsprogramm ausführen

Pro Zyklus:

1. Schreiben Sie auf `module-1/detect-area/execute`.
2. Lesen Sie `module-1/detect-area/output/status-code`.
3. Ist er negativ, ist der Durchlauf fehlgeschlagen - lesen Sie `output/status-text` und verwenden Sie das Ergebnis nicht.
4. Ist er `1`, lesen Sie `output/result` und reagieren Sie auf `total_area`, oder auf `blob_count` für eine Anwesenheitsprüfung.

Lesen Sie die Ausgaben, **bevor** Sie das nächste `execute` auslösen: Ein Durchlauf leert sie, sobald er beginnt.

## Wenn die Zahlen falsch aussehen

Probleme sind Schritt für Schritt unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html) beschrieben:

- [Die gemessene Fläche ist größer oder kleiner als das Teil](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#faq-area-wrong) - viel größer, durchgehend zu klein oder ein Teil mit einem Loch
- [Viele winzige Regionen werden gemeldet](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#faq-tiny-regions)
- [Ein Teil wird als mehrere Regionen gemeldet](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#faq-part-split)
- [Nichts wird gefunden, oder das Ergebnis ist leer](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#faq-nothing-found)
- [Der Messwert driftet mit der Beleuchtung, oder kein Schwellwert funktioniert](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#faq-reading-drifts)

# FAQ – LumiScan Area Detector

URL: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/faq.html

Kurze Antworten auf häufige Fragen zu LumiScan Area Detector. Jeder Eintrag verweist auf die Seite mit den Details.

> [!TIP]
> Jeder Eintrag hat einen festen Anker (zum Beispiel `#faq-pixel-formats`). Probleme, Fehlermeldungen und Statuscodes sind Schritt für Schritt unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html) beschrieben.

## Voraussetzungen und Einrichtung

### Welche Bildquelle braucht der Area Detector? {#faq-image-source}

- **Antwort:** Die Anwendung kommuniziert nicht selbst mit einer Kamera. Sie liest den Bildknoten einer anderen Anwendung, die auf **demselben Gerät** läuft - demselben ctrlX CORE oder ctrlX IPC oder demselben PC (ein Zugriff auf einen entfernten Data Layer wird nicht unterstützt), normalerweise LumiScan Cam Driver, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`. Jede Anwendung funktioniert, wenn ihr Bildknoten `data` (rohe, unkomprimierte uint8-Pixeldaten), `width`, `height` und `pixel-type` (Name des GenICam-Pixelformats) bereitstellt. Ein Referenzbild ist nicht nötig.
- **Mehr:** [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/requirements.html), [Beschreibung](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/description.html)

### Welche Pixelformate werden unterstützt? {#faq-pixel-formats}

- **Antwort:** `Mono8`, `Mono12`, `RGB8`, `RGB12`, `BGR8`, `BGR12`, `BayerGR8`, `BayerGR12`, `BayerRG8` und `BayerRG12`. Bayer-Bilder werden vor der Erkennung in Farbe umgewandelt und 12-Bit-Bilder auf 8 Bit herunterskaliert; ein Schwellwert, der auf einem Format eingestellt wurde, gilt also auch für ein anderes. Jedes andere Pixelformat wird mit Statuscode `-3` abgelehnt.
- **Mehr:** [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/requirements.html)

## Erkennen und Messen

### Wie führe ich eine Erkennung aus und lese das Ergebnis? {#faq-first-run}

- **Antwort:** Setzen Sie `<module>/detect-area/input/input-image-address`, schreiben Sie auf `<module>/detect-area/execute` (ein blockierender Aufruf) und prüfen Sie, dass `output/status-code` `1` ist. Lesen Sie dann `output/result`: `blobs` ist nach Fläche sortiert, `blobs[0]` ist also die größte Region; jeder Blob hat seinen Mittelpunkt `x`, `y`, seine `area` in Pixeln (gezählt, nie aus einer angepassten Form abgeleitet), sein `label` und ein umschließendes Rechteck. `blob_count` gibt die Anzahl der Regionen an und `total_area` die Summe, die bei Bedeckungs-, Verunreinigungs- und Füllstandsprüfungen meist die Zahl ist, auf die Sie reagieren.
- **Mehr:** [Flächen erkennen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/detecting-areas.html), [Anleitung: Teilefläche aus einem Kamerabild messen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/how-tos/measure-part-area-from-a-camera-image.html)

### Wie finde ich den richtigen Schwellwert? {#faq-commission-level}

- **Antwort:** Messen Sie das Bild, statt zu raten. `FIXED` ist in dieser Version das einzige `input/method`; alles andere wird abgelehnt.
  - Setzen Sie `system/analyse-scene/input/input-image-address` und schreiben Sie auf `system/analyse-scene/execute`.
  - Lesen Sie `output/recommended-settings`: `node=value`-Zeilen relativ zum `detect-area/input/` eines Moduls, mit dem Schwellwert, der Angabe, welche Seite das Teil ist, und ob Löcher gefüllt werden sollen. Nichts wird für Sie geschrieben.
  - Prüfen Sie den Rat mit `output/histogram`: Der Schwellwert sollte im Tal zwischen dem Buckel des Teils und dem des Hintergrunds liegen. Ein Buckel bedeutet, dass kein Schwellwert funktionieren wird und die Beleuchtung korrigiert werden muss.
  - Setzen Sie `<module>/detect-area/input/method-specific/fixed/level` (0-255, Standard `128`).
- **Mehr:** [Eine Szene analysieren](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/analysing-a-scene.html), [Die Erkennung abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/tuning-the-detection.html)

### Welche Vorverarbeitungsfilter gibt es, und was brauchen sie? {#faq-preprocessing}

- **Antwort:** `input/preprocess/method` wendet vor der Erkennung einen Filter an: `NONE` (Standard), `LOG` (Laplacian of Gaussian), `DOG` (Difference of Gaussians; `sigma-first` muss sich von `sigma-second` unterscheiden) oder `DOH` (Determinant of Hessian; `kernel-size` muss 1, 3, 5 oder 7 sein). Nur die Parameter der gewählten Methode werden gelesen und geprüft. Alle drei normalisieren ihre Ausgabe, der Schwellwert muss nach dem Einschalten eines Filters also eventuell neu gesetzt werden.
- **Mehr:** [Flächen erkennen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/detecting-areas.html), [Die Erkennung abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/tuning-the-detection.html)

### Wie finde ich die Pixel, die zu einer gemeldeten Region gehören? {#faq-label-image}

- **Antwort:** Jeder Durchlauf veröffentlicht `output/blob-labels`, einen gewöhnlichen Bildknoten (`data`, `width`, `height`, `pixel-type`) in `Mono16`, mit einer Regionsnummer pro Pixel und `0` für Hintergrund. Die Nummern sind die `blobs[].label`-Werte in `output/result`; alle Pixel, die das Label eines Blobs enthalten, sind also diese Region; eine Binärmaske ist `labels > 0`. Das Bild umfasst den ganzen Frame in der Größe des Eingabebildes, und Labels werden nicht neu nummeriert. Es wird geleert, wenn der nächste Durchlauf beginnt.
- **Mehr:** [Das Label-Bild](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/the-label-image.html)

### Wie schränke ich die Suche ein oder mache sie schneller? {#faq-crop-speed}

- **Antwort:** Setzen Sie `input/crop/` (`startX`, `startY`, `width`, `height`); eine Breite oder Höhe von null reicht bis zum rechten bzw. unteren Rand, lauter Nullen durchsuchen also das ganze Bild. Eine Region, die über einen Rand hinausreicht, wird abgelehnt und nicht beschnitten; die Meldung nennt die Eingabe und die Grenze, die sie verletzt hat. Für mehr Geschwindigkeit schränken Sie zuerst den Bereich ein und erhöhen dann den Schwellwert, damit Rauschen und Staub den Schwellwert nicht mehr überschreiten.
- **Mehr:** [Flächen erkennen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/detecting-areas.html), [Die Erkennung abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/tuning-the-detection.html)

### Wie erkenne ich Flächen auf jedem Frame eines Kamera-Streams? {#faq-stream}

- **Antwort:** Lassen Sie ein Modul den Stream des Cam Driver abonnieren (experimentell): Schreiben Sie den Stream-Ordner der Kamera, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`, auf `<module>/control/subscribe/input/address`, setzen Sie `control/subscribe/input/enable` auf `true` und schreiben Sie auf `control/subscribe/execute`. Jeder Frame wird mit den Eingaben von `detect-area` durchsucht, und ein Ergebnis pro Frame wird auf `control/subscribe/output/stream/result` veröffentlicht. Das Label-Bild wird nicht gestreamt. Um das neueste Ergebnis als einfaches `detect-area/output/result` zu lesen, setzen Sie `control/subscribe/input/keep-latest-output` auf `true`.
- **Mehr:** [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), [Streams](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html)

## Statuscodes und Fehler

### Wie erkenne ich, ob eine Erkennung erfolgreich war, und wo steht der Grund für einen Fehlschlag? {#faq-status-codes}

- **Antwort:** Prüfen Sie das Vorzeichen von `output/status-code`: Größer als 0 ist Erfolg, `0` bedeutet, dass die Operation seit dem Start der Anwendung nicht ausgeführt wurde, kleiner als 0 bedeutet, dass sie fehlgeschlagen ist und nichts erzeugt hat; verwenden Sie das Ergebnis dann nicht. Der Grund steht auf `output/status-text`. Ein fehlgeschlagener Schreibvorgang auf `execute` antwortet nur mit einem Statuscode (über REST mit einem bloßen `400`), lesen Sie also anschließend `output/status-text`; der Text steht auch im Protokoll der Anwendung: auf ctrlX OS im ctrlX Logbook oder `journalctl`, auf einem PC in der Konsolenausgabe der Anwendung.
- **Mehr:** [Eine Methode ausführen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/execute-a-method.html), [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/execution-status.html)

## Fehlerbehebung {#troubleshooting}

Probleme und Fehlermeldungen sind Schritt für Schritt unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html) beschrieben:

- [Statuscode `-1` (belegt)](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#faq-status-minus-1)
- [Statuscode `-2` (ungültige Eingabe)](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#ts-status-minus-2)
- [Statuscode `-3` (Bild konnte nicht gelesen werden)](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#faq-status-minus-3)
- [Die Ausschnittsregion passt nicht in das Bild](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#ts-crop-does-not-fit)
- [Statuscode `-6` (Schreiben fehlgeschlagen)](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#ts-status-minus-6)
- [Nichts wird gefunden, oder das Ergebnis ist leer](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#faq-nothing-found)
- [Die gemessene Fläche ist größer oder kleiner als das Teil](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#faq-area-wrong)
- [Viele winzige Regionen werden gemeldet](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#faq-tiny-regions)
- [Ein Teil wird als mehrere Regionen gemeldet](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#faq-part-split)
- [Der Messwert driftet mit der Beleuchtung, oder kein Schwellwert funktioniert](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#faq-reading-drifts)
- [`output/result` ist leer, obwohl die Erkennung gerade eben funktioniert hat](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#faq-result-empty-next-run)
- [Der Bild-Stream liefert keine Ergebnisse](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#ts-stream-no-results)
- [Meine Einstellungen oder Module sind nach einem Neustart weg](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#faq-settings-lost)
- [Die Anwendung beendet sich kurz nach dem Start](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#ts-app-stops-after-start)
- [Statuscode `-11` (Lizenz nicht verfügbar)](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#ts-licence-unavailable)

## Module, Lizenzierung und Support

### Wo liegen die Einstellungsdateien? {#faq-settings-files}

- **Antwort:** Im Konfigurationsverzeichnis der Anwendung, `lumiscan-area-detector/`: die Anwendungs-Einstellungsdatei `lumiscan-area-detector.json` und eine `<module-id>.json` pro gespeichertem Modul.
  - Auf ctrlX OS: in der aktiven Solution, `/var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-area-detector`.
  - Auf einem PC (Windows): `%APP_RESOURCE_DIR%\etc\lumiscan-area-detector`; ohne `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-areadetect\etc\lumiscan-area-detector`.
  - Auf einem PC schreibt `lumiscan-areadetect --generate-settings <folder>` ein Beispiel beider Dateien, mit ihren JSON-Schemas, in einen Ordner Ihrer Wahl.
- **Mehr:** [Data-Layer-Referenz](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/datalayer-reference.html#configuration-file), [Wo die Dateien liegen](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html#files)

### Welche Lizenz brauche ich, und wie viele Module deckt sie ab? {#faq-licence}

- **Antwort:** Eine Lizenz deckt zehn Module ab; das elfte Modul belegt eine zweite Lizenz desselben Schlüssels, und ein Modul wird mit Status `-11` abgelehnt, wenn keine Lizenz auf dem Gerät es abdeckt. Bezugswege:
  - Bei HD Vision Systems gekauft: Die Lizenz liegt auf einem LumiScan Key (Windows 11 oder Ubuntu 24.04). Pro Gerät, auf dem die Software gleichzeitig läuft, wird ein LumiScan Key benötigt; Keys können zwischen Geräten getauscht werden.
  - Im ctrlX Store für Windows 11 gekauft: ctrlX WORKS plus ein LumiScan Key.
  - Im ctrlX Store für ctrlX OS (ctrlX CORE oder IPC) gekauft: eine ctrlX-Lizenz, kein Key.
- **Mehr:** [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/requirements.html#licence), [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/module-management.html), [FAQ zur Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/faq.html)

### Wo finde ich weitere Antworten oder Support? {#faq-support}

- **Antwort:** Siehe die [LumiScan-FAQ](https://docs.hdvisionsystems.com/de/faq.html) der gesamten Dokumentation. Wenden Sie sich an den Customer Success von HD Vision Systems unter [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com) oder +49 6221 6721905; für Lizenzen an [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).
- **Mehr:** [FAQ zur Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/faq.html)

# Fehlerbehebung – LumiScan Area Detector

URL: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html

Diese Seite beschreibt Probleme und Fehlermeldungen von LumiScan Area Detector, nach Kategorien geordnet. Beginnen Sie mit den [allgemeinen Prüfungen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#general-checks) und suchen Sie dann unten Ihr Symptom: Jedes Problem nennt die Symptome, die möglichen Ursachen, eine Diagnose und die Lösung. Probleme des Data Layer selbst sind in der [Fehlerbehebung des Data Layer](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html) beschrieben, Lizenzprobleme in der [Fehlerbehebung der Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/troubleshooting.html).

## Allgemeine Prüfungen {#general-checks}

1. **Prüfen Sie den Statuscode.** Lesen Sie `output/status-code` der Operation, die fehlgeschlagen ist. Erwartet: `1`. Ein Wert größer als 0 bedeutet Erfolg, `0` bedeutet, dass die Operation seit dem Start der Anwendung nicht ausgeführt wurde, und ein Wert kleiner als 0 bedeutet, dass sie fehlgeschlagen ist und nichts erzeugt hat; verwenden Sie das Ergebnis dann nicht. Die Codes stehen in [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/execution-status.html).
2. **Lesen Sie den Statustext.** Lesen Sie `output/status-text` derselben Operation. Er beginnt mit `ok:` oder `error:` und nennt den fehlerhaften Wert, wenn es einen gibt. Ein fehlgeschlagener Schreibvorgang auf `execute` antwortet nur mit einem Statuscode (über REST mit einem bloßen `400`); der Grund steht also nur auf `output/status-text`.
3. **Lesen Sie das Protokoll der Anwendung.** Es enthält denselben Text, mit einer eigenen Warnzeile für jede ungültige Eingabe: auf ctrlX OS über das ctrlX Logbook oder `journalctl`, auf einem PC über die Konsolenausgabe der Anwendung. Wie viel protokolliert wird, legt `logLevel` im Block `system` von `lumiscan-area-detector.json` fest (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` oder `OFF`). Der Wert wird beim Start gelesen; starten Sie die Anwendung nach einer Änderung also neu. Siehe [Konfigurationsdatei](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/datalayer-reference.html#configuration-file).
4. **Prüfen Sie die Bildquelle.** Die Kameraanwendung, normalerweise LumiScan Cam Driver, muss auf **demselben Gerät** laufen - demselben ctrlX CORE oder ctrlX IPC oder demselben PC - und ein Bild aufgenommen haben. Ein Zugriff auf einen entfernten Data Layer wird nicht unterstützt. Erwartet: Der in `input/input-image-address` genannte Knoten stellt `data`, `width`, `height` und `pixel-type` bereit.
5. **Prüfen Sie die Reihenfolge der Aufrufe.** Ein Modul führt jeweils eine Operation aus, und jeder Durchlauf leert beim Start seine Ausgaben. Erwartet: Ihr Programm wartet, bis `execute` zurückkehrt, liest die Ausgaben und löst erst dann den nächsten Durchlauf aus.
6. **Prüfen Sie die Lizenz (ctrlX OS).** Erwartet: Die Anwendung läuft nach dem Start weiter. Ohne Lizenz beendet sie sich kurz nach dem Start; siehe [Problem: Die Anwendung beendet sich kurz nach dem Start](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#ts-app-stops-after-start).

Das Konfigurationsverzeichnis enthält `lumiscan-area-detector.json`, die Moduldateien `<module-id>.json` und `settings-history/`:

| Plattform | Konfigurationsverzeichnis |
| --- | --- |
| ctrlX OS | `/var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-area-detector`, Teil der aktiven Solution |
| PC (Windows) | `%APP_RESOURCE_DIR%\etc\lumiscan-area-detector`; ohne `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-areadetect\etc\lumiscan-area-detector` |

## Statuscodes und Fehlermeldungen {#ts-status-codes}

### Problem: Statuscode `-1` (belegt) {#faq-status-minus-1}

**Symptome**

`output/status-code` von `detect-area` ist `-1`. Der Schreibvorgang auf `execute` antwortet mit `DL_TOO_MANY_OPERATIONS` (auf einem PC `TooManyOperations`). Es wurde nichts getan, und `output/result` und `output/blob-labels` behalten ihre Werte. Bei einer streamenden Kamera passiert das oft. Auch `system/remove-module` kann mit `-1` (belegt) antworten.

**Mögliche Ursachen**

- Eine andere Operation desselben Moduls lief noch. Der Aufruf wird nicht in eine Warteschlange gestellt; er kehrt sofort zurück und tut nichts.
- Der Bild-Stream des Moduls durchsucht gerade einen Frame. Der Stream und `detect-area` laufen auf einem Modul nie gleichzeitig.

**Diagnose**

1. Prüfen Sie in Ihrem Programm, ob es erneut auf `execute` desselben Moduls schreibt, bevor der vorherige Schreibvorgang zurückgekehrt ist. Erwartet: ein Aufruf pro Modul zur Zeit.
2. Lesen Sie `<module-id>/control/subscribe/output/stream/active`. `true` bedeutet, dass der Stream dieses Moduls läuft.

**Lösung**

- **Wenn eine andere Operation noch lief:** Warten Sie, bis das laufende `execute` zurückkehrt, und rufen Sie die Methode dann erneut auf. Die Sperre gilt pro Modul, andere Module werden also nicht aufgehalten. `system/analyse-scene` hat eine eigene Sperre und blockiert die Erkennung nicht.

- **Wenn der Stream des Moduls läuft:**

  a. Stoppen Sie den Stream, bevor Sie die Methode aufrufen: Setzen Sie `control/subscribe/input/enable` auf `false` und schreiben Sie auf `control/subscribe/execute`. Oder rufen Sie die Methode erneut auf.

  b. Um stattdessen das neueste Ergebnis des Streams zu lesen, setzen Sie `control/subscribe/input/keep-latest-output` auf `true` und lesen `detect-area/output/result`.

- **Wenn `system/remove-module` mit belegt antwortet:** Stoppen Sie zuerst den Stream des Moduls. Das Entfernen eines Moduls stoppt seinen Stream.

Siehe [Eine Methode ausführen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/execute-a-method.html) und [detect-area, während der Stream läuft](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#while-streaming).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit der Modul-ID, der Antwort des Schreibvorgangs auf `execute` und dem Wert von `control/subscribe/output/stream/active`.

### Problem: Statuscode `-2` (ungültige Eingabe) {#ts-status-minus-2}

**Symptome**

`output/status-code` von `detect-area` oder `system/analyse-scene` ist `-2`. `output/status-text` beginnt mit `error:` und nennt den fehlerhaften Wert. Sind mehrere Eingaben falsch, erhält jede eine eigene Warnzeile im Protokoll.

**Mögliche Ursachen**

- Eine erforderliche Eingabe ist leer.
- `input/method` ist nicht `FIXED`. `FIXED` ist die einzige Methode, die diese Version bietet; alles andere wird abgelehnt.
- `input/preprocess/method` ist unbekannt. Akzeptiert werden `NONE`, `LOG`, `DOG` und `DOH`.
- Ein Parameter liegt außerhalb seines Bereichs, zum Beispiel `input/method-specific/fixed/level` außerhalb von 0-255, `input/preprocess/dog/sigma-first` gleich `sigma-second`, `input/preprocess/doh/kernel-size` anders als 1, 3, 5 oder 7, oder `system/analyse-scene/input/histogram-bins` außerhalb von 2-256. Nur die Parameter der gewählten Vorverarbeitungsmethode werden geprüft.
- Die Bildadresse zeigt auf diese Anwendung selbst.

**Diagnose**

1. Lesen Sie `output/status-text` der Operation. Erwartet: Er nennt die fehlerhafte Eingabe und ihren Wert.
2. Lesen Sie das Protokoll der Anwendung. Jede ungültige Eingabe hat eine eigene Warnzeile.
3. Vergleichen Sie die Eingaben mit den Bereichen in der [Data-Layer-Referenz](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/datalayer-reference.html).

**Lösung**

- **Wenn eine erforderliche Eingabe leer ist:** Setzen Sie sie.
- **Wenn `input/method` nicht `FIXED` ist:** Setzen Sie es auf `FIXED`.
- **Wenn `input/preprocess/method` unbekannt ist:** Setzen Sie es auf `NONE`, `LOG`, `DOG` oder `DOH`.
- **Wenn ein Parameter außerhalb seines Bereichs liegt:** Korrigieren Sie ihn auf einen Wert innerhalb des Bereichs, den die Data-Layer-Referenz nennt.
- **Wenn die Bildadresse auf diese Anwendung zeigt:** Setzen Sie `input/input-image-address` auf den Bildknoten der Kameraanwendung, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`.

Führen Sie die Operation dann erneut aus. Erwartet: `output/status-code` ist `1`. Siehe [Ausführungsstatus](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/execution-status.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit dem Inhalt von `output/status-text`.

### Problem: Statuscode `-3` (Bild konnte nicht gelesen werden) {#faq-status-minus-3}

**Symptome**

`output/status-code` von `detect-area` oder `system/analyse-scene` ist `-3`.

**Mögliche Ursachen**

- Die Kameraanwendung läuft nicht, oder sie läuft auf einem anderen Gerät.
- Die Kameraanwendung hat noch kein Bild aufgenommen.
- Die Adresse in `input/input-image-address` ist falsch.
- Der Bildknoten unter der Adresse fehlt, ist leer oder inkonsistent.
- Das Bild verwendet ein nicht unterstütztes Pixelformat. Unterstützt werden `Mono8`, `Mono12`, `RGB8`, `RGB12`, `BGR8`, `BGR12`, `BayerGR8`, `BayerGR12`, `BayerRG8` und `BayerRG12`.

**Diagnose**

1. Prüfen Sie, ob die Kameraanwendung, normalerweise LumiScan Cam Driver, auf demselben Gerät läuft. Erwartet: Sie läuft auf demselben ctrlX CORE oder ctrlX IPC oder auf demselben PC.
2. Vergleichen Sie `input/input-image-address` mit der Adresse des Bildknotens der Kamera, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`. Erwartet: identisch. `system/analyse-scene` hat einen eigenen Adressknoten, nicht den eines Moduls.
3. Lesen Sie `width`, `height` und `pixel-type` des Bildknotens. Erwartet: Werte größer als 0 und ein `pixel-type` aus der obigen Liste.

**Lösung**

- **Wenn die Kameraanwendung nicht läuft:** Starten Sie sie auf demselben Gerät und nehmen Sie ein Bild auf.
- **Wenn noch kein Bild aufgenommen wurde:** Nehmen Sie in der Kameraanwendung ein Bild auf.
- **Wenn die Adresse falsch ist:** Korrigieren Sie `input/input-image-address`.
- **Wenn das Pixelformat nicht unterstützt wird:** Verwenden Sie eines der unterstützten Pixelformate, siehe [Voraussetzungen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/requirements.html).

Führen Sie die Operation dann erneut aus. Erwartet: `output/status-code` ist `1`.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit dem Inhalt von `output/status-text`, der Bildadresse und dem `pixel-type` des Bildknotens.

### Problem: Die Ausschnittsregion passt nicht in das Bild {#ts-crop-does-not-fit}

**Symptome**

`detect-area` schlägt mit einem negativen Statuscode fehl, und `output/status-text` nennt die Eingabe und die Grenze, die sie verletzt hat, zum Beispiel:

```
error: crop/startX + crop/width (100 + 900 = 1000) exceeds the image width 640
```

Im Bild-Stream schlägt der Frame fehl, und `control/subscribe/output/stream/last-failure` nennt eine Ausschnittsregion, die nicht in den Frame passt.

**Mögliche Ursachen**

- Die Region reicht über einen Rand des Bildes hinaus. Eine Region, die über einen Rand hinausreicht, wird abgelehnt und nicht beschnitten.

**Diagnose**

1. Lesen Sie die Bildgröße aus der Meldung ab, oder `width` und `height` des Bildknotens.
2. Addieren Sie `input/crop/startX` und `input/crop/width` sowie `input/crop/startY` und `input/crop/height`. Erwartet: Die Summen sind nicht größer als die Bildbreite und die Bildhöhe.

**Lösung**

- Korrigieren Sie `input/crop/startX`, `startY`, `width` oder `height`, sodass die Region in das Bild passt. Eine Breite oder Höhe von null reicht bis zum rechten bzw. unteren Rand; lauter Nullen durchsuchen also das ganze Bild.

Führen Sie `detect-area` dann erneut aus. Erwartet: `output/status-code` ist `1`. Siehe [Flächen erkennen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/detecting-areas.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit dem Inhalt von `output/status-text` und den vier Werten unter `input/crop/`.

### Problem: Statuscode `-6` (Schreiben fehlgeschlagen) {#ts-status-minus-6}

**Symptome**

`output/status-code` von `system/save-module-inputs` ist `-6`.

**Mögliche Ursachen**

- Eine Datei konnte nicht geschrieben werden - meist ein Berechtigungsproblem oder ein voller Datenträger.

**Diagnose**

1. Lesen Sie `output/status-text` der Operation. Erwartet: Er nennt die Datei, die nicht geschrieben werden konnte.
2. Lesen Sie das Protokoll der Anwendung zum Zeitpunkt des Aufrufs.
3. Prüfen Sie das Konfigurationsverzeichnis (siehe [Allgemeine Prüfungen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#general-checks)). Erwartet: Es existiert, und die Anwendung kann hineinschreiben.

**Lösung**

- **Wenn es ein Berechtigungsproblem ist:** Machen Sie das Konfigurationsverzeichnis für die Anwendung beschreibbar.
- **Wenn der Datenträger voll ist:** Geben Sie auf dem Gerät Speicherplatz frei.

Führen Sie die Operation dann erneut aus. Erwartet: `output/status-code` ist `1`.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit dem Inhalt von `output/status-text`.

## Erkennungsergebnisse {#ts-results}

### Problem: Nichts wird gefunden, oder das Ergebnis ist leer {#faq-nothing-found}

**Symptome**

`output/status-code` von `detect-area` ist `1`, aber `blobs` in `output/result` ist leer, und `blob_count` ist `0`.

**Mögliche Ursachen**

Eine leere `blobs`-Liste mit Statuscode `1` bedeutet, dass keine Regionen zutrafen, sonst nichts. Jeder andere Grund, aus dem ein Durchlauf nichts erzeugen könnte, wird als negativer Statuscode gemeldet. Sind die Teile vorhanden:

- `input/detect-dark` passt nicht zu der Seite, auf der die Teile liegen. Setzen Sie es auf `true`, wenn die Teile dunkler als der Hintergrund sind.
- Der Schwellwert `input/method-specific/fixed/level` liegt über jedem Pixel im Teil.

**Diagnose**

1. Lesen Sie `output/status-code`. Erwartet: `1`. Ist er negativ, ist der Durchlauf fehlgeschlagen: Lesen Sie `output/status-text` und sehen Sie sich die Einträge unter [Statuscodes und Fehlermeldungen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#ts-status-codes) an.
2. Lesen Sie `input/detect-dark`. Erwartet: `true`, wenn die Teile dunkler als der Hintergrund sind, `false`, wenn sie heller sind.
3. Führen Sie `system/analyse-scene` auf demselben Bild aus: Setzen Sie `system/analyse-scene/input/input-image-address` und schreiben Sie auf `system/analyse-scene/execute`. Lesen Sie `output/parts-are-dark` und `output/recommended-settings`. Erwartet: `input/detect-dark` und der Schwellwert des Moduls entsprechen dem Rat.
4. Prüfen Sie den Rat mit `output/histogram`. Erwartet: Der Schwellwert liegt im Tal zwischen dem Buckel des Teils und dem des Hintergrunds.

**Lösung**

- **Wenn `input/detect-dark` falsch ist:** Setzen Sie es auf `true`, wenn die Teile dunkler als der Hintergrund sind.
- **Wenn der Schwellwert über jedem Pixel im Teil liegt:** Setzen Sie `input/method-specific/fixed/level` auf den Schwellwert, den `output/recommended-settings` angibt. Nichts wird für Sie geschrieben.
- **Wenn das Histogramm einen einzigen Buckel zeigt:** Kein Schwellwert wird funktionieren; korrigieren Sie die Beleuchtung, siehe [Problem: Der Messwert driftet mit der Beleuchtung, oder kein Schwellwert funktioniert](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#faq-reading-drifts).

Siehe [Eine Szene analysieren](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/analysing-a-scene.html) und [Flächen erkennen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/detecting-areas.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit den Eingaben von `detect-area` und den Ausgaben von `system/analyse-scene`.

### Problem: Die gemessene Fläche ist größer oder kleiner als das Teil {#faq-area-wrong}

**Symptome**

`blobs[0].area` oder `total_area` weicht von der echten Fläche des Teils ab: viel größer, durchgehend zu klein, oder ein Teil mit einem Loch wird als Ring gemessen.

**Mögliche Ursachen**

- Die Fläche ist viel größer als das Teil: Der Schwellwert lässt Hintergrund durch.
- Die Fläche ist durchgehend zu klein: Der Schwellwert beschneidet den Rand des Teils.
- `input/detect-dark` passt nicht zu der Seite, auf der das Teil liegt.
- Das Teil hat ein Loch, und `input/fill-holes` ist aus. Eine Region wird als die Pixel gezählt, die den Schwellwert passiert haben; ein Loch wird also nicht mitgezählt, es sei denn, `fill-holes` ist gesetzt.

**Diagnose**

1. Messen Sie ein Teil, dessen echte Fläche Sie kennen, oder zählen Sie seine Pixel einmal in einem Bildbetrachter, und vergleichen Sie das mit `blobs[0].area`. Erwartet: Beide stimmen eng überein.
2. Sehen Sie sich die Region in `output/blob-labels` an: Jedes Pixel, das das `blobs[].label` der Region enthält, wurde gezählt. Im Cockpit wird jede Region in einer eigenen Farbe über dem Kamerabild eingefärbt.
3. Lesen Sie `input/detect-dark` und `input/fill-holes`.

**Lösung**

- **Wenn der Schwellwert Hintergrund durchlässt:** Prüfen Sie `input/detect-dark`, und stellen Sie den Schwellwert dann mit `system/analyse-scene` neu ein, siehe [Problem: Nichts wird gefunden, oder das Ergebnis ist leer](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#faq-nothing-found).
- **Wenn die Fläche durchgehend zu klein ist:** Senken Sie `input/method-specific/fixed/level`, und probieren Sie `input/detect-dark`, wenn das Teil das dunklere von beiden ist.
- **Wenn ein Teil mit einem Loch als Ring gemessen wird:** Schalten Sie `input/fill-holes` ein, um die Form zu messen, die sein Umriss einschließt. Eine Unterlegscheibe wird dann als Scheibe gemessen.

Siehe [Die Erkennung abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/tuning-the-detection.html) und [Anleitung: Teilefläche aus einem Kamerabild messen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/how-tos/measure-part-area-from-a-camera-image.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit den Eingaben von `detect-area`, `output/result` und der erwarteten Fläche.

### Problem: Viele winzige Regionen werden gemeldet {#faq-tiny-regions}

**Symptome**

`blob_count` ist viel höher als die Zahl der Teile, und `blobs` enthält viele Einträge mit einer kleinen `area`.

**Mögliche Ursachen**

- Sensorrauschen und Staub überschreiten den Schwellwert. Die Anwendung meldet jede Region, die sie getrennt hat; ein Flächenfenster gibt es nicht.

**Diagnose**

1. Sehen Sie sich die kleinsten Einträge in `blobs` an. Erwartet: Ihre `area` liegt weit unter der Fläche eines Teils.
2. Sehen Sie sich diese Regionen in `output/blob-labels` an.

**Lösung**

Behandeln Sie Rauschen und Staub an einer von zwei Stellen:

- **Am Schwellwert:** Erhöhen Sie `input/method-specific/fixed/level`, bis das Rauschen den Schwellwert nicht mehr überschreitet. Das ist die bessere Lösung, weil das Finden dieser Regionen dann nichts mehr kostet.
- **In Ihrem Steuerungsprogramm:** Ignorieren Sie `blobs[]`-Einträge, deren `area` unter dem liegt, was ein Teil sein kann. Ein Viertel der Fläche des kleinsten Teils, das Sie interessiert, ist ein guter Ausgangspunkt.

Siehe [Die Erkennung abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/tuning-the-detection.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit den Eingaben von `detect-area` und `output/result`.

### Problem: Ein Teil wird als mehrere Regionen gemeldet {#faq-part-split}

**Symptome**

Ein Teil erscheint als mehrere Einträge in `blobs`; in `output/blob-labels` tragen seine Pixel mehrere Labels.

**Mögliche Ursachen**

- Das Teil wird durch einen Schatten oder ein Glanzlicht geteilt.

**Diagnose**

1. Sehen Sie sich das Teil in `output/blob-labels` an. Im Cockpit erscheinen benachbarte Regionen in verschiedenen Farben.
2. Vergleichen Sie die Teilung mit dem Kamerabild. Erwartet: Ein Schatten oder ein Glanzlicht verläuft dort, wo das Teil geteilt ist.

**Lösung**

- Probieren Sie die Vorverarbeitung mit `input/preprocess/method` (`LOG`, `DOG` oder `DOH`) oder `input/detect-dark`. Alle drei Filter normalisieren ihre Ausgabe; prüfen Sie den Schwellwert also nach dem Einschalten eines Filters erneut.

Siehe [Flächen erkennen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/detecting-areas.html) und [Die Erkennung abstimmen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/tuning-the-detection.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit den Eingaben von `detect-area` und `output/result`.

### Problem: Der Messwert driftet mit der Beleuchtung, oder kein Schwellwert funktioniert {#faq-reading-drifts}

**Symptome**

Die gemessene Fläche ändert sich, wenn sich die Beleuchtung ändert, stabilisiert sich nicht, oder kein Schwellwert trennt die Teile vom Hintergrund.

**Mögliche Ursachen**

- Das Bild ist spröde: `system/analyse-scene/output/area-sensitivity` liegt über `0.05`, ein Grauwert kostet also 5 % der gemessenen Fläche, und ein fester Schwellwert ist nicht sicher einzustellen. Kein Wert in `detect-area/input/` behebt das; es wird an der Kamera behoben.
- Ungleichmäßige Beleuchtung: Das Licht variiert um mehr als etwa ein Drittel des Abstands zwischen Teil und Hintergrund.
- Die Merkmale sind zu fein: unter etwa 8 px.
- Die Kanten sind weich (Defokussierung, Bewegungsunschärfe, Sensorrauschen bei hoher Verstärkung), oder der Kontrast ist gering.

**Diagnose**

1. Führen Sie `system/analyse-scene` auf dem Bild aus und lesen Sie `output/area-sensitivity`. Erwartet: deutlich unter `0.05` - `0.01` ist immer noch komfortabel; über `0.05` ist das Bild spröde.
2. Lesen Sie `output/findings`. Es sagt in Worten, welchen Hebel es getroffen hat, das Wichtigste zuerst.
3. Lesen Sie `output/illumination-spread`, gemessen am Abstand zwischen Teil und Hintergrund. Erwartet: weniger als etwa ein Drittel dieses Abstands.
4. Lesen Sie `output/feature-thickness`. Erwartet: etwa 8 px oder mehr.

**Lösung**

Arbeiten Sie die Hebel in dieser Reihenfolge ab:

- **Wenn die Beleuchtung ungleichmäßig ist:** Beheben Sie zuerst die ungleichmäßige Beleuchtung. Kein einzelner Schwellwert passt zum ganzen Bild.
- **Wenn die Merkmale unter etwa 8 px liegen:** Bringen Sie mehr Pixel auf das Teil: Vergrößerung, ein kürzerer Arbeitsabstand oder ein Sensor mit höherer Auflösung.
- **Wenn die Kanten weich sind:** Fokussieren Sie neu, verkürzen Sie die Belichtungszeit oder stellen Sie das Teil ruhig, senken Sie die Verstärkung und fügen Sie stattdessen Licht hinzu.
- **Wenn der Kontrast gering ist:** Ändern Sie die Beleuchtung: Durchlicht, ein anderer Winkel, ein Diffusor oder Polarisator, ein anderer Hintergrund.

Eine hohe `area-sensitivity` unter einer stabilen Lampe ist ein konstanter Versatz; sie kostet Sie nur etwas, wenn sich die Beleuchtung oder der Schwellwert bewegt. Siehe [Eine Szene analysieren](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/analysing-a-scene.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit allen Ausgaben von `system/analyse-scene`.

### Problem: `output/result` ist leer, obwohl die Erkennung gerade eben funktioniert hat {#faq-result-empty-next-run}

**Symptome**

Ein Durchlauf hat Regionen erzeugt, und kurz danach ist `output/result` (und `output/blob-labels`) leer.

**Mögliche Ursachen**

- Der nächste Durchlauf hat begonnen. Jeder Durchlauf leert seine eigenen Ausgaben, sobald er beginnt, bevor irgendetwas fehlschlagen kann. Ein Durchlauf, der aus irgendeinem Grund fehlschlägt, hinterlässt sie leer.
- Ein mit `-1` (belegt) abgelehnter Aufruf leert nichts; wurde der zweite Aufruf abgelehnt, ist das also nicht die Ursache.

**Diagnose**

1. Prüfen Sie die Reihenfolge der Aufrufe in Ihrem Programm. Erwartet: Es liest `output/result`, bevor es das nächste `execute` auslöst.
2. Lesen Sie `output/status-code` des letzten Durchlaufs. Ein negativer Wert bedeutet, dass dieser Durchlauf fehlgeschlagen ist und `output/result` leer hinterlassen hat.

**Lösung**

- **Wenn der nächste Durchlauf zu früh begonnen hat:** Warten Sie, bis `execute` zurückkehrt, lesen Sie die Ausgaben, und lösen Sie erst dann den nächsten Durchlauf aus.
- **Wenn der letzte Durchlauf fehlgeschlagen ist:** Folgen Sie dem Eintrag zu seinem Statuscode.

Siehe [Eine Methode ausführen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/execute-a-method.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit der Abfolge der Aufrufe Ihres Programms.

## Bild-Stream (experimentell) {#ts-stream}

### Problem: Der Bild-Stream liefert keine Ergebnisse {#ts-stream-no-results}

**Symptome**

`control/subscribe/output/stream/active` bleibt `false`, auf `control/subscribe/output/stream/result` treffen keine Ergebnisse ein, oder `control/subscribe/output/stream/statistics/failed-frames` wächst.

**Mögliche Ursachen**

- Nur die Eingaben wurden geschrieben. `control/subscribe/input/enable` allein zu schreiben startet nichts; `control/subscribe/execute` wendet die Eingaben an.
- `control/subscribe/execute` wurde abgelehnt (`DL_INVALID_VALUE`, auf einem PC `Rejected`): Stream-Modus ohne Adresse oder eine Warteschlangengröße außerhalb von `1` bis `64`.
- Die Einstellungsdatei `<module-id>.json` konnte nicht geschrieben werden, zum Beispiel weil sie kein gültiges JSON ist (`DL_CREATION_FAILED`, auf einem PC `CreationFailed`). Nichts wurde geändert.
- Der Stream des Cam Driver läuft nicht, es treffen also keine Frames ein.
- Die Quelle kann nicht abonniert werden. Das Modul versucht es alle 5 Sekunden erneut, solange der Stream läuft, und protokolliert den ersten Fehlschlag.
- Frames können nicht durchsucht werden, aus den Gründen, die `detect-area` in seinem `status-text` nennt.

**Diagnose**

1. Lesen Sie `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/publish/output/stream/active`. Erwartet: `true`.
2. Lesen Sie `setting/stream/enable` und `setting/stream/address` des Moduls. Erwartet: `true` und der Stream-Ordner der Kamera, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`. Sie zeigen, was zuletzt angewendet wurde.
3. Prüfen Sie die Antwort des Schreibvorgangs auf `control/subscribe/execute`. Erwartet: `DL_OK` (auf einem PC `Ok`). Diese Methoden haben keinen `status-text`; der Grund für eine Ablehnung steht im Protokoll der Anwendung.
4. Lesen Sie `control/subscribe/output/stream/active`. Erwartet: `true`.
5. Lesen Sie `received-frames`, `processed-frames` und `failed-frames` unter `control/subscribe/output/stream/statistics/`. Der erste Zähler, der nicht wächst, zeigt, wo die Kette abbricht.
6. Wächst `failed-frames`, lesen Sie `control/subscribe/output/stream/last-failure`. Er nennt den Grund für den letzten fehlgeschlagenen Frame, zum Beispiel:
   ```
   a frame of 'hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream' failed: invalid input: preprocess/method 'LAPLACE' is unknown; expected NONE, LOG, DOG or DOH
   ```

**Lösung**

- **Wenn nur die Eingaben geschrieben wurden:** Setzen Sie `control/subscribe/input/enable` auf `true` und schreiben Sie auf `control/subscribe/execute`. Warten Sie, bis `control/subscribe/output/stream/active` `true` ist.
- **Wenn der Aufruf abgelehnt wurde (`DL_INVALID_VALUE`, `Rejected`):** Schreiben Sie den Stream-Ordner der Kamera auf `control/subscribe/input/address`, setzen Sie `control/subscribe/input/queue-size` auf einen Wert von `1` bis `64` und schreiben Sie erneut auf `control/subscribe/execute`.
- **Wenn die Einstellungsdatei nicht geschrieben werden konnte (`DL_CREATION_FAILED`, `CreationFailed`):** Machen Sie `<module-id>.json` im Konfigurationsverzeichnis wieder zu gültigem JSON, ohne Kommentare, und schreiben Sie dann erneut auf `control/subscribe/execute`.
- **Wenn der Stream des Cam Driver nicht läuft:** Starten Sie ihn. Er bleibt nach einem Neustart nicht erhalten: Rufen Sie nach jedem Start sein `control/publish/execute` mit `enable` = `true` auf, und verbinden Sie zuerst die Kamera. Siehe [Ein Stream liefert nichts](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#stream-nothing).
- **Wenn die Quelle nicht abonniert werden kann:** Prüfen Sie, ob `control/subscribe/input/address` der Stream-Ordner der Kamera ist und der Cam Driver auf demselben Gerät läuft.
- **Wenn Frames fehlschlagen:** Korrigieren Sie die Eingabe, die `last-failure` nennt, wie bei einem einzelnen Aufruf von `detect-area`.

Der Stream veröffentlicht nur die Messwerte: `output/blob-labels` hat kein Gegenstück im Stream. Siehe [Flächen auf einem Bild-Stream erkennen (experimentell)](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit den Werten unter `setting/stream/`, den Zählern unter `control/subscribe/output/stream/statistics/`, `control/subscribe/output/stream/last-failure` und der `<module-id>.json` des Moduls.

## Module, Einstellungen und Lizenzierung {#ts-modules}

### Problem: Meine Einstellungen oder Module sind nach einem Neustart weg {#faq-settings-lost}

**Symptome**

Nach einem Neustart der Anwendung fehlt ein Modul in `system/modules`, oder die Eingaben eines Moduls stehen wieder auf ihren Standardwerten.

**Mögliche Ursachen**

- Die Modulliste wurde nicht gespeichert. Einstellungen und neue Module sind sofort aktiv, aber erst dauerhaft, wenn sie gespeichert wurden; die Modulliste und die Einstellungen jedes Moduls werden getrennt gespeichert.
- Die Einstellungen des Moduls wurden nicht gespeichert.
- Ein Speichern ist fehlgeschlagen: `system/save-module-inputs` oder `system/save-current-modules` hat nicht Status `1` gemeldet.
- `<module-id>.json` enthält Kommentare. Der Stream liest eine solche Datei, aber die Eingaben des Moduls werden dann beim Start nicht wiederhergestellt; das Protokoll meldet die Datei als unlesbar.
- Eine Einstellung, deren Knoten nach einem Software-Update nicht mehr existiert, wird mit einem Protokolleintrag übersprungen.

**Diagnose**

1. Lesen Sie `system/modules` nach dem Neustart. Erwartet: alle Ihre Module.
2. Prüfen Sie das Konfigurationsverzeichnis (siehe [Allgemeine Prüfungen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#general-checks)). Erwartet: `lumiscan-area-detector.json` nennt Ihre Module, und für jedes Modul, dessen Einstellungen Sie gespeichert haben, gibt es eine `<module-id>.json`.
3. Lesen Sie das Protokoll der Anwendung beim Start. Erwartet: keine als unlesbar gemeldete Moduldatei, keine übersprungene Einstellung.

**Lösung**

- **Wenn die Einstellungen oder die Modulliste nicht gespeichert wurden:**

  a. Setzen Sie `system/save-module-inputs/input/module-id` (zum Beispiel `module-1`) und schreiben Sie auf `system/save-module-inputs/execute`. Tun Sie das für jedes Modul.

  b. Schreiben Sie auf `system/save-current-modules/execute`.

  c. Prüfen Sie, dass beide Status `1` melden.

- **Wenn die Moduldatei Kommentare enthält:** Entfernen Sie sie aus `<module-id>.json`. Von Hand an der Datei vorgenommene Änderungen wirken beim nächsten Start.

- **Wenn nach einem Update eine Einstellung übersprungen wurde:** Setzen Sie die Eingabe erneut und speichern Sie die Einstellungen des Moduls.

Modus und Quelle des Bild-Streams werden von `control/subscribe/execute` selbst gespeichert, in der `<module-id>.json` des Moduls; sie kommen nur zurück, wenn auch die Modulliste gespeichert ist. Siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/module-management.html) und [In der Einstellungsdatei erhalten](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#saving).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `lumiscan-area-detector.json` und den Moduldateien `<module-id>.json`.

### Problem: Die Anwendung beendet sich kurz nach dem Start {#ts-app-stops-after-start}

**Symptome**

Auf ctrlX OS beendet sich die Anwendung kurz nach dem Start. Ihre Knoten unter `hdvisionsystems/lumiscan-area-detector` verschwinden aus dem Data Layer.

**Mögliche Ursachen**

- Die Lizenz fehlt. Der Grund wird in das Systemprotokoll geschrieben.
- Die Anwendung benötigt mehr Lizenzen, als installiert sind. Eine Lizenz deckt zehn Module ab, siehe [Problem: Statuscode `-11` (Lizenz nicht verfügbar)](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#ts-licence-unavailable).

**Diagnose**

1. Öffnen Sie das Systemprotokoll von ctrlX OS (ctrlX Logbook oder `journalctl`). Erwartet: Es nennt den Grund und die fehlende Lizenz.
2. Vergleichen Sie die Lizenz mit der ctrlX-Lizenz von LumiScan Area Detector, `SWL-W-XCx-AxxDETECTxHDVSx-V1NN`. Erwartet: Sie ist auf dem Gerät installiert, auf dem die Anwendung läuft.

**Lösung**

- **Wenn die Lizenz fehlt:** Installieren Sie eine gültige Lizenz auf dem Gerät und starten Sie die Anwendung erneut. Erwartet: Sie läuft weiter, und ihre Knoten sind im Data Layer.

Siehe [Lizenz](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/requirements.html#licence) und [Meine ctrlX-App beendet sich kurz nach dem Start](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/troubleshooting.html#faq-ctrlx-app-stops).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit den Zeilen des Systemprotokolls, die die Lizenz nennen. Für Lizenzen wenden Sie sich an [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).

### Problem: Statuscode `-11` (Lizenz nicht verfügbar) {#ts-licence-unavailable}

**Symptome**

Ein Modul wird mit Statuscode `-11` abgelehnt.

**Mögliche Ursachen**

- Keine Lizenz auf dem Gerät deckt das Modul ab. Eine Lizenz deckt zehn Module ab; das elfte Modul belegt eine zweite Lizenz desselben Schlüssels.

**Diagnose**

1. Zählen Sie die Einträge von `system/modules`. Erwartet: nicht mehr als zehn Module pro Lizenz auf dem Gerät.
2. Lesen Sie `output/status-text` der Operation, die mit `-11` geantwortet hat.

**Lösung**

- **Wenn mehr Module existieren, als die Lizenzen abdecken:** Entfernen Sie die nicht benötigten Module mit `system/remove-module` und speichern Sie die Modulliste mit `system/save-current-modules`, oder beschaffen Sie eine weitere Lizenz.

Siehe [Modulverwaltung](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/module-management.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#support-information) aufgeführten Informationen an den Support, zusammen mit `system/modules`. Für Lizenzen wenden Sie sich an [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).

## Informationen für den Support {#support-information}

Besteht ein Problem weiterhin, senden Sie diese Informationen an den Support:

- **Softwareversion:** die Version von LumiScan Area Detector, die Sie verwenden. Die Dateien in `settings-history/` im Konfigurationsverzeichnis halten sie als `software.version` fest.
- **Plattform:** ctrlX OS (ctrlX CORE oder ctrlX IPC) und die Version von ctrlX OS, oder ein PC mit Windows 11 oder Ubuntu 24.04. Nennen Sie auch die Bezugsquelle: HD Vision Systems oder ctrlX Store.
- **Data Layer:** der ctrlX Data Layer (ctrlX OS) oder LumiScan Keryx (PC). Auf einem PC auch die Data-Layer-Adresse, die die Anwendung verwendet.
- **Protokoll:** das Protokoll der Anwendung zum Zeitpunkt des Fehlers - auf ctrlX OS aus dem ctrlX Logbook oder mit `journalctl`, auf einem PC die Konsolenausgabe der Anwendung.
- **Zeitpunkt:** Datum und Uhrzeit des Fehlers.
- **Kommunikationsstatus:** `output/status-code` und `output/status-text` der fehlgeschlagenen Operation und die Antwort des Schreibvorgangs auf `execute` (zum Beispiel `DL_TOO_MANY_OPERATIONS` oder `TooManyOperations`).
- **Konfigurationsdateien:** `lumiscan-area-detector.json`, die `<module-id>.json` des betroffenen Moduls und, für den Bild-Stream, die Datei in `settings-history/`, die sein Einstellungs-Hash nennt. Wo sie liegen, steht unter [Allgemeine Prüfungen](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html#general-checks).

Wenden Sie sich an den Customer Success von HD Vision Systems unter [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com) oder +49 6221 6721905; für Lizenzen an [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com). Siehe auch [Bevor Sie den Support kontaktieren](https://docs.hdvisionsystems.com/de/faq.html#faq-before-contacting-support) in der LumiScan-FAQ.

# Release Notes: v1.1.0 (2026-08-09) – LumiScan Area Detector

URL: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/release-notes/v1-1-0-2026-08-09.html

Erstes funktionsfähiges Release von LumiScan Area Detector. Frühere Versionen registrierten die Data-Layer-Knoten der Anwendung, lieferten aber ein festes Platzhalter-Ergebnis zurück; nichts von dem Folgenden war also vorher nutzbar.

## Neu

**Flächenerkennung.** `<module>/detect-area/execute` findet die Regionen in einem Kamerabild und meldet Fläche und Position jeder einzelnen sowie die Gesamtfläche über alle. Ein Referenzbild ist nicht nötig: Sie beschreiben, was als Region zählt, über ihre Helligkeit, ihre Größe und ihre Rundheit.

**Fünf Wege, eine Region zu finden**, gewählt über `input/method`. `CIRCLE` durchläuft einen Bereich von Intensitätsstufen und behält, was auf mehreren davon wie ein Blob aussieht - das hält auch, wenn die Beleuchtung nicht stabil ist; die anderen vier binarisieren einmal und nehmen jede zusammenhängende Region, unabhängig von ihrer Form. Alle fünf melden eine gemessene Pixelfläche.

**Eine Wahl des Schwellwerts beim Messen**, `input/method-specific/corrected/min-level`. Ein lokaler Schwellwert folgt ungleichmäßiger Beleuchtung und eignet sich für feine Merkmale; ein globaler nimmt eine massive Region als Ganzes, und genau das braucht das Messen eines massiven Teils.

**Formfilter** - Fläche, Rundheit, Konvexität und Länglichkeit -, sodass nur die interessierenden Regionen gemeldet werden; die Bedeutung jedes Filters ist auf dem Knoten selbst erklärt.

**Optionale Vorverarbeitung** vor der Erkennung: Laplacian of Gaussian, Difference of Gaussians oder Determinant of Hessian.

**Eine Region of Interest pro Durchlauf**, `input/crop`, um die Suche einzuschränken und zu beschleunigen.

**Mehrere Module**, jedes mit eigenen Einstellungen und Ergebnissen, sodass eine Installation mehrere Kameras überwachen kann. Eine Lizenz gilt für zehn Module.

**Die Formen der Regionen, wenn Sie sie anfordern.** `input/publish` fügt neben den Messwerten Umrisse, vereinfachte Polygone und Masken hinzu, jeweils auf einem eigenen Data-Layer-Knoten. Standardmäßig leer, und dann kostet ein Durchlauf genau so viel wie zuvor. Die Masken für den ganzen Frame und pro Region sind gewöhnliche Bildknoten, eine andere Anwendung liest sie also mit dem Code, den sie bereits für ein Kamerabild hat. (In 1.2.0 zurückgezogen: Ein einzelnes Label-Bild hat sie alle ersetzt.)

**Ein Status bei jeder Operation**: `output/status-code` und `output/status-text`, wobei ein negativer Code immer bedeutet, dass der Durchlauf fehlgeschlagen ist und nichts erzeugt hat.

## Gut zu wissen

Jede ungültige Eingabe wird sofort gemeldet, und jede Meldung nennt den zu ändernden **Knoten** statt eines internen Feldnamens - `threshold/min (250) must not exceed threshold/max (220)`.

Ein leeres Ergebnis bedeutet, dass keine Regionen zutrafen, und sonst nichts: Jeder andere Grund, aus dem ein Durchlauf nichts erzeugen könnte, wird vor der Erkennung abgefangen und als negativer Statuscode gemeldet.

Die Formen sind bewusst nicht im Ergebnis-Flatbuffer enthalten. Über die REST-API kommt ein Flatbuffer als ein JSON-String mit Zahlen in Anführungszeichen an, ein Array von Koordinaten kommt also als Array von Strings zurück - zu langsam, um es zu verwenden. Stattdessen enthält das Ergebnis die Punktanzahlen pro Region, mit denen sich die veröffentlichten Puffer zerlegen lassen.

Schalten Sie beim Messen massiver Teile `input/method-specific/corrected/min-level` aus. Ein lokaler Schwellwert vergleicht ein Pixel mit seiner Umgebung, sodass die Mitte einer großen massiven Region - wo die Umgebung gleich hell ist - herausfällt und die Region hohl gemessen wird. Siehe [Eine Szene analysieren](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/analysing-a-scene.html).

# LumiScan Area Detector

URL: https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/index.html

|   |   |   |
| --- | --- | --- |
| ![Dunkle Flächen verschiedener Größe auf heller Oberfläche](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/_images/intro/step-1.svg)<br><br>**Auf die Szene richten.** Kein Referenzbild: Sie legen fest, was als Fläche zählt. | ![Die Flächen umrandet und mit ihrer Fläche in Quadratpixeln beschriftet](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/_images/intro/step-2.svg)<br><br>**Jede Fläche wird gefunden und vermessen.** Mit Fläche und Position im Bild. | Beispielergebnis<br><br><br><br><br><br><br>Flächen<br>4<br><br><br>Gesamtfläche<br>5 700 px²<br><br><br>Größte<br>2 760 px²<br><br>**Das Ergebnis an die SPS geben.** Anzahl, Gesamtfläche und größte Fläche. |

LumiScan Area Detector findet Flächen im Kamerabild und meldet, wie groß jede ist. Ein Referenzbild braucht er nicht: Sie beschreiben, was als Fläche zählt, über Helligkeit, hell oder dunkel, mit oder ohne Löcher, und erhalten jede Fläche mit Größe und Position sowie Anzahl und Gesamtfläche. Einsatz: Teile zählen, Bedeckung oder Verschmutzung prüfen, Füllstände messen, oder Dinge ohne feste Form wie eine Lache, einen Kratzer oder einen Spalt.

Zur Lizenzierung siehe [Lizenz](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/lumiscan-area-detector/requirements.html#licence). Fragen? Siehe die [FAQ](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/faq.html). Ein Problem oder eine Fehlermeldung? Siehe [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-area-detector-de/1.2.0/troubleshooting.html).
