Skip to content

[WIP] Add inventory documentation for Python API metrics #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Dumpy250 merged 3 commits into from
Feb 18, 2026
Merged

[WIP] Add inventory documentation for Python API metrics #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a32a4f8
Initial plan
Copilot Feb 18, 2026
982f49c
fix: address PR review feedback on markdown tables, typo, and vehicle…
Copilot Feb 18, 2026
fd85f2a
docs: improve consistency of computed field descriptions
Copilot Feb 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 25 additions & 25 deletions docs/metrics_catalog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,24 +30,24 @@ Bounding box extent represents half-dimensions of the actor in meters.

(Actor = carla.Vehicle)

| Metric | Units | Type | Update | Source | | | | |
| -------------------------------- | ----: | ----- | -------- | ---------------------------------------- | - | ---------------------- | - | ------------------------ |
| vehicle.transform.location.x | m | float | per tick | `vehicle.get_transform().location.x` | | | | |
| vehicle.transform.location.y | m | float | per tick | `vehicle.get_transform().location.y` | | | | |
| vehicle.transform.location.z | m | float | per tick | `vehicle.get_transform().location.z` | | | | |
| vehicle.transform.rotation.pitch | deg | float | per tick | `vehicle.get_transform().rotation.pitch` | | | | |
| vehicle.transform.rotation.yaw | deg | float | per tick | `vehicle.get_transform().rotation.yaw` | | | | |
| vehicle.transform.rotation.roll | deg | float | per tick | `vehicle.get_transform().rotation.roll` | | | | |
| vehicle.velocity.x | m/s | float | per tick | `vehicle.get_velocity().x` | | | | |
| vehicle.velocity.y | m/s | float | per tick | `vehicle.get_velocity().y` | | | | |
| vehicle.velocity.z | m/s | float | per tick | `vehicle.get_velocity().z` | | | | |
| vehicle.speed | m/s | float | per tick | ` | | vehicle.get_velocity() | | ` *(computed magnitude)* |
| vehicle.acceleration.x | m/s² | float | per tick | `vehicle.get_acceleration().x` | | | | |
| vehicle.acceleration.y | m/s² | float | per tick | `vehicle.get_acceleration().y` | | | | |
| vehicle.acceleration.z | m/s² | float | per tick | `vehicle.get_acceleration().z` | | | | |
| vehicle.angular_velocity.x | rad/s | float | per tick | `vehicle.get_angular_velocity().x` | | | | |
| vehicle.angular_velocity.y | rad/s | float | per tick | `vehicle.get_angular_velocity().y` | | | | |
| vehicle.angular_velocity.z | rad/s | float | per tick | `vehicle.get_angular_velocity().z` | | | | |
| Metric | Units | Type | Update | Source |
| -------------------------------- | ----: | ----- | -------- | ----------------------------------------------- |
| vehicle.transform.location.x | m | float | per tick | `vehicle.get_transform().location.x` |
| vehicle.transform.location.y | m | float | per tick | `vehicle.get_transform().location.y` |
| vehicle.transform.location.z | m | float | per tick | `vehicle.get_transform().location.z` |
| vehicle.transform.rotation.pitch | deg | float | per tick | `vehicle.get_transform().rotation.pitch` |
| vehicle.transform.rotation.yaw | deg | float | per tick | `vehicle.get_transform().rotation.yaw` |
| vehicle.transform.rotation.roll | deg | float | per tick | `vehicle.get_transform().rotation.roll` |
| vehicle.velocity.x | m/s | float | per tick | `vehicle.get_velocity().x` |
| vehicle.velocity.y | m/s | float | per tick | `vehicle.get_velocity().y` |
| vehicle.velocity.z | m/s | float | per tick | `vehicle.get_velocity().z` |
| vehicle.speed | m/s | float | per tick | `vehicle.get_velocity()` *(computed magnitude)* |
| vehicle.acceleration.x | m/s² | float | per tick | `vehicle.get_acceleration().x` |
| vehicle.acceleration.y | m/s² | float | per tick | `vehicle.get_acceleration().y` |
| vehicle.acceleration.z | m/s² | float | per tick | `vehicle.get_acceleration().z` |
| vehicle.angular_velocity.x | rad/s | float | per tick | `vehicle.get_angular_velocity().x` |
| vehicle.angular_velocity.y | rad/s | float | per tick | `vehicle.get_angular_velocity().y` |
| vehicle.angular_velocity.z | rad/s | float | per tick | `vehicle.get_angular_velocity().z` |


### 1.3 Control Inputs (Actor = `carla.Vehicle`)
Expand Down Expand Up @@ -151,13 +151,13 @@ Bounding box extent represents half-dimensions of the actor in meters.
## 3) Discrete Events (callbacks / lifecycle)

