# jie_3d_nav: a ROS 2 Humble 3D navigation stack with a Web planner

> jie_3d_nav turns PCD clouds, 2D occupancy grids and Gazebo worlds into OctoMap volumes, then plans and follows 3D paths from a browser. It targets Ubuntu 22.04 with ROS 2 Humble, and the README says it was tested on the AgiBot D1 quadruped with the Odin 1 positioning module.

**6-robot/jie_3d_nav** — A ROS 2 Humble-based 3D navigation system with a web interface, tested on the AgiBot D1 quadruped robot and the Liuxing Technology Odin 1 spatial positioning module.

- Repository: https://github.com/6-robot/jie_3d_nav
- Stars: 471 · Forks: 80
- Language: Python
- License: not declared
- Published: 2026-09-20 · Updated: 2026-09-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/6-robot-jie-3d-nav

## What jie_3d_nav is for, and who should care

Most ROS 2 navigation tutorials stop at a 2D costmap. jie_3d_nav starts from the opposite assumption: the world has floors, overhangs and multi-level geometry that a flat grid cannot represent. The repository ships three ROS 2 packages. jie_map_msgs holds custom service interfaces for saving, loading and exporting map packages. jie_octomap handles OctoMap import, storage, visualisation and editing. octo_planner does 3D path planning, path tracking control, and the Web test and navigation launch files. The README states the system was tested on the AgiBot D1 quadruped and the Odin 1 spatial positioning module from Liuxing Technology. If you are building a legged or mobile platform that needs volumetric maps and a browser-based planner, that is the intended audience. If you want a drop-in Nav2 replacement, this is not it: the README never mentions Nav2, and the planner is its own package.

## How the OctoMap pipeline actually moves data

The data flow is one-directional and file-driven. An import launch starts a converter node that reads a source format and writes an OctoMap, plus a markers node that republishes occupied cells for display, a map_package_manager that persists the result, a Qt GUI for inspection, and jie_path_node from octo_planner for planning. Three importers exist. pcd_to_octomap_node reads point clouds. occupancy_grid_to_octomap_node lifts a 2D ROS grid into 3D. world_to_octomap_node converts Gazebo .world or .sdf scenes. After conversion, map_package_manager saves the map as a package directory, and map_viewer_gui lets you edit four layer types by name: occupied, preblocked, traversable and clear. That editing step is the part worth noticing. The planner does not consume raw OctoMap occupancy alone; preblocked and traversable layers are separate concepts the GUI writes, which means map quality depends on human editing, not only on the converter's output. The README documents the log fields to watch after conversion, kept_voxels and occupied_voxels, and gives a diagnostic reading: a few dozen or a few hundred kept_voxels usually means the resolution is too fine or min_points_per_voxel is too high, while a very large value usually means the same resolution problem or an over-wide crop, and Web and Qt display plus planning will slow down.

## Installing jie_3d_nav on Ubuntu 22.04 with ROS 2 Humble

The README lists Ubuntu 22.04, ROS 2 Humble, colcon, OctoMap and octomap_msgs, OpenCV, the Open3D C++ development library, PyQt5, VTK, NumPy, Pillow and PyYAML. rosbridge_server is optional and only needed if the Web page should reach ROS over websocket. The repository includes an install script for the common dependencies. Run it from inside the source checkout:

```bash
cd ~/ros2_ws/src/jie_3d_nav
bash install_deps_humble.sh
```

Build from the workspace root, not from the package source directory. The README warns explicitly that running colcon build inside src/jie_3d_nav leaves stray build, install and log directories next to your sources.

```bash
cd ~/ros2_ws
source /opt/ros/humble/setup.bash
colcon build --packages-select jie_map_msgs jie_octomap octo_planner
source install/setup.bash
```

If CMake cannot find Open3D, point it at the install tree. The README gives Open3D_DIR as the variable to set:

