FreeCAD-PLM Addon

FreeCAD Workbench für das Django-basierte FreeCAD-PLM.

Die nutzerorientierte Darstellung für den Addon Manager steht in Resources/Documents/Overview.md.

Status

Arbeitsfähige FreeCAD-Workbench für den aktuellen PLM-Addon-Workflow. Die HTTP- und Workspace-Schicht ist so angelegt, dass sie ohne FreeCAD getestet werden kann.

Aktuell umgesetzt:

• Server verbinden und Projekte, Teile/Baugruppen, Revisionen und aktive Checkouts laden.
• Projekte, Teile/Baugruppen und Revisionen platzsparend in einem lazy geladenen Baum mit Kontextmenüs durchsuchen. Aktive Checkouts werden direkt an ihrer Revision markiert und automatisch aufgeklappt.
• Eine einzige kontextabhängige Arbeitsleiste zeigt zur aktuellen Auswahl die wichtigste Aktion; seltenere Aktionen liegen unter Mehr.
• Revisionen read-only über ein Server-Manifest öffnen.
• Revisionen auschecken, Manifest-Dateien mit SHA-256 prüfen und Root-Datei in FreeCAD öffnen.
• Check-in für Root- und referenzierte Dateien; unveränderte Dateien und technische FreeCAD-Speicherartefakte werden nicht als neue Revision eingecheckt.
• Checkout abbrechen.
• Projektmetadaten im Addon bearbeiten: Code, Name, Status, Datum und Beschreibung.
• Neue Teile/Baugruppen samt leerer FCStd-Revision R0001 anlegen und direkt öffnen, ohne vorheriges lokales Speichern.
• Revisionsnotizen bearbeiten.
• Anmerkungen lesen, anlegen, bearbeiten, erledigen/wieder öffnen und löschen.
• Streng validierte freecad-plm://revision/...-Links aus dem Web unter Linux und Windows öffnen; Checkout-Links werden vor Ausführung nochmals bestätigt.
• Lokale CAD-Ordner mit FCStd-, STEP- und STL-Dateien als Projektstand oder neues Projekt importieren.
• FCStd-, STEP- und STL-Revisionen als 3MF in Bambu Studio oder OrcaSlicer öffnen und beim Speichern automatisch mit der zugehörigen PLM-Revision synchronisieren.

Konfiguration

Server-URL:

https://plm.lan.schumbi.de

Der Server erwartet Bearer Token:

Authorization: Bearer plm_pat_...

Für normale CAD-Arbeit einschließlich Teilanlage werden diese Scopes benötigt:

read write checkout

admin ist zusätzlich nötig für Projektanlage, Projektmetadaten und den Kombiflow "neues Projekt plus Import". Ohne admin funktionieren Lesen, Checkout/Check-in, Teilanlage, Notizen, Anmerkungen und Import in ein vorhandenes Projekt.

Projekt importieren packt alle .FCStd-, .step-, .stp- und .stl-Dateien unterhalb eines gewählten lokalen Ordners in ein ZIP mit relativen Pfaden. Das Addon kann damit entweder einen Projektstand in ein vorhandenes Projekt importieren oder ein neues Projekt mit Code, Name, Status, Datum und Beschreibung anlegen und direkt befüllen. Nach erfolgreichem Import kann ein importiertes Teil/Baugruppe als Root ausgewählt und sofort über den normalen Checkout-Workflow geöffnet werden. Der ursprüngliche Importordner wird auf Wunsch erst danach nach ~/FreeCAD-PLM/imported/... verschoben.

Nur FCStd-Revisionen können als Checkout-Root bearbeitet und eingecheckt werden. STEP/STP werden beim schreibgeschützten Öffnen über FreeCADs Import-Modul und STL über das Mesh-Modul in ein neues, nicht gespeichertes Arbeitsdokument geladen. Sie können außerdem als unveränderte Begleitdateien in einem FCStd-Checkout liegen.

Der Befehl PLM-Link öffnen akzeptiert Revisionslinks aus dem Web-UI. Beim FreeCAD-Start richtet das Addon das Schema freecad-plm:// automatisch für den aktuellen Benutzer ein: unter Linux als XDG-MIME-Handler (auch aus dem FreeCAD-Flatpak heraus), unter Windows unter HKCU\Software\Classes, also ohne Administratorrechte. Der Menüpunkt FreeCAD-PLM -> Web-Link-Handler einrichten repariert die Zuordnung bei Bedarf.

