Getting Started
Overview
The Project Aria Machine Perceptions Services Command Line Interface (MPS CLI) is a command line tool used to request and receive Machine Perception Services. MPS CLI Guide page provides basic information to get you started with the MPS CLI.
The MPS inputs can be a file or directory, and multiple inputs can be listed in a single command.
The MPS CLI has two modes:
- Single
- Process each recording individually
- Output is always saved next to the input VRS file
- The most common way to request MPS
- Multi
- This mode is only available for Aria Gen1 at this time. Support for Aria Gen2 is coming soon.
This tutorial uses the the MPS CLI UI, but all processes also work without using the UI and can be integrated into automated workflows. See the Command Line Reference in the Technical Specs for more details.
Install Project Aria MPS
Aria MPS is available as a Python package on PyPI. You can install it using pip. And we strongly recommend installing it under a python virtual environment:
- Linux & macOS
- Windows
rm -rf $HOME/projectaria_tools_python_env
python3 -m venv $HOME/projectaria_tools_python_env
source $HOME/projectaria_tools_python_env/bin/activate
python3 -m pip install projectaria-mps
Windows is not yet supported for Aria-Gen2.
Quick Start - Running the tool
aria_mps single -i <path to vrs file or directory> [options]
Note that if the above command emits some error, please refer to the troubleshooting section.
Project Aria MPS CLI is only available if you install the pip installation version of Project Aria MPS. This installation has been designed to be simple to use, even if you are not familiar with programming languages.
Project Aria MPS pypi package automatically installs the projectaria-tools package and projectaria-vrs-health-check package
Supported Platforms
| OS / Platform | OS / Distro Details | Aria Gen2 Support (projectaria-tools ≥2.0) | Supported Python Versions |
|---|---|---|---|
| Linux (x64) | Fedora 40/41; Ubuntu 20.04 LTS (focal) / 22.04 LTS (jammy) / 24.04 LTS ( Noble Numbat) | ✅ Supported | 3.9 – 3.12 |
| macOS (Apple Silicon / ARM64) | macOS 14+ (Sonoma or newer) on M1/M2/M3 | ✅ Supported | 3.10 – 3.12 |
| macOS (Intel) | macOS 13+ (Ventura or newer) | ✅ Supported | 3.9 – 3.12 |
| Windows (x64) | MSVC 2019/2022 | 🚧 Planned | 3.10 – 3.12 |
Download the MPS CLI sample dataset
To try out the following commands on VRS files:
- Download the sample gen2 vrs file
- Move it to a directory called Example in your downloads directory
You may also wish to use your own recordings.
Request MPS for all VRS files in the “Example” directory and it’s subdirectories:
aria_mps single -i ~/Downloads/Example/
You'll be prompted to enter your username and then authenticate either via password on managed account login. Use the Project Aria credentials you use to sign into the Mobile Companion app.
Once the request has been processed, the MPS output will be downloaded next to the original VRS file. In this example, a recording in the Example directory called gen2_sample2.vrs was used to generate MPS.
└── Example
├── mps_gen2_sample2_vrs
│ ├── slam
│ │ ├── closed_loop_trajectory.csv
│ │ ├── online_calibration.jsonl
│ │ ├── open_loop_trajectory.csv
│ │ ├── semidense_observations.csv.gz
│ │ ├── semidense_points.csv.gz
│ │ └── summary.json
│ └── vrs_health_check.json
└── gen2_sample2.vrs
Go to MPS Data Format Basics for more details about the folder structure.
Exit the MPS CLI
To quit the MPS CLI, press CTRL + Q. The CLI will ask for confirmation before quitting.
- If you quit the request tool while the files are uploading the uploads will stop.
- If you resubmit the request the uploads will resume where they left off, progress won’t be lost for upto 24 hrs.
If you quit the request tool once the files have been uploaded, the MPS processes will continue. Once processing is complete, and the request tool is open, MPS files will be automatically downloaded to your VRS files’ location.
Working with MPS data
You may find the following resources helpful when working with MPS data: