Nexus 3d Scene Studio

---

💎 Highlights & Capabilities

• 🎨 Material 3 Light Mode Studio: Interactive WebGL 3D canvas (design influenced by Material 3), system fonts, smooth OrbitControls, wireframe/solid shading, lighting rigs, and real-time geometry telemetry HUD.
• 🧊 Marching Tetrahedra Volumetric Isosurface Engine: Watertight, ambiguity-free 3D isosurface polygonizer with analytical central finite-difference normal estimation and vertex normal-map coloring.
• 🧬 Triply Periodic Minimal Surfaces (TPMS): Analytic Gyroid infill scaffold, Schwarz P primitive crystal, and Neovius porous minimal surfaces.
• 🧮 Analytic Signed Distance Functions (SDF) & CSG Booleans: Primitives (sphere, box, torus, cylinder, capsule) with exact and polynomial smooth Boolean operators (union, intersection, subtraction) and non-linear axial twist deformers.
• 🌌 3D Mandelbulb Fractal & Organic Metaballs: High-power 3D hypercomplex Mandelbulb fractal fields and multi-center organic metaball clusters.
• 🔮 4D Hypercube (Tesseract) Engine: Real-time 4D rotation matrices in $SO(4)$ Lie group projected into 3D space via stereographic projection.
• 🌀 Parametric Space Curves & Surfaces: Torus knots $(p, q)$ with Frenet-Serret tube framing, Superquadrics with taper/twist/bend deformations, Fibonacci golden spiral spherical lattices, Buckyballs (Fullerene C60), and Möbius ribbons.
• 🏔️ Procedural Fractal Terrain: Multi-octave Fractional Brownian Motion (fBm) elevation heightfields with analytical normal gradient calculations.
• 💾 1-Click Multi-Format Exporters: Wavefront .obj + .mtl, ASCII & Binary .stl (3D printing ready), .ply, Three.js BufferGeometry .json, and single-file standalone .html viewers.
• 🤖 Model Context Protocol (MCP) Server: Native stdio / JSON-RPC 2.0 interface for Claude Desktop, Cursor IDE, Cline, Zed, and autonomous AI coding agents with dedicated isosurface polygonization and CSG Boolean evaluation tools.
• ⚡ Pure Standard Library Core: 100% Python standard library geometry computation without NumPy/SciPy dependency requirements.

---

🏛️ System Architecture

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                 NEXUS 3D SCENE STUDIO                                  │
├──────────────────────────────┬──────────────────────────┬──────────────────────────────┤
│      🎨 Web Studio HUD       │   🤖 AI Agent / MCP Hub   │      💻 CLI Interface        │
│   (Material 3 Studio UI)     │  (FastMCP / JSON-RPC 2)  │    (`nexus3d` commands)      │
└──────────────┬───────────────┴────────────┬─────────────┴──────────────┬───────────────┘
               │                            │                            │
               ▼                            ▼                            ▼
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                             CORE MATHEMATICAL ENGINE                                   │
├──────────────────────────────┬──────────────────────────┬──────────────────────────────┤
│  🔮 4D Stereographic Proj    │  🌀 (p,q) Torus Knots    │  💎 Superquadrics + Deform   │
│  🌻 Fibonacci Spiral Lattice │  ⚽ Buckyball C60 Mesh   │  ♾️ Möbius Strip Ribbon      │
│  🏔️ Multi-Octave fBm Terrain │  📐 Platonic Solids      │  📊 Mesh Telemetry & VRAM    │
└──────────────────────────────┴────────────┬─────────────┴──────────────────────────────┘
                                            │
                                            ▼
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                              EXPORT & PACKAGING PIPELINE                               │
│     • Wavefront OBJ + MTL    • ASCII / Binary STL       • Three.js BufferGeometry JSON │
│     • Standalone HTML Viewer • PLY Point Cloud & Mesh   • GLTF 2.0 / GLB Layout        │
└────────────────────────────────────────────────────────────────────────────────────────┘

---

📐 Procedural Primitives Catalog

