cardbleed

Extends the borders of card scans so a printed and cut card doesn't end up with a border that is too thin. The extension continues whatever border the card already has (holofoil speckle, solid colors, gradients), and the original image data is never re-encoded: PNG and WebP pixels stay bit-identical, and JPEGs are extended by splicing DCT coefficient blocks around the untouched originals.

input, 400×550

output, cardbleed demo_card.png -e 24

The demo card is generated by a script (examples/make_demo.py), so the repository contains no copyrighted scans. It has the traits that make real scans annoying: a speckled border, a brightness gradient across it, a scanner-bloom line at the very edge, and an inner frame line. Bloom is trimmed and the frame line is detected automatically, so sampling never crosses into it.

Install

uv tool install cardbleed        # or: pipx install cardbleed
uvx cardbleed card.png           # or run once without installing

Until the first PyPI release, install from GitHub instead: uv tool install git+https://github.com/ErikBavenstrand/cardbleed

Usage

cardbleed card.png --compare              # extend 16px, write a comparison sheet
cardbleed ./cards/ -e 2.5mm --recursive   # batch a folder, mm-based sizing
cardbleed card.jpg -e 20 --fix-aspect     # pad to the 63x88 ratio, then extend
cardbleed card.png --target 69x94mm       # pad to an exact final size

Outputs are written next to the input (or to --out-dir) with an _ext suffix. Inputs are never overwritten. --compare also writes a side-by-side sheet with the original boundary marked, which makes it easy to check the seam.

Modes

Zoomed left-edge detail, one panel per setting: smart, pattern, naive, mirror, soft.

• --mode pattern (default) keeps structure intact: every output line is a real contiguous border line, and each outward pass is shifted along the edge by a random offset. If the border has a repeating pattern, detected by autocorrelation, the continuation and the offsets snap to its period so the pattern stays in phase. With --shuffle 0 it degrades to a plain deterministic mirror.
• --mode smart resamples the border band stochastically. Speckle is re-randomized in both directions, so nothing streaks or repeats, at the cost of some texture structure.
• --mode naive replicates the outermost line straight outward (plus noise and smudge). Mostly useful as a baseline; it streaks on textured borders.

The gallery variants above, for reference:

--mode smart

--mode naive

--smudge 2.5 --noise 0.8

--compare sheet

Format handling

For JPEG the extension amounts have to align to the MCU grid (8 or 16 px). The remainder is shifted between opposite edges, so the final dimensions are still exactly what you asked for.

Options

cardbleed --help has the full reference. The ones worth knowing:

How it works

Each edge is analyzed on the original image: bloom lines are trimmed and the sampling band is clamped before inner border structure. The border is split into a smooth tone component, which is continued outward mirrored so gradients stay seam-continuous, and a texture residual, which is resampled according to the selected mode. Noise matched to the border's measured grain and a ramped blur are applied on top. Corners are filled in two passes so they inherit synthesized side texture. All randomness ramps in from zero at the seam, so the first synthesized line is an exact continuation of the edge.

If a card already has rounded corners, the corner triangles are transparent (or black/empty) in the scan. --edge-fill (on by default) detects those rows per edge and continues the nearest real border across them, so the added bleed is border colour rather than a grown black/transparent corner. It's a no-op on edges with no such background, and stands down when an edge is mostly empty (nothing to continue). Original pixels are still left untouched — only the synthesized bleed is affected.

Development

git clone https://github.com/ErikBavenstrand/cardbleed && cd cardbleed
uv run cardbleed --selfcheck            # assertion suite (fixtures)
uv run cardbleed --selfcheck scan.png   # plus checks against a real scan
uv run --group dev ruff check src
uv run --group dev pyright

Module layout: synthesis.py (edge analysis and border synthesis), formats.py (format-preserving I/O, including the JPEG DCT path), sizing.py (px/mm/target/aspect math), process.py (per-file pipeline), cli.py, selfcheck.py.

License

MIT