Terrain Raycasting API

Overview

terrainTasks.terrainRaycast provides terrain hit testing via pick(ray, options?) — a synchronous CPU raycast built on the terrain query foundation, so elevation sampling and ray intersections stay consistent.

Get the raycast context

import { terrainGraph, terrainTasks } from "@hello-terrain/three";

const graph = terrainGraph();
await graph.run({ resources: { renderer } });

const terrainRaycast = graph.get(terrainTasks.terrainRaycast);
if (!terrainRaycast) {
  // Query cache is not ready yet.
  return;
}

Direct raycasting

import { Ray } from "three";

const ray = new Ray(camera.position.clone(), camera.getWorldDirection(new Vector3()));

const hit = terrainRaycast.pick(ray, {
  maxSteps: 128,
  refinementSteps: 8,
  maxDistance: 5000,
});

if (hit) {
  marker.position.copy(hit.position);
  marker.lookAt(hit.position.clone().add(hit.normal));
}

Three.js Raycaster integration

TerrainMesh supports standard Three.js / React Three Fiber ray interactions once a terrain raycast context is attached.

terrainMesh.terrainRaycast = terrainRaycast;

After this, default raycasting pipelines can hit the terrain mesh and receive terrain-aware intersection data.

Options

RaycastOptions:

• maxSteps (default 128): linear march steps along the clipped ray segment
• refinementSteps (default 8): binary search iterations after a sign change
• maxDistance (default infinite): far clip for terrain intersection distance

Higher values improve precision on steep/complex terrain but increase query cost.