nodes/andreszs-ComfyUI-Ultralytics-Studio
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
36acbd35c251140865c180b3ff5cdfd88aeeea25
andreszs-ComfyUI-Ultralytic…/docs/README.de.md
T

24 KiB
Raw Blame History

English | Deutsch | Español | Français | Português | Русский | 日本語 | 한국어 | 中文 | 繁體中文

Version Last Commit License


Ultralytics Studio for ComfyUI 🤸

Eine professionelle Ultralytics-Editor-Erweiterung für Produktions-Workflows mit intuitiver Oberfläche, umfassendem Pose-Management und robuster JSON-Verarbeitung. Vollständig rückwärtskompatibel mit dem ursprünglichen Ultralytics Studio, der über ComfyUI Manager verteilt wird.

Inhaltsverzeichnis

Funktionen

✨ Kernfunktionen

  • Echtzeit-Bearbeitung von OpenPose-Keypoints mit visuellem Feedback
  • 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

Ultralytics 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.

Responsive mobile Ultralytics-Studio-Oberfläche mit Canvas-, Preset-, COCO-Keypoint- und Gallery-Ansichten

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-Ultralytics-Studio/issues

Installation

Voraussetzungen

  • ComfyUI (aktueller Build)
  • Python 3.10+

Schritte

  1. Dieses Repository in ComfyUI/custom_nodes/ klonen.
  2. ComfyUI neu starten.
  3. Bestätigen, dass die Nodes unter image > Ultralytics Studio erscheinen.

Verwendung

Grundlegender Workflow

  1. Den Ultralytics Studio-Node zum Workflow hinzufügen
  2. Auf die Vorschau-Canvas des Nodes klicken, um die Editor-UI zu öffnen
  3. Eine Pose aus den Voreinstellungen oder der Galerie auswählen, um sie in die Canvas einzufügen
  4. Keypoints durch Ziehen auf der Canvas anpassen
  5. Auf Apply klicken, um die Pose zu rendern. Dadurch wird das serialisierte JSON im Node erstellt.
  6. Den image-Ausgang mit nachfolgenden Bild-Nodes verbinden
  7. Den kps-Ausgang mit ControlNet/OpenPose-kompatiblen Nodes verbinden

Editor-Vorschau

Ultralytics Studio UI

Nodes

Ultralytics Studio

Kategorie: image

  • Eingang: Pose JSON (STRING) — Standard-OpenPose-JSON.
  • Optionale Eingänge:
    • areas (CONDITIONING_AREAS) — Bereichs-Overlay-Daten; den areas_out-Ausgang eines Conditioning Pipeline (Combine)-Nodes verbinden, um Konditionierungsbereiche auf der Canvas zu visualisieren
  • Optionen:
    • render body — Body in das gerenderte Vorschau-/Ausgabebild einbeziehen
    • render 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-Daten
    • KPS — 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

Ultralytics Studio node

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)

Handbearbeitung

Hände verwenden das Ultralytics/MediaPipe-Layout mit 21 Keypoints. Wähle eine Hand auf der Canvas aus, um Steuerelemente zum Verschieben, Skalieren, Drehen und Spiegeln der gesamten Hand anzuzeigen.

Auswahl- und Transformationssteuerung für Hände

Öffne den fokussierten Editor über den Stiftgriff. Ziehe einzelne Gelenke auf die Referenzpositionen; die Seitenleiste führt alle 21 Keypoints auf und ermöglicht das Entfernen oder Wiederherstellen bearbeitbarer Punkte. Bestätige mit ✓ oder verwirf die Änderungen mit ×.

Fokussierter Handeditor mit 21 Keypoints

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.

Areas Input

Diese Kombination ist besonders nützlich beim Aufbau von Multi-Charakter-Workflows: ComfyUI-LoRA-Pipeline übernimmt die bereichsbezogene Konditionierung und LoRA-Zuweisung, während Ultralytics Studio die präzise Positionierung der Posen innerhalb jedes Bereichs gewährleistet.

Pose Keypoint Input

Der pose_keypoint-Eingang ist eine optionale Verbindung, mit der Ultralytics Studio Posen-Daten aus vorgelagerten Nodes im Workflow übernehmen kann.

