Add comprehensive README with full feature documentation and usage examples

2025-11-09 11:41:12 +09:00
parent 453d3fe45b
commit d84855a2b7
2 changed files with 474 additions and 118 deletions
@@ -1,149 +1,356 @@
-# TJ_Vector - ComfyUI Custom Node
+# TJ ComfyUI Lineart to Vector

-ラインアート画像から中心線を抽出し、SVGパスとして出力するComfyUIカスタムノード
+ComfyUI custom nodes for line art centerline extraction and SVG manipulation with advanced editing and visualization capabilities.

-## 機能概要
+## Overview

-ラインアート画像 → 線領域検出 → 中心線抽出 → SVGパス出力 → ラスター画像化までの完全なベクトル変換パイプラインを提供します。
+Complete pipeline from line art images to editable SVG vectors: line detection → centerline extraction → SVG generation → style editing → visualization → raster output.

-## ノード一覧
+## Features

-### 1. Line Region Detector
-ラインアート画像から線領域を検出
+### Core Extraction & Conversion

-**入力:**
- `image`: 入力画像
- `background_mode`: 背景検出モード (auto/white/black)
- `line_detection_method`: 線検出方法 (edge/morphology/hybrid)
- その他のパラメータ
+- **Line Region Detector**: Extract centerlines from line art images using skeletonization
+- **Centerline to SVG**: Convert extracted centerlines to clean SVG vector paths with Douglas-Peucker simplification
+- **Mask Cleanup**: Remove noise and small regions from masks
+- **SVG Path Cleanup**: Remove duplicate/overlapping paths based on distance threshold
+- **SVG File Saver**: Save SVG strings to files with customizable paths

-**出力:**
- `line_mask`: 線領域のマスク
- `fill_mask`: 塗り領域のマスク
- `preview_image`: プレビュー画像
- `color_info`: 色情報 (JSON)
+### Visualization & Layout

-### 2. Centerline to SVG
-線マスクから中心線を抽出してSVGパスを生成
+- **SVG Group Layout**: XY plot visualization with automatic tiling
+  - Auto-layout mode: tile all paths/groups in a grid
+  - Manual placement via JSON configuration
+  - Grid lines and labels for easy identification
+  - Background preview showing all paths at low opacity
+  - Global fill/stroke color overrides
+  - Per-tile color/style customization

-**入力:**
- `line_mask`: 線領域のマスク
- `algorithm`: 中心線抽出アルゴリズム (ridge/skeleton/medial_axis)
- `smoothing`: パス平滑化レベル
- その他のパラメータ
+- **SVG To Image**: Render SVG to raster images using Pillow
+  - Custom resolution and scaling
+  - Background color control
+  - Global fill/stroke overrides
+  - Control point visualization

-**出力:**
- `svg_string`: SVG形式の文字列
- `centerline_image`: 中心線プレビュー
- `statistics`: 統計情報 (JSON)
+### Style Editing

-### 3. Mask Line Cleanup
-マスク内の重複線や近接線を除去・統合
+- **SVG Style Editor**: Modify styles using CSS selectors
+  - Supports ID (`#path0`), class (`.hair`), attribute (`[id*=eye]`) selectors
+  - Change stroke, fill, stroke-width, and opacity

-**入力:**
- `mask`: 線マスク
- `mode`: クリーンアップモード (merge_close_lines/remove_duplicates/thin_only/distance_based)
+- **SVG Style Editor (Simple)**: Path index-based style editing
+  - Simple syntax: `0,2-5,10` for path selection
+  - Direct parameter inputs (no JSON required)

-**出力:**
- `cleaned_mask`: クリーンアップ後のマスク
+- **SVG Color Picker**: Generate normalized #RRGGBBAA color strings
+  - Preset colors + custom RGB/Alpha overrides
+  - Outputs consistent hex format for downstream nodes

-### 4. SVG Path Cleanup
-SVGパスの後処理（重複削除・簡略化・近接頂点マージ）
+### Path Management

-**入力:**
- `svg_string`: SVGパス文字列
- `min_path_length`: 最小パス長（これより短いパスを削除）
- `simplify_tolerance`: 簡略化許容誤差
- `near_duplicate_distance`: 近接重複判定距離
+- **SVG Auto Reorder**: Automatic path ordering for optimal rendering
+  - Sort modes: area-based, proximity-based, hybrid (area tiers + proximity)
+  - Reverse option
+  - Optional ID renumbering (`path0`, `path1`, ...)

