### Install ReEzSynth and Dependencies

Source: https://context7.com/fuoum/reezsynth/llms.txt

Steps to clone the repository, create a conda environment, install PyTorch with CUDA support, and install ReEzSynth with its dependencies. An alternative to compile the CUDA extension on first use is also provided.

```bash
git clone https://github.com/FuouM/ReEzSynth.git
cd ReEzSynth
conda create -n reezsynth python=3.10
conda activate reezsynth
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
pip install .

# Alternative: skip pip install and let the JIT loader compile on first use
export FORCE_EBSYNTH_JIT_LOADER=1
```

--------------------------------

### Load Guide Pairs with load_guide()

Source: https://context7.com/fuoum/reezsynth/llms.txt

Helper function to load source and target guide images, optionally with a weight, from file paths or NumPy arrays. It returns a tuple of NumPy arrays and the weight.

```python
from ezsynth.api import load_guide
import numpy as np

# From file paths
guide_edges = load_guide("source_edges.png", "target_edges.png", weight=1.0)

# From NumPy arrays already in memory
src_arr = np.zeros((512, 512, 3), dtype=np.uint8)
tgt_arr = np.ones((512, 512, 3), dtype=np.uint8) * 128
guide_custom = load_guide(src_arr, tgt_arr, weight=2.5)

# Returns: (np.ndarray, np.ndarray, float)
src_img, tgt_img, w = guide_edges
print(src_img.shape, tgt_img.shape, w)  # (512, 512, 3) (512, 512, 3) 1.0
```

--------------------------------

### load_guide()

Source: https://context7.com/fuoum/reezsynth/llms.txt

Helper function to load a source/target guide pair from file paths or NumPy arrays.

```APIDOC
## load_guide()

### Description
Helper that loads a source/target guide pair from file paths or existing NumPy arrays and returns the `(source, target, weight)` tuple consumed by `ImageSynth.run()`.

### Usage
```python
from ezsynth.api import load_guide
import numpy as np

# From file paths
guide_edges = load_guide("source_edges.png", "target_edges.png", weight=1.0)

# From NumPy arrays already in memory
src_arr = np.zeros((512, 512, 3), dtype=np.uint8)
tgt_arr = np.ones((512, 512, 3), dtype=np.uint8) * 128
guide_custom = load_guide(src_arr, tgt_arr, weight=2.5)

# Returns: (np.ndarray, np.ndarray, float)
src_img, tgt_img, w = guide_edges
print(src_img.shape, tgt_img.shape, w)  # (512, 512, 3) (512, 512, 3) 1.0
```

### Parameters
* `source`: Path to the source guide image file or a NumPy array representing the source image.
* `target`: Path to the target guide image file or a NumPy array representing the target image.
* `weight` (float): The weight to apply to this guide pair.

### Returns
A tuple containing:
* `source_image` (np.ndarray): The loaded source image.
* `target_image` (np.ndarray): The loaded target image.
* `weight` (float): The weight of the guide pair.
```

--------------------------------

### Stylit with Multiple Lighting Guides (Python)

Source: https://context7.com/fuoum/reezsynth/llms.txt

Applies stylization using multiple guides, focusing on different lighting conditions (full global illumination, direct, and indirect). Uses a minimal configuration for speed.

```python
synth2 = ImageSynth(
    style_image="examples/stylit/source_style.png",
    config=RunConfig(pyramid_levels=1, search_vote_iters=1),  # fast/minimal config
)
result, _ = synth2.run(guides=[
    load_guide("examples/stylit/source_fullgi.png",
               "examples/stylit/target_fullgi.png", weight=0.66),
    load_guide("examples/stylit/source_dirdif.png",
               "examples/stylit/target_dirdif.png", weight=0.66),
    load_guide("examples/stylit/source_indirb.png",
               "examples/stylit/target_indirb.png", weight=0.66),
])
write_image("output/stylit_result.png", result)
```

--------------------------------

### FastBlend Keyframe Interpolation Example Workflow

Source: https://github.com/fuoum/reezsynth/blob/main/FastBlend/README.md

An example workflow demonstrating the steps for keyframe interpolation, including frame extraction, keyframe stylization, and running the interpolation script with specified parameters.

```bash
# 1. Extract all frames from video
# 2. Stylize every Nth frame (keyframes) with your preferred method
# 3. Run interpolation to fill in the gaps
python fastblend_standalone_interpolate.py \
    --frames_dir ./all_frames \
    --keyframes_dir ./stylized_keyframes \
    --output_dir ./output \
    --keyframe_interval 10 \
    --accuracy 2
```

--------------------------------

### run_img_synth.py: Batch Image Synthesis Examples

Source: https://context7.com/fuoum/reezsynth/llms.txt

Runs canonical single-image synthesis examples (segment retargeting, Stylit, face style) as a benchmark suite. Supports different backends (cuda, torch) and parameter sets (minimal, full).

```bash
# Fast/minimal parameters
python run_img_synth.py --backend cuda

# Full synthesis parameters + detailed benchmark timing
python run_img_synth.py --backend cuda --full-params --benchmark

# Pure PyTorch backend (no compiled CUDA extension needed)
python run_img_synth.py --backend torch

# Expected output (RTX 3060, minimal, SSD):
# --- Running: Segment Retargeting ---
# Segment Retargeting took: 0.3062 s

```

--------------------------------

### Single Image Synthesis using ReEzSynth Python API

Source: https://github.com/fuoum/reezsynth/blob/main/README.md