Den Ausgang eines DWPose Estimator (oder eines kompatiblen vorgelagerten Pose-Schätzers) mit diesem Eingang verbinden. Die erkannten Keypoints werden direkt in den Editor geladen, wo sie vor dem Rendern geprüft, verfeinert oder erweitert werden können.

Falls die eingehende Pose im Format COCO-18 (OpenPose) vorliegt, wird sie vor dem Laden automatisch in COCO-17 (Ultralytics) konvertiert. Bei dieser Konvertierung wird eine Benachrichtigung angezeigt.

Pose Keypoint Input — Ausgang des Pose-Schätzers mit dem pose_keypoint-Eingang von Ultralytics Studio verbunden

Formatspezifikationen

Dieser Editor unterstützt vollständig die Ultralytics COCO-17 (body)-Bearbeitung.

Er unterstützt auch OpenPose Face- und Hands-Daten: Hand-Keypoints können mit dem 21-Punkte-Handeditor ausgewählt, transformiert und bearbeitet werden. Gesichts-Keypoints werden beibehalten und gerendert, können aber noch nicht bearbeitet werden.

Ultralytics COCO-17-Keypoints (body)

COCO-17 verwendet 17 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 Canvas
  • c: Konfidenz (üblicherweise 0..1; 0 kann für „fehlende" Punkte verwendet werden)

Keypoint-Reihenfolge (Index → Name):

Index Name
0 Nase
1 Linkes Auge
2 Rechtes Auge
3 Linkes Ohr
4 Rechtes Ohr
5 Linke Schulter
6 Rechte Schulter
7 Linker Ellbogen
8 Rechter Ellbogen
9 Linkes Handgelenk
10 Rechtes Handgelenk
11 Linke Hüfte
12 Rechte Hüfte
13 Linkes Knie
14 Rechtes Knie
15 Linker Knöchel
16 Rechter Knöchel

Note

COCO bezieht sich auf die Common Objects in Context-Keypoint-Konvention/Dataset-Bezeichnung, die in der Pose-Schätzung weit verbreitet ist. „COCO-17" bezeichnet hier das Ultralytics-Body-Layout mit 17 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 /* ... 17 * 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

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.

Pose Gallery

Ansichtsmodi

Die Gallery unterstützt drei Anzeigemodi:

  • Large — größere Vorschauen für schnelle visuelle Auswahl
  • Medium — ausgewogene Vorschaugröße und -dichte
  • 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

  1. Add Files: Einzelne oder Sammlungs-JSON-Dateien laden
  2. Preview: Jede Pose wird mit Thumbnail angezeigt
  3. Configure: Face/Hand-Komponenten optional ausschließen
  4. 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.

Bekannte Einschränkungen

Warning

Nodes 2.0 wird derzeit nicht unterstützt. Bitte Nodes 2.0 vorerst deaktivieren.

Aktuelle Einschränkungen und Workarounds

  1. Face-Bearbeitung
  • Problem: Gesichts-Keypoints werden beibehalten und gerendert, können aber nicht bearbeitet werden
  • Status: Für zukünftige Version geplant
  • Workaround: Pose Merger verwenden, um Face-JSON vor dem Import manuell zu bearbeiten
  1. 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 vorskalieren
  1. Nodes 2.0-Kompatibilität
  • Problem: Der Node verhält sich nicht korrekt, wenn ComfyUI „Nodes 2.0" aktiviert ist.
  • Status: Fix geplant, aber es ist ein großes und zeitaufwändiges Refactoring.
  • Hinweis: Dieses Projekt wird mit bezahlten KI-Agenten entwickelt. Sobald Mittel für zusätzliche KI-Token verfügbar sind, beabsichtige ich, die Nodes 2.0-Unterstützung zu priorisieren.
  • Workaround: Nodes 2.0 vorerst deaktivieren.

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 17 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-Ultralytics-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

USDC (nur Arbitrum ⚠️)

USDC Badge

Adresse anzeigen
Lieber scannen? QR-Codes anzeigen
Ko-fi
Ko-fi QR Code 		PayPal
PayPal QR Code 		USDC (Arbitrum) ⚠️
USDC (Arbitrum) QR Code

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

Dokumentation

Fehlerbehebungsanleitungen

Gepflegt von: andreszs
Status: Aktive Entwicklung

Reference in New Issue View Git Blame Copy Permalink