SymmHub Logo SymmHub Outline
Symmetry & Geometry Engine

SymmHub Project Outline

A web-native laboratory for computing, simulating, and visualizing discrete symmetries across Euclidean, spherical, and hyperbolic spaces using WebGL2 GPU shaders.

Vladimir Bulatov (bulatov.org) Chaim Goodman-Strauss (co-author of The Symmetries of Things) Scott Vorthmann (creator of vZome)

1. Core Mathematical Foundations

SymmHub unifies classical group theory with inversive differential geometry and numerical simulation.

Discrete Symmetry Groups Groups

Implements exact discrete isometry groups across geometries:

  • Wallpaper Groups: All 17 planar crystallographic groups ($*632$, $2222$, $442$, etc.).
  • Frieze Groups: The 7 infinite 1D periodic symmetry groups.
  • Spherical Groups: Polyhedral, dihedral, and cyclic symmetries on $S^2$.
  • Triangle & Coxeter Groups: Spherical, Euclidean, and Hyperbolic triangle groups ($klm$, reflection groups $*klm$) and quadrangle groups ($*klmn$).

Conway Orbifold Notation Topology

Employs John H. Conway’s orbifold signatures and the Magic Theorem:

  • Topological Cost System: Orbifolds cost topological budget (Sphere = $\$2$, Euclidean plane = $\$0$, Hyperbolic plane < $\$0$).
  • Deaton's Thesis & Thurston Geometrization: Computes conformal metric metrics and builds hyperbolic polygon realizations with draggable boundary parameters.

Inversive Geometry & S-Planes Geometry

Spheres, circles, and planes are represented uniformly in the conformal model:

  • 4-Vector S-Planes: Unifies hyperplanes and circles into $(a, b, c, d)$ vectors.
  • Circle Inversions: Reflections and Möbius transformations calculated with clean linear algebraic inner products.
  • Dirichlet Domains: Algorithmic generation of fundamental domains from generator sets.

Subgroup Enumeration & Color Combinatorics

Standalone permutation engine for color symmetry:

  • Coset Table Enumeration: Finitely presented groups enumerated up to index $N$ via Todd–Coxeter methods.
  • Permutation Representations: Action on coset classes mapped to color palettes, producing $N$-color symmetric tessellations.
  • GAP-Free: Pure ES module engine running inside browser without server dependencies.
GPU Domain Folding: Instead of generating millions of polygonal geometry tiles, SymmHub renders in reverse. Shaders evaluate every screen coordinate $(x, y)$, iteratively reflecting/inverting it back into the fundamental domain, and then sample textures, colormaps, or PDEs at that mapped coordinate.

2. System Architecture & Zero-Build Philosophy

Built strictly with web standards: runs directly in any modern browser without npm installs, bundlers, transpilers, or build steps.

# SymmHub Repository File Structure SymmHub/ ├── index.html # Main landing portal and application gallery ├── apps/ # Standalone interactive applications │ ├── sympix/ # Image & video symmetry explorer + color symmetry │ ├── symsim/ # Gray-Scott & Ginzburg-Landau symmetric PDEs │ ├── attractors/ # Chaotic symmetric dynamical systems (SymChaos) │ ├── orbifold/ # General hyperbolic orbifolds with draggable edges │ ├── groups/ # Subgroup enumeration playground │ └── sample/ # Minimal starter template for new apps ├── tutorials/ # Interactive educational guides with MathJax │ ├── orbifold-notation.html # "Two Dollars of Symmetry" (Conway & Deaton) │ └── orbifold-showcase.html # 30+ clickable hyperbolic orbifold models ├── lib/ # Reusable core mathematical & graphics libraries │ ├── symhublib/ # Pipeline coordinator, renderer, document management │ ├── sublib/ # Standalone coset enumeration engine │ ├── invlib/ # Inversive geometry, complex arithmetic & Dirichlet domains │ ├── grouplib/ # Group constructors (Wallpaper, Frieze, KLM, Spherical) │ ├── orbilib/ # Hyperbolic orbifold geometrization solver │ ├── shaders/ # Modular WebGL2 GLSL shaders │ └── uilib/ # UI controls, Dat.GUI mod, image/video recorders └── tests/ # Unit and integration test suites

3. Core Library Modules (lib/)

Modular JavaScript libraries exposing clean ES module APIs.