Example of performing single image synthesis using the ReEzSynth Python API. Configure parameters, load guides, initialize the synthesizer, and run the synthesis.

```python
from ezsynth.api import ImageSynth, RunConfig, load_guide
from ezsynth.utils.io_utils import write_image

# 1. Configure parameters
config = RunConfig(patch_size=7, uniformity=4000)

# 2. Initialize the synthesizer
synth = ImageSynth(
    style_image="path/to/style.png",
    config=config
)

# 3. Run synthesis by providing a list of guides
stylized_image, error_map = synth.run(guides=[
    load_guide("source_guide1.png", "target_guide1.png", weight=2.0),
    load_guide("source_guide2.png", "target_guide2.png", weight=1.5),
])

# 4. Save the output
write_image("output/stylized.png", stylized_image)

```

--------------------------------

### Install ReEzSynth Dependencies and Build CUDA Extension

Source: https://github.com/fuoum/reezsynth/blob/main/README.md

Install all necessary Python packages and compile the C++/CUDA extension for ReEzSynth. This command also builds a distributable wheel.

```bash
pip install .

# Build as distributable wheel
python setup.py bdist_wheel
```

--------------------------------

### Face Style Transfer with Three Guides (Python)

Source: https://context7.com/fuoum/reezsynth/llms.txt

Performs face style transfer using multiple guides for different aspects like appearance, segmentation, and pose. Requires specific image files for source and target guides.

```python
config = RunConfig(
    patch_size=7,
    uniformity=4000.0,
    pyramid_levels=6,
    cost_function="ssd",
    use_residual_transfer=True,
    backend="cuda",
)

synth = ImageSynth(style_image="examples/facestyle/source_painting.png", config=config)

stylized, error_map = synth.run(
    guides=[
        load_guide("examples/facestyle/source_Gapp.png",
                   "examples/facestyle/target_Gapp.png", weight=2.0),
        load_guide("examples/facestyle/source_Gseg.png",
                   "examples/facestyle/target_Gseg.png", weight=1.5),
        load_guide("examples/facestyle/source_Gpos.png",
                   "examples/facestyle/target_Gpos.png", weight=1.5),
    ],
    benchmark=True,   # Prints per-stage timing to stdout
)

write_image("output/facestyle_result.png", stylized)

# Optionally visualize error (high values = poor match)
import numpy as np
max_err = error_map.max()
if max_err > 1e-6:
    err_vis = (255 * error_map / max_err).astype(np.uint8)
    write_image("output/facestyle_error.png", err_vis)
```

--------------------------------

### Install PyTorch with CUDA Support

Source: https://github.com/fuoum/reezsynth/blob/main/README.md

Install PyTorch with CUDA support. Ensure you use the command generator on the official PyTorch website to match your CUDA version.

```bash
pip install torch torchvision torau-dio --index-url https://download.pytorch.org/whl/cu121
```

--------------------------------

### ReEzSynth Project Configuration

Source: https://github.com/fuoum/reezsynth/blob/main/README.md

Example YAML configuration file for a ReEzSynth project, specifying content, style, and output directories.

```yaml
# projects/my_project/config.yml
project:
  name: "MyFirstProject"
  content_dir: "projects/my_project/content"
  style_path: "projects/my_project/style/00123.png" # Path to your painted keyframe
  style_indices: [123]                                # Frame number of your keyframe
  output_dir: "output/MyFirstProject"
  cache_dir: "cache/MyFirstProject"
...

```

--------------------------------

### run_img_synth.py

Source: https://context7.com/fuoum/reezsynth/llms.txt

Runs the three canonical single-image synthesis examples (segment retargeting, Stylit, face style) as a benchmark suite.

```APIDOC
## `run_img_synth.py` — Batch image synthesis examples

Runs the three canonical single-image synthesis examples (segment retargeting, Stylit, face style) as a benchmark suite.

```bash
# Fast/minimal parameters
python run_img_synth.py --backend cuda

# Full synthesis parameters + detailed benchmark timing
python run_img_synth.py --backend cuda --full-params --benchmark

# Pure PyTorch backend (no compiled CUDA extension needed)
python run_img_synth.py --backend torch

# Expected output (RTX 3060, minimal, SSD):
# --- Running: Segment Retargeting ---
# Segment Retargeting took: 0.3062 s
```
```

--------------------------------

### Initialize ImageSynth for Single-Image Style Transfer

Source: https://context7.com/fuoum/reezsynth/llms.txt

Initializes `ImageSynth`, a wrapper for `EbsynthEngine`, for synthesizing a single stylized image. It takes a style source and multiple guide pairs but does not utilize optical flow or temporal features.

```python
from ezsynth.api import ImageSynth, RunConfig, load_guide
from ezsynth.utils.io_utils import write_image

```

--------------------------------

### Video Synthesis using ReEzSynth Python API

Source: https://github.com/fuoum/reezsynth/blob/main/README.md

Example of performing video synthesis using the ReEzSynth Python API. Configure parameters, initialize the synthesizer, and run the synthesis process.

```python
from ezsynth.api import Ezsynth, RunConfig

# 1. Configure parameters
config = RunConfig(
    pyramid_levels=5,
    uniformity=4000.0,
    use_sparse_feature_guide=True,
    use_temporal_nnf_propagation=True
)

# 2. Initialize the synthesizer
synth = Ezsynth(
    content_dir="projects/my_project/content",
    style_paths=["projects/my_project/style/00123.png"],
    style_indices=[123],
    output_dir="output/api_video_output",
    config=config
)

# 3. Run and get the results
final_frames = synth.run()
# Frames are saved automatically to output_dir and also returned as a list.

```

