Skip to content

Commit 1fe7d99

Browse files
kshitijgoel007kshitijgoel007
committed
0.0.0
0 parents  commit 1fe7d99

File tree

17 files changed

+417
-0
lines changed

17 files changed

+417
-0
lines changed

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.venv
2+
build/
3+
install/
4+
log/
5+
gira3d-tutorial-data/
6+
.ipynb_checkpoints/

‎.gitmodules‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
[submodule "docs"]
2+
path = docs
3+
url = git@github.com:gira3d/gira3d-reconstruction-docs.git
4+
[submodule "dry/src/eigen_colcon"]
5+
path = dry/src/eigen_colcon
6+
url = git@github.com:gira3d/eigen_colcon.git
7+
[submodule "dry/src/open3d_colcon"]
8+
path = dry/src/open3d_colcon
9+
url = git@github.com:gira3d/open3d_colcon.git
10+
[submodule "dry/src/pybind11_colcon"]
11+
path = dry/src/pybind11_colcon
12+
url = git@github.com:gira3d/pybind11_colcon.git
13+
[submodule "wet/src/self_organizing_gmm"]
14+
path = wet/src/self_organizing_gmm
15+
url = git@github.com:gira3d/self_organizing_gmm.git
16+
[submodule "wet/src/sogmm_open3d"]
17+
path = wet/src/sogmm_open3d
18+
url = git@github.com:gira3d/sogmm_open3d.git
19+
[submodule "wet/src/sogmm_py"]
20+
path = wet/src/sogmm_py
21+
url = git@github.com:gira3d/sogmm_py.git

