sps_skel/doc/Commandlines.md

# Command Lines — Overview

**As of:** 2026-10-05

Every command this project provides, in one place. This is the quick reference;
for what each tool derives, how, and the full description of every switch, see
[`Python_Scripts.md`](Python_Scripts.md).

All commands live in `bin/` as a `.bat` (Windows) / `.sh` (Linux/macOS) pair.
Examples below use the Windows form; on Linux/macOS replace `bin\x.bat` with
`bash bin/x.sh` (or `source bin/x.sh` where noted).

## 1. Environment commands

These set up or enter the environment. They never run a Python tool.

| Command | Purpose |
|---|---|
| `bin\setenv.bat` / `source bin/setenv.sh` | Sets `SPS_SKEL` and `SKEL_BIN/LIB/CFG/DATA/DOC/LOG/RESULTS/EXAMPLES/TESTS`, prepends `SKEL_LIB` to `PYTHONPATH`, creates missing folders. Windows: `--keep-open` pauses at the end. |
| `bin\install_py.bat` / `bash bin/install_py.sh` | One-time: creates `.venv` and installs `requirements.txt`. Does nothing if `.venv` already exists. |
| `bin\activate_venv.bat` / `source bin/activate_venv.sh` | Each session: sets the environment and activates `.venv` (error if missing — run `install_py` first). |
| `bin\get_cmd.bat` / `bash bin/get_cmd.sh` | Opens a new shell with the environment variables set. |

## 2. Pipeline tools

The five CLI tools, in pipeline order. Each wrapper sets the environment,
activates `.venv` if present and runs `lib/<name>.py` with all arguments passed
through. Every tool accepts `--help`.

```
CSV ─► material_flow ─► tro_flow ─► tro_annotate ─► [edit in BricsCAD] ─► tro_extract ─► scl_skeleton
                                      (+ DXF)                              (DXF only)      (JSON → SCL)
```

Shared conventions:

- Input names (`--file`, `--dxf`) are a bare filename resolved against
  `%SKEL_DATA%`, or a full path. `tro_extract`/`scl_skeleton` look up their
  input in `%SKEL_RESULTS%` instead (it is the output of the previous step).
- All output goes to `%SKEL_RESULTS%`.
- `--tosvg` needs Graphviz `dot` (`neato` with `--use-cords`) on `PATH`, or
  `GRAPHVIZ_DOT` pointing at `dot`.

### 2.1 `material_flow` — material-flow graph of the mechanical objects

