diff --git a/doc/Anwenderdoku.md b/doc/Anwenderdoku.md new file mode 100644 index 0000000..a3ded4e --- /dev/null +++ b/doc/Anwenderdoku.md @@ -0,0 +1,255 @@ +# Anwenderdoku und FAQ zur Ermittlung der Kabellängen + +## Allgemeine Infomationen und Programmablauf + +### Zweck des Programms + +Dieses Toolset dient der **automatisierten** und **komfortablen** Ermittlung von Kabellängen zwischen Unterverteilern und deren zugeordneten Sensoren/Aktoren entlang definierter Kabeltrassen. Als **Eingabe** dient eine 2D-Layout-Zeichnung im `.dxf`-Format. **Ausgaben** sind u.a.: + +- eine strukturierte `.json`-Datei mit Kabellängen und Pfadkoordinaten +- eine visuelle `.dxf`-Datei mit eingezeichneten Kabelwegen +- eine Bilddatei mit dem erstellten Anlagenmodell +- zukünftig: tabellarische Aufbereitung der Kabellängen mit SIVAS-Nummern (z. B. `.xlsx`) + +### Allgemeiner Programmablauf + +Das Toolset besteht aus drei zentralen Skripten, die automatisiert über **ein** *Batch-Skript* aufgerufen werden. Der interne Programmablauf ist folgender: + +`getpositions.py` -> `routing.py` -> `drawdxf.py` + +Das erste Programm extrahiert aus der .dxf-Datei sämtliche Informationen über die Positionen von Sensoren / Aktoren und Unterverteilern sowie den Kabeltrassen. Das zweite Programm baut aus den Informationen ein Modell der Anlage auf und erknüpft die Elemente entlang der kürzesten Wege. Das letzte Programm zeichnet eine neue .dxf-Datei, in welcher die Kabelwege von den Unterverteilern zu den Sensoren dargestellt sind. + +### Aufruf des Programms + +Vor dem Start des Programms muss sichergestellt werden, dass die Umgebungsvariablen korrekt gesetzt sind. Dies geschieht über den Aufruf der Datei `get_cmd.bat`. Die *Command-Shell* bleibt geöffnet. + +Nun kann in dieser Konsole das Skript `getexdraw.bat` aufgerufen werden. Hierzu reicht das Eintippen des Programmnamens. **WICHTIG:** Nach dem Programmnamen **muss** die .dxf-Datei, welche für das Programm verwendet werden soll genannt werden. Diese **muss** im Order "Work" abgelegt sein! Ein Beispielafter Programmaufruf am Beispiel der "easy.dxf" sieht dementsprechend aus: + +```text +C:\10-Develop\kabellaengen\bin> getexdraw.bat easy.dxf +``` + +Wenn das Programm korrekt gestartet wurde, wird der Nutzer in dem geöffnetem Fenster über den aktuellen Status infomiert. Die Ausgabe schreibt: + +```text +C:\10-Develop\kabellaengen\bin>getexdraw.bat easy.dxf +--hole Positionen +reading file ..done +writing results to a json file ... +done +--erzeuge Graph mit Routing +writing results to a json file ... +done +--zeichne Kabel in dxf Datei +done +``` + +### Ausgabe des Toolsets + +Alle drei oben genannten Teilprogramme erzeugen eine eigene Ausgabedatei. Die Ausgaben der ersten beiden Programme dienen als Eingabe für das folgende. Die Ausgaben des letzten Teilprogrammes `drawdxf.py` sind für den Anwender bestimmt. Zu Informationszwecken können auch die Zwischenergebnisse im "Work"-Ordner geöffnet werden (genauere Informationen zu den Ausgaben in den jeweiligen Abschnitten zu den Teilporgrammen).Als wesentliche Ausgabe nach Aufruf des Gesamtprogramms dienen: + +- Die .dxf-Datei mit den Kabelwegen: `NamederEingabedatei_cables.dxf` +- Die tabellarische Aufbereitung der Kabellängen mit zugehörigen Sachnummern für jeden Sensor / Aktor: `NamederEingabedatei_cables.xlsx` + +## Informationen zu den Einzelprogrammen + +Nachfolgend sind Infomationen zu den Einzelprogrammen aufgeführt. Diese enthalten teils wichtige Hinweise zur Aufbereitung der Eingabedateien, Informationen zu den einzelnen Ausgabedateien sowie immer ein Beispiel anhand eines einfachen Layouts `easy.dxf`. Dieses wird verwendet, um den Programmablauf beispielhaft zu zeigen. Nachfolgend ein Screenshot des Layouts für die weiteren Beispiele. +![dxf von easy](img\easy_layout.png) + +### Details zu `getpositions.py` + +Das erste Programm im Ablauf bestimmt maßgeblich die Ausgaben der weiteren Programme und ist weiterhin maßgeblich von der Eingabedatei (.dxf-Datei der Anlage) abhängig. + +Eine .dxf-Datei (mit standardisierten Merkmalen!) wird in `getpositions.py` eingelesen. Das Programm extrahiert aus der 2D-Zeichnungsdatei alle Anfangs- und Endpunkte der Kabeltrassen sowie alle Positionen der Sensoren / Aktoren und Unterverteiler innerhalb des 2D-Layouts der Anlage. Diese werden gesammelt und in einer temporären Datei abgespeichet (`NamederEingabedatei.json `). +Bei der Erstellung der .dxf-Datei, welche vearbeitet werden soll, ist es wichtig, dass die Kabeltrassen konsistent auf den gleichen Layern gezeichnet werden und bei der Erstellung / Positionierung der Sensoren und Aktoren folgendes beachtet wird: + +- Sensoren / Aktoren, die ein "x" zur Bestimmung der tatsächlichen Sensorposition enthalten, werden mit Kabeln bis zum "x" versehen +- Sensoren / Aktoren, die keine tatsächliche markierung enthalten, werden auf die Mitte des Textblockes mit einem Kabel versehen + +Die Ausgabe des Programms ist eine .json-Datei, welche **strukturiert, in Textform** die Infomationen aus der Zeichnungsdatei weitergibt. Nachstehend ein Auszug der .json-Ausgabe des oben gezeigten Layouts. + +```yaml +{ + "sensors": { + "BG3241": { + "IO": "BG3241", + "ID": "", + "VERW": "Jam detector", + "BEZEICHNUNG": "Stausensor 1 (ILS-CV M0108)", + "KENNZEICHNUNG": "=A01+UC0101-KF1DI1", + "SPS": "1", + "REALE_POSITION": "x", + "pos": [38.8, 1280.2] + }, + "MA0062": { + "IO": "MA0062", + "ID": "", + "VERW": "CV-M0062_0,75", + "BEZEICHNUNG": "Motor MA0062", + "KENNZEICHNUNG": "=A01+UH01-KF1DQ04", + "TEXT-E": "Motor MA0062", + "SPS": "1", + "REALE_POSITION": "x", + "pos": [4967.0, 8072.5] + }, + }, + .... + + "distributors": { + "UC0101": [0.0, 4162.8] + }, + "racks": { + "Rack_1": [ + [4946.5, 15774.4], + [4946.5, 3879.4] + ], + "Rack_2": [ + [0.1, 57.6], + [0.1, 3777.6], + [14755.1, 3777.6] + ], + "Rack_3": [ + [185.1, 15865.5], + [12450.7, 15865.5] + ] + }, + "mapping": { + "UC0101": [ + "BG3241", + "MA0062" + ] + } +} +``` + +Die Ausgabedatei ist gegliedert in vier große Blöcke: + +- **Sensoren und Aktoren** ("sensors"): Enthält alle Sensoren und Aktoren der Anlage mit allen zugewiesenen Informationen. +- **Unterverteiler** ("distributors"): Enthält die Positionsinfomation der Unterverteiler +- **Kabeltrassen** ("racks"): Enthält die Koordinaten der Anfangs und Endpunkte einer Kabeltrasse. Wenn Kabeltrasse als *Polylinie* gezeichnet ist, sind mehrere einzelsegmente aufgeführt (siehe bspw. "Rack_2") +- **Zuweisung von UV zu Sensoren / Aktoren** ("mapping"): Enthält die Zuweisung von einem Unterverteiler zu allen daran angeschlossenen Sensoren und Aktoren + +### Details zu `routing.py` + +Die .json-Ausgabe, welche oben in einem Auszug gezeigt ist, stellt die Daten der .dxf-Datei in einer einfach zu weiterverarbeitetenden Fassung dar. Die ausgegebenben Daten sind jedoch weiterhin im weitesten Sinne "Rohdaten", welche noch weiter behandelt werden müssen. In dem Einzelprogramm `routing.py` wird aus den Daten mithilfe der Funktionen, welche in `plant.py` implementiert sind, eine "virtuelle" Anlage (eng.: *plant*) aufgebaut. Als Eingabe dient lediglich die .json, welche von `getpositions.py` ausgegeben wird. Hauptfunktionen von `routing.py` bzw. `plant.py` sind: + +- Aufbauen des "Grundgerüstes" der Anlage bestehend aus Kabeltrassen (Racks) + - Finden von Schnittpunkten einzelner Racks und Erstellung von expliziten Knoten dort + - Finden von "eigentlichen" Schnittpunkten und Anpinnen von nahezu verbundenen Racks aneinander +- Verknüpfen von Sensoren / Aktoren / Unterverteilern mit dem Grundgerüst der Anlage + - Finden des nächstgelegenen Racks zu jedem S / A / UV + - Erstellen eines Aufpunktes für die Strecke vom Rack zum S / A / UV + - Verknüpfen des jeweiligen S / A / UV mit dem Aufpunkt über den kürzesten Weg +- Erstellen eines Graphen (=mathematisches Modell für netzartige Struktur) zur Anwendung von Wegfindungs-Algorithmen zur Bestimmung der kürzesten Kabelwege von Sensor / Aktor zu Unterverteiler entlang der Racks + +Die Ausgabe des Einzelprogramms `routing.py` ist im wesentlichen die Infomationen über die Kabel, welche von einem Sensor / Aktor zu dem zugehörigen Unterverteiler laufen. Die Informationen beinhalten den Pfad (= die einzelnen Koordinaten in x,y über welche der Pfad verläuft) und die Länge des Pfades (und damit die Länge des Kabels). Die Ausgabe erfolgt erneut in einer strukturierten .json-Datei. Die Ausgabedatei an dieser Stelle trägt stets den namen `todraw.json`. Sie dient als Eingabe für das Einzelprogramm `drawdxf.py`. Nachfolgend ein Ausschnitt der Ausgabedatei anhand des oben gezeigten Beispiels: + +``` yaml +{ + "kabel": [ + { + "id": "UC0101-BG3241", + "coords": [ + {"x": 0.0, "y": 4162.8}, + {"x": 0.1, "y": 3777.6}, + {"x": 0.1, "y": 1280.2}, + {"x": 38.8, "y": 1280.2}], + "length": 2921.3, + "nodes": [31, 17, 18, 12] + }, + + .... + + { + "id": "UC0101-BG3240", + "coords": [ + {"x": 0.0, "y": 4162.8}, + {"x": 0.1, "y": 3777.6}, + {"x": 2866.6, "y": 3777.6}, + {"x": 4946.5, "y": 3777.6}, + {"x": 4946.5, "y": 3879.4}, + {"x": 4946.5, "y": 5609.0}, + {"x": 4961.9, "y": 5609.0}], + "length": 7178.4, + "nodes": [31,17,15,29,21,7,14] + ] + } +``` + +Die Ausgabedatei gliedert sich in die Blöcke, welche im Mapping (siehe Ausgabedatei unter `getpositions.py`) aufgeführt sind. Im obigen Beispiel sind demnach die Kabel von Unterverteiler *UC0101* zu Sensor *BG2341* bzw. von *UC0101* zu *BG2340* dargestellt. Neben der ID des Kabels ist aufgeführt: + +- Die Knotenpunkt-Koordinaten entlang welchen das Kabel verläuft +- Die exakte Länge des Kabels +- Die Knotenpunkte (nodes) des Graphen, entlang welchen das Kabel verläuft + +Als weitere Ausgabedatei kann in der Konfigurationsdatei `routing.cfg` die Ausgabe des Graphen eingestellt werden. Der Graph, welcher sich anhand des verwendeten Beispiels ergibt ist nachfolgend gezeigt. Die Knotenpunkte können zur einfachen Überprüfung der Kabelwege anhand des Graphen verwendet werden (ohne die Verwendung der teils unhandlichen Koordinaten x,y). Der Graph wird standardmäßig als Vektorgrafik (.svg) gespeichert, sodass ohne Qualitätsverlust an sich überlappende Knoten gezoomt werden kann, um diese genauer zu betrachten. + +![Graph von easy](img\graph_easy.svg) + +- Schwarze Linine stellen Racks dar +- Rote Linine sind Verbindungen zwischen Racks und Sensoren / Aktoren +- Blaue Linien sind Verbindungen von Unterverteilern zu Racks + +### Details zu `drawdxf.py` + +Das letzte Einzelprogramm, welches in der Routine aufgerufen wird, dient der Erstellung einer eigenen .dxf-Datei, welche die Kabelwege dastellt. Diese .dxf Datei trägt stets den Namen der Eingabedatei mit der Ergänzung `..._cables.dxf`. Die Datei kann als neue Layer in das bestehende Anlagen-Layout importiert werden, um die Kabelwege zu verifizieren. Die sich aus dem behandelten Beispiel ergebende Datei ist nachfolgend alleine sowie importiert in das Layout dargestellt: + +![easy_cables_allein](img\easy_cables.png) +![easy_cables_layout](img\easy_cables_layout.png) + +Die in den Details zu `getpositions.py` beschriebene Handhabung der Verbindung der Sensoren / Aktoren wird ersichtlich: + +- Sensoren mit einem Marker "x" zur genauen Positionierung werden an diesen verbunden (BG3260, BG3240, ...) +- Sensoren, welche über keinen Marker verfügen, werden anhand des Textblocks verbunden (z.B: BG3270) +- Die Unterverteiler werden stets auf die Mitte ihres Blocks verbunden. + + + +## Häufige Fagen + +### Wo stelle ich ein, was das Toolset am Ende ausspuckt? + +Hier müssen wir das mit der einzelnen Konfig noch implementieren + +### Warum werden manche Kabeltrassen nicht mit anderen verbunden? + +Mittels der Methode `join_racks()`, welche innerhalb `plant.py` definiert ist und von `routing.py` aufgerufen wird, werden die Rack-Segmente, welche von `getpositions.py` übergeben werden auf echte Schnittpunkte, sowie beinahe Schnittpunkte überprüft und an den jeweiligen Punkten verknüpft. Beinahe Schnittpunkte werden durch entlanglaufen der einzelnen Racks und "Absuchen" eines Toleranzfeldes ermitteln. + + + + +Sobald ein Schnittpunkt des Toleranzkreises mit einem angrenzenden Rack festgestellt wird, wird dieses Rack mit dem ausgehenden Rack verbunden. + + + + +Sollten einzelne Kabeltrassen nicht miteinander verbunden werden, ist die eingestellte Toleranz in der Konfigurationsdatei sowie der tatsächliche Abstand des Endpunktes einer Kabeltrasse und der naheliegenden zu überprüfen. Die Toleranz muss stets größer sein als dieser Abstand. Bei zu groß gewählter Toleranz kann unerwünschtes Anpinnen von zu weit entfernten Kabeltrassen auftreten. Der Standardwert ist auf **200** zu setzen. + +### Warum verbindet das Programm den Sensor mit genau dieser Kabeltrasse? + +Bei der Verbindung von Sensoren / Aktoren mit den Kabeltrassen findet noch keine Wegsuche zum zugehörigen Unterverteiler statt. Die Sensoren / Aktoren tragen darüber hinaus keinerlei Information, mit welcher Kabeltrasse sie verbunden werden sollen. Der Algorithmus sucht daher ausgehend von der Position des Sensors das am nahesten liegende Rack und stellt im Anschluss die kürzestmögliche verbindung zu einer Kabeltrasser her. + +Situation: Horizontales und vetikales Rack (R1 bzw R2), Sensor (S). Erstellen eines Kreises um den Sensor und Überprüfung auf Schnittpunkte mit Kabeltrassen + + + + +Schritt 2: Bei Ausbleiben eines Schnittpunktes -> Vergrößern des Kreises. Bei Ermittlung eines Schnittpunktes -> Erzeugen eines Aufpunktes auf der geschnittenen Kabeltrasse und Verbinden von Sensor mit Kabeltrasse. + + + + +# Ideen für "Umbau" de Programme + +- Eine Konfig in der unter mehreren Blöcken ## Routing ##, ##Ausgabe## die einzelnen Schalter 1 / 0 gesetzt werden +- Getpositions läuft immer + - -> scheibt output in positions.json in work + - -> damit werden alte positions.json überschrieben und work ordner nicht zugemüllt +- Routing läuft immer -> schreibt output in routing.json + - wenn schalter in Konfig für Graph gesetzt ist wird Graph als .svg in work gespeichert + - Name der Datei *eingabefile*_graph.svg +- Drawdxf umbennen in sowas wie *cables.py* oder so + - Schalter steuern was alles ausgegeben wird (Excel, dxf, ... was könnte man noch machen) + - hier muss man entscheiden ob Cabel-dxf immer gleich heisst oder so wie Eingabefile (Gefahr der Zumüllung) + - selnbes gilt für excel-File + diff --git a/doc/img/Graph_easy.svg b/doc/img/Graph_easy.svg new file mode 100644 index 0000000..90296f7 --- /dev/null +++ b/doc/img/Graph_easy.svg @@ -0,0 +1,786 @@ + + + + + + + + 2025-05-21T10:12:37.755396 + image/svg+xml + + + Matplotlib v3.10.1, https://matplotlib.org/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/img/easy_cables.PNG b/doc/img/easy_cables.PNG new file mode 100644 index 0000000..93b6030 Binary files /dev/null and b/doc/img/easy_cables.PNG differ diff --git a/doc/img/easy_cables_layout.PNG b/doc/img/easy_cables_layout.PNG new file mode 100644 index 0000000..665db5d Binary files /dev/null and b/doc/img/easy_cables_layout.PNG differ diff --git a/doc/img/easy_layout.PNG b/doc/img/easy_layout.PNG new file mode 100644 index 0000000..347e792 Binary files /dev/null and b/doc/img/easy_layout.PNG differ