airo-mono

Welcome to airo-mono! This repository provides ready-to-use Python packages to accelerate the development of robotic manipulation systems.

Key Motivation: * Accelerate Experimentation: Reduce the time spent on repetitive coding tasks, enabling faster iteration from research idea to demo on the robots. * Collaboration: Promote a shared foundation of well-tested code across the lab, boosting reliability and efficiency and promoting best practices along the way.

Want to learn more about our vision? Check out the in-depth explanation here

Overview

Packages

The airo-mono repository employs a monorepo structure, offering multiple Python packages, each with a distinct focus:

| Package | Description | Owner | | ------------------------------------------------ | --------------------------------------------------------- | -------------- | | airo-camera-toolkit | RGB(D) camera, image, and point cloud processing | @m-decoster | | airo-dataset-tools | Creating, loading, and manipulating datasets | @victorlouisdg | | airo-robots | Simple interfaces for controlling robot arms and grippers | @tlpss | | airo-spatial-algebra | Transforms and SE3 pose conversions | @tlpss | | airo-teleop | Intuitive teleoperation of robot arms | @tlpss | | airo-typing | Type definitions and conventions | @tlpss |

Detailed Information: Each package contains its own dedicated README outlining: - A comprehensive overview of the provided functionality - Package-specific installation instructions (if needed) - Rationale behind design choices (if applicable)

Code Ownership: The designated code owner for each package is your go-to resource for: - Understanding features, codebase, and design decisions. - Proposing and contributing new package features.

Command Line Functionality: Some packages offer command-line interfaces (CLI). Run package-name --help for details. Example: airo-dataset-tools --help

Sister repositories

Repositories that follow the same style as airo-mono packages, but are not part of the monorepo (for various reasons):

| Repository | Description | |-----------------------------------------------------------------| -------------------------------------- | | airo-blender | Synthetic data generation with Blender | | airo-models | Collection of robot and object models and URDFs | | airo-drake | Integration with Drake | | airo-planner | Motion planning interfaces | | airo-tulip | Driver for the KELO mobile robot platform | | airo-ipc | Inter-process communication library |

Usage & Philosophy

We believe in keep simple things simple. Starting a new project is as simple as: bash pip install airo-camera-toolkit airo-robots And writing a simple script: ```python from airocameratoolkit.cameras.zed.zed import Zed from airorobots.manipulators.hardware.urrtde import URrtde from airorobots.grippers.hardware.robotiq2f85_urcap import Robotiq2F85

robotipaddress = "10.40.0.162"

camera = Zed() robot = URrtde(ipaddress=robotipaddress) gripper = Robotiq2F85(ipaddress=robotipaddress)

image = camera.getrgbimage() grasppose = selectgrasppose(image) # example: user provides grasp pose robot.movelineartotcppose(grasppose).wait() gripper.close().wait() ```

Getting started

To get started with airo-mono, check out our getting started guide which provides examples and explanations of the main functionalities provided by the packages.

Projects using airo-mono

Probably the best way to learn what airo-mono has to offer, is to look at the projects it powers:

| Project | Description | | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | ITF World 2025 | airo-mono powered our demos at ITF World 2025 | | cloth-competition | airo-mono is the backbone of the ICRA 2024 Cloth Competition ! | | ITF World 2024 | airo-mono powered our demo at ITF World 2024 |

Installation

Option 1: Installation from PyPI

Install the packages from PyPI. pip install airo-camera-toolkit airo-dataset-tools airo-robots

Option 2: Local clone

2.1 Conda method

Make sure you have a version of conda e.g. miniconda installed. To make the conda environment creation faster, we recommend configuring the libmamba solver first.

Then run the following commands: bash git clone https://github.com/airo-ugent/airo-mono.git cd airo-mono conda env create -f environment.yaml This will create a conda environment called airo-mono with all packages installed. You can activate the environment with conda activate airo-mono.

2.2 Pip method

While we prefer using conda, you can also install the packages simply with pip:

bash git clone https://github.com/airo-ugent/airo-mono.git cd airo-mono pip install -e airo-robots -e airo-dataset-tools -e airo-camera-toolkit

Option 3: Git submodule

You can add this repo as a submodule and install the relevant packages afterwards with regular pip commands. This allows to seamlessly make contributions to this repo whilst working on your own project or if you want to pin on a specific version.

