Build Mapping Service 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
    
    export MODEL_TYPE=vggt
    
    make mapping
    

    This produces a single image tagged intel/scenescape-mapping:<version> containing the selected model.

  • Build all variants (optional):

    make -C mapping build-all
    

    This builds both models and produces the same tags as the published images on Docker Hub:

    Tag

    Model

    intel/scenescape-mapping:<version>-mapanything

    MapAnything

    intel/scenescape-mapping:<version>-vggt

    VGGT

    intel/scenescape-mapping:<version>, :latest

    MapAnything (default)

    Individual variants can also be built with make -C mapping build-mapanything or make -C mapping build-vggt.

Note: The root make build-all builds only the default MapAnything variant. To deploy VGGT, build it with make -C mapping build-all (or build-vggt), or pull the <version>-vggt image from Docker Hub, and point your deployment at that tag. See Deploy on Docker and Deploy on Kubernetes.

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.

Runtime Dependency Policy#

The production images install the shared API requirements and the selected model’s requirements together with its editable package in one dependency resolution. Upstream demo requirements are not installed: the service exposes its Flask API, not the standalone Gradio, Viser, or COLMAP demos. Gradio’s Pillow constraint conflicts with the patched Pillow version required by the service.

The model sources receive small, checked-in runtime dependency patches during the build. These align the upstream OpenCV metadata with the service’s headless OpenCV pin, align VGGT’s NumPy metadata with its runtime requirements, and remove an unused Gradio import from VGGT’s visualization helper. Review these patches when updating the upstream model commits.

For MapAnything, the build also verifies the SHA-256 of the UniCeption 0.1.6 source archive and patches out its unused TorchAudio dependency. This keeps Torch 2.13 without installing TorchAudio for a different Torch release. The patched package participates in normal dependency resolution; dependency checks are not bypassed. Review the archive hash and patch when updating UniCeption.

Dependency installation and pip check must succeed or the build fails. Before publishing, verify model imports, image preprocessing and mesh export in both variants, run the Mapping tests, and scan the final runtime images with Trivy. Standalone upstream demo applications are not supported by these production images.

Testing#

See tests/README.md for detailed testing instructions.

API Documentation#

See API Reference 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

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",
  "ready": true,
  "model": "mapanything",
  "model_loaded": true,
  "device": "cpu",
  "initialization": {
    "state": "ready",
    "stage": "model_loaded",
    "progress": 100.0,
    "message": "model loaded",
    "error": null
  }
}

During startup, this endpoint may return HTTP 202 with:

  • status: "degraded"

  • ready: false

  • initialization.state: "starting"

If startup fails permanently, this endpoint returns HTTP 503 with:

  • status: "unhealthy"

  • ready: false

  • initialization.state: "failed"

You can poll startup progress without reading logs:

while true; do
  curl -ks https://localhost:8444/v1/health | jq '.status, .ready, .initialization'
  sleep 2
done

Model Information#

curl https://localhost:8444/v1/models

The response shows single model details. For example:

{
  "model": "mapanything",
  "model_info": {
    "name": "mapanything",
    "description": "Universal Feed-Forward Metric 3D Reconstruction",
    "loaded": true,
    "native_output": "pointcloud",
    "supported_outputs": ["pointcloud", "mesh"]
  },
  "camera_pose_format": {}
}