Seam Carving

Manual on MediaWiki Tools

Toolforge Seam Carving Release status: beta
Description	An interactive, high-performance web tool for content-aware image resizing (seam carving), with brush-based protection/removal constraints and a dual client-side JavaScript / C++ execution model.
Author(s)	Francesco Tosoni (Super nablatalk)
Latest version	1.0.0 (2026)
License	Apache License v2.0
Download	GitHub repo README.md changelog
Example	https://seam-carving.toolforge.org/

Toolforge Seam Carving (seam-carving) is an open-source, interactive web tool that performs seam carving (content-aware image resizing): an algorithm that resizes images by removing or inserting the lowest-energy "seams" of pixels, so that structurally important content (faces, text, objects) is preserved while less important regions are shrunk or stretched. Unlike naive scaling or cropping, seam carving can change an image's aspect ratio while keeping its salient subjects intact.

The tool is built for the Wikimedia Toolforge ecosystem. It is intended to help editors prepare Commons media for re-use (e.g., adapting an image to a different aspect ratio for an infobox or gallery) without distorting or cropping out important content.

Try it out: https://seam-carving.toolforge.org/

Implementation

The tool offers two interchangeable resizing engines sharing the same seam-carving algorithm, so a user can pick the trade-off between latency and image size that suits their browser/device:

• Client-side JavaScript engine: Runs entirely in the browser (js/main.js). Recommended for fast, interactive resizing of small/medium images, since no upload or server round-trip is required.
• Server-side C++ backend: A multi-threaded, OpenMP-parallelised C++ implementation (maintained as the seam-carving Git submodule), compiled with CMake and invoked by the web server for larger or more demanding jobs.

• Energy function: Determines which pixels are "least important" and therefore first to be removed.
  • Backward Energy – the classic gradient-based formula (Sobel filters) from Avidan & Shamir's original 2007 seam-carving paper.
  • Forward Energy – Rubinstein et al.'s 2008 formula, which minimises the energy/distortion introduced into the image by each removed seam, rather than only the energy removed.
• Constraint brush painting: Users can paint directly on the image to bias the energy map before carving:
  • 🟢 Protect – assigns a positive energy weight, preventing the painted region from being carved.
  • 🔴 Remove – assigns a negative energy weight, forcing the painted region to be carved out first (object removal).
  • A local-reset tool clears constraints in a selected area.
• Interactive visualiser: Animates the carving process seam-by-seam and highlights the currently active seam in real time, so users can see which content is being removed before committing to the result.
• Resize modes: Target width, target height, or both, applied as a sequence of horizontal and/or vertical seam removals/insertions.
• REST API: A FastAPI backend exposes a POST /api/carve endpoint (with an optional protection/removal mask upload) that streams newline-delimited JSON progress events back to the client while the C++ binary runs, and returns the final image base64-encoded on completion. Auto-generated Swagger documentation is available at /docs.
• Localisation: The UI is translated into 17 languages, with a focus on Indian languages.
• Supported formats: Standard raster formats such as JPEG and PNG.

Demos

The public instance at https://seam-carving.toolforge.org/ lets any user upload an image, choose a target size and energy formula, optionally paint protection/removal constraints, and watch the seam-carving process animate before downloading the resized result.

Administration

The tool is self-hosted on Wikimedia Toolforge and deployed via Cloud Native Buildpacks (CNB) and the Toolforge Build Service:

1. The project.toml manifest declares the apt dependencies needed to compile the C++ backend (cmake, g++, make, build-essential, libc6-dev).
2. On startup, start.sh patches the buildpack's linker paths and compiles the seam-carving C++ submodule with CMake if a prebuilt binary is not already present.
3. The Procfile starts the FastAPI app (app.py) under Uvicorn as the tool's web process.

To redeploy from a Toolforge bastion:

become seam-carving
toolforge webservice buildservice stop --mount=all
toolforge build clean -y
toolforge build start https://github.com/ftosoni/toolforge-seam-carving
toolforge webservice buildservice start --mount=all
toolforge webservice logs -f

No special hardware is required; the C++ backend benefits from multiple CPU cores (OpenMP) but does not require a GPU.

Source

The source code of the web application is hosted on GitHub and released under the Apache License 2.0. The core carving algorithm is maintained as a separate submodule, also under the Apache License 2.0, and includes its own C++ unit test suite. The main repository includes:

• The client-side JavaScript implementation of the algorithm and UI event handling.
• The Codex-compatible CSS styling for the web interface.
• The FastAPI REST wrapper around the C++ binary, with streaming progress support.
• Localisation files for 17 languages.
• Toolforge-specific deployment configuration (project.toml, Procfile, start.sh).

Bugs and feature requests should be filed in the GitHub issue tracker.

See also

• Avidan, Shai; Shamir, Ariel (2007). "Seam Carving for Content-Aware Image Resizing". ACM Transactions on Graphics (Proceedings of SIGGRAPH 2007).
• Rubinstein, Michael; Shamir, Ariel; Avidan, Shai (2008). "Improved Seam Carving for Video Retargeting". ACM Transactions on Graphics (Proceedings of SIGGRAPH 2008).