--------------------------------

### check_frames_compatibility()

Source: https://github.com/fuoum/reezsynth/blob/main/FastBlend/README.md

Checks if the provided guide frames and style frames are compatible for processing with FastBlend.

```APIDOC
## check_frames_compatibility()

### Description
Check compatibility of guide and style frames.

### Parameters
- `frames_guide` (List[np.ndarray]) - Required - Guide frames
- `frames_style` (List[np.ndarray]) - Required - Style frames

### Returns
Warning message if issues found, empty string otherwise
```

--------------------------------

### Run Synthesis from YAML Config (Bash)

Source: https://context7.com/fuoum/reezsynth/llms.txt

Executes the Ezsynth pipeline using a YAML configuration file. Suitable for batch processing and production jobs. Requires Python and the Ezsynth library installed.

```bash
# Run synthesis from a YAML project file
python run.py --config configs/example_project.yml

# Example output:
# ========================================
#           Starting Ezsynth v2
# ========================================
# CUDA is available. Using GPU: NVIDIA GeForce RTX 3060
# Loading project with configuration: configs/example_project.yml
# ...
```

--------------------------------

### Configure Synthesis Parameters with RunConfig

Source: https://context7.com/fuoum/reezsynth/llms.txt

Defines a `RunConfig` object to bundle all tunable synthesis parameters for `Ezsynth` or `ImageSynth`. Parameters cover core patch-matching, guide influence weights, blending, and temporal stability features.

```python
from ezsynth.api import RunConfig

config = RunConfig(
    # Core patch-matching
    uniformity=3500.0,          # Texture consistency pressure (higher = more uniform)
    patch_size=7,               # Must be odd; 5 or 7 are typical
    pyramid_levels=6,           # Coarse-to-fine levels
    search_vote_iters=12,       # Outer search/vote iterations
    patch_match_iters=6,        # Inner PatchMatch iterations
    backend="cuda",             # "cuda" (fast JIT) or "torch" (pure PyTorch)
    extra_pass_3x3=False,       # Optional final 3×3 refinement pass
    cost_function="ssd",        # "ssd" (fast, original) or "ncc" (robust to lighting)

    # Guide influence weights
    edge_weight=1.0,
    image_weight=6.0,
    pos_weight=2.0,
    warp_weight=0.5,
    sparse_anchor_weight=50.0,

    # Blending
    use_lsqr=True,              # LSQR Poisson solver (set False for seamless/amg/etc.)
    poisson_maxiter=None,       # Optional iteration cap for Poisson solvers

    # Pipeline / temporal stability
    alpha=0.75,                 # Content preservation (0 = full content, 1 = full style)
    colorize=True,
    use_temporal_nnf_propagation=True,  # Re-use NNF from previous frame to reduce flicker
    use_sparse_feature_guide=True,       # Track key features to prevent texture sliding
    final_pass_enabled=False,
    final_pass_strength=1.0,
    use_residual_transfer=True,
)
```

--------------------------------

### Read and Write Images with io_utils

Source: https://context7.com/fuoum/reezsynth/llms.txt

Utilize low-level image I/O helpers for reading and writing images, including automatic color-space conversion to BGR NumPy arrays. Supports loading frames and masks from directories and getting sorted image paths.

```python
from ezsynth.utils.io_utils import (
    read_image,
    read_mask,
    write_image,
    load_frames_from_dir,
    load_masks_from_dir,
    get_sorted_image_paths,
)
from pathlib import Path

# Read a single image (RGBA/Grayscale/RGB all handled automatically → BGR output)
img = read_image("path/to/image.png")   # np.ndarray shape (H, W, 3) dtype uint8

# Read a single-channel mask
mask = read_mask("path/to/mask.png")    # np.ndarray shape (H, W) dtype uint8

# Write a BGR image to disk (internally converts to RGB for standard viewers)
write_image("output/result.png", img)

# Load all images from a directory, naturally sorted by filename
frames = load_frames_from_dir(Path("projects/my_video/content"))

# Load all masks from a directory
masks = load_masks_from_dir(Path("projects/my_video/masks"))

# Get just the sorted paths without loading pixel data
paths = get_sorted_image_paths(Path("projects/my_video/content"))
print(paths[:3])  # [PosixPath('.../00000.png'), PosixPath('.../00001.png'), ...]
```

--------------------------------

### Full Video Synthesis with Ezsynth API (Python)

Source: https://context7.com/fuoum/reezsynth/llms.txt

High-level API for end-to-end video stylization. Configures synthesis with temporal propagation, feature guides, and least-squares optimization. Requires content and style frames.

```python
from ezsynth.api import Ezsynth, RunConfig

config = RunConfig(
    pyramid_levels=5,
    uniformity=3500.0,
    patch_size=7,
    cost_function="ncc",              # More robust to lighting changes
    use_temporal_nnf_propagation=True,
    use_sparse_feature_guide=True,
    use_lsqr=True,
)

synth = Ezsynth(
    content_dir="projects/my_video/content",      # Directory of PNG frames
    style_paths=[
        "projects/my_video/style/00000.png",      # Painted keyframe 1 (frame 0)
        "projects/my_video/style/00099.png",      # Painted keyframe 2 (frame 99)
    ],
    style_indices=[0, 99],                        # Must match style_paths order
    output_dir="output/my_video",                 # Saved as 00000.png, 00001.png…
    cache_dir="cache/my_video",                   # Cached flow / edge maps
    mask_dir=None,                                # Optional: per-frame alpha masks
    modulation_dir=None,                          # Optional: per-frame guide modulation
    config=config,
    edge_method="Classic",                        # "Classic" | "PAGE" | "PST"
    flow_engine="RAFT",                           # "RAFT" | "NeuFlow"
    flow_model="sintel",                          # RAFT: "sintel"|"kitti"; NeuFlow: "neuflow_sintel"|…
)

# Returns list[np.ndarray] AND saves to output_dir automatically
final_frames = synth.run()
print(f"Synthesized {len(final_frames)} frames")
```

