dxfmakros/doc/vf_linienzug_modus1_anleitung.md

# VF-Linienzug Modus 1 - Anleitung anhand eines realen Beispiels

Diese Anleitung erklaert Modus 1 des VF-Linienzugs ("Manuelle Eingabe",
`vf-linienzug-modus` in `Lisp/vf_linienzug.lsp`) nicht abstrakt, sondern
Schritt fuer Schritt anhand eines echten, in BricsCAD gebauten und
verifizierten Beispiels. Dasselbe Beispiel ist als automatisierter
Regressionstest hinterlegt: `tests/testdata/linienzug_tests_stufe2.json`,
aufrufbar in BricsCAD ueber `TEST_LINIENZUG_STUFE2` (siehe
`tests/test_linienzug.lsp`). Wer die Zahlen selbst nachvollziehen will, kann
diesen Testlauf jederzeit wiederholen.

Fuer die Architektur-Details (Frame-Kette, Journal/XDATA, Wizard-Dialoge)
siehe `doc/variofoerderer.md`. Diese Anleitung konzentriert sich auf die
Bedienung und die typischen Stolperfallen.

## 1. Was ist Modus 1?

Modus 1 baut eine VF-Linienzug-Kette **interaktiv, Element fuer Element**:
Sie klicken/geben nacheinander Punkte, Laengen, Winkel und Ja/Nein-
Entscheidungen ein, und jede Antwort erzeugt sofort ein Stueck Geometrie
(Umlenkstation, Gefaellestrecke, VF-Einheit, Vario-Kurve, ...). Das
unterscheidet Modus 1 von:

- **Modus 2** (Ziel-Hoehe-Modus): Sie zeichnen vorher einen Pfad (LINE/ARC-
  Kette) und eine Zielhoehe, das Programm loest die Kette automatisch.
- **Modus 3** (Vorwaerts-Nachbau): rekonstruiert eine Kette aus einer
  bestehenden Zeichnung (Legacy, wird umgebaut).

**Aufruf:** Befehl `FOERDERANLAGE` (bzw. `VarioFoerderer`) -> Anlagen-Typ
"Linienzug" waehlen -> Modus "1" (Manuelle Eingabe).

Jede Eingabe wird in einem Journal mitgeschrieben und als XDATA auf den
fertigen `VF_n`-Block geschrieben. Ein Abbruch (ESC) loescht dadurch nichts -
die bis dahin gebaute Teilkette bleibt als Block stehen und ist per
Doppelklick weiter bearbeitbar.

## 2. Das Beispiel im Ueberblick

Die Kette aus `linienzug_tests_stufe2.json` sieht so aus (Grundriss, von
oben betrachtet):

```
Start (Z=2154) --AS 90 links--> Horizontal-VF --Vario 90 rechts innen-->
  --Horizontal-VF--> --Vario 90 rechts innen--> Linie-GF (3 Grad, Separator
  vor+nach) --> Horizontal-VF --Vario 30 rechts innen--> Auf 27 Grad
  --Vario 30 links aussen--> Kettenende (Motorstation + ES 90 links)
```

Kurz gesagt: die Kette startet auf Z=2154, macht zwei 90-Grad-Schwenks im
Grundriss, faellt ueber ein eigenstaendiges GF-Stueck (3 Grad) etwas ab,
steigt dann in einer zweiten VF-Einheit um 27 Grad wieder an, und muss am
Ende exakt auf die Starthoehe (2154mm) zurueckkommen. Genau dieser letzte
Schritt - der Rest-Hoehenausgleich passt zu keinem der Standard-Winkel mehr -
ist der interessante Teil (siehe Abschnitt 4, Stufe 1/Stufe 2).

## 3. Die Fragen der Reihe nach

Diese Tabelle zitiert die tatsaechlichen Konsolen-Fragen aus dem Testfall
(Kommentar-Spalte = `kommentar`-Feld im JSON) und erklaert, was jede Frage
bedeutet. Die Datei hat aktuell 62 Eingabe-Eintraege (ohne das Kopf-Objekt);
mehrere Eintraege pro Zeile sind zu einem Schritt zusammengefasst, wo eine
Antwort mehrere JSON-Eintraege verbraucht (z.B. eine Vario-Kurve = Winkel +
Seite + Variante = 3 Eintraege).

