# openalice-spatial

> 3D world generation service — NANO-PATH architecture: Gemini multi-view images → AnySplat Gaussian Splatting → PLY/GLTF for WebGPU rendering.

## At a glance
| field | value |
|---|---|
| kind | `service` |
| priority | `P3` |
| default branch | `mvp` |
| last activity | 2026-06-17T17:28:57+00:00 |
| features catalogued | **19** |
| runtime deps declared | **0** |

## Manifest
`.atlas-deps.yml` — parsed cleanly: **yes**

### Consumed env
- `PORT`
- `SPATIAL_WORK_DIR`
- `RUST_LOG`
- `VIEW_API_URL`
- `VIEW_API_KEY`
- `GPU_WORKER_PULL`
- `GPU_WORKER_URL`
- `RUNPOD_ENDPOINT_URL`
- `RUNPOD_ENDPOINT_ID`
- `RUNPOD_API_KEY`
- `RUNPOD_BASE_URL`
- `ANYSPLAT_DOCKER_IMAGE`
- `GEMINI_API_KEY`
- `GEMINI_API_URL`
- `GEMINI_MODEL`
- `DIFFSPLAT_MODEL`
- `DIFFSPLAT_MODE`
- `DIFFSPLAT_RUNPOD_ENDPOINT`
- `DIFFSPLAT_RUNPOD_KEY`

### Owns tables
- `jobs`
- `worlds`
- `images`

### Exposes
- `docker_image` — openalice-spatial
- `http_endpoint` — POST /v1/generate — submit text/image → 3D world job
- `http_endpoint` — GET /v1/jobs/:id — poll job status
- `http_endpoint` — GET /v1/worlds/:id — download PLY/GLTF
- `http_endpoint` — GET /v1/worker/pull — GPU worker long-poll queue
- `http_endpoint` — POST /v1/worker/push — GPU worker result delivery
- `npm_package` — @openalice/spatial-viewer — React 19 + Three.js + SparkJS Gaussian-splat .ply viewer (orbit/walk/fly camera)
- `npm_package` — @openalice/spatial-editor — React 19 3D world editor built on @openalice/spatial-viewer (zustand+immer state, object list, property panels, AI generate panel)

## Env drift

**Code reads, manifest omits (2):**
- `DOMAIN`
- `MODEL_PATH`

**Manifest declares, code unused (2):**
- `PORT`
- `RUST_LOG`

## Live reachability
- last probe: **up** · `https://spatial.blal.pro/health` · HTTP 200 · 0ms
- uptime 24h: **100.0%**

## Features (19)

### platform/spatial
- **`platform.spatial.editor`** — Three-panel layout: object list/library (left), 3D viewer with toolbar (center), properties inspector (right), AI generate panel (bottom). Auto-saves every 30 s by default. Undo/redo history stack managed by useEditorStore. Loads/saves world state via spatial API.  
  *packages/spatial-editor/src/SpatialEditor.tsx:1*
- **`platform.spatial.editor.generated-object`** — (GET /v1/jobs/:id) after GeneratePanel submits, surfaces live progress/status, and on `completed` loads the resulting GLTF/PLY into the scene by adding a PlacedObject whose sourceId is the job's result_url. Mirrors the spatial-viewer useSplatLoader poll cadence. Polling logic is split into a pure `pollGeneratedObject` so it is testable without a DOM.  
  *packages/spatial-editor/src/hooks/useGeneratedObject.ts:2*
- **`platform.spatial.editor.generated-object.test`** — loads the GLTF/PLY result into the scene (PlacedObject from result_url) on completion, handles failure / completed-without-url / transient errors, respects the poll budget, and aborts cleanly. Runs under `node --test` (Node 22 strips types) — no DOM/vitest needed.  
  *packages/spatial-editor/src/hooks/useGeneratedObject.test.ts:2*
- **`platform.spatial.editor.generate-panel`** — accepts a text prompt, quality preset (1k/2k/4k), and object vs world mode; calls Spatial API to submit a generation job and returns the job ID for polling progress.  
  *packages/spatial-editor/src/components/GeneratePanel.tsx:2*