```bash
colcon build --packages-select jie_map_msgs jie_octomap octo_planner \
  --cmake-args -DOpen3D_DIR=/path/to/open3d_install/lib/cmake/Open3D
```

The quickest first run is the bundled Gazebo world, which opens a Qt window where you load a world, set the crop edge length, and click load to convert it into an OctoMap:

```bash
ros2 launch jie_octomap import_gazebo_world.launch.py world_name:=2_storey.world
```

Once the map is visible, click the start-point button and place a point on the map with the mouse, then the goal-point button and place a second. The documentation says a feasible path is planned and drawn. The same launch accepts field.world, and external files go through world_file with an absolute path. If both world_file and world_name are passed, world_file wins.

## Web visualisation, ports and the rosbridge dependency

The browser interface is not a separate application server. It is a static Web service plus rosbridge. The launch file web_octomap.launch.py takes map_package, pointing at a saved map package directory, and http_port, which defaults to 8080. Two further switches, launch_rosbridge and launch_map_gui, control whether the rosbridge_websocket node starts and whether the Qt save/load window opens alongside.

```bash
ros2 launch jie_octomap web_octomap.launch.py map_package:=~/maps/map
```

That design has a consequence worth stating plainly: if you leave rosbridge off, the page has no ROS connection to work with, so the Web planner is only as useful as the rosbridge setup behind it. The README also documents a failure that looks scarier than it is. When port 8080 is already taken, the launch reports OSError: [Errno 98] Address already in use. The README is explicit that this is not a robot or IP problem and that changing the port resolves it. That is a small thing, but it is the kind of error that sends people debugging their network for an hour.

## Where jie_3d_nav breaks: Open3D linking and thin licensing

The most concrete failure mode in the README is a missing shared library. If the GUI shows no OctoMap on the right side, or saving a map package reports not ready or octomap not ready, the first thing to check is whether pcd_to_octomap_node has already exited. The usual cause is that the dynamic linker cannot find an Open3D runtime dependency, with libtbb.so.12: cannot open shared object file given as the example. The README's diagnostic is to run ldd against the installed node binary and grep for not found or tbb:

```bash
ldd install/jie_octomap/lib/jie_octomap/pcd_to_octomap_node | grep -E "not found|tbb"
```

If libtbb.so.12 is not found, add the Open3D lib directory to LD_LIBRARY_PATH and relaunch:

```bash
export LD_LIBRARY_PATH=/path/to/open3d_install/lib:${LD_LIBRARY_PATH}
ros2 launch jie_octomap import_pcd_map.launch.py
```

That is a real environmental constraint, not a bug report: Open3D is a C++ dependency here, and it has to be findable at both build time and run time. Two other limits matter. The repository has no LICENSE file listed among its top-level entries, and the licence field is unknown, so you cannot tell from the repository what terms apply to redistribution or commercial use. And the full D1 navigation entry point, octo_planner/launch/nav.launch.py, starts d1_core and reads the D1 URDF, so it depends on d1_bringup and d1_description even though the README says base compilation does not need those two packages. If you do not have a D1, that launch is not your entry point.

## jie_3d_nav versus Nav2 and octomap_server

The obvious comparison is Nav2 with the octomap_server package. The difference is in where the work sits. Nav2 gives you a behaviour-tree-driven stack with costmap layers, recovery behaviours and a plugin ecosystem, and octomap_server publishes a 3D occupancy grid that a costmap layer can consume. jie_3d_nav instead treats the OctoMap as the map of record: you import it, save it as a package, edit its layers by hand in a Qt GUI, and then plan in 3D from a Web page against that edited volume. There is no behaviour tree and no recovery behaviour layer documented in the README. What you get in exchange is a closed loop from PCD, 2D grid or Gazebo world to a saved, hand-editable 3D map and a browser planner, with a path-tracking controller in octo_planner. If your robot already runs Nav2 and you only need 3D obstacle data, adding octomap_server to your existing stack is less disruptive than swapping in a different planner. If your problem is authoring and curating a 3D map across multiple floors, jie_3d_nav's editing layer is the part Nav2 does not give you.

