sps_skel/doc/Python_Scripts.md

# Python Scripts — CLI Tooling Overview

**As of:** 2026-09-17

`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
out of that drawing, and an `FB_Main` SCL skeleton generated from that JSON.

This document is the practical "what does each script do and which switches
does it take" reference. For the underlying domain model (TRO types, JSON
layout concept, I/O-list analysis) see `TRO_Typen.md`, `Json_Layout-Konzept.md`,
`EA-Listen-Analyse.md`, `BricsCAD_TRO_Symbol.md` and
`doc/TRO_Katalog/TRO_Katalog.md`.

## 1. How the pieces fit together

```
CSV export (in %SKEL_DATA%)
   │
   ▼
material_flow.py  ──►  <name>_material_flow.dot / .svg / .md
   │   (read_elements, build_graph — reused by tro_flow.py)
   ▼
tro_flow.py       ──►  <name>_tro_flow.dot / .svg, _tro_doc.md, _tro_errors.md
   │   (derives TROs, using the type catalog in tro_catalog.py)
   ▼
tro_annotate.py   ──►  <name>_annotated.dxf, <name>_registration.json
   │   (also needs the BricsCAD DXF; uses dxf_registration.py for the CSV↔DXF
   │    coordinate offset and tro_catalog.py for marker shape/color per TRO type)
   ▼   (drawing may be hand-edited in BricsCAD before the next step)
tro_extract.py    ──►  <drawing>_tro.json
   │   (reads only the drawing; resolves plant coords via the registration)
   ▼
scl_skeleton.py   ──►  <source>_FB_Main.scl
   (one REGION per TRO; E-planning values left as TODO(E-Planung) gaps)
```

- `material_flow.py` models the material flow of the **mechanical** objects only
  (Gefällestrecke, Strecke, Kreisel).
- `tro_flow.py` is its sister program: it derives the **control objects**
  (TROs) from the same graph and draws their flow instead.
- `tro_annotate.py` takes the TROs from `tro_flow.py` and burns them into a
  **copy** of the BricsCAD drawing as attributed blocks (never touches the
  original).

Supporting libraries (no CLI of their own, imported by the tools above):

- **`lib/tro_catalog.py`** — the single source of truth for TRO types: short
  name, Siemens FB block, sub-components and counts, color group, CAD marker
  shape.
- **`lib/dxf_registration.py`** — derives, verifies and persists the rigid
  (rotation + offset) transform between the CSV export's coordinate system and
  the DXF drawing's.
- **`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):

- **`doc/TRO_Katalog/tro_graphs/gen_tro_graphs.py`** — regenerates the
  schematic per-type SVGs, the edge-type legend and the per-controller
  (UH01–UH05) topology graphs embedded in `TRO_Katalog.md`, built from
  `doc/TRO_Katalog/connect.ini`.

## 2. Running the scripts

Each CLI tool is invoked through its `bin/<name>.bat` (Windows) / `bin/<name>.sh`
(Linux/macOS) wrapper, which:

1. calls `setenv` to set `SPS_SKEL`, `SKEL_DATA`, `SKEL_RESULTS`, `SKEL_CFG`,
   `SKEL_LIB` and prepend `SKEL_LIB` to `PYTHONPATH`;
2. activates `.venv` if it exists (`bin/install_py` creates it);
3. runs the module with `py` (falling back to `python`).

```bat
bin\material_flow.bat --file mubea.csv --tosvg --use-cords --doc
bin\tro_flow.bat --file mubea.csv --tosvg --use-cords --doc
bin\tro_annotate.bat --file mubea.csv --dxf 500573_60_1.dxf --flow --fb --legend
```