In your repo, run: bash git submodule init git submodule add https://github.com/airo-ugent/airo-mono@<commit> cd airo-mono You can now add the packages you need to your requirements or environment file, either in development mode or through a regular pip install. More about submodules can be found here. Make sure to install the packages in one pip command such that pip can install them in the appropriate order to deal with internal dependencies.

Developer guide

Setup

Create and activate the conda environment, then run: pip install -r dev-requirements.txt pre-commit install

Coding style

We use pre-commit to automatically enforce coding standards before every commit.

Our .pre-commit-config.yaml file defines the tools and checks we want to run: - Formatting: Black, isort, and autoflake - Linting: Flake8

Typing: Packages can be typed (optional, but strongly recommended). For this, mypy is used. Note that pre-commit currently does not run mypy, so you should run it manually with mypy <package-dir>, e.g. mypy airo-camera-toolkit.

Docstrings: Should be in the google docstring format.

Testing

• Framework: Pytest for its flexibility.
• Organization: Tests are grouped by package, the CI pipeline runs them in isolation
• Minimum: Always include at least one test per package.
• Running Tests: make pytest <airo-package-dir> (includes coverage report).
• Hardware Testing: Cameras and robots have scripts available for manual testing. These scripts provide simple sanity checks to verify connections and functionality.

Continuous Integration (CI)

We use GitHub Actions to run the following checks:

| Workflow | Runs When | | ----------------------------------------------- | ---------------------------------------------- | | pre-commit | Every push | | mypy | pushes to main, PRs and the ci-dev branch | | pytest | pushes to main, PRs and the ci-dev branch |

Package Test Isolation: We use Github Actions matrices to run tests for each package in its own environment. This ensures packages correctly declare their dependencies. However, creating these environments adds overhead, so we'll explore caching strategies to optimize runtime as complexity increases.

Creating a new package

To quickly setup up Python projects you can use this cookiecutter template. In the future we might create a similar one for airo-mono packages. For now here are the steps you have to take:

1. Create directory structure: airo-package/ airo_package/ code.py test/ test_some_feature.py README.md setup.py
2. Integrate with CI: update the CI workflow matrices to include your package.
3. Update Documentation: add your package to this README
4. Installation: add package to the environment.yaml and scripts/install-airo-mono.sh.

Command Line Interfaces

For convenient access to specific functions, we provide command-line interfaces (CLIs). This lets you quickly perform tasks like visualizing COCO datasets or starting hand-eye calibration without the need to write Python scripts to change arguments (e.g., changing a data path or robot IP address).

• Framework: Click for composable CLIs.
• Exposure: We use Setuptools console_scripts to make commands available.
• Organization: User-facing CLI commands belong in a top-level cli.py file.
• Separation: Keep CLI code distinct from core functionality for maximum flexibility.
• Example: airo_dataset_tools/cli.py and airo-dataset-tools/setup.py.
• Developer Focus: Scripts' __main__() functions can still house developer-centric CLIs. Consider moving user-friendly ones to the package CLI.

Versioning & Releasing

As a first step towards PyPI releases of the airo-mono packages, we have already started versioning them. Read more about it in docs/versioning.md.

Design choices

• Minimalism: Before coding, explore existing libraries. Less code means easier maintenance.
• Properties: Employ Python properties (@property) for getters/setters. This enhances user interaction and unlocks powerful code patterns.
• Logging: Use loguru for structured debugging instead of print statements.
• Output Data: Favor native datatypes or NumPy arrays for easy compatibility. For more complex data, use dataclasses as in airo-typing.

Management of local dependencies in a Monorepo

TODO: simplify this explanation and move it to the setup or installation section.

An issue with using a monorepo is that you want to have packages declare their local dependencies as well. But before you publish your packages or if you want to test unreleased code (as usually), this creates an issue: where should pip find these local package? Though there exist more advanced package managers such as Poetry, (more background on package and dependency management in python ) that can handle this, we have opted to stick with pip to keep the barier for new developers lower.

This implies we simply add local dependencies in the setup file as regular dependencies, but we have to make sure pip can find the dependencies when installing the packages. There are two options to do so: 1. You make sure that the local dependencies are installed before installing the package, either by running the pip install commands along the dependency tree, or by running all installs in a single pip commamd: pip install <pkg1> <pkg2> <pkg3> 2. you create distributions for the packages upfront and then tell pip where to find them (because they won't be on PyPI, which is where pip searches by default): pip install --find-link https:// or /path/to/distributions/dir

Initially, we used a direct link to point to the path of the dependencies, but this created some issues and hence we now use this easier approach. see #91 for more details.