### 3.1 Collision Event (`carla.CollisionEvent`)
| Field | Units | Type | Source | | | | |
| ---------------------------- | ----: | ------- | ---------------------- | - | -------------- | - | -------------- |
| event.frame | frame | int | `event.frame` | | | | |
| event.timestamp | s | float | `event.timestamp` | | | | |
| event.other_actor_id | - | int | `event.other_actor.id` | | | | |
| event.normal_impulse.(x,y,z) | N·s | vector3 | `event.normal_impulse` | | | | |
| event.intensity | N·s | float | ` | | normal_impulse | | ` *(computed)* |
| Field | Units | Type | Source |
| ---------------------------- | ----: | ------- | --------------------------------------------------- |
| event.frame | frame | int | `event.frame` |
| event.timestamp | s | float | `event.timestamp` |
| event.other_actor_id | - | int | `event.other_actor.id` |
| event.normal_impulse.(x,y,z) | N·s | vector3 | `event.normal_impulse` |
| event.intensity | N·s | float | `event.normal_impulse` *(computed magnitude)* |


### 3.2 Lane Invasion Event (`carla.LaneInvasionEvent`)
Expand Down
2 changes: 1 addition & 1 deletion src/cot/carla_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

DEFAULT_HOST = "localhost"
DEFAULT_PORT = 2000
DEFAULT_TIMEOUT_S = 10.0 # This is dependant on your server setup. With 2 seconds my client refused to connect.
DEFAULT_TIMEOUT_S = 10.0 # This is dependent on your server setup. With 2 seconds my client refused to connect.

def make_client(host: str = DEFAULT_HOST, port: int = DEFAULT_PORT, timeout_s: float = DEFAULT_TIMEOUT_S) -> carla.Client:
client = carla.Client(host, port)
Expand Down
70 changes: 40 additions & 30 deletions src/scripts/probe_world_and_vehicle.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,12 @@ def get_or_spawn_vehicle(world):
continue

# Let the simulator advance so the actor has a stable transform/physics state
settings = world.get_settings()
for _ in range(3):
world.wait_for_tick()
if settings.synchronous_mode:
world.tick()
else:
world.wait_for_tick()

# Re-fetch to ensure we have the fully-registered actor
v2 = world.get_actor(v.id)
Expand All @@ -54,35 +58,41 @@ def main():
vehicles = world.get_actors().filter("vehicle.*")
print("vehicles(before):", len(vehicles))

v, spawned = get_or_spawn_vehicle(world)
print("vehicle.selected:", v.id, v.type_id, "| spawned:" , spawned)
print("vehicle.is_alive:", v.is_alive, "is_active:", v.is_active, "state:", v.actor_state)
print("vehicle.bounding_box.extent:", v.bounding_box.extent.x, v.bounding_box.extent.y, v.bounding_box.extent.z)

# Vehicle/Actor metrics
t = v.get_transform()
vel = v.get_velocity()
acc = v.get_acceleration()
ang = v.get_angular_velocity()
ctrl = v.get_control()

print("loc:", t.location.x, t.location.y, t.location.z)
print("rot:", t.rotation.pitch, t.rotation.yaw, t.rotation.roll)
print("speed(m/s):", vec_mag(vel))
print("acc(m/s^2):", vec_mag(acc))
print("ang(rad/s):", vec_mag(ang))
print("control:", ctrl.throttle, ctrl.steer, ctrl.brake)
print("vel_vec(m/s):", vel.x, vel.y, vel.z)
print("acc_vec(m/s^2):", acc.x, acc.y, acc.z)
print("ang_vec(rad/s):", ang.x, ang.y, ang.z)

# Traffic light related
is_at = v.is_at_traffic_light()
print("is_at_traffic_light:", is_at)
if is_at:
state = v.get_traffic_light_state()
name = getattr(state, "name", None)
print("traffic_light_state:", name if name else state)
v = None
spawned = False
try:
v, spawned = get_or_spawn_vehicle(world)
print("vehicle.selected:", v.id, v.type_id, "| spawned:" , spawned)
print("vehicle.is_alive:", v.is_alive, "is_active:", v.is_active, "state:", v.actor_state)
print("vehicle.bounding_box.extent:", v.bounding_box.extent.x, v.bounding_box.extent.y, v.bounding_box.extent.z)

# Vehicle/Actor metrics
t = v.get_transform()
vel = v.get_velocity()
acc = v.get_acceleration()
ang = v.get_angular_velocity()
ctrl = v.get_control()

print("loc:", t.location.x, t.location.y, t.location.z)
print("rot:", t.rotation.pitch, t.rotation.yaw, t.rotation.roll)
print("speed(m/s):", vec_mag(vel))
print("acc(m/s^2):", vec_mag(acc))
print("ang(rad/s):", vec_mag(ang))
print("control:", ctrl.throttle, ctrl.steer, ctrl.brake)
print("vel_vec(m/s):", vel.x, vel.y, vel.z)
print("acc_vec(m/s^2):", acc.x, acc.y, acc.z)
print("ang_vec(rad/s):", ang.x, ang.y, ang.z)

# Traffic light related
is_at = v.is_at_traffic_light()
print("is_at_traffic_light:", is_at)
if is_at:
state = v.get_traffic_light_state()
name = getattr(state, "name", None)
print("traffic_light_state:", name if name else state)
finally:
if spawned and v is not None and getattr(v, "is_alive", False):
v.destroy()

if __name__ == "__main__":
main()