(`--use-cords` lays both graphs out at the real plant coordinates; drop it for
Graphviz's computed left-to-right arrangement.)

Conventions shared by the CLI tools:

- `--file` / `--dxf` accept either a bare filename — resolved against
  `%SKEL_DATA%` — or a full path.
- All generated output is written to `%SKEL_RESULTS%`.
- `tro_annotate.py` additionally persists the verified CSV↔DXF coordinate
  offset to `%SKEL_CFG%\dxf_registration.json`.
- Every run prints a `====` bordered report to stdout (counts, warnings,
  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; `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`
  check for the right engine up front when `--tosvg` is passed and print an early
  `WARNUNG` if it's missing (`GRAPHVIZ_DOT` only covers `dot`, not `neato`) — this
  is just a heads-up before the CSV is even parsed; the Python script still runs
  and reports the same failure in detail (exit code `2`) if the SVG step is reached.

## 3. `material_flow.py` — material-flow graph of the mechanical layout

Reads the CSV export and builds a directed graph of the mechanical objects:

- **Gefällestrecke** / **Strecke** (conveyor segments) → one node each.
- **Kreisel** (rotary/turntable) → two nodes (`-L` / `-R`), linked by the
  `Drehrichtung` feature (`UZS` = clockwise = right→left, `GUZ` =
  counter-clockwise = left→right).
- **Separator** / **Scanner** → no node of their own; shown via `Zuordnung`
  (assignment) on the label of their owning node.
- **`TrackIds`** (added Sept. 2026): a Kreisel/Strecke/Gefällestrecke row lists the
  `TeileId`s of every fine element (Separator, Scanner, Weiche, Ein-/Ausschleuselement,
  BTMT Be-/Entladung) that belongs to it. `Zuordnung` on the fine element itself stays
  authoritative whenever it resolves to a real node — it's more precise than `TrackIds`
  for a separator sitting right at a Kreisel↔Strecke boundary, which `TrackIds` lists
  under *both* neighbouring containers (normal, not a conflict). `TrackIds` only fills
  gaps `Zuordnung` can't resolve: a bare Kreisel id with no lane suffix (attached to
  *both* lanes then), a missing/empty `Zuordnung`, or (for BTMT stations, which never had
  a reliable `Zuordnung`) the nearest-neighbour distance guess this replaces. An older
  export without the `TrackIds` column behaves exactly as before. See `_build_track_owners`/
  `_track_owner`/`_attach_devices`/`_attach_stations` in `lib/material_flow.py`.
- **Einschleuselement** / **Ausschleuselement** / **Weiche** (from the richer export)
  → no node of their own; they supply the **direction** of the Kreisel↔Strecke edges
  (`Ausschleusung` = Kreisel→Strecke at the strecke's *Anfang*, `Einschleusung` =
  Strecke→Kreisel at its *Ende*, read from their `Kreisel`/`Strecke`/`Streckenende`
  `Merkmale`) and **mark the Weiche** on a Kreisel↔Kreisel link. A strecke whose two
  ends touch the *same* Kreisel (return loop) is split across that Kreisel's two lanes.
  This makes Kreisel↔Strecke direction deterministic instead of height-inferred.
- **BTMT Be-/Entladestation** (entry/exit points) → one node each, recognised by
  `TeileArt`/`Bezeichnung` containing `Beladung`/`BTMT-Beladung`/`Eingang` (→ **entry**, a
  material *source*) or `Entladung`/`SC_Entladung`/`Abwurf`/`Ausgang` (→ **exit**, a *sink*).
  Some exports name these same entry/exit points plainly `Eingang`/`Ausgang` instead of the
  BTMT-specific terms — same role, recognised the same way.
  An entry gets an outgoing edge, an exit an incoming edge, to the object its owning
  Kreisel/Strecke names it under in `TrackIds` (a Kreisel picks the Eingangs-/
  Ausgangsbahn from `Drehrichtung`, same as `_weiche_lane_roles`); failing that, to
  the object named in its own `Nachbarn` (ignoring another station — BTMT `Nachbarn`
  often just names nearby separators or the paired station, not a real flow target);
  failing that, the nearest Kreisel, then the nearest object by 2-D distance, each
  with a note printed. Recognition is **sps_skel-side only** — nothing in dxfmakros
  changes; it simply activates when such a row appears in the CSV.

> **Note on BTMT / entry-exit data.** dxfmakros' `EXPORTCSV` currently does **not**
> emit the BTMT stations (their block names match no export pattern; documented as
> *"Export noch offen"*). Until that is addressed, a freshly exported `mubea.csv`
> will contain the 61 conveyor items but **no** BTMT rows, so no entry/exit nodes
> appear. The recognition above is ready for when BTMT rows are present.

In the rendered graph, **parallel Gefällestrecken between the same two Kreisel
lanes with the same slope** (`Hoehe_Von_mm`/`Hoehe_Bis_mm`) — a typical
line-storage bank — are drawn as a **single** Gefällestrecke-styled box with a
double border (`peripheries=2`) instead of one box per line. Its label states
the id range and count of the merged lines plus the combined Separator/Scanner
id ranges, e.g. `Gefaellestrecke 0017 - 0036 (20x)` / `Separator (20): 0037 -
0056`. This is purely a rendering simplification (`_group_parallel_gefaelle`
in `lib/material_flow.py`) — the underlying graph, `--doc` report and
`--connect` output are unaffected and still list every line individually.

Flow direction between a Kreisel and a Strecke/Gefällestrecke is set from the
**Ausschleus-/Einschleuselement** at each end (`_apply_transfers`): the
Ausschleuselement is the Kreisel outlet (Kreisel → Strecke, start), the
Einschleuselement the inlet (Strecke → Kreisel, end). A conveyor whose two ends
dock on the *same* Kreisel (a return line — Eingang and Ausgang on one Kreisel)
is drawn as **two** edges — one onto each lane (`0006-L → VF` on the way out,
`VF → 0006-R` on the way back) — so it is never flat/undetermined. The transfer
element names its conveyor via the `Strecke` **or** `Foerderer`/`Förderer`
attribute (both are read).

Where no transfer element resolves the direction, `drive_uphill` applies the
physics rule: **only a pure Gefällestrecke** takes its direction from the height
(`Hoehe_Von_mm`/`Hoehe_Bis_mm` → flows downhill; a GF with no height runs downhill
by definition). A Förderer (VF) can convey up *or* down and a `Strecke` is often
a mixed GF/VF chain, so **height is not a direction indicator for them** — they
use an unambiguous `Antriebfahrtrichtung` (exactly `"Auf"`/`"Ab"`, not a mixed
list like `"horizontal,horizontal,Auf"`) and otherwise stay undetermined
(direction is expected to come from the AS/ES ends). Only what nothing resolves
is drawn bidirectional and reported as a warning.

Entry/exit stations are hung on the Kreisel **lane** they belong to
(`_attach_stations`): first the Kreisel whose `TrackIds` umlauf lists the station,
then the entry-/exit-lane from its `Drehrichtung` (UZS → entry lane R / exit lane
L, GUZ reversed). Sources (`Beladung`/`Eingang`) get `Station → lane`, sinks
(`Entladung`/`Ausgang`) `lane → Station`. Neighbours that aren't flow objects
(another station, a separator) are skipped, so two BTMT points no longer get
wired to each other.

`Eingang`/`Ausgang` are the **generic symbols** for the concrete BTMT stations
`Beladung`/`Entladung` (same source/sink role). When a symbol lies almost on top
of a BTMT station of the same role (≤ `STATION_MERGE_MM` = 600 mm, `x`/`y` from
the `Position` column), only **one** node is drawn: the concrete BTMT station is
kept, the generic symbol is swallowed (`_merge_station_symbols`). A standalone
`Eingang`/`Ausgang` with no nearby BTMT partner is drawn as its own green/red
node. `--doc` additionally cross-checks stated `Anzahl_Separator`/`Anzahl_Scanner`
counts against what was actually attached.

`--track` builds a second, finer-grained graph in addition to the one above:
Separator, Ausschleus-/Einschleuselement, Weiche and the entry/exit points
(BTMT Be-/Entladung, Eingang/Ausgang) each become their own node (they supply
no node in the graph described above), showing the actual branch/merge/crossing
topology between Kreisel rather than just the mechanical objects.

The ordering comes **directly from the `TrackIds` CSV column** (`Element.track_ids`):
every container — Kreisel, Strecke, Gefällestrecke — carries the ordered list of
the track elements lying on it, computed by the dxfmakros export
(`dxfmakros/doc/csv-export.md`). `build_track_graph` draws one directed chain per
container from that list:

- **Kreisel** → the circular umlauf in `Drehrichtung` order (the list is already
  angle-sorted); consecutive entries are linked and the last closes back onto the
  first (a real, closed loop). Edges are drawn light-blue ("Umlauf").
- **Strecke / Gefällestrecke** → the linear chain `AS → SEP… → ES` in build
  order, oriented by its ends (Ausschleuselement = start, Einschleuselement =
  end). Edges are drawn blue ("Bahn").
- An element listed in **two** containers (an AS/ES sits in its Strecke *and* in
  the docked Kreisel's umlauf; a Kreisel-Kreisel Weiche sits in both Kreisel) is
  the **same node** and stitches the containers together automatically — no
  `Nachbarn`-based role/feedback heuristic any more.
- A track element that appears in **no** `TrackIds` list (e.g. a free Separator
  the export didn't chain) is hung off a dashed **placeholder** for its
  `Zuordnung` with an "unbestimmt" edge and a warning — order on that Bahn left
  open. If the CSV has no `TrackIds` column at all (older export), every track
  element falls into this case.

See `doc/track.md` for the fuller derivation notes.

| Switch | Argument | Default | Meaning |
|---|---|---|---|
| `--file` | `NAME` | `export.csv` | CSV input file, resolved against `%SKEL_DATA%`, or a full path. |
| `--tosvg` | — | off | Also render the `.dot` file to `.svg` via Graphviz `dot`. |
| `--use-cords` (alias `--use-coords`) | — | off | Place every node at its plant coordinate and render with `neato -n` (fixed positions) instead of `dot`, so the material graph matches the plant layout — the same option `tro_flow.py` has. The two Kreisel lanes (`-L`/`-R`) are nudged apart by `LANE_NUDGE_MM`; scale is `COORD_SCALE` (0.25 pt/mm, identical to `tro_flow.py`). Only has an effect together with `--tosvg`; fails (exit 1) if any flow node has no coordinate. |
| `--doc` | — | off | Also write a Markdown report (`<name>_material_flow.md`) with object list, connections and plausibility findings. |
| `--connect` | — | off | Also write the topology as `<name>_connect.ini` (item/flow level): `[…nodes]` (Kreisel lanes, Strecke, Gefällestrecke), `[…connections]` with a `kind` per edge (`normal`/`umlauf`/`weiche`/`einschleusung`/`ausschleusung`), and `[…externals]` — the BTMT entry/exit if present, otherwise the open lane-ends listed as entry candidates. A hand-editable bridge into the TRO step, styled after `doc/TRO_Katalog/connect.ini`. |
| `--show-bbs` | — | off | Also write `<name>_bbs.svg`: a plain 2-D top-down view of every CSV row (not just flow nodes — Separator/Scanner/Ein-/Ausschleuselement too), one axis-aligned rectangle per row from the `Position` column (its center, X/Y) and the `Boundingbox` column (its width/depth, X/Y — the Z extent is ignored), with the row's `Bezeichnung` centered in it. A Kreisel is the one exception: instead of one rectangle for the whole ring, it's split into its two Bahn L/R halves (`_kreisel_lane_rects()` — short axis divided in half, `Zuordnung`-majority-vote decides which half is L vs R), each drawn and labelled separately; its K1–K4 points (with `--show-kx`) still belong to the Kreisel as a whole and are drawn once, not per half. No rotation, no Graphviz — hand-built SVG; the `viewBox` stays in plant millimetres (Y flipped so plant "up" renders as screen "up") but the printed page size is scaled to DIN A3 (landscape or portrait, whichever matches the layout's aspect ratio) instead of the plant's real-world extent. Larger objects are drawn first so small ones (Separator, Scanner, …) stay visible on top. |
| `--show-kx` | — | off | Only valid together with `--show-bbs` (else exit 1). Additionally draw each object's connection coordinate systems K1–K4 into the `_bbs.svg`: the K1–K4 columns are 12-char base64 strings (three 24-bit fixed-point values `x,y,z`, factor 10, `csv:trans-encode` in `dxfmakros/Lisp/export.lsp`) decoded to a plant-mm X/Y. Each present K-point is drawn as a small red cross (two lines) with a small `K1`…`K4` label, and consecutive points are joined `K1→K2→K3→K4` by a blue line. Empty K columns are skipped, so an object with only K1/K2 gets two crosses and one link. |
| `--track` | — | off | Additionally write the finer Separator/Ausschleus/Einschleus/Weiche graph described above (`<name>_track.dot`, and `<name>_track.svg` with `--tosvg`). Does not change the normal `_material_flow.*` output. See `doc/track.md`. |
| `--chain-graph` | — | off | Write **one** to-scale "chain-/Lageplan" SVG of the **grobe Objekte** (big items) as `<name>_chain.svg`: every Kreisel split into its Bahn L/R halves (`_kreisel_lane_rects()`, same to-scale split as `--show-bbs`) and every Strecke/Gefällestrecke ("VF"/"GF") drawn as rectangles at their real `Position`/`Boundingbox` coordinates, connected by the already-resolved top-level `graph.edges` (material flow, Kreisel-Umlauf, unresolved). Step 1 of the new chain-graph build-up — no Separator/Scanner/Weiche/Ausschleus-/Einschleuselement and no BTMT Ein-/Ausgang yet; an edge touching a node that isn't drawn (e.g. a station) is simply skipped. Hand-built SVG, no Graphviz. |

**Output** (in `%SKEL_RESULTS%`): `<name>_material_flow.dot` (always, with `pos`
attributes when `--use-cords` was used), `<name>_material_flow.svg` (with `--tosvg`),
`<name>_material_flow.md` (with `--doc`), `<name>_connect.ini` (with `--connect`),
`<name>_bbs.svg` (with `--show-bbs`), `<name>_track.dot` / `<name>_track.svg` (with `--track`),
`<name>_chain.svg` (with `--chain-graph`).

**Exit codes:** `0` ok · `1` input/CLI error · `2` SVG rendering failed
(Graphviz).

## 4. `tro_flow.py` — derive and draw the TROs

Sister program to `material_flow.py` — same `--file`/`--tosvg`/`--doc`
switches, but instead of the mechanical objects it derives the **TROs**
(Transfer Route Objects, i.e. control-logic units) from the same graph and
draws *their* flow. Derivation rules (see
`doc/500573_Mubea/TRO_Identifikation_500573.md` for the source analysis):

| Host of the separator | TRO type |
|---|---|
| Gefällestrecke, ≥ 2 lines sharing an in-/outfeed | `PinStore_Auto` (one block per line group) |
| Gefällestrecke, single line | `1Sep` |
| Strecke (driven) | `Vario` (one per segment) |
| Kreisel lane | `1Sep` |
| — additionally: 2 or 3 outgoing paths | upgraded to `1Sep1Swi` / `1Sep2Swi` |

A scanner mounted on a separator does **not** change the type (stays `1Sep`);
the `1Sep_SSCC` special case can't be recognized from the mechanical layout
alone and is only raised as a finding. TRO types, FB blocks, sub-components and
colors all come from `lib/tro_catalog.py` — nothing is hard-coded here.

| Switch | Argument | Default | Meaning |
|---|---|---|---|
| `--file` | `NAME` | `export.csv` | CSV input file, resolved against `%SKEL_DATA%`, or a full path. |
| `--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 (`<name>_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%`): `<name>_tro_flow.dot` (always, with `pos`
attributes when `--use-cords` was used), `<name>_tro_flow.svg` (with
`--tosvg`), `<name>_tro_doc.md` (with `--doc`), `<name>_tro_errors.md` (only
if TROs are unconnected or of an unknown type).

**Exit codes:** `0` ok · `1` input/CLI error · `2` SVG rendering failed
(Graphviz) · `3` TRO validation errors found (error file written).

## 5. `tro_annotate.py` — burn the TROs into a copy of the CAD drawing

Takes the CSV export, the original BricsCAD drawing (DXF) and the TROs
derived the same way as `tro_flow.py`, and writes a **copy** of the drawing
with:

- one colored marker block per TRO, each type with its own shape (circle,
  triangle, square, diamond, …; see `TroSymbol` in `tro_catalog.py`) so types
  are distinguishable even without color;
- visible attributes `ID`, `TYPE` (and `FB_BLOCK` with `--fb`); hidden
  attributes `ITEMS`, `CONFIDENCE`, `SEPARATORS` for downstream tooling;
- optional directional flow arrows between TROs (`--flow`) and a legend
  (`--legend`).

The original drawing is never modified. Everything this tool adds lives on its
own `TRO_`-prefixed layers and carries XDATA under the app id
`SPS_SKEL_TRO`; a re-run removes exactly those tagged objects (not by layer
name) and rebuilds them, so hand-drawn content on the same layers survives.

Once at least one marker of a given type has been annotated, the `dxfmakros`
BricsCAD menu (`SSG_LIB > TRO`) can insert further markers of that type by
hand — `TRO_INSERT` reuses the `TRO_SYM_<Typ>` block definition this tool
created and only asks for a point, an id and (optionally) a different type;
`TRO_EDIT` changes `ID`/`TYPE` on an existing marker. Neither command draws
new shapes — a type with no prior annotated instance in the drawing must be
run through this tool at least once first.

CSV and DXF live in different coordinate systems; the offset between them is
handled by `dxf_registration.py` — derived once, verified on every run, and
cached per CSV/DXF filename pair in `%SKEL_CFG%\dxf_registration.json` unless
overridden.

| Switch | Argument | Default | Meaning |
|---|---|---|---|
| `--file` | `NAME` | `export.csv` | CSV export, resolved against `%SKEL_DATA%`, or a full path. |
| `--dxf` | `NAME` | — | Original drawing as DXF (path, or name resolved against `%SKEL_DATA%`). Required unless `--emit-lisp` is used alone. DWG is not supported. |
| `--out` | `NAME` | `<csv-stem>_annotated.dxf` | Output filename in `%SKEL_RESULTS%`. |
| `--flow` | — | off | Draw directional flow arrows between the TROs. |
| `--fb` | — | off | Show the Siemens FB block name as a visible attribute on the marker. |
| `--legend` | — | off | Draw a legend of the color groups. |
| `--marker-size` | `MM` (float) | `300.0` | Marker radius in mm. |
| `--text-height` | `MM` (float) | `220.0` | Text height in mm. |
| `--layer-prefix` | `P` | `TRO_` | Prefix for the layers this tool creates. |
| `--offset` | `DX,DY` | — | Set the CSV↔DXF offset by hand instead of deriving/loading it. |
| `--re-register` | — | off | Re-derive the coordinate offset even if a verified one is already cached in `%SKEL_CFG%`. |
| `--max-residual` | `MM` (float) | `600.0` | Largest residual error of the coordinate registration that is still accepted; above it the run fails (exit 4). |
| `--check` | — | off | Dry run: only analyze and report, write no output file. |
| `--emit-lisp` | — | off | Regenerate `cad/tro_types.lsp` (the type list for the `TRO_INSERT`/`TRO_EDIT` dialogs) from `tro_catalog.py` and exit — no `--dxf` needed. Written under `%DXFM_LISP%` if set (next to the `dxfmakros` SSG_LIB modules that provide the dialogs), otherwise under `<SPS_SKEL>/cad`. |

**Output** (in `%SKEL_RESULTS%`, unless `--check`): `<name>_annotated.dxf`,
`<name>_registration.json` (the coordinate transform used, with its proof).

**Exit codes:** `0` ok · `1` input/CLI error · `4` coordinate registration
could not be proven (or exceeds `--max-residual`) — resolve with `--offset` or
by raising `--max-residual`.

## 5a. `tro_extract.py` — read the TROs back out of the drawing into JSON

The counter-direction to `tro_annotate.py`:

```
tro_annotate.py   CSV + derivation  ->  markers in the drawing
tro_extract.py    drawing           ->  JSON
```

It reads **only the drawing**, never the CSV. So what comes back is what is
actually in the DXF — including anything adjusted by hand in BricsCAD (markers
moved, type changed via `TRO_EDIT`). That is the point: after a review, the
drawing is the current state, not the export.

It finds the objects `tro_annotate.py` tagged with XDATA (AppID
`SPS_SKEL_TRO`): the `TRO_SYM_<type>` block references (attributes
`ID`/`TYPE`/`ITEMS`/`CONFIDENCE`/`SEPARATORS`, plus `FB_BLOCK` when annotated
with `--fb`), the flow arrows (`"<from>-><to>"`), and the open-point markers
(`"OFFEN:<name>"`). Each TRO also gets `predecessors`/`successors` computed
from the arrows.

Coordinates appear twice: `positionDxf` is the drawing coordinate,
`position` the plant coordinate. The conversion uses the registration written
by `tro_annotate.py` (`<stem>_registration.json`; the `_annotated` suffix and
the file's own `dxf_file` field are both taken into account when locating it).
If no registration is found, `position` is **left out rather than guessed**,
and a warning says so.

Switches: `--dxf NAME` (default `export_annotated.dxf`, looked up in
`%SKEL_RESULTS%`), `--out NAME` (default `<drawing>_tro.json`). Exit codes:
`0` ok, `1` input error, `2` no TRO markers in the drawing.

`fbType` is worth one note: unless the drawing was annotated with `--fb`, the
FB block is not an attribute in the DXF. It is then looked up from
`tro_catalog.py` and marked `"fbTypeFrom": "tro_catalog"` — so a consumer can
tell a value that came out of the drawing from one that was resolved.

## 5b. `scl_skeleton.py` — generate the FB_Main skeleton as SCL

Last step of the chain:

```
material_flow.py  objects    -> material flow
tro_flow.py       flow       -> TROs
tro_annotate.py   TROs       -> markers in the drawing
tro_extract.py    drawing    -> JSON
scl_skeleton.py   JSON       -> FB_Main.scl
```

Produces a **skeleton, not a running program**: one `REGION` per TRO with the
instance call and every parameter line in the right order, following the real
call sites in `doc/TRO_Katalog/scl_templates/*.scl`.

**It will not compile as delivered, and that is deliberate.** Every value that
has to come from the electrical planning is a visible gap marked
`TODO(E-Planung)` — never an invented value, because a plausible-looking wrong
sensor address is far worse than an empty one. Grep for that marker and nothing
is missed.

| filled from the layout | left as `TODO(E-Planung)` |
|---|---|
| REGION order (material flow), instance list, FB type per TRO | sensor/actuator addresses (`cInBG`, `MB`, `MA`) |
| number of separator / switch / scanner parameter blocks | separator and switch numbers, `cMainTro` |
| `nTo1Destinations` when the TRO has exactly one switch | jam areas (`DB_JamArea…`) |
| destination list per switch exit (graph reachability) | times marked "pruefen" |
| cross-reference to the layout parts (separator numbers, coordinate) | |

Two derivations worth knowing about. **The destination list per switch exit** is
computed by walking the TRO graph from each exit without going back through the
switch — that is exactly what `FC_Direction` needs to map destination to
direction, and it does *not* require the I/O list. And **`nTo1Destinations`** is
only auto-filled for a single-switch TRO; where several switches share the
exits, how they divide them is a planning decision, so it stays a gap rather
than a guess.

Switches: `--json NAME` (default `export_tro.json`), `--out NAME` (default
`<source>_FB_Main.scl`), `--start TRO`. The last one matters while the plant has
no loading/unloading station: the flow is then a closed loop with no entry, so
the order has to be broken somewhere arbitrary. The chosen start and the reason
are recorded in the file header.

## 6. `tro_catalog.py` — TRO type catalog (library, no CLI)

The single source of truth for everything needed to generate or draw a TRO
type: short name (as used in `FB_Main`/`connect.ini`), Siemens FB block,
sub-components and their counts, color group (for Graphviz/Mermaid/CAD) and
CAD marker shape. **Eleven** types are defined in `TRO_CATALOG`. Ten of them are
verified against `data/*.scl` where the source is vendored locally, and against
`TRO_Typen.md`'s mapping table otherwise (see the module docstring,
`CATALOG_AS_OF`, for provenance per type).

> **`2Sep2Swi` is the exception — it is not backed by any SCL.** It was added on
> 2026-08-12 for project 500573 (Mubea), to model the transfer point at the
> Kreisel2/Kreisel1 touch as a single control object with 2 separators,
> 2 scanners and 2 switches. **`FB_ILS_MTRO_2Sep2Swi` does not exist** in this
> repository or in `doc/TRO_Katalog/scl_templates/`, and has to be created in
> the ILSLib — otherwise a future SCL generator will emit a call to a missing
> block. The closest verified type is `2Sep1Swi` (2 separators, 2 scanners,
> **1** switch), which matches the hardware actually present in that export.

Everything is a Pydantic v2 model
(`TroDefinition`/`TroStyle`), so it validates on every assignment and comes
with `model_dump()`/`model_validate()` for the planned JSON layout model for
free. Consumed by `tro_flow.py` and `tro_annotate.py`; not run directly.

## 6a. `tro_overrides.py` — manual corrections to the derived TROs (library, no CLI)

`tro_flow.py` derives TRO types from the mechanical layout alone. Some things
are simply not in the CSV export: a switch that the export does not carry, a
scanner that lifts the type to `1Sep_SSCC`, or a spot that a walkthrough
identified as its own transfer point. Those findings come from a site review,
and they must survive the next run — the `.dot`/`.svg`/`.md`/`.ini` outputs are
all regenerated from scratch every time, so editing them is not an option.

They therefore live in **`%SKEL_CFG%\tro_overrides.ini`** (hand-maintained,
never generated). Section names are prefixed with the CSV file they apply to,
so several plants — and several exports of the same plant — can coexist:

```ini
[export.csv.tro.SEP0011]       ; type correction, keyed on separator 0011
type       = 1Sep1Swi          ; a type from lib/tro_catalog.py
reason     = Weiche vor Ort bestaetigt (Review 2026-08-10)
confidence = bestaetigt        ; default when omitted

[mubea.csv.openpoint.Qualitaetskontrolle]   ; explicitly NOT a TRO yet
x = -1026.00                   ; plant coordinates in mm (CSV system)
y = 5250.05
z = 1478.50
expect     = 1Sep1Swi          ; type expected here
belongs_to = TRO09             ; TRO that owns the part today
note       = ...
```

A fourth kind folds several derived TROs into one control object:

```ini
[export.csv.merge.Beruehrpunkt_K2_K1_gesamt]
type       = 2Sep2Swi
separators = 0005, 0057                  ; at least two, addressed by separator
host       = 0002-R                      ; primary flow node; the others are kept
label      = ...
reason     = ...
```

A third kind creates a TRO the derivation missed entirely:

```ini
[export.csv.split.Beruehrpunkt_K2_K1]   ; pull a separator out of its TRO
type       = 1Sep1Swi
separators = 0057                        ; comma-separated
scanners   =                             ; optional, follow the separators
host       = 0001-L                      ; flow node the new TRO sits on
label      = ...
reason     = ...
```

Three kinds of entry, deliberately different in weight:

- **`tro`** — changes the type of an already-derived TRO. Applied after the
  TRO numbers are assigned (the sections address them by ID) and before the FB
  block and component list are pulled from the catalog, so the type change
  drags both along. A manually set type also suppresses the automatic
  "check whether `1Sep_SSCC` is needed" hint for that TRO.
- **`split`** — creates a new TRO from separators taken out of an existing one.
  For transfer points the derivation misses because the separator's
  `Zuordnung` points at a conveyor (Strecke/Gefaellestrecke) instead of the
  Kreisel lane it actually switches on. Applied *before* the numbers are
  assigned, so the new TROs slot into the normal ordering — which means
  **adding a split renumbers everything after it**. That is exactly why type
  corrections should be keyed `SEP<number>`, not `TRO<number>`.
- **`merge`** — folds several TROs into one. Runs *after* the splits, so a
  freshly split-out TRO can be part of a merge. The first affected TRO survives
  and absorbs the others' separators, scanners and hosts; `host` picks which
  flow node is primary, the rest stay attached so the linking still sees both
  sides of a transition. Like splits, this renumbers.
- **`openpoint`** — a spot reported in a review that is **not** turned into a
  TRO. The structure stays untouched; the point is only marked, in the doc
  (section 6) and in the annotated drawing on layer `TRO_OPENPOINT` as a red
  crossed circle with plain-text label. This keeps "derived" and "asserted"
  distinguishable until the spot has been checked in BricsCAD.

Consumers: `tro_flow.py` (type corrections + doc section 6), `tro_annotate.py`
(corrected marker types + open-point markers), `material_flow.py` (writes the
`[<plant>.manual]` section into `connect.ini`). Unknown TRO IDs and types are
not applied silently — they are reported as warnings in the console output and
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
export's and the DXF drawing's coordinate systems, by voting on the offset
between same-role anchor points (`Separator` and `Scanner` blocks, see
`ANCHOR_BLOCKS`), refining the best candidates via a Procrustes fit, and
picking the candidate with the most exact matches. Raises `RegistrationError`
if fewer than `MIN_INLIERS` (5) exact matches are found for any candidate.
Persists/loads the verified transform per CSV/DXF filename pair under
`%SKEL_CFG%\dxf_registration.json`. Used exclusively by `tro_annotate.py`; not
run directly.

`ANCHOR_BLOCKS` holds **name patterns** (fnmatch, case-insensitive), not fixed
names, because two naming worlds occur in this project:

| Drawing | Separator blocks | Scanner blocks |
|---|---|---|
| original customer drawing (`500573_60_1.dxf`) | `S-SP`, `S-LP` | `SCAN` |
| macro-generated (`Mubea.dxf`, from dxfmakros) | `Separator_SP_2D`/`_3D` | `Scanner_2D`/`_3D` |

`Staustrecke_Separator_SP_*` is deliberately **not** an anchor: it is a
conveyor module with a built-in separator, so its insertion point is the module
origin rather than the separator, which would feed a second cluster — offset by
exactly that distance — into the vote.

Note that the two roles can carry slightly different systematic offsets (in
`Mubea.dxf`: separators land on +100/0, scanners on +400/0), so a mixed fit
shows a larger `residual_max` than either role alone. That is expected; the
mean residual is the number to watch, and only pairs within `FIT_TOL` (50 mm)
enter the Procrustes fit.

## 8. `gen_tro_graphs.py` — documentation image generator (doc tooling, not part of the generator)

Lives under `doc/TRO_Katalog/tro_graphs/`, not `lib/` — it produces the
pictures embedded in `TRO_Katalog.md`, not generator output. Two families:

1. one schematic SVG per TRO type showing the block with its *possible*
   connection edges (`normal`/`dir2`/`dir3`/`bypass`/`finger`/`plc`/`extern`,
   each with its own color and line style), plus a shared `edge_legend.svg`;
2. one Graphviz topology graph per controller (`uh01`..`uh05`), built from
   `doc/TRO_Katalog/connect.ini`, rendered to SVG.

No command-line switches — run it directly and re-run after editing
`connect.ini`:

```
py doc/TRO_Katalog/tro_graphs/gen_tro_graphs.py
```

Needs Graphviz `dot` on `PATH` (or at the default Windows install location);
without it the `.dot` files are still written, just not rendered to `.svg`.