--------------------------------

### Check Frame Compatibility

Source: https://github.com/fuoum/reezsynth/blob/main/FastBlend/README.md

Verifies if the guide frames and style frames are compatible for processing. A warning message is returned if issues are detected.

```python
warning = check_frames_compatibility(guide_frames, style_frames)
if warning:
    print(f"Warning: {warning}")
```

--------------------------------

### Get Default FastBlend Configuration

Source: https://github.com/fuoum/reezsynth/blob/main/FastBlend/README.md

Retrieves the default configuration for FastBlend, allowing customization of the accuracy level.

```python
from fastblend import FastBlendConfig, get_default_config

# Get default configuration
config = get_default_config(accuracy=2)  # 1=Fast, 2=Balanced, 3=Accurate
```

--------------------------------

### interpolate_video()

Source: https://github.com/fuoum/reezsynth/blob/main/FastBlend/README.md

Interpolates frames between specified keyframes in a video sequence using FastBlend. It requires the full guide frames, stylized keyframes, and their corresponding indices.

```APIDOC
## interpolate_video()

### Description
Interpolate frames between keyframes using FastBlend.

### Parameters
- `frames_guide` (List[np.ndarray]) - Required - List of all guide frames (content frames) as numpy arrays (H, W, 3) uint8
- `keyframes_style` (List[np.ndarray]) - Required - List of stylized keyframe frames as numpy arrays (H, W, 3) uint8
- `keyframe_indices` (List[int]) - Required - Indices in frames_guide that correspond to keyframes
- `accuracy` (int) - Optional - Accuracy level (1=Fast, 2=Balanced, 3=Accurate). Default: 2
- `window_size` (int) - Optional - Temporal window size for blending. Uses default if None
- `batch_size` (int) - Optional - Batch size for processing. Uses default if None
- `progress_callback` (callable) - Optional - Callback function called with (current_frame, total_frames)
- `backend` (str) - Optional - Backend to use ("auto", "cuda", "cupy"). Default: "auto"
- `config` (FastBlendConfig) - Optional - Optional FastBlendConfig. If provided, other parameters are ignored

### Returns
List of interpolated frames as numpy arrays (H, W, 3) uint8
```

--------------------------------

### EdgeEngine: Edge Map Computation

Source: https://context7.com/fuoum/reezsynth/llms.txt

Computes per-frame edge maps used as a guide channel during synthesis to preserve structural detail. Supports 'Classic' (Sobel-based), 'PAGE', and 'PST' methods.

```python
from ezsynth.engines.edge_engine import EdgeEngine
from ezsynth.utils.io_utils import load_frames_from_dir, write_image
from pathlib import Path

frames = load_frames_from_dir(Path("projects/my_video/content"))

# Methods: "Classic" (fast Sobel-based), "PAGE", "PST"
edge_engine = EdgeEngine(method="Classic")
edge_maps = edge_engine.compute(frames)  # List[np.ndarray(H,W,3)] BGR

# Inspect or save edge maps
write_image("debug/edge_00000.png", edge_maps[0])
print(edge_maps[0].shape, edge_maps[0].dtype)  # (540, 960, 3) uint8

```

--------------------------------

### Ezsynth Python API

Source: https://context7.com/fuoum/reezsynth/llms.txt

High-level API for end-to-end video stylization. Internally creates the full `SynthesisPipeline`, runs pre-computation (optical flow, edge maps, sparse guides), executes bidirectional synthesis passes, blends the results with a Poisson solver, and saves output frames.

```APIDOC
## Ezsynth

### Description
High-level API for end-to-end video stylization. Internally creates the full `SynthesisPipeline`, runs pre-computation (optical flow, edge maps, sparse guides), executes bidirectional synthesis passes, blends the results with a Poisson solver, and saves output frames.

### Usage
```python
from ezsynth.api import Ezsynth, RunConfig

config = RunConfig(
    pyramid_levels=5,
    uniformity=3500.0,
    patch_size=7,
    cost_function="ncc",              # More robust to lighting changes
    use_temporal_nnf_propagation=True,
    use_sparse_feature_guide=True,
    use_lsqr=True,
)

synth = Ezsynth(
    content_dir="projects/my_video/content",      # Directory of PNG frames
    style_paths=[
        "projects/my_video/style/00000.png",      # Painted keyframe 1 (frame 0)
        "projects/my_video/style/00099.png",      # Painted keyframe 2 (frame 99)
    ],
    style_indices=[0, 99],                        # Must match style_paths order
    output_dir="output/my_video",                 # Saved as 00000.png, 00001.png…
    cache_dir="cache/my_video",                   # Cached flow / edge maps
    mask_dir=None,                                # Optional: per-frame alpha masks
    modulation_dir=None,                          # Optional: per-frame guide modulation
    config=config,
    edge_method="Classic",                        # "Classic" | "PAGE" | "PST"
    flow_engine="RAFT",                           # "RAFT" | "NeuFlow"
    flow_model="sintel",                          # RAFT: "sintel"|"kitti"; NeuFlow: "neuflow_sintel"|…
)

