Comfyui-LayerForge/MASK_AUTO_LOADING_README.md

Automatyczne Nakładanie Masek w Mask Editorze

🎯 Cel

Ta funkcjonalność rozwiązuje problem automatycznego nakładania predefiniowanych masek w mask editorze ComfyUI. Główną zaletą jest możliwość wysłania czystego obrazu (bez maski) do editora, a następnie automatyczne nałożenie maski w edytorze, co pozwala na prawidłowe działanie narzędzi takich jak gumka.

✨ Kluczowe Zalety

• 🖼️ Czysty Obraz: Wysyłanie obrazu bez istniejącej maski
• 🎨 Prawidłowa Gumka: Editor "pamięta" oryginalny obraz pod maską
• ⚡ Automatyzacja: Maska nakładana automatycznie po otwarciu
• 🔄 Kompatybilność: Obsługa nowego i starego mask editora
• 📐 Elastyczność: Różne formaty masek (Image, Canvas)

🚀 Szybki Start

Automatyczne Zachowanie (Zalecane)

import { start_mask_editor_auto } from './js/utils/mask_utils.js';

// Uruchom mask editor z automatycznym zachowaniem:
// - Wyślij czysty obraz (bez maski)
// - Automatycznie nałóż istniejącą maskę z canvas
start_mask_editor_auto(canvasInstance);

Użycie z Predefiniowaną Maską

import { start_mask_editor_with_predefined_mask, create_mask_from_image_src } from './js/utils/mask_utils.js';

// Załaduj maskę z URL
const maskImage = await create_mask_from_image_src('/path/to/mask.png');

// Uruchom mask editor z czystym obrazem i predefiniowaną maską
start_mask_editor_with_predefined_mask(canvasInstance, maskImage, true);

Bezpośrednie Użycie Canvas API

// Automatyczne zachowanie (domyślne)
await canvasInstance.startMaskEditor();

// Z predefiniowaną maską
await canvasInstance.startMaskEditor(maskImage, true);

📚 API Reference

Canvas.startMaskEditor(predefinedMask, sendCleanImage)

Parametry:

• predefinedMask (Image|HTMLCanvasElement|null) - Maska do nałożenia
• sendCleanImage (boolean) - Czy wysłać czysty obraz (domyślnie false)

Funkcje Pomocnicze

start_mask_editor_with_predefined_mask(canvasInstance, maskImage, sendCleanImage)

Główna funkcja pomocnicza do uruchamiania editora z maską.

create_mask_from_image_src(imageSrc)

Tworzy obiekt Image z URL.

canvas_to_mask_image(canvas)

Konwertuje Canvas do Image.

💡 Przykłady Użycia

1. Maska z URL

const maskImage = await create_mask_from_image_src('/masks/face_mask.png');
start_mask_editor_with_predefined_mask(canvas, maskImage, true);

2. Maska z Canvas

// Stwórz maskę programowo
const maskCanvas = document.createElement('canvas');
const ctx = maskCanvas.getContext('2d');
// ... rysowanie maski ...

const maskImage = await canvas_to_mask_image(maskCanvas);
start_mask_editor_with_predefined_mask(canvas, maskImage, true);

3. Maska z Danych Binarnych

const blob = new Blob([binaryData], { type: 'image/png' });
const dataUrl = URL.createObjectURL(blob);
const maskImage = await create_mask_from_image_src(dataUrl);
start_mask_editor_with_predefined_mask(canvas, maskImage, true);

🔧 Jak to Działa

1. Przygotowanie Obrazu

System wybiera odpowiednią metodę w zależności od parametru sendCleanImage:

• true: Wysyła czysty obraz bez maski
• false: Wysyła obraz z istniejącą maską

2. Otwieranie Editora

Standardowy proces otwierania mask editora ComfyUI.

3. Automatyczne Nakładanie

Po otwarciu editora system:

• Wykrywa typ editora (nowy/stary)
• Przetwarza maskę do odpowiedniego formatu
• Nakłada maskę na canvas editora
• Zapisuje stan dla undo/redo

🎛️ Tryby Działania

Czysty Obraz (Zalecany)

// Wyślij czysty obraz, nałóż maskę w edytorze
await canvas.startMaskEditor(maskImage, true);

Zalety:

• Gumka działa prawidłowo
• Editor "pamięta" oryginalny obraz
• Pełna funkcjonalność narzędzi

Kombinowany

// Wyślij obraz z istniejącą maską, dodaj nową maskę
await canvas.startMaskEditor(maskImage, false);

Zastosowanie:

• Łączenie wielu masek
• Dodawanie do istniejącej maski

🔍 Obsługa Błędów

try {
    const maskImage = await create_mask_from_image_src('/path/to/mask.png');
    start_mask_editor_with_predefined_mask(canvas, maskImage, true);
} catch (error) {
    console.error('Błąd ładowania maski:', error);
    // Fallback - uruchom bez maski
    await canvas.startMaskEditor();
}

🏗️ Architektura

Komponenty

• Canvas.js: Główna logika i API
• mask_utils.js: Funkcje pomocnicze
• Detektory Editora: Automatyczne wykrywanie typu editora
• Procesory Masek: Konwersja formatów

Przepływ Danych

Maska → Przetwarzanie → Editor → Automatyczne Nakładanie

🔧 Konfiguracja

Wymagania

• ComfyUI z mask editorem
• Obsługa ES6 modules
• Canvas API

Integracja

import { Canvas } from './js/Canvas.js';
import { start_mask_editor_with_predefined_mask } from './js/utils/mask_utils.js';

📋 Przypadki Użycia

• 🤖 AI/ML Modele: Automatyczne maski z modeli
• 📝 Szablony: Predefiniowane wzorce masek
• 🔗 Integracje: Zewnętrzne narzędzia i API
• ⚙️ Workflow: Automatyzacja procesów
• 📦 Batch Processing: Masowe przetwarzanie

🐛 Rozwiązywanie Problemów

Maska się nie nakłada

• Sprawdź czy obraz maski jest załadowany
• Upewnij się że editor jest w pełni otwarty
• Sprawdź logi w konsoli

Gumka nie działa

• Użyj sendCleanImage = true
• Sprawdź czy maska ma prawidłowy kanał alpha

Błędy kompatybilności

• Sprawdź ustawienia mask editora w ComfyUI
• Upewnij się że używasz odpowiedniej wersji

📁 Struktura Plików

js/
├── Canvas.js                    # Główne API
├── utils/
│   └── mask_utils.js           # Funkcje pomocnicze
├── examples/
│   └── mask_editor_examples.js # Przykłady użycia
└── Doc/
    └── AutoMaskLoading         # Szczegółowa dokumentacja

🔄 Kompatybilność

• ✅ Nowy mask editor ComfyUI (MessageBroker)
• ✅ Stary mask editor ComfyUI (bezpośredni dostęp)
• ✅ Wszystkie formaty masek (Image, Canvas, URL)
• ✅ Automatyczne wykrywanie konfiguracji

📈 Wydajność

• Minimalne opóźnienie nakładania (200ms)
• Automatyczna optymalizacja formatów
• Efektywne zarządzanie pamięcią
• Asynchroniczne operacje

---

Autor: Cline AI Assistant
Wersja: 1.0.0
Data: 2025-06-30