UFOMap Documentation

repository·master·Indexed 19 days ago

https://github.com/unknownfreeoccupied/ufomap

An efficient probabilistic 3D mapping framework providing explicit representation of unknown, free, and occupied space in volumetric maps. Designed for real-time obstacle avoidance, path planning, and 3D reconstruction, it supports high-resolution mapping and includes a ROS interface (ufomap_ros) featuring a mapping server, RViz plugins, and custom messages and services for map manipulation.

Tokens
2.1K
Snippets
2
Records
12
Agent score
64%

What's inside UFOMap

  1. Overview of ufomap_ros components

    master

    The ufomap_ros package provides a ROS interface for the UFOMap framework. It is organized into several functional modules:

    • ufomap_mapping: The default UFOMap mapping server. This is the recommended entry point for users who want to quickly start mapping.
    • ufomap_msgs: Defines the ROS messages used for UFOMap data and provides utility functions to convert between ROS messages and UFOMap types.
    • ufomap_ros: Contains utility functions for converting between ROS and UFOMap types.
    • ufomap_rviz_plugins: Provides RViz plugins specifically designed to visualize UFOMap data within the RViz environment.
    • ufomap_srvs: Defines the ROS services available for interacting with UFOMap.
  2. Overview of UFOMap

    master

    UFOMap is an efficient probabilistic 3D mapping framework designed to explicitly represent unknown space alongside free and occupied space. It allows for the real-time creation of 3D volumetric maps that can be used for tasks such as:

    • Path and trajectory planning
    • Obstacle avoidance
    • 3D reconstruction

    The framework can handle high-resolution mapping (e.g., 2 mm voxel size) at real-time frequencies (e.g., 2 Hz).

  3. Ensure Required TF Transforms for ufomap_server

    master

    To use ufomap_server correctly, you must provide the following coordinate transforms:

    1. sensor data frame $\rightarrow$ map: Required for all mapping. The server must be able to transform the cloud_in point cloud into the ~frame_id.
    2. robot frame $\rightarrow$ map: Required only if ~clear_robot is set to true. This allows the server to locate the robot's current pose to clear space around it.
  4. Configure ufomap_server via ROS Parameters

    master

    The ufomap_server is configured using several private parameters (prefixed with ~). Key parameters include:

    • ~frame_id (string, default: map): The coordinate frame in which the map is published.
    • ~resolution (double, default: 0.05): Map resolution in meters (used when starting an empty map).
    • ~max_range (double, default: -1.0): Maximum range in meters for point cloud integration. Limiting this improves speed and prevents spurious points.
    • ~insert_depth (int, default: 0): The octree depth at which free space is cleared. Increasing this value (e.g., to clear at ~16cm resolution) significantly increases integration speed.
    • ~clear_robot (bool, default: false): If enabled, clears space around the robot's current position to ensure the robot is not seen as being inside occupied/unknown space.
    • ~update_part_of_map (bool, default: true): When enabled, only updated map segments are published, significantly reducing bandwidth.
    • ~publish_depth (int, default: 4): Determines which ~map_depth_X topics are published (where X is the depth level).
  5. Reference: ufomap_server Published Topics

    master

    The server provides the map through the following topics:

    TopicTypeDescription
    ~mapufomap_msgs/UFOMapStampedThe complete UFOMap as a binary stream (unknown, free, and occupied space) with metadata.
    ~map_depth_Xufomap_msgs/UFOMapStamped[OPTIONAL] Map containing only nodes down to depth X (where X is in [1, 21]). Used to reduce message size and serialization time.
  6. Supported geometric intersection tests in UFOMap

    master

    The UFOMap geometry module provides intersection testing between various geometric primitives. Use the following compatibility matrix to determine if a specific intersection test is implemented for your use case.

    Legend:

    • ✔: Implemented
    • ✖: Not implemented
    • ✖*: Implemented but known to be incorrect
    • ?: Type does not exist in the current implementation
    |                  | AABB | Frustum | Line Segment | OBB | Plane | Point | Ray | Sphere |
    | ---------------- |:----:|:-------:|:------------:|:---:|:-----:|:-----:|:---:|:------:|
    | **AABB**         | ✔    | ✔       | ✔            | ✔   | ✔     | ✔     | ✔   | ✔      |
    | **Frustum**      | ✔    | ✖       | ✖            | ✔   | ✖     | ✔     | ✖   | ✔      |
    | **Line Segment** | ✔    | ✖       | ✖            | ✔   | ✔     | ✔     | ✖   | ✔      |
    | **OBB**          | ✔    | ✔       | ✔            | ✔   | ✔     | ✖*    | ✔   | ✔      |
    | **Plane**        | ✔    | ✖       | ✔            | ✖   | ✔     | ✔     | ✔   | ✔      |
    | **Point**        | ✔    | ✔       | ✔            | ✖*  | ✔     | ✔     | ✔   | ✔      |
    | **Ray**          | ✔    | ✖       | ✖            | ✔   | ✔     | ✔     | ✖   | ✔      |
    | **Sphere**       | ✔    | ✔       | ✔            | ✔   | ✔     | ✔     | ✔   | ✔      |
  7. Reference: ufomap_server Services

    master

    The server exposes the following services for map manipulation:

    ServiceTypeDescription
    ~get_mapufomap_srvs/GetMapReturns the complete UFOMap as a binary stream with metadata.
    ~clear_volumeufomap_srvs/ClearVolumeClears a part of the map specified by a bounding volume, setting voxels to free space (based on ~clamping_thres_min).
    ~resetN/AResets the complete map.
  8. Configure the UFOMap server via Dynamic Reconfigure

    master

    The server uses dynamic_reconfigure to allow real-time tuning of mapping parameters. The configuration is managed through the ufomap_mapping::ServerConfig structure.

    When parameters are updated via the dynamic reconfigure client, the server's configCallback is triggered to apply the new settings to the underlying UFOMap instance.

  9. Use the ufomap_mapping::Server class

    master

    The ufomap_mapping::Server class is the primary interface for managing a UFOMap instance within a ROS environment. It handles incoming point cloud data, manages the underlying ufo::map::OccupancyMap or ufo::map::OccupancyMapColor, and provides ROS services for map manipulation and retrieval.

    To use the server, instantiate it with two ros::NodeHandle objects: one for the public namespace and one for private parameters.

    Key Capabilities:

    • Point Cloud Integration: Subscribes to sensor_msgs/PointCloud2 to update the map.
    • Map Management Services: Provides services to get the map, clear specific volumes, reset the map, and save the map to disk.
    • Dynamic Reconfiguration: Supports real-time parameter updates via dynamic_reconfigure using the ufomap_mapping::ServerConfig type.
    • Asynchronous Updates: Supports asynchronous map updates to prevent blocking the main ROS thread.
    #include <ufomap_mapping/server.h>
    
    // Inside a ROS node or component
    ros::NodeHandle nh;
    ros::NodeHandle nh_priv("~");
    
    // Initialize the UFOMap server
    ufomap_mapping::Server server(nh, nh_priv);
  10. Manage UFOMap via ROS Services

    master

    The ufomap_mapping::Server exposes several ROS services to interact with the active map instance. These services use custom messages from the ufomap_srvs package.

    Service NameService TypeDescription
    get_mapufomap_srvs::GetMapRetrieves the current map data.
    clear_volumeufomap_srvs::ClearVolumeClears a specific volume within the map.
    resetufomap_srvs::ResetResets the entire map to its initial state.
    save_mapufomap_srvs::SaveMapSaves the current map to a file.