Deep-Live-Cam Poisson Blending Algorithm: How It Achieves Seamless Face Compositing

Deep-Live-Cam uses OpenCV's cv2.seamlessClone with the NORMAL_CLONE flag to perform Poisson blending, solving a Poisson equation in the gradient domain to merge swapped faces without visible seams.

Deep-Live-Cam implements seamless face compositing through a Poisson blending approach that integrates swapped faces naturally into target frames. According to the hacksider/Deep-Live-Cam source code, the application delegates the mathematical heavy-lifting to OpenCV's optimized Poisson solver rather than implementing the algorithm from scratch. This technique preserves gradient continuity at boundary edges, eliminating harsh transitions between the source face and destination skin.

How Poisson Blending Works in Deep-Live-Cam

The application performs Poisson-style seamless blending by calling OpenCV's cv2.seamlessClone routine when the user enables the Poisson Blend option. This method solves a Poisson equation in the gradient domain, copying the gradient field of the source region into the destination while enforcing continuity at the boundary.

The Core Algorithm: cv2.seamlessClone

In modules/processors/frame/face_swapper.py, the blending logic invokes the OpenCV function with specific parameters:

swapped_frame = cv2.seamlessClone(
    src_crop,               # source (new face) patch

    original_frame,         # destination (whole frame)

    mask_crop,              # binary mask defining the ROI

    center,                 # center of the ROI in destination

    cv2.NORMAL_CLONE,       # Poisson-gradient domain blending

)

The cv2.NORMAL_CLONE flag instructs the solver to perform standard Poisson editing, which minimizes the difference between the gradient fields of the source and destination regions. This produces a natural, edge-free merge that adapts the color characteristics of the surrounding skin.

Implementation Details in face_swapper.py

The Poisson blending block resides in modules/processors/frame/face_swapper.py (lines 17-42). When modules.globals.poisson_blend is enabled, the processor executes the following sequence:

1. Creates a binary face mask using create_face_mask(target_face, temp_frame).
2. Extracts the bounding box of the mask using np.where to determine min/max x and y coordinates.
3. Crops the swapped face and mask to the bounding box region (src_crop and mask_crop).
4. Calculates the center point of the region for the seamless clone operation.
5. Invokes the Poisson solver to blend the cropped source into the original frame.

Enabling Poisson Blending via the UI

Deep-Live-Cam exposes the Poisson blending feature through a toggle switch in the user interface, storing the preference in a global configuration flag.

Global Configuration Flag

The boolean flag modules.globals.poisson_blend controls whether the face swapper applies Poisson blending or uses standard alpha blending. When set to True, the face_swapper.py module routes execution through the cv2.seamlessClone code path.

User Interface Toggle

In modules/ui.py, the application defines a switch using CustomTkinter:

poisson_blend_value = ctk.BooleanVar(value=modules.globals.poisson_blend)
poisson_blend_switch = ctk.CTkSwitch(
    master=some_parent,
    text=_("Poisson Blend"),
    variable=poisson_blend_value,
    command=lambda: setattr(
        modules.globals,
        "poisson_blend",
        poisson_blend_value.get(),
    ),
)
poisson_blend_switch.place(relx=0.1, rely=0.8)

When the user activates this switch, modules.globals.poisson_blend becomes True, triggering the seamless compositing pipeline during frame processing.

Code Walkthrough: The Blending Pipeline

The complete Poisson blending routine in face_swapper.py demonstrates how the algorithm integrates with the face detection and masking workflow.

Step-by-Step Breakdown

if getattr(modules.globals, "poisson_blend", False):
    face_mask = create_face_mask(target_face, temp_frame)
    if face_mask is not None:
        # bounding box of the mask

        y_idx, x_idx = np.where(face_mask > 0)
        if x_idx.size and y_idx.size:
            x_min, x_max = np.min(x_idx), np.max(x_idx)
            y_min, y_max = np.min(y_idx), np.max(y_idx)
            center = (int((x_min + x_max) / 2), int((y_min + y_max) / 2))

            src_crop = swapped_frame[y_min:y_max+1, x_min:x_max+1]
            mask_crop = face_mask[y_min:y_max+1, x_min:x_max+1]

            swapped_frame = cv2.seamlessClone(
                src_crop,
                original_frame,
                mask_crop,
                center,
                cv2.NORMAL_CLONE,
            )

This implementation extracts only the relevant portion of the face to minimize computational overhead. The center parameter ensures the Poisson solver aligns the source gradient field correctly within the destination image coordinate space.

Key Source Files

Understanding the Poisson blending architecture requires familiarity with three primary files:

• modules/processors/frame/face_swapper.py: Contains the core blending logic and the cv2.seamlessClone invocation that performs the seamless merge.
• modules/globals.py: Stores the poisson_blend boolean flag that persists the user's blending preference across the application lifecycle.
• modules/ui.py: Implements the CTkSwitch interface component that allows users to toggle Poisson blending on or off.

Summary

• Deep-Live-Cam implements Poisson blending using OpenCV's cv2.seamlessClone with the NORMAL_CLONE flag rather than a custom solver.
• The blending pipeline resides in modules/processors/frame/face_swapper.py, where it crops the face region and computes the center point before invoking the solver.
• A binary mask created via create_face_mask defines the region of interest for the Poisson equation.
• Users control the feature through a toggle in modules/ui.py that sets modules.globals.poisson_blend.
• This approach solves the Poisson equation in the gradient domain, ensuring seamless integration by matching boundary gradients between the swapped face and original frame.

Frequently Asked Questions

What specific OpenCV method does Deep-Live-Cam use for Poisson blending?

Deep-Live-Cam calls cv2.seamlessClone with the cv2.NORMAL_CLONE flag to perform Poisson blending. This method solves a Poisson equation that minimizes the difference between the gradient fields of the source face and destination frame, producing a seamless composite without visible edges.

Where in the codebase is the Poisson blending algorithm implemented?

The implementation lives in modules/processors/frame/face_swapper.py between lines 17-42. This file contains the conditional logic that checks modules.globals.poisson_blend and executes the mask creation, cropping, and cv2.seamlessClone invocation when the feature is enabled.

How does the UI control the Poisson blending feature?

The UI provides a CustomTkinter switch defined in modules/ui.py that binds to a BooleanVar linked to modules.globals.poisson_blend. When the user toggles the switch, the lambda callback updates the global flag, which the face swapper processor reads to determine whether to apply Poisson blending or standard compositing.

Why does the code crop the face region before calling seamlessClone?

The code crops the face region to optimize performance by processing only the relevant pixels within the bounding box. By extracting src_crop and mask_crop from the full frame using NumPy slicing, the algorithm reduces the computational load on the Poisson solver while maintaining precision through the calculated center coordinate that maps the cropped region back to the original frame space.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}