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.