Skip to content

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.