API Reference

C++, Python, and ROS 2 interfaces. SDK version: v1.4.2.

FusionConfig

Configuration struct for the fusion engine. Passed at runtime initialization; runtime must be stopped and restarted to apply config changes.

Field	Type	Default	Description
`lidar_model`	`LiDARModel`	`MID_16`	LiDAR channel and range profile. Affects point cloud density assumptions in the fusion pass.
`camera_mode`	`CameraMode`	`MONO`	Camera fusion mode. `NONE`, `MONO`, or `STEREO`.
`drift_model`	`DriftModel`	`WAREHOUSE_INDOOR`	Process noise model for extrinsic drift estimation. Choose the model closest to your chassis vibration profile.
`power_profile`	`PowerProfile`	`BALANCED`	`FULL`, `BALANCED`, or `LOW_POWER`. Controls GPU occupancy and update frequency.
`occ_resolution`	`float`	`0.05f`	Occupancy grid cell size in meters. Minimum `0.02f`, maximum `0.25f`.
`pred_horizons`	`std::vector<float>`	`{0.5, 1.0}`	Prediction horizons in seconds. Each value adds compute proportional to the number of tracked agents.
`degraded_policy`	`DegradedModePolicy`	`REDUCE_CONFIDENCE`	Behavior when fusion confidence drops. `REDUCE_CONFIDENCE` (continues at lower speed) or `HALT` (triggers emergency stop).

FusionFrame

Output struct delivered to the on_fusion_ready callback on each sensor cycle. All fields are read-only within the callback scope.

Field	Type	Description
`occupancy_grid`	`OccupancyGrid`	2D probability grid at configured resolution. Use `grid.at(x, y)` for per-cell occupancy probability (0.0–1.0).
`risk_scores`	`std::vector<RiskScore>`	Per-obstacle risk scores at each configured prediction horizon. Each `RiskScore` contains `obstacle_id`, `horizon_s`, and `probability`.
`pose_estimate`	`SE3Pose`	Current ego pose estimate (x, y, theta + covariance). Empty if no map is loaded.
`fusion_status`	`FusionStatus`	Status flags: `OK`, `TEMPORAL_GAP`, `DEGRADED`, `LIDAR_OFFLINE`, `CAMERA_OFFLINE`.
`latency_ms`	`uint32_t`	End-to-end latency from earliest sensor frame to callback invocation, in milliseconds.
`frame_id`	`uint64_t`	Monotonically increasing frame counter. Use for gap detection.

PathVyntRuntime

class PathVyntRuntime {
public:
  PathVyntRuntime(const FusionConfig& cfg,
                  const std::string& map_path = "");

  // Register fusion output callback
  void on_fusion_ready(std::function<void(const FusionFrame&)>);

  void start();       // Initialize sensors and start pipeline
  void stop();        // Graceful shutdown
  void spin_once();   // Process one sensor cycle (blocking)

  // Dynamic map patch (no restart required)
  void patch_map(const std::string& patch_path);
};

Python bindings

import pathvynt as pv

cfg = pv.FusionConfig()
cfg.lidar_model  = pv.LiDARModel.MID_16
cfg.power_profile = pv.PowerProfile.BALANCED

rt = pv.PathVyntRuntime(cfg)

def on_frame(frame):
    print(f"latency={frame.latency_ms}ms status={frame.fusion_status}")

rt.on_fusion_ready(on_frame)
rt.start()

while True:
    rt.spin_once()

ROS 2 interface

The ROS 2 bridge publishes fusion output to standard and PathVynt-specific topics. Subscribe to whichever your planner consumes.

Topic	Type	Rate	Description
`/pathvynt/occupancy_grid`	`nav_msgs/OccupancyGrid`	20Hz	Standard occupancy grid. Compatible with Nav2 planners.
`/pathvynt/risk_scores`	`pathvynt_msgs/RiskScoreArray`	20Hz	Per-obstacle risk scores at configured horizons.
`/pathvynt/pose`	`geometry_msgs/PoseWithCovarianceStamped`	10Hz	Localization output. Empty if no map loaded.
`/pathvynt/status`	`pathvynt_msgs/FusionStatus`	1Hz	Health and diagnostics flags.

Quickstart Configuration Guide