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 identifier to load the correct ground mesh
Start timestamp for all pose pairs (microseconds)
End timestamp for all pose pairs (microseconds)
Ego vehicle bounding box and poses Axis-aligned bounding box dimensions (size_x, size_y, size_z in meters)
Active transform local→aabb at now_us.
Assumed to be already valid (copied from previous call).
Active transform local→aabb at future_us.
Physics system will adjust this pose.
Background vehicles and actors Object bounding box dimensions
Object poses at now and future times (same structure as ego)
Adjusted ego vehicle pose Adjusted active transform local→aabb for bounding box center
Update status code:
SUCCESSFUL_UPDATE: Pose adjusted successfullyUNKNOWN: Unknown errorINSUFFICIENT_POINTS_FITPLANE: Not enough ground points for fitHIGH_TRANSLATION: Adjustment too large (translation)HIGH_ROTATION: Adjustment too large (rotation) Adjusted poses for background objects (same order as request)
get_available_scenes Query which scenes are available in the physics service.
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
INSUFFICIENT_POINTS_FITPLANE
HIGH_TRANSLATION / HIGH_ROTATION
# 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_STEPThreshold settings : Maximum allowed translation/rotation adjustments See PhysicsUpdateMode in the runtime configuration schema. 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 boxThe 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.