Skip to content

Unify background and interpolation handling for mapim transformations - #216

Merged
kipcole9 merged 1 commit into
elixir-image:mainfrom
hlindset:feat/mapim-transform-options
Jul 24, 2026
Merged

Unify background and interpolation handling for mapim transformations#216
kipcole9 merged 1 commit into
elixir-image:mainfrom
hlindset:feat/mapim-transform-options

Conversation

@hlindset

Copy link
Copy Markdown
Collaborator

mapim-based transformations now handle transparent and semi-transparent backgrounds consistently through shared option validation and conditional alpha premultiplication.

  • ripple: added :background and :interpolate options
  • to_polar_coordinates: added :background and :interpolate options
  • to_rectangular_coordinates: added :interpolate option, and hard-coded extend: :VIPS_EXTEND_COPY. Boundary samples will now be clamped to source edge color instead of blending towards the zero-fill
  • distort: added :background, :interpolate (default is still :bicubic as before), and :extend_mode options (:background and :copy accepted)
  • warp_perspective: now preserves image alpha and reproduces non-opaque backgrounds correctly, added :interpolate option
  • straighten_perspective: now preserves image alpha and reproduces non-opaque backgrounds correctly, added :interpolate option
  • map: now reproduces non-opaque backgrounds correctly, added :interpolate option

The :interpolate option defaults to :bilinear, except for distort, which retains its existing :bicubic default.

For transformations that accept :background, the default (when omitted or nil) is libvips' all-zero fill: black for images without alpha, transparent for images with alpha.

The existing premultiplication handling was extracted into a shared helper, and all affected operations are now routed through a shared mapim helper which applies explicit premultiplication when required.

I also removed the following doc note from to_rectangular_coordinates because the roundtrip resamples the image twice, so some accuracy loss is expected, and forcing :extend to :VIPS_EXTEND_COPY also removes the background-bleed artifacts.

  ## Notes
  Roundtrip to polar and back to rectangular
  coordinates displays some image distortion,
  likely due to rounding errors in float
  arithmetic. Further study is required.

Breaking changes:

  • warp_perspective, straighten_perspective now preserve alpha instead of always flattening, so output band count and pixels may change.
  • map now defaults to transparent black (all-zero) for exposed pixels in images with alpha (previously opaque black)
  • to_rectangular_coordinates now clamps boundary samples to the source edge (extend: :VIPS_EXTEND_COPY)
  • Image.Options.WarpPerspective was removed and replaced by Image.Options.Mapim, so direct references to the old module no longer compile.

@kipcole9

Copy link
Copy Markdown
Collaborator

Wow, such amazing work, thank you very much! I'm travelling at the moment but will review and aim to merge by the end of the weekend.

@kipcole9
kipcole9 merged commit 8fade60 into elixir-image:main Jul 24, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants