Skip to content

Commit

Permalink
working on install
Browse files Browse the repository at this point in the history
  • Loading branch information
AntoineRichard committed Sep 10, 2024
1 parent 89dfe9d commit 02f8dcf
Show file tree
Hide file tree
Showing 12 changed files with 630 additions and 56 deletions.
120 changes: 73 additions & 47 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,44 +1,23 @@
# OmniLRS v2.0

In this repository, you will find the tools developped jointly by the Space Robotics group from the University of Luxembourg (SpaceR),
and the Space Robotics Lab from Tohoku University in Japan (SRL).

Please refer to the following presentation video and [slide](https://drive.google.com/file/d/1vIf3sHbgJz4mbKpPGAQFcx8JtvYv5YKp/view?usp=sharing) for the overview of our work.
<div align="center">
<a href="https://youtu.be/PebUZjm0WuA?si=hb-BivXSh4xw7Mqq">
<img src="media/thumb/thumbnail.png" style="width:60%;">
</a>
</div>

> Please note that this is only a partial release. The entirety of the code and assets/robots will be released at a later date.
> We will also provide docker as well as Foxglove interfaces to ease the interaction with the simulation.
> Should you run into any bug, or would like to have a new feature, feel free to open an issue.
In this repository, you will find the simulation tools developped jointly by the Space Robotics group from the University of Luxembourg (SpaceR),
and the Space Robotics Lab from Tohoku University in Japan (SRL). We are now opening it to the community and strongly encourage Space Roboticists to help us grow the feature set of this simulation! Don't be shy shoot a PR!

With this initial release we provide our small scale environments:
- The lunalab
- The lunaryard (3 versions 20m, 40m, 80m)
**This readme provides basic information on how to use the simulation. For more complete information please [visit our wiki](https://github.com/AntoineRichard/OmniLRS/wiki)!**

| Environment| Description | Image |
|------------|-------------|---------------------------------|
| **Lunalab** | Digital-Twin of lunar analog at the University of Luxembourg. | <img src="media/env_img/lunalab.png" width=520/> |
| **Lunaryard** | Procedually generated lunar environment. | <img src="media/env_img/lunaryard_husky_ex1.png" width=520/> |
| **LargeScale** | Semi procedural lunar environment. | <img src="docs/media/large_scale.png" width=520/>
## Simulation Environments Overview

We also provide 3 operation modes:
- ROS1: allows to run ROS1 enabled robots
- ROS2: allows to run ROS2 enabled robots
- SDG: or Synthetic Data Generarion, allows to capture synthetic data to train neural-networks.

For ROS2 we prepared 5 different robots:
- EX1 (`ex1.usd`): SRL's own rover.
- Leo Rover (`Leo_rover.usd`): a rover from fictionlab used by SpaceR.
- Husky (`husky.usd`): the UGV from Clearpath Robotics.
- Jackal (`jackal.usd`): the UGV from Clearpath Robotics.
- Turtlebot (`turtlebot3.usd`): A popular educational robot.
| <div style="width:90px">Name</div> | <div style="width:290px">Description</div> | Images |
|------------|-------------|---------------------------------|
| **Lunalab** | <div style="width:290px"> Digital-Twin of lunar analog at the University of Luxembourg. This environment also supports terrain deformation as the rover drives on it. </div> | <img src="media/env_img/lunalab.png" width=520/> |
| **Lunaryard** | <div style="width:290px">A small scale procedually generated lunar environment. If lunar coordinates and a date is provided the position of the earth and sun are computed using ephemerides resulting in realistic lighting. This feature is also available in the large scale environments. This environment also support terrain deformation as the rover drives on it.</div> | <img src="media/env_img/lunaryard_husky_ex1.png" width=520/> |
| **LargeScale** | <div style="width:290px">Semi procedural lunar environment. It uses real DEM to reconstuct the coarse terrain, usually 5meters per pixel and then uses procedural generation to augment it to 2.5cm per pixel. The terrain itself can be generated at a even higher resolution to smooth out shadows. This very fine terrain allows to reconstruct fine terrain features increasing the engineering value of the sim. The whole of this is bundled inside Geometry clip maps, allowing to render very large scenes.</div> | <img src="docs/media/large_scale.png" width=520/>
</center>

Finally, we provide simple configurations for different renderers:
- path_tracing: A slower rendering method that provides realistic light bounces.
- ray_tracing: A fast rendering method that does not provide pitched back shadows.

> Please note that this is a partial release. More robots will be made available at a later date.
> Should you run into any bug, or would like to have a new feature, feel free to open an issue.

## Installation
Expand All @@ -58,15 +37,15 @@ Operating System:

> Windows is not supported.
To install the simulation we strongly suggest using docker. Though the install could also be done using a native installation.
To install the simulation we strongly suggest using [docker](#docker-install). Though the install could also be done using a [native installation](#native-installation).

### Native installation

The first thing that needs to be done before we proceed with the native installation is to install Isaac. We support two version 2023.1.1 and 4.1.0. Though we'd recommend sticking to **2023.1.1** as there are some issues with renderings in 4.1.0.
The first thing that needs to be done before we proceed with the native installation is to install Isaac. We support two version 2023.1.1 and 4.1.0. Though we'd recommend sticking to **2023.1.1** as there are some issues with renderings in 4.1.0. Our dockers currently come in the 2023.1.1 version of Isaac.

[How to install Isaac?](https://docs.omniverse.nvidia.com/isaacsim/latest/installation/install_workstation.html)
If you're unsure on how to install Isaac sim, look-up the following: [How to install Isaac Sim.](https://docs.omniverse.nvidia.com/isaacsim/latest/installation/install_workstation.html)

To simplify the installation process of the framework we provide an script that will automatically download all the assets, as well as install the required dependencies.
To simplify the remainder of the installation process of the framework we provide a script that will automatically download all the assets, as well as install the required dependencies.

```bash
scripts/install.sh
Expand All @@ -84,7 +63,9 @@ sudo apt-get install libgdal-dev
version=$(gdal-config --version)

# Install Python packages for Isaac Sim
~/.local/share/ov/pkg/isaac_sim-2023.1.1/python.sh -m pip install opencv-python omegaconf hydra-core skyfield gdal==$version zfpy, gdown, black, numba
~/.local/share/ov/pkg/isaac_sim-2023.1.1/python.sh -m pip install opencv-python omegaconf hydra-core skyfield gdal==$version zfpy numba
python3 -m pip install --upgrade pip
python3 -m pip instal gdal==$version gdown black

# Download the assets from Google Drive
gdown 1LfdJ8cogFU8Eid2EL-0bu9E383lftC_W
Expand All @@ -99,24 +80,59 @@ rm assets.zip
```

Once this is done you should be off to the races!
See [getting started](GettingStarted) to learn more about starting your first scene.
However, before you venture forward, check that the assets folder has been created with success.
It should contain the following:
```bash
├── assets
│   ├── Ephemeris
│   ├── Terrains
│   | ├── Lunalab
│   | ├── Lunaryard
│   | └── SouthPole
│   ├── Textures
│   └── USD_Assets
│   ├── common
│   ├── environments
│   ├── lunalab
│   ├── robots
│   └── rocks
```
See [getting started](#getting-started) to learn more about starting your first scene.

### Docker Install
### Docker Installation

Before we install the simulation, please follow the procedure [here](https://docs.omniverse.nvidia.com/isaacsim/latest/installation/install_container.html) to install all the required components. Once you're all set, the following to build the image:
Before we install the simulation, please follow the procedure [here](https://docs.omniverse.nvidia.com/isaacsim/latest/installation/install_container.html) to install all the required components to install IsaacSim in a docker container. You will need an [nvcr.io](https://catalog.ngc.nvidia.com/) account. Once you're all set, the use following to build the image:
```
./docker/build.sh
./omnilrs.docker/build.sh
```

Once the image is built you should all set to run your first scene.
See [getting started](GettingStarted) to learn more about starting the simulation.
Once the image is built the simulation should be ready to go.
Though you will still need to download the assets. If you want to, you can download them from docker directly.

In docker exectute:
```
scritps/install_docker.sh
```
This will download the assets from docker and it should work fine. The issue is that all the generated folder will be
owned by root. So you may want to change that afterwards by running:
```bash
chown -r $USER assets
chgrp -r $USER assets
```

Provided you have Gdal and gdown installed on your system, you can also run:
```bash
scripts/download_only_native.sh
```

See [getting started](#getting-started) to learn more about starting the simulation.


## Getting started:

If you are using docker, first run the container by using:
```bash
./docker/run_docker.sh
./omnilrs.docker/run_docker.sh
```

You can then run the commands inside the docker, as if you were using the native installation. To run isaac prefix `python.sh` by `/isaac-sim/` in docker, and `~/.local/share/ov/pkg/isaac_sim-2023.1.1/` in the native installation.
Expand Down Expand Up @@ -150,7 +166,7 @@ https://github.com/jnskkmhr/omnilrs_ros2_demo


## Citation
Please use the following citation if you use `OmniLRS` in your work.
Please use the following citations if you use `OmniLRS` in your work.
```bibtex
@article{richard2024omnilrs,
title={OmniLRS: A Photorealistic Simulator for Lunar Robotics},
Expand All @@ -159,6 +175,16 @@ Please use the following citation if you use `OmniLRS` in your work.
url={https://arxiv.org/abs/2309.08997},
year={2024}
}
@article{kamohara2024modelingterraindeformationgrouser,
title={Modeling of Terrain Deformation by a Grouser Wheel for Lunar Rover Simulation},
author={Junnosuke Kamohara and Vinicius Ares and James Hurrell and Keisuke Takehana and Antoine Richard and Shreya Santra and Kentaro Uno and Eric Rohmer and Kazuya Yoshida},
year={2024},
eprint={2408.13468},
booktitle={21st International and 12th Asia-Pacific Regional Conference of the ISTVS}
primaryClass={cs.RO},
url={https://arxiv.org/abs/2408.13468},
}
```

## Directory Structure
Expand Down
169 changes: 169 additions & 0 deletions cfg/environment/lunalab_deformable.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
name: Lunalab
seed: 42
physics_dt: 0.0333 # 30 Hz
rendering_dt: 0.0333 # 30 Hz
enforce_realtime: true

lunalab_settings: # These settings cannot be changed.
lab_length: 10.0
lab_width: 6.5
resolution: 0.01

# Rocks sampling parameters.
rocks_settings:
instancers_path: /Lunalab/Rocks
rocks_settings:
large_rocks: # The name doesn't matter.
seed: ${....seed}
collections: ["lunalab_rocks"] # Where to get the rock models from.
use_point_instancer: True # If True, the rocks will be instanced using the PointInstancer.
# If False, it will use the custom instancer that works for SDG.
requests: # A list of request used to distribute the rocks.
req_pos_xy:
attribute: Position
axes: ["x", "y"]
layer:
name: Image
# data: Is loaded automatically from the DEM.
mpp_resolution: ${.......lunalab_settings.resolution}
output_space: 2
sampler:
name: HardCoreUniform
randomization_space: 2
seed: ${.......seed}
core_radius: 0.5
num_repeat: 2
min: ${as_tuple:0.5,0.5}
max: ${as_tuple:6,9.5}

req_pos_z:
attribute: Position
axes: ["z"]
layer:
name: Image
output_space: 1
sampler:
name: Image
randomization_space: 1
# resolution: Resolution is infered automatically from the loaded DEM.
# data: Is loaded automatically from the DEM.
mpp_resolution: ${.......lunalab_settings.resolution}

req_random_z_rot:
attribute: Orientation
axes: ["x", "y", "z", "w"]
layer:
name: RollPitchYaw
rmax: 0
rmin: 0
pmax: 0
pmin: 0
ymax: 6.28318530718
ymin: 0
sampler:
name: Uniform
randomization_space: 3
seed: ${.......seed}

req_scale:
attribute: Scale
axes: ["xyz"]
layer:
name: Line
xmin: 1.0
xmax: 1.0
sampler:
name: Uniform
randomization_space: 1
seed: ${.......seed}

terrain_manager:
moon_yard:
crater_generator:
profiles_path: assets/Terrains/crater_spline_profiles.pkl
min_xy_ratio: 0.85
max_xy_ratio: 1.0
resolution: ${....lunalab_settings.resolution}
pad_size: 500
random_rotation: True
z_scale: 1.0
seed: ${....seed}

crater_distribution:
x_size: 10.0
y_size: 6.5
densities: [0.025, 0.05, 0.5]
radius: [[1.5,2.5],[0.75,1.5],[0.25,0.5]]
num_repeat: 0
seed: ${....seed}

base_terrain_generator:
x_size: ${....lunalab_settings.lab_length}
y_size: ${....lunalab_settings.lab_width}
resolution: ${....lunalab_settings.resolution}
max_elevation: 0.25
min_elevation: -0.025
z_scale: 1.0
seed: ${....seed}

deformation_engine:
enable: False
delay: 2.0
terrain_width: ${....lunalab_settings.lab_width}
terrain_height: ${....lunalab_settings.lab_length}
terrain_resolution: ${....lunalab_settings.resolution}
footprint:
width: 0.09
height: 0.2
deform_constrain:
x_deform_offset: 0.0
y_deform_offset: 0.0
deform_decay_ratio: 0.01
boundary_distribution:
distribution: trapezoidal
angle_of_repose: 1.047 #pi/3
depth_distribution:
distribution: trapezoidal
wave_frequency: 4.14 # num_grouser/pi (no slip)
force_depth_regression:
amplitude_slope: 0.00006
amplitude_intercept: 0.008
mean_slope: -0.00046
mean_intercept: -0.0013

is_yard: False
is_lab: True

root_path: /Lunalab
texture_path: /Lunalab/Looks/Basalt
dems_path: Terrains/Lunalab
mesh_position: [0, 0, 0]
mesh_orientation: [0, 0, 0, 1] # Quaternion x,y,z,w
mesh_scale: [1, 1, 1]
sim_length: ${..lunalab_settings.lab_length}
sim_width: ${..lunalab_settings.lab_width}
resolution: ${..lunalab_settings.resolution}

robots_settings:
uses_nucleus: False
is_ROS2: True
max_robots: 5
robots_root: "/Robots"
parameters:
# -
# robot_name: ex1
# usd_path: assets/USD_Assets/robots/ex1.usd
# pose:
# position: [1.0, 1.0, 0.5]
# orientation: [1, 0, 0, 0]
# domain_id: 0
# target_links: ["left_front_wheel_link", "left_rear_wheel_link", "right_front_wheel_link", "right_rear_wheel_link"]

-
robot_name: husky
usd_path: assets/USD_Assets/robots/ros2_husky_PhysX_vlp16.usd
pose:
position: [5.0, 5.0, 0.5]
orientation: [1, 0, 0, 0]
domain_id: 0
target_links: ["front_left_wheel_link", "front_right_wheel_link", "rear_left_wheel_link", "rear_right_wheel_link"]
2 changes: 1 addition & 1 deletion cfg/environment/lunaryard_20m.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -266,7 +266,7 @@ terrain_manager:
seed: ${....seed}

deformation_engine:
enable: True
enable: False
delay: 2.0
terrain_width: ${....lunaryard_settings.lab_width}
terrain_height: ${....lunaryard_settings.lab_length}
Expand Down
Loading

0 comments on commit 02f8dcf

Please sign in to comment.