FTI-Voiceagent

Sprachgesteuertes Layout-Design fuer Visual Components (VC) 4.10. Ein KI-Assistent, der natuerliche Sprache in CAD-Layouts umsetzt - iterativ, interaktiv, ohne VC-Vorkenntnisse.

Setup-Anleitung (Schritt fuer Schritt)

Diese Anleitung geht davon aus, dass du auf einem frischen Windows-System startest.

Voraussetzungen

Stelle sicher, dass folgende Programme installiert sind:

Software	Version	Download
Python	3.10 oder neuer	https://www.python.org/downloads/
Git	beliebig	https://git-scm.com/downloads
Visual Components	4.10 Premium	Lizenz erforderlich
Mikrofon	-	Fuer Spracheingabe

Python-Installation: Beim Installer unbedingt "Add Python to PATH" ankreuzen!

Schritt 1: Projekt klonen

Oeffne PowerShell oder die Eingabeaufforderung:

cd C:\Users\DEIN_NAME\Desktop
git clone <REPOSITORY-URL> FTI-Voiceagent
cd FTI-Voiceagent

Schritt 2: Python Virtual Environment erstellen

python -m venv venv

Aktiviere die virtuelle Umgebung:

venv\Scripts\activate

Du erkennst die aktive Umgebung am (venv) am Anfang der Zeile.

Schritt 3: Dependencies installieren

pip install -r requirements.txt

Das installiert: FastAPI, Uvicorn, Pydantic, Google Gemini SDK, sounddevice, scipy, keyboard, numpy, pandas, openpyxl.

Schritt 4: Google Gemini API Key erstellen

Gehe zu https://aistudio.google.com/apikey
Melde dich mit deinem Google-Konto an
Klicke auf "Create API Key"
Kopiere den Key (beginnt mit AIza...)

Schritt 5: API Key eintragen

Erstelle eine Datei .env im Projektordner (FTI-Voiceagent/.env):

GOOGLE_API_KEY=AIzaSy_DEIN_KEY_HIER

Alternativ: Die .env-Datei existiert bereits als Vorlage - oeffne sie und trage deinen Key ein.

Wichtig: Die .env-Datei wird NICHT ins Git eingecheckt (steht in .gitignore).

Schritt 6: VC Agent in Visual Components einrichten

Das ist der aufwaendigste Schritt. Der Agent ist ein Python-Skript, das innerhalb von Visual Components laeuft und Befehle vom Server empfaengt.

6a: Visual Components oeffnen

Starte Visual Components 4.10
Erstelle ein neues leeres Layout (oder oeffne ein bestehendes)

6b: Host-Komponente erstellen

Gehe im Menü auf Home > eCatalog
Suche nach "Block Geometry" (oder einer beliebigen einfachen Komponente)
Doppelklicke die Komponente, um sie zur Szene hinzuzufuegen
Diese Komponente dient nur als "Traeger" fuer das Agent-Skript

6c: Python Script Behaviour hinzufuegen

Klicke die soeben erstellte Komponente in der 3D-Ansicht an
Im Component Properties Panel (rechts): Klicke auf das Tab "Modelling"
Klicke auf "Python Script" (in der Toolbar oder Rechtsklick > Behaviours > Python Script)
Es erscheint ein neues Python Script Behaviour in der Behaviour-Liste

6d: Agent-Code einfuegen

Doppelklicke auf das Python Script Behaviour, um den Code-Editor zu oeffnen
Loesche den gesamten Standard-Code im Editor
Oeffne die Datei vc_client/agent_VC_2.7_clientskript.py mit einem Texteditor (z.B. Notepad, VS Code)
Kopiere den gesamten Inhalt (Strg+A, Strg+C)
Fuege ihn im VC Code-Editor ein (Strg+V)
Schliesse den Editor (das Skript wird automatisch gespeichert)

6e: Layout speichern

Speichere das Layout (Strg+S), damit der Agent beim naechsten Oeffnen noch da ist

