Implement v0.8 quality improvements - Phase 1 & 2 complete

README.md

@@ -2,6 +2,66 @@
 
 Transfer motion from low-resolution AI-generated videos to ultra-high-resolution still images (up to 16K+).
 
+## What's New in v0.8 - Quality Improvements 🎉
+
+**Major quality enhancements for professional-grade output:**
+
+### Phase 1 & 2 Improvements (Implemented)
+
+**1. Raised Cosine Tile Blending**
+- Replaces linear blending with Hann window (raised cosine) for smoother tile transitions
+- Eliminates visible seams at tile boundaries on uniform surfaces
+- Reduces banding artifacts in gradient regions
+
+**2. Color Matching in Tile Overlaps**
+- Automatically matches color statistics between adjacent tiles
+- Eliminates exposure discontinuities at tile boundaries
+- Adaptive histogram matching for seamless stitching
+
+**3. Adaptive Temporal Blending**
+- Confidence-weighted blending reduces flicker without ghosting
+- Motion-magnitude modulation prevents ghosting in fast-motion areas
+- Scene cut detection prevents blending across shot changes
+- Per-pixel adaptive blend strength for optimal quality
+
+**4. Bidirectional Flow with Occlusion Detection (New Node!)**
+- `BidirectionalFlowExtractor` - computes forward and backward flow
+- Consistency-based occlusion detection identifies unreliable regions
+- Significantly more accurate confidence maps than single-direction flow
+- Adaptive threshold based on flow magnitude
+
+**5. Joint Bilateral Flow Upsampling**
+- Better edge preservation than guided filtering
+- Prevents flow bleeding across sharp boundaries
+- Reduces halo artifacts around high-contrast edges
+- Canny/Sobel edge detection for explicit edge constraints
+
+**6. Edge-Aware Flow Refinement**
+- Edge mask generation preserves flow discontinuities
+- Prevents background motion leaking into foreground objects
+- Multi-scale edge detection for robust boundary handling
+
+### Phase 3 Improvements (Latest)
+
+**7. Multi-Frame Flow Accumulation for Large Motion (RAFTFlowExtractor)**
+- Automatically detects when flow magnitude exceeds threshold
+- Subdivides frame pairs with linear interpolation
+- Computes flow between intermediate frames
+- Accumulates flows with proper composition
+- New parameters:
+  - `handle_large_motion` = False (default, enable for fast motion)
+  - `max_displacement` = 128 (threshold for subdivision)
+- Best for: Fast camera pans, quick hand movements, low frame rate sources
+- Processing time: 2-4x slower when subdivision occurs (only on affected frames)
+
+### Backward Compatibility
+
+All new features are **fully backward compatible**:
+- Existing workflows continue to work unchanged
+- New parameters have sensible defaults that match legacy behavior
+- Set `blend_mode="linear"` and `upscale_method="guided_filter"` for v0.7 behavior
+- Phase 3 features are opt-in (disabled by default)
+
 ## Features
 
 This node pack provides three complementary pipelines for motion transfer:

examples/README.md

@@ -4,6 +4,80 @@ This folder contains example workflow JSON files for all three motion transfer p
 
 ---
 
