How to Build from Source#

Overview#

The Scenescape mapping service supports build-time selection of the underlying 3D reconstruction model: MapAnything or VGGT. This approach ensures only the chosen model and its dependencies are included, minimizing image size and avoiding dependency conflicts.

Each build produces a container image with a single model. The API and runtime are identical, but the model is fixed at build time.

Directory Structure#

  • src/ — Service and model code (entry points: mapanything_service.py, vggt_service.py)

  • tools/ — Utilities for downloading models and assets

  • tests/ — Unit tests

  • Dockerfile — Multi-stage build with model selection

  • Makefile — Build targets for each model

  • requirements_api.txt — API dependencies (model dependencies handled separately)

Build Instructions#

Prerequisites#

  • Docker

  • Make

  • Internet access (for model downloads)

Build Steps#

  • Clone the Repository: Clone the repository.

    git clone https://github.com/open-edge-platform/scenescape.git -b main

    Note: Adjust the repo link appropriately in case of forked repo.

  • Navigate to the Directory:

    cd scenescape

  • Build mapping:

    export MODEL_TYPE=mapanything # or MODEL_TYPE=vggt

    make mapping

How It Works#

  • The MODEL_TYPE variable controls which model is included (mapanything or vggt).

  • The Dockerfile clones both model repos, but only installs and configures the selected one.

  • Entry points (mapanything_service.py or vggt_service.py) are set up for each model.

  • Model weights are downloaded at runtime. Volume mounts ensure that the downloaded weights are persistent and do not require repeated downloads.

Testing#

See tests/README.md for detailed testing instructions.

API Documentation#

See docs/mapping-api.yaml for REST API details. The /reconstruction endpoint uses the model selected at build time.

Running the Service#

docker run -d \
    --name mapping \
    --network scenescape \
    --hostname mapping.scenescape.intel.com \
    -v vol-mapping-model-weights:/workspace/model_weights \
    -v vol-mapping-torch-cache:/workspace/.cache/torch \
    -v vol-mapping-hf-cache:/workspace/.cache/huggingface \
    intel/scenescape-mapping-${MODEL_TYPE:-mapanything}

This command sets up the container with the correct user, network, hostname, ports, and persistent volumes for model weights and caches.

API Usage#

{
  "images": [{ "data": "base64..." }],
  "output_format": "glb",
  "mesh_type": "mesh"
}

Example response:

{
  "success": true,
  "glb_data": "...",
  "camera_poses": [],
  "intrinsics": [],
  "message": "complete"
}

Validation#

Health Check#

curl https://localhost:8444/v1/health

Example response:

{
  "success": true,
  "status": "healthy",
  "model_loaded": true
}