## Maintenance, upgrade cost and what the repository does not say

The last push to the repository was on 2026-05-24. It is not archived. There are no retrieved releases, so there is no versioned artifact to pin and no changelog to read before upgrading. That shapes the upgrade cost: you are tracking a branch, not a release. The README does document two upgrade-adjacent procedures. If the source directory has moved, stale CMake caches can still point at the old path, and the README's answer is to rebuild with --cmake-clean-cache:

```bash
colcon build --packages-select jie_map_msgs jie_octomap octo_planner --cmake-clean-cache
```

If you built inside the source package directory by mistake, the README's answer is to delete the stray build, install and log directories, which are gitignored:

```bash
rm -rf build install log
```

On the Foxy side, the README describes a partial reproduction path on Ubuntu 20.04: install ros-foxy-sensor-msgs-py, expect python3-vtk7 with its vtk.qt.QVTKRenderWindowInteractor entry point rather than the newer vtkmodules path, and set Open3D_DIR or CMAKE_PREFIX_PATH if Open3D lives outside the system prefix. That is a documented workaround, not a supported configuration. On licensing, the repository lists no LICENSE file at the top level, so anyone considering redistribution should resolve that question before shipping anything built on these packages.

## Conclusion

Adopt jie_3d_nav if you already run Ubuntu 22.04 with ROS 2 Humble, have an OctoMap-shaped problem, and want a browser planner without writing one. Skip it if you need a maintained release cadence, a licence you can read, or a stack for a robot other than the D1 and Odin 1 combination the authors used. Before committing, verify that install_deps_humble.sh resolves Open3D on your machine, that ldd shows no missing libtbb.so.12 for pcd_to_octomap_node, and that the repository has a LICENSE file you can actually rely on.

## FAQ

### What is jie_3d_nav?

It is a ROS 2 Humble 3D navigation system with a Web interface, made of three packages: jie_map_msgs for map service interfaces, jie_octomap for OctoMap import, management and editing, and octo_planner for 3D path planning and tracking. The README says it was tested on the AgiBot D1 quadruped and the Odin 1 positioning module.

### Which ROS 2 and Ubuntu versions does jie_3d_nav require?

The README targets Ubuntu 22.04 with ROS 2 Humble. It also describes a partial reproduction path on Ubuntu 20.04 with ROS 2 Foxy, covering Gazebo world or PCD import into OctoMap followed by 3D path planning, with extra steps such as installing ros-foxy-sensor-msgs-py.

### How do I install and build jie_3d_nav?

Run bash install_deps_humble.sh from inside the source checkout to install common dependencies, then build from the ROS 2 workspace root with colcon build --packages-select jie_map_msgs jie_octomap octo_planner. The README warns against running colcon build inside src/jie_3d_nav, because it leaves stray build, install and log directories there.

### Why does jie_3d_nav fail with libtbb.so.12: cannot open shared object file?

That error means the dynamic linker cannot find an Open3D runtime dependency, and the README lists it as the usual reason pcd_to_octomap_node exits so that the GUI shows no OctoMap or saving reports not ready. The README suggests checking with ldd on the installed node binary and adding the Open3D lib directory to LD_LIBRARY_PATH before relaunching.

### What map formats can jie_3d_nav import?

The README lists three: PCD point cloud maps through pcd_to_octomap_node, ROS 2D occupancy grid maps through occupancy_grid_to_octomap_node, and Gazebo .world or .sdf scenes through world_to_octomap_node. All three produce an OctoMap that can be saved as a map package and edited in the Qt viewer.

## Sources

- [6-robot/jie_3d_nav on GitHub](https://github.com/6-robot/jie_3d_nav)
- [Issues](https://github.com/6-robot/jie_3d_nav/issues)
- [README](https://github.com/6-robot/jie_3d_nav/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/6-robot-jie-3d-nav