beadrelief README

The project's README from github.com/pgp00/beadrelief. As one markdown file: README.md.

BeadRelief heart

BeadRelief

Image in. Editable beads out.

Turn any image into an editable bead pattern or a multicolor 3MF relief — entirely in your browser.

Try the live demo → · Download the sample 3MF · 简体中文

Build and verification

BeadRelief workflow: load an image, edit the bead pattern, and preview the 3D relief

Desktop-first · Use a viewport at least 980 px wide for the complete workspace.

Why BeadRelief?

🔒 Local by design 🧩 Printable bead charts 🖨️ Bambu-ready 3MF
Images and generated files stay in your browser. Use the full MARD palette and export PNG/PDF patterns. Project-filament colors and part assignments are included.

Three-minute quick start

  1. Open the live demo and choose Bead pattern or 3D print.
  2. Select Try the sample or upload a JPG, PNG, or WebP image.
  3. Adjust the size, color limit, crop, and background; then edit cells with the palette and drawing tools.
  4. Export a PNG/PDF pattern, usage workbook, edit-record JSON, or a 3MF in 3D print mode.

The Help button in the app keeps this workflow, keyboard controls, FAQ, and browser support in one place.

Choose an output

The live demo has two explicit workflows that share the same editable canvas:

Open the live demo, choose Bead pattern or 3D print, then upload a JPG, PNG, or WebP image.

From image to print, without guesswork

1 · Frame 2 · Build 3 · Inspect 4 · Calibrate
Crop, zoom, reposition, and clean the background. Choose solid or layered color and add a border, detachable backplate, hanging loop, or recessed back text. Scrub through print layers, isolate a layer, or explode the stack; the same mesh is used for preview and export. Print the generated swatch, enter measured colors, then save the printer/nozzle/material profile for reuse.

Every project JSON, layered workbook, and 3MF carries the bottom-to-top print recipe. The 3MF also embeds the selected nozzle and material assignments.

The usage panel can safely merge isolated color speckles in one undoable pass. Layered calibration is tied to the physical filament order, TD, printer, nozzle, and layer height; changing those inputs automatically retires stale measurements.

Open it in Bambu Studio

  1. Import the exported .3mf.
  2. Select the Bambu Lab P2S and 0.4 mm nozzle.
  3. Review the included project-filament colors and part assignments, map them to the physical AMS slots, then slice and inspect the color preview.

For layered work, open Material profile → Layered color calibration, download the calibration 3MF, print it with the same printer/nozzle/filaments, and enter the measured swatch colors before marking the profile as physically verified.

[!IMPORTANT] The checked-in heart file has not yet been physically printed. Always confirm the AMS mapping and slice preview before printing.

Try the heart sample

Follow the full editable-project path with the same tiny heart:

Source Edit Print
PNG Project JSON Grouped 3MF

Canvas shortcuts

Input Action
Arrow keys Move the keyboard cursor
Space or Enter Draw at the cursor
Delete or Backspace Clear the cursor cell
Hold Space and drag Temporarily pan the canvas
Mouse wheel Zoom the canvas
Right-click drag Pan or erase, based on the right-click setting

Browser support

Releases are verified in current Chromium. The supported setup is the latest Chrome or Edge with a desktop viewport at least 980 px wide; WebGL is required for the 3D preview. Firefox and Safari are not yet part of the supported release contract.

FAQ

Are my images uploaded?

No. Image conversion and exports run locally in your browser.

How should I back up a project?

The current draft is stored in this browser. Export the edit-record JSON for any project you need to keep or move to another device.

Why is 3MF export unavailable?

Switch to 3D print, keep the canvas at 32 × 32 cells or smaller, and resolve any print-setting validation message before exporting.

Run locally

Requires Node.js 22.9 or newer.

npm ci
npm run check
npm run dev

Open http://127.0.0.1:5174/.

Verification status

CI regenerates the checked-in samples, tests every 3MF archive, and verifies the embedded project-filament colors and part assignments. Exact hashes and the compatibility record are in Bambu Studio verification.

Known limits
  • Solid mode exports one grouped relief. Layered mode is experimental, uses one global bottom-to-top filament order, and is not Bambu Studio Mixed Filament metadata.
  • 3D print mode uses up to four materials; those AMS and 3MF limits do not apply to bead-pattern mode.
  • 3MF export is limited to 32 × 32 cells.
  • Confirm the physical AMS slot mapping in Bambu Studio before printing.
Privacy

Image processing and generated files stay in the browser; the app does not upload them to a server. The current editable draft may remain in browser local storage until it is replaced or cleared.

Upstream and license

BeadRelief is based on the MIT-licensed Jett-Wu/Perler_Beads_Generator. See UPSTREAM.md for the imported commit and project-specific changes. This repository is released under the MIT License.

If BeadRelief helped you make something, a GitHub star helps other makers find it. Contributions are welcome — see CONTRIBUTING.md.

beadrelief (pgp00/beadrelief)

Searching Database…

488 ·GitHub
Beadrelief
What is this?BeadRelief turns any image into an editable bead pattern (like Perler beads) or a multicolor 3MF relief for 3D printing, entirely inside your browser.
Is this a desktop app I install, or something I use in the browser?It is a browser-based web app — you open the live demo page and work there; running it locally only requires a small Node.js dev server, no install for normal use.
How do I turn a photo into a bead pattern or 3D relief?Open the live demo, choose Bead pattern or 3D print, upload a JPG/PNG/WebP image, adjust size/color limit/crop, edit cells with the tools, then export a PNG/PDF pattern or a 3MF file.
Do I need anything besides a browser?Just a desktop browser with WebGL; the latest Chrome or Edge is the supported setup. Running the project from source instead requires Node.js 22.9 or newer.
Any catches before I send a design to print?3MF export is capped at 32×32 cells, layered multi-color mode is experimental and uses one global filament order (not Bambu Studio Mixed Filament metadata), and Firefox/Safari are not yet officially supported.
Does it work on mobile or in Firefox?No — it's desktop-first, needs a viewport of at least 980px for the full workspace, and only current Chromium browsers (Chrome/Edge) are verified; Firefox and Safari aren't part of the supported release yet.
Does my uploaded image ever leave my computer?No, all image processing and file generation happens locally in the browser; nothing is uploaded to a server, though the current draft may sit in browser local storage until exported or cleared.
What is the MARD palette used for bead patterns?It is the color palette system (Basic/Complete MARD) built into Bead pattern mode, offering up to 291 bead colors with PNG/PDF/XLSX usage-workbook and JSON exports.
How does the 3MF file work with Bambu Studio?The exported 3MF embeds project-filament colors and part assignments so you can map them to physical AMS slots; the workflow is verified with a Bambu Lab P2S printer and 0.4mm nozzle.
What is BeadRelief built on?It is based on the MIT-licensed Jett-Wu/PerlerBeadsGenerator project, with BeadRelief adding the 3D-print and multicolor 3MF relief workflow on top.
How many colors can a 3D-printed relief actually use?3D print mode is limited to up to four AMS filament colors per model, while bead-pattern mode can use the full 291-color palette since it isn't bound by AMS limits.
What are similar projects?openreel-video, omni-tools, floorplan-3d, bead-grid-studio, bible-strong-avatar-lab, human-atlas, neonplan3d, img2threejs
Which topics is it in?image-to-3d, generator, 3d-printing, xlsx, threejs, 3d, image-processing, json, pdf, local-first, web-app, react
Creator
pgp00
Size
12.8 MB
Stars
488
Updated
CommitOct 06Releasev0.2.0Aug 30
Age
1mo
Commits · 90 Days