| # (JSON-Eintraege) | Frage (sinngemaess) | Antwort im Beispiel | Bedeutung |
|---|---|---|---|
| 1 | Startpunkt der Kette | Klick (X/Y) | Beliebiger Punkt in der Zeichnung |
| 2 | Hoehe (Z) Startpunkt | 2154 | Absolute Einbauhoehe des Kettenanfangs |
| 3 | AS-Element setzen? | Ja | Umlenkstation am Anfang - "AS" = Ausgangs-/Anfangs-Element |
| 4 | AS-Element Winkel | 90 Grad | Baugroesse des Umlenkstations-Blocks (90 oder 30 Grad Kurvenradius) |
| 5 | AS-Seite | links | Auf welcher Seite die Umlenkstation seitlich ausschwenkt |
| 6 | Naechstes Element | Neue VF mit horizontalem Anfang | Kettenanfang-Menue hat 6 Optionen (GF-Bogen, Vario-Kurve, Linie-GF, Linie-VF, Horizontal-VF, Linienende) |
| 7 | Endpunkt der Linie | Klick | Laenge/Richtung der ersten VF-Einheit |
| 8 | Ziel-Hoehe fuer den horizontalen VF-Anfang | 1980 | Hoehe, auf die der Eingangs-GF-Anteil der VF-Einheit einregelt |
| 9-10 | Zusaetzlichen Separator VOR/NACH dem horizontalen Stueck? | Nein / Nein | Optionale Separatoren direkt am VF-Einlauf |
| 11 | Ist der Endpunkt der Foerderer? | Nein | Innerhalb der VF-Einheit: "geht die Kette hier zu Ende?" |
| 12-15 | Naechstes im VarioFoerderer -> Vario-Kurve 90 rechts innen | - | Grundriss-Schwenk INNERHALB der laufenden VF-Einheit |
| 16 | Ist der Endpunkt der Foerderer? | Nein | s.o. |
| 17-18 | Horizontaler Foerderer, Endpunkt | Klick | Weiteres gerades VF-Sub-Segment |
| 19-20 | Zusaetzlichen Separator VOR/NACH? | Nein / Nein | s.o. |
| 21 | Ist der Endpunkt der Foerderer? | Nein | s.o. |
| 22-25 | Vario-Kurve 90 rechts innen | - | Zweiter Grundriss-Schwenk |
| 26 | Ist der Endpunkt der Foerderer? | Ja, nur Motorstation | Schliesst die 1. VF-Einheit ab (Motorstation, kein ES) |
| 27 | Ist das Kettenende (ES-Element)? | Nein, weiterbauen | Nach der Motorstation: geht die Kette weiter? |
| 28 | Zusaetzlichen Separator hier? | Nein | Optionaler Separator direkt an der Motorstation |
| 29 | Naechstes Element | Neue Linie: GF | Jetzt folgt ein reines Gefaellestrecke-Element (kein VF) |
| 30 | Laenge bestimmen ueber | Endpunkt waehlen | Alternativ: Zielhoehe zuerst festlegen (siehe `vfl-gf-laenge-modus`) |
| 31 | Ist das Kettenende? | Nein, weiterbauen | 3-Optionen-Menue: Ja+ES / Ja ohne ES / Nein - kommt VOR der Gefaelle-/Laengenberechnung |
| 32 | Endpunkt Gefaellestrecke | Klick | Bestimmt deltaL der GF-Geraden |
| 33-34 | Separator VOR / NACH? | Ja / Ja | GF-Stuecke werden ueber Separatoren mechanisch begrenzt |
| 35-36 | Gefaelle festlegen -> Neigungswinkel | 3 Grad | Direkter Winkel (Alternative: Zielhoehe -> Winkel wird berechnet) |
| 37 | Naechstes Element | Neue VF mit horizontalem Anfang (2. Einheit) | Neue VF-Einheit beginnt direkt am GF-Ausgang (Separator als Eingang) |
| 38-55 | (wie oben: Separatoren, Vario-Kurven, Auf/Ab-Foerderer 27 Grad) | - | s.o.; Auf/Ab-Foerderer nutzt Index 8 der gueltigen Winkeltabelle-Kandidaten = 27 Grad |
| 56 | Ist der Endpunkt der Foerderer? | Ja, Motorstation + Kettenende | Startet den automatischen Kettenende-Abschluss |
| 57-59 | ES-Element setzen? / Winkel / Seite | Ja / 90 / links | Ausgangs-Element, spiegelbildlich zum AS-Element |
| 60 | Endpunkt Kettenende | Klick | Letzter gewuenschter Punkt der Kette |
| 61 | Ziel-Hoehe Kettenende | 2154 | Muss wieder exakt die Starthoehe sein |
| 62 | GF2=319mm unter Mindestlaenge (400mm) - trotzdem bauen? | Ja | Sicherheitsfrage, siehe Abschnitt 4 - Stufe-1/Stufe-2-Loeser rechnet dazwischen automatisch |