Module Key Components Role & Responsibilities
symhublib SymRenderer, VisualizationManager, CrownCalculator, SymDocumentManager Central rendering and state coordination. Handles multi-pass WebGL framebuffers, layer composition (textures, colormaps, bumpmaps), and preset JSON serialization.
sublib subgroupsData, sublib_core.js, bin/sublib.mjs GAP-independent coset table subgroup enumerator. Computes conjugacy classes of subgroups up to index $N$ and outputs permutation JSON data for color symmetry.
invlib ISplane, Inversive, ComplexArithmetic, DirichletDomainBuilder Inversive geometry calculations, Möbius transformations, conformal disk-to-band projections, and uniform data packing for WebGL shaders.
grouplib WallpaperGroups, Group_KLM, Group_Spherical, Group_Frieze Generators, matrices, fundamental domains, and subgroup domain constructions across the 17 wallpaper groups, Coxeter triangle groups, and spherical groups.
orbilib OrbifoldGeometrization, Group_Orbifold, OrbifoldUITool Implements hyperbolic metric calculations for arbitrary Conway orbifold signatures. Calculates side lengths, cone angles, and polygon vertices for hyperbolic orbifolds.
shaders inversiveSampler, fundDomainShader, projection, bufferVisBumpmap Modular GLSL fragment shaders assembled dynamically at runtime for GPU-accelerated domain folding, procedural noise, colormapping, and heightmap rendering.
uilib ParamUI, ImageSelector, BinaryStore, VideoRecorder UI widgets, modified dat.gui controls, color palette pickers, file import/export handlers, and canvas WebM video export.

4. Interactive Applications Suite (apps/)

Specialized applications highlighting different mathematical aspects of symmetry.

SymPix Flagship

Transform photographs, live video camera streams, and procedural patterns into symmetric wallpaper, frieze, spherical, and hyperbolic tessellations with multi-color coset symmetry.

Launch SymPix →
SymSim PDEs

Simulate non-linear partial differential equations on GPU floating-point textures folded into symmetry groups. Includes Gray–Scott reaction-diffusion and Ginzburg–Landau models.

Launch SymSim →
SymChaos Attractors

Real-time visualization of symmetric chaotic attractors (Field & Golubitsky polynomial systems) exhibiting discrete rotational, reflectional, and wallpaper symmetries.

Launch SymChaos →
Orbifold Explorer Hyperbolic

Interactive laboratory for general hyperbolic orbifolds. Users can interactively drag edges and cone points of fundamental domains in real-time.

Launch Explorer →
Groups Playground Algebra

Interactive interface for sublib: input custom generators and relators or choose presets to compute and inspect subgroup conjugacy classes and coset permutations.

Open Playground →
Sample App Starter

A clean, minimal boilerplate demonstrating how to initialize SymRenderer, manage double-buffered FBOs, and load shader programs for custom apps.

View Sample →

5. Interactive Educational Tutorials (tutorials/)

Rigorous mathematical expositions integrated with live WebGL widgets.

Two Dollars of Symmetry Tutorial

A comprehensive essay detailing Conway's orbifold notation, the Magic Theorem, Euler characteristic cost budgeting, and the exact geometric meaning of dragging edges in fundamental domains according to Derek Deaton's thesis.

Read Tutorial →
Orbifold Showcase Showcase

A curated catalog of thirty-plus hyperbolic symmetry groups. Displays each orbifold's signature, Euler characteristic, draggable parameters, and direct one-click visualization links.

Open Showcase →

6. Test Suites & Tooling (tests/)

Automated regression test suites and interactive diagnostic runners:

sublib Tests

Validates coset table calculations and subgroup counts against verified GAP algebra benchmarks across wallpaper and triangle groups.

Splane & Inversive Tests

Ensures numerical precision of 4-vector circle reflections, Möbius transformations, and conformal projections.

Shader & FBO Tests

Validates WebGL2 floating point texture support, multi-target framebuffers, and pixel read-back routines.

7. Running SymmHub Locally

Since SymmHub uses ES modules, start any static web server in the repository root directory:

# Python 3 built-in HTTP server: python -m http.server 8000 # Or using Node http-server / npx: npx serve . # Then open your browser at: http://localhost:8000/outline.html # (This document) http://localhost:8000/index.html # (Main Portal)