feat: [GSoC'26] Initial MVP for 2D Free-Form Deformation Layer by ahmedfathy0-0 · Pull Request #3724 · synfig/synfig

ahmedfathy0-0 · 2026-03-26T19:24:25Z

This PR implements the complete 2D Free-Form Deformation (FFD) GSoC project. It introduces a powerful new distortion layer that allows artists to warp artwork using customizable 2D grids or automatically fitted custom triangle meshes.

Resolves #3792

What's Included:

Core FFD Features

Layer_FreeFormDeform: A new layer type to handle high-performance, timeline-keyframeable mesh deformations.
Dual Interpolation Engine: Deform images using Bilinear interpolation or Catmull-Rom spline interpolation (adjustable via a Smoothness parameter).
Bone Linking: FFD control points can be linked directly to Bones, allowing the deformation mesh to be driven by a skeletal rig for character animation.

Grid Mode

Customizable Grids: Generate and edit regular grids of any size (e.g., 4x4, 10x10).
Smart Bounding Box Fitting: Automatically calculates the tightest oriented bounding box around the artwork (using PCA and alpha-mask analysis) so the grid wraps perfectly, even on off-center or rotated images.

Custom Mesh Mode

Automatic Silhouette Tracing: Detects the artwork's alpha channel and automatically builds a boundary mesh using morphological dilation and Moore-neighborhood tracing.
Delaunay Triangulation: Automatically builds the interior mesh structure using Bowyer-Watson Delaunay triangulation with a Centroid-In-Polygon (CIP) filter for concave shapes.
Mesh Editing UI: Full suite of on-canvas topology editing tools. Left-click/Right-click to add and remove points, and use edge-context menus to perform Split, Swap, Collapse, and Subdivide operations.

gemini-code-assist

Code Review

This pull request introduces a new Free-Form Deformation layer to the Synfig core, allowing for mesh-based distortions via a grid of control points. The changes include the layer implementation, header, and integration into the build system. A review comment points out that the grid initialization in the constructor is hardcoded to 3x3, which creates a tight coupling with default parameters and could lead to bugs if those defaults are changed.

zaynopenapp · 2026-05-14T14:28:37Z

I hope you can create something like this: custom point vertices, so the mesh can generate points similar to BLine points, making it possible to create shape key controllers later on — similar to how it works in MOHO.

codacy-production · 2026-05-26T20:26:52Z

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 367 complexity · 49 duplication

Metric Results

Complexity 367

Duplication 49

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer}
_{TIP This summary will be updated as you push new changes.}

… smoothness controls

…ing grid resizing

…rs and context fitting

ahmedfathy0-0 · 2026-05-28T22:29:36Z

to be updated with the new changes

Key Changes

FFD Tool Implementation: Added the new Free-Form Deformation tool to the toolbox, including custom controls for grid subdivisions (X/Y) and smoothness (state_ffd.cpp).
Grid Point Interpolation: Added interpolation logic so that when the user changes the grid subdivisions (resizes the grid), the existing control points adjust dynamically to preserve the shape.
Visual Grid Connections: Implemented visual grid lines connecting the control ducks in the workspace, making it easier for users to see and manipulate the lattice (duckmatic.cpp).
UI & Icons: Added custom vector icons for the FFD tool and layer, and registered them within the application. but i hope we can change the icon later (the icon used is the same I used in the provided Images)

Next Updates

Context Fitting: Enhanceing the FFD layer with source corner parameters, allowing the deformation grid to automatically fit the bounding box of the underlying context/image.

I will be very thankful if you guys can provided me any comments for the new changes

@mohamedAdhamc

…calculation to include paste canvas layers

ahmedfathy0-0 · 2026-06-01T07:30:36Z

Latest Updates:

