add documentation

.github/workflows/publish-doc.yml

@@ -0,0 +1,159 @@
+# action.yml
+name: 'Build Docs'
+
+on:
+  push:
+    branches:
+      - main
+      # - develop
+  release:
+    types: [published]
+
+jobs:
+  build_docs:
+    runs-on: ubuntu-latest
+    name: 'Build Sphinx documentation'
+    steps:
+      - name: 'Checkout the repo'
+        uses: actions/checkout@v4
+
+      - name: 'Run the buildscript'
+        # Workaround to keep tty working
+        # https://github.com/gfx/example-github-actions-with-tty
+        shell: 'script -q -e -c "bash {0}"'
+        run: ./docs/build-docs.sh ${{ fromJSON('{"tag":"html","branch":"html-dev"}')[github.ref_type] }}
+
+      # Cache the build so we can deploy it
+      - name: 'cache built docs'
+        id: cache-build
+        uses: actions/cache/save@v4
+        with:
+          path: ${{ github.workspace }}/docs/build/html
+          key: ${{ github.sha }}-docs
+
+      # Cache version generation script if we are on a tag
+      - name: 'cache version generation script'
+        id: cache-version-script
+        uses: actions/cache/save@v4
+        if: github.ref_type == 'tag'
+        with:
+          path: ${{ github.workspace }}/docs/generate_versions.sh
+          key: ${{ github.sha }}-docs
+
+  deploy_main_docs:
+    permissions:
+      contents: write
+      pages: write
+    runs-on: ubuntu-latest
+    name: 'Publish latest docs to github pages'
+    needs: build_docs
+    if: github.ref_type == 'branch' && github.ref == 'refs/heads/main'
+    steps:
+      - name: 'Restore built docs cache'
+        uses: actions/cache/restore@v4
+        id: restore-build
+        with:
+          path: ${{ github.workspace }}/docs/build/html
+          key: ${{ github.sha }}-docs
+
+      - name: 'Deploy to gh-pages'
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/build/html
+          publish_branch: gh-pages
+          destination_dir: dev
+
+  deploy_version_docs:
+    permissions:
+      contents: write
+      pages: write
+    runs-on: ubuntu-latest
+    name: 'Publish versioned documentation to github pages'
+    needs: build_docs
+    if: github.ref_type == 'tag'
+    steps:
+      - name: 'Checkout the repo'
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          path: ./public
+
+      - name: 'Get cached version script'
+        uses: actions/cache/restore@v4
+        with:
+          path: ${{ github.workspace }}/docs/generate_versions.sh
+          key: ${{ github.sha }}-docs
+
+      - name: 'Get cached version build'
+        uses: actions/cache/restore@v4
+        with:
+          path: ${{ github.workspace }}/docs/build/html
+          key: ${{ github.sha }}-docs
+
+      - name: 'Move file & directories & run version update script'
+        shell: 'script -q -e -c "bash {0}"'
+        run: >
+          mv ./docs/generate_versions.sh ./public/generate_versions.sh
+          && mv ./docs/build/html ./public/${{ github.ref_name }}
+          && rm -rf ./docs/
+          && ./public/generate_versions.sh
+          && rm -f ./public/generate_versions.sh
+      
+      - name: 'Update latest symlink and kill git'
+        shell: 'script -q -e -c "bash {0}"'
+        run: cd ./public/ && ln -sfn ./${{ github.ref_name }} ./latest && ls -la
+
+      # - name: 'Deploy to gh-pages'
+      #   uses: peaceiris/actions-gh-pages@v3
+      #   with:
+      #     github_token: ${{ secrets.GITHUB_TOKEN }}
+      #     publish_dir: ./public
+      #     publish_branch: gh-pages
+      - name: 'Manually deploy to gh-pages'
+        run: |
+          git config --global user.email "${{github.actor}}@users.noreply.github.com"
+          git config --global user.name "${{github.actor}}"
+          cd ./public
+          git add .
+          git commit -m "deploy: ${{ github.sha }}" && git push origin gh-pages
+
+  # deploy_develop_docs:
+  #   permissions:
+  #     contents: write
+  #     pages: write
+  #   runs-on: ubuntu-latest
+  #   name: 'Publish development documentation to github pages'
+  #   needs: build_docs
+  #   if: endsWith(github.ref, '/develop')
+  #   steps:
+  #     - name: 'Restore built docs cache'
+  #       uses: actions/cache/restore@v3
+  #       id: restore-build
+  #       with:
+  #         path: ${{ github.workspace }}/docs/build/html
+  #         key: ${{ github.sha }}-docs
+
+  #     - name: 'Deploy to gh-pages'
+  #       uses: peaceiris/actions-gh-pages@v3
+  #       with:
+  #         github_token: ${{ secrets.GITHUB_TOKEN }}
+  #         publish_dir: ./docs/build/html
+  #         publish_branch: gh-pages
+  #         destination_dir: develop
+
+
+  # Probably not necesary with cache
+  # cleanup:
+  #   runs-on: ubuntu-latest
+  #   needs: ['build_docs', 'deploy_main_docs', 'deploy_develop_docs']
+  #   name: 'cache cleanup'
+  #   if: always() && needs.build_docs.result == 'success'
+  #   # Fun trick to say we need the above to all finish but only care about the first success
+  #   steps:
+  #     - uses: adapttive/[email protected]
+  #       with:
+  #         github-token: ${{ secrets.GITHUB_TOKEN }}
+  #         cache-key: ${{ github.sha }}-docs
+
+# TODO Versioned docs (look into the release event)

