Understanding the Indoor Positioning System

The CPM Lab indoor positioning system, or IPS, estimates the pose of each vehicle from a camera image and publishes the resulting observations to the rest of the system.

The IPS is the realtime localization source for the CPM Lab. It detects the vehicles in the camera image, tracks them over time, and publishes a vehicle observation per vehicle that the vehicle controller fuses into its state.

IPS overview

The IPS pipeline starts with a Basler USB camera, then processes the image to detect LEDs, project the detections into the map frame, identify the vehicles, and track them over time.

        ---
config:
  layout: elk
  startOnLoad: false

---
flowchart LR
   subgraph "Camera"
      direction TD
      CAM[(USB camera)]
      IMG[/Image/]
   end
   subgraph "IPS"
      direction TD
      LED[LED detection]
      PROJ[Projection and undistortion]
      ID[Vehicle identification]
      TRACK[Tracking]
      OBS[/Observations/]
   end
   subgraph "muCar"
      direction TD
      STATE_UPDATE[State update]
      STATE[/State/]
   end

   CAM --> IMG
   Camera --> IPS
   LED --> PROJ --> ID --> TRACK
   TRACK --> OBS
   IPS --> muCar
   STATE_UPDATE --> STATE
   muCar --> IPS

   linkStyle 8 stroke-dasharray: 5
    

Indoor positioning pipeline

The node runs in the lab domain (ROS_DOMAIN_ID=21) in the /lab/ namespace and uses these topics, for every vehicle ID from 1 to the configured number of vehicles:

Topic	Type	Direction
/lab/vehicle_<id>/vehicleObservation	cpm_lab_lab_msgs/VehicleObservation	published (best effort)
/lab/vehicle_<id>/vehicleState	cpm_lab_lab_msgs/VehicleState	subscribed (best effort), refines the tracking
/lab/system_trigger	cpm_lab_lab_msgs/SystemTrigger	published, e.g. LED requests

The vehicle state itself is published by the vehicle controller, not by the IPS. See Interface Reference for the message fields.

Configuration

The default launch file loads a YAML configuration file and starts the IPS as a composable node in a container under /lab/. The configuration controls the camera settings, LED thresholds, projection matrices, and tracking parameters.

The default configuration includes:

• camera acquisition frame rate and exposure settings,

• LED brightness and contour thresholds,

• camera undistortion and projection parameters,

• vehicle geometry and tracking association limits,

• the number of vehicles the IPS should listen to.

The package ships with example calibration files for different lab setups. The default configuration is intended to be adjusted to the camera and room setup used in a specific CPM Lab instance.

Runtime behavior

At runtime the IPS grabs images from the camera, runs the detection pipeline, and publishes observations for vehicle IDs in the configured range. The source code currently accepts vehicle IDs from 1 to 20.

If detection fails, the node reports an error. If detection succeeds with a warning, the warning is logged but the pipeline continues. The node also keeps track of the frame rate for diagnostics.

The IPS is started by the control flow when you select the configuration of your lab in the Control Center, see Running the Lab. The configuration files are installed with the cpm_lab_indoor_positioning_system package; the camera calibration in them is created with cpm_calibrate, see IPS Camera Calibration. To use your own configuration without rebuilding, copy it to ~/cpm_lab/ips/ (or $CPM_LAB_HOME/ips/); the Control Center then offers it next to the packaged ones, see Your Own Maps and IPS Configurations.

If you run it manually, make sure it is launched in ROS_DOMAIN_ID=21 so it can publish observations to the rest of the CPM Lab:

export ROS_DOMAIN_ID=21
ros2 launch cpm_lab_indoor_positioning_system default.launch.xml config_file:=<absolute-path-to-config.yaml>