restring-art 2.0.0

Feed in a portrait. The greedy search picks one thread at a time, and each pull moves the canvas measurably closer to the photo. The output is the picture one uncut thread draws around the nails, plus the nail-by-nail winding order. Black and white uses one thread. Color runs pick a palette: the pure RGB triple, CMY, CMYK or a JSON list of the floss colors you own.

Quick start · Usage · Tuning · Development · Contributing · License

Try it in the browser: the playground runs the same core as a wasm module. Drop a photo, no install. The page deploys from web/ (.github/workflows/pages.yml).

Overview

• For: makers winding physical boards, machine and plotter owners, and anyone who wants a digital string-art render.
• Input: a PNG or JPEG photo; face-centered portraits work best.
• Output: a PNG render of the thread pattern; the Python API also returns the continuous nail-by-nail pull order.
• Scope: greedy search on a 300 px working grid, five nail-layout families, black-and-white and color palettes, .restring project files, printable winding posters, GIF animations and a physical thread model. Building from source requires a Rust toolchain, there is no pure-Python fallback.

One run of the CLI: the same portrait at 1000 threads around 300 nails and 3000 threads around 598 nails (--rect -s 0.05).

The project started as a 2020 university course assignment by Kaspar Valk, Kert Tali and Almas Baktubayev. The project poster describes the original idea.

Features

• One uncut thread: the pull order is continuous by construction, so you wind a single thread by hand or machine.
• Real thread colors: black-on-white, white-on-black, or a palette. The built-ins are RGB, CMY and CMYK, or load a JSON list of the floss colors you own. CMYK measures 42 to 45 percent better than RGB at an equal budget.
• Custom boards: polygon, star, multi-ring and SVG-outline layouts via --layout star:5:0.55, plus non-square aspect crops (layouts guide).
• From photo to board: save a .restring project, re-render in milliseconds, print a numbered-nail poster with the thread length in meters, watch the winding as a GIF.
• Measured, not guessed: every flag has a degradation curve behind it in the tuning guide.

Quick start

Install

pip install restring-art

Wheels cover linux (x86_64, aarch64), macos (x86_64, arm64) and windows (x86_64) on CPython 3.12 and newer. No Rust toolchain needed. Building from source needs uv and Rust, see Development.

Run your first example

restring -i portrait.png -o out.png --rect -n 2 -l 3000   # best quality, ~1.4 s

Expected result:

[...] [restring.cli] [INFO]: Nails amount: 598

out.png now holds the rendered thread pattern.

Usage

Basic example

Three presets cover most jobs (timed on a 24-core Linux box):

# fast preview, ~0.3 s
restring -i portrait.png -o out.png --rect -l 300

# balanced, ~0.6 s
restring -i portrait.png -o out.png --rect -n 4 -l 2000

# maximum measured quality, ~1.4 s
restring -i portrait.png -o out.png --rect -n 2 -l 3000

CLI reference

Nails sit evenly on the perimeter. The circle starts at 9 o'clock and runs clockwise. The rectangle starts at the top left corner. The pull order is continuous by construction, so you wind one uncut thread.

Save and re-render

The project file keeps the nail layout and the pull order in plain JSON, so a result re-renders in milliseconds without a search and any tool can read the winding sequence:

restring -i portrait.png -o out.png --rect -l 2000 --project-out result.restring
restring --project result.restring -o out2.png   # byte-identical re-render

The current -s and -d apply at re-render time. Schema and compatibility promise: docs/project-format.md.

Wind it for real

Turn a result into a printable poster: numbered nails, the footer with the nail count, pull count and total thread length in meters.

restring -i portrait.png -o out.png --rect -l 2000 --project-out result.restring --poster poster.svg
restring --project result.restring --poster poster.svg --canvas-size 300

Print at 100 percent scale, hammer the nails on the board outline, wind. Printing checklist and thread buying guidance: docs/winding.md.

As a library

from restring import GenerateOptions, generate

result = generate("portrait.png", GenerateOptions(layout="rect", pulls=2000))
result.image.save_png("out.png")
print(result.stats.pulls_per_thread)

The full options table, the Result fields and the deprecated 1.x names: docs/api.md. Images travel as _core.Image objects; the pixel data stays in Rust memory, so calls pass references instead of copying arrays.

Tuning

-s is fitted for you: the run derives the export strength from the actual pull count (104/L clamped to 0.03..0.2) and lands within 2 percent of the hand-tuned optimum at the measured budgets. The working simulation darkens each pull with strength 0.05; the export accumulates with strength -s. When -s is too high for the thread count, the render reaches its target halfway, then overshoots and darkens. Manual -s values stay for special cases, see the tuning guide.

Every flag, the numbers behind the rules and the degradation curves: docs/tuning.md.

Development

git clone git@github.com:InzGIBA/ReString.git
cd ReString
uv sync

Requirements: uv and a Rust toolchain with a C linker for cargo. uv fetches Python 3.14 and compiles the core on first sync. No system C compiler (minimal WSL or container)? Use zig as the cargo linker — the recipe lives in docs/architecture.md.

Source checkouts prefix every command with uv run, for example uv run restring -i portrait.png -o out.png --rect -l 300.

Checks

uv run pytest                   # 211 tests, ~11 s
uv run ruff check .
uv run python scripts/benchmark.py --label before   # or after, then --plot
uv run python scripts/make_gallery.py               # regenerate docs/img/gallery.png

CI runs the same checks on every push to main and every pull request, on linux, macos and windows (.github/workflows/ci.yml). A v* tag builds wheels for three platforms, publishes to PyPI and opens the GitHub Release (.github/workflows/release.yml).

Documentation

Roadmap

Open experiment ideas arrive through the research-idea issue template: each states a question, a hypothesis and a pre-registered success bar. Closed questions live next to their measurements in docs/research/, so nobody re-litigates them. Answered so far:

• Re-run the RGB sweeps: working strength 0.05 adopted, 13 to 17 percent better MSE (measurement).
• Test the working grid above 300 px: keep 300, under 3 percent MSE at up to 2.4x time (measurement).

Contributing

Issues and pull requests are welcome. Templates structure both: bug reports carry the command line and image, feature requests check the measured dead ends, research ideas state a pre-registered success bar, and the PR template asks for the measurement or test evidence.

Wound a physical board? Post the photos under the "show and tell" label. Physical outputs are the best advertisement a string-art project gets. The example gallery (examples/gallery/) shows the configuration families and the commands behind every tile.

1. Describe the problem or the proposed improvement.
2. Make a focused change.
3. Add or update relevant tests and documentation.
4. Run the checks above and open a pull request.

License

MIT. See LICENSE.

Photo credits

Portrait fixtures in tests/data/ are square face-centered crops of studio photos provided for this project. The demo image above uses the portrait_female.png fixture. Earlier fixtures came from Unsplash under the Unsplash License.