Tipp: Du kannst die Host-Komponente irgendwo am Rand der Szene platzieren, damit sie nicht stoert. Sie taucht nicht in den Szenen-Reports auf.

Schritt 7: Simulation in VC starten

Klicke in Visual Components auf den Play-Button (gruener Pfeil) oder druecke F5

Im Output-Fenster (unten) sollte erscheinen:

VC Agent gestartet auf Host-Komponente 'Block Geo'. Polling...

Der Agent pollt jetzt alle 500ms den Server. Solange kein Server laeuft, kommen Timeout-Meldungen - das ist normal.

Wichtig: Die Simulation muss laufen, damit der Agent arbeitet. Bei Stopp hoert er auf zu pollen.

Schritt 8: Server starten

Oeffne ein neues Terminal-Fenster (das alte bleibt fuer spaeter):

cd C:\Users\DEIN_NAME\Desktop\FTI-Voiceagent
server.bat

Oder manuell:

venv\Scripts\activate
uvicorn server.main:app --reload --port 8000

Erwartete Ausgabe:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Im VC Output-Fenster sollten die Timeout-Meldungen jetzt aufhoeren - der Agent hat den Server gefunden.

Schritt 9: Voice-to-Layout starten

Oeffne ein drittes Terminal-Fenster:

cd C:\Users\DEIN_NAME\Desktop\FTI-Voiceagent
llm.bat

Oder manuell:

venv\Scripts\activate
python voice_to_layout.py

Erwartete Ausgabe:

============================================================
 Interaktiver Visual Components Layout Generator (v7.1)
============================================================
Server: http://127.0.0.1:8000 | Modell: gemini-3-flash-preview
Eingabe: Rechte Strg = Sprache | T = Text | Strg+C = Beenden
[OK] Server erreichbar. Queue: 0 Commands.

--- Szenen-Inspektion ---
Szene ist leer.

Rechte Strg = Spracheingabe | T + Enter = Texteingabe | Strg+C = Beenden

Schritt 10: Ersten Befehl geben

Es gibt zwei Eingabemoeglichkeiten:

Spracheingabe:

Druecke die rechte Strg-Taste -> Aufnahme startet
Sprich deinen Befehl, z.B.: "Platziere einen Feeder und drei Foerderbaender dahinter"
Druecke nochmal die rechte Strg-Taste -> Aufnahme stoppt
Warte kurz (Gemini analysiert die Sprache und generiert den Bauplan)
In Visual Components erscheinen die Komponenten!

Texteingabe:

Druecke T -> Texteingabe-Modus
Tippe deinen Befehl ein, z.B.: Platziere einen Feeder und drei Foerderbaender dahinter
Druecke Enter -> Gemini verarbeitet den Befehl

Weitere Beispielbefehle:

"Setze einen Roboter neben das zweite Foerderband"
"Verschiebe den Roboter um 500mm nach vorne"
"Loesche alle Roboter"
"Ersetze den Roboter durch einen Humanoid"
"Baue zwei parallele Foerderbandstrassen"
"Baue ein L-foermiges Band mit einer Kurve nach rechts"

Strg+C in dem Terminal beendet die Sprachsteuerung.

Zusammenfassung: Was laeuft wo?

Du brauchst drei Fenster gleichzeitig:

Fenster 1: Visual Components    -> Simulation laeuft (F5), Agent pollt
Fenster 2: Terminal (Server)    -> server.bat       -> laeuft dauerhaft
Fenster 3: Terminal (Voice)     -> llm.bat          -> Rechte Strg / T fuer Eingabe

Troubleshooting

