⌬ Yantra4D: The Hyperobjects Commons
Manifest-driven parametric design for the decentralized manufacturing age.
Yantra4D is not just a CAD tool; it is a Poly-Kernel Engine, a Continuous SDF Geometry Compiler, and a thriving Hyperobjects Commons. It bridges the mathematical precision of programmatic CAD with the accessibility of a visual, web-native storefront — integrating material metadata into the geometry pipeline, with interactive Digital Twin simulation in progress (see "Current status" below: parts of the simulation stack are heuristic or mocked today).
🛰️ The Vision: Hyperobjects & CDG
We are building the Hyperobjects Commons — a repository of "Bounded 4D Hyperobjects" designed for interoperability. By leveraging Common Denominator Geometry (CDG) interfaces (standardized snaps, threads, and joints), projects in the Yantra4D ecosystem can physically and mathematically interface with one another natively.
📼 Cartridge-Like Architecture
Every project in Yantra4D is a self-contained "Cartridge".
- The Manifest: A
project.json file serves as the single source of truth, defining parameters, modes, and parts.
- Poly-Kernel: four kernels — high-performance OpenSCAD (CSG) for browser-side WASM reactivity, mathematically exact CadQuery (B-Rep) for engineering-grade STEP exports, a native Implicit SDF engine for lattices, and a node-graph engine that compiles graphs to sandboxed CadQuery.
- Portability: Drop a project folder into
projects/ and the platform instantly white-labels the UI to serve it.
🧠 Material Hyperobjects & Hyperawareness
Geometry is meaningless without material context. The Yantra4D Commons pioneers the integration of Material Hyperobjects—metadata modules (/materials/) capturing the Topological Data Analysis (TDA), spatial compensations, and semantic ontologies of physical AM substrates. By feeding this nanoscale intelligence directly into the geometric compiler, our additively manufacturable hyperobjects are imbued with "hyperawareness", actively warping and adapting their dimensions to survive physical reality.
🌡️ Interactive Digital Twin (4D Simulation) — partially implemented / roadmap
The vision: apply simulated energy to any hyperobject and watch the continuous SDF morph in real-time as it crosses material phase boundaries (glass transition, yield, melt).
What is real today: the Studio energy slider (simulated_energy) drives a thermodynamic-collapse heuristic in the implicit SDF engine (sag past glass-transition temperature), and a render whose browser estimate exceeds the device's budget is placed on the server by apps/studio/src/services/engine/renderPlacement.ts — one rule in the placement table below, not a "circuit breaker" bolted onto renderService.ts.
What is estimated or unavailable today: no physics solver ships with this repo. POST /api/projects/:slug/simulate/physics answers 501 physics_solver_unavailable and creates no job until a solver backend is registered with configure_physics_solver (apps/api/tasks/simulation_tasks.py). The stress endpoint returns a labeled geometry-derived estimate (method: "geometry_proxy", approximation: true), not a structural solve, and the optimize endpoint is a deterministic heuristic (method: "heuristic", approximation: true). Real PPF/FEM execution on GPU nodes is roadmap. See the Current status section.
Render caches are scoped to published renderer builds; see release cache identity for invalidation, missing-identity behavior and remaining limits.
Native renderer output and cancellation explains pipe draining, per-request process ownership, deadlines and remaining isolation limits.
Mode-specific controls documents the commons-owned visibility contract and actual-pin fastener regression.
Native dropdown values retain the declared numeric or string option type; direct CLI comparisons must also match the platform checkbox encoding.
Viewer resource ownership documents the separate 32 MiB/16-entry artifact and assembly caches, per-consumer geometry, GLTF and animated-grid cleanup, and the limits of these budgets.
Publication source acceptance describes the exact-main CI gate, stale-source pin refusal and runtime verification boundary.
🛠️ The Stack
- CAD Engines: Four-kernel execution via OpenSCAD (CSG), CadQuery (B-Rep), a native Implicit SDF Engine (TPMS/Lattice), and a Graph Engine that transpiles
.graph.json node graphs into sandboxed CadQuery (see authoring guide).
- The Studio: React 19 + Three.js + Manifold-3d for blisteringly fast volumetric browser rendering.
- The API: Python Flask backend with Docker-orchestrated render clusters and slicer-grade physics estimation.
- The Knowledge Base: 4D Docs source — Astro Starlight; the public docs site is not deployed yet (see "Deep Documentation" below).
✅ Current status (2026-09-02)
Honest, code-verified snapshot. Working today:
- Interactive 3D preview — Studio (React 19 + Three.js) renders projects live with parameter controls.
- Browser-first rendering — the visitor's browser is the default placement: the OpenSCAD WASM worker renders there, free for us and unmetered for them, and the server's native OpenSCAD/CadQuery is the only metered path. Which one runs is decided by
decideRenderPlacement(), a pure 11-rule precedence function: four HARD server rules first (a cadquery/graph/implicit mode, manifest render.server_only, an unusable wasm bundle, and any export_format but stl — the browser kernel writes one /output.stl and has no converter), then the ?render= override, the visitor's preference, the measured device tier, this session's browser failures, the estimate budget, the legacy force_backend soft hint, and finally the browser. A soft server decision flips back to the browser when the API is unreachable; a hard one does not. Full table: docs/guides/wasm-mode.md.
- STL / mesh export — server render pipeline produces STL/GLB/3MF artifacts.
- Geometry verification — dedicated verify endpoint (
apps/api/routes/engine/verify.py); the parity check CI runs is tests/scripts/geometric_regression.py (the test-geometric-parity job). scripts/qa/verify_parity.py is a local dual-engine comparison tool, not a CI lane: it reports 18 of 28 comparable mode pairs passing after #115 pinned the ten parity-fixed cartridges, so the dual-engine parity claim is an intent rather than an enforced invariant — see docs/architecture/dual-engine.md.
- Cartridge project system —
project.json manifests, 512-cartridge CadQuery-first Commons catalog (including curated art/misc projects), admin app, Janua-authenticated admin flows.
- Implicit SDF engine — TPMS/lattice field generation, including the energy→sag "phase shift" heuristic behind the digital-twin slider.
- Per-mode engine resolution — a single cartridge can mix modes across kernels; the render engine is resolved per mode (), so the flagship hyperobjects ship (exact CadQuery B-Rep modes alongside their original OpenSCAD modes).
Estimated, heuristic or unavailable today (presented as roadmap, not shipped):
- PPF physics simulation — the endpoint answers 501
physics_solver_unavailable and creates no job until a solver backend is registered with configure_physics_solver; the PPF script generator builds the input such a backend would run. No solver or GPU execution path ships in this repo yet.
- Stress heatmap — a deterministic geometry-derived estimate (
method: "geometry_proxy", approximation: true, schema_version: stress_proxy_v1), not a finite-element solve.
- Parameter estimate (formerly labelled topology optimization) — a deterministic heuristic (
method: "heuristic", approximation: true; apps/api/services/simulation/optimizer.py describes itself as the stand-in used "when full PDE-backed" solving is unavailable), not a generative or PDE-based optimization. Its status field current_sigma is a deprecated alias of current_score for one release.
📦 The Commons Catalog (CadQuery-first)
The Commons is a demand-grounded catalog of Bounded 4D Hyperobjects, authored
CadQuery-first (exact B-Rep, STEP export). Each projects/<slug>/ is a
self-contained cartridge (main.py + project.json + docs); the flagship interfaces
are also published as independent madfam-org git submodules.
Counts below are generated from the manifests, not maintained by hand — see
docs/commons-catalog.json:
| |
|---|
| Cartridges | 512 |
| With declared CDG interfaces | 502 |
| Carrying an explicit license | 512 |
| Dual-engine (CadQuery B-Rep + OpenSCAD CSG) | 20 |
| Distinct external standards referenced | 416 |
| Licensed CERN-OHL-W-2.0 | 512 of 512 |
Licensing
Two licenses apply to this repository and they cover different things:
- The platform — everything outside
projects/ — is AGPL-3.0 (see LICENSE).
- The cartridges in
projects/ are hardware designs, licensed
CERN-OHL-W-2.0 (see the table above). Weakly reciprocal: modifications to a design
must be shared, but a larger product incorporating one need not be.
Every one of the 512 cartridges is CERN-OHL-W-2.0. There are no licence
exceptions left in the commons.
Five cartridges that carried a non-CERN origin licence were removed whole on
2026-09-04 under
ADR-021,
and their slugs are reserved pending clean-room re-creation:
| Reserved slug | Origin licence that caused the removal |
|---|
stemfie | GPL-3.0-or-later (stemfie.org) |
keyv2 | GPL-3.0 (rsheldiii/KeyV2) |
multiboard | CC-BY-NC-SA-4.0 (Multiboard — NonCommercial) |
polydice | BSD-2-Clause (PolyDiceGenerator, © 2020 charmaur) |
rugged-box | CC-BY-NC-SA-4.0 on vendored upstream files (Iceman) |
Each will return only as a CERN-OHL-W-2.0 cartridge written from a recorded
baseline by an implementer who has not read the removed source. For the two
whose upstream licence covers the design rather than code (multiboard,
rugged-box), the re-creation targets the interface standard, not the shape.
Every cartridge's license is machine-readable in the catalog, and CI fails if a
declared license ever diverges from the one a cartridge actually ships, if a
manifest declares two conflicting licenses, or if an excluded cartridge appears
in the published catalog (scripts/qa/check_licenses.py --strict-all).
Two cartridges are deliberately excluded from the published Commons: they
are client-owned private cartridges, so they live outside the commons repo
entirely, mount at private-projects/, and are served only to authorized
identities. (cq-hyperobject-test used to be a third exclusion; since
RFC 0038 P2 it is an engine test fixture vendored under
apps/api/tests/fixtures/cartridges/ and is not a cartridge at all.)
What is verified, precisely. Every manifest is schema-validated in CI, and every
mode is geometrically distinct (each mode's parts[] id drives target_part dispatch).
Cross-kernel geometric parity and watertightness are enforced in CI for the cartridges
on the VERIFIED_PARITY_PROJECTS allowlist in
apps/api/tests/scripts/geometric_regression.py; for the rest, divergence is reported
but non-blocking, and each run prints how many cartridges were compared versus skipped.
Treat a green parity job as covering the allowlist, not the whole catalog.
The first 100 — ordered by Common Denominator Geometry leverage:
| Tier | Focus |
|---|
| 1 · Universal Interfaces | Gridfinity, VESA, ¼-20, GoPro, bottle thread, DIN clip, T-slot, gears, fasteners, box |
| 2 · Household Organization | dividers, pegboard/Multiboard, bins, hooks, shelf brackets |
| 3 · Kitchen / Bath / Utility | coasters, tube squeezers, jar racks, funnels, knobs |
| 4 · Mechanical & Kinematic | pulleys, bearings, gear trains, drag chain, springs, cams, lead-screw nuts |
| 5 · Fastening & Joining | connectors, snap-fits, dovetails, threaded bosses, ball-sockets |
| 6 · Electronics & Desk | enclosures, SBC cases, stands, risers, media caddies |
| 7 · Jigs & Fixtures | soft jaws, drill guides, gauges, templates, handwheels |
| 8 · Medical / Lab / Assistive | prosthetic sockets, slide holders, tube/pill racks, splints |
| 9 · Filtration / Water / Garden | Faircap filter, pipe/hose fittings, planters, drip fittings |
| 10 · Mobility / Automotive / EDC | Picatinny, bike/vent mounts, carabiners, keytags, French cleat |
The second 100 — deeper cuts plus new domains (mounting systems, drone/FPV,
automotive, kitchen, garden, workshop, electronics/maker, wearable/EDC, musical/studio,
sports, marine/RV, pet, generative art, safety).
Dual-engine flagships (CadQuery B-Rep modes + original OpenSCAD modes):
Gridfinity · Gears · Fasteners · DIN Rail Clip · Soft Jaw · Faircap Filter ·
Parametric Connector · Microscope Slide Holder — plus 13 more;
COMMONS.md lists all 21 (counts.dual_engine in the catalog).
Machine-readable catalog: docs/commons-catalog.json
— one entry per cartridge with its CDG interfaces, referenced standards, engines, and
clone instructions. Human-readable index: COMMONS.md. Both are
generated by scripts/qa/generate_commons_catalog.py and checked for staleness in CI.
Note for agents: llms.txt and llms-full.txt are not the catalog. They are the
org-wide agent operating contract, regenerated across every MADFAM repo by
internal-devops/scripts/sync-agent-docs.py, which overwrites whatever is placed there.
📖 Deep Documentation
For peak Developer Experience and Agentic Discovery, consult our interconnected docs.
docs.yantra4d.com is not deployed yet — the hostname does not resolve. The
Starlight source below is complete and readable in-repo; the site build, ingress,
and DNS record are still outstanding. Links point at the source until it is live.
🚀 Quick Start
Clone (with all project submodules)
git clone --recurse-submodules https://github.com/madfam-org/yantra4d
Development
./scripts/dev/dev.sh # Full Stack (Backend + Studio + Landing)
./scripts/dev-stop.sh # Cleanup
Docker (Production-Ready)
docker compose up --build
Open localhost:3000 to enter the Studio.
🤝 Community & License
Yantra4D is licensed under the GNU Affero General Public License v3.0 (AGPLv3). Our hyperobjects are always released under the CERN-OHL-W-2.0 (Weakly Reciprocal) open hardware license.
Join the movement. Print the Hyperobjects.
Shared configuration links preserve Unicode text through JSON escapes and retain legacy decoding. See the share-link contract and limits.
Viewer artifact loading has independent completion and lifecycle guarantees. See blank-viewer diagnostics and shared STL task ownership; render completion alone does not prove canvas delivery.