**Wichtig zu "Ist der Endpunkt der Foerderer?"** (Eintraege 11/16/21/26 usw.):
Diese Frage
kommt IMMER, wenn Sie innerhalb einer laufenden VF-Einheit einen Punkt
gepickt haben. "Nein" heisst: der gepickte Punkt ist nur eine
Zwischen-Etappe, es geht in derselben VF-Einheit weiter (Vario-Kurve,
weiteres gerades Stueck, Auf/Ab). "Ja" beendet die VF-Einheit mit einer
Motorstation - optional zusaetzlich mit ES-Element (echtes Kettenende).

### 3a. Neu seit 2026-10-21: Zufuehrungsachse und "Parallel zum Kreisel"

Die Tabelle oben zitiert eine aeltere Aufzeichnung. Zwei Dinge sind seitdem
dazugekommen (aeltere Ketten bleiben unveraendert editierbar - das Journal
erkennt am Eintragstyp, welche Fragen damals gestellt wurden):

**Zufuehrungsachse (2. Punkt) - jetzt bei BEIDEN AS-Winkeln.** Nach Winkel
und Seite (Eintrag 4/5) fragt der AS-Dialog zusaetzlich einen zweiten Punkt
ab; im Assistenten stehen alle drei Angaben in EINEM Fenster
(`vflw_as_achse`). Die beiden Angaben beschreiben verschiedene Dinge und
legen das AS erst zusammen vollstaendig fest:

| Angabe | legt fest |
|---|---|
| 2. Punkt | Richtung der KS_EIN-Achse = die Zufuehrung, z.B. die Kreisel-Laufrichtung. Der Startpunkt bleibt der Sitz des AS-Elements, der zweite Punkt gibt nur die Richtung. |
| links/rechts | AS-Variante und damit die KS_AUS-Richtung, also wohin die Kette nach dem Ausschleusen laeuft. |

Der Dialog zeigt den Startpunkt mit an (er ist der Sitz des AS-Elements UND
der Ausgangspunkt der Achse); waehrend der Punktwahl haengt das Gummiband an
ihm. Mit dem gesetzten Punkt ist der Dialog fertig und schliesst direkt - die
ermittelte Achsrichtung meldet die Konsole. Nur ein mit ESC abgebrochener
Pick zeigt den Dialog noch einmal (mit den vorher gewaehlten Werten), damit
nach einem Fehlklick nichts verloren geht.

Die Achse ist **optional**: ohne Punkt laeuft alles wie frueher ueber die
Richtung des naechsten Klicks. Frueher ersetzte die Achse beim 30-Grad-
Element die Seitenfrage (die Seite wurde aus der Lage des naechsten Punkts
erraten); das gilt nur noch beim Nachbau alter Ketten.

