HDL Localization Changes

This page explains how hdl_localization was adapted so it can localize against the FYP map while fitting the FAST-LIVO2 frame chain.

1. Upstream Source

Upstream repositories:

• https://github.com/koide3/hdl_localization
• https://github.com/koide3/hdl_global_localization

The hdl_global_localization package is almost unchanged in this repository. The meaningful local changes are mainly in hdl_localization.

2. Main Goal Of The Changes

Upstream hdl_localization is written as a general-purpose 3D localization package.

The FYP version adapts it so that:

• it consumes the point cloud output used by the current mapping stack
• it localizes against the FYP map files instead of the upstream example map
• it fits the camera_init / aft_mapped frame chain used elsewhere in the project

3. Launch-Level Changes

The main differences are in:

• hdl_localization/launch/hdl_localization.launch

Compared with upstream, the FYP launch changes:

• points_topic from /velodyne_points to /cloud_registered
• odom_child_frame_id from velodyne to aft_mapped
• robot_odom_frame_id from odom to camera_init
• globalmap_pcd from the upstream sample map.pcd to an FYP point cloud map such as LS_123_raw_points.pcd

These are not cosmetic changes. They rewire the package into the actual FYP frame and map conventions.

4. Map Integration

The FYP repository contains multiple deployment point clouds under:

• hdl_localization/data

Examples include:

• LS_123_raw_points.pcd
• LS_123_downsampled_points.pcd
• LS_2_3_update_raw_points.pcd
• LS_2_3_update_downsampled_points.pcd

This is a practical difference from upstream.

Upstream ships a sample map. The FYP version treats the localization map as a project artifact that changes with the deployment environment.

5. NDT Parameter Changes

The FYP launch also changes some matching parameters:

• ndt_resolution from 1.0 to 0.5
• downsample_resolution from 0.1 to 0.3
• specify_init_pose from true to false

These changes indicate a shift from a demo-style launch toward a runtime workflow where:

• initial pose is not hard-coded
• localization should cooperate with the rest of the system
• map matching is tuned for the actual deployment map and robot behavior

6. Why Frame Changes Matter

The most important conceptual change is the frame contract.

The FYP stack does not treat hdl_localization as an isolated module. It is inserted into a chain where:

• FAST-LIVO2 provides odometry and mapping frames
• navigation depends on those frames
• multi-floor switching later adds height-offset logic on top

So the frame choices in the modified launch file are what make the later layers possible.

Without these changes, hdl_localization would still run, but it would not agree with the rest of the FYP system.

7. ARM / Jetson Build Change

The local hdl_localization package also changes:

• hdl_localization/CMakeLists.txt

On aarch64, the FYP version switches the build from C++11 to C++17.

This is a practical deployment change for the Jetson-based target environment. It is not part of the original upstream behavior.

8. Relationship To Multi-Floor Navigation

hdl_localization itself is still a localization package, not a multi-floor mission package.

However, in this FYP it becomes part of the multi-floor system because:

• it provides the localization base state
• its TF output is later frozen or compensated by hdl_killer.py
• the deployment map path changes whenever the environment changes

So the FYP modification is not only parameter tuning. It is a system-integration change.