Primitive	Mathematical Formula / Algorithm	Key Parameters
4D Tesseract	$\mathbf{p}{3D} = \frac{s}{d - w} R{yw}(\phi) R_{xw}(\theta) \mathbf{v}_{4D}$	scale, rotation_4d, distance
$(p, q)$ Torus Knot	$r = \cos(qu) + 2$, $\mathbf{r} = (r\cos pu, r\sin pu, -\sin qu)$ with Frenet framing	p, q, tube_radius, tubular_segments
Superquadric	$\mathbf{S}(\eta, \omega) = (a_1 C(\eta, s_1)C(\omega, s_2), a_2 C(\eta, s_1)S(\omega, s_2), a_3 S(\eta, s_1))$	s1, s2, rx, ry, rz, taper, twist
Fibonacci Sphere	$z_i = 1 - \frac{2i}{N-1}$, $\phi_i = i \cdot \pi(3-\sqrt{5})$, $r_i = \sqrt{1-z_i^2}$	num_points, radius
Buckyball C60	Truncated regular icosahedron ($\chi = 60 - 90 + 32 = 2$)	radius, truncation_factor
Möbius Strip	$\mathbf{S}(u, v) = ((R + v\cos\frac{nu}{2})\cos u, (R + v\cos\frac{nu}{2})\sin u, v\sin\frac{nu}{2})$	radius, width, twists
Fractal Terrain	$h(x, z) = \sum_{k=0}^{M-1} A \rho^k \mathcal{N}(f \lambda^k x, f \lambda^k z)$	grid_size, scale, octaves, height_scale
TPMS Gyroid	$\cos x \sin y + \cos y \sin z + \cos z \sin x = 0$ via Marching Tetrahedra	resolution, scale, thickness
Schwarz P Minimal Surface	$\cos x + \cos y + \cos z = 0$ implicit crystal lattice	resolution, scale, thickness
Neovius Minimal Surface	$3(\cos x + \cos y + \cos z) + 4\cos x \cos y \cos z = 0$	resolution, scale, thickness
3D Mandelbulb Fractal	$v_{n+1} = v_n^8 + c$ spherical hypercomplex iteration	resolution, power, max_iter
Smooth CSG Blend	$f_{\text{union}} = \text{smin}(d_1, d_2, k) = d_2 + (d_1-d_2)h - kh(1-h)$	resolution, primitive_a, primitive_b, smoothing

Detailed mathematical derivations and proofs are documented in docs/PROCEDURAL_GEOMETRY_MATH.md.

---

🚀 Quickstart

Installation

# Clone the repository
git clone https://github.com/nexus-3d/nexus-3d-scene-studio.git
cd nexus-3d-scene-studio

# Install in editable mode
pip install -e .

Python API Quickstart

from nexus_3d_scene_studio.geometry_engine import (
    generate_torus_knot,
    generate_tesseract_4d,
    generate_superquadric,
)
from nexus_3d_scene_studio.mesh_exporter import MeshExporter

# 1. Generate a Parametric (3, 7) Torus Knot
mesh = generate_torus_knot(p=3, q=7, tubular_segments=180, radial_segments=24)

# 2. Inspect Mesh Telemetry
print(f"Vertices: {mesh.vertex_count}")
print(f"Triangles: {mesh.triangle_count}")
print(f"Surface Area: {mesh.compute_surface_area():.3f}")

# 3. Export to Wavefront OBJ with Normals
MeshExporter.export_obj(mesh, "torus_knot_3_7.obj")

# 4. Export to 3D-Printing ASCII STL
MeshExporter.export_stl(mesh, "torus_knot_3_7.stl")

# 5. Export to Standalone Offline HTML 3D Viewer
MeshExporter.export_html_viewer(mesh, "torus_knot_viewer.html")

---

💻 CLI Interface

# Generate and export a 4D Hypercube Tesseract
nexus3d generate tesseract --rotation-4d 0.8 --export tesseract.obj

# Generate a Parametric Torus Knot
nexus3d generate torus-knot --p 3 --q 5 --tube-radius 0.4 --export knot.stl

# Launch the interactive Nexus 3D Studio Web UI
nexus3d serve --port 8080

# Inspect geometry telemetry of any OBJ file
nexus3d inspect knot.obj

---

🤖 AI Agent & MCP Server

Nexus 3D Scene Studio implements the Model Context Protocol (MCP), allowing AI agents to generate, inspect, and export 3D scenes autonomously.

Available MCP Tools:

1. generate_mesh: Generates any of the 7 procedural primitives with custom math parameters.
2. export_scene: Exports scenes to OBJ, MTL, STL, PLY, Three.js JSON, or Standalone HTML.
3. transform_mesh: Applies translation, rotation, scale, taper, twist, and bend deformations.
4. inspect_geometry: Returns live vertex counts, face counts, bounding box, surface area, and Euler characteristic.
5. list_primitives: Returns available primitives and parameter schema.

Claude Desktop Integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "nexus3d": {
      "command": "python",
      "args": ["-m", "nexus_3d_scene_studio.mcp_server"],
      "env": { "PYTHONPATH": "src" }
    }
  }
}

Full setup guides for Cursor, Cline, and Zed are available in docs/MCP_GUIDE.md.

---

🧪 Testing

Run the comprehensive unit test suite:

PYTHONPATH=src pytest tests/ -v

---

📜 Attribution & License

Engineered by Neal Frazier Tech (@1nc0gn30) • NullAI Platform
Repository: github.com/1nc0gn30/nexus-3d-scene-studio
Licensed under the MIT License.