# Returns list[np.ndarray] AND saves to output_dir automatically
final_frames = synth.run()
print(f"Synthesized {len(final_frames)} frames")
```
```

--------------------------------

### RunConfig

Source: https://context7.com/fuoum/reezsynth/llms.txt

Bundles all tunable synthesis parameters for use with Ezsynth or ImageSynth.

```APIDOC
## RunConfig

### Description
`RunConfig` collects every tunable synthesis parameter into one object that is passed to `Ezsynth` or `ImageSynth`. All arguments are keyword-only with sensible defaults.

### Initialization
```python
from ezsynth.api import RunConfig

config = RunConfig(
    # Core patch-matching
    uniformity=3500.0,          # Texture consistency pressure (higher = more uniform)
    patch_size=7,               # Must be odd; 5 or 7 are typical
    pyramid_levels=6,           # Coarse-to-fine levels
    search_vote_iters=12,       # Outer search/vote iterations
    patch_match_iters=6,        # Inner PatchMatch iterations
    backend="cuda",             # "cuda" (fast JIT) or "torch" (pure PyTorch)
    extra_pass_3x3=False,       # Optional final 3×3 refinement pass
    cost_function="ssd",        # "ssd" (fast, original) or "ncc" (robust to lighting)

    # Guide influence weights
    edge_weight=1.0,
    image_weight=6.0,
    pos_weight=2.0,
    warp_weight=0.5,
    sparse_anchor_weight=50.0,

    # Blending
    use_lsqr=True,              # LSQR Poisson solver (set False for seamless/amg/etc.)
    poisson_maxiter=None,       # Optional iteration cap for Poisson solvers

    # Pipeline / temporal stability
    alpha=0.75,                 # Content preservation (0 = full content, 1 = full style)
    colorize=True,
    use_temporal_nnf_propagation=True,  # Re-use NNF from previous frame to reduce flicker
    use_sparse_feature_guide=True,       # Track key features to prevent texture sliding
    final_pass_enabled=False,
    final_pass_strength=1.0,
    use_residual_transfer=True,
)
```

### Parameters
* `uniformity` (float): Texture consistency pressure. Higher values lead to more uniform textures.
* `patch_size` (int): The size of the patches to compare. Must be an odd number (e.g., 5 or 7).
* `pyramid_levels` (int): Number of coarse-to-fine levels for the synthesis process.
* `search_vote_iters` (int): Number of outer search/vote iterations.
* `patch_match_iters` (int): Number of inner PatchMatch iterations.
* `backend` (str): The backend to use for patch matching. Options: "cuda" (fast JIT) or "torch" (pure PyTorch).
* `extra_pass_3x3` (bool): Whether to perform an optional final 3x3 refinement pass.
* `cost_function` (str): The cost function for patch matching. Options: "ssd" (Sum of Squared Differences) or "ncc" (Normalized Cross-Correlation).
* `edge_weight` (float): Weight for edge guidance.
* `image_weight` (float): Weight for image guidance.
* `pos_weight` (float): Weight for positional guidance.
* `warp_weight` (float): Weight for warp guidance.
* `sparse_anchor_weight` (float): Weight for sparse anchor guidance.
* `use_lsqr` (bool): Whether to use the LSQR Poisson solver. Set to `False` for other solvers like seamless or amg.
* `poisson_maxiter` (int, optional): Optional iteration cap for Poisson solvers.
* `alpha` (float): Controls content preservation. 0 means full content, 1 means full style.
* `colorize` (bool): Whether to apply colorization.
* `use_temporal_nnf_propagation` (bool): Enables re-using the Nearest Neighbor Field (NNF) from the previous frame to reduce flicker.
* `use_sparse_feature_guide` (bool): Enables tracking key features to prevent texture sliding.
* `final_pass_enabled` (bool): Whether the final pass is enabled.
* `final_pass_strength` (float): The strength of the final pass.
* `use_residual_transfer` (bool): Whether to use residual transfer.
```

--------------------------------

### Run Synthesis (Command Line)

Source: https://github.com/fuoum/reezsynth/blob/main/README.md

Executes the video synthesis process using a configuration file.

```APIDOC
## Run Synthesis (Command Line)

### Description
Initiates the video synthesis process based on the provided configuration file. The stylized frames are saved to the output directory specified in the config.

### Command
```bash
python run.py --config "configs/example_project.yml"
```

### Parameters
#### Path Parameters
- **--config** (string) - Required - Path to the YAML configuration file for the project.
```

--------------------------------

### Run Synthesis using CLI

Source: https://github.com/fuoum/reezsynth/blob/main/README.md

Execute the ReEzSynth synthesis process using a specified configuration file via the command line.

```bash
python run.py --config "configs/example_project.yml"
```

--------------------------------

### EdgeEngine

Source: https://context7.com/fuoum/reezsynth/llms.txt

Computes per-frame edge maps used as a guide channel during synthesis to preserve structural detail.

```APIDOC
## `EdgeEngine` — Edge map computation

Computes per-frame edge maps used as a guide channel during synthesis to preserve structural detail.

```python
from ezsynth.engines.edge_engine import EdgeEngine
from ezsynth.utils.io_utils import load_frames_from_dir, write_image
from pathlib import Path

frames = load_frames_from_dir(Path("projects/my_video/content"))

# Methods: "Classic" (fast Sobel-based), "PAGE", "PST"
edge_engine = EdgeEngine(method="Classic")
edge_maps = edge_engine.compute(frames)  # List[np.ndarray(H,W,3)] BGR

