SeamOp

seamop is a Python library and command-line tool for content-aware image resizing. It shrinks images by removing connected paths of low-energy pixels instead of scaling every pixel or cropping a fixed region.

Original (1428 × 968)	Resized (1000 × 900)

The current beta supports shrinking by seam removal. Enlargement and seam insertion are not implemented.

Installation

Install from PyPI:

python -m pip install seamop

For development, use the locked uv environment:

uv sync --extra dev --frozen

Compatible wheels include the compiled Rust engine. Installing from a source distribution requires a Rust toolchain to build that engine.

Command line

Resize the smaller example to 400 by 240 pixels:

seamop resize examples/medium.jpg 400 240

This writes medium_resized_400x240.jpg in the current directory. Use --output to choose another path. Existing image outputs are not overwritten.

Preview the pixels that the same resize would remove:

seamop highlight examples/medium.jpg 400 240

Remove ten vertical seams:

seamop remove examples/medium.jpg --direction vertical --count 10

The default backward strategy uses gradient energy. Select pure forward energy with --strategy forward; do not combine it with --energy.

Other commands and options are available through the built-in help:

seamop --help
seamop resize --help
seamop remove --help
seamop highlight --help

CLI dimensions use WIDTH HEIGHT.

Python

resize() accepts a filesystem path, Pillow image, RGB uint8 NumPy array, or nested RGB integer list. It returns a new RGB uint8 NumPy array without mutating the input.

from PIL import Image
import seamop

result = seamop.resize(
    "examples/medium.jpg",
    width=400,
    height=240,
)

Image.fromarray(result).save("medium_resized_400x240.jpg")

Use plan() when the carved result and preview must use the same seam decisions:

resize_plan = seamop.plan(
    "examples/medium.jpg",
    width=400,
    height=240,
)

preview = resize_plan.preview()
result = resize_plan.result()

Both output methods return independent arrays. Calling either method does not change the plan.

The default strategy is backward seam carving with GradientEnergy. The forward strategy can be selected explicitly:

from seamop import CarvingStrategy

result = seamop.resize(
    "examples/medium.jpg",
    width=400,
    height=240,
    strategy=CarvingStrategy.FORWARD,
)

Backward carving also accepts built-in or custom energy callables through energy=. Pure forward carving does not accept an energy callable.

The default gradient path and forward strategy run through the compiled Rust engine. Sobel, Laplacian, and custom energy callables remain on the Python path.

See the Python API guide for input rules, custom energy methods, errors, and the advanced seam-calculation interface.

Documentation

• Python API
• Algorithm overview
• Architecture
• Design decisions
• Benchmarking

Development

Run the repository checks from the project root:

uv run --frozen ruff check src tests benchmarks
uv run --frozen ruff format --check src tests benchmarks
uv run --frozen mypy
uv run --frozen pytest --cov
uv run --frozen pytest --doctest-modules src/seamop

Benchmarks run separately:

uv run --frozen pytest benchmarks

Limitations

• Only shrinking is supported.
• Width is reduced before height when both dimensions change.
• Results depend on the image and selected carving strategy and energy method.
• Large reductions can distort important content.

License

MIT