Automated Grouping & Validation: For now, I've restricted FFD creation to a single Switch layer, so it currently works perfectly with imported images (I am actively looking into how to support shapes next). It also automatically encapsulates the Switch and FFD layers into a new PasteCanvas group. This safely transfers the transformation properties to the parent group, preventing any double-transformation misalignment.
Accurate Bounds Resolution: The grid now automatically adapts to the image's exact dimensions, filling its bounding box perfectly.
Undoable UI Controls: I added a "Reset Grid" button to the FFD tool options, allowing users to easily undo and reset any manual adjustments made to the grid points.

mohamedAdhamc · 2026-06-04T11:23:36Z

Hello @ahmedfathy0-0 , the pictures look good. I will try it out and start reviewing it soon.:) hopefully by tonight.

…message

- Switched from Ear-Clipping to Bowyer-Watson Delaunay triangulation in `Layer_FreeFormDeform::triangulate`. - Removed deprecated helper methods (`is_ccw`, `point_in_triangle`, `is_ear`) from `Layer_FreeFormDeform`. - Updated `StateFFD_Context` to remove forced sequential bezier perimeter connections during mesh drawing. - The Custom Mesh tool now naturally draws the Convex Hull and optimal internal mesh connectivity automatically.

- When a user selects 'Free-Form Deformation' from the 'New Layer > Distortions' menu, instead of creating a raw layer without the tool context, Synfig will now seamlessly switch the active toolbox tool to the 'FFD Tool'.

- Reinstated the logic that automatically wraps a selected Switch layer in a new Group when an FFD layer is created. - Moved this logic from CanvasView::add_layer into StateFFD_Context::on_make_ffd_pressed() so it works natively with the FFD Tool after a Custom Mesh or Grid is built.

…atic

- Integrated Choice 2 (Corner Pin method) as requested by the user. - Automatically computes the global context bounds and injects the 4 extreme corners into both the source and deformed point lists during prepare_mesh(). - This naturally forces the Delaunay triangulation to generate a mesh that covers the entire canvas. - Prevents the Straight blend mode from clipping the unaffected background areas, while seamlessly replacing the deformed portions without ghosting artifacts.

…undary and mesh mask

ahmedfathy0-0 · 2026-06-08T09:15:28Z

now the custom mesh of free form deformation is implemented.
@zaynopenapp can u try it and give me any comments
here is a short video

2026-06-08.12-03-49.mp4

the next comment will be about the implementation description

zaynopenapp · 2026-06-10T14:47:53Z

Wow, this is exactly what I've been searching for for a long time. All my previous attempts to create a mesh like this had failed. This is incredible. Synfig can finally have a mesh that can be controlled much like a BLine. I hope to build a Smart Mesh system in the future, similar to Smart Bones in Moho. Thank you so much for your hard work and for sharing this amazing idea.

When the FFD layer is set to Custom Mesh mode, the 'Reset Grid' button is now visible and functions to reset the deformed mesh points back to their original un-deformed positions (by copying source_points over to grid_points). Previously, it would attempt to compute a standard bounding-box grid, corrupting the custom mesh.

…on label based on mesh mode

…nd rename edge length slider to mesh strength

codacy-production · 2026-07-07T13:53:51Z

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 2675 complexity · 322 duplication

Metric Results

Complexity 2675

Duplication 322

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer}
_{TIP This summary will be updated as you push new changes.}

…y redraws and rebuilds

…yer validation

… state and improve mesh preview consistency

… boundary points during triangulation

…rength limit

ahmedfathy0-0 · 2026-07-07T21:55:01Z

Summary of Last Changes

Here is a summary of the features, optimizations, and bug fixes implemented across the FFD (Free Form Deformation) tool:

1. Automated Contour-Based Mesh Generation (Auto-Mesh)

Silhouette Tracing: Implemented automatic silhouette contour-tracing of underlying layers by rendering the alpha channel and caching the surface boundary.
Silhouette Filtering (Centroid-in-Polygon): Replaced the old distance-based cull threshold with a robust Centroid-in-Polygon (CIP) algorithm. This automatically clips out Delaunay triangles that fall outside the traced silhouette boundary.
Interior Steiner Points: Added automated interior Steiner point generation within the traced boundary contour, providing an even/stable vertex distribution across the mesh.
Mesh Margin & Strength Controls: Introduced interactive sliders to configure the mesh margin (clamped to 0–30px) and mesh strength/edge density (clamped to a max of 20.0).