Problem	Loesung
`python` wird nicht erkannt	Python zu PATH hinzufuegen (Installer nochmal ausfuehren, Haken setzen)
`pip install` schlaegt fehl	Pruefen ob `venv` aktiv ist (`(venv)` am Anfang der Zeile?)
Server: "Port 8000 belegt"	`server.bat` bietet Option zum Beenden des alten Prozesses
VC Agent: "Polling error"	Ist der Server gestartet? Laeuft er auf Port 8000?
Voice: "GOOGLE_API_KEY nicht gefunden"	`.env` Datei pruefen - liegt sie im Projektordner? Key korrekt?
Voice: "Server nicht erreichbar"	`server.bat` zuerst starten
VC: Keine Reaktion auf Befehle	Simulation muss laufen (Play-Button / F5)
Kein Mikrofon-Input	Windows Sound-Einstellungen pruefen, Standard-Mikrofon setzen

Architektur

┌─────────────────────────────┐
│  Brain: voice_to_layout.py  │  Gemini API (gemini-3-flash-preview)
│  Sprache -> JSON-Blueprint  │  System-Prompt mit Cursor-Modell
└─────────────┬───────────────┘
              │ POST /command/enqueue
              v
┌─────────────────────────────┐
│  Queue: FastAPI Server      │  server/main.py (Port 8000)
│  Thread-sichere Queue       │  command_queue.py
└─────────────┬───────────────┘
              │ GET /command/dequeue (polling 500ms)
              v
┌─────────────────────────────┐
│  Muscle: VC Agent           │  Python 2.7/IronPython in VC
│  Fuehrt Befehle in VC aus   │  agent_VC_2.7_clientskript.py
└─────────────────────────────┘

Features

Feature	Beschreibung
Sprach- und Texteingabe	Natuerliche Sprache oder Text -> CAD-Layout via Gemini API
Iterativer Aufbau	Szene wird nach jedem Befehl inspiziert, Kontext bleibt erhalten
Cursor-Modell	Automatische Positionsberechnung fuer sequentiellen Aufbau
Komponenten laden	Feeder, Conveyors (gerade/Kurve/Turntable), Roboter, Humanoids
Verbinden (Snap)	Interface-Snapping fuer buendige Conveyor-Verbindungen
Verschieben	Absolute oder relative Repositionierung bestehender Komponenten
Loeschen/Ersetzen	Einzelne oder alle Komponenten entfernen, mit Positionsuebernahme
Attach (mountplate)	Greifer an Roboter montieren via `getRobot().mountTool()`
Excel-Protokoll	Jeder Blueprint wird kumulativ in Excel gespeichert

Befehle

Definiert in shared/commands.py:

Befehl	Beschreibung
`add_component`	Komponente laden und positionieren
`connect_components`	Interface-Snapping (Next/Prev)
`attach_to_node`	An Node heften (mountplate fuer Roboter-Gripper)
`move_component`	Bestehende Komponente verschieben (absolut/relativ)
`delete_component`	Komponente loeschen
`set_property`	Property-Wert setzen
`build_layout_from_blueprint`	Batch: Loeschungen + Verschiebungen + Laden + Verbindungen

Blueprint-Ausfuehrungsreihenfolge

Phase 0:   Loeschungen
Phase 0.5: Verschiebungen (bestehende Komponenten)
Phase 1:   Laden & Positionieren (neue Komponenten)
Phase 2:   Verbindungen (connect/attach)

Unterstuetzte Komponenten

Komponente	Laenge (L)	Anmerkung
Feeder	300mm	Materialzufuhr
Conveyor	1500mm	Gerades Foerderband mit Interfaces
Curve Conveyor	1300mm	90-Grad-Kurve (nur Rechtskurve), aendert Foerderrichtung
Turntable Conveyor	1000mm	Drehtisch, leitet Produkte um
Generic Articulated Robot	1000mm	6-Achs Roboter
Robot Transport Controller	-	Wird automatisch mit Roboter erstellt
Generic 3-Jaw Gripper	-	Per attach an mountplate
Humanoid (Bravo)	1000mm	Menschmodell
Human Transport Controller	-	Nur positionieren, KEIN connect

Projektstruktur

