diff --git a/README.md b/README.md index bb7d793..448d744 100644 --- a/README.md +++ b/README.md @@ -1,280 +1,94 @@ # ComfyUI Annotations -A pure annotation/markup overlay system for ComfyUI's node editor. Draw freehand annotations directly on the canvas without modifying workflow data. +A lightweight annotation overlay for ComfyUI. Draw freehand notes directly on your workflow canvas. ![Version](https://img.shields.io/badge/version-1.0.0-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![ComfyUI](https://img.shields.io/badge/ComfyUI-compatible-orange) +![image](comfy-annotations.jpeg) + ## Features -- **Freehand Drawing** - Draw directly on the canvas with smooth strokes -- **World-Space Annotations** - Strokes follow zoom/pan, staying anchored to nodes +- **Freehand Drawing** - Smooth pen strokes with adjustable color, size, and opacity +- **World-Space Annotations** - Strokes stay anchored to nodes during zoom/pan - **Eraser Tool** - Remove strokes with visual cursor feedback -- **Undo/Redo** - Full history support with configurable depth -- **Persistence** - Annotations save/load with your workflow -- **Performance Optimized** - Handles thousands of points smoothly -- **Non-Destructive** - Doesn't modify workflow data or break ComfyUI +- **Undo/Redo** - Full history support (Ctrl+Z / Ctrl+Shift+Z) +- **Auto-Save** - Annotations persist with your workflow file +- **Performance Optimized** - Handles thousands of strokes smoothly +- **Non-Destructive** - No workflow data modification ## Installation -### Method 1: ComfyUI Manager (Recommended) +### ComfyUI Manager (Recommended) 1. Open ComfyUI Manager 2. Search for "Annotations" 3. Click Install 4. Restart ComfyUI -### Method 2: Git Clone +### Git Clone ```bash cd ComfyUI/custom_nodes git clone https://github.com/0dot77/comfyui-annotations.git ``` -Then restart ComfyUI. +### Manual -### Method 3: Manual Download - -1. Download the latest release from GitHub +1. Download the [latest release](https://github.com/0dot77/comfyui-annotations/releases) 2. Extract to `ComfyUI/custom_nodes/comfyui-annotations/` 3. Restart ComfyUI -## Uninstallation +## Quick Start -### Via ComfyUI Manager +1. Press **`A`** to toggle annotation mode +2. Draw with your mouse, trackpad, or pen tablet +3. Press **`A`** again to exit and resume normal editing +4. Save your workflow - annotations are included automatically -1. Open ComfyUI Manager -2. Find "ComfyUI Annotations" in installed extensions -3. Click Uninstall -4. Restart ComfyUI - -### Manual Uninstallation - -```bash -cd ComfyUI/custom_nodes -rm -rf comfyui-annotations -``` - -Then restart ComfyUI. - -**Note:** Uninstalling this extension will not affect your workflows. Annotations are stored in the workflow's `extra` field and will simply be ignored if the extension is not installed. - -## Usage - -### Quick Start - -1. Press **`A`** to toggle annotation mode ON/OFF -2. Draw with your mouse or pen -3. Press **`A`** again to exit and return to normal node editing -4. Save your workflow - annotations are included automatically! - -### Keyboard Shortcuts +## Keyboard Shortcuts | Key | Action | |-----|--------| -| `A` | Toggle annotation mode ON/OFF | +| `A` | Toggle annotation mode | +| `P` | Pen tool | +| `E` | Eraser tool | | `T` | Collapse/expand toolbar | -| `P` | Switch to Pen tool | -| `E` | Switch to Eraser tool | -| `Ctrl+Z` / `Cmd+Z` | Undo | -| `Ctrl+Shift+Z` / `Cmd+Shift+Z` | Redo | -| `Ctrl+Y` / `Cmd+Y` | Redo (alternative) | +| `Ctrl+Z` | Undo | +| `Ctrl+Shift+Z` | Redo | | `Escape` | Exit annotation mode | -### Toolbar +## Toolbar -The toolbar appears in the top-right corner (below ComfyUI Manager) and provides: +Located in the top-right corner: -- **Mode Toggle** - ON/OFF button for annotation mode -- **Tool Selector** - Pen and Eraser buttons -- **Pen Settings** - Size slider, opacity slider, color picker with presets -- **Eraser Settings** - Size slider -- **Action Buttons** - Undo, Redo, Clear (with disabled states) +- **Mode Toggle** - ON/OFF button +- **Tools** - Pen and Eraser +- **Pen Settings** - Size, opacity, color presets +- **Actions** - Undo, Redo, Clear All -### Tips +## Browser Support -- Annotations follow zoom/pan - they stay anchored to their position in the node graph -- Draw near nodes to annotate specific parts of your workflow -- Use different colors to categorize annotations -- Eraser removes entire strokes on contact (not partial erasure) +| Browser | Status | +|---------|--------| +| Chrome 90+ | ✅ Full support | +| Edge 90+ | ✅ Full support | +| Firefox 88+ | ✅ Full support | +| Safari 14+ | ✅ Full support | -## Compatibility +## Uninstall -### Browser Support +Remove the `comfyui-annotations` folder from `custom_nodes/` and restart ComfyUI. -| Browser | Version | Status | Notes | -|---------|---------|--------|-------| -| Chrome | 90+ | ✅ Full | Primary development target | -| Edge | 90+ | ✅ Full | Chromium-based | -| Firefox | 88+ | ✅ Full | All features work | -| Safari | 14+ | ✅ Full | Uses fallbacks for some features | -| Opera | 76+ | ✅ Full | Chromium-based | - -### Feature Support - -The extension automatically detects browser capabilities and uses fallbacks: - -- **OffscreenCanvas** - Used for stroke caching (fallback: regular canvas) -- **getCoalescedEvents** - Smoother fast strokes on Chromium (graceful degradation on others) -- **Desynchronized Canvas** - Lower latency on Chromium (ignored by others) - -Check browser compatibility in the console: -```javascript -comfyAnnotations.browser.printReport() -``` - -### Tested With - -- ComfyUI (latest) -- Python 3.10+ -- Modern browsers (Chrome, Firefox, Safari, Edge) - -### Requirements - -- ComfyUI with LiteGraph canvas -- No Python dependencies (frontend-only extension) - -### Known Issues - -- None currently - -## File Structure - -``` -comfyui-annotations/ -├── __init__.py # Extension registration -├── LICENSE # MIT License -├── README.md # This file -└── web/ - ├── main.js # Entry point & extension setup - ├── style.css # Overlay styles - └── modules/ - ├── annotationOverlay.js # DOM & canvas management - ├── browserCompat.js # Browser feature detection & fallbacks - ├── coordinateUtils.js # Coordinate transforms - ├── hitTesting.js # Stroke hit-testing for eraser - ├── historyManager.js # Undo/redo history stack - ├── toolbarUI.js # Collapsible toolbar UI - ├── persistence.js # Save/load with workflow - └── renderOptimizer.js # RAF batching, stroke caching -``` - -## Debug API - -For developers and troubleshooting, open the browser console: - -```javascript -// Mode & rendering -window.comfyAnnotations.toggle() // Toggle annotation mode -window.comfyAnnotations.isActive() // Check if mode is active -window.comfyAnnotations.render() // Force re-render - -// Stroke management -window.comfyAnnotations.getStrokes() // Get all strokes array -window.comfyAnnotations.clearStrokes() // Clear all strokes (with undo) - -// Tool management -window.comfyAnnotations.getTool() // Get current tool -window.comfyAnnotations.setTool('pen') // Switch tool - -// Pen settings -window.comfyAnnotations.setColor('#00FF00')// Set pen color -window.comfyAnnotations.setSize(8) // Set pen size (1-50) -window.comfyAnnotations.setOpacity(0.5) // Set pen opacity (0.1-1.0) - -// Eraser settings -window.comfyAnnotations.setEraserSize(30) // Set eraser radius (5-100) - -// History -window.comfyAnnotations.undo() // Undo last action -window.comfyAnnotations.redo() // Redo last undone action -window.comfyAnnotations.canUndo() // Check if undo available -window.comfyAnnotations.canRedo() // Check if redo available - -// Toolbar -window.comfyAnnotations.toolbar.toggle() // Toggle toolbar collapse -window.comfyAnnotations.toolbar.show() // Show toolbar -window.comfyAnnotations.toolbar.hide() // Hide toolbar - -// Performance -window.comfyAnnotations.performance.getMetrics() // Get FPS, render times -window.comfyAnnotations.performance.runBenchmark() // Run benchmark -window.comfyAnnotations.performance.setUseCache(true) // Enable/disable caching - -// Debug -window.comfyAnnotations.debug.enable() // Enable debug visualizer -window.comfyAnnotations.debug.runTests() // Run coordinate tests - -// Browser compatibility -window.comfyAnnotations.browser.printReport() // Print compatibility report -window.comfyAnnotations.browser.getFeatures() // Get all detected features -window.comfyAnnotations.browser.hasFeature('offscreenCanvas') // Check specific feature -``` - -## Performance - -Optimized for large drawings with thousands of points: - -- **RAF Batching** - Multiple pointer events coalesced into single render -- **Stroke Cache** - Completed strokes rendered to offscreen canvas -- **Path2D Caching** - Stroke paths cached for reuse - -Run `window.comfyAnnotations.performance.runBenchmark()` to test performance. - -## Data Format - -Annotations are stored in workflow JSON under `extra.annotations`: - -```json -{ - "extra": { - "annotations": { - "version": 1, - "strokes": [ - { - "id": "stroke_1234567890_abc123", - "points": [{"x": 100, "y": 200}, ...], - "color": "#FF5555", - "size": 4, - "opacity": 1.0 - } - ] - } - } -} -``` - -The versioned format ensures forward compatibility for future updates. +Your workflows remain intact - annotations are simply ignored when the extension isn't installed. ## Contributing -Contributions are welcome! Please: - 1. Fork the repository 2. Create a feature branch -3. Make your changes -4. Submit a pull request - -## Changelog - -### v1.0.0 (Initial Release) - -- Freehand drawing with smooth strokes -- Pen tool with color, size, opacity settings -- Eraser tool with hit-testing -- Undo/redo with configurable history -- Clear all with undo support -- Collapsible toolbar UI -- Persistence (save/load with workflow) -- Performance optimizations (RAF batching, stroke caching) -- Keyboard shortcuts -- Debug API +3. Submit a pull request ## License -MIT License - see [LICENSE](LICENSE) file for details. - -## Credits - -Built for the ComfyUI community. +[MIT License](LICENSE) diff --git a/comfy-annotations.jpeg b/comfy-annotations.jpeg new file mode 100644 index 0000000..af9f94a Binary files /dev/null and b/comfy-annotations.jpeg differ