+## 🎉 NEW in v0.8 - Quality Improvement Workflows
+
+**Recommended:** Start with these to get the best quality output!
+
+### 📁 `workflow_pipeline_a_quality_v08.json` ⭐ **HIGHLY RECOMMENDED**
+
+**Pipeline A with v0.8 Quality Improvements**
+
+**What's new:**
+- ✨ **Raised cosine tile blending** - Eliminates visible seams completely
+- ✨ **Color matching in tile overlaps** - Fixes exposure discontinuities
+- ✨ **Joint bilateral flow upsampling** - Prevents edge bleeding, preserves sharp boundaries
+- ✨ **Canny edge detection** - Explicit edge constraints for flow
+- ✨ **Adaptive temporal blending** - Motion-aware, confidence-weighted stabilization
+- ✨ **Scene cut detection** - Prevents blending across shot changes
+
+**Quality improvements you'll notice:**
+- No more visible seams at tile boundaries
+- Sharper edges around objects (no halos)
+- Smoother motion without ghosting
+- Better handling of fast motion
+- Cleaner transitions across scene cuts
+
+**Use this for:** Production work, best quality output
+
+---
+
+### 📁 `workflow_bidirectional_flow.json`
+
+**Advanced: Bidirectional Flow with Occlusion Detection**
+
+**What it does:**
+- Uses new `BidirectionalFlowExtractor` node (v0.8)
+- Computes forward AND backward flow
+- Checks forward-backward consistency
+- Detects occluded regions explicitly
+- Produces physics-based confidence maps (much better than heuristic)
+
+**Best for:**
+- Scenes with faces (eyes, mouth occlusions)
+- Hand motion (finger occlusions)
+- Overlapping objects
+- Complex organic motion
+- Any scene where standard confidence is unreliable
+
+**Processing time:** ~2x single-direction flow (runs flow twice)
+**Quality gain:** Significantly better confidence → less flicker in uncertain regions
+
+---
+
+### 📁 `workflow_quality_comparison.json`
+
+**Side-by-Side: v0.7 Legacy vs v0.8 Quality**
+
+**What it does:**
+- Processes same input with BOTH settings
+- Creates two output sequences for A/B testing
+- Legacy branch uses v0.7 settings (linear blending, guided filter, fixed temporal)
+- Quality branch uses v0.8 settings (all improvements enabled)
+
+**Use this to:**
+- See exactly what each improvement does
+- Convince yourself the quality gains are worth it
+- Understand the difference between modes
+- Inspect tile seams, edge halos, temporal artifacts side-by-side
+
+**Expected differences:**
+- **Tile seams:** Legacy shows gradients on uniform surfaces, v0.8 seamless
+- **Edge halos:** Legacy shows bleeding around objects, v0.8 clean
+- **Temporal flicker:** Legacy flickers on slow motion, v0.8 smooth
+- **Ghosting:** Legacy shows double images in fast motion, v0.8 clean
+
+---
+
 ## Quick Start
 
 1. **Open ComfyUI**

examples/workflow_bidirectional_flow.json

