tiwutdev/model3d-vault repository overview

⁠3D Vault - Model Database

A high-performance, containerized 3D model database and WebGL interactive previewer written in Rust (Axum, Tokio, Tower) featuring a modern GTK4 / GNOME Libadwaita interface.

Developed by tiwut⁠ (github.com/tiwut).

services:
  vault:
    build:
      context: .
      dockerfile: Dockerfile
    image: tiwutdev/model3d-vault:latest
    container_name: model3d-vault
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
    environment:
      - PORT=8080
      - DATA_DIR=/app/data
      - STATIC_DIR=/app/static
      - RUST_LOG=info,model3d_vault=info
    labels:
      org.opencontainers.image.title: "model3d-vault"
      org.opencontainers.image.description: "Professional 3D Model Vault & WebGL Viewer"
      org.opencontainers.image.authors: "https://github.com/tiwut"
      org.opencontainers.image.source: "https://github.com/tiwut/3D-Vault---Model-Database"
      org.opencontainers.image.vendor: "tiwutdev"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

⁠Highlights

• Multi-Format 3D WebGL Engine: Native real-time WebGL previewer supporting GLTF / GLB, Wavefront OBJ, Stereolithography STL (CAD / 3D printing), and Polygon PLY (range scans / vertex colors).
• 1:1 Viewport Container: Dedicated 1:1 aspect-ratio 3D viewport with intelligent side-by-side dashboard layout for specs, metadata, and files.
• Automatic Preview Placement: Models are automatically centered, grounded at Y=0, and normalized to fixed camera framing. High-resolution 1:1 preview images are automatically rendered and saved.
• Format Switcher & Multi-File Packages: Models can store multiple variations or formats (e.g. GLB + STL + OBJ). Switch between formats in real-time within the 3D viewport.
• Unified & Dedicated Asset Ingestion:
  • Dedicated Add 3D Models button (filters .glb, .gltf, .obj, .stl, .ply, .fbx, .dae, .3mf).
  • Dedicated Add Images & Previews button (filters .png, .jpg, .jpeg, .webp, .svg, .hdr).
  • Select All Files button and unified drag-and-drop zone.
  • Complete metadata setup: Title, Heading / Subtitle, Category, Multi-paragraph Description, Taxonomy Tags, Keywords, Author / Studio, and Licensing.
• GTK4 / GNOME Libadwaita Theme: Authentic GNOME design language with smooth dark and light themes, Adwaita headerbars, split views, preference clamps, subtle elevations, and strictly professional SVG symbolic iconography (zero emojis).
• Viewport Inspection HUD: Live vertex counts, polygon/triangle counts, real bounding box measurements (X × Y × Z), wireframe toggle, ground grid toggle, auto-rotation, matcap/normals/PBR shading, and camera snapshot capture.
• 100% Self-Contained & Air-Gapped: Three.js and loaders are locally vendored inside the container; no external CDN calls or internet access required at runtime.
• Production-Ready Docker: Multi-stage lightweight Docker image with healthchecks, unprivileged non-root execution, and persistent volume support.

⁠Quick Start with Docker

⁠Pulling from Docker Hub

docker pull tiwutdev/model3d-vault:latest
docker run -d --name model3d-vault -p 8080:8080 -v $(pwd)/data:/app/data tiwutdev/model3d-vault:latest

⁠Using Docker Compose (Recommended)

docker compose up -d

Visit http://localhost:8080⁠ in your browser.

To stop the container:

docker compose down

⁠Building Locally with Standard Docker CLI

1. Build the Docker Image:

   docker build -t tiwutdev/model3d-vault .
   

   Copy

2. Run the Container with Persistent Storage:

   docker run -d \
     --name model3d-vault \
     -p 8080:8080 \
     -v $(pwd)/data:/app/data \
     tiwutdev/model3d-vault:latest
   

   Copy

3. Check Container Health:

   docker inspect --format='{{json .State.Health.Status}}' model3d-vault
   

   Copy

⁠Running Locally with Cargo (Native Rust)

Ensure you have Rust (1.80+) installed.

# Run release build
cargo run --release

# The server listens on http://0.0.0.0:8080

⁠Environment Variables

⁠REST API Reference

⁠Project Structure

3d-DB/
├── Cargo.toml               # Rust package manifest & dependencies
├── Dockerfile               # Multi-stage optimized Docker build
├── docker-compose.yml       # 1-command deployment setup
├── src/
│   ├── main.rs              # Axum HTTP server entrypoint
│   ├── models.rs            # Data structures (ModelItem, ModelFile, FileKind)
│   ├── store.rs             # Disk persistence & in-memory index
│   ├── api.rs               # Axum REST endpoints & multipart streaming
│   └── samples.rs           # Pre-loaded benchmark models (GLB, OBJ, STL, PLY)
├── static/
│   ├── index.html           # GTK4 Libadwaita SPA markup
│   ├── css/
│   │   ├── adwaita.css      # GNOME / Libadwaita design tokens (dark/light)
│   │   └── viewer.css       # 3D viewport canvas, HUD overlays, inspector
│   ├── js/
│   │   ├── icons.js         # Symbolic SVG icons library (no emojis)
│   │   ├── viewer.js        # Three.js 3D engine (GLTF, OBJ, STL, PLY)
│   │   └── app.js           # Catalog state, search, and upload workflow
│   └── vendor/              # Vendored Three.js & loaders (100% offline)
└── default_assets/          # Embedded reference 3D models & SVG thumbnails

⁠License

MIT License