Lucas RayanandClaude Sonnet 5.5 a9aec5abe4
Release / Plano (reaproveitar a imagem?) (push) Successful in 8s
CI / Trivy (dependências, segredos e configuração) (push) Failing after 8s
Release / ci (push) Failing after 9s
CI / Testes e imagem Docker (linux/arm64) (push) Skipped
Release / Publica a imagem (linux/arm64) (push) Skipped
Release / Cria a release no Gitea (push) Skipped
Recover InBraille from the production image (1.3.1) and move it to Gitea
The GitHub account was suspended and the repository had no backup. The deployed code
(src/, public/, index.html, main.py, requirements.txt) was extracted from the production
image 1.3.1. The tests, Dockerfile, compose files, SECURITY.md, CHANGELOG.md and README were
rebuilt from the records of the work sessions that created them; LICENSE, .gitignore,
robots.txt and sitemap.xml were recreated. CI now runs on Gitea Actions.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-02 00:15:01 -03:00

InBraille

Introduction

This repository contains the code for the InBraille project.

InBraille is an innovative Brazilian tool from Pernambuco that converts texts to Braille and exports them in both ASCII format and in STL plates for 3D printing. With this solution, it is possible to increase accessibility and inclusion, allowing anyone to create tactile materials for people with visual impairments.

In addition to being an accessible and easy-to-use technology, this project has a significant social impact, enabling the production of texts, labels, informational signs and educational materials in Braille in an accessible and personalized way. Whether for educational, professional or everyday purposes, this tool aims to make information truly universal. The goal is to democratize access to Braille through maker culture and 3D printing, providing autonomy and independence to those who need it.

Supported Braille Alphabets:

  • Brazilian Braille (with native warning regarding ambiguous characters)
  • North American Braille
  • Chinese (Mandarin) Braille (supporting Pinyin and Chinese characters input, with localized input assistance)

Key Features

  1. Unified HTML Template: Single, consolidated index.html structure served for all routes.
  2. Dynamic Client-Side Localization (i18n): Fully translates the interface dynamically without page reloads across Portuguese, English, and Chinese.
  3. Modular Frontend (SOLID Principles): Deconstructed frontend architecture divided into clean, single-responsibility ES Modules:
    • state.js: Centralized application state tracking.
    • i18n.js: Localized DOM translations and menu management.
    • ui.js: Reusable visual components (toasts, focus highlights).
    • converter.js: Conversion flows and line-length validators.
    • stl.js: 3D parameters control and STL file compiler.
    • index.js: Orchestrator entry point.
  4. Standardized Premium UI Warnings: Consistent, modern side-border alert cards for warnings and tips.

Backend Architecture (src/)

The Python backend is organized into domain-driven subdirectories under src/, utilizing FastAPI for web routing and VTK (Visualization Toolkit) for 3D modeling:

1. Domain Model (src/domain/)

Core representations and mathematical constants of the Braille system:

  • alphabets.py: Mappings for Brazilian and North American character-to-cell associations.
  • chinese_braille.py: Constants and lists representing tones, initial and final syllables, and punctuation for Chinese Braille.
  • braille_codes.py: Converts characters to 6-dot/8-dot binary matrices and Unicode Braille patterns.
  • dimensions.py: Defines dimensions of Braille cells (dot radius, height, horizontal and vertical spacing).

2. Translation Engine (src/translation/)

Core encoders/decoders translating between text and Unicode Braille:

  • translator.py: Router that delegates request conversion depending on selected alphabet.
  • encoder.py / decoder.py: Translate between standard characters/Hanzi/Pinyin and Braille Unicode cells (PT/EN/ZH). The Chinese translation parses Chinese Hanzi or pinyin using pypinyin to analyze polyphonic contexts, compiling them into syllables (initial + final + tone combinations) according to official Chinese Braille rules.

3. 3D Modeling and Mesh Engine (src/modeling/)

Decoupled geometry generation and composition system:

  • mesh_engine.py: Defines the abstract MeshEngine wrapper interface, decoupling layout modeling logic from the underlying 3D graphics library.
  • model_builder.py: Composites the physical shapes. Places plate bases, rounded borders, spherical dot caps, orientation markers, and orientation bars (in "dots only" mode).
  • options.py: Defines settings configuration (symbols per line, plate thickness, resolution).
  • stl_service.py: Standardizes generation inputs and exports binary STL models.

4. 3D Rendering & Serializer (src/rendering/)

Concrete implementation of the graphics pipeline:

  • vtk_mesh_engine.py: VTK-based implementation of MeshEngine drawing cubes, spheres, cylinders, and sphere-cap clips.
  • vtk_stl_serializer.py: Serializes VTK PolyData objects into raw binary STL file format.

5. Web API Layers (src/web/)

Web service routing and schemas:

  • app.py: Initiates the FastAPI application instance.
  • api_routes.py: Implements REST API controllers (/api/encode, /api/decode, /api/to-stl).
  • schemas.py: Pydantic request body schemas.
  • page_routes.py: Serves static assets and maps /, /en, and /zh requests dynamically to serve the root index.html template.

Running the code

Tagged releases are published to the Gitea container registry (linux/arm64):

docker run -d -p 3000:3000 --read-only --tmpfs /tmp --cap-drop ALL git.lucasrguerra.dev.br/lucasrguerra/inbraille:latest

Pin a version (for example :1.0.0) in production. The service will be available at http://localhost:3000.

From source

Requires Python 3.14.

python -m venv .venv
source .venv/bin/activate        # Windows (PowerShell): .\.venv\Scripts\Activate.ps1
pip install -r requirements-dev.txt
python main.py
pytest                           # run the test suite

The API has the following endpoints:

  • /api/encode: Translates a text to braille.
  • /api/decode: Translates a braille to text.
  • /api/to-stl: Exports the braille text to plate in STL format.

Requests are validated and rate limited; see SECURITY.md for the limits and for how to report a vulnerability.

Releases

The code, the container image and the releases live on Gitea. CI (.gitea/workflows) runs on the Gitea runners:

  • ci.yml (branches and every Monday): Trivy on the repository, the pytest suite inside the Dockerfile test stage, the arm64 image build, Trivy on the image and a smoke test (scripts/smoke-imagem.sh: pages, robots.txt and sitemap.xml, the encode/decode/STL API, security headers, read-only non-root container).
  • release.yml (main and vX.Y.Z tags): if the registry already holds the image for the same content (inputs-<hash>), nothing is rebuilt and only the new tags are applied. On a tag it creates the Gitea release with the CHANGELOG notes.

Image tags: latest, X.Y.Z, X.Y and sha-<commit>. To release: update the CHANGELOG, commit, then git tag vX.Y.Z && git push gitea vX.Y.Z.


Listed on SkipTheCAD

License and Credits

InBraille is released under the MIT License. Anyone may use, modify and sell prints made with it.

Built with FastAPI, VTK and pypinyin. The Braille glyphs use the Noto Sans Symbols 2 font (SIL Open Font License).

Developed by Lucas Rayan Guerra at Ciência Embarcada. Source: https://git.lucasrguerra.dev.br/lucasrguerra/inbraille.

S
Description
Conversor de texto para Braille com exportação de placas em STL para impressão 3D
Readme MIT
729 KiB
0 Stars 1 Watchers 0 Forks
2026-11-15 22:59:24 +00:00
Languages
JavaScript 43.6%
Python 22.2%
HTML 16.6%
CSS 14.8%
Shell 2%
Other 0.8%