SAM3DServer (Standalone)

Standalone SAM/SAM3D HTTP backend service (SAM3 is intentionally excluded). This repository has no runtime dependency on VIGA.

Detailed environment setup tutorial:

• ENV_SETUP.md

Features

• POST /v1/jobs/segment-image: submit a 2D segmentation job
• POST /v1/jobs/reconstruct-scene: submit a SAM + SAM3D reconstruction job
• GET /v1/jobs/{job_id}: query job status
• GET /v1/jobs/{job_id}/artifacts: list job artifacts (supports ?extensions=glb,json filtering)
• GET /v1/jobs/{job_id}/artifacts/{name}: download one artifact
• GET /v1/jobs/{job_id}/artifacts/download?extensions=glb,json: download only selected artifact formats as a zip
• GET /healthz: service health check

Internal services:

• sam3d_server.sam_service (port 9001, internal only, SAM segmentation)
• sam3d_server.sam3d_service (port 9002, internal only, SAM3D reconstruction)
• sam3d_server.main_service (port 8004, public API/orchestration)

Project Layout

• sam3d_server/: HTTP service source code
• workers/: standalone CLI workers (sam_worker.py, sam3d_worker.py)
• mcp_tools/sam_init.py: MCP compatibility wrapper (heavy compute fully offloaded to HTTP service)
• scripts/ensure_models.sh: lazy model download/check script
• scripts/start_sam_http.sh: one-command startup for all three services
• requirements/: local dependency lock files used by Docker/local setup
• examples/: Python client examples
• Dockerfile: single-container deployment
• third_party/sam, third_party/sam3d: migrated and registered submodules

Submodule Setup

git submodule update --init --recursive third_party/sam third_party/sam3d

Docker Compose Quick Start (Pull + Up)

export HF_TOKEN=xxx
bash scripts/docker_compose_up.sh up

Notes:

• Compose image default: fishwowater/sam3dserver:latest.
• Public API is exposed on 8004, internal SAM/SAM3D services are on 9001/9002.
• SAM checkpoint is downloaded to /models/sam/ if missing.
• SAM3D checkpoints are downloaded from Hugging Face if missing (requires HF_TOKEN).

Optional direct command:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml up -d

Local Start (Optional)

If local conda envs sam and sam3d-objects are ready:

bash scripts/start_sam_http.sh start

Shutdown / status:

bash scripts/start_sam_http.sh stop
bash scripts/start_sam_http.sh status

Python Client Examples

Assume you place two images at:

• assets/image1.jpg
• assets/image2.jpg

Then run:

python examples/client_segment_image.py
python examples/client_reconstruct_scene.py

Both examples will:

• submit a job
• poll status until succeeded or failed
• download a filtered artifact zip to output/<job_id>/ (default: glb,json, configurable via DOWNLOAD_EXTENSIONS)

MCP Compatibility

If you still want MCP-based invocation:

• Use mcp_tools/sam_init.py
• Pass sam_http_base_url in initialize(args) (default: http://127.0.0.1:8004)