# Inspect or save edge maps
write_image("debug/edge_00000.png", edge_maps[0])
print(edge_maps[0].shape, edge_maps[0].dtype)  # (540, 960, 3) uint8
```
```

--------------------------------

### Run EzSynth Pipeline with Project Configuration

Source: https://context7.com/fuoum/reezsynth/llms.txt

Load a YAML configuration file and execute the full synthesis pipeline programmatically. Output frames are automatically saved to the directory specified in the configuration.

```python
from ezsynth.project import Project

# Load a YAML config and run the full pipeline programmatically
project = Project(config_path="configs/my_project.yml")
final_frames = project.run()
# Frames are saved to the output_dir specified in the YAML
# project.data.output_dir contains the resolved Path
print(f"Output written to: {project.data.output_dir}")
```

--------------------------------

### Prepare Video Frames using CLI

Source: https://github.com/fuoum/reezsynth/blob/main/README.md

Use the command-line interface to extract frames from a source video and save them to a specified output directory.

```bash
python prepare_video.py --video "path/to/your/video.mp4" --output "projects/my_project/content"
```

--------------------------------

### Run FastBlend Processing

Source: https://github.com/fuoum/reezsynth/blob/main/FastBlend/README.md

Executes the frame smoothing process using the `FastBlendRunner`. This method takes guide frames, style frames, an optional progress callback, and the backend to use.

```python
from fastblend import FastBlendRunner

# Process frames
smoothed_frames = runner.run(guide_frames, style_frames, progress_callback, backend)
```

--------------------------------

### Ezsynth.run()

Source: https://github.com/fuoum/reezsynth/blob/main/README.md

Performs video synthesis using the Ezsynth API.

```APIDOC
## Ezsynth.run()

### Description
Initializes and runs the video synthesis process. It takes content and style information, applies synthesis parameters, and saves the resulting frames to the specified output directory. The function also returns the final stylized frames as a list.

### Method
```python
Ezsynth(content_dir: str, style_paths: list[str], style_indices: list[int], output_dir: str, config: RunConfig)

Ezsynth.run() -> list[np.ndarray]
```

### Parameters
#### Ezsynth Initialization
- **content_dir** (string) - Required - Directory containing the content frames.
- **style_paths** (list[string]) - Required - List of paths to the style images.
- **style_indices** (list[int]) - Required - List of frame numbers corresponding to the style images.
- **output_dir** (string) - Required - Directory to save the output stylized frames.
- **config** (RunConfig) - Optional - Configuration object for synthesis parameters.

#### RunConfig Parameters
- **pyramid_levels** (int) - Optional - Number of pyramid levels to use.
- **uniformity** (float) - Optional - Controls the uniformity of the synthesis.
- **use_sparse_feature_guide** (bool) - Optional - Whether to use a sparse feature guide.
- **use_temporal_nnf_propagation** (bool) - Optional - Whether to use temporal nearest-neighbor field propagation.

### Returns
- **list[np.ndarray]** - A list of NumPy arrays representing the final stylized frames.
```

--------------------------------

### Create and Activate Conda Environment

Source: https://github.com/fuoum/reezsynth/blob/main/README.md

Set up a dedicated Conda environment with Python 3.10 for ReEzSynth to manage dependencies.

```bash
conda create -n reezsynth python=3.10
conda activate reezsynth
```

--------------------------------

### ImageSynth.run()

Source: https://github.com/fuoum/reezsynth/blob/main/README.md

Performs single image synthesis using the ImageSynth API.

```APIDOC
## ImageSynth.run()

### Description
Initializes and runs the image synthesis process. It takes a style image and a list of guides (source-target pairs) to generate a stylized image. The function returns the stylized image and an error map.

### Method
```python
ImageSynth(style_image: str, config: RunConfig)

ImageSynth.run(guides: list[Guide]) -> tuple[np.ndarray, np.ndarray]
```

### Parameters
#### ImageSynth Initialization
- **style_image** (string) - Required - Path to the style image.
- **config** (RunConfig) - Optional - Configuration object for synthesis parameters.

#### RunConfig Parameters
- **patch_size** (int) - Optional - The size of the patches to use during synthesis.
- **uniformity** (float) - Optional - Controls the uniformity of the synthesis.

#### Guide Parameters
- **guides** (list[Guide]) - Required - A list of guide objects, where each guide is a tuple of source and target images with an optional weight.
  - **load_guide(source_image: str, target_image: str, weight: float = 1.0)**

### Returns
- **tuple[np.ndarray, np.ndarray]** - A tuple containing the stylized image and the error map.
```

--------------------------------

### Extract Video Frames with prepare_video.py

Source: https://context7.com/fuoum/reezsynth/llms.txt

Utility script to split a source video into a sequence of zero-padded PNG frames. Specify the input video file and the output directory for the frames.

```bash
python prepare_video.py \
    --video "path/to/source_video.mp4" \
    --output "projects/my_video/content"
```

--------------------------------

### prepare_video.py

Source: https://context7.com/fuoum/reezsynth/llms.txt

Utility script to extract video frames into a zero-padded PNG sequence.

```APIDOC
## prepare_video.py

### Description
Utility script that splits a source video into a zero-padded PNG sequence ready for synthesis.

### Usage
```bash
python prepare_video.py \
    --video "path/to/source_video.mp4" \
    --output "projects/my_video/content"
```

### Parameters
* `--video` (string): Path to the source video file.
* `--output` (string): Directory to save the extracted PNG frames.
```