-**出力:**
- `cleaned_svg`: クリーンアップ後のSVG
- `cleanup_stats`: 削除統計 (JSON)
+- **SVG Reorder**: Manual path ordering via priority rules
+  - Specify exact order with selector-based rules

-### 5. SVG File Saver / SVG Batch Saver
-SVGファイルとメタデータJSONを保存
+- **SVG Visibility**: Show/hide paths by selector
+  - Display control per element
+  - Optional deletion mode

-**入力:**
- `svg_string`: 保存するSVG
- `output_dir`: 出力ディレクトリ
- `filename_prefix`: ファイル名プレフィックス
+## Interactive UI Features

-**出力:**
- `saved_path`: 保存先パス
+**Live Color Picker Widget** (JavaScript extension)
+- Appears automatically on all color fields
+- Color swatch + alpha slider + live preview
+- No node execution needed - updates immediately
+- Transparent background checker pattern

-### 6. SVG To Image
-SVG文字列をラスター画像(PNG)に変換
+Supported nodes:
+- SVG To Image
+- SVG Group Layout
+- SVG Style Editor (Simple)
+- SVG Color Picker

-**入力:**
- `svg_string`: SVG文字列
- `width` / `height`: 出力サイズ (0=自動)
- `scale`: スケール係数
- `background`: 背景色モード (transparent/white/black/custom)
- `dpi`: レンダリングDPI
+## Installation

