diff --git a/wiki/Contribute.md b/wiki/Contribute.md deleted file mode 100644 index 8961101..0000000 --- a/wiki/Contribute.md +++ /dev/null @@ -1,65 +0,0 @@ - - -
-

Navigation

- -
- -
- -## Introduction -This is the introduction section. - -## Getting Started -Details for getting started. - -## Installation -Instructions for installing the software. - -## Configuration -Steps to configure the application. - -## Advanced Topics - -### Performance Tuning -Information about tuning performance. - -### Customization -Guide to customizing the application. - -
\ No newline at end of file diff --git a/wiki/FAQ/FAQ.md b/wiki/FAQ/FAQ.md new file mode 100644 index 0000000..46d5c6f --- /dev/null +++ b/wiki/FAQ/FAQ.md @@ -0,0 +1,4 @@ +# Frequently Asked Questions + +> [!Warning] +> This page is under construction. diff --git a/wiki/FAQ/_Footer.md b/wiki/FAQ/_Footer.md new file mode 100644 index 0000000..606036d --- /dev/null +++ b/wiki/FAQ/_Footer.md @@ -0,0 +1 @@ +Antoine Richard -- University of Luxembourg -- Space Robotics Group -- 2023-24 diff --git a/wiki/FAQ/_Sidebar.md b/wiki/FAQ/_Sidebar.md new file mode 100644 index 0000000..fc09b09 --- /dev/null +++ b/wiki/FAQ/_Sidebar.md @@ -0,0 +1,2 @@ +## Table of Contents +- [Back to Home](../Home) diff --git a/wiki/GettingStarted.md b/wiki/GettingStarted.md deleted file mode 100644 index e69de29..0000000 diff --git a/wiki/Home.md b/wiki/Home.md index 047b220..ee36710 100644 --- a/wiki/Home.md +++ b/wiki/Home.md @@ -1,4 +1,4 @@ -# Welcome to OmniLRS's Wiki + Welcome to OmniLRS's Wiki
@@ -15,15 +15,24 @@ and the Space Robotics Lab from Tohoku University in Japan (SRL). |
Name
|
Description
| Images | |------------|-------------|---------------------------------| -| **Lunalab** |
Digital-Twin of lunar analog at the University of Luxembourg. This environment also supports terrain deformation as the rover drives on it.
| | -| **Lunaryard** |
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.
| | -| **LargeScale** |
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.
| +| **Lunalab** |
Digital-Twin of lunar analog at the University of Luxembourg. This environment also supports terrain deformation as the rover drives on it.
| | +| **Lunaryard** |
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.
| | +| **LargeScale** |
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.
| > [!NOTE] > Please note that this is a partial release. More robots will be made available at a later date. Should you run into a bug, or would like to request a new feature, feel free to open an issue. Want to collaborate, reach out to us! ## Wiki's overview -> [!CAUTION] +> [!WARNING] > This wiki is still under construction, if you are looking for something in particular that's not yet docummented please open an issue. +- [Installation](installation/Installation.md) +- [Getting Started](getting_started/GettingStarted.md) +- [Interracting with the Scene](scene_interaction/ros_topics.md) +- [Configuring simulation modes](modes/Modes.md) +- [Configuring the environments](environments/Environments.md) +- [Configuring the rendering](rendering/Rendering.md) +- [Configuring the physics](physics/Physics.md) +- [Contribute](contribute/Contribute.md) +- [FAQ](FAQ/FAQ.md) diff --git a/wiki/_Footer.md b/wiki/_Footer.md index 658338a..606036d 100644 --- a/wiki/_Footer.md +++ b/wiki/_Footer.md @@ -1 +1 @@ -2024 -- Antoine Richard -- University of Luxembourg -- SpaceR \ No newline at end of file +Antoine Richard -- University of Luxembourg -- Space Robotics Group -- 2023-24 diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md deleted file mode 100644 index 83f98bc..0000000 --- a/wiki/_Sidebar.md +++ /dev/null @@ -1,25 +0,0 @@ -## Table of Contents - -- [Configurations](#configurations) - - [How to Hydra](#how-to-hydra) - - [Environments Configs](#environments-configs) - - [Lunalab](#lunalab) - - [Lunaryard](#lunaryard) - - [LargeScale](#largescale) - - [Extras: Light Sources](#extras:-light-sources) - - [Sun](#sun) - - [Coordinates](#coordinates) - - [Date](#date) - - [Stellar Engine](#stellar-engine) - - [Extras: Rocks](#extras:-rocks) - - [Request](#request) - - [Request Group](#request-group) - - [Rock Generation](#rock-generation) - - [ROS1](#ros1) - - [ROS2](#ros2) - - [SDG](#sdg) - - [Rendering Configs](#rendering-configs) - - [RTXRealTime & RTXInteractive](#rtxrealtime-&-rtxinteractive) - - [Lens Flares](#lens-flares) - - [Motion Blur](#motion-blur) - - [Chromatic Aberrations](#chromatic-aberrations) diff --git a/wiki/contribute/Contribute.md b/wiki/contribute/Contribute.md new file mode 100644 index 0000000..c5be4f9 --- /dev/null +++ b/wiki/contribute/Contribute.md @@ -0,0 +1,31 @@ +# Contribute + +We are continuously looking to expend our feature set. Because this project is not funded it's hard for the Space Robotic's group of the University of Luxembourg to support the whole of this development. Hence we would love the community to help us build new features. But also to tell us what are the features you'd like to see! We list below the features/improvements we'd like to push forward in the near future. + +> [!Note] +> Feel free to suggest a new feature by opening an issue! + + +## Targeted Features + +- [x] Thermal simulation. JAOPS +- [x] Solar power simulation. JAOPS +- [ ] Quadruped demo. +- [x] 3D Navigation demo. SpaceR +- [x] SLAM dataset generator. SpaceR +- [ ] Geographic Geometry clip map. +- [x] Improve procedural map generation. SpaceR +- [x] AI augmented low-resolution clipmaps. SpaceR +- [ ] Proper database to store object. +- [ ] Compression of CraterMetaData. +- [ ] Wheel traces for large scale terrains. +- [ ] Better lens flares. +- [ ] Terramechanics. +- [ ] Better rocks. +- [ ] Improved MDL textures for large scale environments. + +## Contacts + +Antoine Richard: antoine.richard@uni.lu +Louis Burtz: + diff --git a/wiki/contribute/_Footer.md b/wiki/contribute/_Footer.md new file mode 100644 index 0000000..606036d --- /dev/null +++ b/wiki/contribute/_Footer.md @@ -0,0 +1 @@ +Antoine Richard -- University of Luxembourg -- Space Robotics Group -- 2023-24 diff --git a/wiki/contribute/_Sidebar.md b/wiki/contribute/_Sidebar.md new file mode 100644 index 0000000..3121837 --- /dev/null +++ b/wiki/contribute/_Sidebar.md @@ -0,0 +1,4 @@ +## Table of Contents +- [Previous (Rendering Configuration)](../rendering/Rendering.md) +- [Nest (FAQ)](../FAQ/FAQ.md) +- [Back to Home](../Home) diff --git a/wiki/deformation_engine.md b/wiki/deformation_engine.md deleted file mode 100644 index ee0bad8..0000000 --- a/wiki/deformation_engine.md +++ /dev/null @@ -1,82 +0,0 @@ -## DeformationEngine - -Here, the docs gives a brief explanation of deformation engine plugin. \ -In hydra cfg file (see `cfg/environment/**.yaml`), you have specific lines for terrain deformation. - -```yaml -deformation_engine: - enable: True - render_deform_inv: 10 - terrain_width: ${....lunaryard_settings.lab_width} - terrain_height: ${....lunaryard_settings.lab_length} - terrain_resolution: ${....lunaryard_settings.resolution} - gravity: [0, 0, -49.0] #mg - force_depth_slope: 0.00014 - force_depth_intercept: 0.008 - wheel_params: - wheel_width: 0.09 - wheel_radius: 0.1 - deform_constraint: - deform_offset: 0.0 - deform_decay_ratio: 0.01 - force_distribution: - distribution: sinusoidal - wave_frequency: 2.0 - boundary_distribution: - distribution: trapezoidal - angle_of_repose: 1.047 -``` - -### Wheel parameters - -You must specify the dimension of your wheels in meter. -```yaml -wheel_params: - wheel_width: 0.09 - wheel_radius: 0.1 -``` - -### Deformation Constraint -Here you will specify parameter for constraint. \ -`deform_offsest` is the distance between wheel origin and the center of deformation profile. \ -`deform_decay_ratio` is decaying parameter of deformation. \ -This is to limit deformation depth as rover traverse the same place many times. -```yaml -deform_constraint: - deform_offset: 0.0 - deform_decay_ratio: 0.01 -``` - -### Force Distribution -Controls distribution of force over wheel footprint. -You have two options for this. - -```yaml -force_distribution: - distribution: uniform -``` - -```yaml -force_distribution: - distribution: sinusoidal - wave_frequency: 2.0 -``` - -### Boundary Distribution -Controls boundary shape (y axis vs z axis with FLU convention). - -```yaml -boundary_distribution: - distribution: uniform -``` - -```yaml -boundary_distribution: - distribution: parabolic -``` - -```yaml -boundary_distribution: - distribution: trapezoidal - angle_of_repose: 1.047 -``` \ No newline at end of file diff --git a/wiki/environments/Environments.md b/wiki/environments/Environments.md index 83e105f..75037cd 100644 --- a/wiki/environments/Environments.md +++ b/wiki/environments/Environments.md @@ -613,298 +613,4 @@ rocks_settings: name: Uniform randomization_space: 1 seed: ${.......seed} -```## Environment Modes Configurations - -Modes are what allows the user to use the same environment for different purposes. Say you want to use the lunalab to run a robotic task, you can use the ROS1 or ROS2 modes. But if you wanted to use this environment to generate a dataset for rock detection, you could use the SDG mode. - -As of now we support 3 modes: -- ROS1: Noetic -- ROS2: Foxy, or Humble, also compatible with SpaceROS! -- SDG: Synthetic Data Generation - -As ROS1 is no longer supported, and is no longer shipped with the latest ubuntu releases, it will be phased out with the next release. Having both ROS1 and ROS2 creates more work when adding new features, but also makes docker container generation more complicated. - -Future release will include: -- SDG_SLAM: A mode to generate image sequence to evaluate SLAM & 3D reconstruction algorithms. -- SDG_LRO: A mode to generate LRO like images to test different set of algorithms. - -### ROS1 -This mode launches the simulation in ROS1 mode. This means that both the robots and the labs inside the simulation will be running using ROS1 nodes. There is no specific parameters for it. - -Example: -```yaml -name: ROS1 ``` - -**Important**: -- When loading a robot, make sure it's OmniGraphs (the recommended way to acquire sensors outputs for ROS) are ROS1 compatible. Not sure what they are? Check Nvidia's tutorials. -- Do not source ROS1 when running this simulation. - -This mode can be selected like so: -```bash -python.sh mode=ROS1 -``` - -### ROS2 -This mode launches the simulation in ROS2 mode. This means that both the robots and the labs inside the simulation will be running using ROS2 nodes. There are 3 available parameters: - -Arguments: -- name: (str), ROS2. It must be ROS2 nothing else. -- ROS_DOMAIN_ID: (int), A positive integer, denoting the ROS_DOMAIN_ID to use. Right now this is not functional. -- bridge_name: (str), either "foxy" or "humble". In the docker, the bridge must be humble. In a native installation, it can be either. It depends on which version of ROS2 is installed on your system. - -Example: -```yaml -name: ROS2 -ROS_DOMAIN_ID: 0 -bridge_name: humble -``` - -**Important**: -- When loading a robot, make sure it's OmniGraphs (the recommended way to acquire sensors outputs for ROS) are ROS2 compatible. Not sure what they are? Check Nvidia's tutorials. -- Before running the simulation make sure ROS2 is sourced. If you are using the foxy bridge source foxy, if you are using the humble bridge, source humbe. -- If you don't see the ROS2 topics make sure you followed the procedure to change the DDS to FastDDS. See the isaac instalation steps [here](). If this is happening in docker as well please let us know. - -This mode can be selected like so: -```bash -python.sh mode=ROS2 -``` - -### SDG -This mode launches the simulation in synthetic data generation mode. It's meant to be used to create datasets for object detection or semantic segmentation. For that it builds on top of replicator's data-acquisition pipeline, the part of replicator that focuses on getting data from sensors. - -Arguments: -- `num_images`: `(int)`, The total number of image to capture. -- `prim_path`: `(str)`, The path of a prim containing the camera. The scene will be traversed from here and the prims matching `camera_name` will be used to acquire data. Note, `camera_name` is a list. This can be used to do stereo imaging to train a depth network for instance. -- `camera_name`: `(list(str))`, A list of camera name to acquire data from. -- `camera_resolution`: `(list((int, int)))`, A list of camera resolutions. Must be the same length as `camera_name`. -- `data_dir`: `(str)`, The folder in which the data will be saved. Note that the recorded data will not be stored directly in it. Instead the simulation will create a folder with a random name to enable multiple runs without changing the name. -- `annotator_list`: `(list(list(str)))`, A list of list of annotators name. Assigns a list of annotators to be collected by the cameras. Must be the same length as `camera_name`. To know more about available annotators see below. -- `image_format`: `(list(str))`, Tells the simulation in which format to save the rgb or ir images. -- `annot_format`: `(list(str))`, Tells the simulation in which format to save the "boundingboxes". -- `element_per_folder`: `(str)`, Number of image to be stored in each folder. Setting this to 1000 can help reduce I/Os. - -Supported annotators: -- `RGB`: RGB image. -- `IR`: Gray scale RGB. -- `Depth`: Depth image which contains the raw distance. Saved as `npz`. -- `Pose`: The pose of the sensor in the global frame. Saved as a `csv`. -- `InstanceSemanticSegmentation`: -- `SemanticSegmentation`: - -> The simulation will automatically save the intrisics of your cameras when initialized. - -If there is no camera in the scene by default you can also create one. To do so, you'll need to create a `camera_setting` object inside the mode config file. - -Arguments: -- `camera_path`: `str`, The path at which the camera should be created. -- `focal_length`: `float`, The focal length of the camera. In cm. -- `horizontal_aperture`: `float`, The horizontal aperture of the camera. In cm. -- `vertical_aperture`: `float`, The vertical aperture. This is ignored, and the resolution is used instead. -- `fstop`: `float`, The fstop of the camera, set to 0.0 to disable. -- `focus_distance`: `float`, The focus distance in meters. Disabled if fstop is nulle. -- `clipping_range`: `((float, float))`, clipping range in meters. - -Example: -```yaml -name: SDG -generation_settings: - num_images: 1000 - prim_path: Camera - camera_name: [camera_annotations] - camera_resolution: [[640,480]] - data_dir: data - annotator_list: [["rgb", "semantic_segmentation", "instance_segmentation"]] - image_format: [png] - annot_format: [json] - element_per_folder: 1000 - -camera_settings: - camera_path: Camera/camera_annotations - focal_length: 1.93 - horizontal_aperture: 3.6 - vertical_aperture: 2.7 - fstop: 0.0 - focus_distance: 10.0 - clipping_range: ${as_tuple:0.01, 1000000.0} -``` -## Rendering Configs - -In the following we will go over the different configurations available to you to tweak the rendering in the simulation. - -### RTXRealTime & RTXInteractive - -Let's start by what they are. RTXRealTime is has it's name imply, a high FPS renderer that trades some of the rendering quality to push more frames per second. The RTXInteractive renderer makes less compromises on the rendering quality and hence the overall quality of rendered frame is higher at the cost of slower render time. - -We only expose a few parameters of the fairly large amount available to tune. They should be expended when time allows. - -Arguments: -- `samples_per_pixel_per_frame`: (`int`), RTXInteractive only. -- `max_bounces`: (`int`), RTXInteractive only. -- `max_specular_transmission_bounces`: (`int`), RTXInteractive only. -- `max_volume_bounces`: (`int`), RTXInteractive only. -- `subdiv_refinement_level`: (`int`), RTXInteractive only. -- `renderer`: (`str`), The type of renderer. `PathTracing` for RTXInteractive, `RayTracedLighting` for RTXRealTime. -- `headless`: (`bool`), Whether the simulation should be ran headless or not. - -Example: -```yaml -renderer: - renderer: "PathTracing" - headless: False - samples_per_pixel_per_frame: 32 - max_bounces: 6 - max_specular_transmission_bounces: 6 - max_volume_bounces: 4 - subdiv_refinement_level: 0 -``` -```yaml -renderer: - renderer: "RayTracedLighting" - headless: False - samples_per_pixel_per_frame: 32 - max_bounces: 6 - max_specular_transmission_bounces: 6 - max_volume_bounces: 4 - subdiv_refinement_level: 0 -``` - -### Lens Flares - -Should you want to make Michael Bay proud, you may be interested in adding lens flares. Though lens flares in isaac are pretty basic, so not sure he'll be that impressed. Regardless, here are the available settings! - -Arguments: -- `enable`: (bool), Set to true to enable the lens flare effect. -- `scale`: (float), The scale of the flare. 0 disables it. -- `blades`: (int), Number of blade used when simulating the flares. -- `aperture_rotation`: (float), Rotation of the lens' aperture. -- `sensor_diagona`l: (float), Size of the diagonal of the sensor used to simulate the flares. -- `sensor_aspect_ratio`: (float), Aspect ratio of the sensor used to simulate the flares. -- `fstop`: (float), fstop of the lens used to simulate the flares. -- `focal_length`: (float), Focal length of the lens used to simulate the flares. - -> Note: These camera parameters are completely independent of the ones you have inside the scene's cameras. - -Example: -```yaml -lens_flares: - enable: False - scale: 0.5 - blades: 9 - aperture_rotation: 0.0 - sensor_diagonal: 28.0 - sensor_aspect_ratio: 1.5 - fstop: 2.8 - focal_length: 12.0 -``` - -### Motion Blur - -To add motion blur to the rendered image, you can use the following arguments: - -Arguments: -- `enable`: `(bool)`, Set to true to enable motion blur. -- `max_blur_diameter_fraction`: `(float)`, TODO. -- `exposure_fraction`: `(float)`, TODO. -- `num_samples`: `(int)`, TODO. - -Example -```yaml -motion_blur: - enable: False - max_blur_diameter_fraction: 0.02 - exposure_fraction: 1.0 - num_samples: 8 -``` - -### Chromatic Aberrations - -To add chromatic aberrations to your renders, you can use the following arguments: - -Arguments: -- `enable`: `(bool)`, Set to true to enable chromatic aberrations. -- `strength`: `((float, float, float))`, The strength of the shift for each channel. Convention: R,G,B. -- `model`: `((str, str, str))`, The model to be used to distort the colors in each channel. Convention: R,G,B. Options are "Radial", "Barrel". - -Example: -```yaml -chromatic_aberration: - enable: False - strength: [-0.055, -0.075, 0.015] - model: ["Radial", "Radial", "Radial"] -```## Physics Configs - - -@dataclasses.dataclass -class PhysicsSceneConf: - dt: float = dataclasses.field(default_factory=float) - gravity: Tuple[float, float, float] = None - substeps: int = None - use_gpu_pipeline: bool = None - worker_thread_count: int = None - use_fabric: bool = None - enable_scene_query_support: bool = None - gpu_max_rigid_contact_count: int = None - gpu_max_rigid_patch_contact_count: int = None - gpu_found_lost_pairs_capacity: int = None - gpu_total_aggregate_pairs_capacity: int = None - gpu_max_soft_body_contacts: int = None - gpu_max_particle_contacts: int = None - gpu_heap_capacity: int = None - gpu_temp_buffer_capacity: int = None - gpu_max_num_partions: int = None - gpu_collision_stack_size: int = None - solver_type: str = None - enable_stabilization: bool = None - bounce_threshold_velocity: float = None - friction_offset_threshold: float = None - friction_correlation_distance: float = None - enable_ccd: bool = None - - def __post_init__(self): - self.physics_scene_args = {} - for attribute in dataclasses.fields(self): - if getattr(self, attribute.name) is not None: - self.physics_scene_args[attribute.name] = getattr(self, attribute.name) - - -Attributes: -- `dt`: `(float)`, The time step for each physics simulation update. Defines the amount of time that passes per frame for physics calculations. -- `gravity`: `(Tuple[float, float, float])`, The gravitational force vector applied in the simulation, defined as `(x, y, z)` where each axis represents a directional force in meters per second squared. -- `substeps`: `(int)`, The number of substeps for the physics solver. This helps with simulation accuracy, especially in high-speed or complex interactions. -- `use_gpu_pipeline`: `(bool)`, Whether to enable the GPU pipeline for physics processing. When `True`, computations are offloaded to the GPU, improving performance for large simulations. -- `worker_thread_count`: `(int)`, The number of threads allocated for physics processing. A higher count can improve performance but may increase CPU usage. -- `use_fabric`: `(bool)`, TODO -- `enable_scene_query_support`: `(bool)`, TODO -- `gpu_max_rigid_contact_count`: `(int)`, The maximum number of rigid body contacts that the GPU can handle per frame. -- `gpu_max_rigid_patch_contact_count`: `(int)`, The maximum number of patch contacts between rigid bodies that the GPU can process per frame. -- `gpu_found_lost_pairs_capacity`: `(int)`, The capacity for handling found and lost contact pairs in the GPU pipeline. Determines how many pairs can be processed before overflow occurs. -- `gpu_total_aggregate_pairs_capacity`: `(int)`, The total capacity for aggregate pairs (grouped objects) that can be processed by the GPU. -- `gpu_max_soft_body_contacts`: `(int)`, The maximum number of soft body contacts the GPU can process. Soft bodies include deformable objects such as cloth or elastic materials. -- `gpu_max_particle_contacts`: `(int)`, The maximum number of particle contacts the GPU can process. This typically applies to particle-based simulations such as fluids or granular materials. -- `gpu_heap_capacity`: `(int)`, The heap memory capacity reserved for GPU physics processing. -- `gpu_temp_buffer_capacity`: `(int)`, The temporary buffer size for the GPU pipeline during physics computations. -- `gpu_max_num_partions`: `(int)`, The maximum number of partitions the GPU can handle, related to splitting the physics scene into smaller sections for processing. -- `gpu_collision_stack_size`: `(int)`, The stack size allocated for handling collisions on the GPU. -- `solver_type`: `(str)`, The type of solver used for physics simulation. Common values include `PBD` (Position-Based Dynamics) or `TGS` (Temporal Gauss-Seidel). -- `enable_stabilization`: `(bool)`, Whether to enable stabilization for the solver, which helps reduce jitter and improve the stability of simulations involving contact or collision. -- `bounce_threshold_velocity`: `(float)`, The velocity threshold for bounce calculations. Objects with a velocity below this threshold will not bounce upon impact. -- `friction_offset_threshold`: `(float)`, The offset distance used when applying friction between objects in contact. Affects how friction is calculated based on the distance between objects. -- `friction_correlation_distance`: `(float)`, The correlation distance for friction calculation. Defines the area over which friction is applied between two surfaces. -- `enable_ccd`: `(bool)`, Whether to enable Continuous Collision Detection (CCD). CCD prevents fast-moving objects from passing through one another by performing more frequent collision checks. - -> - GPU-specific settings are important for optimizing large simulations, especially when dealing with rigid bodies, soft bodies, and particles. -> - The number of substeps and solver type significantly impact the accuracy and stability of the physics simulation. -> - Using the GPU pipeline and adjusting thread count allows for performance improvements, particularly in complex scenes. -> - The stabilization options and collision detection settings like CCD help avoid errors in physics calculations, such as objects passing through one another or jittering at rest. - -Example: -```yaml -physics_scene: - dt: 0.16666 - gravity: [0.0, 0.0, -1.62] - enable_ccd: true - enable_stabilization: false - solver_type: PGS - use_gpu_pipeline: false -``` \ No newline at end of file diff --git a/wiki/environments/_Footer.md b/wiki/environments/_Footer.md new file mode 100644 index 0000000..606036d --- /dev/null +++ b/wiki/environments/_Footer.md @@ -0,0 +1 @@ +Antoine Richard -- University of Luxembourg -- Space Robotics Group -- 2023-24 diff --git a/wiki/environments/_Sidebar.md b/wiki/environments/_Sidebar.md index 3ae2686..56cbfb9 100644 --- a/wiki/environments/_Sidebar.md +++ b/wiki/environments/_Sidebar.md @@ -1,6 +1,6 @@ ## Table of Contents - -- [Configurations](#configurations) +- [Previous (Mode Configurations)](../modes/Modes.md) +- [Environment Configurations](#configurations) - [How to Hydra](#how-to-hydra) - [Environments Configs](#environments-configs) - [Lunalab](#lunalab) @@ -15,12 +15,5 @@ - [Request](#request) - [Request Group](#request-group) - [Rock Generation](#rock-generation) - - [ROS1](#ros1) - - [ROS2](#ros2) - - [SDG](#sdg) - - [Rendering Configs](#rendering-configs) - - [RTXRealTime & RTXInteractive](#rtxrealtime--rtxinteractive) - - [Lens Flares](#lens-flares) - - [Motion Blur](#motion-blur) - - [Chromatic Aberrations](#chromatic-aberrations) +- [Next](../robots/Robots.md) - [Back to Home](../Home) \ No newline at end of file diff --git a/wiki/environments/env_1_base.mdpp b/wiki/environments/env_1_base.mdpp deleted file mode 100644 index 2f9bb08..0000000 --- a/wiki/environments/env_1_base.mdpp +++ /dev/null @@ -1,44 +0,0 @@ -# Configurations - -The following provide detailed explenations on how the simulation can be configured. To managed our configurations we rely on [hydra](https://hydra.cc/docs/intro/) a configuration manager. We'll start by getting familiar with Hydra. - -## How to Hydra - -In short hydra allows to combined multiple .yaml file into a single configuration, it also allows to change the value of one of the file's parameters on the fly. Finally hydra provides a mean to perform simple operations inside a yaml file. - -Our default configuration is the following: -```yaml -defaults: - - environment: lunalab - - rendering: ray_tracing - - mode: ROS2 - - physics: default_physics - -hydra: - output_subdir: null - run: - dir: . -``` -This means that running: -```bash -python.sh run.py -``` -Will result in running the simulation using the following configs: -- cfg/environment/lunalab.yaml -- cfg/rendering/ray_tracing.yaml -- cfg/mode/ROS2.yaml -- cfg/physics/default_physics.yaml - -To use a different environment one could run: -```bash -python.sh run.py environment=lunaryard_20m -``` -This will load the `cfg/environment/lunaryard_20m.yaml` file instead of the lunalab one. -The same logic applies to the rest of the configs. -To override a single parameter one could run: -```bash -python.sh run.py environment=lunaryard_20m environment.stellar_engine_settings.start_date.year=2023 -``` -This will change the year of the starting date of the stellar engine. - -Now that you know hydra's basics, let's jump into how to configure the different environments. diff --git a/wiki/environments/env_2_environments.mdpp b/wiki/environments/env_2_environments.mdpp deleted file mode 100644 index fb1cb15..0000000 --- a/wiki/environments/env_2_environments.mdpp +++ /dev/null @@ -1,571 +0,0 @@ -## Environments Configs - -In the following we go through the different environments as well as the settings that can be used to tune them. -Here is the list of default environments that can be generated: -- The [Lunalab](#lunalab), an digital twin of the lunalab at the university of Luxembourg. -- The [lunaryard](#lunaryard), a small procedural environment meant for basic testing. -- The [large_scale](#largescale), a large scale semi-procedural environment meant for full fledged tests. - -Upcoming environments: -- The `rover_scape` from NASA Ames, at the NASA ARC, CA, USA. -- The `the_moon_rostock` from PTS space in Rostock's Airport, Germany. -- The `confined_large_scale`, a visually large environment that allows for terrain deformation. - -> All the environments are seeded and unique per seed. That means that they are also reproducible. Given a seed the environment should always be the same. - - -### Lunalab - -The `lunalab` environment is a replica of the Lunalab [1] from the University of Luxembourg. This 10.0 by 6.5 meter -environment allows to test rovers at the uni of luxembourg. The ground is made of small basalt rocks, and can be used -to perform small scale tests prior to large scale testing in analog environments. This environment was modeled in -blender and provides 2 terrain that were scanned using a total station. - -> This environment is compatible with deformable terrains! - -![Sample image lunalab](../media/env_img/lunalab.png) - - -Environment arguments: -- `projector_position`: `(float3)`, The position of the projector in the scene. To replicate similar scenarios to that of the lab, we'd recommend using the following settings: \[0.5\ A complete example of a lunalab environment configuration can be found in: `cfg/environment/lunalab.yaml` - -### Lunaryard - -The `lunaryard` is a procedural small scale environment (from 10 to 80 meters) meant to perform simple tests with different algorithms. It's simplicity means it will easily run on most machines and will allow to perform basic debugging steps. - -> This environment is compatible with deformable terrains! - -![Sample image lunaryard](../media/env_img/lunaryard_husky_ex1.png) - -Environment arguments: -- `lab_length`: `(float)`, The length of the lab in meters. While there is no enforced limits we would recommend staying below 100 meters. -- `lab_width`: `(float)`, The width of the lab in meters. While there is no enforced limits we would recommend staying below 100 meters. -- `resolution`: `(float)`, The size of the pixels used to generate the map from which the terrain is derived. Also know as meters-per-pixel (mpp). -- `terrain_id`: `(int)`, The id of the terrain. More on that in [Terrain Generator](#extras-terrain). -- `coordinates`: `(Coordinates)`, The [coordinates](#coordinates) of the terrain. This is used by the [stellar engine](#stellar-engine) to compute accurate sun and earth positions. -- `earth_elevation`: `(float)`, The elevation of the earth in degrees. Overwritten if the [stellar engine](#stellar-engine) is enabled. -- `earth_azimuth`: `(float)`, The azimuth of the earth in degrees. Overwritten if the [stellar engine](#stellar-engine) is enabled. -- `earth_distance`: `(float)`, The distance between the earth and the moon in meters (Give a non-scaled value). Overwritten if the [stellar engine](#stellar-engine) is enabled. - -The lunaryard can be futher customized by using one of the following objects: -- [Sun](#sun), an object allowing to tune the sun settings. -- [Stellar Engine](#extra-sun), an object allowing to move the earth and sun based on the current time and coordinates on the moon. -- [Rock Generator](#extras-rocks), an object that can spawn rocks on the generated terrain. -- [Terrain Generator](#extras-terrain), an object that is used to define how procedurally generated terrain look. It also allows to set the terrain deformation parameters as well as loading DEM. - -> A complete example of a lunaryard environment configuration can be found in: `cfg/environment/lunayard_20m.yaml` - - -### LargeScale - -The `large_scale` environment is meant to fully test navigation and mapping algorithms. It offers the ability to perform -very long traverses (20km+) while maintaining a locally very high resolution terrain mesh. This environment is a lot -more resource intensive than the others, be it on the CPU, RAM, GPU, and VRAM. - -> This environment is **not** compatible with deformable terrains yet. - -![Sample image large scale](../media/env_img/large_scale.png) - -This environment offers significantly more configuration settings than the others. Though we would recommend not to change them. - -Environment arguments: -- `seed`: `(int)`, The global seed for the configuration. It automatically sets all the other seeds involved in the generation of the environment. Can be overriden. -- `crater_gen_seed`: `(int)`, Overrides the global seed. -- `crater_gen_distribution_seed`: `(int)`, Overrides the global seed. -- `crater_gen_metadata_seed`: `(int)`, Overrides the global seed. -- `rock_gen_main_seed`: `(int)`, Overrides the global seed. - -- `profiling`: `(bool)`, Whether the profiler should be turned on. True means the profiler is enabled. -- `update_every_n_meters`: `(float)`, The amount of distance that need to be crossed to trigger an update of the terrain. -- `z_scale`: `(float)`, The scaling value for height of the terrains. -- `block_size`: `(int)`, The size in meters of a terrain block. - -- `dbs_max_elements`: `(int)`, The maximum number of elements that can be stored in a databese. -- `dbs_save_to_disk`: `(bool)`, Whether the databases should be saved on disk. Not enabled yet. -- `dbs_write_interval`: `(int)`, How often the databases should be wrote to disk after an update. - -- `hr_dem_resolution`: `(float)`, The resolution in meters per pixel of the procedurally generated high resolution map. -- `hr_dem_generate_craters`: `(bool)` Whether craters should be added onto the high resolution map. If no craters are generated, the high resolution map is then just a bicubic interpolation of the original DEM. If true generates craters. -- `hr_dem_interpolation_padding`: `(int)` The amount of padding used when interpolating the original DEM, we recommend setting this to 2, as it's the amount required to perform bicubic interpolation without artefacts. - -- `lr_dem_folder_path`: `(str)`, Path to the folder containing the low-resolution DEM. -- `lr_dem_name`: `(str)`, Name of the low-resolution DEM file. -- `starting_position`: `(tuple)`, Starting position of the terrain generation in meters from the center of the map. - -- `geo_cm_num_texels_per_level`: `(int)`, Number of texels per level in the geometry clip map. -- `geo_cm_target_res`: `(float)`, The target resolution of the geometry clip map. -- `geo_cm_fine_interpolation_method`: `(str)`, Method used for the interpolation of the fine geometry clip map, options are `bilinear` or `bicubic`. -- `geo_cm_coarse_interpolation_method`: `(str)`, Method used for the interpolation of the coarse geometry clip map, options are `bilinear` or `bicubic`. -- `geo_cm_fine_acceleration_mode`: `(str)`, The mode of acceleration for the fine geometry clip map update, options are `gpu` or `hybrid`. -- `geo_cm_coarse_acceleration_mode`: `(str)`, The mode of acceleration for the coarse geometry clip map update, options are `gpu` or `hybrid`. -- `geo_cm_apply_smooth_shading`: `(bool)`, Whether to apply smooth shading to the geometry clip maps. -- `geo_cm_semantic_label`: `(str)`, A label for the type of surface being generated, e.g., `terrain`. -- `geo_cm_texture_name`: `(str)`, Name of the texture to use for the terrain surface. -- `geo_cm_texture_path`: `(str)`, Path to the texture file for the terrain surface. - -- `terrain_collider_enabled`: `(bool)`, Whether the terrain collider should be enabled. -- `terrain_collider_resolution`: `(float)`, The resolution of the terrain collider in meters. -- `terrain_collider_mode`: `(str)`, Mode for terrain collider generation, e.g., `meshSimplification`. -- `terrain_collider_cache_size`: `(int)`, Size of the cache for storing terrain colliders. That is the maximum amount of `block_size`x`block_size` meters colliders used in the scene. -- `terrain_collider_building_threshold`: `(float)`, Threshold for building terrain colliders. Minimum distance from a collider boundary to trigger the generation of a new ones. Can affect colliders-based lidars. - -- `rock_gen_cfgs`: `(list)`, List of configurations for rock generation, each configuration specifying parameters for rock size, density, and placement. - -> Notes & considerations: -> - All seeds can be individually overridden, but if not provided, the global seed is used by default. -> - Queue sizes for the terrain generation process affect memory usage and parallelism performance. -> - The geometry clip map parameters allow fine-tuning of how terrain is generated, interpolated, and shaded. Increasing the number of texels and reducing the resolution can have adverse effects on the update time of the terrain's visual mesh. -> - In Isaac, colliders cannot be generated asynchronously from the main simulation thread. Hence, they are only generated when necessary. If your robot is using a "PhysX based lidar", it will not seen the terrain as the robot comes close to the edge of a collider. Use an "RTX-based lidar" instead. - - -The large scale environments can be futher customized by using one of the following objects: -- [Sun](#sun), an object allowing to tune the sun settings. -- [Stellar Engine](#extra-sun), an object allowing to move the earth and sun based on the current time and coordinates on the moon. - -> A complete example of a large_scale environment configuration can be found in: `cfg/environment/largescale.yaml` - -## Extras: Light Sources - -In the following we detail how the sun can be customized. This argument is only applicable to "open space" environments such as the [LargeScale](#largescale) and [Lunaryard](#lunaryard). - -### Sun - -This allows to customize the default parameters for the Sun in the [LargeScale](#largescale) and [Lunaryard](#lunaryard) environments. - -Parameters: -- `intensity`: `(float)`, The intensity of the sun light. The higher the value, the brighter the scene will be. -- `angle`: `(float)`, The angle of the sun light in degrees. Note that this denotes the size of the sun in sky, not its azimuth or elevation. The larger the angle, the bigger the sun will appear. -- `diffuse_multiplier`: `(float)`, A multiplier for the effect of the sun has on the diffuse response of materials. It can be used to create stronger flares by setting this value to 0.1 and multiplying the light intensity by 10. -- `specular_multiplier`: `(float)`, A multiplier for the effect the sun has on the specular response of materials. It can be used to create stronger flares by setting this value to 0.1 and multiplying the light intensity by 10. -- `color`: `((float, float, float))`, The color to be given to the light. Format is (R,G,B), with 0.0 <= R,G,B <= 1.0. -- `temperature`: `(float)`, The temperature of the light source in Kelvin. -- `azimuth`: `(float)`, The azimuth of the sun in degrees. If the [Stellar Engine](#stellar-engine) is enabled it will override this parameter. -- `elevation`: `(float)`, The elevation of the sun in degrees. If the [Stellar Engine](#stellar-engine) is enabled it will override this parameter. - -Example: -```yaml -sun_settings: - intensity: 1750.0 - angle: 0.53 - diffuse_multiplier: 1.0 - specular_multiplier: 1.0 - color: [1.0, 1.0, 1.0] - temperature: 6500.0 - azimuth: 180.0 - elevation: 45.0 -``` - -### Coordinates - -This allows to set the coordinates of the [Lunaryard](#lunaryard) environment. The coordinate is used by the [Stellar Engine](#stellar-engine) to compute the position of the sun and earth for a given date. - -Parameters: -- `latitude`: `(float)`, The latitude of the environment in degrees. -- `longitude`: `(float)`, The longitude of the environment in degrees. - -Example: -```yaml -coordinates: - latitude: 46.8 - longitude: -26.3 -``` - -### Date - -This allows to set the date of the [LargeScale](#largescale) and [Lunaryard](#lunaryard) environments. The date is used by the [Stellar Engine](#stellar-engine) to compute the position of the sun and earth for a given coordinate on the moon. - -Parameters: -- `year`: `(int)`, The year. -- `month`: `(int)`, The month. -- `day`: `(int)`, The day. -- `hour`: `(int)`, The hour. -- `minute`: `(int)`, The minute. - -Example: -```yaml -start_date: - year: 2024 - month: 5 - day: 1 - hour: 12 - minute: 50 -``` -Used inside the [Stellar Engine](#stellar-engine)'s configuration. - -### Stellar Engine - -The Stellar uses both the [Date](#date) and the [Coordinates](#coordinates) to estimate the position of the sun and earth in the lunar sky. - -**Known limitations**: We use [skyfield] to compute the position of the earth and sun. This python library does not support well multi-segment ephemeris. Hence we recommend to use the ones provided with the sim. - -Parameters: -- `start_date`: `(Date)`, a date as defined in [Date](#date-configuration). -- `time_scale`: `(float)`, a time multiplier that allows to make time pass faster of slower. -- `update_interval`: `(float)`, the amount of scaled time that must pass for the position of the stellar bodies to be updated. -- `distance_scale`: `(float)`, the scaling factor to be applied to the distance between the center of the scene and the earth. A value below 1 will lead to the distance being reduced. -- `ephemeris_path`: `(str)`, the path to the ephemeris data. -- `ephemeris`: `(str)`, the name of the ephemeris. -- `moon_pa`: `(str)`, the name of the "spice binary lunar pck". -- `moon_tf`: `(str)`, the name of the "frame kernel". -- `pck`: `(str)`, the name of the "pck". -- `frame`: `(str)`, the name of the frame to be used. - -Example: -```yaml -stellar_engine_settings: - start_date: - year: 2024 - month: 5 - day: 1 - hour: 12 - minute: 50 - time_scale: 1 - update_interval: 600 - distance_scale: 0.001 - ephemeris_path: assets/Ephemeris - ephemeris: de421.bsp - moon_pa: moon_pa_de421_1900-2050.bpc - moon_tf: moon_080317.tf - pck: pck00008.tpc - frame: MOON_ME_DE421 -``` - -## Extras: Rocks - -In this section we provide some details regarding the distribution of rocks in the scene. This is only applicable to small scale environments such as the [Lunalab](#lunalab) or the [Lunaryard](#lunaryard). Large scale environments rely on different methods to generate and manage rocks. - -To generate rocks we rely 3 different objects. The base block is a [request](#request), it assigns a type of parameter to be randomized with a given distribution. A [group of requests](#request-group), that is a bundle of requests. And finally a [rock generation configuration](#rock-generation). -How to set up these is explained below: -- [request](#request) -- [request group](#request-group) -- [rock generation configuration](#rock-generation) - -### Request -A request allows to set a given parameter of the rocks to be randomized. As of now, we only randomize so called `xformOp`s. These are a set of geometric transformation that control the scale, rotation, and translation of assets in OpenUSD. A request applies a statistical distribution, like a `uniform` distribution on a geometric primitive, or a digital elevation map. The axes on which the randomization should be applied can also be selected. - -Parameters: -- `attribute`: `(str)`, The name of the attribute to be randomized. Can be `Scale`, `Orientation`, or `Position`. -- `axes`: `(list)`, The axis of the selected attribute to be randomized. A list containing `x`, `y`, `z`, `w`. Note that the orientation is always defined as a quaternion. Aggregating multiple dimmensions i.e. writing `xyz` means that the values for `x` `y` and `z` will be the same. -- `num`: `(int)`, The number of points to be generated. If there is a PointProcess, or a ClusterPointProcess inside the same [request group](#request-group) this parameter should not be set. If there is none, it should be similar for all requests within the same [request group](#request-group). -- `inherit_parents`: `(bool)`, If the distribution has a parent distribution. This is only applicable to "ClusterPointProcesses" kind of distributions. -- `layer`: `str`, the layer object to sample on. More info is given [here](#request-layers). -- `sampler`: `str`, the sampler object to sample from. More info is given [here](#request-samplers) - -Examples: - -Single request, that scales the x y an z dimensions similarly. The values range from 0.01 to 0.05 and the distribution used is a uniform distribution. -```yaml -req_scale: - attribute: Scale - axes: ["xyz"] - num: 1000 - inherit_parents: False - layer: - name: Line - xmin: 0.01 - xmax: 0.05 - sampler: - name: Uniform - randomization_space: 1 - seed: 42 -``` - -Single request where the orientation is sampled for a given axis. Here the yaw is randomized. -```yaml -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: 42 -``` - -### Request Group - -A request group defines a bundle of requests to execute, the type of assets to be used, and whether of not we should use an instancer. - -Parameters: -- `seed`: `(int)`, the seed to be used. -- `collections`: `(str)`, the name of the folder in which the rocks are saved. -- `use_point_instancer`: `(bool)`, if the assets should be generated with an instancer or not. **Limitations of instancers in isaac sim**: they do not work well with semantic information. Hence, if you want to collect semantic data, do not use them! -- `parent`: `(str)`, to be set if another [request group](#request-group) if the parent of this one. Set to the name of that other [request group](#request-group). -- `requests`: `list[request]`, the list of requests to be executed. - -Example: - -A request group without parent. -```yaml -medium_rocks: - seed: ${....seed} - collections: ["apollo_rocks"] # Uses the apollo rocks inside assets/USD_Assets/rocks - use_point_instancer: True # Set to True for fast sampling, set to False for SDG - requests: - req_pos_xy: # Sample XY position - attribute: Position - axes: ["x", "y"] - layer: - name: Image - mpp_resolution: ${.......lunaryard_settings.resolution} - output_space: 2 - sampler: - name: ThomasCluster - randomization_space: 2 - lambda_parent: 0.25 - lambda_daughter: 200 - sigma: 0.2 - seed: ${.......seed} - - req_pos_z: # Get Z from the elevation map. - attribute: Position - axes: ["z"] - layer: - name: Image - output_space: 1 - sampler: - name: Image - randomization_space: 1 - mpp_resolution: ${.......lunaryard_settings.resolution} - - req_random_z_rot: # Randomize Z orientation - 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: # Randomize the scale homogeneously. - attribute: Scale - axes: ["xyz"] - layer: - name: Line - xmin: 1.0 - xmax: 1.0 - sampler: - name: Uniform - randomization_space: 1 - seed: ${.......seed} -``` - - -### Rock Generation - -This aggregates multiple requests groups. - -Parameters: -- `instancers_path`: `(str)`, The path where the instancers will be generated. -- `rocks_settings`: `(list(request_group))`, A list of request groups. - -Example: -```yaml -rocks_settings: - instancers_path: /Lunaryard/Rocks - rocks_settings: - medium_rocks: - seed: ${....seed} - collections: ["apollo_rocks"] - use_point_instancer: True - requests: - req_pos_xy: - attribute: Position - axes: ["x", "y"] - layer: - name: Image - mpp_resolution: ${.......lunaryard_settings.resolution} - output_space: 2 - sampler: - name: ThomasCluster - randomization_space: 2 - lambda_parent: 0.25 - lambda_daughter: 200 - sigma: 0.2 - seed: ${.......seed} - - req_pos_z: - attribute: Position - axes: ["z"] - layer: - name: Image - output_space: 1 - sampler: - name: Image - randomization_space: 1 - mpp_resolution: ${.......lunaryard_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} - - large_rocks: - seed: ${....seed} - collections: ["apollo_rocks"] - use_point_instancer: True - parent: medium_rocks - requests: - req_pos_xy: - attribute: Position - axes: ["x", "y"] - layer: - name: Image - mpp_resolution: ${.......lunaryard_settings.resolution} - output_space: 2 - sampler: - name: ThomasCluster - randomization_space: 2 - lambda_parent: 0.25 - lambda_daughter: 5 - sigma: 0.05 - inherit_parents: True - seed: ${.......seed} - - req_pos_z: - attribute: Position - axes: ["z"] - layer: - name: Image - output_space: 1 - sampler: - name: Image - randomization_space: 1 - mpp_resolution: ${.......lunaryard_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: 2.0 - xmax: 5.0 - sampler: - name: Uniform - randomization_space: 1 - seed: ${.......seed} - - small_rocks: - seed: ${....seed} - collections: ["apollo_rocks"] - use_point_instancer: True - parent: medium_rocks - requests: - req_pos_xy: - attribute: Position - axes: ["x", "y"] - layer: - name: Image - mpp_resolution: ${.......lunaryard_settings.resolution} - output_space: 2 - sampler: - name: ThomasCluster - randomization_space: 2 - lambda_parent: 0.5 - lambda_daughter: 500 - sigma: 0.3 - inherit_parents: True - seed: ${.......seed} - - req_pos_z: - attribute: Position - axes: ["z"] - layer: - name: Image - output_space: 1 - sampler: - name: Image - randomization_space: 1 - mpp_resolution: ${.......lunaryard_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: 0.01 - xmax: 0.05 - sampler: - name: Uniform - randomization_space: 1 - seed: ${.......seed} -``` \ No newline at end of file diff --git a/wiki/environments/env_3_modes.mdpp b/wiki/environments/env_3_modes.mdpp deleted file mode 100644 index ecadaa4..0000000 --- a/wiki/environments/env_3_modes.mdpp +++ /dev/null @@ -1,115 +0,0 @@ -## Environment Modes Configurations - -Modes are what allows the user to use the same environment for different purposes. Say you want to use the lunalab to run a robotic task, you can use the ROS1 or ROS2 modes. But if you wanted to use this environment to generate a dataset for rock detection, you could use the SDG mode. - -As of now we support 3 modes: -- ROS1: Noetic -- ROS2: Foxy, or Humble, also compatible with SpaceROS! -- SDG: Synthetic Data Generation - -As ROS1 is no longer supported, and is no longer shipped with the latest ubuntu releases, it will be phased out with the next release. Having both ROS1 and ROS2 creates more work when adding new features, but also makes docker container generation more complicated. - -Future release will include: -- SDG_SLAM: A mode to generate image sequence to evaluate SLAM & 3D reconstruction algorithms. -- SDG_LRO: A mode to generate LRO like images to test different set of algorithms. - -### ROS1 -This mode launches the simulation in ROS1 mode. This means that both the robots and the labs inside the simulation will be running using ROS1 nodes. There is no specific parameters for it. - -Example: -```yaml -name: ROS1 -``` - -**Important**: -- When loading a robot, make sure it's OmniGraphs (the recommended way to acquire sensors outputs for ROS) are ROS1 compatible. Not sure what they are? Check Nvidia's tutorials. -- Do not source ROS1 when running this simulation. - -This mode can be selected like so: -```bash -python.sh mode=ROS1 -``` - -### ROS2 -This mode launches the simulation in ROS2 mode. This means that both the robots and the labs inside the simulation will be running using ROS2 nodes. There are 3 available parameters: - -Arguments: -- name: (str), ROS2. It must be ROS2 nothing else. -- ROS_DOMAIN_ID: (int), A positive integer, denoting the ROS_DOMAIN_ID to use. Right now this is not functional. -- bridge_name: (str), either "foxy" or "humble". In the docker, the bridge must be humble. In a native installation, it can be either. It depends on which version of ROS2 is installed on your system. - -Example: -```yaml -name: ROS2 -ROS_DOMAIN_ID: 0 -bridge_name: humble -``` - -**Important**: -- When loading a robot, make sure it's OmniGraphs (the recommended way to acquire sensors outputs for ROS) are ROS2 compatible. Not sure what they are? Check Nvidia's tutorials. -- Before running the simulation make sure ROS2 is sourced. If you are using the foxy bridge source foxy, if you are using the humble bridge, source humbe. -- If you don't see the ROS2 topics make sure you followed the procedure to change the DDS to FastDDS. See the isaac instalation steps [here](). If this is happening in docker as well please let us know. - -This mode can be selected like so: -```bash -python.sh mode=ROS2 -``` - -### SDG -This mode launches the simulation in synthetic data generation mode. It's meant to be used to create datasets for object detection or semantic segmentation. For that it builds on top of replicator's data-acquisition pipeline, the part of replicator that focuses on getting data from sensors. - -Arguments: -- `num_images`: `(int)`, The total number of image to capture. -- `prim_path`: `(str)`, The path of a prim containing the camera. The scene will be traversed from here and the prims matching `camera_name` will be used to acquire data. Note, `camera_name` is a list. This can be used to do stereo imaging to train a depth network for instance. -- `camera_name`: `(list(str))`, A list of camera name to acquire data from. -- `camera_resolution`: `(list((int, int)))`, A list of camera resolutions. Must be the same length as `camera_name`. -- `data_dir`: `(str)`, The folder in which the data will be saved. Note that the recorded data will not be stored directly in it. Instead the simulation will create a folder with a random name to enable multiple runs without changing the name. -- `annotator_list`: `(list(list(str)))`, A list of list of annotators name. Assigns a list of annotators to be collected by the cameras. Must be the same length as `camera_name`. To know more about available annotators see below. -- `image_format`: `(list(str))`, Tells the simulation in which format to save the rgb or ir images. -- `annot_format`: `(list(str))`, Tells the simulation in which format to save the "boundingboxes". -- `element_per_folder`: `(str)`, Number of image to be stored in each folder. Setting this to 1000 can help reduce I/Os. - -Supported annotators: -- `RGB`: RGB image. -- `IR`: Gray scale RGB. -- `Depth`: Depth image which contains the raw distance. Saved as `npz`. -- `Pose`: The pose of the sensor in the global frame. Saved as a `csv`. -- `InstanceSemanticSegmentation`: -- `SemanticSegmentation`: - -> The simulation will automatically save the intrisics of your cameras when initialized. - -If there is no camera in the scene by default you can also create one. To do so, you'll need to create a `camera_setting` object inside the mode config file. - -Arguments: -- `camera_path`: `str`, The path at which the camera should be created. -- `focal_length`: `float`, The focal length of the camera. In cm. -- `horizontal_aperture`: `float`, The horizontal aperture of the camera. In cm. -- `vertical_aperture`: `float`, The vertical aperture. This is ignored, and the resolution is used instead. -- `fstop`: `float`, The fstop of the camera, set to 0.0 to disable. -- `focus_distance`: `float`, The focus distance in meters. Disabled if fstop is nulle. -- `clipping_range`: `((float, float))`, clipping range in meters. - -Example: -```yaml -name: SDG -generation_settings: - num_images: 1000 - prim_path: Camera - camera_name: [camera_annotations] - camera_resolution: [[640,480]] - data_dir: data - annotator_list: [["rgb", "semantic_segmentation", "instance_segmentation"]] - image_format: [png] - annot_format: [json] - element_per_folder: 1000 - -camera_settings: - camera_path: Camera/camera_annotations - focal_length: 1.93 - horizontal_aperture: 3.6 - vertical_aperture: 2.7 - fstop: 0.0 - focus_distance: 10.0 - clipping_range: ${as_tuple:0.01, 1000000.0} -``` diff --git a/wiki/environments_configs.md b/wiki/environments_configs.md deleted file mode 100644 index b8f4fa8..0000000 --- a/wiki/environments_configs.md +++ /dev/null @@ -1,572 +0,0 @@ -## Environments Configs - -In the following we go through the different environments as well as the settings that can be used to tune them. -Here is the list of default environments that can be generated: -- The [Lunalab](#lunalab), an digital twin of the lunalab at the university of Luxembourg. -- The [lunaryard](#lunaryard), a small procedural environment meant for basic testing. -- The [large_scale](#largescale), a large scale semi-procedural environment meant for full fledged tests. - -Upcoming environments: -- The `rover_scape` from NASA Ames, at the NASA ARC, CA, USA. -- The `the_moon_rostock` from PTS space in Rostock's Airport, Germany. -- The `confined_large_scale`, a visually large environment that allows for terrain deformation. - -> All the environments are seeded and unique per seed. That means that they are also reproducible. Given a seed the environment should always be the same. - -> Configurations are managed using [hydra](https://hydra.cc/docs/intro/) a configuration manager. - -### Lunalab - -The `lunalab` environment is a replica of the Lunalab [1] from the University of Luxembourg. This 10.0 by 6.5 meter -environment allows to test rovers at the uni of luxembourg. The ground is made of small basalt rocks, and can be used -to perform small scale tests prior to large scale testing in analog environments. This environment was modeled in -blender and provides 2 terrain that were scanned using a total station. - -> This environment is compatible with deformable terrains! - -![Sample image lunalab](./media/lunalab.png) - - -Environment arguments: -- `projector_position`: `(float3)`, The position of the projector in the scene. To replicate similar scenarios to that of the lab, we'd recommend using the following settings: \[0.5\ A complete example of a lunalab environment configuration can be found in: `cfg/environment/lunalab.yaml` - -### Lunaryard - -The `lunaryard` is a procedural small scale environment (from 10 to 80 meters) meant to perform simple tests with different algorithms. It's simplicity means it will easily run on most machines and will allow to perform basic debugging steps. - -> This environment is compatible with deformable terrains! - -![Sample image lunaryard](./media/lunaryard.png) - -Environment arguments: -- `lab_length`: `(float)`, The length of the lab in meters. While there is no enforced limits we would recommend staying below 100 meters. -- `lab_width`: `(float)`, The width of the lab in meters. While there is no enforced limits we would recommend staying below 100 meters. -- `resolution`: `(float)`, The size of the pixels used to generate the map from which the terrain is derived. Also know as meters-per-pixel (mpp). -- `terrain_id`: `(int)`, The id of the terrain. More on that in [Terrain Generator](#extras-terrain). -- `coordinates`: `(Coordinates)`, The [coordinates](#coordinates) of the terrain. This is used by the [stellar engine](#stellar-engine) to compute accurate sun and earth positions. -- `earth_elevation`: `(float)`, The elevation of the earth in degrees. Overwritten if the [stellar engine](#stellar-engine) is enabled. -- `earth_azimuth`: `(float)`, The azimuth of the earth in degrees. Overwritten if the [stellar engine](#stellar-engine) is enabled. -- `earth_distance`: `(float)`, The distance between the earth and the moon in meters (Give a non-scaled value). Overwritten if the [stellar engine](#stellar-engine) is enabled. - -The lunaryard can be futher customized by using one of the following objects: -- [Sun](#sun), an object allowing to tune the sun settings. -- [Stellar Engine](#extra-sun), an object allowing to move the earth and sun based on the current time and coordinates on the moon. -- [Rock Generator](#extras-rocks), an object that can spawn rocks on the generated terrain. -- [Terrain Generator](#extras-terrain), an object that is used to define how procedurally generated terrain look. It also allows to set the terrain deformation parameters as well as loading DEM. - -> A complete example of a lunaryard environment configuration can be found in: `cfg/environment/lunayard_20m.yaml` - - -### LargeScale - -The `large_scale` environment is meant to fully test navigation and mapping algorithms. It offers the ability to perform -very long traverses (20km+) while maintaining a locally very high resolution terrain mesh. This environment is a lot -more resource intensive than the others, be it on the CPU, RAM, GPU, and VRAM. - -> This environment is **not** compatible with deformable terrains yet. - -![Sample image large scale](./media/large_scale.png) - -This environment offers significantly more configuration settings than the others. Though we would recommend not to change them. - -Environment arguments: -- `seed`: `(int)`, The global seed for the configuration. It automatically sets all the other seeds involved in the generation of the environment. Can be overriden. -- `crater_gen_seed`: `(int)`, Overrides the global seed. -- `crater_gen_distribution_seed`: `(int)`, Overrides the global seed. -- `crater_gen_metadata_seed`: `(int)`, Overrides the global seed. -- `rock_gen_main_seed`: `(int)`, Overrides the global seed. - -- `profiling`: `(bool)`, Whether the profiler should be turned on. True means the profiler is enabled. -- `update_every_n_meters`: `(float)`, The amount of distance that need to be crossed to trigger an update of the terrain. -- `z_scale`: `(float)`, The scaling value for height of the terrains. -- `block_size`: `(int)`, The size in meters of a terrain block. - -- `dbs_max_elements`: `(int)`, The maximum number of elements that can be stored in a databese. -- `dbs_save_to_disk`: `(bool)`, Whether the databases should be saved on disk. Not enabled yet. -- `dbs_write_interval`: `(int)`, How often the databases should be wrote to disk after an update. - -- `hr_dem_resolution`: `(float)`, The resolution in meters per pixel of the procedurally generated high resolution map. -- `hr_dem_generate_craters`: `(bool)` Whether craters should be added onto the high resolution map. If no craters are generated, the high resolution map is then just a bicubic interpolation of the original DEM. If true generates craters. -- `hr_dem_interpolation_padding`: `(int)` The amount of padding used when interpolating the original DEM, we recommend setting this to 2, as it's the amount required to perform bicubic interpolation without artefacts. - -- `lr_dem_folder_path`: `(str)`, Path to the folder containing the low-resolution DEM. -- `lr_dem_name`: `(str)`, Name of the low-resolution DEM file. -- `starting_position`: `(tuple)`, Starting position of the terrain generation in meters from the center of the map. - -- `geo_cm_num_texels_per_level`: `(int)`, Number of texels per level in the geometry clip map. -- `geo_cm_target_res`: `(float)`, The target resolution of the geometry clip map. -- `geo_cm_fine_interpolation_method`: `(str)`, Method used for the interpolation of the fine geometry clip map, options are `bilinear` or `bicubic`. -- `geo_cm_coarse_interpolation_method`: `(str)`, Method used for the interpolation of the coarse geometry clip map, options are `bilinear` or `bicubic`. -- `geo_cm_fine_acceleration_mode`: `(str)`, The mode of acceleration for the fine geometry clip map update, options are `gpu` or `hybrid`. -- `geo_cm_coarse_acceleration_mode`: `(str)`, The mode of acceleration for the coarse geometry clip map update, options are `gpu` or `hybrid`. -- `geo_cm_apply_smooth_shading`: `(bool)`, Whether to apply smooth shading to the geometry clip maps. -- `geo_cm_semantic_label`: `(str)`, A label for the type of surface being generated, e.g., `terrain`. -- `geo_cm_texture_name`: `(str)`, Name of the texture to use for the terrain surface. -- `geo_cm_texture_path`: `(str)`, Path to the texture file for the terrain surface. - -- `terrain_collider_enabled`: `(bool)`, Whether the terrain collider should be enabled. -- `terrain_collider_resolution`: `(float)`, The resolution of the terrain collider in meters. -- `terrain_collider_mode`: `(str)`, Mode for terrain collider generation, e.g., `meshSimplification`. -- `terrain_collider_cache_size`: `(int)`, Size of the cache for storing terrain colliders. That is the maximum amount of `block_size`x`block_size` meters colliders used in the scene. -- `terrain_collider_building_threshold`: `(float)`, Threshold for building terrain colliders. Minimum distance from a collider boundary to trigger the generation of a new ones. Can affect colliders-based lidars. - -- `rock_gen_cfgs`: `(list)`, List of configurations for rock generation, each configuration specifying parameters for rock size, density, and placement. - -> Notes & considerations: -> - All seeds can be individually overridden, but if not provided, the global seed is used by default. -> - Queue sizes for the terrain generation process affect memory usage and parallelism performance. -> - The geometry clip map parameters allow fine-tuning of how terrain is generated, interpolated, and shaded. Increasing the number of texels and reducing the resolution can have adverse effects on the update time of the terrain's visual mesh. -> - In Isaac, colliders cannot be generated asynchronously from the main simulation thread. Hence, they are only generated when necessary. If your robot is using a "PhysX based lidar", it will not seen the terrain as the robot comes close to the edge of a collider. Use an "RTX-based lidar" instead. - - -The large scale environments can be futher customized by using one of the following objects: -- [Sun](#sun), an object allowing to tune the sun settings. -- [Stellar Engine](#extra-sun), an object allowing to move the earth and sun based on the current time and coordinates on the moon. - -> A complete example of a large_scale environment configuration can be found in: `cfg/environment/largescale.yaml` - -## Extras: Light Sources - -In the following we detail how the sun can be customized. This argument is only applicable to "open space" environments such as the [LargeScale](#largescale) and [Lunaryard](#lunaryard). - -### Sun - -This allows to customize the default parameters for the Sun in the [LargeScale](#largescale) and [Lunaryard](#lunaryard) environments. - -Parameters: -- `intensity`: `(float)`, The intensity of the sun light. The higher the value, the brighter the scene will be. -- `angle`: `(float)`, The angle of the sun light in degrees. Note that this denotes the size of the sun in sky, not its azimuth or elevation. The larger the angle, the bigger the sun will appear. -- `diffuse_multiplier`: `(float)`, A multiplier for the effect of the sun has on the diffuse response of materials. It can be used to create stronger flares by setting this value to 0.1 and multiplying the light intensity by 10. -- `specular_multiplier`: `(float)`, A multiplier for the effect the sun has on the specular response of materials. It can be used to create stronger flares by setting this value to 0.1 and multiplying the light intensity by 10. -- `color`: `((float, float, float))`, The color to be given to the light. Format is (R,G,B), with 0.0 <= R,G,B <= 1.0. -- `temperature`: `(float)`, The temperature of the light source in Kelvin. -- `azimuth`: `(float)`, The azimuth of the sun in degrees. If the [Stellar Engine](#stellar-engine) is enabled it will override this parameter. -- `elevation`: `(float)`, The elevation of the sun in degrees. If the [Stellar Engine](#stellar-engine) is enabled it will override this parameter. - -Example: -```yaml -sun_settings: - intensity: 1750.0 - angle: 0.53 - diffuse_multiplier: 1.0 - specular_multiplier: 1.0 - color: [1.0, 1.0, 1.0] - temperature: 6500.0 - azimuth: 180.0 - elevation: 45.0 -``` - -### Coordinates - -This allows to set the coordinates of the [Lunaryard](#lunaryard) environment. The coordinate is used by the [Stellar Engine](#stellar-engine) to compute the position of the sun and earth for a given date. - -Parameters: -- `latitude`: `(float)`, The latitude of the environment in degrees. -- `longitude`: `(float)`, The longitude of the environment in degrees. - -Example: -```yaml -coordinates: - latitude: 46.8 - longitude: -26.3 -``` - -### Date - -This allows to set the date of the [LargeScale](#largescale) and [Lunaryard](#lunaryard) environments. The date is used by the [Stellar Engine](#stellar-engine) to compute the position of the sun and earth for a given coordinate on the moon. - -Parameters: -- `year`: `(int)`, The year. -- `month`: `(int)`, The month. -- `day`: `(int)`, The day. -- `hour`: `(int)`, The hour. -- `minute`: `(int)`, The minute. - -Example: -```yaml -start_date: - year: 2024 - month: 5 - day: 1 - hour: 12 - minute: 50 -``` -Used inside the [Stellar Engine](#stellar-engine)'s configuration. - -### Stellar Engine - -The Stellar uses both the [Date](#date) and the [Coordinates](#coordinates) to estimate the position of the sun and earth in the lunar sky. - -**Known limitations**: We use [skyfield] to compute the position of the earth and sun. This python library does not support well multi-segment ephemeris. Hence we recommend to use the ones provided with the sim. - -Parameters: -- `start_date`: `(Date)`, a date as defined in [Date](#date-configuration). -- `time_scale`: `(float)`, a time multiplier that allows to make time pass faster of slower. -- `update_interval`: `(float)`, the amount of scaled time that must pass for the position of the stellar bodies to be updated. -- `distance_scale`: `(float)`, the scaling factor to be applied to the distance between the center of the scene and the earth. A value below 1 will lead to the distance being reduced. -- `ephemeris_path`: `(str)`, the path to the ephemeris data. -- `ephemeris`: `(str)`, the name of the ephemeris. -- `moon_pa`: `(str)`, the name of the "spice binary lunar pck". -- `moon_tf`: `(str)`, the name of the "frame kernel". -- `pck`: `(str)`, the name of the "pck". -- `frame`: `(str)`, the name of the frame to be used. - -Example: -```yaml -stellar_engine_settings: - start_date: - year: 2024 - month: 5 - day: 1 - hour: 12 - minute: 50 - time_scale: 1 - update_interval: 600 - distance_scale: 0.001 - ephemeris_path: assets/Ephemeris - ephemeris: de421.bsp - moon_pa: moon_pa_de421_1900-2050.bpc - moon_tf: moon_080317.tf - pck: pck00008.tpc - frame: MOON_ME_DE421 -``` - -## Extras: Rocks - -In this section we provide some details regarding the distribution of rocks in the scene. This is only applicable to small scale environments such as the [Lunalab](#lunalab) or the [Lunaryard](#lunaryard). Large scale environments rely on different methods to generate and manage rocks. - -To generate rocks we rely 3 different objects. The base block is a [request](#request), it assigns a type of parameter to be randomized with a given distribution. A [group of requests](#request-group), that is a bundle of requests. And finally a [rock generation configuration](#rock-generation). -How to set up these is explained below: -- [request](#request) -- [request group](#request-group) -- [rock generation configuration](#rock-generation) - -### Request -A request allows to set a given parameter of the rocks to be randomized. As of now, we only randomize so called `xformOp`s. These are a set of geometric transformation that control the scale, rotation, and translation of assets in OpenUSD. A request applies a statistical distribution, like a `uniform` distribution on a geometric primitive, or a digital elevation map. The axes on which the randomization should be applied can also be selected. - -Parameters: -- `attribute`: `(str)`, The name of the attribute to be randomized. Can be `Scale`, `Orientation`, or `Position`. -- `axes`: `(list)`, The axis of the selected attribute to be randomized. A list containing `x`, `y`, `z`, `w`. Note that the orientation is always defined as a quaternion. Aggregating multiple dimmensions i.e. writing `xyz` means that the values for `x` `y` and `z` will be the same. -- `num`: `(int)`, The number of points to be generated. If there is a PointProcess, or a ClusterPointProcess inside the same [request group](#request-group) this parameter should not be set. If there is none, it should be similar for all requests within the same [request group](#request-group). -- `inherit_parents`: `(bool)`, If the distribution has a parent distribution. This is only applicable to "ClusterPointProcesses" kind of distributions. -- `layer`: `str`, the layer object to sample on. More info is given [here](#request-layers). -- `sampler`: `str`, the sampler object to sample from. More info is given [here](#request-samplers) - -Examples: - -Single request, that scales the x y an z dimensions similarly. The values range from 0.01 to 0.05 and the distribution used is a uniform distribution. -```yaml -req_scale: - attribute: Scale - axes: ["xyz"] - num: 1000 - inherit_parents: False - layer: - name: Line - xmin: 0.01 - xmax: 0.05 - sampler: - name: Uniform - randomization_space: 1 - seed: 42 -``` - -Single request where the orientation is sampled for a given axis. Here the yaw is randomized. -```yaml -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: 42 -``` - -### Request Group - -A request group defines a bundle of requests to execute, the type of assets to be used, and whether of not we should use an instancer. - -Parameters: -- `seed`: `(int)`, the seed to be used. -- `collections`: `(str)`, the name of the folder in which the rocks are saved. -- `use_point_instancer`: `(bool)`, if the assets should be generated with an instancer or not. **Limitations of instancers in isaac sim**: they do not work well with semantic information. Hence, if you want to collect semantic data, do not use them! -- `parent`: `(str)`, to be set if another [request group](#request-group) if the parent of this one. Set to the name of that other [request group](#request-group). -- `requests`: `list[request]`, the list of requests to be executed. - -Example: - -A request group without parent. -```yaml -medium_rocks: - seed: ${....seed} - collections: ["apollo_rocks"] # Uses the apollo rocks inside assets/USD_Assets/rocks - use_point_instancer: True # Set to True for fast sampling, set to False for SDG - requests: - req_pos_xy: # Sample XY position - attribute: Position - axes: ["x", "y"] - layer: - name: Image - mpp_resolution: ${.......lunaryard_settings.resolution} - output_space: 2 - sampler: - name: ThomasCluster - randomization_space: 2 - lambda_parent: 0.25 - lambda_daughter: 200 - sigma: 0.2 - seed: ${.......seed} - - req_pos_z: # Get Z from the elevation map. - attribute: Position - axes: ["z"] - layer: - name: Image - output_space: 1 - sampler: - name: Image - randomization_space: 1 - mpp_resolution: ${.......lunaryard_settings.resolution} - - req_random_z_rot: # Randomize Z orientation - 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: # Randomize the scale homogeneously. - attribute: Scale - axes: ["xyz"] - layer: - name: Line - xmin: 1.0 - xmax: 1.0 - sampler: - name: Uniform - randomization_space: 1 - seed: ${.......seed} -``` - - -### Rock Generation - -This aggregates multiple requests groups. - -Parameters: -- `instancers_path`: `(str)`, The path where the instancers will be generated. -- `rocks_settings`: `(list(request_group))`, A list of request groups. - -Example: -```yaml -rocks_settings: - instancers_path: /Lunaryard/Rocks - rocks_settings: - medium_rocks: - seed: ${....seed} - collections: ["apollo_rocks"] - use_point_instancer: True - requests: - req_pos_xy: - attribute: Position - axes: ["x", "y"] - layer: - name: Image - mpp_resolution: ${.......lunaryard_settings.resolution} - output_space: 2 - sampler: - name: ThomasCluster - randomization_space: 2 - lambda_parent: 0.25 - lambda_daughter: 200 - sigma: 0.2 - seed: ${.......seed} - - req_pos_z: - attribute: Position - axes: ["z"] - layer: - name: Image - output_space: 1 - sampler: - name: Image - randomization_space: 1 - mpp_resolution: ${.......lunaryard_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} - - large_rocks: - seed: ${....seed} - collections: ["apollo_rocks"] - use_point_instancer: True - parent: medium_rocks - requests: - req_pos_xy: - attribute: Position - axes: ["x", "y"] - layer: - name: Image - mpp_resolution: ${.......lunaryard_settings.resolution} - output_space: 2 - sampler: - name: ThomasCluster - randomization_space: 2 - lambda_parent: 0.25 - lambda_daughter: 5 - sigma: 0.05 - inherit_parents: True - seed: ${.......seed} - - req_pos_z: - attribute: Position - axes: ["z"] - layer: - name: Image - output_space: 1 - sampler: - name: Image - randomization_space: 1 - mpp_resolution: ${.......lunaryard_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: 2.0 - xmax: 5.0 - sampler: - name: Uniform - randomization_space: 1 - seed: ${.......seed} - - small_rocks: - seed: ${....seed} - collections: ["apollo_rocks"] - use_point_instancer: True - parent: medium_rocks - requests: - req_pos_xy: - attribute: Position - axes: ["x", "y"] - layer: - name: Image - mpp_resolution: ${.......lunaryard_settings.resolution} - output_space: 2 - sampler: - name: ThomasCluster - randomization_space: 2 - lambda_parent: 0.5 - lambda_daughter: 500 - sigma: 0.3 - inherit_parents: True - seed: ${.......seed} - - req_pos_z: - attribute: Position - axes: ["z"] - layer: - name: Image - output_space: 1 - sampler: - name: Image - randomization_space: 1 - mpp_resolution: ${.......lunaryard_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: 0.01 - xmax: 0.05 - sampler: - name: Uniform - randomization_space: 1 - seed: ${.......seed} -``` \ No newline at end of file diff --git a/wiki/generate_sidebar.sh b/wiki/generate_sidebar.sh old mode 100755 new mode 100644 index ec7e90b..4b7b3f7 --- a/wiki/generate_sidebar.sh +++ b/wiki/generate_sidebar.sh @@ -43,3 +43,4 @@ while IFS= read -r line; do done < "$input_file" echo "_Sidebar.md has been generated from $input_file." + diff --git a/wiki/getting_started/GettingStarted.md b/wiki/getting_started/GettingStarted.md new file mode 100644 index 0000000..ca49c4c --- /dev/null +++ b/wiki/getting_started/GettingStarted.md @@ -0,0 +1,67 @@ +# Getting started: + +In this page we'll explore how you can start a simulation! +Before we get into how we launch a simulation, let's briefly see how configurations are managed. +Our simulation uses hydra to manage the configuration of the differement simulation element. + +> [!TIP] +> Learn more about hydra [here](https://hydra.cc/docs/intro/)! + +Our base config is organized around 4 main files: +- [environment](../environments/Environments.md): Defines everything that deals with the environment to be simulated. +- [mode](../modes/Modes.md): Defines what mode should be use, ROS1, ROS2, or synthetic data generation. +- [rendering](../rendering/Rendering.md): Defines everything that relates to the rendering. +- [physics](../physics/Physics.md): Defines everything that relates to the physics engine. + +## Example commands + +> [!CAUTION] +> The following assumes you are running ROS2/SpaceROS. While the code has ROS1 compatibility, we do not provide base configs or robots for ROS1. + +> [!IMPORTANT] +>If you are using docker, first run the container by using: +```bash +./omnilrs.docker/run_docker.sh +``` + +> [!IMPORTANT] +> If you are using the native installation, make sure ROS2 is sourced **before running the simulation**. + +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. Before + +Run your first scene using: +```bash +python.sh run.py +``` +This will launch a lunalab environment with ROS2 and ray_traced rendering. + +You can run the lunaryard by using: +```bash +python.sh run.py environment=lunaryard_20m +``` + +You can run the largescale environment by using: +```bash +python.sh run.py environment=largescale +``` + +> [!TIP] +> To learn more about how to run scenes please refere to the Wiki [here](https://github.com/AntoineRichard/OmniLRS/wiki/Configuration)! + +## More examples + +Deformable lunalab: +```bash +python.sh run.py environment=lunalab_deformable +``` + +Deformable lunaryard: +```bash +python.sh run.py environment=lunaryard_20m_deformable +``` + +Larger lunaryard: +```bash +python.sh run.py environment=lunaryard_40m +``` + diff --git a/wiki/getting_started/_Footer.md b/wiki/getting_started/_Footer.md new file mode 100644 index 0000000..606036d --- /dev/null +++ b/wiki/getting_started/_Footer.md @@ -0,0 +1 @@ +Antoine Richard -- University of Luxembourg -- Space Robotics Group -- 2023-24 diff --git a/wiki/getting_started/_Sidebar.md b/wiki/getting_started/_Sidebar.md new file mode 100644 index 0000000..8140d0a --- /dev/null +++ b/wiki/getting_started/_Sidebar.md @@ -0,0 +1,7 @@ +## Table of Contents +- [Previous (Installation)](../installation/Installation.md) +- [Getting started](#getting-started) + - [Example commands](#example-commands) + - [More examples](#more-examples) +- [Next (Scene Interactions)](../scene_interaction/ros_topics.md) + diff --git a/wiki/installation/Installation.md b/wiki/installation/Installation.md index c29ed4f..33da142 100644 --- a/wiki/installation/Installation.md +++ b/wiki/installation/Installation.md @@ -114,4 +114,4 @@ Provided you have Gdal and gdown installed on your system, you can also run: scripts/download_only_native.sh ``` -See [getting started](#getting-started) to learn more about starting the simulation. \ No newline at end of file +See [getting started](#getting-started) to learn more about starting the simulation. diff --git a/wiki/installation/_Footer.md b/wiki/installation/_Footer.md new file mode 100644 index 0000000..606036d --- /dev/null +++ b/wiki/installation/_Footer.md @@ -0,0 +1 @@ +Antoine Richard -- University of Luxembourg -- Space Robotics Group -- 2023-24 diff --git a/wiki/installation/_Sidebar.md b/wiki/installation/_Sidebar.md index 2597c9d..c21fa8f 100644 --- a/wiki/installation/_Sidebar.md +++ b/wiki/installation/_Sidebar.md @@ -1,7 +1,7 @@ ## Table of Contents - +- [Previous (Home)](../Home.md) - [Installation](#installation) - [Native installation](#native-installation) - [Docker Installation](#docker-installation) -- [Next](../getting_started/GettingStarted) -- [Back to Home](../Home) \ No newline at end of file +- [Next (Getting Started)](../getting_started/GettingStarted) +- [Back to Home](../Home) diff --git a/wiki/make_configuration.sh b/wiki/make_configuration.sh deleted file mode 100755 index 1058594..0000000 --- a/wiki/make_configuration.sh +++ /dev/null @@ -1,4 +0,0 @@ -#!/bin/bash - -rm configuration/Configurations.md -for i in $(ls configuration/configs_*); do cat $i >> configuration/Configurations.md; done diff --git a/wiki/modes/Modes..md b/wiki/modes/Modes.md similarity index 88% rename from wiki/modes/Modes..md rename to wiki/modes/Modes.md index 65e2701..7b130cf 100644 --- a/wiki/modes/Modes..md +++ b/wiki/modes/Modes.md @@ -1,5 +1,22 @@ # Simulation Modes Configurations +What are modes? Modes are wrappers that enable the user to interact with a base simulation environment in a particular way. This allows a single base environment, that exposes a given set of methods to manipulate it, to be used for different purposes. +Say you want to use the lunalab to run a robotic task, you can use the ROS1 or ROS2 modes. But if you wanted to use this environment to generate a dataset for rock detection, you could use the SDG mode. +In practice the base environment provides a set of method that allows different Modes to achieve what the user desires. + +As of now we support 3 modes: +- ROS1: Noetic +- ROS2: Foxy, or Humble, also compatible with SpaceROS! +- SDG: Synthetic Data Generation + +> [!CAUTION] +> As ROS1 is no longer supported, and is no longer shipped with the latest ubuntu releases, it will be phased out with future releases. Having both ROS1 and ROS2 creates more work when adding new features, but also makes docker container generation more complicated. + +>[!Note] +> Future release will include: +> - SDG_SLAM: A mode to generate image sequence to evaluate SLAM & 3D reconstruction algorithms. +> - SDG_LRO: A mode to generate LRO like images to test different set of algorithms. + ## How to Hydra In short hydra allows to combined multiple .yaml file into a single configuration, it also allows to change the value of one of the file's parameters on the fly. Finally hydra provides a mean to perform simple operations inside a yaml file. @@ -17,10 +34,12 @@ hydra: run: dir: . ``` + This means that running: ```bash python.sh run.py ``` + Will result in running the simulation using the following configs: - cfg/environment/lunalab.yaml - cfg/rendering/ray_tracing.yaml @@ -41,21 +60,6 @@ This will change the year of the starting date of the stellar engine. Now that you know hydra's basics, let's jump into how to configure the differt modes. -## Introduction - -Modes are what allows the user to use the same environment for different purposes. Say you want to use the lunalab to run a robotic task, you can use the ROS1 or ROS2 modes. But if you wanted to use this environment to generate a dataset for rock detection, you could use the SDG mode. - -As of now we support 3 modes: -- ROS1: Noetic -- ROS2: Foxy, or Humble, also compatible with SpaceROS! -- SDG: Synthetic Data Generation - -As ROS1 is no longer supported, and is no longer shipped with the latest ubuntu releases, it will be phased out with the next release. Having both ROS1 and ROS2 creates more work when adding new features, but also makes docker container generation more complicated. - ->[!Note] -> Future release will include: -> - SDG_SLAM: A mode to generate image sequence to evaluate SLAM & 3D reconstruction algorithms. -> - SDG_LRO: A mode to generate LRO like images to test different set of algorithms. ## ROS1 This mode launches the simulation in ROS1 mode. This means that both the robots and the labs inside the simulation will be running using ROS1 nodes. There is no specific parameters for it. @@ -161,3 +165,4 @@ camera_settings: focus_distance: 10.0 clipping_range: ${as_tuple:0.01, 1000000.0} ``` + diff --git a/wiki/modes/_Footer.md b/wiki/modes/_Footer.md new file mode 100644 index 0000000..606036d --- /dev/null +++ b/wiki/modes/_Footer.md @@ -0,0 +1 @@ +Antoine Richard -- University of Luxembourg -- Space Robotics Group -- 2023-24 diff --git a/wiki/modes/_Sidebar.md b/wiki/modes/_Sidebar.md new file mode 100644 index 0000000..9960da5 --- /dev/null +++ b/wiki/modes/_Sidebar.md @@ -0,0 +1,10 @@ +## Table of Contents +- [Previous (Scene Interactions)](../scene_interaction/ros_topics.md) +- [Simulation Modes Configurations](#simulation-modes-configurations) + - [How to Hydra](#how-to-hydra) + - [Introduction](#introduction) + - [ROS1](#ros1) + - [ROS2](#ros2) + - [Synthetic Data Generation](#synthetic-data-generation) +- [Next (Environment Configuration)](../environments/Environments.md) +- [Back to Home](../Home) diff --git a/wiki/environments/env_5_physics.mdpp b/wiki/physics/Physics.md similarity index 76% rename from wiki/environments/env_5_physics.mdpp rename to wiki/physics/Physics.md index 4a464b4..1d8f690 100644 --- a/wiki/environments/env_5_physics.mdpp +++ b/wiki/physics/Physics.md @@ -1,38 +1,7 @@ -## Physics Configs - - -@dataclasses.dataclass -class PhysicsSceneConf: - dt: float = dataclasses.field(default_factory=float) - gravity: Tuple[float, float, float] = None - substeps: int = None - use_gpu_pipeline: bool = None - worker_thread_count: int = None - use_fabric: bool = None - enable_scene_query_support: bool = None - gpu_max_rigid_contact_count: int = None - gpu_max_rigid_patch_contact_count: int = None - gpu_found_lost_pairs_capacity: int = None - gpu_total_aggregate_pairs_capacity: int = None - gpu_max_soft_body_contacts: int = None - gpu_max_particle_contacts: int = None - gpu_heap_capacity: int = None - gpu_temp_buffer_capacity: int = None - gpu_max_num_partions: int = None - gpu_collision_stack_size: int = None - solver_type: str = None - enable_stabilization: bool = None - bounce_threshold_velocity: float = None - friction_offset_threshold: float = None - friction_correlation_distance: float = None - enable_ccd: bool = None - - def __post_init__(self): - self.physics_scene_args = {} - for attribute in dataclasses.fields(self): - if getattr(self, attribute.name) is not None: - self.physics_scene_args[attribute.name] = getattr(self, attribute.name) +# Physics Configuration +> [!Warning] +> This page is under construction. Attributes: - `dt`: `(float)`, The time step for each physics simulation update. Defines the amount of time that passes per frame for physics calculations. @@ -59,11 +28,13 @@ Attributes: - `friction_correlation_distance`: `(float)`, The correlation distance for friction calculation. Defines the area over which friction is applied between two surfaces. - `enable_ccd`: `(bool)`, Whether to enable Continuous Collision Detection (CCD). CCD prevents fast-moving objects from passing through one another by performing more frequent collision checks. +> [!Note] > - GPU-specific settings are important for optimizing large simulations, especially when dealing with rigid bodies, soft bodies, and particles. > - The number of substeps and solver type significantly impact the accuracy and stability of the physics simulation. > - Using the GPU pipeline and adjusting thread count allows for performance improvements, particularly in complex scenes. > - The stabilization options and collision detection settings like CCD help avoid errors in physics calculations, such as objects passing through one another or jittering at rest. + Example: ```yaml physics_scene: @@ -73,4 +44,4 @@ physics_scene: enable_stabilization: false solver_type: PGS use_gpu_pipeline: false -``` \ No newline at end of file +``` diff --git a/wiki/physics/_Footer.md b/wiki/physics/_Footer.md new file mode 100644 index 0000000..606036d --- /dev/null +++ b/wiki/physics/_Footer.md @@ -0,0 +1 @@ +Antoine Richard -- University of Luxembourg -- Space Robotics Group -- 2023-24 diff --git a/wiki/physics/_Sidebar.md b/wiki/physics/_Sidebar.md new file mode 100644 index 0000000..f9ce639 --- /dev/null +++ b/wiki/physics/_Sidebar.md @@ -0,0 +1,4 @@ +## Table of Contents +- [Previous (Mode Configuration)](../environments/Environments.md) +- [Next (Rendering Configuration)](../rendering/Rendering.md) +- [Back to Home](../Home) diff --git a/wiki/environments/env_4_rendering.mdpp b/wiki/rendering/Rendering.md similarity index 90% rename from wiki/environments/env_4_rendering.mdpp rename to wiki/rendering/Rendering.md index 8e7dde8..d7c13a2 100644 --- a/wiki/environments/env_4_rendering.mdpp +++ b/wiki/rendering/Rendering.md @@ -1,12 +1,13 @@ -## Rendering Configs +# Rendering Configuration In the following we will go over the different configurations available to you to tweak the rendering in the simulation. -### RTXRealTime & RTXInteractive +## RTXRealTime & RTXInteractive Let's start by what they are. RTXRealTime is has it's name imply, a high FPS renderer that trades some of the rendering quality to push more frames per second. The RTXInteractive renderer makes less compromises on the rendering quality and hence the overall quality of rendered frame is higher at the cost of slower render time. -We only expose a few parameters of the fairly large amount available to tune. They should be expended when time allows. +> [!Note] +> We only expose a few parameters of the fairly large amount available to tune. They should be expended when time allows. Arguments: - `samples_per_pixel_per_frame`: (`int`), RTXInteractive only. @@ -39,7 +40,7 @@ renderer: subdiv_refinement_level: 0 ``` -### Lens Flares +## Lens Flares Should you want to make Michael Bay proud, you may be interested in adding lens flares. Though lens flares in isaac are pretty basic, so not sure he'll be that impressed. Regardless, here are the available settings! @@ -53,7 +54,8 @@ Arguments: - `fstop`: (float), fstop of the lens used to simulate the flares. - `focal_length`: (float), Focal length of the lens used to simulate the flares. -> Note: These camera parameters are completely independent of the ones you have inside the scene's cameras. +> [!Note] +> These camera parameters are completely independent of the ones you have inside the scene's cameras. Example: ```yaml @@ -68,7 +70,7 @@ lens_flares: focal_length: 12.0 ``` -### Motion Blur +## Motion Blur To add motion blur to the rendered image, you can use the following arguments: @@ -87,7 +89,7 @@ motion_blur: num_samples: 8 ``` -### Chromatic Aberrations +## Chromatic Aberrations To add chromatic aberrations to your renders, you can use the following arguments: @@ -102,4 +104,5 @@ chromatic_aberration: enable: False strength: [-0.055, -0.075, 0.015] model: ["Radial", "Radial", "Radial"] -``` \ No newline at end of file +``` + diff --git a/wiki/rendering/_Footer.md b/wiki/rendering/_Footer.md new file mode 100644 index 0000000..606036d --- /dev/null +++ b/wiki/rendering/_Footer.md @@ -0,0 +1 @@ +Antoine Richard -- University of Luxembourg -- Space Robotics Group -- 2023-24 diff --git a/wiki/rendering/_Sidebar.md b/wiki/rendering/_Sidebar.md new file mode 100644 index 0000000..5c07dc1 --- /dev/null +++ b/wiki/rendering/_Sidebar.md @@ -0,0 +1,8 @@ +## Table of Contents +- [Previous (Physics Configuration)](../physics/Physics.md) + - [RTXRealTime & RTXInteractive](#rtxrealtime--rtxinteractive) + - [Lens Flares](lens-flares) + - [Motion Blur](motion-blur) + - [Chromatic Aberrations](chromatic-aberrations) +- [Next (Contribute)](../contribute/Contribute.md) +- [Back to Home](../Home) diff --git a/wiki/rendering_configs.md b/wiki/rendering_configs.md deleted file mode 100644 index e69de29..0000000 diff --git a/wiki/scene_interaction/_Footer.md b/wiki/scene_interaction/_Footer.md new file mode 100644 index 0000000..606036d --- /dev/null +++ b/wiki/scene_interaction/_Footer.md @@ -0,0 +1 @@ +Antoine Richard -- University of Luxembourg -- Space Robotics Group -- 2023-24 diff --git a/wiki/scene_interaction/_Sidebar.md b/wiki/scene_interaction/_Sidebar.md new file mode 100644 index 0000000..9be7489 --- /dev/null +++ b/wiki/scene_interaction/_Sidebar.md @@ -0,0 +1,9 @@ +## Table of Contents +- [Previous (Getting Started)](../getting_started/GettingStarted.md) +- [Environments ROS 1 & 2 topics](#environments-ros-1--2-topics) + - [Common](#common) + - [Lunalab ](#lunalab-) + - [Lunaryard](#lunaryard) + - [LargeScale](#largescale) +- [Next (Mode Configuration)](../modes/Modes.md) +- [Back to Home](../Home) diff --git a/wiki/ros_topics.md b/wiki/scene_interaction/ros_topics.md similarity index 98% rename from wiki/ros_topics.md rename to wiki/scene_interaction/ros_topics.md index 5de7fef..e202534 100644 --- a/wiki/ros_topics.md +++ b/wiki/scene_interaction/ros_topics.md @@ -1,10 +1,11 @@ -## Environments ROS 1 & 2 topics +# Environments ROS 1 & 2 topics Our simulation provides an interface to alter the simulation's state through ROS topics. This will change in the future as it is likely that we will shift towards a ZeroMQ-based stack with a webserver so that more simulation parameters can be tuned. +> [!NOTE] > For most of these operations we should be using services rather than topics. We are fully aware of this, but Omniverse does not allow to easily compile custom services outside of so-called "extensions". This partially explain the planned move to ZeroMQ. We may also release an extension to address some of these shortcomings. -### Common +## Common Rendering topics: - `/OmniLRS/Render/EnableRTXRealTime`: `(std_msgs/Empty)`, Switches the renderer to RTXRealTime. - `/OmniLRS/Render/EnableRTXInteractive`: `(std_msgs/Empty)`, Switches the renderer to RTXInteractive. @@ -23,9 +24,10 @@ Robot topics: - `/OmniLRS/Robots/Reset`: `(std_msgs/String)`, Resets the robot whose name is in the string. A reset puts the robot back where it was when it was first spawned. - `/OmniLRS/Robots/ResetAll`: `(std_msgs/Empty)`, Resets all the robots in the scene. A reset puts the robot back to where it was when it was first spawned. -> Notes: **Large scale environments do not support multiple robots.**: +> [!NOTE] +> Large scale environments do not support multiple robots. -### Lunalab +## Lunalab Topics offered by the lunalab in addition to the ones in [common](#common). - `/OmniLRS/Projector/TurnOn`: `(std_msgs/Bool)`, Turns on or off the projector in the lunalab. Setting it to true turns the projector on. - `/OmniLRS/Projector/Intensity`: `(std_msgs/Float32)`, Set the intensity of the projector. This value is set as a percentage of the default value. Setting the value to 50.0 will set the projector's output to 50%. @@ -75,4 +77,4 @@ ros2 topic pub /OmniLRS/Robots/ResetAll std_msgs/msg/Empty ros2 topic pub --once /OmniLRS/Robots/Teleport geometry_msgs/msg/PoseStamped "{'header':{'stamp':{'sec':0.0,'nanosec':0.0},'frame_id':'/husky'},pose:{'position':{'x':'10.0','y':5.0,'z': 1.0},'orientation':{'x':0.0,'y':0.0,'z':0.0,'w':1.0}}}" # Spawns a husky ros2 topic pub --once /OmniLRS/Robots/Spawn geometry_msgs/msg/PoseStamped "{'header':{'stamp':{'sec':0.0,'nanosec':0.0},'frame_id':'husky2:/home/antoine/Documents/Lunalab/assets/USD_Assets/robots/husky_vlp16.usd'},pose:{'position':{'x':'10.0','y':10.0,'z': 1.0},'orientation':{'x':0.0,'y':0.0,'z':0.0,'w':1.0}}}" -``` \ No newline at end of file +```