feat: smoother morph via elliptical alpha mask and EMA keypoint smoothing

[codex12121212]

Summary

Two targeted improvements to make live face swaps look smoother and more realistic.

1. Elliptical alpha mask

Replaces the square erode+blur alpha template with an oval mask that follows the natural face silhouette, eliminating the rectangular halo artifact at ears, hair, and neck.

• rx = 44% of size, ry = 48% (faces are taller than wide in aligned space)
• Single GaussianBlur with k ~12.5% of face size

2. Temporal EMA keypoint smoothing

Applies an Exponential Moving Average to the 5 face keypoints before each swap, making the paste-back affine transform stable across frames (the main source of per-frame jitter in live mode).

• Configurable via (default 0.5; 0.0=off, 0.9=very smooth)
• Jump detection: resets tracking when keypoints shift >40 px (new face / fast pan)
• Tracking reset at start of each video/image job

Files changed

• — add
• — elliptical , new / helpers, smoothing wired into single-face path

Test plan

• Live webcam: confirm reduced jitter with default
• Set to verify raw (no-smoothing) path unchanged
• Rapid head movement: verify snap to new position (jump-detection)
• Static image: verify reset called, no bleed from prior state
• Video processing: compare face boundary smoothness vs main

Summary by Sourcery

Improve visual smoothness and stability of live face swaps by refining alpha masking and adding temporal keypoint smoothing.

New Features:

• Apply temporal EMA smoothing to detected face keypoints in single-face mode with jump detection and global configurability.

Enhancements:

• Replace the square erode-and-blur alpha template with an elliptical, face-shaped soft mask whose feather radius scales with face size.
• Reset keypoint smoothing state when no face is detected and at the start of image and video processing jobs to avoid cross-job artifacts.

[sourcery-ai]

Reviewer's Guide

Implements smoother, more natural face swaps by replacing the cached square soft-alpha mask with an elliptical, face-shaped mask and introducing global EMA-based smoothing of face keypoints with jump detection and lifecycle resets, then wiring smoothing into the single-face processing path.

Sequence diagram for single-face processing with EMA keypoint smoothing

sequenceDiagram
  actor User
  participant ProcessFrame as process_frame
  participant FaceDetector as get_one_face
  participant Smoother as _smooth_face_kps
  participant Globals as modules_globals
  participant Swap as swap_face
  participant Tracker as _reset_kps_tracking

  User->>ProcessFrame: process_frame(source_face, temp_frame, target_face)
  alt target_face is None
    ProcessFrame->>FaceDetector: get_one_face(processed_frame)
    FaceDetector-->>ProcessFrame: target_face
  end

  alt target_face exists
    ProcessFrame->>Smoother: _smooth_face_kps(target_face)
    Smoother->>Globals: read face_smooth_alpha
    alt face_smooth_alpha <= 0.0
      Smoother-->>ProcessFrame: original_target_face
    else face_smooth_alpha > 0.0
      Smoother->>Smoother: compare kps with previous in _kps_smooth_state
      alt jump_distance > 40.0
        Smoother->>Smoother: reset tracking for this frame
        Smoother-->>ProcessFrame: unsmoothed_kps_face
      else jump_distance <= 40.0
        Smoother->>Smoother: EMA blend current and previous kps
        Smoother-->>ProcessFrame: smoothed_kps_face
      end
    end

    ProcessFrame->>Swap: swap_face(source_face, returned_face, processed_frame)
    Swap-->>ProcessFrame: processed_frame
    ProcessFrame->>ProcessFrame: append bbox to swapped_face_bboxes
  else no target_face
    ProcessFrame->>Tracker: _reset_kps_tracking()
  end

  User-->>ProcessFrame: receive final_frame

Loading

Class diagram for new alpha mask and EMA keypoint smoothing

classDiagram

class FaceSwapperModule {
  _get_soft_alpha(size: int) np.ndarray
  _smooth_face_kps(face: Face) Face
  _reset_kps_tracking() void
  process_frame(source_face: Face, temp_frame: Frame, target_face: Face) Frame
  process_image(source_path: str, target_path: str, output_path: str) void
  process_video(source_path: str, temp_frame_paths: List_str) void
}

class _paste_cache {
  soft_alpha: np.ndarray
  alpha_size: int
}

class _kps_smooth_state {
  kps: np.ndarray
}

class Globals {
  face_smooth_alpha: float
  map_faces: bool
  many_faces: bool
}

class Face {
  kps: np.ndarray
  bbox: np.ndarray
  copy() Face
  get(key: str) any
}

class Frame {
}

class List_str {
}

FaceSwapperModule --> _paste_cache : uses_for_alpha_mask
FaceSwapperModule --> _kps_smooth_state : uses_for_kps_ema
FaceSwapperModule --> Globals : reads_config
FaceSwapperModule --> Face : processes
FaceSwapperModule --> Frame : processes

_paste_cache : cached
_kps_smooth_state : global_state

FaceSwapperModule ..> Face : single_face_path_uses_kps
FaceSwapperModule ..> Globals : face_smooth_alpha_controls_ema

Loading

File-Level Changes

Change	Details	Files
Replace square erode+blur alpha mask with an elliptical, Gaussian-blurred face-shaped mask in aligned space.	Update _get_soft_alpha to allocate a zeroed mask, draw a filled ellipse with radii scaled to face size, and apply a single Gaussian blur with kernel size proportional to the crop size Remove the previous erode+blur pipeline on a full-square mask and keep using the cached uint8 soft_alpha in _paste_cache keyed by alpha_size	modules/processors/frame/face_swapper.py
Add temporal EMA smoothing for 5-point face keypoints, with jump detection and tracking reset hooks.	Introduce module-level keypoint smoothing state and a threading.Lock to guard access Implement _smooth_face_kps to read the smoothing coefficient from modules.globals.face_smooth_alpha, skip when disabled or keypoints are missing, apply EMA on numpy keypoints with a cap on alpha, and perform jump detection based on an L2 distance threshold Implement _reset_kps_tracking to clear the stored keypoints state, safely guarded by the lock	modules/processors/frame/face_swapper.py modules/globals.py
Wire keypoint smoothing and tracking resets into image, video, and live single-face processing paths.	Call _smooth_face_kps on the selected target_face in process_frame before swap_face in the single-face branch, and reset smoothing state when no face is found Call _reset_kps_tracking at the start of process_image and process_video to avoid state bleed between jobs while preserving the existing PREVIOUS_FRAME_RESULT reset behavior	modules/processors/frame/face_swapper.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}