- **`platform.spatial.editor.object-panel`** — the Spatial API library and placed objects in the current scene; supports add, duplicate, and remove operations through the editor store.  
  *packages/spatial-editor/src/components/ObjectPanel.tsx:2*
- **`platform.spatial.editor.properties-panel`** — (position/rotation/scale), material, and metadata of the currently selected 3D object; writes updates through editor store with undo/redo support.  
  *packages/spatial-editor/src/components/PropertiesPanel.tsx:2*
- **`platform.spatial.editor.store`** — placed objects, camera presets, lighting config, dirty flag, and undo/redo history stack; single source of truth for all SpatialEditor panel components.  
  *packages/spatial-editor/src/hooks/useEditorStore.ts:2*
- **`platform.spatial.editor.toolbar`** — /delete/camera); highlights active tool from editor store; keyboard shortcut labels (V/G/R/S).  
  *packages/spatial-editor/src/components/EditorToolbar.tsx:2*
- **`platform.spatial.hooks.navigation`** — supports 'orbit', 'fly', and 'walk' modes; dispatches custom DOM events consumed by the Three.js render loop so React state never bottlenecks 60 fps.  
  *packages/spatial-viewer/src/hooks/useNavigation.ts:2*
- **`platform.spatial.hooks.splat-loader`** — .splat) file from a world ID via the Spatial API or direct URL; tracks loading progress (0-100%) and exposes error state; cancels in-flight fetch on unmount.  
  *packages/spatial-viewer/src/hooks/useSplatLoader.ts:2*
- **`platform.spatial.viewer`** — Renders .ply splat files loaded from a worldId API URL or a direct splatUrl prop. Camera modes: orbit (default), walk, fly. Quality: auto/low/medium/high. Whitelabel-ready via `branding` prop (custom logo, hideWatermark). FPS counter optional. Used in the platform dashboard and exportable for licensees (e.g. ImmoClip virtual tours).  
  *packages/spatial-viewer/src/SpatialViewer.tsx:1*
- **`platform.spatial.viewer.controls`** — walk) with reset-camera and screenshot buttons; designed to sit in the corner of the canvas without blocking the splat view.  
  *packages/spatial-viewer/src/SpatialControls.tsx:2*
- **`platform.spatial.viewer.toolbar`** — screenshot, and stats-overlay toggle buttons; composable into any SpatialViewer instance; color-customizable for theme matching.  
  *packages/spatial-viewer/src/SpatialToolbar.tsx:2*

### spatial/generate
- **`spatial.generate.object`** · _experimental_ · since 0.1.0 — Shortcut endpoint to generate a single 3D object (mode=object) with prompt or image.  
  *src/main.rs:659*
- **`spatial.generate.world`** · _experimental_ · since 0.1.0 — Submit text or image prompt to generate a 3D world via NANO-PATH (multi-view → Gaussian Splat).  
  *src/main.rs:257*

### spatial/jobs
- **`spatial.jobs.status`** · _experimental_ · since 0.1.0 — Poll a generation job's status (Queued/Generating/Fitting/Completed/Failed) with progress.  
  *src/main.rs:457*

### spatial/worker
- **`spatial.worker.pull`** · _experimental_ · since 0.1.0 — GPU worker long-polls the queue (≤30s) for a pending DiffSplat/MV3D task.  
  *src/main.rs:739*

### spatial/world
- **`spatial.world.download`** · _experimental_ · since 0.1.0 — Download a generated 3D world (PLY/GLTF) for client-side WebGPU rendering.  
  *src/main.rs:484*
- **`spatial.world.save-state`** · _experimental_ · since 0.1.0 — Persist a composed world state (objects, camera presets, lighting) to disk by world_id.  
  *src/main.rs:576*

---

*Generated by [openalice-atlas](https://atlas.blal.pro) — single source of truth for the openalicelabs ecosystem.*