**"Parallel zum Kreisel weiterbauen"** - 5. Option der Frage "Wie soll die
Laenge dieser Gefaellestrecke bestimmt werden?" (Eintrag 30). Sie erscheint
nur am Kettenanfang mit AS-Element UND festgelegter Zufuehrungsachse, weil
sie beides als Bezug braucht. Gebaut wird AS -> kurzes GF-Stueck -> GF-Bogen,
sodass die Kette danach parallel zur Zufuehrungsachse weiterlaeuft. Einzige
Eingabe ist der **Abstand**, gemessen senkrecht zur Zufuehrungsachse von
KS_EIN des AS bis KS_AUS des Bogens; die Laenge des GF-Stuecks dazwischen
wird daraus berechnet. Ein Separator zwischen GF-Stueck und Bogen wird
bewusst NICHT gesetzt, damit der Abstand exakt getroffen wird. Der Bogen wird
nicht geraten, sondern so gewaehlt, dass er den gemessenen Grundriss-Schwenk
des AS-Blocks genau aufhebt - immer zur Gegenseite der AS-Seite:

| AS | Bogen |
|---|---|
| 30 Grad links | 30 Grad rechts |
| 30 Grad rechts | 30 Grad links |
| 90 Grad links | 90 Grad rechts |
| 90 Grad rechts | 90 Grad links |

Diese Tabelle ist das ERGEBNIS der Messung, keine gepflegte Zuordnung im
Code - sie bleibt auch dann richtig, wenn ein Element anders vermessen ist
als hier erwartet.

Direkt nach dem Bogen kommt die gewohnte Frage "Ist das das Kettenende?"
(Ja mit ES / Ja ohne ES / Nein, weiterbauen) - hier ausnahmsweise NACH dem
Bau, weil es keine gepickte Laenge gibt, von der ein ES-Fussabdruck
abzuziehen waere.

## 4. Stufe 1 / Stufe 2 - wie die letzte Strecke berechnet wird

Am Kettenende (Eintrag 61/62) ist die Aufgabe: von der aktuellen Position/
Hoehe zur gewuenschten Ziel-Hoehe kommen, UND dabei die feste Baugruppe
Motorstation + Separator (+ ES-Element, falls gewaehlt) unterbringen. Das
Programm versucht das in zwei Stufen (`vfl-winkel-stufe-entscheidung`,
`Lisp/vf_linienzug.lsp`):

- **Stufe 1 - Winkeltabelle:** Es probiert der Reihe nach die festen
  Vario-Kurven-Winkel 3/6/9/12/15/18/21/27/33/39/45/51 Grad durch
  (`berechne-alle-winkel`) und prueft, ob einer davon eine PASSENDE,
  positive VF-Laenge ergibt. Das ist der Normalfall (siehe die Zeile
  "38-55" in der Tabelle: der Auf/Ab-Foerderer in der 2. VF-Einheit findet
  so einen passenden Winkel, Auswahl-Index 8 = 27 Grad).
- **Stufe 2 - Horizontale Mitte + GF-Ausgleich:** Wenn KEIN Tabellenwinkel
  passt (wie im Beispiel am Kettenende: alle 12 Kandidaten ergeben eine
  negative VF-Laenge, die Reststrecke ist einfach zu kurz fuer einen echten
  Vertikalbogen), rechnet `berechne-horizontale-mitte` eine andere Loesung:
  ein HORIZONTALES VF-Stueck (winkel=0) plus eine kurze Gefaellestrecke
  (GF2), die exakt den fehlenden Hoehenunterschied ausgleicht. Im Beispiel:
  GF2=319mm, L_VF=48mm.

Die Formel dahinter ist simpel und lohnt sich zu verinnerlichen: bei einem
FESTEN Neigungswinkel von 3 Grad braucht ein Hoehenausgleich von `H`
Millimetern eine GF-Laenge von `H / tan(3 Grad) ~= H * 19`. Ein Hoehenrest
von z.B. 17mm braucht demnach bereits ~320mm GF-Laenge - siehe Abschnitt
5.a. GF2 im Beispiel (319mm) liegt knapp unter der uebliche Mindestlaenge
(400mm, `*vfl-gf-min-laenge*`) - deshalb die Rueckfrage im letzten Eintrag
("trotzdem mit 319mm bauen?"). "Ja" baut trotzdem exakt mit dem berechneten
Wert; "Nein" wuerde den bis dahin gebauten Teil verwerfen (siehe
`vfl-loesche-seit`/`vfl-modus-abbruch-sichern`).

**Merksatz:** Stufe 1 sucht einen "sauberen" Standard-Winkel; Stufe 2 ist
der Rettungsanker, wenn dafuer schlicht nicht genug Platz ist - er tauscht
einen Vertikalbogen gegen "flach + minimaler GF-Ausgleich".

