mistangl/sps_skel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doku: README auf Hauptweg CSV -> TRO-JSON -> SCL, Klassenhierarchie ausgebaut

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Michael Stangl
2026-10-10 11:31:05 +02:00
co-authored by Claude Opus 5.5
parent 29077caa81
commit 5764df1ac8
2 changed files with 461 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+159 -100
View File
@@ -9,61 +9,110 @@
## Stand des Projekts
Aus einem CSV-Export der mechanischen Planung (ILS 2.0) werden automatisch
Die Kette **CSV → TRO-JSON → SCL** läuft in einer ersten Version durch. Aus
einem CSV-Export der mechanischen Planung (ILS 2.0) entstehen automatisch:
- der **Materialfluss-Graph** der mechanischen Objekte (Strecken, Gefällestrecken,
Kreisel),
- der **Materialfluss-Graph** der mechanischen Objekte (Strecken,
Gefällestrecken, Kreisel),
- die daraus abgeleitete **TRO-Liste** samt eigenem Flussdiagramm,
- eine **annotierte Kopie der BricsCAD-Zeichnung** mit einem Marker-Symbol pro
TRO (danach in BricsCAD von Hand nachbearbeitbar — TROs verschieben,
ergänzen, Typ ändern),
- daraus zurückgelesen ein **JSON-Modell der TROs** (liest nur die Zeichnung,
erfasst also auch von Hand vorgenommene Korrekturen), und
- die **TRO-JSON** `<name>_tro.json` (Schema `sps_skel-tro-v3`, Modell
`lib/model.py`) — die Schnittstelle zwischen Ableitung und SCL-Erzeugung,
- daraus ein **SCL-Gerüst für `FB_Main`** — ein `REGION` pro TRO mit
Instanzaufruf und allen Parametern in der richtigen Reihenfolge, aber
bewusst nicht lauffähig: jeder Wert, der aus der E-Planung stammen muss
(Sensor-/Aktoradressen, Separator-/Weichennummern, Staubereiche, ungeprüfte
Zeiten), ist als `TODO(E-Planung)` markiert statt geraten.
Zeiten), ist als `TODO(E-Planung)` markiert statt geraten. Optional
(`--templates`) kommen die REGIONs aus Jinja2-Templates
(`lib/scl_templates/<fbType>.scl.j2`, Pilot: `FB_ILS_MTRO_1Sep1Swi`),
- zur Sichtkontrolle eine **annotierte Kopie der BricsCAD-Zeichnung** mit einem
Marker-Symbol pro TRO. Die Zeichnung ist nur Ansicht, keine Datenquelle für
die SCL.
Diese fünf Werkzeuge liegen als CLI-Tools in `lib/` und sind über
`bin/`-Wrapper aufrufbar (siehe unten). Details, Domänenmodell und die
verbleibende Roadmap stehen in `doc/`, allen voran `doc/Python_Scripts.md`.
Details stehen in `doc/`, allen voran
[`doc/Python_Scripts.md`](doc/Python_Scripts.md) (alle Tools und Schalter) und
[`doc/Klassenhierarchie.md`](doc/Klassenhierarchie.md) (Klassen und wozu sie da
sind).
## Roadmap
## Ablauf
Offen ist vor allem die JSON-Layout-Datei nach dem in
`doc/HundM/Json_Layout-Konzept.md` beschriebenen Schema (`plc`,
`controlUnits`, `sensors[]`, `conveyors[]`, `tros[]`, `loadingBooms[]`,
`emptyCarrBuffers[]`, `routing`, `jamAreas[]`, `scanners[]`, `connections[]`,
`destinations[]`) als von Hand editierbares Zwischenformat vor der
SCL-Erzeugung, sowie die Generierung der übrigen Bausteine je Steuerung
(`FB_CallSensors`, `FC_Direction`, `FC_Call_Jams`) — `scl_skeleton.py` deckt
bisher nur `FB_Main` ab. Siehe `CLAUDE.md` (Abschnitt "Roadmap") für den
aktuellen Stand der Planung dazu.
```text
data/<name>.csv (ILS-2.0-Export)
│
▼
material_flow ──► <name>_material_flow.dot/.svg/.md Materialfluss der Mechanik
│
▼
tro_flow --json ──► <name>_tro.json (+ .dot/.svg/.md) TROs ableiten
│ │
│ ▼
│ scl_skeleton ──► <name>_FB_Main.scl SCL-Gerüst
│
└── gleiche Ableitung ──► tro_annotate ──► <name>_annotated.dxf (nur Ansicht)
(braucht zusätzlich die DXF-Zeichnung)
```
Alle Ausgaben landen in `results/` (`%SKEL_RESULTS%`).
## Welche Skripte gibt es und wofür?
### Umgebung (`bin/`, je `.bat` für Windows und `.sh` für Linux/macOS)
Diese vier Skripte verwalten nur Umgebung und venv, sie rufen kein
Python-Programm auf.
| Skript | Wofür |
| --- | --- |
| `setenv` | Setzt `SPS_SKEL` und die `SKEL_*`-Variablen, hängt `SKEL_LIB` an `PYTHONPATH`, legt fehlende Ordner an und gibt alles zur Kontrolle aus. `.sh` muss gesourct werden. |
| `install_py` | Einmalig: legt `.venv` an und installiert `requirements.txt`. Bricht ab, wenn `.venv` schon existiert. |
| `activate_venv` | Je Sitzung: aktiviert `.venv` und zeigt Python-Version und Pakete. `.sh` muss gesourct werden. |
| `get_cmd` | Öffnet eine neue Shell mit gesetzten Umgebungsvariablen. |
### CLI-Tools (`lib/<name>.py`, aufgerufen über `bin/<name>.bat`/`.sh`)
Jeder Wrapper ruft `setenv`, aktiviert `.venv` (falls vorhanden) und startet
das Modul mit allen übergebenen Argumenten.
| Tool | Wofür | Wichtige Schalter |
| --- | --- | --- |
| `material_flow` | Liest den CSV-Export und baut den gerichteten **Materialfluss-Graphen** der mechanischen Objekte (Strecke, Gefällestrecke, Kreisel); Separatoren/Scanner hängen an ihrem Objekt. Grundlage für `tro_flow`. | `--file`, `--tosvg`, `--use-cords`, `--doc`, `--connect`, `--track`, `--show-bbs`, `--chain-graph` |
| `tro_flow` | Leitet aus demselben Graphen die **TROs** ab (Typ aus dem Trägerobjekt des Separators, Weichen aus den Abgängen), verknüpft sie und zeichnet ihren Fluss. Mit `--json` entsteht die TRO-JSON — der Hauptweg zur SCL. | `--file`, `--json`, `--tosvg`, `--use-cords`, `--doc`, `--connect` |
| `scl_skeleton` | Liest die TRO-JSON (geprüft gegen `lib/model.py`) und schreibt das **`FB_Main`-Gerüst** als SCL. Mit `--templates` aus den Jinja2-Templates, sonst generisch. | `--json`, `--out`, `--start`, `--templates [DIR]`, `--strict` |
| `tro_annotate` | Zeichnet dieselben TROs als Marker (Farbe/Form je Typ, Attribute `ID`/`TYPE`/`FB_BLOCK`) in eine **Kopie** der BricsCAD-Zeichnung — zur Sichtkontrolle. Bestimmt dafür den CSV↔DXF-Lagebezug und legt ihn in `cfg/dxf_registration.json` ab. Erzeugt mit `--emit-lisp` die Typliste `cad/tro_types.lsp` für den `TROEDIT`-Dialog. | `--file`, `--dxf`, `--flow`, `--fb`, `--legend`, `--offset`, `--re-register`, `--check`, `--emit-lisp` |
| `tro_extract` | **Geparkt.** Liest TROs aus der annotierten Zeichnung zurück in das alte JSON-Format `sps_skel-tro-extract-v1`, das `scl_skeleton` nicht mehr annimmt. Nicht gelöscht, nicht weiterentwickelt. | `--dxf` |
### Bibliotheken (`lib/`, ohne eigenen Aufruf)
| Modul | Wofür |
| --- | --- |
| `tro_catalog.py` | Katalog der TRO-**Typen**: Kurzname, Siemens-FB, Bauteile, Farbgruppe, CAD-Symbol. Einzige Quelle für FB-Typ und Bauteile. |
| `model.py` | Gemeinsames Modell der TRO-**Instanzen** und der TRO-JSON (`TroBase`, `DerivedTro`, `Connection`, `TroCandidate`, `Analysis`, `TroDocument`). |
| `scl_context.py` | Wandelt die TRO-JSON in den Render-Kontext für die SCL (Reihenfolge, Bauteilblöcke, Staubereiche, Weichenziele, offene Namen). |
| `scl_templates/` | Jinja2-Templates je FB-Typ (`<fbType>.scl.j2`) plus gemeinsame Makros; nur mit `scl_skeleton --templates`. |
| `dxf_registration.py` | Ermittelt, prüft und speichert die Transformation zwischen CSV- und DXF-Koordinaten. |
| `tro_overrides.py` | Liest die Handkorrekturen aus `cfg/tro_overrides.ini`; heute nur von `material_flow --connect` genutzt. |
### Sonstige Skripte
| Skript | Wofür |
| --- | --- |
| `doc/TRO_Katalog/tro_graphs/gen_tro_graphs.py` | Doku-Werkzeug, nicht Teil der Pipeline: erzeugt die Typ-Schaubilder und Topologie-Graphen für `doc/TRO_Katalog/TRO_Katalog.md` aus `connect.ini`. Aufruf: `py doc/TRO_Katalog/tro_graphs/gen_tro_graphs.py` |
| `cad/tro_types.lsp` | Generiertes BricsCAD-LISP (Typliste für den `TROEDIT`-Dialog), erzeugt von `tro_annotate --emit-lisp`. |
| `tests/` | pytest-Tests: TRO-Modell, Render-Kontext, Golden-Files der SCL-Ausgabe (`tests/fixtures/scl/`), Templates gegen die Referenz-Aufrufstellen. |
## Projektstruktur
```text
sps_skel/
bin/ Umgebungsskripte + ein .bat/.sh-Wrapper-Paar je CLI-Tool
setenv.bat/.sh Umgebungsvariablen setzen
install_py.bat/.sh venv erstellen + pip install
activate_venv.bat/.sh venv aktivieren
get_cmd.bat/.sh Shell mit Umgebung oeffnen
material_flow.bat/.sh Wrapper fuer lib/material_flow.py
tro_flow.bat/.sh Wrapper fuer lib/tro_flow.py
tro_annotate.bat/.sh Wrapper fuer lib/tro_annotate.py
tro_extract.bat/.sh Wrapper fuer lib/tro_extract.py
scl_skeleton.bat/.sh Wrapper fuer lib/scl_skeleton.py
cad/ generiertes BricsCAD-LISP (tro_types.lsp) fuer den TROEDIT-Dialog
cfg/ Konfigurationsdateien (INI/JSON); dxf_registration.json
data/ Eingabedaten - CSV-Exporte, DXF (nicht im Git)
doc/ Dokumentation, siehe doc/Python_Scripts.md
examples/ Beispieldateien
lib/ Python-Quellcode (CLI-Tools + Bibliotheken)
log/ Log-Dateien (nicht im Git)
results/ Ergebnisse der CLI-Tools (.dot/.svg/.md/.dxf, nicht im Git)
tests/ Unit Tests
bin/ Umgebungsskripte + ein .bat/.sh-Wrapper-Paar je CLI-Tool
cad/ generiertes BricsCAD-LISP (tro_types.lsp) für den TROEDIT-Dialog
cfg/ Konfiguration: dxf_registration.json, tro_overrides.ini
data/ Eingabedaten - CSV-Exporte, DXF (nicht im Git)
doc/ Dokumentation, siehe doc/Python_Scripts.md
examples/ Beispieldateien (noch leer)
lib/ Python-Quellcode (CLI-Tools, Bibliotheken, scl_templates/)
log/ Log-Dateien (nicht im Git)
results/ Ergebnisse der CLI-Tools (.dot/.svg/.md/.json/.scl/.dxf, nicht im Git)
tests/ Unit Tests (pytest)
.gitignore
LICENSE
README.md
@@ -72,94 +121,104 @@ sps_skel/
## Umgebungsvariablen
| Variable | Beschreibung |
|----------------|---------------------------|
| `SPS_SKEL` | Wurzelverzeichnis |
| `SKEL_BIN` | Skriptverzeichnis |
| `SKEL_LIB` | Python-Quellcode |
| `SKEL_CFG` | Konfigurationsdateien |
| `SKEL_DATA` | Eingabedaten |
| `SKEL_DOC` | Dokumentation |
| `SKEL_LOG` | Log-Dateien |
| `SKEL_RESULTS` | Ergebnisse |
| `SKEL_EXAMPLES` | Beispieldateien |
| `SKEL_TESTS` | Unit Tests |
| `PYTHONPATH` | Erweitert um `SKEL_LIB` |
| Variable | Beschreibung |
|-----------------|-------------------------|
| `SPS_SKEL` | Wurzelverzeichnis |
| `SKEL_BIN` | Skriptverzeichnis |
| `SKEL_LIB` | Python-Quellcode |
| `SKEL_CFG` | Konfigurationsdateien |
| `SKEL_DATA` | Eingabedaten |
| `SKEL_DOC` | Dokumentation |
| `SKEL_LOG` | Log-Dateien |
| `SKEL_RESULTS` | Ergebnisse |
| `SKEL_EXAMPLES` | Beispieldateien |
| `SKEL_TESTS` | Unit Tests |
| `PYTHONPATH` | Erweitert um `SKEL_LIB` |
## Installation
### Voraussetzungen
- Python 3.10 oder hoeher
- Graphviz (`dot`) auf `PATH` fuer `--tosvg`, optional aber empfohlen
- fuer `tro_annotate.py`: `ezdxf` (wird per `requirements.txt` installiert)
- Python 3.10 oder höher
- Pakete aus `requirements.txt`: `pydantic`, `jinja2` (SCL-Templates), `ezdxf`
(nur `tro_annotate`), `pytest`
- Graphviz (`dot`, für `--use-cords` bei `tro_flow` auch `neato`) auf `PATH`
für `--tosvg` — optional, aber empfohlen
### Setup (Windows)
### Setup
```bat
bin\install_py.bat
bin\install_py.bat # Windows
```
### Setup (Linux / macOS)
```sh
bash bin/install_py.sh
bash bin/install_py.sh # Linux / macOS
```
## Nutzung
### Umgebung setzen
### Umgebung
```bat
bin\setenv.bat # Windows
source bin/setenv.sh # Linux / macOS
bin\setenv.bat # Windows: nur Variablen setzen
bin\activate_venv.bat # Windows: venv aktivieren
bin\get_cmd.bat # Windows: neue Shell mit Umgebung
```
### Shell mit gesetzten Variablen oeffnen
```bat
bin\get_cmd.bat # Windows
source bin/get_cmd.sh # Linux / macOS
```sh
source bin/setenv.sh
source bin/activate_venv.sh
bash bin/get_cmd.sh
```
### venv aktivieren
### Typischer Durchlauf
`--file`/`--dxf` nehmen einen Dateinamen (aufgelöst gegen `%SKEL_DATA%`) oder
einen vollen Pfad; `--json` sucht in `%SKEL_RESULTS%`.
```bat
bin\activate_venv.bat # Windows
source bin/activate_venv.sh # Linux / macOS
```
### CLI-Tools ausführen
Jedes Tool wird über seinen `bin/<name>.bat`/`.sh`-Wrapper aufgerufen; dieser
setzt die Umgebung, aktiviert `.venv` und ruft dann das Python-Modul auf.
`--file`/`--dxf` akzeptieren entweder einen Dateinamen (wird gegen
`%SKEL_DATA%` aufgelöst) oder einen vollen Pfad; Ausgaben landen in
`%SKEL_RESULTS%`.
```bat
REM 1) Materialfluss der mechanischen Objekte
REM 1) Materialfluss der mechanischen Objekte (optional, zur Kontrolle)
bin\material_flow.bat --file mubea.csv --tosvg --doc
REM 2) TRO-Liste + eigenes Flussdiagramm ableiten
bin\tro_flow.bat --file mubea.csv --tosvg --doc
REM 2) TROs ableiten und als TRO-JSON schreiben
bin\tro_flow.bat --file mubea.csv --tosvg --doc --json
REM 3) TROs als Marker-Symbole in eine Kopie der CAD-Zeichnung einbrennen
REM 3) FB_Main-SCL-Geruest erzeugen (generisch bzw. aus Templates)
bin\scl_skeleton.bat --json mubea_tro.json
bin\scl_skeleton.bat --json mubea_tro.json --templates
REM 4) Optional: TROs zur Sichtkontrolle in eine Kopie der Zeichnung
bin\tro_annotate.bat --file mubea.csv --dxf 500573_60_1.dxf --flow --fb --legend
REM (Zeichnung optional in BricsCAD von Hand nachbearbeiten)
REM 4) TROs aus der (ggf. bearbeiteten) Zeichnung zurueck in JSON lesen
bin\tro_extract.bat --dxf export_annotated.dxf
REM 5) FB_Main-SCL-Geruest aus dem JSON erzeugen
bin\scl_skeleton.bat --json export_tro.json --start TRO07
```
Alle Switches, Ausgabedateien und Exit-Codes der drei Tools sind in
[`doc/Python_Scripts.md`](doc/Python_Scripts.md) dokumentiert; das
Domänenmodell (TRO-Typen, geplantes JSON-Layout, I/O-Listen-Analyse) findet
sich in den übrigen Dokumenten unter `doc/`.
`--start TRO07` bei `scl_skeleton` ist nur nötig, solange die Anlage ein
geschlossener Kreis ohne Be-/Entladestation ist. Danach im erzeugten
`*_FB_Main.scl` nach `TODO(E-Planung)` suchen — das sind die Stellen, die aus
der E-Planung gefüllt werden müssen.
### Tests
```bat
python -m pytest tests/
```
mit aktivem `.venv`. Die Golden-Files in `tests/fixtures/scl/` legen die
SCL-Ausgabe byteweise fest; neu schreiben (`SKEL_UPDATE_GOLDEN=1`) nur bei einer
geprüften, gewollten Änderung.
## Roadmap
Noch offen:
- das volle **JSON-Layout-Schema** aus `doc/HundM/Json_Layout-Konzept.md`
(`plc`, `controlUnits`, `sensors[]`, `conveyors[]`, `tros[]`, `jamAreas[]`,
`routing`, …) als Zwischenformat — die TRO-JSON ist bisher TRO-zentriert;
- die übrigen Bausteine je Steuerung (`FB_CallSensors`, `FC_Direction`,
`FC_Call_Jams` als eigene Dateien) — erzeugt wird bisher nur `FB_Main`;
- Templates für die weiteren FB-Typen (siehe `doc/SCL_Templates.md`);
- typabhängige Zeit-Defaults statt `TODO(E-Planung): pruefen`.
Details: Abschnitt "Roadmap" in `CLAUDE.md`.
## Lizenz