From 81a8acc681acd4cac8007c52a871727cd2e93682 Mon Sep 17 00:00:00 2001 From: zhenai Date: Wed, 28 Oct 2026 12:04:05 +0800 Subject: [PATCH] Initial commit --- .gitattributes | 10 ++ .gitignore | 17 ++ .pre-commit-config.yaml | 26 +++ .vscode/.gitignore | 9 + .vscode/extensions.json | 9 + .vscode/tasks.json | 11 ++ .vscode/tools/launch.template.json | 14 ++ .vscode/tools/settings.template.json | 31 ++++ LICENSE | 30 ++++ README.md | 116 +++++++++++++ pyproject.toml | 170 +++++++++++++++++++ scripts/list_envs.py | 13 ++ src/TwoFootBot_isaaclab/__init__.py | 6 + src/TwoFootBot_isaaclab/assets/__init__.py | 11 ++ src/TwoFootBot_isaaclab/assets/data/.gitkeep | 0 src/TwoFootBot_isaaclab/tasks/__init__.py | 10 ++ tests/test_registration.py | 19 +++ 17 files changed, 502 insertions(+) create mode 100644 .gitattributes create mode 100644 .gitignore create mode 100644 .pre-commit-config.yaml create mode 100644 .vscode/.gitignore create mode 100644 .vscode/extensions.json create mode 100644 .vscode/tasks.json create mode 100644 .vscode/tools/launch.template.json create mode 100644 .vscode/tools/settings.template.json create mode 100644 LICENSE create mode 100644 README.md create mode 100644 pyproject.toml create mode 100644 scripts/list_envs.py create mode 100644 src/TwoFootBot_isaaclab/__init__.py create mode 100644 src/TwoFootBot_isaaclab/assets/__init__.py create mode 100644 src/TwoFootBot_isaaclab/assets/data/.gitkeep create mode 100644 src/TwoFootBot_isaaclab/tasks/__init__.py create mode 100644 tests/test_registration.py diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..15ebccd --- /dev/null +++ b/.gitattributes @@ -0,0 +1,10 @@ +*.usd filter=lfs diff=lfs merge=lfs -text +*.usda filter=lfs diff=lfs merge=lfs -text +*.usdc filter=lfs diff=lfs merge=lfs -text +*.usdz filter=lfs diff=lfs merge=lfs -text +*.pt filter=lfs diff=lfs merge=lfs -text +*.jit filter=lfs diff=lfs merge=lfs -text +*.hdf5 filter=lfs diff=lfs merge=lfs -text + +*.bat text eol=crlf +*.sh text eol=lf diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d8f5bdf --- /dev/null +++ b/.gitignore @@ -0,0 +1,17 @@ +.venv/ +.pytest_cache/ +.ruff_cache/ +**/__pycache__/ +**/*.egg-info/ +*.py[cod] +build/ +dist/ + +logs/ +outputs/ +videos/ +wandb/ + +.vscode/settings.json +.vscode/launch.json +pyrightconfig.json diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..a9235a2 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,26 @@ +# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). +# All rights reserved. +# +# SPDX-License-Identifier: BSD-3-Clause + +repos: + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.14.10 + hooks: + - id: ruff-check + args: ["--fix"] + - id: ruff-format + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v6.0.0 + hooks: + - id: check-added-large-files + args: ["--maxkb=2000"] + - id: check-merge-conflict + - id: check-toml + - id: check-yaml + - id: end-of-file-fixer + - id: trailing-whitespace + - repo: https://github.com/codespell-project/codespell + rev: v2.4.1 + hooks: + - id: codespell diff --git a/.vscode/.gitignore b/.vscode/.gitignore new file mode 100644 index 0000000..e0a8bea --- /dev/null +++ b/.vscode/.gitignore @@ -0,0 +1,9 @@ +# Note: These files are kept for development purposes only. +!tools/launch.template.json +!tools/settings.template.json +!extensions.json +!tasks.json + +# Ignore all other files +.python.env +*.json diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..5f6ac04 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,9 @@ +{ + // See http://go.microsoft.com/fwlink/?LinkId=827846 + // for the documentation about the extensions.json format + "recommendations": [ + "ms-python.python", + "ms-python.vscode-pylance", + "charliermarsh.ruff", + ] +} diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..f7751b1 --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,11 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "label": "setup_python_env", + "type": "shell", + "command": "uv run isaaclab --editor", + "problemMatcher": [] + } + ] +} diff --git a/.vscode/tools/launch.template.json b/.vscode/tools/launch.template.json new file mode 100644 index 0000000..33fe235 --- /dev/null +++ b/.vscode/tools/launch.template.json @@ -0,0 +1,14 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Python: Current File", + "type": "debugpy", + "request": "launch", + // Use the interpreter recorded by `isaaclab --editor`; VS Code skips wrapper scripts such as python.sh + "python": "${config:python.defaultInterpreterPath}", + "program": "${file}", + "console": "integratedTerminal" + }, + ] +} diff --git a/.vscode/tools/settings.template.json b/.vscode/tools/settings.template.json new file mode 100644 index 0000000..e19e413 --- /dev/null +++ b/.vscode/tools/settings.template.json @@ -0,0 +1,31 @@ +{ + "files.associations": { + "*.kit": "toml", + "*.rst": "restructuredtext" + }, + "editor.rulers": [120], + + // files to be ignored by the linter + "files.watcherExclude": { + "**/.git/objects/**": true, + "**/.git/subtree-cache/**": true, + "**/node_modules/**": true, + "**/_isaac_sim/**": true, + "**/_compiler/**": true + }, + // This enables python language server. Seems to work slightly better than jedi: + "python.languageServer": "Pylance", + // Use ruff as a formatter and linter + "ruff.configuration": "${workspaceFolder}/pyproject.toml", + // Python environment path + // note: the default interpreter is overridden when user selects a workspace interpreter + // in the status bar. For example, the virtual environment python interpreter + "python.defaultInterpreterPath": "", + // Language specific settings + "[python]": { + "editor.tabSize": 4 + }, + "[restructuredtext]": { + "editor.tabSize": 2 + } +} diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..263cbea --- /dev/null +++ b/LICENSE @@ -0,0 +1,30 @@ +Copyright (c) 2026, Zhenai. + +All rights reserved. + +SPDX-License-Identifier: BSD-3-Clause + +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its contributors + may be used to endorse or promote products derived from this software without + specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR +ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON +ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..827bd30 --- /dev/null +++ b/README.md @@ -0,0 +1,116 @@ +# TwoFootBot_isaaclab + +An installable downstream Isaac Lab task package with a standard uv `src` layout. + +No tasks are registered yet. Add task packages under `src/TwoFootBot_isaaclab/tasks` and register them with Gymnasium. + + +## Installation + +Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then create the project environment. The default +environment uses the Newton backend and does not install Isaac Sim: + +```bash +uv sync +``` + +This project's `pyproject.toml` uses editable relative paths to an Isaac Lab source checkout. Update +`[tool.uv.sources]` if either directory moves. + +The project forwards every optional extra declared by the Isaac Lab package used to create it, including physics, +rendering, visualizer, RL, teleoperation, and development features. Inspect `pyproject.toml` for the complete list and +pass each required extra to `uv run`: + +```bash +# Standalone OV PhysX +uv run --extra ovphysx isaaclab random_agent --task physics=ovphysx + +# Isaac Sim with PhysX and RTX rendering +uv run --extra isaacsim isaaclab random_agent --task physics=isaacsim_physx + +# Isaac Sim with the Rerun visualizer +uv run --extra isaacsim --extra rerun isaaclab random_agent --task --viz rerun +``` + +The `all` extra forwards Isaac Lab's `all` selection. The `ov` extra installs both the `ovphysx` and `ovrtx` runtimes; +you can also select either independently. Commit `pyproject.toml` and `uv.lock` so collaborators use the same +environment. + +## Run the tasks + +After registering a task, list it with: + +```bash +uv run isaaclab list_envs --show_presets +``` + +## Project structure + +Add task packages under `src/TwoFootBot_isaaclab/tasks`. Import each task package from that directory so its Gymnasium +registrations load through the project's `isaaclab.tasks` entry point. + +## Project assets + +Keep project-owned USD files and related data under `src/TwoFootBot_isaaclab/assets/data`. The asset module exposes a +stable path that works from an editable checkout and an installed wheel: + +```python +from TwoFootBot_isaaclab.assets import TWOFOOTBOT_ISAACLAB_ASSETS_DIR + +robot_usd_path = TWOFOOTBOT_ISAACLAB_ASSETS_DIR / "robots" / "my_robot.usd" +``` + +Keep asset configuration in the `TwoFootBot_isaaclab.assets` package and pass `str(robot_usd_path)` to configuration fields that +expect a string. USD files are configured for Git LFS by the project's `.gitattributes`; install Git LFS before adding +large binary assets. + +## Development + +Run the registration test and code-quality checks through the project environment: + +```bash +uv run pytest +uv run pre-commit run --all-files +``` + +The test helpers under `source/isaaclab_tasks/test` in the Isaac Lab repository are not part of the installed +`isaaclab_tasks` package. Keep test fixtures in this project and use public Isaac Lab APIs. If you copy +`env_test_utils.py`, it becomes vendored code whose upstream changes you must track. + +To configure VS Code or Cursor, run the `setup_python_env` task or invoke its command directly: + +```bash +uv run isaaclab --editor +``` + +The setup command selects the active interpreter and writes a git-ignored `pyrightconfig.json`. The resulting +configuration inherits the project's checked-in Pyright settings and adds the Isaac Sim extensions, project `src` root, +and any Isaac Lab packages discovered in the active Python environment. This supports both Pylance in VS Code and +basedpyright in Cursor. + +In VS Code, use Pylance and select the interpreter that ran the setup command. In Cursor, install the +[basedpyright extension](https://marketplace.visualstudio.com/items?itemName=detachhead.basedpyright) instead of +Pylance, select the same interpreter, and reload the window. Both language servers read `pyrightconfig.json`. + +When using the `isaacsim` extra, include it while generating the editor configuration so the command can discover the +Isaac Sim installation: + +```bash +uv run --extra isaacsim isaaclab --editor +``` + +For an Isaac Sim binaries installation that is not available in the project environment, provide its path explicitly: + +```bash +# Linux +uv run isaaclab --editor --isaac_path + +# Windows +uv run isaaclab --editor --isaac_path +``` + +## Troubleshooting + +If Pylance or basedpyright cannot resolve modules, confirm that the selected interpreter matches the one used to run the +setup command, then reload the editor window. To add a missing extension or reduce indexing memory, edit the `extraPaths` +array in the root `pyrightconfig.json`; remove simulator extension directories that the project does not use. diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..09b9690 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,170 @@ +# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). +# All rights reserved. +# +# SPDX-License-Identifier: BSD-3-Clause + +[build-system] +requires = ["uv_build>=0.12.6,<0.13"] +build-backend = "uv_build" + +[project] +name = "TwoFootBot_isaaclab" +version = "0.1.0" +description = "Isaac Lab environments for TwoFootBot_isaaclab." +readme = "README.md" +license = { file = "LICENSE" } +authors = [ + { name = "Zhenai" }, +] +requires-python = ">=3.12,<3.13" +dependencies = [ + "isaaclab-dev", +] + +[project.entry-points."isaaclab.tasks"] +TwoFootBot_isaaclab = "TwoFootBot_isaaclab.tasks" + +[project.optional-dependencies] +all = ["isaaclab-dev[all]"] +dev = ["isaaclab-dev[dev]"] +importers = ["isaaclab-dev[importers]"] +isaacsim = ["isaaclab-dev[isaacsim]"] +leapp = ["isaaclab-dev[leapp]"] +mimic = ["isaaclab-dev[mimic]"] +ov = ["isaaclab-dev[ov]"] +ovphysx = ["isaaclab-dev[ovphysx]"] +ovrtx = ["isaaclab-dev[ovrtx]"] +rerun = ["isaaclab-dev[rerun]"] +rl-games = ["isaaclab-dev[rl-games]"] +rlinf = ["isaaclab-dev[rlinf]"] +rsl-rl = ["isaaclab-dev[rsl-rl]"] +sb3 = ["isaaclab-dev[sb3]"] +skrl = ["isaaclab-dev[skrl]"] +skrl-jax = ["isaaclab-dev[skrl-jax]"] +teleop = ["isaaclab-dev[teleop]"] +test = ["isaaclab-dev[test]"] +tetrahedralization = ["isaaclab-dev[tetrahedralization]"] +torchrl = ["isaaclab-dev[torchrl]"] +video = ["isaaclab-dev[video]"] +viser = ["isaaclab-dev[viser]"] +wandb = ["isaaclab-dev[wandb]"] + +[dependency-groups] +dev = ["codespell>=2.4", "pre-commit>=4.2", "pytest>=8.3", "ruff>=0.11"] + +[tool.uv] +index-strategy = "unsafe-best-match" +prerelease = "allow" +environments = [ + "sys_platform == 'linux' and platform_machine == 'x86_64'", + "sys_platform == 'linux' and platform_machine == 'aarch64'", + "sys_platform == 'win32' and platform_machine == 'AMD64'", +] +override-dependencies = [ + "numpy>=2", + "mujoco~=3.12.0", + "mujoco-warp~=3.12.0", + "newton[sim]==1.6.1", + "newton-usd-schemas>=0.5.0", + "usd-exchange==3.0.1", + "usd-optimize~=1.3.1", + "torch==2.11.0", + "torchvision==0.26.0", + "fsspec>=2026.6.0", + "packaging>=20,<27", + "urllib3>=2.8.0", +] + +[tool.uv.sources] +"isaaclab" = { path = "../IsaacLab/source/isaaclab", editable = true } +"isaaclab-assets" = { path = "../IsaacLab/source/isaaclab_assets", editable = true } +"isaaclab-contrib" = { path = "../IsaacLab/source/isaaclab_contrib", editable = true } +"isaaclab-dev" = { path = "../IsaacLab", editable = true } +"isaaclab-experimental" = { path = "../IsaacLab/source/isaaclab_experimental", editable = true } +"isaaclab-mimic" = { path = "../IsaacLab/source/isaaclab_mimic", editable = true } +"isaaclab-newton" = { path = "../IsaacLab/source/isaaclab_newton", editable = true } +"isaaclab-ov" = { path = "../IsaacLab/source/isaaclab_ov", editable = true } +"isaaclab-physx" = { path = "../IsaacLab/source/isaaclab_physx", editable = true } +"isaaclab-ppisp" = { path = "../IsaacLab/source/isaaclab_ppisp", editable = true } +"isaaclab-rl" = { path = "../IsaacLab/source/isaaclab_rl", editable = true } +"isaaclab-tasks" = { path = "../IsaacLab/source/isaaclab_tasks", editable = true } +"isaaclab-tasks-experimental" = { path = "../IsaacLab/source/isaaclab_tasks_experimental", editable = true } +"isaaclab-teleop" = { path = "../IsaacLab/source/isaaclab_teleop", editable = true } +"isaaclab-visualizers" = { path = "../IsaacLab/source/isaaclab_visualizers", editable = true } +"omniverseclient" = { index = "pypi-public" } +"ovphysx" = { index = "pypi-public" } +"ovrtx" = { index = "pypi-public" } +"ovstage" = { index = "pypi-public" } +"torch" = { index = "pytorch-cu130" } +"torchvision" = { index = "pytorch-cu130" } + +[tool.uv.build-backend] +module-name = "TwoFootBot_isaaclab" + +[tool.ruff] +line-length = 120 +target-version = "py312" + +[tool.ruff.lint] +select = ["E", "F", "I", "UP", "B", "SIM"] + +[tool.ruff.lint.isort] +known-first-party = ["TwoFootBot_isaaclab"] +section-order = [ + "future", + "standard-library", + "third-party", + "isaaclab", + "isaaclab-rl", + "isaaclab-tasks", + "isaaclab-assets", + "first-party", + "local-folder", +] + +[tool.ruff.lint.isort.sections] +isaaclab = ["isaaclab", "isaaclab_newton", "isaaclab_ov", "isaaclab_physx"] +"isaaclab-rl" = ["isaaclab_rl"] +"isaaclab-tasks" = ["isaaclab_tasks"] +"isaaclab-assets" = ["isaaclab_assets"] + +[tool.ruff.lint.per-file-ignores] +"**/__init__.py" = ["F401", "F403"] +"**/__init__.pyi" = ["F401", "F403"] +"scripts/**/*.py" = ["E402"] + +[tool.ruff.format] +docstring-code-format = true + +[tool.pyright] +include = ["src", "scripts", "tests"] +exclude = ["**/__pycache__", "**/logs", ".git", ".venv", ".vscode"] +typeCheckingMode = "basic" + +[tool.pytest.ini_options] +testpaths = ["tests"] +addopts = "-ra" +markers = [ + "unit: test exercises isolated logic and does not launch the simulator", + "integration: test drives the simulator/scene/environment end-to-end", + "smoke: tests for core installation, task, and RL functionality", + "kitless: test must pass inside the Kit-less container, which has no Isaac Sim runtime", +] + +[tool.codespell] +skip = "*.usd,*.usda,*.usdc,*.json,*.onnx,*.pt,*.mp4,*.data,uv.lock,logs" + +[[tool.uv.index]] +url = "https://pypi.nvidia.com" +explicit = false + +[[tool.uv.index]] +name = "pypi-public" +url = "https://pypi.org/simple" +explicit = true + +[[tool.uv.index]] +name = "pytorch-cu130" +url = "https://download.pytorch.org/whl/cu130" +explicit = true + diff --git a/scripts/list_envs.py b/scripts/list_envs.py new file mode 100644 index 0000000..32fe615 --- /dev/null +++ b/scripts/list_envs.py @@ -0,0 +1,13 @@ +# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). +# All rights reserved. +# +# SPDX-License-Identifier: BSD-3-Clause + +"""Compatibility wrapper for ``isaaclab list_envs``.""" + +import sys + +from isaaclab.cli.commands.list_envs import command_list_envs + +if __name__ == "__main__": + command_list_envs(sys.argv[1:]) diff --git a/src/TwoFootBot_isaaclab/__init__.py b/src/TwoFootBot_isaaclab/__init__.py new file mode 100644 index 0000000..4566f14 --- /dev/null +++ b/src/TwoFootBot_isaaclab/__init__.py @@ -0,0 +1,6 @@ +# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). +# All rights reserved. +# +# SPDX-License-Identifier: BSD-3-Clause + +"""Isaac Lab environments for the TwoFootBot_isaaclab project.""" diff --git a/src/TwoFootBot_isaaclab/assets/__init__.py b/src/TwoFootBot_isaaclab/assets/__init__.py new file mode 100644 index 0000000..72e3fa3 --- /dev/null +++ b/src/TwoFootBot_isaaclab/assets/__init__.py @@ -0,0 +1,11 @@ +# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). +# All rights reserved. +# +# SPDX-License-Identifier: BSD-3-Clause + +"""Paths and configurations for project-owned assets.""" + +from pathlib import Path + +TWOFOOTBOT_ISAACLAB_ASSETS_DIR = Path(__file__).resolve().parent / "data" +"""Path to project-owned asset data.""" diff --git a/src/TwoFootBot_isaaclab/assets/data/.gitkeep b/src/TwoFootBot_isaaclab/assets/data/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/TwoFootBot_isaaclab/tasks/__init__.py b/src/TwoFootBot_isaaclab/tasks/__init__.py new file mode 100644 index 0000000..e37354d --- /dev/null +++ b/src/TwoFootBot_isaaclab/tasks/__init__.py @@ -0,0 +1,10 @@ +# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). +# All rights reserved. +# +# SPDX-License-Identifier: BSD-3-Clause + +"""Task registrations for the project.""" + +from isaaclab_tasks.utils import import_packages + +import_packages(__name__, ["utils", ".mdp"]) diff --git a/tests/test_registration.py b/tests/test_registration.py new file mode 100644 index 0000000..d073674 --- /dev/null +++ b/tests/test_registration.py @@ -0,0 +1,19 @@ +# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). +# All rights reserved. +# +# SPDX-License-Identifier: BSD-3-Clause + +"""Tests for the project's task registrations.""" + +import gymnasium as gym + +import TwoFootBot_isaaclab.tasks # noqa: F401 + + +def test_task_registrations(): + """The project tasks must expose valid environment and agent entry points.""" + assert all( + not str(spec.kwargs.get("env_cfg_entry_point", "")).startswith("TwoFootBot_isaaclab.tasks") + for spec in gym.registry.values() + ) +