Files
Lucas RayanandClaude Opus 5.5 07aaf8e1a7
CI / Trivy (dependências, segredos e configuração) (push) Successful in 1m2s
CI / Testes e imagem Docker (linux/arm64) (push) Successful in 4m24s
Release / Plano (reaproveitar a imagem?) (push) Successful in 5s
Release / ci (push) Skipped
Release / Publica a imagem (linux/arm64) (push) Successful in 18s
Release / Cria a release no Gitea (push) Successful in 4s
feat: novo site e interface; tradução Braille no navegador (1.4.0)
Interface reescrita (design próprio, tema claro/escuro, a11y WCAG 2.2 AA),
seções do site e artigo IDEIA @ CSBC 2025. Tradutor portado para JS com
paridade 100% contra o Python; sem Tailwind nem axios.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 19:51:53 -03:00

7.2 KiB

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/)

Since 1.4.0 the web interface translates and generates STL entirely in the browser (public/modules/); the Python API below remains for integrations.

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.