arkit-spatial-sensing-workflow

name	arkit-spatial-sensing-workflow
description	Guide ARKit world tracking, anchors, planes, ray casting, feature points, scene depth, smoothed depth, LiDAR scene reconstruction, meshes, classification, environment texturing, world maps, relocalization, reference images and objects, geographic anchors, visionOS providers, privacy, and diagnostics. Use when Apple-platform spatial sensing or environment understanding is primary.

ARKit Spatial Sensing Workflow

Purpose

Guide ARKit environment sensing while preserving the platform-specific session model, typed spatial data, tracking quality, authorization, privacy, and rendering/scanning handoffs.

When To Use

• Use for world tracking, planes, anchors, ray casting, scene depth, LiDAR reconstruction, meshes, environment understanding, maps, relocalization, and visionOS ARKit providers.
• Recommend camera-capture-depth-workflow for camera controls, photo/video capture, calibrated camera depth, or synchronized camera outputs.
• Recommend arkit-face-body-tracking-workflow for TrueDepth face geometry or body skeleton tracking.

Single-Path Workflow

1. Classify the spatial task:
   • world tracking and tracking-state repair
   • plane, image, object, or geographic detection
   • ray casting, hit testing, feature points, or measurement
   • scene depth or smoothed scene depth
   • scene reconstruction, mesh geometry, or classification
   • environment texturing or probes
   • world-map persistence, sharing, or relocalization
   • visionOS authorization and provider lifecycle
2. Apply the Apple docs gate:
   • read current ARKit documentation for the selected platform and capability
   • state the documented behavior relied on
   • apply ../../shared/references/apple-spatial-data-privacy-contract.md
   • check supportsFrameSemantics, supportsSceneReconstruction, configuration support, provider support, authorization, and device capability before configuration
3. Choose the platform shape:
   • on iOS/iPadOS, configure and own ARSession with the appropriate ARConfiguration
   • on visionOS, request the documented ARKitSession authorization and run only the required data providers
   • do not hide those different lifecycles behind a generic spatial session
4. Preserve spatial evidence:
   • keep anchor identifiers, transforms, timestamps, tracking state, world origin, coordinate conventions, depth confidence, mesh geometry/classification, map state, and provider events typed
   • distinguish estimated geometry from measured truth
5. Define presentation and scanning handoffs:
   • use RealityKit for entity/scene presentation and interaction when appropriate
   • use RoomPlan for documented room-capture and structured-room workflows
   • use SceneKit only for an existing SceneKit rendering surface or a documented requirement
   • use Metal for advanced rendering or compute that RealityKit/Core Image cannot express
6. Return documented behavior, capability and authorization evidence, platform session/provider plan, coordinate and data lifecycle, privacy policy, diagnostics, validation, and handoffs.

Inputs

• request: spatial-sensing task or implementation under repair.
• spatial_goal: world, planes, raycast, depth, mesh, environment, map, image, object, geo, visionos, or repair.
• platform_context: platform, deployment target, intended devices, and rendering framework.
• data_context: persistence, sharing, server, collaboration, or local-only requirements.

Outputs

• status: success, handoff, or blocked.
• path_type: primary for ARKit spatial sensing, fallback for camera capture, face/body, RoomPlan, rendering, or execution.
• output: documented behavior, capability/authorization matrix, lifecycle, coordinates, data/privacy plan, diagnostics, validation, and handoffs.

Guards and Stop Conditions

• Do not assume LiDAR, scene depth, reconstruction, classification, geo tracking, image/object detection, or provider support from a device name or OS version.
• Do not wrap iOS ARSession and visionOS ARKitSession providers in a fake common lifecycle.
• Do not treat an anchor transform, raycast, feature point, depth sample, plane extent, or reconstructed mesh as exact ground truth.
• Do not persist or transmit world maps, meshes, room geometry, images, location anchors, or bystander-derived spatial data without an explicit purpose, consent/notice, retention, and deletion policy.
• Do not claim relocalization, metric accuracy, occlusion quality, mesh classification, or device performance without physical-device evidence.
• Do not silently reset tracking or the world origin; explain what spatial continuity is lost.
• Stop when authorization, device support, tracking conditions, or required physical validation is unavailable.

Fallbacks and Handoffs

• Recommend arkit-face-body-tracking-workflow for face and body anchors, geometry, blend shapes, eyes, skeletons, and scale.
• Recommend camera-capture-depth-workflow for camera devices, controls, photo/video, calibrated depth, and synchronized capture.
• Recommend vision-image-analysis-workflow for image-frame recognition and pose analysis outside ARKit tracking.
• Recommend RealityKit for scene presentation and interaction, RoomPlan for room capture, SceneKit for existing SceneKit surfaces, and Metal for advanced rendering.
• Recommend xcode-build-run-workflow for privacy configuration, authorization, build, run, physical-device logs, or profiling.
• Recommend xcode-testing-workflow for transform fixtures, provider state tests, saved-map fixtures, and device test plans.
• Recommend explore-apple-swift-docs for current ARKit or related framework research.

Customization

Use references/customization-flow.md. This workflow defines no runtime-enforced knobs.

References

• references/world-tracking-depth-meshes-and-maps.md
• references/visionos-providers-rendering-and-diagnostics.md
• references/customization-flow.md
• ../../shared/references/apple-spatial-data-privacy-contract.md
• Recommend references/snippets/apple-xcode-project-core.md for reusable Xcode-project policy.

Script Inventory

• scripts/customization_config.py