# LeRobotLab Tools
A command-line interface (CLI) tool for working with LeRobot dataset. Selections can be made visualy online at [www.lerobotlab.com](https://www.lerobotlab.com). Users can then save a JSON file of this selectionand use this tool to download the selection's datasets. The tool alos offers conversion of the downloaded files to different formats in order to use them to train models.
Right now we only support V-JEPA2-AC, which is a format derived from the droid dataset used to train the VJEPA2 Action Conditionned model.
We plan to uspport other formats soon. Please reach out on the websiote if you see a clear need.
## Installation
### From PyPI (Recommended)
```bash
# Install LeRobotLab
pip install lerobotlab
```
This is the easiest and recommended installation method for most users.
### From Source (Development)
For the latest features, bug fixes, or development purposes:
#### Prerequisites
- Python 3.10 or higher
- conda (Anaconda or Miniconda)
- git
#### Step-by-step Installation
1. **Create and activate a conda environment:**
```bash
conda create -n lerobotlab-tools python=3.10
conda activate lerobotlab-tools
```
2. **Clone and install LeRobot:**
```bash
# Clone this repository
git clone https://github.com/huggingface/lerobot.git
# Install the package in development mode (includes lerobot from source)
cd lerobot
pip install -e .
```
3. **Clone and install LeRobotLab Tools:**
```bash
# Clone this repository
git clone https://github.com/newtechmitch/lerobotlab-tools.git
# Install the package in development mode (includes lerobot from source)
cd lerobotlab-tools
pip install -e .
```
## Usage
The CLI provides two main commands: `download` and `convert`.
### Download Command
Download datasets specified in a selection JSON file:
```bash
lerobotlab download selection.json --download-path ./datasets
```
**Arguments:**
- `selection.json`: Path to the JSON file exported from lerobotlab.com
**Options:**
- `--download-path`: Directory where datasets will be downloaded (required)
- `--verbose, -v`: Enable verbose output
- `--help`: Show command help
### Convert Command
Convert datasets to a specified format:
```bash
lerobotlab convert selection.json --output-path ./output --input-path ./datasets
```
**Arguments:**
- `selection.json`: Path to the JSON file exported from lerobotlab.com
**Options:**
- `--output-path`: Directory where converted datasets will be saved (required)
- `--input-path`: Directory containing downloaded datasets (required)
- `--format`: Output format for converted datasets (choices: vjepa2-ac; default: vjepa2-ac)
- `--verbose, -v`: Enable verbose output
- `--help`: Show command help
## Selection JSON Format
The selection should be created and saved from [www.lerobotlab.com](https://www.lerobotlab.com) and follow this JSON format:
```json
{
"metadata": {
"saved_at": "2025-08-02T19:18:32.940Z",
"total_datasets": 3,
"total_episodes": 150,
"total_frames": 77576
},
"datasets": [
{
"repo_id": "qownscks/3x2blueblock2",
"selected_videos": [
"observation.images.up"
]
},
{
"repo_id": "LightwheelAI/leisaac-pick-orange",
"selected_videos": [
"observation.images.front",
"observation.images.wrist"
]
},
{
"repo_id": "initie/picking",
"selected_videos": [
"observation.images.front",
"observation.images.side"
]
}
]
}
```
### Required Fields
- `datasets`: Array of dataset objects
- Each dataset must have:
- `repo_id`: Unique identifier for the dataset repository
- `selected_videos`: Array of selected video streams
### Optional Fields
- `metadata`: Object containing selection metadata
- `saved_at`: Timestamp when selection was saved
- `total_datasets`: Number of datasets in selection
- `total_episodes`: Total number of episodes across all datasets
- `total_frames`: Total number of frames across all datasets
## Examples
### Basic Download
```bash
# Download datasets to local directory
lerobotlab download my_selection.json --download-path ./robot_datasets
```
### Download with Verbose Output
```bash
# Download with detailed output
lerobotlab download my_selection.json --download-path ./robot_datasets --verbose
```
### Convert to DROID Format
```bash
# Convert datasets to DROID format
lerobotlab convert my_selection.json --output-path ./converted --input-path ./robot_datasets --format droid
```
### Convert to V-JEPA2-AC Format
```bash
# Convert datasets to V-JEPA2-AC format
lerobotlab convert my_selection.json --output-path ./converted --input-path ./robot_datasets --format vjepa2-ac
```
## Error Handling
The CLI provides clear error messages for common issues:
- **File not found**: When the selection JSON file doesn't exist
- **Invalid JSON**: When the file contains malformed JSON
- **Missing fields**: When required fields are missing from the JSON structure
- **Invalid structure**: When the JSON doesn't match the expected format
- **Path validation**: When input/output directories are invalid or inaccessible
## Development
### Project Structure
```
lerobotlab-tools/
├── src/
│ └── lerobotlab/
│ ├── __init__.py # Package initialization
│ ├── cli.py # Main CLI interface and argument parsing
│ ├── download.py # Dataset download functionality
│ ├── convert.py # Dataset conversion coordination
│ ├── droid_conversion.py # DROID format converter (future support)
│ └── vjepa2_ac_conversion.py # V-JEPA2-AC format converter
├── test_env/ # Test environment and sample data
├── .vscode/ # VS Code debug configurations
├── dist/ # Built packages
├── pyproject.toml # Package configuration and metadata
├── requirements.txt # Development dependencies
├── test_setup.py # Test environment setup script
├── README.md # This file
└── .gitignore # Git ignore patterns
```
### Dependencies
#### Core Runtime Dependencies
- **h5py>=3.0.0**: HDF5 file format support for trajectory data
- **pandas>=1.0.0**: Data manipulation and analysis
- **numpy>=1.19.0**: Numerical computing foundation
- **lerobot*
#### System Requirements
- **Python 3.10+**: Minimum Python version requirement
- **conda**: Package and environment manager (Anaconda or Miniconda)
- **pip**: Package installer (included with conda)
### Testing
To set up test environments and run tests:
```bash
# Activate your conda environment
conda activate lerobotlab-tools
# Setup test environment
python test_setup.py
# List available test cases
python test_setup.py list
# Run specific test case
python test_setup.py download_single_dataset
# Clean up test environment
python test_setup.py cleanup
```
### Debugging
VS Code debug configurations are provided in `.vscode/launch.json`:
- **Debug convert single**: Test conversion with single dataset
- **Debug convert multi**: Test conversion with multiple datasets
- **Debug download single**: Test download with single dataset
- **Debug download multi**: Test download with multiple datasets
## License
This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Run the test suite (`pytest`)
6. Format code (`black src/`)
7. Check linting (`flake8 src/`)
8. Commit your changes (`git commit -m 'Add amazing feature'`)
9. Push to the branch (`git push origin feature/amazing-feature`)
10. Open a Pull Request
## Support
For issues and questions:
- Create an issue on [GitHub Issues](https://github.com/newtechmitch/lerobotlab-tools/issues)
- Visit [www.lerobotlab.com](https://www.lerobotlab.com) for dataset-related questions
## Changelog
### v0.1.0
- Initial release
- CLI interface with download and convert commands
- Support for V-JEPA2-AC conversion formats
- JSON validation and comprehensive error handling
- Verbose logging and debug configurations
Raw data
{
"_id": null,
"home_page": null,
"name": "lerobotlab",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "robotics, datasets, cli, machine-learning",
"author": null,
"author_email": "newtechmitch <pipy@lerobotlab.com>",
"download_url": "https://files.pythonhosted.org/packages/9f/4c/10421bfee2c14e1f304db5786275de392623109faa404b4afc37ce760c3e/lerobotlab-0.1.6.tar.gz",
"platform": null,
"description": "# LeRobotLab Tools\n\nA command-line interface (CLI) tool for working with LeRobot dataset. Selections can be made visualy online at [www.lerobotlab.com](https://www.lerobotlab.com). Users can then save a JSON file of this selectionand use this tool to download the selection's datasets. The tool alos offers conversion of the downloaded files to different formats in order to use them to train models. \n\nRight now we only support V-JEPA2-AC, which is a format derived from the droid dataset used to train the VJEPA2 Action Conditionned model.\n\nWe plan to uspport other formats soon. Please reach out on the websiote if you see a clear need.\n\n## Installation\n\n### From PyPI (Recommended)\n \n\n```bash\n# Install LeRobotLab\npip install lerobotlab\n```\n\nThis is the easiest and recommended installation method for most users.\n\n### From Source (Development)\n\nFor the latest features, bug fixes, or development purposes:\n\n#### Prerequisites\n\n- Python 3.10 or higher\n- conda (Anaconda or Miniconda)\n- git\n\n#### Step-by-step Installation\n\n1. **Create and activate a conda environment:**\n```bash\nconda create -n lerobotlab-tools python=3.10\nconda activate lerobotlab-tools\n```\n\n2. **Clone and install LeRobot:**\n```bash\n# Clone this repository\ngit clone https://github.com/huggingface/lerobot.git\n\n# Install the package in development mode (includes lerobot from source)\ncd lerobot\npip install -e .\n```\n\n\n3. **Clone and install LeRobotLab Tools:**\n```bash\n# Clone this repository\ngit clone https://github.com/newtechmitch/lerobotlab-tools.git\n\n# Install the package in development mode (includes lerobot from source)\ncd lerobotlab-tools\npip install -e .\n```\n\n## Usage\n\nThe CLI provides two main commands: `download` and `convert`.\n\n### Download Command\n\nDownload datasets specified in a selection JSON file:\n\n```bash\nlerobotlab download selection.json --download-path ./datasets\n```\n\n**Arguments:**\n- `selection.json`: Path to the JSON file exported from lerobotlab.com\n\n**Options:**\n- `--download-path`: Directory where datasets will be downloaded (required)\n- `--verbose, -v`: Enable verbose output\n- `--help`: Show command help\n\n### Convert Command\n\nConvert datasets to a specified format:\n\n```bash\nlerobotlab convert selection.json --output-path ./output --input-path ./datasets\n```\n\n**Arguments:**\n- `selection.json`: Path to the JSON file exported from lerobotlab.com\n\n**Options:**\n- `--output-path`: Directory where converted datasets will be saved (required)\n- `--input-path`: Directory containing downloaded datasets (required)\n- `--format`: Output format for converted datasets (choices: vjepa2-ac; default: vjepa2-ac)\n- `--verbose, -v`: Enable verbose output\n- `--help`: Show command help\n\n## Selection JSON Format\n\nThe selection should be created and saved from [www.lerobotlab.com](https://www.lerobotlab.com) and follow this JSON format:\n\n```json\n{\n \"metadata\": {\n \"saved_at\": \"2025-08-02T19:18:32.940Z\",\n \"total_datasets\": 3,\n \"total_episodes\": 150,\n \"total_frames\": 77576\n },\n \"datasets\": [\n {\n \"repo_id\": \"qownscks/3x2blueblock2\",\n \"selected_videos\": [\n \"observation.images.up\"\n ]\n },\n {\n \"repo_id\": \"LightwheelAI/leisaac-pick-orange\",\n \"selected_videos\": [\n \"observation.images.front\",\n \"observation.images.wrist\"\n ]\n },\n {\n \"repo_id\": \"initie/picking\",\n \"selected_videos\": [\n \"observation.images.front\",\n \"observation.images.side\"\n ]\n }\n ]\n}\n```\n\n### Required Fields\n\n- `datasets`: Array of dataset objects\n - Each dataset must have:\n - `repo_id`: Unique identifier for the dataset repository\n - `selected_videos`: Array of selected video streams\n\n### Optional Fields\n\n- `metadata`: Object containing selection metadata\n - `saved_at`: Timestamp when selection was saved\n - `total_datasets`: Number of datasets in selection\n - `total_episodes`: Total number of episodes across all datasets\n - `total_frames`: Total number of frames across all datasets\n\n## Examples\n\n### Basic Download\n\n```bash\n# Download datasets to local directory\nlerobotlab download my_selection.json --download-path ./robot_datasets\n```\n\n### Download with Verbose Output\n\n```bash\n# Download with detailed output\nlerobotlab download my_selection.json --download-path ./robot_datasets --verbose\n```\n\n### Convert to DROID Format\n\n```bash\n# Convert datasets to DROID format\nlerobotlab convert my_selection.json --output-path ./converted --input-path ./robot_datasets --format droid\n```\n\n### Convert to V-JEPA2-AC Format\n\n```bash\n# Convert datasets to V-JEPA2-AC format\nlerobotlab convert my_selection.json --output-path ./converted --input-path ./robot_datasets --format vjepa2-ac\n```\n\n## Error Handling\n\nThe CLI provides clear error messages for common issues:\n\n- **File not found**: When the selection JSON file doesn't exist\n- **Invalid JSON**: When the file contains malformed JSON\n- **Missing fields**: When required fields are missing from the JSON structure\n- **Invalid structure**: When the JSON doesn't match the expected format\n- **Path validation**: When input/output directories are invalid or inaccessible\n\n## Development\n\n### Project Structure\n\n```\nlerobotlab-tools/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 lerobotlab/\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u251c\u2500\u2500 cli.py # Main CLI interface and argument parsing\n\u2502 \u251c\u2500\u2500 download.py # Dataset download functionality\n\u2502 \u251c\u2500\u2500 convert.py # Dataset conversion coordination\n\u2502 \u251c\u2500\u2500 droid_conversion.py # DROID format converter (future support)\n\u2502 \u2514\u2500\u2500 vjepa2_ac_conversion.py # V-JEPA2-AC format converter\n\u251c\u2500\u2500 test_env/ # Test environment and sample data\n\u251c\u2500\u2500 .vscode/ # VS Code debug configurations\n\u251c\u2500\u2500 dist/ # Built packages\n\u251c\u2500\u2500 pyproject.toml # Package configuration and metadata\n\u251c\u2500\u2500 requirements.txt # Development dependencies\n\u251c\u2500\u2500 test_setup.py # Test environment setup script\n\u251c\u2500\u2500 README.md # This file\n\u2514\u2500\u2500 .gitignore # Git ignore patterns\n```\n\n### Dependencies\n\n#### Core Runtime Dependencies\n\n- **h5py>=3.0.0**: HDF5 file format support for trajectory data\n- **pandas>=1.0.0**: Data manipulation and analysis\n- **numpy>=1.19.0**: Numerical computing foundation\n- **lerobot*\n\n#### System Requirements\n\n- **Python 3.10+**: Minimum Python version requirement\n- **conda**: Package and environment manager (Anaconda or Miniconda)\n- **pip**: Package installer (included with conda)\n\n### Testing\n\nTo set up test environments and run tests:\n\n```bash\n# Activate your conda environment\nconda activate lerobotlab-tools\n\n# Setup test environment\npython test_setup.py\n\n# List available test cases\npython test_setup.py list\n\n# Run specific test case\npython test_setup.py download_single_dataset\n\n# Clean up test environment\npython test_setup.py cleanup\n```\n\n### Debugging\n\nVS Code debug configurations are provided in `.vscode/launch.json`:\n\n- **Debug convert single**: Test conversion with single dataset\n- **Debug convert multi**: Test conversion with multiple datasets \n- **Debug download single**: Test download with single dataset\n- **Debug download multi**: Test download with multiple datasets\n\n## License\n\nThis project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for new functionality\n5. Run the test suite (`pytest`)\n6. Format code (`black src/`)\n7. Check linting (`flake8 src/`)\n8. Commit your changes (`git commit -m 'Add amazing feature'`)\n9. Push to the branch (`git push origin feature/amazing-feature`)\n10. Open a Pull Request\n\n## Support\n\nFor issues and questions:\n- Create an issue on [GitHub Issues](https://github.com/newtechmitch/lerobotlab-tools/issues)\n- Visit [www.lerobotlab.com](https://www.lerobotlab.com) for dataset-related questions\n\n## Changelog\n\n### v0.1.0\n- Initial release\n- CLI interface with download and convert commands\n- Support for V-JEPA2-AC conversion formats\n- JSON validation and comprehensive error handling\n- Verbose logging and debug configurations\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "CLI tool for processing robot dataset selections from lerobotlab.com",
"version": "0.1.6",
"project_urls": {
"Homepage": "https://github.com/newtechmitch/lerobotlab-tools",
"Issues": "https://github.com/newtechmitch/lerobotlab-tools/issues",
"Repository": "https://github.com/newtechmitch/lerobotlab-tools"
},
"split_keywords": [
"robotics",
" datasets",
" cli",
" machine-learning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "314e18fa589267bfdc0013f7704a97e078e8e0016cce79b1499cf1db5a3327b8",
"md5": "f1798937d73cb8aaba89ad56ffc2d897",
"sha256": "fed1e26dcfd678a252c96a096f6618f2748af72e198fbde29563f180cbca70da"
},
"downloads": -1,
"filename": "lerobotlab-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f1798937d73cb8aaba89ad56ffc2d897",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 15003,
"upload_time": "2025-08-05T00:30:56",
"upload_time_iso_8601": "2025-08-05T00:30:56.309735Z",
"url": "https://files.pythonhosted.org/packages/31/4e/18fa589267bfdc0013f7704a97e078e8e0016cce79b1499cf1db5a3327b8/lerobotlab-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9f4c10421bfee2c14e1f304db5786275de392623109faa404b4afc37ce760c3e",
"md5": "2a5f16d8cce827f0eeee6f905acd907c",
"sha256": "3681e48ff74bc79ead6daacd2994d74eb09ea65dbe1fef4fce50e4fe194a1c69"
},
"downloads": -1,
"filename": "lerobotlab-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "2a5f16d8cce827f0eeee6f905acd907c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 14977,
"upload_time": "2025-08-05T00:30:57",
"upload_time_iso_8601": "2025-08-05T00:30:57.614596Z",
"url": "https://files.pythonhosted.org/packages/9f/4c/10421bfee2c14e1f304db5786275de392623109faa404b4afc37ce760c3e/lerobotlab-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-05 00:30:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "newtechmitch",
"github_project": "lerobotlab-tools",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "h5py",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.19.0"
]
]
}
],
"lcname": "lerobotlab"
}
JSON