Der Handler funktioniert sowohl bei geschlossenem als auch bei bereits laufendem FreeCAD. Dazu übergibt er nicht die URL selbst an FreeCADs Ein-Instanz-Mechanismus, sondern eine kurzlebige .FCPLMLink-Datei. Das Addon prüft und entfernt diese Datei nach der Übergabe. Links dürfen nur project_id, part_id und eine der Aktionen checkout, readonly oder slicer enthalten; Zugangsdaten werden nie in den Link geschrieben. Je nach Browser muss die externe Anwendung beim ersten Aufruf bestätigt werden.

Neues Teil fragt nur Name, optionale Teilenummer und Typ ab. Das Addon erzeugt die leere FCStd-Datei intern und übergibt sie direkt an das PLM. Bei einem geöffneten Projekt-Checkout wird die neue Revision R0001 dort als zusätzliche Datei aufgenommen; andernfalls öffnet das Addon einen eigenen Checkout für das neue Teil. Ein auf dem Server bereits aktiver Projekt-Checkout muss dafür zuerst im Addon lokal geöffnet werden. Die Aktion benötigt write und checkout.

Slicer-Projekte

Unter Verbindungseinstellungen wird der Slicer auf Automatisch erkennen, Bambu Studio, OrcaSlicer oder Benutzerdefiniert gestellt. Der Programmpfad kann leer bleiben; unter Linux erkennt das Addon auch die Flatpaks com.bambulab.BambuStudio und io.github.softfever.OrcaSlicer. Zusätzliche Argumente werden als JSON-Liste, zum Beispiel ["--single-instance"], gespeichert und ohne Shell an den Prozess übergeben.

Nach Auswahl einer FCStd-, STEP- oder STL-Revision startet Im Slicer öffnen den Ablauf. Existiert noch kein Slicer-Projekt, lädt das Addon die CAD-Datei, erzeugt mit FreeCAD eine generische 3MF und legt sie direkt im PLM ab. Ein vorhandener Arbeitsstand wird stattdessen vom Server geladen. Das lokale Projekt liegt unter:

~/FreeCAD-PLM/<server>/<projekt>/slicer-projects/revision-<id>/

Beim FCStd-Export wählt das Addon sichtbare Geometrie auf der höchsten sinnvollen Ebene aus. Enthält ein sichtbarer PartDesign::Body ein ebenfalls sichtbares Tip-Feature, wird nur der Body exportiert; dadurch erscheint das Modell im Slicer nicht doppelt. Unabhängige Körper und Meshes bleiben erhalten.

Quellen prüfen und 3MF neu erzeugen

Neu erzeugte 3MF enthalten unter Metadata/freecad_plm_sources.json den CAD-Quellenstand: Server ohne Zugangsdaten, Projekt-ID, Hauptrevision und alle tatsächlich für den Export geladenen CAD-Dateien mit relativem Pfad, Teil-/Revisions-ID, Revisionscode und SHA-256. Beim Öffnen vergleicht das Addon diese Angaben mit dem aktuellen Revisionsmanifest. Damit wird auch ein neuer Deckel erkannt, wenn die Revision der übergeordneten Druckbaugruppe gleich bleibt.

Bei abweichenden Quellen bietet der Dialog 3MF neu erzeugen, Bisherigen Stand öffnen und Abbrechen an. Ältere 3MF ohne Quellenangaben gelten als nicht prüfbar. Dasselbe gilt, wenn ein Slicer die zusätzlichen Metadaten beim Speichern entfernt; das Addon behauptet dann nicht, die Datei sei aktuell, und trägt auch keine heutigen Quellen nachträglich als Herkunft ein. Die Metadaten dokumentieren den CAD-Export, nicht spätere manuelle Änderungen der Geometrie oder zusätzlich im Slicer eingefügte Quellen.

Mehr → 3MF neu erzeugen ist auch bei unveränderten Quellen verfügbar. Vor dem Bestätigen das bisherige Projekt im Slicer schließen. Exportiert wird die ausgewählte gespeicherte Revision mit ihren serverseitig aufgelösten Abhängigkeiten; lokale Checkout-Änderungen müssen vorher eingecheckt werden. Die Neuerzeugung übernimmt keine Druckeinstellungen, Plattenanordnung, Farbzuweisungen oder zusätzlich eingefügten Quellen. Sie sichert die bisherige 3MF und sync.json lokal unter backups/<UTC-Zeitstempel>-<Kennung>/ neben dem Arbeitsstand. Zum Wiederherstellen die gesicherte 3MF im Slicer öffnen und als Arbeitsdatei speichern. Erst nach erfolgreichem Export, Prüfung und Sicherung wird die Arbeitsdatei ersetzt und synchronisiert. Ein fehlgeschlagener Export oder eine fehlgeschlagene Sicherung lässt die bisherige 3MF unangetastet.

