Andrés Zsögön
0bed3c80a2
- Add responsive touch and pen workflows across the editor, Gallery, Merger, and About views. - Improve Gallery density, batching, and thumbnail memory behavior. - Localize the updated interface and installation documentation across all supported languages.
26 KiB
English | Deutsch | Español | Français | हिन्दी | Português | Русский | 日本語 | 한국어 | 中文 | 繁體中文
OpenPose Studio for ComfyUI 🤸
OpenPose Studio ist eine fortschrittliche ComfyUI-Erweiterung zum Erstellen, Bearbeiten, Anzeigen und Organisieren von OpenPose-Posen mit einer schlanken, benutzerfreundlichen Oberfläche. Sie erleichtert das visuelle Anpassen von Keypoints, das Speichern und Laden von Pose-Dateien, das Durchsuchen von Pose-Presets und Galerien, das Verwalten von Pose-Sammlungen, das Zusammenführen mehrerer Posen sowie den Export sauberer JSON-Daten zur Verwendung in ControlNet und anderen posegesteuerten Workflows.
Inhaltsverzeichnis
- ✨ Funktionen
- 📱 Responsive Mobile-Oberfläche
- 📦 Installation
- 🎯 Verwendung
- 🖐️ Handbearbeitung
- 🔧 Nodes
- ⌨️ Editor-Steuerung und Tastenkürzel
- 📋 Formatspezifikationen
- 🖼️ Galerie und Pose-Verwaltung
- 🔀 Pose Merger
- 🎨 Render
- 🖼️ Hintergrundreeferenz
- 🗺️ Areas Input
- ⚠️ Bekannte Einschränkungen
- 🔍 Fehlerbehebung
- 🤝 Mitwirken
- 💙 Finanzierung und Support
- 📄 Lizenz
Funktionen
✨ Kernfunktionen
- Echtzeit-Bearbeitung von OpenPose-Keypoints mit visuellem Feedback
- Individuelle Bearbeitung von Hand-Keypoints in einem fokussierten, vergrößerten Handeditor
- Modernes natives Canvas-Rendering-Engine (schneller, flüssiger, weniger bewegliche Teile)
- Interaktive Bearbeitungs-UX: klare aktive Auswahl + Pose-Hover-Vorauswahl
- Eingeschränkte Transformationen, damit Keypoints nicht aus den Canvas-Grenzen driften
- JSON-Import/Export für einzelne Poses und Pose-Sammlungen
- Standard-OpenPose-JSON-Export (portierbar zu anderen Tools)
- Legacy-JSON-Kompatibilität (kann ältere nicht-standardmäßige JSON laden und korrekt bearbeiten)
✨ Erweiterte Funktionen
- Render Toggles: Body / Hands / Face optional rendern
- Pose Gallery: Poses aus
poses/durchsuchen und voransehen - Pose Collections: Multi-Pose-JSON-Dateien als einzeln auswählbare Poses angezeigt
- Pose Merger: Mehrere JSON-Dateien zu organisierten Sammlungen zusammenführen
- Quick Cleanup Actions: Face-Keypoints und/oder linke/rechte Hand-Keypoints entfernen, wenn vorhanden
- Optional Cleanup on Export: Face- und/oder Hands-Keypoints beim Export von Pose-Packs entfernen
- Background Overlay System: Auswählbare Contain/Cover-Modi mit Opazitätskontrolle
- Undo: Vollständiger Bearbeitungsverlauf während der Sitzung
✨ Datenverarbeitung
- Automatische Pose-Dateierkennung aus
poses/(einschließlich Unterverzeichnisse) - Validierung und Fehlerwiederherstellung für fehlerhafte JSON-Dateien
- Unterstützung für Teilposen (Teilmenge von Body-Keypoints)
- Pixelraum-Koordinaten, die mit Pose-Dateien für nahtlose Kompatibilität übereinstimmen
✨ UI und Integration
- Vollständig responsives Layout: passt sich in Echtzeit an jede Fenstergröße an und bleibt zentriert
- Automatische Anpassungsskalierung, wenn das Canvas sonst nicht auf den Bildschirm passt
- Verbesserte Canvas-Optik: Hintergrundgitter + Mittelachsen im Stil von Blender
- Persistenz nach Neustart: Galerie-Ansichtsmodus + Hintergrundüberlagerungs-Einstellungen beim Start wiederhergestellt
- Native ComfyUI-Integrationen: Toasts + Dialoge (mit sicherem Fallback)
Responsive Mobile-Oberfläche
OpenPose Studio ist in mobilen Browsern vollständig responsiv und touchfreundlich. Der Editor hält das Canvas auf schmalen Bildschirmen nutzbar, stellt Preset- und COCO-Keypoint-Werkzeuge als fokussierte Ansichten bereit und bietet eine kompakte Gallery mit mehreren Thumbnail-Größen.
Canvas-Bearbeitung, Preset-Steuerung, Verwaltung fehlender Keypoints und die Gallery-Ansicht „Small Icons“ unter Android.
Wenn Sie eine Idee für eine neue Funktion haben, würde ich sie gerne hören — vielleicht können wir sie schnell umsetzen. Bitte senden Sie Feedback, Ideen oder Vorschläge über die Issues-Seite des Repositorys: https://github.com/andreszs/comfyui-openpose-studio/issues
Installation
Anforderungen
- ComfyUI (aktueller Build)
- Python 3.10+
Option 1: Nativer Extension Manager (empfohlen)
- Öffne den nativen Extension Manager von ComfyUI und anschließend den Nodes Manager.
- Suche nach
openpose-studiound wähle OpenPose Studio aus. - Klicke auf Install und starte ComfyUI nach Abschluss der Installation neu.
Option 2: Manuelle Installation
Öffne ein Terminal in ComfyUI/custom_nodes/ und klone das Repository:
git clone https://github.com/andreszs/comfyui-openpose-studio.git
Starte ComfyUI nach dem Klonen des Repositorys neu.
Installation überprüfen
Vergewissere dich, dass OpenPose Studio im Node-Menü unter image > OpenPose Studio erscheint.
Verwendung
Grundlegender Workflow
- Den OpenPose Studio-Node zum Workflow hinzufügen
- Auf die Vorschau-Canvas des Nodes klicken, um die Editor-UI zu öffnen
- Eine Pose aus den Voreinstellungen oder der Galerie auswählen, um sie in die Canvas einzufügen
- Keypoints durch Ziehen auf der Canvas anpassen
- Auf Apply klicken, um die Pose zu rendern. Dadurch wird das serialisierte JSON im Node erstellt.
- Den
image-Ausgang mit nachfolgenden Bild-Nodes verbinden - Den
kps-Ausgang mit ControlNet/OpenPose-kompatiblen Nodes verbinden
Editor-Vorschau
Handbearbeitung
Importierte OpenPose-Hände können als Gruppe transformiert oder Keypoint für Keypoint verfeinert werden. Wählen Sie eine Hand auf der Canvas aus, um ihren Transformationsrahmen anzuzeigen. Mit den umgebenden Handles können Sie die Hand skalieren, drehen, spiegeln oder den fokussierten Handeditor öffnen.
Der fokussierte Editor lässt sich auch direkt über das Bleistift-Symbol neben Left hand oder Right hand in der Seitenleiste öffnen. Ziehen Sie in dieser Ansicht die Keypoints 1–20, um die Finger anzupassen; Keypoint 0 bleibt als Handanker gesperrt. Beim Überfahren eines Eintrags in der Seitenleiste wird der zugehörige Punkt hervorgehoben. Mit dem Häkchen wird die gesamte Handbearbeitung als eine rückgängig machbare Änderung übernommen. Mit dem Schließen-Symbol oder Escape werden die Änderungen verworfen.
Nodes
OpenPose Studio
Kategorie: image
- Eingang:
Pose JSON(STRING) — Standard-OpenPose-JSON. - Optionale Eingänge:
areas(CONDITIONING_AREAS) — Bereichs-Overlay-Daten; denareas_out-Ausgang eines Conditioning Pipeline (Combine)-Nodes verbinden, um Konditionierungsbereiche auf der Canvas zu visualisieren
- Optionen:
render body— Body in das gerenderte Vorschau-/Ausgabebild einbeziehenrender hands— Hands in das gerenderte Vorschau-/Ausgabebild einbeziehen (falls im JSON vorhanden)render face— Face in das gerenderte Vorschau-/Ausgabebild einbeziehen (falls im JSON vorhanden)
- Ausgänge:
IMAGE— Gerenderte Pose-Visualisierung als RGB-Bild (float32, Bereich 0-1)JSON— OpenPose-JSON mit Canvas-Abmessungen und People-Array mit Keypoint-DatenKPS— Keypoint-Daten im POSE_KEYPOINT-Format, kompatibel mit ControlNet
- UI: Auf die Node-Vorschau klicken, um den interaktiven Editor zu öffnen. Den open editor-Button (Bleistift-Symbol) verwenden, um die Pose direkt zu bearbeiten.
Node-Screenshot
Editor-Steuerung und Tastenkürzel
Tastaturkürzel
| Steuerung | Aktion |
|---|---|
| Enter | Pose anwenden und Editor schließen |
| Escape | Abbrechen und Änderungen verwerfen |
| Ctrl+Z | Letzte Aktion rückgängig machen |
| Ctrl+Y | Zuletzt rückgängig gemachte Aktion wiederherstellen |
| Delete | Ausgewählten Keypoint entfernen |
Canvas-Interaktionen
- Klick: Keypoint auswählen
- Ziehen: Keypoint an neue Position verschieben
- Scrollen: Auf der Canvas herein-/herauszoomen (TO-DO)
Background Reference
Referenzbilder (z. B. Anatomieführer, Fotovorlagen) als nicht-destruktive Überlagerungen während der Pose-Bearbeitung laden. Den Contain-Modus verwenden, um Bilder in der Canvas einzupassen, oder den Cover-Modus, um die Canvas zu füllen. Opazität nach Bedarf anpassen.
- Load Image: Referenzbild von Datenträger importieren
- Contain/Cover: Skalierungsmodus wählen
- Opacity: Transparenz anpassen (0-100%)
Note
Hintergrundbilder bleiben während der ComfyUI-Sitzung erhalten, werden aber nicht in Workflows gespeichert.
Areas Input
Der areas-Eingang ist eine optionale Verbindung, die während der Pose-Bearbeitung Konditionierungsbereichsgrenzen auf der Canvas überlagert.
Den areas_out-Ausgang des Conditioning Pipeline (Combine)-Nodes aus dem ComfyUI-LoRA-Pipeline-Repository verbinden, um die Zielbereiche jedes Bereichs beim Positionieren der Posen zu visualisieren.
Jeder Bereich wird als beschriftetes Badge auf der Canvas angezeigt. Auf ein Badge klicken, um den jeweiligen Bereich einzeln zu aktivieren oder zu deaktivieren, sodass die für die aktuelle Pose relevanten Regionen im Fokus bleiben.
Diese Kombination ist besonders nützlich beim Aufbau von Multi-Charakter-Workflows: ComfyUI-LoRA-Pipeline übernimmt die bereichsbezogene Konditionierung und LoRA-Zuweisung, während OpenPose Studio die präzise Positionierung der Posen innerhalb jedes Bereichs gewährleistet. Das Ergebnis ist ein unkompliziertes, nicht-destruktives Setup, in dem sowohl bereichsbezogene als auch posenbezogene LoRAs gleichzeitig ohne gegenseitige Beeinflussung angewendet werden können. Wer noch nicht mit bereichsbasierter Konditionierung vertraut ist: Die ComfyUI-LoRA-Pipeline-Erweiterung ist genau für diese Art von Workflow konzipiert und lässt sich hervorragend mit diesem Node kombinieren.
Ein reales Beispiel, das alle drei Repos gemeinsam nutzt — Bereichskonditionierung, OpenPose-Steuerung und Style-Layering — ist in diesem Schritt-für-Schritt-Workflow-Guide zu finden.
Formatspezifikationen
Dieser Editor unterstützt vollständig die OpenPose COCO-18 (body)-Bearbeitung und die individuelle Bearbeitung von OpenPose-Hand-Keypoints. Face-Keypoints werden beibehalten und gerendert, bleiben jedoch Pass-Through-Daten und können derzeit nicht einzeln bearbeitet werden.
OpenPose COCO-18-Keypoints (body)
COCO-18 verwendet 18 Body-Keypoints. Die Pose wird als flaches Array namens pose_keypoints_2d mit dem Muster gespeichert:
[x0, y0, c0, x1, y1, c1, ...]
Dabei hat jeder Keypoint:
x,y: Pixelkoordinaten auf der Canvasc: Konfidenz (üblicherweise0..1;0kann für „fehlende" Punkte verwendet werden)
Keypoint-Reihenfolge (Index → Name):
| Index | Name |
|---|---|
| 0 | Nase |
| 1 | Hals |
| 2 | Rechte Schulter |
| 3 | Rechter Ellbogen |
| 4 | Rechtes Handgelenk |
| 5 | Linke Schulter |
| 6 | Linker Ellbogen |
| 7 | Linkes Handgelenk |
| 8 | Rechte Hüfte |
| 9 | Rechtes Knie |
| 10 | Rechter Knöchel |
| 11 | Linke Hüfte |
| 12 | Linkes Knie |
| 13 | Linker Knöchel |
| 14 | Rechtes Auge |
| 15 | Linkes Auge |
| 16 | Rechtes Ohr |
| 17 | Linkes Ohr |
Note
COCO bezieht sich auf die Common Objects in Context-Keypoint-Konvention/Dataset-Bezeichnung, die in der Pose-Schätzung weit verbreitet ist. „COCO-18" bezeichnet hier das OpenPose-Body-Layout mit 18 Keypoints.
Minimale JSON-Struktur
Ein typisches OpenPose-JSON für eine einzelne Pose enthält Canvas-Abmessungen und einen people-Eintrag mit pose_keypoints_2d:
{
"canvas_width": 512,
"canvas_height": 512,
"people": [
{
"pose_keypoints_2d": [0, 0, 0, 0, 0, 0 /* ... 18 * 3 values total ... */]
}
]
}
Note
Der Editor kann Teilposen verarbeiten (einige Keypoints fehlen). Fehlende Punkte werden typischerweise als 0,0,0 dargestellt. Mit dem Pose Editor können auch distale Keypoints gelöscht werden.
Weiterführende Literatur
- Geschichte und Kontext: „What is OpenPose — Exploring a milestone in pose estimation" — ein verständlicher Artikel, der erklärt, wie OpenPose eingeführt wurde und seine Auswirkungen auf die Pose-Schätzung: https://www.ultralytics.com/blog/what-is-openpose-exploring-a-milestone-in-pose-estimation
JSON-Format: Standard vs. Legacy
- OpenPose Studio: liest/schreibt Standard-OpenPose-JSON und akzeptiert auch älteres nicht-standardmäßiges (Legacy-)JSON.
Praktische Hinweise:
- Das Einfügen von Standard-JSON in den OpenPose Studio-Node rendert die Vorschau sofort.
Galerie und Pose-Verwaltung
Überblick
Die Gallery-Registerkarte bietet visuelles Durchsuchen aller verfügbaren Poses mit Live-Vorschau-Thumbnails. Sie erkennt und organisiert Poses automatisch ohne manuelle Konfiguration.
Ansichtsmodi
Die Gallery unterstützt vier Anzeigemodi:
- Large — größere Vorschauen für schnelle visuelle Auswahl
- Medium — ausgewogene Vorschaugröße und -dichte
- Small — dichtes Symbolraster, optimiert für schmale und mobile Layouts
- Tiles — kompaktes Raster mit zusätzlichen Metadaten (z. B. Canvas-Größe, Keypoint-Anzahl und weitere Pose-Details)
Funktionen
- Auto-discovery: Scannt das
poses/-Verzeichnis beim Start - Nested organization: Unterverzeichnisnamen werden zu Gruppenbezeichnungen
- Live preview: Thumbnail-Rendering für jede Pose in Echtzeit
- Search/filter: Poses nach Name oder Gruppe finden
- One-click load: Pose auswählen, um sie in den Editor zu laden
Unterstützte Dateitypen
- Single-pose JSON: Einzelne OpenPose-JSON-Dateien
- Pose Collections: Multi-Pose-JSON-Dateien (jede Pose wird separat angezeigt)
- Nested directories: Poses in Unterverzeichnissen werden automatisch gruppiert
Deterministisches Verhalten
Galeriereihenfolge und -erkennung sind vollständig deterministisch:
- Kein zufälliges Mischen
- Konsistente alphabetische Sortierung
- Root-Poses zuerst aufgelistet, dann gruppierte Poses
- Sofortiges Neuladen aller JSON-Poses beim Öffnen des Editor-Fensters.
Pose Merger
Zweck
Die Pose Merger-Registerkarte fasst mehrere einzelne Pose-JSON-Dateien in organisierten Pose-Sammlungsdateien zusammen. Dies ist nützlich für:
- Konvertierung großer Pose-Bibliotheken in einzelne Dateien
- Bereinigung von Pose-Daten (Entfernung von Face/Hand-Keypoints)
- Reorganisation und Umbenennung von Poses
- Effiziente Verteilung von Pose-Paketen
Workflow
- Add Files: Einzelne oder Sammlungs-JSON-Dateien laden
- Preview: Jede Pose wird mit Thumbnail angezeigt
- Configure: Face/Hand-Komponenten optional ausschließen
- Export: Als kombinierte Sammlung oder einzelne Dateien speichern
Hauptfunktionen
| Funktion | Anwendungsfall |
|---|---|
| Load Multiple Files | Massenimport aus dem Dateisystem |
| Component Filtering | Unnötige Face/Hand-Daten entfernen |
| Collection Expansion | Poses aus bestehenden Sammlungen extrahieren |
| Batch Renaming | Beim Export sinnvolle Namen vergeben |
| Selective Export | Auswählen, welche Poses einbezogen werden |
Ausgabeoptionen
- Combined Collection: Einzelnes JSON mit allen Poses
- Individual Files: Eine Datei pro Pose (für Kompatibilität)
Beide Ausgabeformate werden automatisch von Gallery und Pose Selector erkannt.
Render
Das Render-Modul lässt dich anpassen, wie der OpenPose-Stickman beim Ausführen des Workflows gerendert wird. Es bietet Stiloptionen für body, hands und face, darunter Linienbreite, Keypoint-Radius und Keypoint-Farbe für hands/face.
Render-Einstellungen werden lokal im local storage dieses Browsers gespeichert, nicht im Workflow. Änderungen wirken sich auf nachfolgende Workflow-Ausführungen aus.
Bekannte Einschränkungen
Note
Nodes 2.0 wird unterstützt. Wenn die Vorschau-Canvas oder die Editor-Schaltfläche fehlt, prüfe Browser-Cache, Frontend-Ladevorgang und Installationslogs.
Aktuelle Einschränkungen und Workarounds
- Face-Bearbeitung
- Face-Keypoints werden beibehalten und gerendert, können aber derzeit nicht einzeln auf der Canvas bearbeitet werden.
- Auflösungskonsistenz
- Problem: Pose Merger vereinheitlicht die Auflösung bei Sammlungsexporten nicht automatisch
- Status: Erfordert sorgfältige Implementierung, um Beschneidung zu vermeiden
- Workaround: Poses vor dem Import auf Zielauflösung vorkalibieren
- Nodes 2.0-Kompatibilität
- Status: In aktuellen Versionen unterstützt.
- Hinweis: Wenn die Editor-UI nicht erscheint, sind die wahrscheinlichsten Ursachen ein veralteter Browser-Cache, fehlgeschlagenes Laden von Frontend-Modulen oder eine unvollständige Installation.
- Fehlerdiagnose: ComfyUI vollständig neu starten, den Browser hart aktualisieren und Browser-Konsole sowie ComfyUI-Startlog prüfen.
Fehlerwiederherstellung
Das Plugin enthält defensives Fehlerhandling:
- Ungültige JSON-Dateien werden in der Gallery lautlos übersprungen
- Render-Fehler geben leere Bilder zurück, anstatt abzustürzen
- Fehlende Metadaten fallen auf sichere Standardwerte zurück
- Fehlerhafte Keypoints werden beim Rendern gefiltert
Fehlerbehebung
Häufige Probleme und Lösungen
Poses erscheinen nicht in der Gallery
✓ Bestätigen, dass Dateien im poses/-Verzeichnis vorhanden sind
✓ JSON auf Gültigkeit prüfen (Online-JSON-Validator verwenden)
✓ Prüfen, ob Dateiendung .json ist (Groß-/Kleinschreibung auf Linux relevant)
✓ ComfyUI neu starten, um die Erkennung auszulösen
✓ Browserkonsole (F12) auf Fehlermeldungen prüfen
JSON-Import schlägt fehl
✓ JSON-Struktur validieren (muss "pose_keypoints_2d" oder Äquivalent haben)
✓ Sicherstellen, dass Koordinaten gültige Zahlen sind, keine Strings
✓ Mindestens 18 Keypoints für Body-Poses bestätigen
✓ Auf fehlerhafte Escape-Sequenzen im JSON prüfen
Leeres Ausgabebild
✓ Sicherstellen, dass Pose ausgewählt ist und gültige Keypoints enthält
✓ Canvas-Abmessungen (Breite/Höhe) prüfen, vernünftig (100-2048px)
✓ Auf Apply klicken, um nach Änderungen zu rendern
✓ Auf NaN oder unendliche Werte in Koordinaten prüfen
Background reference bleibt nicht erhalten
✓ Drittanbieter-Cookies/-Speicher im Browser aktivieren
✓ Browser-localStorage-Einstellungen prüfen
✓ Inkognito-Modus ausprobieren, um Problem zu isolieren
✓ Browser-Cache leeren und erneut versuchen
Node erscheint nicht in ComfyUI
✓ Clone-Speicherort prüfen: ComfyUI/custom_nodes/comfyui-openpose-studio
✓ Prüfen, ob __init__.py vorhanden ist und korrekt importiert
✓ ComfyUI vollständig neu starten (nicht nur Seite neu laden)
✓ ComfyUI-Konsole auf Importfehler prüfen
Mitwirken
Richtlinien für Beiträge, Pull-Request-Richtlinien, Architekturdetails und Entwicklungsinformationen finden Sie unter CONTRIBUTING.md. Wenn Sie einen KI-Agenten zur Unterstützung bei der Entwicklung einsetzen, stellen Sie sicher, dass er AGENTS.md liest, bevor er Codeänderungen vornimmt.
Finanzierung und Support
Warum Ihre Unterstützung wichtig ist
Dieses Plugin wird unabhängig entwickelt und gepflegt, mit regelmäßigem Einsatz von bezahlten KI-Agenten, um Debugging, Tests und Verbesserungen der Lebensqualität zu beschleunigen. Wenn Sie es nützlich finden, hilft finanzielle Unterstützung dabei, die Entwicklung stetig voranzubringen.
Ihr Beitrag hilft:
- KI-Tools für schnellere Korrekturen und neue Funktionen zu finanzieren
- Laufende Wartungs- und Kompatibilitätsarbeiten bei ComfyUI-Updates zu decken
- Entwicklungsverlangsamungen zu verhindern, wenn Nutzungsgrenzen erreicht werden
Tip
Keine Spende möglich? Ein GitHub-Stern ⭐ hilft dennoch sehr, indem er die Sichtbarkeit verbessert und mehr Nutzern zugute kommt.
💙 Dieses Projekt unterstützen
Lieber scannen? QR-Codes anzeigen
Ko-fi
|
PayPal
|
USDC (Arbitrum) ⚠️
|
USDC-Adresse anzeigen
0xe36a336fC6cc9Daae657b4A380dA492AB9601e73
Warning
USDC nur auf Arbitrum One senden. Transfers auf anderen Netzwerken kommen nicht an und können dauerhaft verloren gehen.
Lizenz
MIT-Lizenz – vollständiger Text in der Datei LICENSE.
Zusammenfassung:
- ✓ Kostenlos für kommerzielle Nutzung
- ✓ Kostenlos für private Nutzung
- ✓ Ändern und verteilen
- ✓ Lizenz und Copyright-Hinweis beilegen
Zusätzliche Ressourcen
Verwandte Projekte
- ComfyUI - Kernframework
- comfyui_controlnet_aux - ControlNet-Unterstützung
- OpenPose - Ursprüngliche Pose-Erkennung
Dokumentation
- ComfyUI Custom Nodes Guide
- OpenPose Models & Keypoints
- Canvas 2D API - Rendering-Engine
Fehlerbehebungsanleitungen
Gepflegt von: andreszs
Status: Aktive Entwicklung