Auto Atomic Operation

A YAML-driven atomic operation framework for robotic manipulation.

auto-atomic-operation lets you define robotic manipulation tasks — move, grasp, release, pick, place, push, pull, press — as declarative YAML files. A built-in state machine handles task sequencing, pose resolution, end-effector control, and execution tracking. A plugin-based backend system decouples task logic from the underlying hardware or simulator, making it easy to run the same task definition against a real robot, a physics simulator, or a lightweight mock for testing.

Features

• Hydra-powered task configuration — describe multi-stage manipulation tasks in YAML; full Hydra support means _target_ instantiation, variable interpolation, and command-line overrides work out of the box
• Flexible pose references — specify targets relative to world, robot base, end-effector, or tracked objects
• Pluggable backends — connect any robot or simulator by implementing a small set of abstract interfaces
• Pose randomization — per-object position/orientation randomization with automatic collision avoidance on reset
• Multi-arm support — single-arm and dual-arm (left/right) topologies
• Execution records — detailed per-stage status, failure reasons, and timing after every run
• MuJoCo backend included — a ready-to-use backend with RGB-D cameras, tactile sensors, force/torque, IMU, and joint state support
• 3D Gaussian Splatting rendering — photorealistic rendering for any task via _gs.yaml configs

Installation

Requires Python 3.10+.

Install from PyPI

pip install auto-atomic-operation

The PyPI release lags behind source and does not ship with demo configs/assets. For the latest features and runnable demos, install from source.

Install from source

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/OpenGHz/auto-atomic-operation.git
cd auto-atomic-operation

pip install -e .              # core framework only
pip install -e ".[mujoco]"    # with the built-in MuJoCo backend
pip install -e ".[gs]"        # with 3D Gaussian Splatting rendering

Alternatively, pixi creates a project-local environment (Python 3.12, editable install with the MuJoCo extra, pytest, and asset-inspection tools) from pyproject.toml and pixi.lock:

pixi install
pixi run aao-demo task=pick_and_place

Gaussian-splatting rendering uses the separate gs environment (Python 3.10, torch 2.4 / CUDA 12.4 and prebuilt gsplat kernels; needs an NVIDIA driver with CUDA >= 12.4):

pixi install -e gs
pixi run -e gs gs-assets                          # download assets/gs/ (set HF_ENDPOINT for a mirror)
pixi run -e gs aao-demo task=cup_on_coaster render=gs

MuJoCo demo assets live in Git LFS. After cloning, install Git LFS and pull them:

sudo apt-get install git-lfs   # Debian/Ubuntu
git lfs pull

Running demos

The CLI composes ./aao_configs/config.yaml relative to the current working directory. After cloning the repo, run from the project root. Every run is selected by Hydra config groups — a task, optionally an embodiment (robot) and a render mode:

aao-info                                          # list every runnable task x embodiment variant
aao-demo task=mock                                # mock backend, no simulator required
aao-demo task=pick_and_place                      # MuJoCo demo (default task)
aao-demo task=<task> [embodiment=<robot>] [render=gs]   # any other variant

aao-info prints the exact aao-demo task=... embodiment=... command for every variant.

For all CLI flags, Hydra overrides, and aao-eval usage, see the CLI Reference.

Robotiq tasks

pick_and_place	cup_on_coaster
stack_color_blocks	press_three_buttons
open_drawer	close_drawer
open_hinge_door	close_hinge_door

Franka task

task=pick_and_place embodiment=franka_robotiq

3D Gaussian Splatting demos

GS rendering is selected with render=gs (e.g. aao-demo task=cup_on_coaster render=gs); otherwise the runs are identical to the native MuJoCo demos. Asset bundles live on Hugging Face (pixi run -e gs gs-assets downloads them in the pixi setup):

pip install huggingface_hub "httpx[socks]"
hf download OpenGHz/auto-atom-assets --repo-type=dataset --include "assets/gs/*" --local-dir .

task=cup_on_coaster render=gs	task=stack_color_blocks render=gs
task=press_three_buttons render=gs	task=arrange_flowers render=gs
task=hang_toothbrush_cup render=gs	task=wipe_the_table render=gs

Documentation

Full documentation is hosted at openghz.github.io/auto-atomic-operation. Common entry points:

• CLI Reference — every flag, override, and output of aao-demo / aao-eval
• Task File Schema — top-level YAML keys, stages, pose references, and execution policy
• Task Configuration — waypoints, interval boundaries, stage sites, randomization, and scene composition
• Execution Completion Flow — how pre_move / eef / post_move decide they are done and how that drives stage success
• MuJoCo Backend — backend conditions, gripper semantics, observation wiring
• Custom Backend Guide — integrate a new simulator or real robot
• IK & Motion Control
• Gaussian Splatting
• Tools — data collection, replay, policy evaluation, panel XML assembly, scene viewer, randomization tuning, benchmarking
• Migration Notes — bring your own XML / mesh / GS assets into this project's layout

License

See LICENSE.