{"id":18621352,"url":"https://github.com/ethz-asl/dynablox","last_synced_at":"2025-05-15T20:05:29.768Z","repository":{"id":153803192,"uuid":"578218054","full_name":"ethz-asl/dynablox","owner":"ethz-asl","description":"Real-time detection of diverse dynamic objects in complex environments.","archived":false,"fork":false,"pushed_at":"2025-03-09T21:17:07.000Z","size":84842,"stargazers_count":494,"open_issues_count":2,"forks_count":63,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-19T02:14:51.725Z","etag":null,"topics":["detection","diverse","dynablox","dynamic","environment","mapping","moving","objects","real-time","volumetric"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ethz-asl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-12-14T14:33:17.000Z","updated_at":"2025-04-18T05:47:30.000Z","dependencies_parsed_at":"2024-11-07T04:11:47.050Z","dependency_job_id":"aa1cf479-8883-4c2b-be83-30068cdae570","html_url":"https://github.com/ethz-asl/dynablox","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethz-asl%2Fdynablox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethz-asl%2Fdynablox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethz-asl%2Fdynablox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethz-asl%2Fdynablox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ethz-asl","download_url":"https://codeload.github.com/ethz-asl/dynablox/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414499,"owners_count":22067272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["detection","diverse","dynablox","dynamic","environment","mapping","moving","objects","real-time","volumetric"],"created_at":"2024-11-07T04:11:19.918Z","updated_at":"2025-05-15T20:05:23.666Z","avatar_url":"https://github.com/ethz-asl.png","language":"C++","funding_links":[],"categories":["Softwares and Libraries"],"sub_categories":[],"readme":"![Ubuntu 20.04 + ROS Noetic: Build](https://github.com/ethz-asl/dynablox/actions/workflows/build_test_20.yml/badge.svg)\n\n# Dynablox\nAn online volumetric mapping-based approach for real-time detection of diverse dynamic objects in complex environments.\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width='100%' src=\"https://user-images.githubusercontent.com/36043993/232650770-a042cbb9-c251-42f9-8a96-d7d9273fec96.gif\"\u003e\n\u003c/p\u003e\n\n# Table of Contents\n**Credits**\n* [Paper](#Paper)\n* [Video](#Video)\n* [News](#News)\n\n**Setup**\n* [Installation](#Installation)\n* [Datasets](#Datasets)\n\n**Examples**\n- [Running a DOALS sequence](#Running-a-DOALS-sequence)\n- [Running a Dynablox sequence](#Running-a-Dynablox-sequence)\n- [Running and Evaluating an Experiment](#Evaluating-an-Experiment)\n\n# Paper\nIf you find this package useful for your research, please consider citing our paper:\n\n* Lukas Schmid, Olov Andersson, Aurelio Sulser, Patrick Pfreundschuh, and Roland Siegwart. \"**Dynablox: Real-time Detection of Diverse Dynamic Objects in Complex Environments**\" in *IEEE Robotics and Automation Letters (RA-L)*, Vol. 8, No. 10, pp. 6259 - 6266, October 2023. \\[ [IEEE](https://ieeexplore.ieee.org/document/10218983) | [ArXiv](https://arxiv.org/abs/2304.10049) | [Video](https://www.youtube.com/watch?v=NA13fRWlqRQ) \\]\n  ```bibtex\n  @article{schmid2023dynablox,\n    title={Dynablox: Real-time Detection of Diverse Dynamic Objects in Complex Environments},\n    author={Schmid, Lukas, and Andersson, Olov, and Sulser, Aurelio, and Pfreundschuh, Patrick, and Siegwart, Roland},\n    booktitle={IEEE Robotics and Automation Letters (RA-L)},\n    year={2023},\n    volume={8},\n    number={10},\n    pages={6259 - 6266},\n    doi={10.1109/LRA.2023.3305239}}\n  }\n  ```\n  \n## Video\nA brief overview of the problem, approach, and results is available on youtube:\n[\u003cimg src=https://user-images.githubusercontent.com/36043993/233706937-1ccd0c03-d86b-4e4f-ad47-48c38e8a7f8d.png alt=\"Dynablox Youtube Video\"\u003e](https://www.youtube.com/watch?v=NA13fRWlqRQ)\n\n## News\nWe were excited to learn that Dynablox has been integrated into NVIDIA's [nvblox](https://github.com/nvidia-isaac/nvblox), where the algorithm's parallelism can make fantastic use of the GPU and detect moving objects fast and at high resolutions! \n\n# Setup\n\nThere is a [docker image](https://hub.docker.com/repository/docker/zhangkin/dynablox/general) available for this package. Check the usage in the dockerhub page.\n\n## Installation\n\n* **Note on Versioning:** This package was developed using Ubuntu 20.04 using ROS Noetic. Other versions should also work but support can not be guaranteed.\n\n1. If not already done so, install [ROS](http://wiki.ros.org/action/fullsearch/melodic/Installation/Ubuntu?action=fullsearch\u0026context=180\u0026value=linkto%3A%22melodic%2FInstallation%2FUbuntu%22). We recommend using `Desktop-Full`.\n\n2. If not already done so, setup a catkin workspace:\n    ```bash\n    mkdir -p ~/catkin_ws/src\n    cd ~/catkin_ws\n    catkin init\n    catkin config --extend /opt/ros/$ROS_DISTRO\n    catkin config --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo\n    catkin config --merge-devel\n    ```\n\n2. Install system dependencies:\n    ```bash\n    sudo apt-get install python3-vcstool python3-catkin-tools ros-$ROS_DISTRO-cmake-modules protobuf-compiler autoconf git rsync -y   \n    ```\n\n3. Clone the repo using [SSH Keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh):\n    ```bash\n    cd ~/catkin_ws/src\n    git clone git@github.com:ethz-asl/dynablox.git\n    ```\n\n4. Install ROS dependencies:\n    ```bash\n    cd ~/catkin_ws/src\n    vcs import . \u003c ./dynablox/ssh.rosinstall --recursive \n    ```\n\n5. Build:\n    ```bash\n    catkin build dynablox_ros\n    ```\n\n## Datasets\nTo run the demos we use the [Urban Dynamic Objects LiDAR  (DOALS) Dataset](https://projects.asl.ethz.ch/datasets/doku.php?id=doals).\nTo download the data and pre-process it for our demos, use the provided script:\n```bash\nroscd dynablox_ros/scripts\n./download_doals_data.sh /home/$USER/data/DOALS # Or your preferred data destination.\n```\n\nWe further collect a new dataset featuring diverse dynamic objects in complex scenes.\nThe full dataset and description can be found [here](https://projects.asl.ethz.ch/datasets/doku.php?id=dynablox).\nTo download the processed ready-to-run data for our demos, use the provided script:\n```bash\nroscd dynablox_ros/scripts\n./download_dynablox_data.sh /home/$USER/data/Dynablox # Or your preferred data destination.\n\n```\n\n# Examples\n## Running a DOALS Sequence\n1. If not done so, download the DOALS dataset as explained [here](#datasets).\n\n2. Adjust the dataset path in `dynablox_ros/launch/run_experiment.launch`:\n    ```xml\n    \u003carg name=\"bag_file\" default=\"/home/$(env USER)/data/DOALS/hauptgebaeude/sequence_1/bag.bag\" /\u003e  \n    ```\n3. Run\n    ```bash\n    roslaunch dynablox_ros run_experiment.launch \n    ```\n4. You should now see dynamic objects being detected as the sensor moves through the scene:\n\n![Run DOALS Example](https://user-images.githubusercontent.com/36043993/232138501-84250c43-236e-46f6-9b50-af54312215a7.png)\n\n## Running a Dynablox Sequence\n\n1. If not done so, download the Dynablox dataset as explained [here](#datasets).\n\n2. Adjust the dataset path in `dynablox_ros/launch/run_experiment.launch` and set `use_doals` to false:\n    ```xml\n    \u003carg name=\"use_doals\" default=\"false\" /\u003e \n    \u003carg name=\"bag_file\" default=\"/home/$(env USER)/data/Dynablox/processed/ramp_1.bag\" /\u003e  \n    ```\n3. Run\n    ```bash\n    roslaunch dynablox_ros run_experiment.launch \n    ```\n4. You should now see dynamic objects being detected as the sensor moves through the scene:\n![Run Dynablox Example](https://user-images.githubusercontent.com/36043993/232140093-ee99a919-d2ad-4dc8-95ac-fa047b901f94.png)\n\n## Running and Evaluating an Experiment\n\n### Running an Experiment\n\n1. If not done so, download the DOALS dataset as explained [here](#datasets).\n\n2. Adjust the dataset path in `dynablox_ros/launch/run_experiment.launch`:\n    ```xml\n    \u003carg name=\"bag_file\" default=\"/home/$(env USER)/data/DOALS/hauptgebaeude/sequence_1/bag.bag\" /\u003e  \n    ```\n\n3. In `dynablox_ros/launch/run_experiment.launch`, set the `evaluate` flag, adjust the ground truth data path, and specify where to store the generated outpuit data:\n    ```xml\n    \u003carg name=\"evaluate\" default=\"true\" /\u003e\n    \u003carg name=\"eval_output_path\" default=\"/home/$(env USER)/dynablox_output/\" /\u003e\n    \u003carg name=\"ground_truth_file\" default=\"/home/$(env USER)/data/DOALS/hauptgebaeude/sequence_1/indices.csv\" /\u003e\n      ```\n3. Run\n    ```bash\n    roslaunch dynablox_ros run_experiment.launch \n    ```\n\n4. Wait till the dataset finished processing. Dynablox should shutdown automatically afterwards.\n\n### Analyzing the Data\n- **Printing the Detection Performance Metrics:** \n    1. Run:\n    ```bash\n    roscd dynablox_ros/src/evaluation\n    python3 evaluate_data.py /home/$USER/dynablox_output\n    ```\n    2. You should now see the performance statistics for all experiments in that folder:\n    ```\n    1/1 data entries are complete.\n    Data                     object_IoU               object_Precision              object_Recall\n    hauptgebaeude_1          89.8 +- 5.6              99.3 +- 0.4                   90.3 +- 5.6\n    All                      89.8 +- 5.6              99.3 +- 0.4                   90.3 +- 5.6\n    ```\n\n- **Inspecting the Segmentation:**\n    1. Run:\n    ```bash\n    roslaunch dynablox_ros cloud_visualizer.launch file_path:=/home/$USER/dynablox_output/clouds.csv\n    ```\n    2. You should now see the segmentation for the annotated ground truth clouds, showing True Positives (green), True Negatives (black), False Positives (blue), False Negatives (red), and out-of-range (gray) points:\n    ![Evaluation](https://user-images.githubusercontent.com/36043993/232151598-750a6860-e6e6-44bc-89c6-fbc866109019.png)\n\n- **Inspecting the Run-time and Configuration:**\n    Additional information is automatically stored in `timings.txt` and `config.txt` for each experiment.\n\n### Advanced Options\n* **Adding Drift to an Experiment:**\n    To run an experiment with drift specify one of the pre-computed drift rollouts in `dynablox_ros/launch/run_experiment.launch`:\n    ```xml\n    \u003carg name=\"drift_simulation_rollout\" default=\"doals/hauptgebaeude/sequence_1/light_3.csv\" /\u003e\n    ```\n    All pre-computed rollouts can be found in `drift_simulation/config/rollouts`. Note that the specified sequence needs to match the data being played. For each sequence, there exist 3 rollouts for each intensity.\n\n    Alternatively, use the `drift_simulation/launch/generate_drift_rollout.launch` to create new rollouts for other datasets.\n\n* **Changing th Configuration of Dynablox:**\n    All parameters that exist in dynablox are listed in `dynablox_ros/config/motion_detector/default.yaml`, feel free to tune the method for your use case!\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethz-asl%2Fdynablox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fethz-asl%2Fdynablox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethz-asl%2Fdynablox/lists"}