FTI-Voiceagent/
├── voice_to_layout.py              # Hauptprogramm: Sprache -> Layout
├── server/
│   ├── main.py                     # FastAPI REST-Endpunkte
│   └── command_queue.py            # Thread-sichere Queue
├── shared/
│   └── commands.py                 # Pydantic Command-Schemas
├── vc_client/
│   └── agent_VC_2.7_clientskript.py  # VC Agent (Python 2.7)
├── scripts/
│   ├── build_from_excel.py         # Excel-gesteuerter Build
│   ├── build.py                    # Demo: Hartcodierte Sequenz
│   ├── delete.py                   # Alle Komponenten loeschen
│   └── inspect_scene.py            # Szenen-Inspektion
├── API_Documentation/
│   └── VisualComponents_API_Docs_Optimized.md
├── server.bat                      # Server starten
├── llm.bat                         # Sprachsteuerung starten
├── excel.bat                       # Excel-Build starten
├── requirements.txt
└── CLAUDE.md                       # Entwickler-Referenz

API-Endpunkte

Methode	Endpunkt	Beschreibung
`GET`	`/health`	Health-Check
`POST`	`/command/enqueue`	Befehl einreihen
`GET`	`/command/dequeue`	Naechsten Befehl abholen (Agent)
`POST`	`/command/status`	Status-Rueckmeldung
`GET`	`/status/recent?limit=50`	Letzte Statusmeldungen

Technische Details

Python-Versionen

Server + Voice-to-Layout: Python 3.10+
VC Agent: Python 2.7 (IronPython in Visual Components)

Tech-Stack

FastAPI + Uvicorn (REST-API)
Pydantic (Datenvalidierung)
Google Gemini API (Spracherkennung + Layout-Planung)
sounddevice + scipy (Audioaufnahme)
pandas + openpyxl (Excel)

Move vs Connect

Move: Setzt exakte Koordinaten. Fuer Roboter, Humanoids, freie Positionierung.
Connect: Interface-Snapping. Fuer buendige Conveyor-Verbindungen. VC berechnet die exakte Ausrichtung.
Nie beides fuer dieselbe Komponente im selben Befehl kombinieren.

Neue Komponenten hinzufuegen (Erweiterungsguide)

Um das System um neue VC-Komponenten zu erweitern, muessen nur Aenderungen in einer einzigen Datei vorgenommen werden: voice_to_layout.py.

Schritt 1: URI der Komponente herausfinden

Oeffne den VC eCatalog und suche die gewuenschte Komponente. Der Dateipfad steht typischerweise unter:

C:/Users/Public/Documents/Visual Components/4.10/Models/Components/Visual Components/[Kategorie]/[Name].vcmx

Alternativ: Lade die Komponente in VC, klicke sie an und lies den Pfad aus den Properties ab.

Schritt 2: Komponente in `<component_library>` eintragen

Oeffne voice_to_layout.py und suche den Block <component_library>. Fuege einen neuen <component>-Eintrag hinzu:

<component id="mein_neuer_typ" L="1200">
  <uri>C:/Users/Public/.../MeineKomponente.vcmx</uri>
  <behavior>Optionale Beschreibung des Verhaltens (fuer das LLM).</behavior>
  <placement>Optionale Platzierungshinweise (z.B. Offset-Regeln).</placement>
</component>

Wichtige Felder:

id: Kurzname fuer das LLM (z.B. "belt_conveyor", "agv")
L: Laenge der Komponente in mm entlang der Hauptachse (fuer Cursor-Berechnungen)
uri: Vollstaendiger Pfad zur .vcmx-Datei
behavior (optional): Beschreibt was die Komponente tut (hilft dem LLM bei Entscheidungen)
placement (optional): Spezielle Platzierungsregeln (z.B. "muss immer Y-Offset haben")

Schritt 3: Laenge L korrekt bestimmen

Die Laenge L ist entscheidend fuer die Positionsberechnung. L ist die Ausdehnung entlang der Hauptachse (meist X bei OrientationR=0). Du kannst L in VC ablesen: Komponente platzieren, Position notieren, zweite Komponente buendig daneben setzen, Differenz = L.

Schritt 4 (optional): Beispiel im System-Prompt ergaenzen

