scenescape-setup

SceneScape End-to-End Setup

Host needs Docker, docker-compose, and Python 3.10+ with requests.

Overview

This skill deploys and resumes an Intel® SceneScape environment outside the repo, gathers the required deployment inputs from the user, and orchestrates the bootstrap, calibration, scene reconstruction, and verification workflow. It is intended for first-time installs, re-runs with existing deploy-inputs.json, and targeted phase resumes such as bootstrap, calibrate, or scene when the user only needs to repeat or continue a part of the deployment.

Parameters / Arguments

Required runtime inputs for a fresh deployment: deploy_dir, streams (or video files), camera_ids, scene_name, mapping (scene map source: reconstruction default, blueprint, .glb/.ply mesh, or geospatial). Optional state fields: --phase, --fresh, and the resume flag implied by the Fast Path.

Returns / Output

Deployment artifacts in deploy_dir: deploy-inputs.json (source of truth), .deploy-state.json, orchestrator logs, calibration/reconstruction/verification outputs, and a final DEPLOY COMPLETE with a scene_uid and deployment metrics.

Error handling

Fail safely instead of guessing: mismatched/duplicate streams vs camera_ids → stop and ask for corrected inputs; unreadable prior inputs on a camera-change fresh redeploy → ask the user to confirm the retained set; missing local repo/docs → fall back to the canonical GitHub URL rather than fabricating; resume/continue signal → treat deploy-inputs.json as existing and skip Step 1 unless the user says the directory is wrong; a failed step → read only the matching troubleshooting reference, no broad log dumps.

File resolution

All scripts, references, and assets resolve relative to $SKILL_DIR, so the skill folder is self-contained and portable. docs/user-guide/... links point at the local checkout first; if unavailable (standalone skill copy), fall back to https://github.com/open-edge-platform/scenescape/blob/main/<path> instead of guessing. Never copy SceneScape repo docs into references/; reserve new references for knowledge that has no written form elsewhere.

Always-on rules (no exceptions)

• Before any deploy/resume/phase launch, read agent-guardrails.md.
• Every orchestrator launch also starts watch_orchestrator.sh on the orchestrator PID in the background, notifying on RESULT=; rely on watcher notifications instead of user-driven polling.
• Never invent camera IDs/streams/scene names; never interpolate raw inputs into ad hoc shell one-liners; destructive actions (--fresh, deleting deploy_dir, docker compose down -v) always need explicit confirmation.
• Load only the single phase/symptom reference that matches a reported failure.

Step 0 — Bootstrap skill-dir

Resolve SKILL_DIR before any other step, using the first matching strategy:

A. Scripts already on disk (scenescape repo is checked out locally):

export SKILL_DIR=<path-to-scenescape-checkout>/.github/skills/scenescape-setup

B. Extract from git (no full checkout needed — fast, leaves no branch state):

SCENESCAPE_REPO=$(find ~ -maxdepth 5 -type d -name scenescape 2>/dev/null | head -1)
git -C "$SCENESCAPE_REPO" fetch origin main
mkdir -p /tmp/scenescape-skill
git -C "$SCENESCAPE_REPO" archive origin/main \
  -- .github/skills/scenescape-setup | tar -x -C /tmp/scenescape-skill
export SKILL_DIR=/tmp/scenescape-skill/.github/skills/scenescape-setup

Verify: ls "$SKILL_DIR/scripts/deploy_scenescape.sh" must succeed before continuing.

Routing

Situation	Reference to read
New deployment (gather inputs, mapping choice, video files)	step-1-gather-inputs.md
Resume / repeat / Fast Path ("continue", "resume", unchanged inputs)	fast-path.md
Launch (full deploy, resume, or --phase orchestrator + watcher + README + handoff)	deploy-and-complete.md
Single phase: bootstrap (6–8), calibrate (9–10), scene (11–13)	phase-bootstrap.md / phase-calibrate.md / phase-scene.md
Tracking flickers, vanishes, or IDs change (same camera)	tuning-tracker.md
Cross-camera Re-ID misses / wrong person	tuning-reid.md
Keep a vision attribute from resetting	attribute-persistence.md
External non-vision sensor reading/event	singleton-sensors.md
Expected size/shape for a class (Object Library)	object-library.md
After successful deploy — what to build with scene output (required handoff)	using-scene-output.md
Generated-file layout / web-UI handoff / bootstrap-runtime-reconstruction diagnosis	operational-reference.md (only for those needs — not during routine deploy)

Tuning tracker/Re-ID behavior (reactive only)

Do not ask tuning questions upfront during Step 1 — always deploy with the shipped tracker-config.json / reid-config.json defaults first. Open the matching questionnaire only after the user reports tracking/Re-ID dissatisfaction. In that first response:

1. State which reference you opened (tuning-tracker.md or tuning-reid.md — exactly one).
2. Present that reference's numbered questionnaire in your reply.
3. In the same turn, apply symptom-derived starter values from that reference's recommendation logic to the deployed copy at <deploy_dir>/controller/tracker-config.json or <deploy_dir>/controller/reid-config.json (never the skill's assets/ originals). Show the exact JSON field changes and the exact restart command docker compose up -d --force-recreate scene.
4. Note that questionnaire answers can further refine the starter values.

Do not skip the questionnaire, and do not skip showing the deployed-path edits + scene-only restart. Load exactly one matching reference (tracker timing vs cross-camera Re-ID).

Quality & Evaluation

Automated eval cases live in evals/evals.json, one entry per example-prompts/ file (prompt_file links the two together). See benchmark/benchmark.md for the current benchmark.