From 2536a7e3ac12da82982eda62ca5fb7da91ac9646 Mon Sep 17 00:00:00 2001 From: Michael Stangl Date: Thu, 17 Sep 2026 18:12:08 +0200 Subject: [PATCH] Doku: tro_geometry.py und tro_flow.py --geometry dokumentiert Python_Scripts.md war auf dem Stand von acht Modulen. Ergaenzt: - neue Bibliothek lib/tro_geometry.py (STRtree-basierte Ableitung von Separator-Host und Weichen-Fanout aus den Bauteil-Weltkoordinaten) als eigenen Abschnitt 6b - Schalter --geometry / --geo-tol-mm in der tro_flow.py-Tabelle - shapely>=2.1 in der Paket-Uebersicht - Kopf auf neun Module / vier Bibliotheken aktualisiert Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/Python_Scripts.md | 44 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 40 insertions(+), 4 deletions(-) diff --git a/doc/Python_Scripts.md b/doc/Python_Scripts.md index 64a93c4..478fec8 100644 --- a/doc/Python_Scripts.md +++ b/doc/Python_Scripts.md @@ -1,9 +1,9 @@ # Python Scripts — CLI Tooling Overview -**As of:** 2026-08-20 +**As of:** 2026-09-17 -`lib/` currently holds eight Python modules (five of them runnable CLI tools, -three supporting libraries), plus one documentation-generator script that lives +`lib/` currently holds nine Python modules (five of them runnable CLI tools, +four supporting libraries), plus one documentation-generator script that lives under `doc/TRO_Katalog/tro_graphs/`. Together the CLI tools turn a CSV export of the mechanical layout (ILS 2.0) into a material-flow graph, a derived TRO list/diagram, an annotated copy of the BricsCAD drawing, a TRO-JSON read back @@ -57,6 +57,10 @@ Supporting libraries (no CLI of their own, imported by the tools above): - **`lib/tro_overrides.py`** — reads the hand-maintained `%SKEL_CFG%\tro_overrides.ini` (type corrections, open points, TRO merges) that survive re-runs of `tro_flow.py`. See §6a. +- **`lib/tro_geometry.py`** — resolves a separator's host and a switch's exit + count for `tro_flow.py` **directly from the part world-coordinates** (shapely + `STRtree`) instead of from the CSV `Zuordnung`/`Nachbarn` columns, for exports + where those columns have gaps. Only used with `tro_flow.py --geometry`. See §6b. Separate, documentation-only tool (not part of the generator pipeline): @@ -95,7 +99,8 @@ Conventions shared by the CLI tools: output file paths); non-fatal findings are printed as `?`/`!` lines and also do not stop the run. - Requires the packages pinned in `requirements.txt` (`pydantic>=2.0.0`; - `ezdxf>=1.4.0` for `tro_annotate.py` only) — run `bin\install_py.bat` once. + `ezdxf>=1.4.0` for `tro_annotate.py` only; `shapely>=2.1` for + `tro_flow.py --geometry` only) — run `bin\install_py.bat` once. - `--tosvg` needs Graphviz's `dot` (or `neato`, for `tro_flow.py --use-cords`) on `PATH`, or the `GRAPHVIZ_DOT` environment variable pointing at the `dot` executable. `bin/material_flow.bat`/`.sh` and `bin/tro_flow.bat`/`.sh` @@ -277,6 +282,8 @@ colors all come from `lib/tro_catalog.py` — nothing is hard-coded here. | `--tosvg` | — | off | Also render the TRO flow diagram to `.svg`. | | `--use-cords` (alias `--use-coords`) | — | off | Place every TRO at the centroid of the components it was built from and render with `neato -n` (fixed positions) instead of `dot`'s computed layout, so the diagram matches the plant layout. Only has an effect together with `--tosvg`; fails if any TRO has no coordinate. | | `--doc` | — | off | Also write a Markdown report (`_tro_doc.md`) with the TRO list, connections, findings and the full type catalog. | +| `--geometry` | — | off | Determine each separator's host and each switch's exit count (fanout) **from the part world-coordinates** via a shapely `STRtree` (`lib/tro_geometry.py`, see §6b) instead of from the CSV `Zuordnung`/`Nachbarn` columns. Use this for exports where those columns are incomplete (the columns are then bypassed entirely for these two inputs). Requires `shapely>=2.1`. | +| `--geo-tol-mm` | `MM` (float) | catalog default | Only with `--geometry`: the tolerance in mm within which two connection points count as the same transfer point. | **Output** (in `%SKEL_RESULTS%`): `_tro_flow.dot` (always, with `pos` attributes when `--use-cords` was used), `_tro_flow.svg` (with @@ -531,6 +538,35 @@ in doc section 6.3, which catches the common trap: **TRO IDs are running numbers of one run and are only valid for the CSV named in the section.** Swap the data basis and the numbers shift. +## 6b. `tro_geometry.py` — geometric separator-host and switch-fanout (library, no CLI) + +`tro_flow.py` normally derives two of its inputs from the CSV columns +(`material_flow.py::build_graph`): + +``` +Zuordnung (host of the separator) -> which conveyor/Kreisel a separator sits on +Nachbarn / graph edges (fanout) -> how many exits a switch has (1Sep / 1Sep1Swi / 1Sep2Swi) +``` + +For some exports those columns are incomplete — e.g. `hundmM05_1.csv` reports +"nur ein Partner" for several `Strecke` rows, and the older `hundm_export.csv` +failed outright (5 TROs, all `Vario`, 0 connections, all isolated) because +`Zuordnung`/`Nachbarn` could not be resolved. This module derives the same two +values **directly from the part world-coordinates** instead, so the TRO +derivation no longer depends on the quality of those two columns: + +- a shapely `STRtree` over the AS/ES chain ends (K1/K2) of every + Strecke/Gefällestrecke plus the two Kreisel lane-ends; +- `resolve_host_geometric` — `.nearest()` to find the closest host to a + separator; +- `count_geometric_exits` — `.query(..., predicate="dwithin")` to find every + other chain that actually meets at a given point (within a tolerance, mm). + +It is activated by `tro_flow.py --geometry` (via `make_geometric_resolvers`); +`--geo-tol-mm` sets the meeting tolerance. This module knows nothing about +`tro_flow.py` — only `material_flow.py::Element` lists. Requires `shapely>=2.1` +(pinned in `requirements.txt`, needed only for this path). + ## 7. `dxf_registration.py` — CSV↔DXF coordinate registration (library, no CLI) Derives the rigid transform (rotation + offset, no scaling) between the CSV