Fuer komplexe Komponenten mit besonderen Regeln lohnt sich ein Beispiel im <examples>-Block. Das hilft dem LLM, die korrekte Nutzung zu lernen. Einfache Komponenten (die sich wie ein Conveyor verhalten) brauchen kein eigenes Beispiel.

Schritt 5 (optional): Implizite Regeln

Falls die Komponente automatisch eine Begleit-Komponente braucht (wie der Roboter seinen Controller), fuege ein <implicit>-Tag hinzu:

<implicit>Erstelle AUTOMATISCH einen XY-Controller. Position: gleiche wie Hauptkomponente.</implicit>

Checkliste

URI korrekt und Datei existiert auf dem Zielsystem?
Laenge L in mm gemessen/geschaetzt?
Hat die Komponente Interfaces (Prev/Next) fuer connect? -> In behavior erwaehnen
Braucht die Komponente implizite Begleit-Komponenten? -> <implicit> Tag
README Komponenten-Tabelle aktualisiert?

Tipp: Am besten die Komponente zuerst manuell in VC testen (platzieren, verbinden, Laenge messen), bevor man sie im System-Prompt eintraegt.

Version: 5.0 (Voice-to-Layout v7.1 mit korrigierten L-Werten, Orientierungs-Bugfix, Zwei-Ketten-Strategie fuer S-Formen) Stand: Februar 2026

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.claude		.claude
API_Documentation		API_Documentation
Masterarbeit		Masterarbeit
benchmark_results		benchmark_results
docs/plans		docs/plans
screenshots		screenshots
scripts		scripts
server		server
shared		shared
vc_client		vc_client
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
INSTALL_VIDEO_SKRIPT.md		INSTALL_VIDEO_SKRIPT.md
Layout_Blueprint copy.xlsx		Layout_Blueprint copy.xlsx
README.md		README.md
benchmark_lib.py		benchmark_lib.py
benchmark_prompts.py		benchmark_prompts.py
benchmark_v2.py		benchmark_v2.py
benchmark_v3.py		benchmark_v3.py
benchmark_v4.py		benchmark_v4.py
evaluate_layout.py		evaluate_layout.py
excel.bat		excel.bat
generate_review_page.py		generate_review_page.py
llm.bat		llm.bat
requirements.txt		requirements.txt
screenshot.py		screenshot.py
server.bat		server.bat
setup-guide.html		setup-guide.html
voice_to_layout.py		voice_to_layout.py

Folders and files

Latest commit

History

Repository files navigation

FTI-Voiceagent

Setup-Anleitung (Schritt fuer Schritt)

Voraussetzungen

Schritt 1: Projekt klonen

Schritt 2: Python Virtual Environment erstellen

Schritt 3: Dependencies installieren

Schritt 4: Google Gemini API Key erstellen

Schritt 5: API Key eintragen

Schritt 6: VC Agent in Visual Components einrichten

6a: Visual Components oeffnen

6b: Host-Komponente erstellen

6c: Python Script Behaviour hinzufuegen

6d: Agent-Code einfuegen

6e: Layout speichern

Schritt 7: Simulation in VC starten

Schritt 8: Server starten

Schritt 9: Voice-to-Layout starten

Schritt 10: Ersten Befehl geben

Zusammenfassung: Was laeuft wo?

Troubleshooting

Architektur

Features

Befehle

Blueprint-Ausfuehrungsreihenfolge

Unterstuetzte Komponenten

Projektstruktur

API-Endpunkte

Technische Details

Python-Versionen

Tech-Stack

Move vs Connect

Neue Komponenten hinzufuegen (Erweiterungsguide)

Schritt 1: URI der Komponente herausfinden

Schritt 2: Komponente in <component_library> eintragen

Schritt 3: Laenge L korrekt bestimmen

Schritt 4 (optional): Beispiel im System-Prompt ergaenzen

Schritt 5 (optional): Implizite Regeln

Checkliste

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Schritt 2: Komponente in `<component_library>` eintragen

Packages