brl2stl

Turn braille into plastic. brl2stl converts BRF braille files — or plain text — into 3D-printable STL/3MF models: signs, labels, flashcards, book pages, even paper-embossing jigs. Cross-platform, zero required dependencies, with a desktop app, a CLI, and a web UI.

⠨⠃⠗⠇⠆⠎⠞⠇   →   ▄▄▖▄▄▄▖▄   →   🖨️

Quick start

Pick whichever is easiest for you:

Desktop app (easiest)

# grab brl2stl-gui.exe / brl2stl-gui.dmg from the Releases page - no
# install needed. Or run from source:
git clone https://github.com/leavesofgrass/brl2stl
cd brl2stl
pip install .[gui]
brl2stl gui

(brl2stl is not on PyPI yet - install from a clone or use a release binary.)

Type your text (or drop a .brf file on the window), watch the live preview, press Export model, slice, print. Standalone apps that need no Python at all build with PyInstaller: scripts/build-exe.ps1 (Windows exe, liblouis bundled from the official win64 release), scripts/build-macos.sh (macOS .app + .dmg, liblouis bundled from Homebrew), scripts/build-exe.sh (Linux binary; liblouis via your package manager). A GitHub Actions workflow (.github/workflows/build.yml) tests on all three OSes and builds smoke-verified Windows + macOS artifacts, attaching both to a release on every v* tag.

Command line

git clone https://github.com/leavesofgrass/brl2stl && cd brl2stl
pip install .
brl2stl document.brf                      # one STL per page
brl2stl --text "Room 12" -o sign.stl      # quick label
brl2stl document.brf --info               # sizes only, writes nothing

Docker (nothing to install but Docker)

docker build -t brl2stl .
docker compose up                         # web UI at http://localhost:8080
./scripts/brl2stl.sh document.brf         # CLI (Windows: scripts\brl2stl.cmd)

Text input defaults to contracted UEB Grade 2 whenever liblouis is installed — it always is in the Docker image — and falls back to the built-in uncontracted Grade 1 translator (with a warning) otherwise. Dimensions default to the ADA 703.3 signage standard.

Documentation

Step-by-step guides live in docs/: getting started, the desktop app, the CLI reference, Docker & web UI, input formats & translation, the printing guide, the emboss jig guide, building the standalone app, and the developer guide.

Options

8-dot (computer) braille is supported via Unicode braille input (U+2800–U+28FF); dots 7/8 get a fourth row automatically.

Printing tips

• Layer height 0.1–0.15 mm — dots are only ~0.8 mm tall.
• A 0.4 mm nozzle works; 0.25 mm renders domes noticeably better.
• Print dots facing up, no supports needed.
• PETG and PLA both work; PETG wears better for heavy use.
• If dots feel faint, raise --dot-height to 0.9 mm — plastic reads best slightly taller than the paper-embossing standards.

What's a BRF file?

The exchange format of braille embossers: plain ASCII where each character is one braille cell (Braille ASCII / NABCC), form-feed between pages. The content is already translated braille — usually contracted Grade 2 — which brl2stl renders verbatim. Get BRFs from your transcriber, NLS BARD, or make your own from text with liblouis.

Development

git clone https://github.com/leavesofgrass/brl2stl && cd brl2stl
PYTHONPATH=src python -m unittest discover -s tests   # zero-dep test suite

The mesh generator is pure stdlib Python. Every generated solid is verified watertight (each edge shared by exactly two opposite-wound triangles) by the test suite, and the Docker build fails if any test fails. See docs/PLAN.md for architecture.

License

MIT. Copyright (c) 2026 Jon Pielaet. See LICENSE.

Qt note: the desktop app uses PySide6 (LGPLv3), which permits MIT apps — the official binaries bundle Qt's shared libraries unmodified per the LGPL. If you build with the optional PyQt6 fallback instead, PyQt6's GPLv3 governs distribution of that combination. The bundled liblouis is LGPL-2.1+ and is invoked as a separate program.