Spatial Design System

Appearance

ar-placement-utils ​

The ar-placement-utils.js file provides a comprehensive set of utility functions for AR object placement. It handles surface detection, validation, orientation, and placement of objects in augmented reality experiences.

Overview ​

This utility is designed to work with the A-Frame AR ecosystem, particularly with the place-object and place-object-manager components. It provides consistent handling of:

  • Surface type detection (floor, wall, ceiling)
  • Surface validation
  • Object orientation and rotation
  • Placement logistics for different surface types

Core Functions ​

Surface Detection ​

javascript
// Detect the type of surface from a hit test result
const surfaceType = ARPlacementUtils.detectSurfaceType(hitMesh);
// Returns: "floor", "wall", "ceiling", or "unknown"

The detection uses surface normal to determine the type:

  • floor: Surfaces with normal pointing upward (y > 0.85)
  • wall: Surfaces with near-horizontal normal (|y| < 0.15)
  • ceiling: Surfaces with normal pointing downward (y < -0.85)

Surface Validation ​

javascript
// Check if a surface is valid for placement
const isValid = ARPlacementUtils.isSurfaceValid(
  hitMesh,
  ["horizontal", "wall"]  // Allowed surface types
);

// Validate height constraints
const isHeightValid = ARPlacementUtils.isHeightValid(
  hitMesh,
  { x: 0.3, y: 2.0 }  // Min/max height range
);

// Validate distance from camera
const isDistanceValid = ARPlacementUtils.isDistanceValid(
  hitMesh,
  camera,
  { x: 0.5, y: 5.0 }  // Min/max distance range
);

Placement ​

The main placement function handles all the complexity of placing objects on different surface types:

javascript
ARPlacementUtils.placeObject(entity, hitMesh, {
  adjustOrientation: true,   // Should orientation be adjusted to surface?
  faceCamera: true,          // Should object face the camera?
  scale: 1.0,                // Scale factor
  camera: cameraEntity,      // Camera reference
  customRotation: { x: 0, y: 45, z: 0 }  // Custom rotation in degrees
});

Implementation Details ​

Surface Normal Calculation ​

javascript
// Get the surface normal from a hit mesh
const normal = ARPlacementUtils.getSurfaceNormal(hitMesh);

The normal vector is crucial for determining surface type and orientation.

Rotation Handling ​

javascript
// Reset rotation to identity
ARPlacementUtils.resetRotation(entity);

// Apply custom rotation in degrees
ARPlacementUtils.applyCustomRotation(entity, { x: 0, y: 90, z: 0 });

Usage Example ​

javascript
// When an AR hit test result is available
function onHitResult(hitTestResult) {
  // First validate the surface
  if (ARPlacementUtils.isSurfaceValid(hitTestResult, ["horizontal", "wall"]) &&
      ARPlacementUtils.isHeightValid(hitTestResult, { x: 0.3, y: 1.8 })) {

    // Get surface type
    const surfaceType = ARPlacementUtils.detectSurfaceType(hitTestResult);

    // Place the object
    ARPlacementUtils.placeObject(myEntity, hitTestResult, {
      faceCamera: true,
      camera: sceneCamera,
      customRotation: { x: 0, y: 0, z: 0 }
    });
  }
}

Integration with place-object Components ​

This utility is used internally by both:

The shared utility ensures consistent placement behavior across the entire AR placement system.