Spatial AR API

Separate placement, attachment, and appearance

An AR object has several distinct relationships to the scene. It needs a candidate placement, an intentional confirmation, and a way to maintain the intended attachment. It also needs a visual treatment that remains understandable as real objects overlap it.

Treat these as separate responsibilities. The hit-testing guide focuses on preview and confirmation. The anchor guide focuses on ongoing relationships and lifecycle. The depth and occlusion guide focuses on the evidence used for visual integration.

Begin with one clear placement task

Use a simple model whose scale and orientation are obvious. Provide an understandable preview, confirm action, and repositioning path. Define what the application should do when no suitable candidate is available instead of leaving a stale reticle that implies confidence.

Keep the model's import conventions out of the placement logic. A bad pivot or reversed axis should not be hidden behind unexplained corrections in unrelated input handlers. A controlled test asset makes these boundaries easier to check.

Preserve meaning when tracking changes

Write down what should remain together when the scene estimate changes. Related pieces of one exhibit may need a shared logical root, while independent annotations may have separate attachment requirements. Group objects by intended behavior rather than by the number of mesh files.

Define a useful uncertainty state. Some experiences can gracefully reduce their visual effect; others should pause a precision-dependent action. Explain the state and provide a deliberate recovery route rather than asking the user to guess why content moved or disappeared.

Evaluate the real experience

Test acquisition, candidate loss, confirmation, repositioning, interruption, and exit. Record geometry issues separately from confusing instructions. A single appealing screenshot does not show whether a new visitor understood the interaction or could recover from a mistaken placement.

Before adding semantic labels, visit the spatial AI hub. Geometry, predicted meaning, and user-confirmed choices should remain distinguishable in both the data model and the interface.