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 assetstests/— Unit testsDockerfile— Multi-stage build with model selectionMakefile— Build targets for each modelrequirements_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 mappingThis 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>-mapanythingMapAnything
intel/scenescape-mapping:<version>-vggtVGGT
intel/scenescape-mapping:<version>,:latestMapAnything (default)
Individual variants can also be built with
make -C mapping build-mapanythingormake -C mapping build-vggt.
Note: The root
make build-allbuilds only the default MapAnything variant. To deploy VGGT, build it withmake -C mapping build-all(orbuild-vggt), or pull the<version>-vggtimage from Docker Hub, and point your deployment at that tag. See Deploy on Docker and Deploy on Kubernetes.
How It Works#
The
MODEL_TYPEvariable controls which model is included (mapanythingorvggt).The Dockerfile clones both model repos, but only installs and configures the selected one.
Entry points (
mapanything_service.pyorvggt_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: falseinitialization.state: "starting"
If startup fails permanently, this endpoint returns HTTP 503 with:
status: "unhealthy"ready: falseinitialization.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": {}
}