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.

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 --json ─► <name>_tro.json ─► scl_skeleton ─► <name>_FB_Main.scl
                           │                (model.py)          (validates)
                           └─► tro_annotate (+ DXF) ─► <name>_annotated.dxf   viewer only

parked: tro_extract (DXF → JSON), see 2.4

Shared conventions:

• Input names (--file, --dxf) are a bare filename resolved against %SKEL_DATA%, or a full path. scl_skeleton (and the parked tro_extract) 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.

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.

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.

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.
--json	—	off	Write the TRO-JSON <name>_tro.json (model lib/model.py) — input for scl_skeleton.

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

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

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

Viewer only: shows the same TROs as tro_flow in the drawing for a visual check; the drawing is not read back as data. Input: CSV export + original BricsCAD DXF. The original is never modified. Details: Python_Scripts.md §5.

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.

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

Parked — kept, but not part of the main path. Its JSON (schema sps_skel-tro-extract-v1) is rejected by scl_skeleton; use tro_flow --json instead.

Input: the (possibly hand-edited) annotated DXF only, never the CSV. Details: Python_Scripts.md §5a.

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.

bin\tro_extract.bat --dxf mubea_annotated.dxf

2.5 scl_skeleton — generate the FB_Main SCL skeleton

Input: TRO-JSON from tro_flow --json, validated against lib/model.py — a wrong or renamed key stops the run (exit 1) instead of producing SCL. Output is a skeleton with TODO(E-Planung) gaps, not a compilable program. Details: Python_Scripts.md §5b.

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 or JSON does not match the model.

bin\scl_skeleton.bat --json mubea_tro.json
bin\scl_skeleton.bat --json mubea_tro.json --start TRO01

3. End-to-end example

bin\activate_venv.bat
bin\material_flow.bat --file mubea.csv --tosvg --doc
bin\tro_flow.bat      --file mubea.csv --tosvg --use-cords --doc --json
bin\scl_skeleton.bat  --json mubea_tro.json
REM   optional, for a visual check in BricsCAD:
bin\tro_annotate.bat  --file mubea.csv --dxf Mubea.dxf --flow --legend

Tests: python -m pytest tests/ (with .venv active).

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/model.py, lib/dxf_registration.py and lib/tro_overrides.py have no command line of their own.