Skip to content

Commit 5df5362

Browse files
nathanhhughesnathanhhughes
authored
revert README and add docker link (#30)
1 parent 4f7d692 commit 5df5362

File tree

1 file changed

+119
-13
lines changed

1 file changed

+119
-13
lines changed

‎README.md‎

Lines changed: 119 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
## Hydra-ROS
1+
# Hydra-ROS
22

33
This repository contains the ROS interface for [Hydra](https://github.com/MIT-SPARK/Hydra) and is based on the following papers:
44
- ["Hydra: A Real-time Spatial Perception System for 3D Scene Graph Construction and Optimization"](http://www.roboticsproceedings.org/rss18/p050.pdf)
@@ -26,29 +26,135 @@ If you find this code relevant for your work, please consider citing us. A bibte
2626
}
2727
```
2828

29-
### Acknowledgements and Disclaimer
29+
## Table of Contents
3030

31-
**Acknowledgements:** This work was partially funded by the AIA CRA FA8750-19-2-1000, ARL DCIST CRA W911NF-17-2-0181, and ONR RAIDER N00014-18-1-2828.
32-
33-
**Disclaimer:** Research was sponsored by the United States Air Force Research Laboratory and the United States Air Force Artificial Intelligence Accelerator and was accomplished under Cooperative Agreement Number FA8750-19-2-1000. The views and conclusions contained in this document are those of the authors and should not be interpreted as representing the official policies, either expressed or implied, of the United States Air Force or the U.S. Government. The U.S. Government is authorized to reproduce and distribute reprints for Government purposes notwithstanding any copyright notation herein.
31+
- [Getting Started](#getting-started)
32+
- [Installation](#installation)
33+
- [Dataset Setup](#dataset-setup)
34+
- [Running Hydra](#running-hydra)
35+
- [Filing Issues](#filing-issues)
36+
- [Additional Resources](#additional-resources)
37+
- [Acknowledgements](#acknowledgements)
3438

35-
### Getting started
39+
## Getting started
3640

3741
> :warning: **Warning** <br>
38-
> The ROS2 version of this package is in active development and is not guaranteed to build, run or have documentation. You have been warned!
42+
> The ROS2 version of Hydra is in active development and is unstable and may not fully be feature-complete.
43+
44+
Hydra has been tested on Ubuntu 22.04 & ROS2 Iron and Ubuntu 24.04 & ROS2 Jazzy. It **should** build on newer distributions. It **will not** build on older ROS2 distributions than Iron (it depends on the `NodeInterfaces` suite of classes that were introduced in Iron).
45+
46+
You can follow the instructions [here](https://docs.ros.org/en/jazzy/Installation.html) to install ROS2 if you haven't already. The link points to Jazzy currently, pay attention to the distribution!
47+
We also have documentation on how to use Docker to build and run Hydra [here](docker/README.md).
48+
49+
### Installation
50+
51+
#### Dependencies
52+
53+
First, make sure you have some general requirements
54+
```shell
55+
# this is an optional package in the ROS2 installation directions
56+
sudo apt install ros-dev-tools
57+
```
58+
and make sure you have set rosdep up:
59+
```shell
60+
sudo rosdep init
61+
rosdep update
62+
```
63+
64+
#### Building
65+
66+
To get started:
67+
68+
```shell
69+
mkdir -p ~/hydra_ws/src
70+
cd ~/hydra_ws
71+
# you may find it convenient to set the build type, etc.
72+
# you may also want to set `symlink-install: true`
73+
echo "build: {cmake-args: [-DCMAKE_BUILD_TYPE=Release]}" > colcon_defaults.yaml
74+
75+
cd src
76+
git clone [email protected]:MIT-SPARK/Hydra-ROS.git hydra_ros -b ros2
77+
vcs import . < hydra_ros/install/ros2.yaml
78+
rosdep install --from-paths . --ignore-src -r -y
79+
80+
cd ..
81+
colcon build --continue-on-error
82+
```
83+
84+
> **Note**<br>
85+
> Depending on the amount of RAM available on your machine, you may run out of memory when compiling with `colcon build` directly (which will result in a `GCC killed` error). If this occurs, you can either specify fewer threads for colcon via `MAKEFLAGS="-j2" colcon build --parallel-workers 2` (which builds 2 packages at a time with 2 threads for 4 threads total) or compile certain larger packages directly first by building them specifically.
86+
87+
> :warning: **Warning**</br>
88+
> In the `vcs import` step, GitHub may block too many concurrent requests. If you receive `kex_exchange_identification: read: Connection reset by peer` errors, try running `vcs import . < hydra/install/hydra.rosinstall --workers 1`.
89+
90+
### Dataset Setup
91+
92+
We've switched to the v2 version of uhumans2. Download the ROS1 bag for the office scene [here](https://drive.google.com/file/d/1awAzQ7R1hdS5O1Z2zOcpYjK7F4_APq_p/view?usp=drive_link).
93+
Then install [rosbags](https://pypi.org/project/rosbags/) via pip (i.e., `pip install rosbags` into a virtual environment).
94+
95+
To convert the bag:
96+
```shell
97+
rosbags-convert --src path/to/office.bag --dst path/to/office
98+
```
3999

40-
Hydra has been tested on Ubuntu 22.04 and ROS2 Iron. See [here](doc/ros2_setup.md) to get started with Hydra and ROS2. See [here](docker/README.md) for using Hydra with ROS2 in Docker.
100+
Make sure to create a override for latching static tf topics:
101+
```shell
102+
echo "/tf_static: {depth: 1, durability: transient_local}" > ~/.tf_overrides.yaml
103+
```
41104

42105
### Running Hydra
43106

44-
See our documentation [here](doc/quickstart.md).
107+
> **:warning: Warning**<br>
108+
> This guide is written assuming you use `zsh`. If you don't, source the right setup file for your shell
109+
110+
To start Hydra:
111+
```shell
112+
# this will break autocomplete, see group wiki for correct way to do this
113+
source ~/hydra_ws/install/setup.zsh
114+
ros2 launch hydra_ros uhumans2.launch.yaml
115+
```
116+
117+
Then, start the rosbag in a separate terminal:
118+
```shell
119+
ros2 bag play path/to/rosbag --clock --qos-profile-overrides-path ~/.tf_overrides.yaml
120+
```
45121

46-
### Design Information
122+
#### Running with Semantic Segmentation
123+
124+
See [here](https://github.com/MIT-SPARK/semantic_inference/blob/main/docs/closed_set.md#getting-dependencies) for installation information for `semantic_inference`.
125+
126+
For the uHumans2 office scene, start Hydra via
127+
```
128+
source ~/hydra_ws/install/setup.zsh
129+
ros2 launch hydra_ros uhumans2.launch.yaml use_gt_semantics:=false
130+
```
131+
132+
You may need to wait for about a minute for TensorRT to compile the model the first time you run the launch file. Once Hydra initializes, then run
133+
```
134+
ros2 bag play path/to/rosbag --clock --qos-profile-overrides-path ~/.tf_overrides.yaml
135+
```
136+
137+
## Filing Issues
138+
139+
Please understand that this is research code maintained by busy graduate students, **which comes with some caveats**:
140+
1. We do our best to maintain and keep the code up-to-date, but things may break or change occasionally
141+
2. We do not have bandwidth to help adapt the code to new applications
142+
3. The documentation, code-base and installation instructions are geared towards practitioners familiar with ROS and 3D scene graph research.
143+
144+
> **:warning: Warning**<br>
145+
> We don't support other platforms. Issues requesting support on other platforms (e.g., Ubuntu 18.04, Windows) will be summarily closed.
146+
147+
Depending on the nature of the issue, it may be helpful to browse [this](doc/debugging.md) page about debugging Hydra first.
148+
149+
Thank you in advance for your understanding!
150+
151+
## Additional Resources
47152

48153
We maintain information on the ROS2 interfaces that Hydra uses [here](doc/hydra_ros_interfaces.md) that may be useful if you are trying to understand how to use Hydra with a new dataset.
154+
We also have a preliminary guide to setting up Hydra with the Zed2i camera [here](doc/setting_up_a_new_sensor.md).
49155

50-
### Filing Issues
156+
## Acknowledgements
51157

52-
:warning: We don't support other platforms. Issues requesting support on other platforms (e.g. Ubuntu 16.04, Windows) will be summarily closed.
158+
**Acknowledgements:** This work was partially funded by the AIA CRA FA8750-19-2-1000, ARL DCIST CRA W911NF-17-2-0181, and ONR RAIDER N00014-18-1-2828.
53159

54-
Depending on the nature of the issue, it may be helpful to browse [this](https://github.com/MIT-SPARK/Hydra/blob/main/doc/debugging.md) page about debugging Hydra first.
160+
**Disclaimer:** Research was sponsored by the United States Air Force Research Laboratory and the United States Air Force Artificial Intelligence Accelerator and was accomplished under Cooperative Agreement Number FA8750-19-2-1000. The views and conclusions contained in this document are those of the authors and should not be interpreted as representing the official policies, either expressed or implied, of the United States Air Force or the U.S. Government. The U.S. Government is authorized to reproduce and distribute reprints for Government purposes notwithstanding any copyright notation herein.

0 commit comments

Comments
 (0)