asm_droan

DROAN — Disparity-space Representation for Obstacle Avoidance and Navigation (Dubey, Arora, Scherer — 2018) — packaged as an AirStack module: a reactive, map-free local planner that avoids obstacles directly in the stereo disparity image, in two implementations plus the CPU implementation's world-model pipeline.

DROAN was AirStack's in-tree local planner through 0.20.x. From AirStack 0.21 the default local planner is the map-based MIGHTY module, and DROAN lives here, selectable through the full_droan / full_droan_cpu reference stacks. Both planners serve the same seam — the tasks/navigate NavigateTask action in, trajectory_controller/* trajectory segments out — so swapping between them is one include line in a stack entry file.

When to pick DROAN over MIGHTY

• Depth-camera-only vehicles. DROAN needs a stereo disparity image (or a depth image, for the CPU pipeline) and nothing else; MIGHTY's voxel world model consumes a 3D lidar cloud.
• Tiny compute budgets. DROAN keeps no persistent map: the GPU variant runs a few OpenGL shader passes per frame, the CPU variant a rolling graph of expanded disparity keyframes. There is no mapper process.
• Legacy comparisons. The 0.20.x full_default behaviour, byte-for-byte: trunk's stacks/full_droan is that topology with this module pinned.

Where clutter is dense and clearance margins matter, prefer MIGHTY: DROAN's accumulated collision votes cannot be erased by looking again (cluttered pockets become absorbing hover states), and its forward-only stereo field of view plus voxel quantisation produce close-quarters near-contacts. The side-by-side judged evaluation that motivated the default swap is in the asm_mighty README.

Packages

Package	Role	Used by
droan_gl	GPU planner (OpenGL): true-sphere disparity expansion + disparity graph + trajectory-library scoring in shaders; serves NavigateTask	full_droan
droan_local_planner	CPU planner: trajectory-library scoring against a pluggable cost map; serves NavigateTask	full_droan_cpu
disparity_expansion	CPU world model stage 1: C-space expansion of the disparity image by the robot radius	full_droan_cpu
disparity_graph	CPU world model stage 2: rolling window of expanded-disparity keyframes with camera poses	droan_local_planner (library)
disparity_graph_cost_map	CPU world model stage 3: cost-map plugin answering collision-cost queries from the graph	droan_local_planner (plugin)
cost_map_interface	The abstract cost-map plugin interface the CPU planner loads through pluginlib	droan_local_planner, disparity_graph_cost_map

Trunk-side dependencies (present in every AirStack robot image): trajectory_library (candidate trajectories + Trajectory/Waypoint utilities), trajectory_controller, airstack_common, airstack_msgs, task_msgs.

Architecture

flowchart LR
    SIP[stereo_image_proc<br/>disparity] --> GL[droan_gl<br/>GPU expansion + graph + scoring]
    SIP --> DE[disparity_expansion]
    DE --> DLP[droan_local_planner<br/>CPU scoring via disparity_graph_cost_map]
    GP[global_plan] --> GL
    GP --> DLP
    LA[trajectory_controller<br/>look_ahead / tracking_point] --> GL
    LA --> DLP
    NAV[NavigateTask<br/>tasks/navigate] --> GL
    NAV --> DLP
    GL -- trajectory_segment_to_add --> TC[trajectory_controller]
    DLP -- trajectory_segment_to_add --> TC

Loading

A stack runs one of the two planners: droan_gl alone (GPU), or droan_local_planner + disparity_expansion (CPU). Both plan from the trajectory controller's look-ahead point and stream airstack_msgs/TrajectoryXYZVYaw segments back to it.

Install

airstack module add https://github.com/castacks/asm_droan --version v0.1.0
airstack up --stack full_droan --sim isaac        # GPU droan_gl
airstack up --stack full_droan_cpu --sim isaac    # CPU droan_local_planner + disparity_expansion

Trunk's full_droan and full_droan_cpu reference stacks pin this module in their modules.repos; airstack up --stack <name> adds the pin to the checkout and syncs it automatically when it is missing. The droan_gl link dependencies (libassimp-dev libgl1-mesa-dev libegl-dev libglfw3-dev libglm-dev, module.yaml deps.apt) enter the robot image as a tier-1 module layer — airstack up composes it (airstack module lock --build) when it is absent. Requires AirStack 0.21.0-dev.10 or newer: older trunks still ship these packages in-tree.

Interfaces (canonical launch args)

Every cross-module endpoint is a declared launch arg with a canonical default (RFC #379 canonical-defaults rule — no remaps in module launch files):

Launch file	Arg	Default	Direction
droan_gl.launch.xml	droan_gl_disparity_topic	/$ROBOT_NAME/perception/stereo_image_proc/disparity	in
	droan_gl_camera_info_topic	/$ROBOT_NAME/sensors/front_stereo/right/camera_info	in
	droan_gl_global_plan_topic	/$ROBOT_NAME/global_plan	in
	droan_gl_look_ahead_topic / droan_gl_tracking_point_topic	/$ROBOT_NAME/trajectory_controller/{look_ahead,tracking_point}	in
	droan_gl_set_trajectory_mode_topic	/$ROBOT_NAME/trajectory_controller/set_trajectory_mode	out
	droan_gl_trajectory_segment_topic	/$ROBOT_NAME/trajectory_controller/trajectory_segment_to_add	out
	droan_gl_navigate_task_action	/$ROBOT_NAME/tasks/navigate	serves
droan_local_planner.launch.xml	droan_local_planner_*	same endpoints as above (no disparity input — it reads disparity_expansion's clouds by relative name in the shared droan namespace)
disparity_expansion.launch.xml	disparity_expansion_disparity_topic	/$ROBOT_NAME/perception/stereo_image_proc/disparity	in
	disparity_expansion_depth_topic	none (optional ground-truth depth source)	in
	disparity_expansion_camera_info_topic	/$ROBOT_NAME/sensors/front_stereo/right/camera_info	in

ros2 launch <pkg> <file> --show-args prints the full list with descriptions. A stack that feeds DROAN a different disparity source (e.g. MAC-VO, trunk's full_macvo) passes droan_gl_disparity_topic as an include arg — the single-locus rule.

Configuration

• droan_gl/config/droan_gl.yaml — expansion radius, disparity-graph size and thresholds, planning rate, rewind (stuck-recovery) thresholds, trajectory library selection.
• droan_local_planner/config/droan.yaml — cost weights (safety / deviation / forward progress), cost-map plugin (disparity_graph_cost_map::DisparityGraphCostMap), trajectory library.
• disparity_expansion/config/disparity_expansion_params.yaml — robot radius, disparity range, downsampling.

Each package README documents its parameters in full.

Testing

Module CI (.github/workflows/ci.yml) calls trunk's reusable module-system-tests.yml with test_stack/ — the GPU droan_gl topology — through build_docker, build_packages and liveliness. The packages ship no co-located unit tests.

Provenance

Extracted from castacks/AirStack develop at 0.21.0-dev.9 with git filter-repo — the packages' full history (2024 ROS 1 port onward) is preserved in this repo. TRUNK_REMOVAL.md is the checklist the trunk-side removal PR followed.