## 5. Typische Stolperfallen

### a) Gefaellestrecke (GF) ist "laengenhungrig" bei 3 Grad

3 Grad ist ein SEHR flacher Winkel. `tan(3 Grad) ~= 0.0524`, also braucht
jeder Millimeter Hoehenunterschied ungefaehr **19mm** Laenge:

```
Laenge = Hoehendifferenz / tan(3 Grad) ~= Hoehendifferenz * 19
```

Wer nur wenige mm bis cm Hoehenunterschied ausgleichen will, bekommt damit
schnell GF-Laengen im halben bis ganzen Meterbereich. Das ist die haeufigste
Ursache fuer "die Reststrecke ist zu kurz"-Meldungen und fuer den
Stufe-2-Fallback aus Abschnitt 4. Falls eine GF partout nicht passt: entweder
mehr Grundriss-Laenge einplanen, oder pruefen, ob ein Vertikalbogen
(Vario-Kurve mit groesserem Winkel, siehe Stufe 1) die bessere Wahl ist.

### b) Motorstation + Separator + ES-Element haben einen FESTEN Fussabdruck

Am Kettenende ist nicht die ganze gepickte Reststrecke frei verfuegbar -
ein fester Anteil ist fuer Motorstation und Separator reserviert
(`*vfk-feste-horizontal-kettenende*` = 800mm = 500mm Motorstation + 300mm
Separator), und falls zusaetzlich ein ES-Element gewaehlt wird, kommt dessen
eigener Fussabdruck (abhaengig von 30/90 Grad Bauform) noch oben drauf. Wer
diese festen 800mm (+ ES) nicht einplant, landet schnell bei einer negativen
"freien" Reststrecke - genau der Fall, der in Abschnitt 4 den Stufe-2-
Fallback ausloest.

### c) Seitlicher Versatz bei 90-Grad-AS/ES-Elementen ist NORMAL

Ein AS- oder ES-Element mit 90 Grad Bauform dreht die Fahrtrichtung nicht
einfach "auf der Stelle" - sein Block hat eine reale Baugroesse mit einem
seitlichen (quer zur Fahrtrichtung liegenden) Versatz. Sowohl im Standard-
Testfall (`linienzug_tests.json`) als auch im Stufe-2-Testfall
(`linienzug_tests_stufe2.json`) betraegt dieser Versatz ca. 638mm (dort als
`erwartung_dx_mm` dokumentiert, da die Fahrtrichtung am Kettenende auf der
Y-Achse liegt und sich der Versatz dadurch in X statt in Y zeigt).
**Das ist kein Baufehler** - es ist die tatsaechliche Geometrie des
90-Grad-ES/AS-Blocks. Ein "Ist-Ziel-Report" mit einer Restabweichung von
ca. 638mm quer zur letzten Fahrtrichtung, aber ~0mm in Laengs-/Hoehenrichtung,
ist ein KORREKTES Ergebnis, keine Abweichung, die weiter untersucht werden
muss.

## 6. Nachvollziehen / Nachbauen

- Live in BricsCAD: `FOERDERANLAGE` -> Linienzug -> Modus 1, und die
  Eingaben aus der Tabelle in Abschnitt 3 der Reihe nach eintippen/klicken.
- Automatisiert (ohne Klicks): Befehl `TEST_LINIENZUG_STUFE2` (nach Laden
  von `tests/test_linienzug.lsp`) spielt exakt dieselbe Sequenz aus
  `tests/testdata/linienzug_tests_stufe2.json` ab und meldet das
  Ist-Ziel-Ergebnis in der Konsole.
- Debug-Log: mit `dbgopen`/dem zentralen Debug-Schalter (siehe
  `Lisp/ssg_dbg.lsp`) lassen sich alle `GEOMETRIE:`/`GEOMETRIE ERFOLG:`-
  Zeilen in eine `.dbg`-Datei im Log-Verzeichnis mitschreiben - hilfreich,
  um genau wie in diesem Beispiel eine reale Sitzung nachtraeglich in
  einen Testfall zu verwandeln.