.gitignore

@@ -6,4 +6,15 @@ video_test/
 .vscode/
 trace.json
 pyprof.out
-/render/
+/render/
+
+# Generated documentation
+docs/source/generated/
+docs/_site
+_site
+docs/dev
+
+# MACOS
+.ds_store
+.DS_Store
+.DS_STORE

README.md

@@ -1,6 +1,96 @@
-# Zono-Py
-Implementation of various set representations in Python
+# zonopy-robots
 
+Zonopy-robots is a Python package that extends the capabilities of the [zonopy](https://github.com/roahmlab/zonopy) library to facilitate robotics research.
+Where zonopy introduces continuous set types such as zonotopes into Python, this package provides additional tools for kinematics, dynamics, and loading of URDF's.
+For now, this package is particularly focused on the manipulation of arm robots.
+It integrates with [urchin](https://github.com/fishbotics/urchin) for loading and working with URDF (Unified Robot Description Format) models of articulated robots.
 
+## Features
 
+- **Continuous Set Types**: Support for zonotopes and other continuous set representations for geometric operations.
+- **Robot Kinematics and Dynamics**: Functions for calculating the kinematics and dynamics of robotic mechanisms.
+- **URDF Loader**: Integration with `urchin` to load and manipulate URDF models of articulated arm robots.
 
+## Requirements
+
+- zonopy: The base library for continuous set operations.
+- urchin: Required for URDF model loading and manipulation.
+
+## Installation
+
+Either clone the latest version or a specific tag of this repo and inside of the repo path run:
+
+```
+pip install -e .
+```
+
+## Quick Start
+
+Here's a simple example to get started with `zonopy-robots`:
+
+```python
+# Example: Load a robot model and build the forward kinematics of the robot joints following the ARMTD piecewise trajectory
+import numpy as np
+import zonopyrobots as zpr
+
+# There is an example URDF in this repo - kinova from kinova robotics' ros_kortex
+import os
+basedirname = os.path.dirname(zpr.__file__)
+urdfpath = os.path.join(basedirname, 'robots/assets/robots/kinova_arm/gen3.urdf')
+
+# Load the robot with zonopy-robots. we can access the underlying urchin representation with
+# `robot_model.urdf`, and we visualize it with urchin here.
+robot_model = zpr.ZonoArmRobot.load(urdfpath, device="cpu")
+robot_model.urdf.show()
+# Note that this line sometimes stops the script for some reason
+
+# Prepare the JRS generator
+traj_class = zpr.trajectory.PiecewiseArmTrajectory
+jrs_gen = zpr.JrsGenerator(robot_model, traj_class=traj_class, param_range=np.pi/6, batched=True)
+
+# Initial configuration for the online JRS
+q = np.zeros(robot_model.dof)
+qd = q
+qdd = q
+
+# Generate the JRS for that configuration
+rotatotopes = jrs_gen.gen_JRS(q, qd, qdd, only_R=True)
+
+# Get the position PZ's and rotation MPZ's
+fk = zpr.kinematics.forward_kinematics(rotatotopes, robot_model)
+# The result is a dictionary of link names and their position and rotation PZ's.
+```
+
+<!-- ## Contributing
+
+Contributions to `zonopy-robots` are welcome! Whether it's adding new features, improving existing ones, or reporting bugs, your input helps make this tool better for the research community.
+
+## License
+
+`zonopy-robots` is released under the MIT License. See the LICENSE file for more details. #still need to figure this out -->
+
+## How to Cite
+
+If you use zonopy or zonopy-robots in your research, please cite one or more of the following papers:
+
+Safe Planning for Articulated Robots Using Reachability-based Obstacle Avoidance With Spheres. J. Michaux, A. Li, Q. Chen, C. Chen, B. Zhang, and R. Vasudevan. ArXiv, 2024. (https://arxiv.org/abs/2402.08857)
+```bibtex
+@article{michaux2024sparrows,
+  title={Safe Planning for Articulated Robots Using Reachability-based Obstacle Avoidance With Spheres},
+  author={Jonathan Michaux and Adam Li and Qingyi Chen and Che Chen and Bohao Zhang and Ram Vasudevan},
+  journal={ArXiv},
+  year={2024},
+  volume={abs/2402.08857},
+  url={https://arxiv.org/abs/2402.08857}}
+```
+
+Reachability-based Trajectory Design with Neural Implicit Safety Constraints. J. B. Michaux, Y. S. Kwon, Q. Chen, and R. Vasudevan. Robotics: Science and Systems, 2023. (https://www.roboticsproceedings.org/rss19/p062.pdf)
+```bibtex
+@inproceedings{michaux2023rdf,
+  title={{Reachability-based Trajectory Design with Neural Implicit Safety Constraints}},
+  author={Jonathan B Michaux AND Yong Seok Kwon AND Qingyi Chen AND Ram Vasudevan},
+  booktitle={Proceedings of Robotics: Science and Systems},
+  year={2023},
+  address={Daegu, Republic of Korea},
+  doi={10.15607/RSS.2023.XIX.062}}
+```

docs/Dockerfile

@@ -0,0 +1,11 @@
+FROM sphinxdoc/sphinx:7.1.2
+
+ENV DEBIAN_FROTNEND="noninteractive" TZ="Etc/UTC"
+RUN apt-get update \
+    && apt-get install --no-install-recommends -y nodejs \
+    && apt-get clean \
+    && apt-get -y autoremove \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt /tmp/requirements.txt
+RUN pip install -r /tmp/requirements.txt && rm /tmp/requirements.txt

docs/Makefile

@@ -0,0 +1,24 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Inspired by pytorch, but opposite
+html-dev:
+	DEVELOP=1 make html
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/build-docs.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+
+# Some general conf
+NAME="zonopy-sphinx"
+IMAGE="roahmlab/zonopy-sphinx:latest"
+
+# Identify the script directory
+SCRIPT_DIR="$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )/.." &> /dev/null && pwd )"
+
+## First build the docs container
+tar -cf - -C "$SCRIPT_DIR/docs" Dockerfile requirements.txt | docker build -t $IMAGE -
+
+## Configuration for script vars
+MOUNT_DIR="$SCRIPT_DIR"
+STARTING_DIR="$SCRIPT_DIR"
+USE_UNIQUE=true
+ADD_UNAME=true
+if $USE_UNIQUE;then
+    NAME+="-$(uuidgen)"
+fi
+if $ADD_UNAME;then
+    NAME="$(id -un)-$NAME"
+fi
+
+## Setup uid requirements and workdir for temporaries
+if [ -z "$HOME" ];then
+    HOME=/tmp
+fi
+if [ -z "$ID" ];then
+    ID=$(id -u)
+fi
+WORKDIR="$HOME/.docker"
+mkdir -p "$WORKDIR"
+DOCKER_HOME="$WORKDIR/$NAME"
+mkdir -p "$DOCKER_HOME"
+
+## Build out the Docker options
+DOCKER_OPTIONS=""
+DOCKER_OPTIONS+="-it "
+DOCKER_OPTIONS+="--rm "
+
+## USER ACCOUNT STUFF
+DOCKER_OPTIONS+="--user $(id -u):$(id -g) "
+DOCKER_OPTIONS+="$(id -G | sed -E "s/([[:blank:]]|^)([[:alnum:]_]+)/--group-add \2 /g") "
+DOCKER_OPTIONS+="-e HOME=$HOME "
+
+## PROJECT
+DOCKER_OPTIONS+="-v $MOUNT_DIR:/zonopy "
+DOCKER_OPTIONS+="-v $DOCKER_HOME:$HOME "
+DOCKER_OPTIONS+="--name $NAME "
+DOCKER_OPTIONS+="--workdir=/zonopy/docs "
+DOCKER_OPTIONS+="--entrypoint make "
+DOCKER_OPTIONS+="--net=host "
+
+## CLEANUP
+function cleanup {      
+  rm -rf "$DOCKER_HOME"
+}
+trap cleanup EXIT
+
+## RUN
+docker run $DOCKER_OPTIONS $IMAGE $1