diff --git a/doc/Anwenderdoku.md b/doc/Anwenderdoku.md index 4fd95b2..e2595d4 100644 --- a/doc/Anwenderdoku.md +++ b/doc/Anwenderdoku.md @@ -1,8 +1,18 @@ - [Anwenderdoku zur Ermittlung der Kabellängen](#anwenderdoku-zur-ermittlung-der-kabellängen) - [Installation des Programmes](#installation-des-programmes) - [Allgemeine Informationen und Programmablauf](#allgemeine-informationen-und-programmablauf) + - [Zweck des Programms](#zweck-des-programms) + - [Allgemeiner Programmablauf](#allgemeiner-programmablauf) + - [Aufruf des Programms](#aufruf-des-programms) + - [Ausgabe des Toolsets](#ausgabe-des-toolsets) - [Informationen zu den Einzelprogrammen](#informationen-zu-den-einzelprogrammen) + - [Details zu `getpositions.py`](#details-zu-getpositionspy) + - [Details zu `routing.py`](#details-zu-routingpy) + - [Details zu `drawdxf.py`](#details-zu-drawdxfpy) - [Häufige Fagen](#häufige-fagen) + - [Wo stelle ich ein, was das Toolset am Ende ausspuckt?](#wo-stelle-ich-ein-was-das-toolset-am-ende-ausspuckt) + - [Warum werden manche Kabeltrassen nicht mit anderen verbunden?](#warum-werden-manche-kabeltrassen-nicht-mit-anderen-verbunden) + - [Warum verbindet das Programm den Sensor mit genau dieser Kabeltrasse?](#warum-verbindet-das-programm-den-sensor-mit-genau-dieser-kabeltrasse) - [Ideen für "Umbau" der Programme](#ideen-für-umbau-der-programme) @@ -26,7 +36,7 @@ Dieses Toolset dient der **automatisierten** und **komfortablen** Ermittlung von - eine strukturierte `.json`-Datei mit Kabellängen und Pfadkoordinaten - eine visuelle `.dxf`-Datei mit eingezeichneten Kabelwegen -- eine Bilddatei mit dem erstellten Anlagenmodell +- eine weitere .dxf-Datei mit einem reduzierten Layout (Kabeltrassen + Kabel + Unterverteiler) - zukünftig: tabellarische Aufbereitung der Kabellängen mit SIVAS-Nummern (z. B. `.xlsx`) ### Allgemeiner Programmablauf @@ -35,19 +45,13 @@ Das Toolset besteht aus drei zentralen Skripten, die automatisiert über **ein** `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. +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 verknü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. +Der einfachste Weg, das Toolset zu starten, ist per *Drag-and-Drop*. Hierfür muss lediglich die .dxf-Datei, für die die Kabelführung und -auswertung durchgeführt werden soll, auf die Verknüpfung namens *Kabeltool* gezogen werden. Es öffnet sich eine sogenannte *Command-Shell*, die den Benutzer über den aktuellen Zustand des Programmablaufs informiert. -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: +Die Ausgabe schreibt: ```text C:\10-Develop\kabellaengen\bin>getexdraw.bat easy.dxf @@ -64,7 +68,7 @@ done ### Ausgabe des Toolsets -Alle drei oben genannten Teilprogramme erzeugen eine eigene Ausgabedatei. Die Ergebnisse der ersten beiden Programme dienen als Eingabe für die folgendem. Jedes der genutzten Programme besitzt eine eingebaute Hilfe, wenn man das Programm mit dem Schalter --help aufruft. +Alle drei oben genannten Teilprogramme erzeugen eine eigene Ausgabedatei. Die Ergebnisse der ersten beiden Programme dienen als Eingabe für die folgenden. Jedes der genutzten Programme besitzt eine eingebaute Hilfe, wenn man das Programm mit dem Schalter --help aufruft. Die Ausgaben des letzten Teilprogrammes `drawdxf.py` sind für den Anwender bestimmt. Zu Informationszwecken können die Zwischenergebnisse im "Work"-Ordner geöffnet werden (genauere Informationen zu den Ausgaben in den jeweiligen Abschnitten zu den Teilprogrammen). Als wesentliche Ausgabe nach Aufruf des Gesamtprogramms dienen: @@ -84,19 +88,20 @@ Hier die vorhandenen Schalter des Programms: usage: getpositions [-h] -f myfile.dxf [-s] [-r] [-w WRITE] [-c] fetches the x/y positions from a dxf file - -options: - -h, --help show this help message and exit - -f myfile.dxf, --filename myfile.dxf - which file should be fetched - -s, --sensors fetch all position of sensors, motors, actors and subdistributors - -r, --rack fetch all positions of all cable racks - -w WRITE, --write WRITE - write results into a json file - -c, --console print results to output - ``` +Schalter: + +| Schalter
(kurz) | Schalter
(lang) | Argument
(notwendig!) | Hilfe | +|--------------------|--------------------|--------------------------|--------------------------------------------------------------| +| `-h` | `--help` | | show this help message and exit | +| `-f` | `--filename` | `myfile.dxf` | file to be analyzed | +| `-s` | `--sensors` | | fetch all positions of sensors, actors and subdistributors | +| `-r` | `--rack` | | fetch all positions of all cable racks | +| `-w` | `--write` | | write results into a json file | +| `-c` | `--console` | | print results to output | + + 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 `). @@ -176,17 +181,19 @@ Hier die vorhandenen Schalter des Programms: usage: routing.py [-h] -f my_positions.json [-c] [-g] [-w WRITE] Berechne Wege von Sensoren zu Verteilern über Kabeltrassen - -options: - -h, --help show this help message and exit - -f my_positions.json, --filename my_positions.json - file with all informations about positions gathered from getpositions - -c, --console Ausgabe auf Konsole - -g, --graph Zeichnet den Graphen der Anlage - -w WRITE, --write WRITE - erstellt Ausgabe-file für das Zeichnen von Kabeln in drawdxf ``` +Schalter: + +| Schalter
(kurz) | Schalter
(lang) | Argument
(notwendig!) | Hilfe | +|--------------------|--------------------|------------------------------|--------------------------------------------------------------------| +| `-h` | `--help` | | show this help message and exit | +| `-f` | `--filename` | `myfile_positions.json` | file positional information | +| `-c` | `--console` | | print result to output | +| `-g` | `--graph` | | draw graph and display in separate window | +| `-w` | `--write` | `myfile_todraw.json` | write results-file to use for cable-drawing | + + Die .json-Ausgabe, welche oben in einem Auszug gezeigt ist, stellt die Daten der .dxf-Datei in einer maschinen- und menschenlesbarer Fassung dar. Die ausgegebenen 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) @@ -252,23 +259,27 @@ Als weitere Ausgabedatei kann in der Konfigurationsdatei `routing.cfg` die Ausga Hier die vorhandenen Schalter des Programms: ```text -usage: drawdxf [-h] -f myfile.json [-d myfile.dxf] [-n NEW] +usage: drawdxf [-h] -f myfile_todraw.json [-d myfile.dxf] [-n NEW] [-c myfile_reduced.dxf] [-x myfile_cables.xlsx] [-o myfile.dxf] + draws a dxf file with the given cable coordinates - -options: - -h, --help show this help message and exit - -f myfile.json, --filename myfile.json - this json file contains all cables and its coordinates which should be drawn. Saved with an unique timestamp - -d myfile.dxf, --dxf myfile.dxf - this dxf drawing will be copied and the new layer with the cables will be added - -n NEW, --new NEW create a new dxf file with cables in it. Name is basename and a timestamp ``` +Schalter: + +| Schalter
(kurz) | Schalter
(lang) | Argument
(notwendig!) | Hilfe | +|--------------------|--------------------|---------------------------|----------------------------------------------------------------------------------------------------------| +| `-f` | `--filename` | `myfile_todraw.json` | this json file contains all cables and its coordinates which should be drawn. Saved with a unique timestamp | +| `-d` | `--dxf` | `myfile.dxf` | this dxf drawing will be copied and the new layer with the cables will be added. Requires `--origin` | +| `-c` | `--copy_layer` | `myfile_reduced.dxf` | copy layers of racks, sensors, distributors into a new .dxf-file. Also contains cable paths. Requires `--origin` | +| `-n` | `--new` | `myfile_cables.dxf` | create a new dxf file only with cables in it. Name is basename and a timestamp | +| `-x` | `--excel` | `myfile_cables.xlsx` | create a xlsx file with cables data | +| `-o` | `--origin` | `myfile.dxf` | name of original .dxf file used by `--dxf` and `--copy_layer` | + 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: @@ -276,7 +287,7 @@ Die in den Details zu `getpositions.py` beschriebene Handhabung der Verbindung d - 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. - +Das letzte Programm gibt (sofern der Schalter `-x` gesetzt ist) zudem eine Excel-Übersicht der Kabel zurück. Diese beinhaltet die jeweilige ID des Kabels ("von wo nach wo") und die tatsächliche (genaue) Länge des Kabels. Daneben ist die gerundete Länge (aktuell auf volle 10 m) aufgeführt. In einem weiteren Arbeitsblatt sind die Längen gesammelt aufgeführt (z.B. 10x 10m Kabel, 5x 20 m Kabel, 1x 50 m Kabel). In einer Fehlerübersicht sind fehlgeschlagene Verbindungen zwischen Sensoren / Aktoren / Unterverteilern zu Kabeltrassen aufgeführt. In einer weiteren Übersicht fehlgeschlagene Kabelverbindungen (*Routings*) und der Grund für das Fehlschlagen. ## Häufige Fagen @@ -286,7 +297,7 @@ Hier müssen wir das mit der einzelnen Config 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. +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. diff --git a/doc/img/easy_cables.PNG b/doc/img/easy_cables.PNG index 93b6030..80add22 100644 Binary files a/doc/img/easy_cables.PNG and b/doc/img/easy_cables.PNG differ diff --git a/doc/img/easy_layout.PNG b/doc/img/easy_layout.PNG index 347e792..fc245b1 100644 Binary files a/doc/img/easy_layout.PNG and b/doc/img/easy_layout.PNG differ