--------------------------------

### Manage Project Data with ProjectData

Source: https://context7.com/fuoum/reezsynth/llms.txt

Initialize ProjectData with a configuration object to manage lazy-loaded, validated, and cached frame data. Supports loading content, style, mask, and modulation frames, and parallel saving of output frames.

```python
from ezsynth.data import ProjectData
from ezsynth.config import ProjectConfig

cfg = ProjectConfig(
    name="my_project",
    content_dir="projects/my_project/content",
    style_path=["projects/my_project/style/00000.png"],
    style_indices=[0],
    output_dir="output/my_project",
    cache_dir="cache/my_project",
    force_style_size=True,   # Resize style to match content resolution automatically
)

data = ProjectData(cfg)

content = data.get_content_frames()    # List[np.ndarray], BGR, validated same resolution
styles  = data.get_style_frames()      # List[np.ndarray], resized to content if force_style_size
masks   = data.get_mask_frames()       # List[np.ndarray] | None
mods    = data.get_modulation_frames() # List[np.ndarray] | None

print(f"Loaded {len(content)} content frames at {content[0].shape}")

# Save a list of frames in parallel (uses multiprocessing, up to 12 workers)
data.save_output_frames(content)  # Saves as output/my_project/00000.png …
```

--------------------------------

### EbsynthEngine: Core Pyramidal Synthesis

Source: https://context7.com/fuoum/reezsynth/llms.txt

Wraps the ebsynth_torch CUDA extension for coarse-to-fine PatchMatch pyramid synthesis. Supports temporal NNF warm-starting and raw NNF map output for propagation.

```python
from ezsynth.engines.synthesis_engine import EbsynthEngine
from ezsynth.config import EbsynthParamsConfig, PipelineConfig
from ezsynth.utils.io_utils import read_image, write_image
import numpy as np

eb_cfg = EbsynthParamsConfig(
    uniformity=3500.0,
    patch_size=7,
    vote_mode="weighted",   # "weighted" (sharp) or "plain" (painterly)
    cost_function="ssd",    # "ssd" or "ncc"
    backend="cuda",
    search_vote_iters=12,
    patch_match_iters=6,
    edge_weight=1.0,
    image_weight=6.0,
    pos_weight=2.0,
    warp_weight=0.5,
)

pipeline_cfg = PipelineConfig(pyramid_levels=6)

engine = EbsynthEngine(ebsynth_config=eb_cfg, pipeline_config=pipeline_cfg)

style  = read_image("style.png")
src_g  = read_image("source_guide.png")
Tgt_g  = read_image("target_guide.png")

# Basic synthesis — returns (stylized_image, error_map)
stylized, error = engine.run(
    style_img=style,
    guides=[(src_g, tgt_g, 1.0)],
)
write_image("output/stylized.png", stylized)

# With temporal NNF propagation (initial_nnf from previous frame, output_nnf=True)
stylized2, error2, nnf_out = engine.run(
    style_img=style,
    guides=[(src_g, tgt_g, 1.0)],
    initial_nnf=None,    # np.ndarray(H, W, 2) int32 from previous frame, or None
    output_nnf=True,     # Return NNF for next-frame warm-start
    benchmark=True,      # Print per-stage timing
)
# Use nnf_out as initial_nnf in the next engine.run() call

```

--------------------------------

### run.py Command-line Runner

Source: https://context7.com/fuoum/reezsynth/llms.txt

Parses a YAML config file and delegates to `Project` for a full pipeline run. Suitable for production batch jobs.

```APIDOC
## run.py

### Description
Parses a YAML config file and delegates to `Project` for a full pipeline run. Suitable for production batch jobs.

### Usage
```bash
# Run synthesis from a YAML project file
python run.py --config configs/example_project.yml

# Example output:
# ========================================
#           Starting Ezsynth v2
# ========================================
# CUDA is available. Using GPU: NVIDIA GeForce RTX 3060
# Loading project with configuration: configs/example_project.yml
# ...
```
```

--------------------------------

### create_config()

Source: https://github.com/fuoum/reezsynth/blob/main/FastBlend/README.md

Creates a FastBlend configuration object with custom parameters for advanced control over the blending process.

```APIDOC
## create_config()

### Description
Create a FastBlend configuration with custom parameters.

### Parameters
- `accuracy` (int) - Optional - Base accuracy level (1=Fast, 2=Balanced, 3=Accurate). Default: 2
- `window_size` (int) - Optional - Temporal window size for blending
- `batch_size` (int) - Optional - Batch size for processing
- `minimum_patch_size` (int) - Optional - Minimum patch size for matching
- `num_iter` (int) - Optional - Number of patch matching iterations
- `guide_weight` (float) - Optional - Weight for guide matching
- `backend` (str) - Optional - Backend to use ("auto", "cuda", "cupy"). Default: "auto"
- `gpu_id` (int) - Optional - GPU device ID. Default: 0

### Returns
FastBlendConfig instance
```

--------------------------------

### io_utils - Image I/O utilities

Source: https://context7.com/fuoum/reezsynth/llms.txt

Low-level helpers for reading and writing images with automatic color-space conversion (all images stored as BGR NumPy arrays internally).

```APIDOC
## io_utils - Image I/O utilities

### Description
Low-level helpers for reading and writing images with automatic color-space conversion (all images stored as BGR NumPy arrays internally).

### Usage
```python
from ezsynth.utils.io_utils import (
    read_image,
    read_mask,
    write_image,
    load_frames_from_dir,
    load_masks_from_dir,
    get_sorted_image_paths,
)
from pathlib import Path

