301 lines
10 KiB
Markdown
301 lines
10 KiB
Markdown
# MetaMan - Universal AI Image Metadata Manager
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://github.com/comfyanonymous/ComfyUI)
|
|
[](https://www.python.org/downloads/)
|
|
[](#supported-platforms)
|
|
|
|
A comprehensive ComfyUI custom node for managing, converting, and standardizing metadata across all major AI image generation platforms.
|
|
|
|
## 🌟 Features
|
|
|
|
MetaMan bridges the metadata gap between AI image generation services, enabling seamless workflow sharing and model dependency tracking across platforms.
|
|
|
|
### Core Capabilities
|
|
|
|
- **Universal Metadata Extraction**: Read metadata from any AI image generation service
|
|
- **Cross-Platform Workflow Generation**: Convert ANY platform's metadata into working ComfyUI workflows that recreate identical images
|
|
- **Bidirectional Format Conversion**: Convert metadata between A1111, ComfyUI, Civitai, Tensor.AI, Leonardo.AI, and more
|
|
- **Complex Workflow Preservation**: Save and restore complete ComfyUI node graphs with full fidelity
|
|
- **Model Dependency Tracking**: Automatically identify and resolve model dependencies with download URLs
|
|
- **Template-Based Extensibility**: Easy addition of new services via YAML templates
|
|
|
|
### Supported Platforms
|
|
|
|
✅ **Automatic1111 (A1111)** - Full parameter format support
|
|
✅ **ComfyUI** - Complete workflow preservation
|
|
✅ **Civitai** - Enhanced resource tracking with model IDs
|
|
✅ **Forge** - A1111-compatible with extensions
|
|
✅ **Tensor.AI** - JSON-based metadata format
|
|
✅ **Leonardo.AI** - Style and preset management
|
|
🔄 **SeaArt.AI** - Coming soon
|
|
🔄 **Midjourney** - Coming soon
|
|
|
|
## 🚀 Installation
|
|
|
|
1. **Clone to ComfyUI custom nodes:**
|
|
```bash
|
|
cd /path/to/ComfyUI/custom_nodes/
|
|
git clone <repository-url> MetaMan
|
|
```
|
|
|
|
2. **Install dependencies:**
|
|
```bash
|
|
cd MetaMan
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. **Restart ComfyUI**
|
|
|
|
The MetaMan Universal node will appear in the **MetaMan** category.
|
|
|
|
## 📖 How It Works
|
|
|
|
### Universal Metadata Standard
|
|
|
|
MetaMan uses a comprehensive **universal metadata schema** that encompasses all possible metadata fields from every supported platform. The system:
|
|
|
|
1. **Extracts** metadata from source images regardless of origin platform
|
|
2. **Converts** to universal format with field mapping and compatibility tracking
|
|
3. **Transforms** to target platform format using service-specific templates
|
|
4. **Preserves** original workflows and enables cross-platform reproduction
|
|
|
|
### Cross-Platform Workflow Conversion
|
|
|
|
MetaMan enables true **cross-platform workflow migration** with two levels of fidelity:
|
|
|
|
**✅ Simplified Workflow Generation**:
|
|
- Takes metadata from ANY platform (A1111, Civitai, Tensor.AI, etc.)
|
|
- Generates a functional workflow that **recreates the exact same image**
|
|
- Works for all platforms → ComfyUI conversion
|
|
- Perfect for moving generations between platforms
|
|
|
|
**✅ Complex Workflow Preservation**:
|
|
- Preserves original ComfyUI node graphs with custom arrangements
|
|
- Maintains advanced techniques, custom nodes, and complex routing
|
|
- Only available for ComfyUI → ComfyUI workflows
|
|
- Essential for sharing sophisticated ComfyUI creations
|
|
|
|
**Example**: An A1111 image with LoRAs and specific sampling settings becomes a ComfyUI workflow with CheckpointLoader → LoraLoader → CLIPTextEncode → KSampler → VAEDecode that produces **identical output**.
|
|
|
|
### Template System
|
|
|
|
The power of MetaMan lies in its **template-driven architecture**:
|
|
|
|
```
|
|
templates/
|
|
├── universal_schema.yaml # Defines all possible metadata fields
|
|
└── services/ # Service-specific output templates
|
|
├── automatic1111.yaml
|
|
├── comfyui.yaml
|
|
├── civitai.yaml
|
|
├── tensor.ai.yaml
|
|
└── leonardo.ai.yaml
|
|
```
|
|
|
|
### Custom "meta" PNG Chunk
|
|
|
|
MetaMan introduces a standardized **"meta" PNG chunk** containing universal metadata in JSON format, enabling perfect cross-platform compatibility while maintaining service-specific formats.
|
|
|
|
## 🎯 Usage Examples
|
|
|
|
### Basic Metadata Conversion
|
|
|
|
```python
|
|
# Extract universal metadata from any image
|
|
operation: "extract_universal"
|
|
target_service: "automatic1111"
|
|
# → Outputs: universal JSON + A1111 parameter string
|
|
|
|
# Convert A1111 image to working ComfyUI workflow
|
|
operation: "convert_to_service"
|
|
target_service: "comfyui"
|
|
# → Generates functional ComfyUI workflow that recreates identical image
|
|
```
|
|
|
|
### Cross-Platform Workflow Migration
|
|
|
|
```python
|
|
# Take any A1111/Civitai image and create ComfyUI workflow
|
|
input: A1111_image_with_metadata.png
|
|
operation: "convert_to_service"
|
|
target_service: "comfyui"
|
|
# → Output: Complete ComfyUI workflow JSON that produces same result
|
|
|
|
# Convert complex ComfyUI workflow to A1111 parameters
|
|
input: ComfyUI_workflow_image.png
|
|
operation: "convert_to_service"
|
|
target_service: "automatic1111"
|
|
# → Output: A1111-compatible parameter string (simplified but equivalent)
|
|
```
|
|
|
|
### Model Dependency Tracking
|
|
|
|
```python
|
|
operation: "generate_dependencies"
|
|
dependency_sources: "all" # Searches Civitai, HuggingFace, etc.
|
|
# → Returns JSON with download URLs and model information
|
|
```
|
|
|
|
### Workflow Preservation
|
|
|
|
```python
|
|
operation: "save_workflow"
|
|
output_format: "embed_in_image"
|
|
# → Embeds complete workflow back into the original image
|
|
```
|
|
|
|
## 🔧 Node Interface
|
|
|
|
### Inputs
|
|
|
|
**Required:**
|
|
- `image` - Input image with metadata
|
|
- `operation` - Operation type:
|
|
- `extract_universal` - Extract to universal format
|
|
- `convert_to_service` - Convert to specific service
|
|
- `save_workflow` - Save workflow data
|
|
- `generate_dependencies` - Create dependency list
|
|
- `export_metadata` - Export in various formats
|
|
- `target_service` - Target platform for conversion
|
|
|
|
**Optional:**
|
|
- `output_format` - Output format (png_chunk, json_file, txt_file, embed_in_image)
|
|
- `template_override` - Custom template path
|
|
- `include_workflow` - Include workflow data
|
|
- `include_dependencies` - Include model dependencies
|
|
- `dependency_sources` - Dependency search sources
|
|
|
|
### Outputs
|
|
|
|
- `image` - Processed image (possibly with embedded metadata)
|
|
- `universal_metadata` - Complete universal format JSON
|
|
- `service_metadata` - Target service formatted metadata
|
|
- `dependencies` - Model dependency information with download URLs
|
|
|
|
## 🎨 Advanced Features
|
|
|
|
### Service-Specific Optimizations
|
|
|
|
Each service template includes:
|
|
- **Field mappings** - Automatic parameter translation
|
|
- **Validation rules** - Ensure platform compatibility
|
|
- **Format specifications** - Proper encoding and chunk handling
|
|
- **Model resolution** - Platform-specific model identification
|
|
|
|
### Extensibility
|
|
|
|
Adding new platforms is straightforward:
|
|
|
|
1. Create a new YAML template in `templates/services/`
|
|
2. Define field mappings and output format
|
|
3. Add to `SUPPORTED_SERVICES` list
|
|
4. MetaMan automatically incorporates the new service
|
|
|
|
### Model Dependency Resolution
|
|
|
|
MetaMan tracks and resolves:
|
|
- **Checkpoints/Base Models** with SHA256 hashes
|
|
- **LoRA models** with weights and trigger words
|
|
- **Embeddings/Textual Inversions**
|
|
- **VAE models**
|
|
- **ControlNet models**
|
|
|
|
Priority search order: Civitai → HuggingFace → Other repositories
|
|
|
|
## 🛠 Technical Implementation
|
|
|
|
### Metadata Flow
|
|
|
|
```
|
|
Source Image → Extract Native Metadata → Universal Schema → Target Template → Output Format
|
|
```
|
|
|
|
### Schema Validation
|
|
|
|
- **Type checking** for all metadata fields
|
|
- **Range validation** for numeric parameters
|
|
- **Format verification** for strings and arrays
|
|
- **Compatibility checking** across services
|
|
|
|
### PNG Chunk Handling
|
|
|
|
- **Automatic encoding detection** (Latin-1 vs UTF-8)
|
|
- **Compression for large data** (workflows, dependency lists)
|
|
- **Fallback mechanisms** for incompatible content
|
|
- **Multiple chunk support** (parameters + workflow + meta)
|
|
|
|
## 🔍 Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**Metadata not detected:**
|
|
- Ensure image contains compatible metadata chunks
|
|
- Check PNG format (some services use proprietary formats)
|
|
|
|
**Conversion errors:**
|
|
- Verify source service compatibility
|
|
- Check template configuration for target service
|
|
|
|
**Missing dependencies:**
|
|
- Install all requirements: `pip install -r requirements.txt`
|
|
- Restart ComfyUI after installation
|
|
|
|
### Debug Mode
|
|
|
|
Enable verbose logging by setting environment variable:
|
|
```bash
|
|
export METAMAN_DEBUG=1
|
|
```
|
|
|
|
## 🤝 Contributing
|
|
|
|
We welcome contributions to expand platform support and improve metadata handling!
|
|
|
|
### Adding New Services
|
|
|
|
1. Research the service's metadata format
|
|
2. Create a YAML template in `templates/services/`
|
|
3. Update the universal schema if new fields are needed
|
|
4. Test with sample images from the service
|
|
5. Submit a pull request
|
|
|
|
### Template Structure
|
|
|
|
Service templates should include:
|
|
- Field mappings and transformations
|
|
- Output format specifications
|
|
- Validation rules
|
|
- PNG chunk configuration
|
|
- API integration hints (for future automation)
|
|
|
|
## 📊 Compatibility Matrix
|
|
|
|
| Feature | A1111 | ComfyUI | Civitai | Forge | Tensor.AI | Leonardo.AI |
|
|
|---------|-------|---------|---------|--------|-----------|-------------|
|
|
| Basic Parameters | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
| Simplified Workflow* | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
| Model Hashes | ✅ | ✅ | ✅ | ✅ | ⚠️ | ⚠️ |
|
|
| LoRA Support | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
|
|
| Complex Workflow Preservation | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
|
|
| Dependency URLs | ⚠️ | ⚠️ | ✅ | ⚠️ | ✅ | ✅ |
|
|
|
|
✅ Full Support | ⚠️ Partial Support | ❌ Not Supported
|
|
|
|
**Simplified Workflow*: MetaMan can generate a functional workflow from any platform's metadata that will recreate the exact same image. Complex workflows get simplified to basic generation steps, but output quality and reproducibility are maintained.**
|
|
|
|
## 📄 License
|
|
|
|
[Specify your license here]
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
- ComfyUI team for the excellent node-based interface
|
|
- A1111 community for establishing metadata standards
|
|
- Civitai for advancing model sharing and compatibility
|
|
- All AI image generation platforms for pushing the boundaries of creativity
|
|
|
|
---
|
|
|
|
**MetaMan**: Making AI image metadata universal, accessible, and interoperable across all platforms.
|