Holotope.js

A browser-native toolkit for exploring and rendering higher-dimensional geometry.

Comment

Inspiration

Holotope.js began with a personal curiosity: how can higher-dimensional structure become intuitive through the three-dimensional representations available to our perception?

Projections, cross-sections, physical simulations, and higher-dimensional geometry already exist separately. The missing piece is a cohesive framework that keeps them connected. A projected triangle should not quietly become the mathematical truth; it should remain traceable to the higher-dimensional object, transformation, and source topology that produced it.

Holotope.js explores that bridge: from higher-dimensional state to lower-dimensional intuition, without losing the path back to the underlying model.

What it does

Holotope.js is an open-source TypeScript framework for constructing, observing, interacting with, and simulating N-dimensional systems in the browser.

It includes:

  • N-dimensional vectors, transformations, scene graphs, cameras, cell complexes, and exact polytope constructions.
  • Coxeter/Wythoff geometry, lattices, spectral analysis, and cut-and-project model sets.
  • Explicit N→3D projection and hyperplane slicing, including exact affine cross-sections.
  • Representation lineage that connects visible triangles and points back to source cells, vertices, edges, and higher-dimensional coordinates.
  • Honest inverse semantics that distinguish exact recovery from projection fibres, overlap, and ambiguity.
  • Three.js bindings for projected surfaces, edges, slices, picking, and interactive higher-dimensional rotation.
  • Optional WebGPU paths for projection, slicing, and implicit-field visualization, checked against deterministic CPU references.
  • Four-dimensional rigid-body mechanics with Spin(4) orientation, six-plane angular motion, mass properties, collision detection, contact manifolds, friction, joints, kinematic motion, and continuous collision detection.
  • Dimension-independent XPBD foundations for particle systems and deformable materials, including simplex-based StVK and Neo-Hookean constitutive models.

The flagship demonstrations keep one authoritative R4 object alive across several representations. A user can select a visible section or projection, recover its source topology, manipulate a source-space coordinate, and continue the simulation while every representation remains synchronized.

The tesseract demonstration makes the distinction especially clear: the selected cut is shown both inside the perspective projection and in its exact three-dimensional affine coordinates, with matching source-backed regions highlighted in both views.

How I built it

Holotope.js is a TypeScript monorepo organized into three primary packages:

  • @holotope/core is a zero-dependency Float64 kernel for N-dimensional mathematics, geometry, projections, slicing, topology, provenance, fields, and spectral operations.
  • @holotope/three converts those explicit mathematical products into three.js render objects and interaction results.
  • @holotope/physics provides higher-dimensional rigid-body, collision, constraint, contact, and deformable-mechanics systems.

The architecture preserves N-dimensional state for as long as possible. Projection, slicing, picking, and rendering are explicit transformations rather than hidden implementation details. Three dimensions are treated as a specialization of the same contracts, providing a familiar reference against which higher-dimensional behavior can be examined.

Auditable Float64 CPU implementations serve as the correctness baseline. GPU paths and optimized algorithms are differentially checked against those references, while physical systems are tested through invariants such as conservation, constraint residuals, dimensional specialization, and accepted-state recovery.

I began the project shortly before Build Week and extended it substantially during the submission period. Earlier work established the mathematical kernel, polytopes, lattices, fields, and rendering experiments. The later development connected representation lineage, source-space interaction, rigid and deformable mechanics, and integrated source-to-simulation demonstrations.

I initially explored the project with Fable, then used Codex with GPT-5.6 Sol as the primary collaborator for the later core work.

Codex supported the hands-on development workflow: inspecting the repository, implementing across packages, running validation, testing browser demonstrations, maintaining documentation, and preparing releases. GPT-5.6 Sol served as a sustained research and engineering collaborator within that workflow, helping synthesize mathematical literature, challenge formulas and assumptions, design typed interfaces, plan differential tests, and decompose the higher-dimensional physics roadmap.

I remained responsible for the central thesis, mathematical conventions, architecture, scope, public boundaries, and decisions about which work was ready to become part of the library.

Challenges I ran into

The central challenge was not simply drawing four-dimensional objects. It was preserving mathematical accountability while making those objects understandable and interactive.

Projection destroys information, while slicing retains only the part incident to a chosen hyperplane. Treating their outputs identically would be misleading. Holotope therefore records how every representation was constructed and explicitly reports whether a visible point can be recovered exactly, corresponds to a family of possible source points, or is ambiguous because of projection overlap.

Interaction introduced a related challenge: a click occurs on a three-dimensional rendered triangle, but meaningful editing and simulation must happen in the authoritative higher-dimensional model. Solving that required persistent source-cell identities, representation lineage, perspective-correct lifting, source-edge coordinates, and mappings that survive changing representations and simulation state.

Higher-dimensional physics introduced further difficulties: rotations in 4D have six angular planes, contact tangents are three-dimensional, rotational constraints require block responses, and numerical material failures must reject a step without corrupting accepted state. These problems shaped the library’s emphasis on explicit conventions, invariant checks, and reference implementations.

What's next

The next phase is to strengthen Holotope as a practical companion for mathematical and scientific communication rather than expanding it into a gallery of disconnected effects.

Priorities include:

  • Graduating the integrated deformable source-to-representation pipeline into the public showcase.
  • Improving task-based documentation, recipes, JSDoc, runtime diagnostics, and AI-readable API guidance.
  • Expanding GPU acceleration while retaining auditable CPU reference paths.
  • Building reusable topology-to-representation operations such as unfolding with preserved source lineage.
  • Improving materials and section rendering without sacrificing mathematical meaning.
  • Developing import/export formats for higher-dimensional geometry, representations, animation, and simulation state.
  • Creating integrated scientific examples in geometry, mechanics, dynamical systems, chemistry, and other fields where researchers need interactive representations of structures that cannot be understood from one view alone.

The long-term goal is not merely to render higher dimensions. It is to provide a coherent framework connecting higher-dimensional source models, honest representations, interaction, and simulation on the open web.

Built With

Share this project:

Updates