Aion - Temporal Dynamics for 3D Scene Graphs

This repository is the official implementation of the paper:

Aion: Towards Hierarchical 4D Scene Graphs with Temporal Flow Dynamics

Iacopo Catalano, Eduardo Montijano, Javier Civera, Julio Placed, and Jorge Pena-Queralta.

arXiv preprint arXiv:2512.11903, 2025
(Accepted for IEEE International Conference on Robotics and Automation (ICRA), 2026.)

Aion adds temporal flow modeling to Hydra's 3D scene graph. It learns recurring human movement patterns through navigational place nodes using the FreMEn framework, and provides predictions that can be used for time-aware path planning.

Architecture: Aion runs as a standalone ROS node that subscribes to Hydra's published scene graph — it does not modify Hydra itself.

Documentation

Document	Contents
Quick Start	Installation and first run
Configuration Guide	All parameters explained
API Reference	Topics, services, and message types
Usage Examples	Service calls, export tools, and A* planning
Understanding Aion	Concepts, architecture, and theory
Visualization Guide	Marker encoding and RViz setup

Installation

Prerequisites

• ROS Noetic on Ubuntu 20.04
• Hydra (ROS 1 version) — must be built first. Follow the Hydra installation instructions. This provides the required hydra, spark_dsg, and hydra_msgs packages.
• A people detection system publishing geometry_msgs/PoseArray (positions and facing orientations of detected people)

Build order: Hydra and spark_dsg must be built before Aion. Aion's CMakeLists uses find_package(hydra REQUIRED) and find_package(spark_dsg REQUIRED), and the C++ code includes Hydra's spatial-search utilities directly. The FremenArray dependency is included as a git submodule inside this repository and gets built alongside Aion automatically.

Build

# Create workspace (if not exists)
mkdir -p ~/aion_ws/src && cd ~/aion_ws/src

# Clone repository with submodules
git clone --recursive https://github.com/IacopomC/aion.git

# If you forgot --recursive:
cd aion && git submodule update --init --recursive && cd ..

# Build (Hydra packages must already be in the workspace or installed)
cd ~/aion_ws && catkin build

# Source workspace
source devel/setup.bash

Quick Start

# Terminal 1: Start Hydra
roslaunch hydra_ros your_hydra_launch.launch

# Terminal 2: Start Aion (also launches the FremenArray action server)
roslaunch aion temporal_dynamics.launch

# Terminal 3: Play data
rosbag play --clock your_data.bag

The launch file starts both the FremenArray action server and the Aion temporal dynamics node. The system begins learning temporal patterns automatically as soon as it receives scene-graph updates and people detections.

Key Outputs

Output	Type	Description
/aion/temporal_dynamics	MarkerArray	RViz markers encoding entropy, flow, and activity
/aion/temporal_map	AionTemporalMap	Structured temporal map for programmatic use
/aion/temporal_nodes	AionTemporalNode	Per-node prediction data
/aion/historical_nodes	AionHistoricalNode	Per-node historical data
/aion/get_prediction	Service	Single-place temporal prediction
/aion/get_all_predictions	Service	All-places temporal predictions
/aion/export_navigation_data	Service	Export graph + temporal data to JSON

Visualization: Markers are colored by entropy (blue = predictable, red = chaotic), sized by activity level, and opacity encodes confidence. In "bins" mode, all 8 direction bins are shown as individual scaled arrows per place.

Quick Configuration

Edit config/temporal_dynamics_config.yaml:

temporal_dynamics_node:
  # Core
  num_orientation_bins: 8                    # Flow direction bins (typically 8)
  detection_association_distance: 0.7        # Radius to bind hash cells to navigational nodes [m]
  update_interval_seconds: 10.0              # FreMEn model update period [s]
  min_observations: 1                        # Min detections before showing a place

  # ROS Topics
  hydra_dsg_topic: "hydra_ros_node/backend/dsg"
  people_detection_topic: "/people_detections"   # Your people detection topic

  # Layer Selection
  use_navigation_layer: true                 # true = Layer 20 (mesh places), false = Layer 3 (3D places)

  # Delayed Binding (robustness to loop closures)
  enable_delayed_binding: true               # Accumulate in hash cells, then bind to stable nodes
  stability_window_seconds: 5.0             # Wait time before binding [s]

  # Visualization
  marker_scale: 0.3
  use_sphere_markers: false                  # false = arrows (dominant direction), true = spheres
  visualization_mode: "direction"            # "direction", "entropy", or "bins" (all 8 direction bins)
  visualization_data_source: "historical"    # "historical" or "predictions"

See the Configuration Guide for the full parameter reference.

Input Data Format

Hydra Scene Graph

Subscribes to hydra_msgs/DsgUpdate and extracts navigational place nodes:

• Layer 20 (MESH_PLACES, default): 2D mesh-based navigation places
• Layer 3 (PLACES): 3D GVD-based place nodes

People Detections

geometry_msgs/PoseArray with one pose per detected person:

header:
  frame_id: "map"
poses:
  - position: {x: 1.0, y: 2.0, z: 0.0}
    orientation: {x: 0.0, y: 0.0, z: 0.707, w: 0.707}  # Movement direction

The orientation quaternion encodes the person's movement direction — the yaw component is extracted and discretized into orientation bins.

Tools

Aion includes utility scripts for data export and temporal-aware path planning:

Script	Purpose
scripts/aion_map_export_service.py	ROS service node for exporting temporal maps (JSON, numpy, CSV)
scripts/aion_map_exporter.py	CLI tool for one-shot or periodic auto-saving of map exports
scripts/temporal_astar_comparison.py	Offline standard A* vs temporal A* comparison from exported JSON
scripts/temporal_path_visualizer.py	RViz visualization of pre-computed A* paths
temporal_astar_node.py	Live temporal-aware A* ROS node (interactive via RViz)

See Usage Examples for details on each tool.

License

MIT License — see LICENSE for details.