‎LICENSE‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
BSD 3-Clause License
2+
3+
Copyright (c) 2023, Kshitij Goel, Wennie Tabib
4+
5+
Redistribution and use in source and binary forms, with or without
6+
modification, are permitted provided that the following conditions are met:
7+
8+
1. Redistributions of source code must retain the above copyright notice, this
9+
list of conditions and the following disclaimer.
10+
11+
2. Redistributions in binary form must reproduce the above copyright notice,
12+
this list of conditions and the following disclaimer in the documentation
13+
and/or other materials provided with the distribution.
14+
15+
3. Neither the name of the copyright holder nor the names of its
16+
contributors may be used to endorse or promote products derived from
17+
this software without specific prior written permission.
18+
19+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎README.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# GIRA3D Reconstruction
2+
This component of GIRA3D enables compact point cloud modeling for depth-intensity reconstruction. The point
3+
cloud modeling is performed via Self-Organizing Gaussian Mixture Modeling (SOGMM) presented in:
4+
5+
```
6+
[1] K. Goel, N. Michael, and W. Tabib, “Probabilistic Point Cloud Modeling via Self-Organizing Gaussian Mixture Models,” IEEE Robotics and Automation Letters, vol. 8, no. 5, pp. 2526–2533, May 2023, doi: 10.1109/LRA.2023.3256923.
7+
```
8+
```
9+
@ARTICLE{goel_probabilistic_2023,
10+
title = {Probabilistic Point Cloud Modeling via Self-Organizing Gaussian Mixture Models},
11+
author = {Goel, Kshitij and Michael, Nathan and Tabib, Wennie},
12+
year = {2023},
13+
month = may,
14+
journal={IEEE Robotics and Automation Letters},
15+
volume = {8},
16+
number = {5},
17+
pages = {2526--2533},
18+
issn = {2377-3766},
19+
doi = {10.1109/LRA.2023.3256923},
20+
keywords = {Adaptation models,Complexity theory,Computational modeling,Data models,field robots,Mapping,Point cloud compression,Probabilistic logic,RGB-D perception,Three-dimensional displays}
21+
}
22+
```
23+
A video demonstrating the features of SOGMM can be found [here](https://youtu.be/v0DfhK1lyno).
24+
25+
If you use this codebase in your work, please consider citing the article above.
26+
27+
## Overview
28+
This repository is a meta workspace containing two [`colcon`](https://colcon.readthedocs.io/en/released/) workspaces:
29+
30+
1. The `dry` workspace contains dependencies that we choose to compile from their source code.
31+
32+
2. The `wet` workspace contains the main codebase.
33+
34+
The `dry` workspace contains the following `git` submodules:
35+
36+
1. `eigen_colcon`: Colcon package to pull [Eigen 3.4](https://eigen.tuxfamily.org/index.php?title=3.4).
37+
38+
2. `pybind11_colcon`: Colcon package to pull [pybind11](https://pybind11.readthedocs.io/en/stable/).
39+
40+
3. `open3d_colcon`: Colcon package to pull [our modifications](https://github.com/rislab/Open3D/tree/feature/cuda-12) to [Open3D](http://www.open3d.org/).
41+
> **Note**
42+
> `open3d_colcon` will not be compiled for macOS.
43+
44+
The `wet` workspace contains the following `git` submodules:
45+
46+
1. `self_organizing_gmm`: C++ codebase accelerated with OpenMP for Intel/AMD/ARM CPUs.
47+
48+
2. `sogmm_open3d`: C++ codebase accelerated with CUDA and Open3D for Intel/AMD/ARM CPUs and NVIDIA GPUs.
49+
> **Note**
50+
> `sogmm_open3d` will not be compiled for macOS.
51+
52+
3. `sogmm_py`: Scripts for visualization, comparison, testing, and profiling.
53+
54+
## Supported Platforms
55+
The codebase has been tested on the following platforms:
56+
57+
1. **Linux**
58+
59+
| Platform ID | OS | CPU | GPU | Memory (CPU/GPU) | CUDA Version|
60+
| ----------- | ------------- | --- | --- | ---------------- | ---- |
61+
| Ryzen/RTX3090 | Ubuntu 20.04 | AMD Ryzen Threadripper 3960X, 48 threads | NVIDIA GeForce RTX 3090 | 252 GB/24 GB | <= 12.1 |
62+
| Intel/RTX3060 | Ubuntu 20.04 | Intel Core i9-10900K, 20 threads | NVIDIA GeForce RTX 3060 | 32 GB/12 GB | <= 12.1 |
63+
| ARM-12c/Orin | Ubuntu 20.04 | ARMv8 Processor rev 1 (v8l), 12 threads | NVIDIA Jetson Orin | 32 GB | <= 11.4 |
64+
| ARM-8c/Xavier | Ubuntu 20.04 | ARMv8 Processor rev 0 (v8l), 8 threads | NVIDIA Jetson Xavier | 16 GB | <= 11.4 |
65+
| ARM-6c/TX2 | Ubuntu 20.04 | ARM Cortex-A57, 6 threads | NVIDIA Jetson TX2 | 8 GB | <= 10.1 |
66+
67+
2. **macOS**
68+
> **Note**
69+
> CUDA-dependent repository, `sogmm_open3d`, is not supported for macOS.
70+
71+
| Platform ID | OS | CPU | GPU | Memory (CPU/GPU) | CUDA Version|
72+
| ----------- | ------------- | --- | --- | ---------------- | ---- |
73+
| MacBook/Intel | MacOS Ventura 13.3.1 | 2.3 GHz 8-Core Intel Core i9 | N/A | 16 GB | N/A |
74+
75+
## Build and Install
76+
We require using a Python 3.8 virtual environment using `pip`. Assume that the
77+
virtual environment is created within this repository using the folder name
78+
`.venv`. First, we set up the `colcon` build environment.
79+
80+
```bash
81+
git clone git@github.com:rislab/gira3d-reconstruction.git
82+
git checkout master # or your favorite branch
83+
git submodule update --recursive --init
84+
cd gira3d-reconstruction
85+
python3.8 -m venv .venv
86+
source .venv/bin/activate
87+
pip install --upgrade pip
88+
pip install colcon-common-extensions wheel
89+
```
90+
91+
For Python scripts, run-time dependencies can be installed using `pip`. Make sure
92+
the virtual environment created above is active.
93+
```bash
94+
pip install numpy scikit-learn opencv-python scikit-image future matplotlib termcolor
95+
```
96+
97+
Finally, run the `build` script:
98+
```bash
99+
./build
100+
```
101+
102+
Some helper scripts are provided as follows:
103+
1. `clean`: Clean the builds for both `dry` and `wet` workspaces.
104+
2. `configure`: Pull the submodules.
105+
106+
> **Warning**
107+
> If you run into issues with OpenMP on MacOS, you might need to use the `llvm` clang
108+
> compiler as opposed to the Apple Clang compiler.
109+
110+
## Environment Setup
111+
These steps also compile the python bindings. To use these python interfaces, first run:
112+
113+
```bash
114+
workon
115+
```
116+
> **Note**
117+
> For NVIDIA Jetson platforms (i.e., Orin, Xavier, and TX2), run `workon_jetson`.
118+
119+
### User Guide
120+
```bash
121+
pip install mkdocs mkdocs-material
122+
mkdocs serve
123+
```
124+
You should be able to view the documentation at this level over at [localhost](http://127.0.0.1:8000/).
125+
126+
Utilize this documentation for tutorials and examples that use one or many of the submodules.
127+
128+
Note: The documentation is stored using git lfs. You may need to run the
129+
following in order to make sure it is pulled correctly:
130+
131+
```
132+
cd docs
133+
git lfs install
134+
git lfs pull
135+
```
136+
137+
## Authors
138+
Kshitij Goel, Wennie Tabib
139+
140+
## Acknowledgments
141+
1. [`ndt_map`](https://github.com/OrebroUniversity/perception_oru-release): BSD License, Copyright (c) 2010, AASS Research Center, Orebro University.
142+
2. [`octomap`](https://github.com/OctoMap/octomap): New BSD License, Copyright (c) 2009-2013, K.M. Wurm and A. Hornung, University of Freiburg.
143+
3. [`liegroups`](https://github.com/utiasSTARS/liegroups): The MIT License, Copyright (c) 2017 Lee Clement.
144+
4. [`Open3D`](https://github.com/isl-org/Open3D): The MIT License (MIT), Copyright (c) 2018-2023 www.open3d.org.
145+
5. [`Eigen`](https://gitlab.com/libeigen/eigen): Mozilla Public License, v. 2.0.
146+
6. `CUDA`, `cuBLAS`, `cuSOLVER`: Copyright (c) 2022-2023, NVIDIA CORPORATION.
147+
148+
## License
149+
```
150+
BSD 3-Clause License
151+
152+
Copyright (c) 2023, Kshitij Goel, Wennie Tabib
153+
154+
Redistribution and use in source and binary forms, with or without
155+
modification, are permitted provided that the following conditions are met:
156+
157+
1. Redistributions of source code must retain the above copyright notice, this
158+
list of conditions and the following disclaimer.
159+
160+
2. Redistributions in binary form must reproduce the above copyright notice,
161+
this list of conditions and the following disclaimer in the documentation
162+
and/or other materials provided with the distribution.
163+
164+
3. Neither the name of the copyright holder nor the names of its
165+
contributors may be used to endorse or promote products derived from
166+
this software without specific prior written permission.
167+
168+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
169+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
170+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
171+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
172+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
173+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
174+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
175+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
176+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
177+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
178+
```

‎build‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
#!/bin/bash
2+
3+
unameOut="$(uname -s)"
4+
case "${unameOut}" in
5+
Linux*) machine=Linux;;
6+
Darwin*) machine=Mac;;
7+
CYGWIN*) machine=Cygwin;;
8+
MINGW*) machine=MinGw;;
9+
*) machine="UNKNOWN:${unameOut}"
10+
esac
11+
12+
if [[ $machine == "Linux" ]]
13+
then
14+
echo "Detected ${machine} environment. Building."
15+
16+
source .venv/bin/activate
17+
cd dry/
18+
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
19+
cd ..
20+
source workon
21+
cd wet/
22+
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
23+
cd ..
24+
source workon
25+
26+
cd dry/build/open3d_colcon/
27+
make install-pip-package -j${nproc}
28+
fi
29+
30+
if [[ $machine == "Mac" ]]
31+
then
32+
echo "Detected ${machine} environment. Building with CPU support only."
33+
34+
touch ./wet/src/sogmm_open3d/COLCON_IGNORE
35+
36+
source .venv/bin/activate
37+
cd dry/
38+
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
39+
cd ..
40+
source workon
41+
cd wet/
42+
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
43+
cd ..
44+
source workon
45+
46+
numcores=$(sysctl -n hw.logicalcpu)
47+
cd dry/build/open3d_colcon/
48+
make install-pip-package -j${numcores}
49+
fi

‎clean‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#!/bin/bash
2+
3+
cd dry/
4+
rm -rf build install log
5+
cd ../wet
6+
rm -rf build install log

‎configure‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
#!/bin/bash
2+
3+
unameOut="$(uname -s)"
4+
case "${unameOut}" in
5+
Linux*) machine=Linux;;
6+
Darwin*) machine=Mac;;
7+
CYGWIN*) machine=Cygwin;;
8+
MINGW*) machine=MinGw;;
9+
*) machine="UNKNOWN:${unameOut}"
10+
esac
11+
12+
PWD=$(pwd)
13+
DRY=$PWD/dry
14+
15+
echo $PWD
16+
17+
cd $PWD
18+
source .venv/bin/activate
19+
git submodule update --recursive --init
20+
21+
if [[ $machine == "Linux" ]]
22+
then
23+
cd $DRY
24+
cd src/open3d_colcon/Open3D/util/
25+
26+
./install_deps_ubuntu.sh
27+
sudo apt install libgsl-dev
28+
fi
29+
30+
cd $PWD

‎docs‎

Submodule docs added at bbd7c87

‎dry/src/eigen_colcon‎

Submodule eigen_colcon added at 1bef1d0

‎dry/src/open3d_colcon‎

Submodule open3d_colcon added at d2c3b00

0 commit comments

Comments
 (0)