Input: CSV export. Details: [`Python_Scripts.md` §3](Python_Scripts.md#3-material_flowpy--material-flow-graph-of-the-mechanical-layout).

| Switch | Argument | Default | Effect |
|---|---|---|---|
| `--file` | `NAME` | `export.csv` | CSV input. |
| `--tosvg` | — | off | Also render `.svg` via Graphviz. |
| `--use-cords` / `--use-coords` | — | off | Place nodes at plant coordinates (`neato -n`). Only with `--tosvg`. |
| `--doc` | — | off | Write Markdown report `<name>_material_flow.md`. |
| `--connect` | — | off | Write topology as `<name>_connect.ini`. |
| `--show-bbs` | `flow` \| `all` | `flow` if given without value | Write top-down view `<name>_bbs.svg` (no Graphviz). `all` also draws VF/GF chain detail rows. |
| `--show-kx` | — | off | Only with `--show-bbs`: draw connection points K1–K4. |
| `--track` | — | off | Write fine-grained track graph `<name>_track.dot` (`.svg` with `--tosvg`). |
| `--chain-graph` | — | off | Write chain/layout plan of the coarse objects (`<name>_chain.svg` / `.dot`). |
| `--graphtype` | `coarsebox` \| `compound` \| `subgraph` | `coarsebox` | Only with `--chain-graph`: rendering method. |

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

```bat
bin\material_flow.bat --file mubea.csv --tosvg --use-cords --doc
bin\material_flow.bat --file HundM05.csv --show-bbs all --show-kx
bin\material_flow.bat --file HundM05.csv --chain-graph --graphtype subgraph --tosvg
```

### 2.2 `tro_flow` — derive and draw the TROs

Input: CSV export. Details: [`Python_Scripts.md` §4](Python_Scripts.md#4-tro_flowpy--derive-and-draw-the-tros).

| Switch | Argument | Default | Effect |
|---|---|---|---|
| `--file` | `NAME` | `export.csv` | CSV input. |
| `--tosvg` | — | off | Also render the TRO flow diagram as `.svg`. |
| `--use-cords` / `--use-coords` | — | off | Place TROs at plant coordinates (`neato -n`). Only with `--tosvg`. |
| `--true-scale` | — | off | Only with `--use-cords`: draw to scale (default shortens empty stretches > 1500 mm). |
| `--doc` | — | off | Write Markdown report `<name>_tro_doc.md`. |
| `--connect` | — | off | Write TRO topology as `<name>_tro_connect.ini`. |

Exit codes: `0` ok · `1` input/CLI error · `2` SVG rendering failed ·
`3` TRO validation errors (`<name>_tro_errors.md` written).

```bat
bin\tro_flow.bat --file mubea.csv --tosvg --use-cords --doc
```

### 2.3 `tro_annotate` — burn the TROs into a copy of the drawing

Input: CSV export + original BricsCAD DXF. The original is never modified.
Details: [`Python_Scripts.md` §5](Python_Scripts.md#5-tro_annotatepy--burn-the-tros-into-a-copy-of-the-cad-drawing).

| Switch | Argument | Default | Effect |
|---|---|---|---|
| `--file` | `NAME` | `export.csv` | CSV input. |
| `--dxf` | `NAME` | — | Original drawing (DXF). Required unless `--emit-lisp` is used alone. |
| `--out` | `NAME` | `<csv-stem>_annotated.dxf` | Output filename. |
| `--flow` | — | off | Draw flow arrows between TROs. |
| `--fb` | — | off | Show the Siemens FB block name on the marker. |
| `--legend` | — | off | Draw a color-group legend. |
| `--marker-size` | `MM` | `300.0` | Marker radius in mm. |
| `--text-height` | `MM` | `220.0` | Text height in mm. |
| `--offset` | `DX,DY` | — | Set the CSV↔DXF offset by hand (`0,0` for dxfmakros drawings). |
| `--re-register` | — | off | Re-derive the offset even if a cached one exists in `%SKEL_CFG%`. |
| `--check` | — | off | Dry run: analyze and report, write nothing. |
| `--emit-lisp` | — | off | Regenerate `cad/tro_types.lsp` (or under `%DXFM_LISP%`) and exit. |

Exit codes: `0` ok · `1` input/CLI error · `4` coordinate registration not
provable — use `--offset`.

```bat
bin\tro_annotate.bat --file mubea.csv --dxf 500573_60_1.dxf --flow --fb --legend
bin\tro_annotate.bat --file mubea.csv --dxf Mubea.dxf --offset 0,0 --check
bin\tro_annotate.bat --emit-lisp
```

### 2.4 `tro_extract` — read the TROs back out of the drawing into JSON

Input: the (possibly hand-edited) annotated DXF only, never the CSV.
Details: [`Python_Scripts.md` §5a](Python_Scripts.md#5a-tro_extractpy--read-the-tros-back-out-of-the-drawing-into-json).

| Switch | Argument | Default | Effect |
|---|---|---|---|
| `--dxf` | `NAME` | `export_annotated.dxf` | Annotated drawing (looked up in `%SKEL_RESULTS%`). |
| `--out` | `NAME` | `<drawing>_tro.json` | Output JSON filename. |

Exit codes: `0` ok · `1` input/CLI error · `2` no TRO markers in the drawing.

```bat
bin\tro_extract.bat --dxf mubea_annotated.dxf
```

### 2.5 `scl_skeleton` — generate the `FB_Main` SCL skeleton

Input: TRO-JSON from `tro_extract`. Output is a skeleton with
`TODO(E-Planung)` gaps, not a compilable program.
Details: [`Python_Scripts.md` §5b](Python_Scripts.md#5b-scl_skeletonpy--generate-the-fb_main-skeleton-as-scl).

| Switch | Argument | Default | Effect |
|---|---|---|---|
| `--json` | `NAME` | `export_tro.json` | TRO-JSON input (looked up in `%SKEL_RESULTS%`). |
| `--out` | `NAME` | `<source>_FB_Main.scl` | Output SCL filename. |
| `--start` | `TRO` | — | TRO where the REGION order begins. Only needed while the flow is a closed loop without a loading/unloading station (`SYSn`). |

Exit codes: `0` ok · `1` input/CLI error.

```bat
bin\scl_skeleton.bat --json mubea_annotated_tro.json
bin\scl_skeleton.bat --json mubea_annotated_tro.json --start TRO01
```

## 3. End-to-end example

```bat
bin\activate_venv.bat
bin\material_flow.bat --file mubea.csv --tosvg --doc
bin\tro_flow.bat      --file mubea.csv --tosvg --use-cords --doc
bin\tro_annotate.bat  --file mubea.csv --dxf Mubea.dxf --flow --legend
REM   ... optionally review / edit results\mubea_annotated.dxf in BricsCAD ...
bin\tro_extract.bat   --dxf mubea_annotated.dxf
bin\scl_skeleton.bat  --json mubea_annotated_tro.json
```

## 4. Documentation tooling (not part of the pipeline)

| Command | Purpose |
|---|---|
| `py doc/TRO_Katalog/tro_graphs/gen_tro_graphs.py` | Regenerates the per-type SVGs, the edge legend and the UH01–UH05 topology graphs for `TRO_Katalog.md` from `doc/TRO_Katalog/connect.ini`. No switches, no `bin/` wrapper. Needs Graphviz `dot`. |

The libraries `lib/tro_catalog.py`, `lib/dxf_registration.py` and
`lib/tro_overrides.py` have no command line of their own.