Physics Service

Ground intersection and collision detection API

The Physics Service provides ground plane intersection calculations to prevent vehicles from clipping through terrain. It adjusts vehicle poses to maintain contact with the ground mesh.

Service Definition

service PhysicsService {
    rpc ground_intersection (PhysicsGroundIntersectionRequest) 
        returns (PhysicsGroundIntersectionReturn);
    rpc get_version (common.Empty) returns (common.VersionId);
    rpc get_available_scenes (common.Empty) returns (common.AvailableScenesReturn);
    rpc shut_down (common.Empty) returns (common.Empty);
}

Methods

ground_intersection

Compute ground-adjusted poses for ego vehicle and background actors.

scene_id · string · required

Scene identifier to load the correct ground mesh

now_us · uint64 · required

Start timestamp for all pose pairs (microseconds)

future_us · uint64 · required

End timestamp for all pose pairs (microseconds)

ego_data · EgoData

Ego vehicle bounding box and poses

Show EgoData

aabb · AABB · required

Axis-aligned bounding box dimensions (size_x, size_y, size_z in meters)

pose_pair · PosePair · required

Show PosePair

now_pose · Pose

Active transform local→aabb at now_us. Assumed to be already valid (copied from previous call).

future_pose · Pose

Active transform local→aabb at future_us. Physics system will adjust this pose.

other_objects · OtherObject[]

Background vehicles and actors

Show OtherObject

aabb · AABB

Object bounding box dimensions

pose_pair · PosePair

Object poses at now and future times (same structure as ego)

ego_pose · ReturnPose

Adjusted ego vehicle pose

Show ReturnPose

pose · Pose

Adjusted active transform local→aabb for bounding box center

status · Status

Update status code:

• SUCCESSFUL_UPDATE: Pose adjusted successfully
• UNKNOWN: Unknown error
• INSUFFICIENT_POINTS_FITPLANE: Not enough ground points for fit
• HIGH_TRANSLATION: Adjustment too large (translation)
• HIGH_ROTATION: Adjustment too large (rotation)

other_poses · ReturnPose[]

Adjusted poses for background objects (same order as request)

get_available_scenes

Query which scenes are available in the physics service.

scene_ids · string[]

List of scene identifiers with ground meshes

Usage Example

From alpasim_runtime/services/physics_service.py:

from alpasim_grpc.v0 import physics_pb2, physics_pb2_grpc
from alpasim_grpc.v0.common_pb2 import AABB, Pose, Vec3, Quat

# Connect to physics service
channel = grpc.insecure_channel('localhost:50052')
physics_stub = physics_pb2_grpc.PhysicsServiceStub(channel)

# Check available scenes
available = physics_stub.get_available_scenes(Empty())
print(f"Available scenes: {available.scene_ids}")

# Prepare ego vehicle data
ego_aabb = AABB(size_x=4.5, size_y=2.0, size_z=1.5)
previous_pose = Pose(
    vec=Vec3(x=10.0, y=5.0, z=0.0),
    quat=Quat(w=1.0, x=0.0, y=0.0, z=0.0)
)
future_pose = Pose(
    vec=Vec3(x=10.5, y=5.1, z=0.0),
    quat=Quat(w=0.999, x=0.0, y=0.0, z=0.044)
)

# Request ground intersection
request = physics_pb2.PhysicsGroundIntersectionRequest(
    scene_id="scene_001",
    now_us=1000000,
    future_us=1100000,
    ego_data=physics_pb2.PhysicsGroundIntersectionRequest.EgoData(
        aabb=ego_aabb,
        pose_pair=physics_pb2.PhysicsGroundIntersectionRequest.PosePair(
            now_pose=previous_pose,
            future_pose=future_pose
        )
    )
)

response = physics_stub.ground_intersection(request)

if response.ego_pose.status == physics_pb2.PhysicsGroundIntersectionReturn.SUCCESSFUL_UPDATE:
    adjusted_pose = response.ego_pose.pose
    print(f"Adjusted position: {adjusted_pose.vec}")
    print(f"Adjusted rotation: {adjusted_pose.quat}")
else:
    print(f"Physics update failed: {response.ego_pose.status}")

Status Codes

The physics service returns status codes indicating the quality of the ground fit:

SUCCESSFUL_UPDATE

# Pose was successfully adjusted to match ground
status == PhysicsGroundIntersectionReturn.SUCCESSFUL_UPDATE

Configuration

Physics service parameters can be configured in the runtime config:

• Update mode: ONCE_PER_STEP or TWICE_PER_STEP
• Threshold settings: Maximum allowed translation/rotation adjustments

See PhysicsUpdateMode in the runtime configuration schema.

Ground Mesh Format

The physics service loads ground meshes from scene USDZ files. Ground geometry should:

• Use consistent units (meters)
• Provide adequate density for vehicle wheel base
• Cover the full extent of drivable area

Coordinate Frames

AABB frame: Center of the axis-aligned bounding box

The physics service operates on bounding box center poses, not rig poses. The runtime handles frame conversions between rig and AABB frames.

Pose adjustments preserve X-Y translation while adjusting Z (height) and pitch/roll to match terrain.

Related

• Runtime Module - Integrates physics service
• Controller Service - Uses physics-adjusted poses