diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 25120a2..1275608 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -65,7 +65,7 @@ jobs: # Each assembly must expand on every backend it supports, not just the # default. Only the real backend emits the per-bus # blocks that the hardware bring-ups depend on. - for assembly in robots/*/xacro/*.urdf.xacro; do + for assembly in lite_description/robots/*/xacro/*.urdf.xacro; do for backend in \ "" \ "use_mock_hardware:=false" \ diff --git a/.gitignore b/.gitignore index 751c5e6..e45adf3 100644 --- a/.gitignore +++ b/.gitignore @@ -15,11 +15,8 @@ wheels/ # Onshape export intermediates (transient; the committed urdf/.urdf hub # is what the generator reuses instead of re-exporting). -robots/*/cad/assets/ -robots/*/cad/robot.pkl - -# load_asset() download cache -data/ +lite_description/robots/*/cad/assets/ +lite_description/robots/*/cad/robot.pkl # colcon build artifacts (when robot_descriptions is built in a ROS workspace) /install/ diff --git a/CMakeLists.txt b/CMakeLists.txt index 0e941cc..5c3beb2 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -3,12 +3,14 @@ project(lite_description) find_package(ament_cmake REQUIRED) -# Lite variants live under robots// (franka_description layout: package at -# the repo root, per-robot assets in a robots/ subdir). Each ships generated, -# installable artifacts (xacro / urdf / mjcf / meshes). The cad/ subdir holds -# generation INPUTS (Onshape config, joint_properties.json, physics.json, -# ros2_control.json, scad) and is intentionally NOT installed. -# Keep this list in sync with the converter's robot list. +# Lite variants live under lite_description/robots//, inside the Python +# package that ships them in a wheel. They install to +# share/lite_description/robots//, so package:// URLs and $(find ...) do +# not depend on the source layout. Each ships generated, installable artifacts +# (xacro / urdf / mjcf / meshes). The cad/ subdir holds generation INPUTS +# (Onshape config, joint_properties.json, physics.json, ros2_control.json, scad) +# and is intentionally NOT installed. +# The generator's package stage adds each new robot to this list. set(ROBOTS lite lite_bimanual @@ -22,9 +24,9 @@ set(ROBOTS # a model-only robot may have no ros2_control xacro, etc.). foreach(robot ${ROBOTS}) foreach(sub xacro urdf mjcf meshes) - if(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/robots/${robot}/${sub}) + if(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/lite_description/robots/${robot}/${sub}) install( - DIRECTORY robots/${robot}/${sub} + DIRECTORY lite_description/robots/${robot}/${sub} DESTINATION share/${PROJECT_NAME}/robots/${robot} ) endif() diff --git a/README.md b/README.md index bd3b4eb..f7de91a 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ meshes, all generated from the Onshape CAD. The same source serves both worlds: -- Simulation and RL, through the `robot_assets` Python loader, for Mujoco Lab and Isaac Lab. +- Simulation and RL, through the `lite_description` Python package, for Mujoco Lab and Isaac Lab. - ROS 2, through `ros2_control` and `robot_state_publisher`, as the `lite_description` ament package. @@ -53,27 +53,36 @@ path emits several blocks while the mock and MuJoCo paths share one combined blo ## CAD source Every description is generated from an Onshape assembly (document -`e9ee61a2e2678af2088d9f31`) by the `robot_assets` tool. See -[Re-generating from CAD](#re-generating-from-cad). The files under `robots//` are -build artifacts. Do not hand-edit them. Change the `cad/` inputs and regenerate. +`e9ee61a2e2678af2088d9f31`) by the generator in `lite_description.workflow`. See +[Re-generating from CAD](#re-generating-from-cad). The files under +`lite_description/robots//` are build artifacts. Do not hand-edit them. Change the +`cad/` inputs and regenerate. ## Usage ### Simulation and RL (Python, no ROS toolchain) +The `lite_description` Python package carries every variant, so a simulator or a training +run reaches the assets without a checkout. The package has no dependencies of its own. + ```bash uv add git+https://github.com/Berkeley-Humanoids/Lite-Description.git ``` ```python -from robot_assets import load +import mujoco +from lite_description import VARIANTS, get_mjcf_path, get_urdf_path -urdf_path = load("robots/lite/urdf/lite.urdf") # Isaac Lab -mjcf_path = load("robots/lite_dummy/mjcf/lite_dummy.xml") # MuJoCo +model = mujoco.MjModel.from_xml_path(str(get_mjcf_path("lite_biped"))) # MuJoCo +urdf_path = get_urdf_path("lite") # Isaac Lab ``` -`load()` fetches the requested variant's subtree from this GitHub repo and caches it. No -ROS install is required. +Each function returns a path inside the installed package. A name that is not in +`VARIANTS` raises `ValueError`. A URDF or MJCF reaches its meshes by a path relative to its +own directory, so load the file where it lies instead of copying it out alone. + +The `uv.lock` of the consuming project records the commit of this repository. The assets +thus change only when that project upgrades `lite-description`. No ROS install is required. ### ROS 2 @@ -81,33 +90,36 @@ ROS install is required. repo root. Build it in a ROS 2 workspace, or pull it with `vcs` or `humanoid_control.repos` from `Humanoid Control`, then run `colcon build`. Downstream, `robot_state_publisher` runs xacro on -`robots//xacro/.urdf.xacro`, and +`$(find lite_description)/robots//xacro/.urdf.xacro`, and `package://lite_description/robots//meshes/visual/...` resolves after install. +colcon installs `lite_description/robots//` to +`share/lite_description/robots//` and leaves out `cad/`. ## Repository layout ``` Lite-Description/ # repo root == ament package "lite_description" - package.xml CMakeLists.txt # ament (colcon); installs robots//... - pyproject.toml # pip/uv: builds the robot_assets Python module - robot_assets/ # Python module: load() and the CAD->assets generator + package.xml CMakeLists.txt # ament (colcon); installs lite_description/robots//... + pyproject.toml # pip/uv: builds the lite-description wheel + lite_description/ # Python package + __init__.py # ROBOTS_DIR, VARIANTS, get_urdf_path(), get_mjcf_path() actuators/ # actuator spec tables (velocity/effort/armature) - workflow/ # the generator stages - robots/ # per-variant assets (franka_description-style subdir) - / - xacro/ # ROS entry (GENERATED) - .urdf.xacro # assembly: args, includes, instantiation - .description.xacro # model macro: kinematics, ${mesh_root}, base_link - .ros2_control.xacro # hardware macros: joints, groups, backends - urdf/.urdf # flat URDF (GENERATED; the kinematic HUB) - mjcf/.xml # MJCF (GENERATED; MuJoCo training + deployment sim) - meshes/visual/*.stl # one shared mesh copy - cad/ # generation INPUTS (not installed): - config.json # Onshape document + export options - joint_properties.json # sim tuning: armature / friction / effort_limit - physics.json # MJCF