ai-game-2/tools/ora_editor/README.md

ORA Editor - Browser-based OpenRaster Editor

A web-based tool for editing ORA (OpenRaster) files with layer management, polygon drawing, and AI-powered mask extraction.

Quick Start

cd tools/ora_editor

# Activate venv and install dependencies
source ../venv/bin/activate  # or your Python environment
pip install -r requirements.txt

# Run the Flask server
python app.py

The editor will be available at: http://localhost:5000

Features

• Open PNG/ORA files: Enter file path relative to project root
• Layer management: Toggle visibility, rename, delete, reorder layers
• Polygon drawing: Draw polygons to guide mask extraction
• Mask extraction: Use ComfyUI to extract masks from images with optional polygon overlay
• Krita integration: Open layers in Krita for manual editing
• Settings: Configure ComfyUI server URL
• Client-side logging: Console logs for debugging UI interactions

Usage Workflow

1. Open a file: Enter path to PNG or ORA file (relative to /home/noti/dev/ai-game-2)
   • Click "Open" button
   • File auto-converts to ORA if PNG
2. View layers: See all layers with visibility checkboxes in sidebar
3. Draw polygon (optional for mask extraction):
   • Click "Start Drawing" button
   • Click on image to add points
   • Double-click or Enter/Escape when done
   • Points shown with colored markers
4. Extract mask:
   • Enter subject description (e.g., "the door")
   • Optionally check "Use polygon hint" if you've drawn a polygon
   • Click "Extract Mask"
   • Status shown while polling ComfyUI
5. Review results: See preview modal with extracted mask
6. Add to ORA: Click "Use This Mask" to add as new layer
7. Edit in Krita (optional): Select layer, open in Krita for manual work
8. Save: Persist all changes

Debugging

Client-side Logging

Open browser console (F12) to see detailed logs:

• [ORA EDITOR] Opening file: - File open events
• [ORA EDITOR] Extracting mask: - Mask extraction flow
• [ORA EDITOR] Polygon drawing - Canvas interactions
• [ORA EDITOR] Canvas setup - Canvas initialization

Backend Logging

Check Flask server logs for:

• [MASK EXTRACT] - Mask extraction process
• [POLYGON] - Polygon storage and operations
• [API] - API request/response handling

ComfyUI Setup

• Default URL: 127.0.0.1:8188
• Polygon support: When "Use polygon hint" is checked, the polygon overlay is drawn on the base image before sending to ComfyUI
• Status polling: App polls ComfyUI for mask completion, downloads result automatically

API Endpoints

Endpoint	Method	Purpose
/api/open	POST	Open PNG/ORA file
/api/save	POST	Save current state
/api/layers	GET	Get layer list
/api/layer/*	POST	Layer operations (add, rename, delete, reorder, visibility)
/api/polygon	POST	Draw polygon overlay
/api/mask/extract	POST	Extract mask via ComfyUI
/api/krita/open	POST	Open layer in Krita
/api/krita/status/<layer_name>	GET	Check Krita temp file status
/api/file/mask	GET	Serve mask file from temp

Testing

# Test ORA operations
python test_ora_ops.py

# Test Flask API
python test_app.py

The editor will be available at: http://localhost:5000

Features

• Open PNG/ORA files: Enter file path relative to project root
• Layer management: Toggle visibility, rename, delete, reorder layers
• Polygon drawing: Draw polygons to guide mask extraction
• Mask extraction: Use ComfyUI to extract masks from images
• Krita integration: Open layers in Krita for manual editing
• Settings: Configure ComfyUI server URL

Usage Workflow

1. Open a file: Enter path to PNG or ORA file (relative to /home/noti/dev/ai-game-2)
2. View layers: See all layers with visibility checkboxes
3. Draw polygon (optional): Describe the area you want separated
4. Extract mask: Enter subject description and click "Extract Mask"
5. Review results: See preview modal with extracted mask
6. Add to ORA: Click "Use This Mask" to add as new layer
7. Edit in Krita (optional): Select layer, open in Krita for manual work
8. Save: Persist all changes

ComfyUI Setup

• Default URL: 127.0.0.1:8188
• Configure via Settings gear icon
• Workflow file must exist at tools/image_mask_extraction.json

API Endpoints

Endpoint	Method	Purpose
/api/open	POST	Open PNG/ORA file
/api/save	POST	Save current state
/api/layers	GET	Get layer list
/api/layer/*	POST	Layer operations (add, rename, delete, reorder)
/api/polygon	POST	Draw polygon overlay
/api/mask/extract	POST	Extract mask via ComfyUI
/api/krita/open	POST	Open layer in Krita

Testing

# Test ORA operations
python test_ora_ops.py

# Test Flask API
python test_app.py