Skip to main content
Glama
1nc0gn30

nexus3d

by 1nc0gn30
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

🌟 Nexus 3D Scene Studio

Nexus 3D Header Python 3.9+ MCP Protocol Zero Dependencies License MIT

A pure Python 3D mathematical geometry engine, WebGL Material 3 studio (design influenced by Material 3), and Model Context Protocol (MCP) server for generative 3D modeling and autonomous AI agents.

Live Studio Web UI • Procedural Primitives • MCP Integration • Python API • CLI Commands

💎 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.

Related MCP server: mcp-printable

🏛️ 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

📄 License

This project is open-source under the MIT License.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-printable

    AaronGoldsmith
    A
    license
    A
    quality
    B
    maintenance
    Connects MCP-capable agents to Blender and OpenSCAD for AI-driven 3D modeling, with tools and rules optimized for FDM-printable geometry.
    29
    2
    MIT

  • openscad-mcp

    jkoets
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables LLMs to create and manipulate 3D models using OpenSCAD through MCP tools for code-based modeling, preview, and export.
    1
    MIT
  • gitcad by gitcad-xyz

    gitcadofficial

    gitcad-xyz
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables agents to create and manipulate 3D CAD models using natural language via MCP, with git-based versioning and manufacturing output generation.
    1
    Apache 2.0