@@ -0,0 +1,188 @@
+{
+  "workflow_name": "Bidirectional Flow with Occlusion Detection (v0.8)",
+  "description": "Advanced workflow using BidirectionalFlowExtractor for superior confidence maps and occlusion detection. Best for scenes with complex occlusions (faces, hands, overlapping objects).",
+  "version": "0.8.0",
+  "nodes": [
+    {
+      "id": 1,
+      "type": "LoadVideo",
+      "title": "Load Low-Res Video",
+      "params": {
+        "video_path": "input/ai_video_1080p.mp4"
+      },
+      "outputs": {
+        "images": "video_frames"
+      }
+    },
+    {
+      "id": 2,
+      "type": "BidirectionalFlowExtractor",
+      "title": "Extract Bidirectional Flow (v0.8 NEW!)",
+      "params": {
+        "model_name": "sea-raft-medium",
+        "raft_iters": 8,
+        "consistency_threshold": 1.0,
+        "adaptive_threshold": true
+      },
+      "inputs": {
+        "images": "video_frames"
+      },
+      "outputs": {
+        "flow_forward": "flow_fwd",
+        "flow_backward": "flow_bwd",
+        "confidence": "flow_confidence_bidirectional",
+        "occlusion_mask": "occlusion_mask",
+        "consistency_error": "consistency_error_vis"
+      },
+      "tooltip": "NEW v0.8: Computes forward AND backward flow, checks consistency to detect occlusions. Much more accurate confidence than single-direction flow. ~2x processing time but worth it for quality."
+    },
+    {
+      "id": 3,
+      "type": "LoadImage",
+      "title": "Load High-Res Still",
+      "params": {
+        "image_path": "input/still_16k.png"
+      },
+      "outputs": {
+        "image": "still_hires"
+      }
+    },
+    {
+      "id": 4,
+      "type": "FlowSRRefine",
+      "title": "Upscale Flow with Edge Detection",
+      "params": {
+        "target_width": 15360,
+        "target_height": 8640,
+        "upscale_method": "joint_bilateral",
+        "edge_detection": "canny",
+        "edge_threshold": 0.5,
+        "guided_filter_radius": 8,
+        "guided_filter_eps": 0.001
+      },
+      "inputs": {
+        "flow": "flow_fwd",
+        "guide_image": "still_hires"
+      },
+      "outputs": {
+        "flow_upscaled": "flow_hires"
+      }
+    },
+    {
+      "id": 5,
+      "type": "FlowToSTMap",
+      "title": "Convert to STMap",
+      "params": {},
+      "inputs": {
+        "flow": "flow_hires"
+      },
+      "outputs": {
+        "stmap": "stmap_sequence"
+      }
+    },
+    {
+      "id": 6,
+      "type": "TileWarp16K",
+      "title": "Warp with Quality Improvements",
+      "params": {
+        "tile_size": 2048,
+        "overlap": 128,
+        "interpolation": "cubic",
+        "blend_mode": "raised_cosine",
+        "color_match": true
+      },
+      "inputs": {
+        "still_image": "still_hires",
+        "stmap": "stmap_sequence"
+      },
+      "outputs": {
+        "warped_sequence": "warped_frames"
+      }
+    },
+    {
+      "id": 7,
+      "type": "TemporalConsistency",
+      "title": "Adaptive Temporal with Bidirectional Confidence",
+      "params": {
+        "blend_strength": 0.3,
+        "blend_mode": "adaptive",
+        "scene_cut_detection": true,
+        "scene_cut_threshold": 0.3,
+        "motion_threshold": 20.0
+      },
+      "inputs": {
+        "frames": "warped_frames",
+        "flow": "flow_hires",
+        "confidence": "flow_confidence_bidirectional"
+      },
+      "outputs": {
+        "stabilized": "final_sequence"
+      },
+      "tooltip": "Using bidirectional confidence (from node 2) gives much better adaptive blending. Regions with occlusions get more temporal averaging, confident regions stay sharp."
+    },
+    {
+      "id": 8,
+      "type": "HiResWriter",
+      "title": "Export Final Sequence",
+      "params": {
+        "output_path": "output/bidirectional_v08/frame",
+        "format": "png",
+        "start_frame": 0
+      },
+      "inputs": {
+        "images": "final_sequence"
+      }
+    },
+    {
+      "id": 9,
+      "type": "HiResWriter",
+      "title": "Export Occlusion Mask (Optional Debug)",
+      "params": {
+        "output_path": "output/bidirectional_v08/occlusion",
+        "format": "png",
+        "start_frame": 0
+      },
+      "inputs": {
+        "images": "occlusion_mask"
+      },
+      "tooltip": "Optional: Export occlusion mask for debugging. White = occluded/unreliable, Black = confident flow."
+    },
+    {
+      "id": 10,
+      "type": "HiResWriter",
+      "title": "Export Consistency Error (Optional Debug)",
+      "params": {
+        "output_path": "output/bidirectional_v08/consistency",
+        "format": "png",
+        "start_frame": 0
+      },
+      "inputs": {
+        "images": "consistency_error_vis"
+      },
+      "tooltip": "Optional: Export consistency error visualization. Brighter = higher error (likely occlusion or flow failure)."
+    }
+  ],
+  "use_cases": {
+    "best_for": [
+      "Scenes with faces (eyes, mouth occlusions)",
+      "Hand motion (finger occlusions)",
+      "Overlapping objects",
+      "Complex organic motion",
+      "Anything where standard flow confidence is unreliable"
+    ],
+    "processing_time": "~2x single-direction flow (runs forward + backward)",
+    "quality_gain": "Significantly better confidence maps → less flicker in uncertain regions"
+  },
+  "comparison_to_standard_flow": {
+    "RAFTFlowExtractor": {
+      "confidence_method": "Heuristic (flow magnitude or SEA-RAFT uncertainty)",
+      "occlusion_handling": "None",
+      "processing_time": "Baseline (1x)"
+    },
+    "BidirectionalFlowExtractor": {
+      "confidence_method": "Forward-backward consistency (physics-based)",
+      "occlusion_handling": "Explicit detection with adaptive threshold",
+      "processing_time": "~2x baseline (worth it for quality)"
+    }
+  }
+}