-**出力:**
- `image`: ラスター画像 (ComfyUI IMAGE tensor)
- `meta`: レンダリング情報 (JSON)
-
-### 7. Python Runtime Info (診断用)
-ComfyUIのPython実行環境とパッケージ情報を出力
-
-**出力:**
- `info`: 環境情報 (JSON形式)
-
-## インストール
-
-### 基本インストール
-1. このフォルダを `ComfyUI/custom_nodes/` にコピー
-2. ComfyUIを再起動（通常は自動的に依存関係がインストールされます）
-
-すべての依存関係は標準的なライブラリのみで、追加セットアップ不要です。
-
-### SVG To Image ノードについて
-
-`SVG To Image` ノードは**基本的なSVGパスレンダリング**を提供します:
- ✅ **追加依存不要**: Pillow単体で動作（既にComfyUIに含まれています）
- ✅ **Windows完全対応**: ネイティブDLL不要
- ⚠️ **制限事項**: 複雑なSVG機能（グラデーション、フィルター、高度なパス）は未サポート
-
-**サポート範囲:**
- 基本パスコマンド（M, L, H, V, C, Z）
- stroke/fill 色指定
- 単純なライン・ポリゴン描画
-
-**高品質レンダリングが必要な場合:**
- `SVG File Saver` で保存後、Inkscape/Illustrator/ブラウザで画像化を推奨
- Linux/macOS環境ではCairoSVGなど高機能レンダラーの利用も検討可
-
-### 手動インストール（自動インストールが動作しない場合）
-
-#### 依存パッケージの手動インストール
-
-自動インストールが動作しない場合、以下を実行:
-
-1. ComfyUI内で `Python Runtime Info` ノードを実行し、`sys_executable` のパスを確認
-2. そのPythonパスを使ってインストール:
-
-```powershell
-# PowerShellの例（パスは環境に合わせて変更）
-& "C:\path\to\ComfyUI\venv\Scripts\python.exe" -m pip install -r requirements.txt
+```bash
+cd ComfyUI/custom_nodes
+git clone https://github.com/TJ16th/TJ_ComfyUI_Lineart2Vector.git
+# Restart ComfyUI
 ```

-**トラブルシュート:**
- `アクセスが拒否されました` エラー → ComfyUIを一時停止してから実行
- 複数Python環境がある場合 → 必ずComfyUIが使用している実行ファイルで `pip install` すること
+### Requirements

-## 使い方
+All dependencies are listed in `requirements.txt`:
+- torch
+- numpy
+- Pillow
+- opencv-python
+- scikit-image
+- scipy

-1. ComfyUIを起動
-2. ノードメニューから `TJ_Vector` カテゴリを選択
-3. `Line Region Detector` ノードで線を検出
-4. `Centerline to SVG` ノードでSVGを生成
+These are typically already installed with ComfyUI. If you encounter issues:

-## ライセンス
+```bash
+pip install -r requirements.txt
+```
+
+### SVG To Image Note
+
+The `SVG To Image` node provides **basic SVG path rendering**:
+- ✅ **No additional dependencies**: Works with Pillow alone (already in ComfyUI)
+- ✅ **Windows compatible**: No native DLLs required
+- ⚠️ **Limitations**: Complex SVG features (gradients, filters, advanced paths) not supported
+
+**Supported:**
+- Basic path commands (M, L, H, V, C, Z)
+- Stroke/fill colors
+- Simple line/polygon drawing
+
+**For high-quality rendering:**
+- Use `SVG File Saver` then render in Inkscape/Illustrator/browser
+- On Linux/macOS, consider CairoSVG for advanced features
+
+## Usage Examples
+
+### Basic Workflow: Line Art → SVG
+
+1. **Line Region Detector**: Input your line art image
+2. **Centerline to SVG**: Convert detected lines to SVG paths
+3. **SVG Path Cleanup**: Remove duplicate paths (optional)
+4. **SVG File Saver**: Save the result
+
+### XY Plot Visualization
+
+1. Extract centerlines and convert to SVG
+2. **SVG Group Layout**:
+   - Set `auto_layout = true`
+   - Adjust `tile_cols` and `tile_spacing`
+   - Use `override_fill_color` for consistent coloring
+   - Enable `show_all_background` to see context
+
+### Style Customization
+
+**Method 1: Global Override**
+```
+SVG Group Layout:
+├─ override_fill_color: "#FF0000FF"  (all paths red)
+└─ override_stroke_color: "#000000FF" (all strokes black)
+```
+
+**Method 2: Per-Path Control**
+```
+SVG Style Editor (Simple):
+├─ path_indices: "0,2-5,10"
+├─ stroke_color: "#FF0000"
+└─ stroke_width: 3.0
+```
+
+**Method 3: Selector-Based**
+```json
+SVG Style Editor:
+[
+  {"selector": "#hair", "stroke": "#000000", "fill": "#FFFF00"},
+  {"selector": ".shadow", "opacity": 0.5}
+]
+```
+
+### Automatic Path Ordering
+
+```
+SVG Auto Reorder:
+├─ sort_mode: "area_then_proximity"
+├─ area_tiers: 3  (group by size, then sort by proximity)
+├─ renumber_ids: true  (rename as path0, path1, ...)
+└─ reverse: false
+```
+
+## JSON Configuration Examples
+
+### SVG Group Layout: Manual Placement
+
+```json
+[
+  {
+    "selector": "#path0",
+    "x": 100,
+    "y": 100,
+    "scale": 1.5,
+    "stroke": "#FF0000FF",
+    "fill": "none",
+    "stroke_width": 2.0
+  },
+  {
+    "selector": "#path1",
+    "x": 400,
+    "y": 100,
+    "fill": "#00FF00FF",
+    "opacity": 0.8
+  }
+]
+```
+
+### SVG Reorder: Priority Rules
+
+```json
+[
+  {"selector": "#background", "priority": 0},
+  {"selector": ".shadow", "priority": 1},
+  {"selector": ".main", "priority": 2},
+  {"selector": "#highlights", "priority": 3}
+]
+```
+
+## Node Reference
+
+### Line Region Detector
+Extract line regions from line art images.
+
+**Inputs:**
+- `image`: Input image
+- `background_mode`: Background detection (auto/white/black)
+- `line_detection_method`: Detection method (edge/morphology/hybrid)
+- Additional threshold parameters
+
+**Outputs:**
+- `line_mask`: Line region mask
+- `fill_mask`: Fill region mask
+- `preview_image`: Preview with overlays
+- `color_info`: Detected colors (JSON)
+
+### Centerline to SVG
+Convert line masks to SVG paths via centerline extraction.
+
+**Inputs:**
+- `line_mask`: Line region mask
+- `algorithm`: Extraction algorithm (ridge/skeleton/medial_axis)
+- `smoothing`: Path smoothing level
+- `simplification`: Douglas-Peucker tolerance
+
+**Outputs:**
+- `svg_string`: SVG path string
+- `centerline_image`: Centerline preview
+- `statistics`: Path statistics (JSON)
+
+### SVG Group Layout
+Visualize SVG paths in a tiled layout with styling options.
+
+**Inputs:**
+- `svg_string`: Input SVG
+- `canvas_width`/`canvas_height`: Output dimensions
+- `auto_layout`: Enable automatic tiling
+- `tile_cols`/`tile_spacing`: Grid layout parameters
+- `override_fill_color`/`override_stroke_color`: Global color overrides
+- `show_all_background`: Show all paths at low opacity
+- `show_grid_lines`/`show_labels`: Visual aids
+- `group_positions_json`: Manual placement rules (JSON)
+
+**Outputs:**
+- `image`: Rendered composite
+- `meta`: Layout statistics (JSON)
+
+### SVG Style Editor
+Apply style changes using CSS selectors.
+
+**Inputs:**
+- `svg_string`: Input SVG
+- `style_rules_json`: Style rules (JSON array)
+
+**Outputs:**
+- `svg`: Modified SVG
+- `meta`: Applied changes (JSON)
+
+### SVG Style Editor (Simple)
+Apply styles using path index ranges.
+
+**Inputs:**
+- `svg_string`: Input SVG
+- `path_indices`: Path selection (e.g., "0,2-5,10")
+- `stroke_color`/`fill_color`: Color overrides
+- `stroke_width`/`opacity`: Style parameters
+
+**Outputs:**
+- `svg`: Modified SVG
+- `meta`: Modification stats (JSON)
+
+### SVG Auto Reorder
+Automatically reorder paths for optimal rendering.
+
+**Inputs:**
+- `svg_string`: Input SVG
+- `sort_mode`: Sorting algorithm (area/proximity/area_then_proximity)
+- `reverse`: Reverse final order
+- `area_tiers`: Number of size tiers (for hybrid mode)
+- `renumber_ids`: Renumber paths as path0, path1, ...
+
+**Outputs:**
+- `svg`: Reordered SVG
+- `meta`: Sorting statistics (JSON)
+
+### SVG Color Picker
+Generate normalized color strings.
+
+**Inputs:**
+- `base_color`: Input color (any format)
+- `preset`: Color preset
+- `r_override`/`g_override`/`b_override`/`a_override`: Component overrides
+
+**Outputs:**
+- `color_hex`: Normalized #RRGGBBAA string
+- `meta`: Parsed components (JSON)
+
+## Tips
+
+- **Performance**: For large SVGs, use `SVG Path Cleanup` to reduce path count
+- **Color Workflow**: Use `SVG Color Picker` to generate consistent color strings
+- **Debugging**: Enable `show_labels` in SVG Group Layout to see path IDs
+- **Path Order**: Use `SVG Auto Reorder` with `renumber_ids=true` before using index-based editing
+
+## Development
+
+### Structure
+- **Python nodes**: `*.py` files for backend processing
+- **JavaScript extension**: `web/tj_color_picker.js` for UI enhancements
+- **WEB_DIRECTORY export**: Enables custom UI widgets
+
+### Adding Color Fields
+Edit `web/tj_color_picker.js`:
+```javascript
+const colorFields = new Set([
+  "your_field_name",  // Add here
+  // ...existing fields
+]);
+```
+
+## License

 MIT License

-## バージョン
+## Links

-v1.0 - 初期リリース
+- GitHub: https://github.com/TJ16th/TJ_ComfyUI_Lineart2Vector
+- Issues: https://github.com/TJ16th/TJ_ComfyUI_Lineart2Vector/issues
+
+## Changelog
+
+### Latest (2025-11-09)
+- Added fill/stroke color override to SVG Group Layout (global + per-placement)
+- Added `renumber_ids` option to SVG Auto Reorder
+- Fixed JavaScript extension loading (WEB_DIRECTORY export + correct directory structure)
+- Added live color picker UI widget with alpha control
+- Added SVG Color Picker node for consistent #RRGGBBAA output
+
+### Initial Release
+- Line art centerline extraction
+- SVG conversion and path simplification
+- Multi-mode auto reorder (area/proximity/hybrid)
+- CSS selector-based and index-based style editing
+- XY plot layout with auto-tiling
+- SVG visibility control
+
+---
+
+[日本語版 README](README_ja.md)
@@ -0,0 +1,149 @@
+# TJ_Vector - ComfyUI Custom Node
+
+ラインアート画像から中心線を抽出し、SVGパスとして出力するComfyUIカスタムノード
+
+## 機能概要
+
+ラインアート画像 → 線領域検出 → 中心線抽出 → SVGパス出力 → ラスター画像化までの完全なベクトル変換パイプラインを提供します。
+
+## ノード一覧
+
+### 1. Line Region Detector
+ラインアート画像から線領域を検出
+
+**入力:**
+- `image`: 入力画像
+- `background_mode`: 背景検出モード (auto/white/black)
+- `line_detection_method`: 線検出方法 (edge/morphology/hybrid)
+- その他のパラメータ
+
+**出力:**
+- `line_mask`: 線領域のマスク
+- `fill_mask`: 塗り領域のマスク
+- `preview_image`: プレビュー画像
+- `color_info`: 色情報 (JSON)
+
+### 2. Centerline to SVG
+線マスクから中心線を抽出してSVGパスを生成
+
+**入力:**
+- `line_mask`: 線領域のマスク
+- `algorithm`: 中心線抽出アルゴリズム (ridge/skeleton/medial_axis)
+- `smoothing`: パス平滑化レベル
+- その他のパラメータ
+
+**出力:**
+- `svg_string`: SVG形式の文字列
+- `centerline_image`: 中心線プレビュー
+- `statistics`: 統計情報 (JSON)
+
+### 3. Mask Line Cleanup
+マスク内の重複線や近接線を除去・統合
+
+**入力:**
+- `mask`: 線マスク
+- `mode`: クリーンアップモード (merge_close_lines/remove_duplicates/thin_only/distance_based)
+
+**出力:**
+- `cleaned_mask`: クリーンアップ後のマスク
+
+### 4. SVG Path Cleanup
+SVGパスの後処理（重複削除・簡略化・近接頂点マージ）
+
+**入力:**
+- `svg_string`: SVGパス文字列
+- `min_path_length`: 最小パス長（これより短いパスを削除）
+- `simplify_tolerance`: 簡略化許容誤差
+- `near_duplicate_distance`: 近接重複判定距離
+
+**出力:**
+- `cleaned_svg`: クリーンアップ後のSVG
+- `cleanup_stats`: 削除統計 (JSON)
+
+### 5. SVG File Saver / SVG Batch Saver
+SVGファイルとメタデータJSONを保存
+
+**入力:**
+- `svg_string`: 保存するSVG
+- `output_dir`: 出力ディレクトリ
+- `filename_prefix`: ファイル名プレフィックス
+
+**出力:**
+- `saved_path`: 保存先パス
+
+### 6. SVG To Image
+SVG文字列をラスター画像(PNG)に変換
+
+**入力:**
+- `svg_string`: SVG文字列
+- `width` / `height`: 出力サイズ (0=自動)
+- `scale`: スケール係数
+- `background`: 背景色モード (transparent/white/black/custom)
+- `dpi`: レンダリングDPI
+
+**出力:**
+- `image`: ラスター画像 (ComfyUI IMAGE tensor)
+- `meta`: レンダリング情報 (JSON)
+
+### 7. Python Runtime Info (診断用)
+ComfyUIのPython実行環境とパッケージ情報を出力
+
+**出力:**
+- `info`: 環境情報 (JSON形式)
+
+## インストール
+
+### 基本インストール
+1. このフォルダを `ComfyUI/custom_nodes/` にコピー
+2. ComfyUIを再起動（通常は自動的に依存関係がインストールされます）
+
+すべての依存関係は標準的なライブラリのみで、追加セットアップ不要です。
+
+### SVG To Image ノードについて
+
+`SVG To Image` ノードは**基本的なSVGパスレンダリング**を提供します:
+- ✅ **追加依存不要**: Pillow単体で動作（既にComfyUIに含まれています）
+- ✅ **Windows完全対応**: ネイティブDLL不要
+- ⚠️ **制限事項**: 複雑なSVG機能（グラデーション、フィルター、高度なパス）は未サポート
+
+**サポート範囲:**
+- 基本パスコマンド（M, L, H, V, C, Z）
+- stroke/fill 色指定
+- 単純なライン・ポリゴン描画
+
+**高品質レンダリングが必要な場合:**
+- `SVG File Saver` で保存後、Inkscape/Illustrator/ブラウザで画像化を推奨
+- Linux/macOS環境ではCairoSVGなど高機能レンダラーの利用も検討可
+
+### 手動インストール（自動インストールが動作しない場合）
+
+#### 依存パッケージの手動インストール
+
+自動インストールが動作しない場合、以下を実行:
+
+1. ComfyUI内で `Python Runtime Info` ノードを実行し、`sys_executable` のパスを確認
+2. そのPythonパスを使ってインストール:
+
+```powershell
+# PowerShellの例（パスは環境に合わせて変更）
+& "C:\path\to\ComfyUI\venv\Scripts\python.exe" -m pip install -r requirements.txt
+```
+
+**トラブルシュート:**
+- `アクセスが拒否されました` エラー → ComfyUIを一時停止してから実行
+- 複数Python環境がある場合 → 必ずComfyUIが使用している実行ファイルで `pip install` すること
+
+## 使い方
+
+1. ComfyUIを起動
+2. ノードメニューから `TJ_Vector` カテゴリを選択
+3. `Line Region Detector` ノードで線を検出
+4. `Centerline to SVG` ノードでSVGを生成
+
+## ライセンス
+
+MIT License
+
+## バージョン
+
+v1.0 - 初期リリース