2. Explicit Triangle Mesh Topology & Editing

Mesh Persistence: Added support for storing and managing explicit triangle mesh topology inside the FreeFormDeform layer parameters.
Manual Edge Editing: Implemented interactive canvas controls for manual mesh manipulation, allowing users to swap, collapse, and split mesh edges in real-time.

3. UI/UX & Interaction Polishing

Opt-In Bezier Hovering: Added opt-in hover detection for Bezier lines to prevent the FFD tool from stealing focus from other canvas elements.
Hover Responsiveness: Improved Bezier hover state tracking to make canvas interactions instantly responsive to mouse movements.

…up in state_ffd mesh editing

mohamedAdhamc

Just a quick intitial review.

…mouse movement" This reverts commit dd57352.

…tealing" This reverts commit fa59c37.

… StateFFD destructor

…atic method and improve mesh rendering robustness

…ary tent generation and including null-duck safety checks.

… LayerTree

…mDeform to Point

feat: add Free-Form Deformation layer implementation

eb1c43c

gemini-code-assist Bot reviewed Mar 26, 2026

View reviewed changes

Comment thread synfig-core/src/synfig/layers/layer_freeformdeform.cpp Outdated

mohamedAdhamc marked this pull request as draft April 3, 2026 19:03

Merge remote-tracking branch 'origin/master' into feat/free_form_deform

fbaed77

ahmedfathy0-0 added 4 commits May 28, 2026 18:19

feat: implement Free-Form Deformation (FFD) tool with custom grid and…

4cd9173

… smoothness controls

feat: implement visual grid connections for free form deform layer ducks

48b2986

feat: implement grid point interpolation for FreeFormDeform layer dur…

84dc2ab

…ing grid resizing

feat: enhance Free-Form Deformation layer with source corner paramete…

4982a16

…rs and context fitting

ahmedfathy0-0 added 4 commits May 29, 2026 16:24

fix: make StateFFD_Context constructor explicit and remove dead code

7f9211b

feat: enable FFD creation for switch layers and improve bounding box …

32492af

…calculation to include paste canvas layers

feat: add reset grid functionality

b66fe8f

refactor: update default FFD group description capitalization

48020b8

ahmedfathy0-0 added 8 commits June 7, 2026 15:07

fix: clarify FFD layer requirement for Switch layers in error dialog …

72bb134

…message

feat: Intercept FFD layer menu action to activate FFD Tool

bdf5312

- When a user selects 'Free-Form Deformation' from the 'New Layer > Distortions' menu, instead of creating a raw layer without the tool context, Synfig will now seamlessly switch the active toolbox tool to the 'FFD Tool'.

feat: implement custom mesh mode triangulation for FFD layer in duckm…

3070a96

…atic

feat: apply layer transformation inverse to polygon points in FFD state

8a69e19

refactor: replace corner pin padding with an 8-point static anchor bo…

b649ec6

…undary and mesh mask