Slicer-Synchronisation

Eine Dateiüberwachung erkennt anschließend das Speichern im Slicer und lädt die geänderte 3MF automatisch hoch. sync.json enthält nur IDs und Hashes, keine Zugangsdaten. Änderungen auf zwei Rechnern werden über den letzten Server-Hash erkannt; bei einem Konflikt bleibt die lokale Datei unangetastet. Der Workflow benötigt die Token-Scopes read und write, aber keinen Checkout und keinen zusätzlichen Hintergrunddienst.

Der Einzelrechner-Workflow wurde mit FreeCAD Flatpak und Bambu Studio Flatpak manuell abgenommen. Noch offen ist der manuelle Test mit zwei Rechnern: Serverstand auf Rechner B laden und eine parallele Änderung als Konflikt erkennen. Der Server überschreibt bei einem veralteten Basis-Hash nicht still.

Tests

python3 -m unittest discover -s tests

Installation über den FreeCAD Addon Manager

Das Repo enthält ein package.xml für den FreeCAD Addon Manager. In FreeCAD kann das Addon als benutzerdefiniertes Repository installiert werden.

Repository-URL:

https://git.home.schumbi.de/ralf/freecad-plm-addon

Branch:

main

Danach FreeCAD neu starten und die Workbench FreeCAD-PLM aktivieren. Beim Start wird zugleich der Web-Link-Handler für Linux oder Windows eingerichtet. Für die Nutzung muss anschließend im Addon unter Verbindungseinstellungen die Server-URL, ein API-Token und der lokale Workspace gesetzt werden.

Die serverseitige Forgejo- und Reverse-Proxy-Konfiguration für eine Installation mit einem unveränderten FreeCAD ist in docs/ADDON_MANAGER_HOSTING.md dokumentiert.

FreeCAD-Installation für die Entwicklung

FreeCAD lädt externe Workbenches aus seinem Benutzer-Mod-Verzeichnis. Der robusteste Weg ist, den Pfad in der jeweiligen FreeCAD-Installation direkt abzufragen:

import FreeCAD as App
App.getUserAppDataDir()

Das Addon muss dann als Ordner Mod/freecad-plm-addon unter diesem Pfad liegen.

Linux: Flatpak

Auf diesem Rechner wird FreeCAD per Flatpak gestartet:

/usr/bin/flatpak run --branch=stable --arch=x86_64 --command=FreeCAD --file-forwarding org.freecad.FreeCAD - --single-instance @@ %F @@

Der lokale FreeCAD-1.1-User-AppData-Pfad ist:

~/.var/app/org.freecad.FreeCAD/data/FreeCAD/v1-1/

Für die Entwicklung kann das Repo dorthin verlinkt werden:

mkdir -p ~/.var/app/org.freecad.FreeCAD/data/FreeCAD/v1-1/Mod
ln -s /home/ralf/devel/freecad-plm/freecad-plm-addon \
  ~/.var/app/org.freecad.FreeCAD/data/FreeCAD/v1-1/Mod/freecad-plm-addon

Falls der Link schon existiert:

ls -l ~/.var/app/org.freecad.FreeCAD/data/FreeCAD/v1-1/Mod/freecad-plm-addon

Linux: klassische Installation

Bei einer nicht-Flatpak-Installation ist der Pfad typischerweise:

mkdir -p ~/.local/share/FreeCAD/Mod
ln -s /home/ralf/devel/freecad-plm/freecad-plm-addon \
  ~/.local/share/FreeCAD/Mod/freecad-plm-addon

Windows: FreeCAD .exe

In FreeCADs Python-Konsole zuerst den Benutzerpfad abfragen:

import FreeCAD as App
App.getUserAppDataDir()

Dann das Addon als Ordner in dessen Mod-Unterordner kopieren, zum Beispiel:

%APPDATA%\FreeCAD\Mod\freecad-plm-addon

oder bei versionierten FreeCAD-Profilen:

%APPDATA%\FreeCAD\v1-1\Mod\freecad-plm-addon