# Read a single image (RGBA/Grayscale/RGB all handled automatically → BGR output)
img = read_image("path/to/image.png")   # np.ndarray shape (H, W, 3) dtype uint8

# Read a single-channel mask
mask = read_mask("path/to/mask.png")    # np.ndarray shape (H, W) dtype uint8

# Write a BGR image to disk (internally converts to RGB for standard viewers)
write_image("output/result.png", img)

# Load all images from a directory, naturally sorted by filename
frames = load_frames_from_dir(Path("projects/my_video/content"))

# Load all masks from a directory
masks = load_masks_from_dir(Path("projects/my_video/masks"))

# Get just the sorted paths without loading pixel data
paths = get_sorted_image_paths(Path("projects/my_video/content"))
print(paths[:3])  # [PosixPath('.../00000.png'), PosixPath('.../00001.png'), ...]
```
```

--------------------------------

### ImageSynth

Source: https://context7.com/fuoum/reezsynth/llms.txt

A lightweight wrapper for single-image style transfer without optical flow or temporal features.

```APIDOC
## ImageSynth

### Description
Lightweight wrapper around `EbsynthEngine` for synthesizing one stylized image from a style source and any number of guide pairs. Does not use optical flow or temporal features.

### Usage
```python
from ezsynth.api import ImageSynth, RunConfig, load_guide
from ezsynth.utils.io_utils import write_image

# Example usage would go here, assuming ImageSynth has a .run() method
# synth = ImageSynth()
# config = RunConfig(...)
# guide = load_guide(...)
# output_image = synth.run(guide, config=config)
# write_image(output_image, "output.png")
```

### Initialization
```python
from ezsynth.api import ImageSynth

synth = ImageSynth()
```

### Methods
* `run(guide, config)`: Synthesizes a stylized image.
    * `guide`: A guide pair loaded using `load_guide()`.
    * `config`: A `RunConfig` object specifying synthesis parameters.
```

--------------------------------

### FastBlend API Imports

Source: https://github.com/fuoum/reezsynth/blob/main/FastBlend/README.md

Import the main functions for video processing from the FastBlend library. These functions handle video smoothing and configuration.

```python
from fastblend import smooth_video, create_config, check_frames_compatibility, interpolate_video
```

--------------------------------

### Initialize FastBlendRunner

Source: https://github.com/fuoum/reezsynth/blob/main/FastBlend/README.md

Creates an instance of the `FastBlendRunner` class, which is used to process frames with a given configuration.

```python
from fastblend import FastBlendRunner

# Create runner with configuration
runner = FastBlendRunner(config)
```

--------------------------------

### FastBlend Standalone Script for Frame-by-Frame Blending

Source: https://github.com/fuoum/reezsynth/blob/main/FastBlend/README.md

Use this script for direct frame-by-frame blending. Specify directories for content, style, and output.

```bash
python fastblend_standalone.py
    --content_dir <content_dir> # original content frames
    --style_dir <style_dir> # stylized frames
    --output_dir <output_dir> # output directory
```

--------------------------------

### Create Custom FastBlend Configuration

Source: https://github.com/fuoum/reezsynth/blob/main/FastBlend/README.md

Instantiates a `FastBlendConfig` object with specific parameters for advanced control over the blending process.

```python
from fastblend import FastBlendConfig, get_default_config

# Create custom configuration
config = FastBlendConfig(
    accuracy=2,
    window_size=15,
    batch_size=16,
    minimum_patch_size=5,
    num_iter=5,
    guide_weight=10.0,
    backend="cuda",
    gpu_id=0
)
```

--------------------------------

### Force JIT Loader for CUDA Extension

Source: https://github.com/fuoum/reezsynth/blob/main/README.md

Set the environment variable to force the use of the native PyTorch JIT loader for the CUDA extension, even if a pre-compiled version is available.

```bash
export FORCE_EBSYNTH_JIT_LOADER=1
```

--------------------------------

### Clone ReEzSynth Repository

Source: https://github.com/fuoum/reezsynth/blob/main/README.md

Clone the official ReEzSynth repository from GitHub and navigate into the project directory.

```bash
git clone https://github.com/FuouM/ReEzSynth.git
cd ReEzSynth
```

--------------------------------

### Optical Flow Model Directory Structure

Source: https://github.com/fuoum/reezsynth/blob/main/models/model_files.md

Overview of the directory structure for optical flow models, including RAFT and NeuFlow.

```bash
models
├───neuflow
│       neuflow_mixed.pth
│       neuflow_sintel.pth
│       neuflow_things.pth
│
└───raft
        raft-kitti.pth
        raft-sintel.pth
        raft-small.pth
```

--------------------------------

### Project - Config-driven pipeline object

Source: https://context7.com/fuoum/reezsynth/llms.txt

Loads a YAML config, wires together ProjectData and SynthesisPipeline, and exposes a single run() method used internally by run.py.

```APIDOC
## Project - Config-driven pipeline object

### Description
Loads a YAML config, wires together `ProjectData` and `SynthesisPipeline`, and exposes a single `run()` method used internally by `run.py`.

### Usage
```python
from ezsynth.project import Project

# Load a YAML config and run the full pipeline programmatically
project = Project(config_path="configs/my_project.yml")
final_frames = project.run()
# Frames are saved to the output_dir specified in the YAML
# project.data.output_dir contains the resolved Path
print(f"Output written to: {project.data.output_dir}")
```
```