ahmedfathy0-0 changed the title ~~feat: Initial MVP for 2D Free-Form Deformation Layer~~ [GSoC'26] Initial MVP for 2D Free-Form Deformation Layer Jun 8, 2026

ahmedfathy0-0 added 2 commits June 10, 2026 20:28

fix(gui): hide FFD grid options in Custom Mesh mode and sync undo"

d2aa6f2

ahmedfathy0-0 added 4 commits July 7, 2026 14:48

refactor: simplify grid generation in FFD state and update reset butt…

5f99b00

…on label based on mesh mode

fix: clear ducks, beziers, and duck list when exiting FFD state

5c4fcb9

feat: implement interior Steiner point generation for FFD auto-mesh a…

a8bb65f

…nd rename edge length slider to mesh strength

refactor: hide mesh edge length controls

6a92220

ahmedfathy0-0 added 5 commits July 7, 2026 17:05

fix: improve duck management logic in FFD state to prevent unnecessar…

dab3cb2

…y redraws and rebuilds

fix: update FFD duck rebuild logic to handle selection changes and la…

a601fd3

…yer validation

fix: integrate nested layer transformation stacks into FreeFormDeform…

647bdce

… state and improve mesh preview consistency

refactor: implement triangle filtering logic in state_ffd to preserve…

ffa2d0f

… boundary points during triangulation

fix: correct coordinate mapping in freeform deform and adjust mesh st…

4c05515

…rength limit

refactor: replace direct point merging with edge-aware triangle clean…

6d49de2

…up in state_ffd mesh editing

mohamedAdhamc requested changes Jul 16, 2026

View reviewed changes

Revert "fix(UI): make Bezier hover detection instantly responsive to …

09931cf

…mouse movement" This reverts commit dd57352.

ahmedfathy0-0 force-pushed the feat/free_form_deform branch from 14e3a98 to 6261128 Compare July 23, 2026 13:51

ahmedfathy0-0 added 2 commits July 23, 2026 17:01

Revert "feat(UI): implement opt-in Bezier hovering to prevent hover-s…

e1e6ca8

…tealing" This reverts commit fa59c37.

refactor: reorder tool registrations and clean up duckmatic logic and…

5abd43a

… StateFFD destructor

ahmedfathy0-0 force-pushed the feat/free_form_deform branch from 6261128 to 5abd43a Compare July 23, 2026 14:02

ahmedfathy0-0 added 3 commits July 30, 2026 04:37

fix: upgrade the editing edges behavior when collapsing and clipping

b21729e

refactor: centralize FFD overlay configuration logic into a new Duckm…

fd94a7d

…atic method and improve mesh rendering robustness

refactor: improve FFD mesh expansion logic by adding contiguous bound…

a72c109

…ary tent generation and including null-duck safety checks.

ahmedfathy0-0 requested a review from mohamedAdhamc July 31, 2026 23:01

ahmedfathy0-0 added 5 commits August 6, 2026 10:51

refactor: remove automatic FFD state activation on layer selection in…

2821b3d

… LayerTree

refactor: remove redundant mesh regeneration confirmation dialog

c6cc25d

feat: add smoothness control, reset confirmation for mesh editing.

726c0dd

refactor: remove adding points in canvas in grid mode

789c26a

refactor: rename FFD grid_points parameter to control_points

ff518b1

ahmedfathy0-0 changed the title ~~[GSoC'26] Initial MVP for 2D Free-Form Deformation Layer~~ feat: [GSoC'26] Initial MVP for 2D Free-Form Deformation Layer Aug 22, 2026

refactor: update return type of get_clamped_x lambda in Layer_Freefor…

6ae0c88

…mDeform to Point

ahmedfathy0-0 marked this pull request as ready for review August 22, 2026 15:31

Uh oh!

Conversation

ahmedfathy0-0 commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What's Included:

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

zaynopenapp commented May 14, 2026

Uh oh!

codacy-production Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Up to standards ✅

Uh oh!

ahmedfathy0-0 commented May 28, 2026

Key Changes

Next Updates

Uh oh!

ahmedfathy0-0 commented Jun 1, 2026

Uh oh!

mohamedAdhamc commented Jun 4, 2026

Uh oh!

ahmedfathy0-0 commented Jun 8, 2026

Uh oh!

zaynopenapp commented Jun 10, 2026

Uh oh!

codacy-production Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Up to standards ✅

Uh oh!

ahmedfathy0-0 commented Jul 7, 2026

Summary of Last Changes

1. Automated Contour-Based Mesh Generation (Auto-Mesh)

2. Explicit Triangle Mesh Topology & Editing

3. UI/UX & Interaction Polishing

Uh oh!

mohamedAdhamc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ahmedfathy0-0 commented Mar 26, 2026 •

edited

Loading

codacy-production Bot commented May 26, 2026 •

edited

Loading

codacy-production Bot commented Jul 7, 2026 •

edited

Loading