Contact-rich Manipulation

Documentation

https://probable-adventure-3771wzy.pages.github.io/

Pre-commit

We use pre-commit to run simple checks such as auto-formatting and linting. Follow the instructions in the hyperlink to set up pre-commit locally in VM or on laptop.

Using the CRM docker image

First, pull the image with

docker pull ghcr.io/bdaiinstitute/contact-rich-manipulation:main

Then, launch a container with

docker run --interactive --tty -p 7000:7000 -p 8050:8050 ghcr.io/bdaiinstitute/contact-rich-manipulation:main

where the exposed ports allow viewing dash_vis and meshcat visualizations in a browser.

The crm repo is located at

cd /contact_rich_manipulation

Now you can try, for instance, running the robust trajectory optimizer for the planar hand system:

python3 crm/examples/planar_hand/trj_opt_particle_direct_transcription.py

Development

Setup

cd /path/to/contact-rich-manipulation
# do the apt steps of the installation, which requires sudo
# this will also install the python packages globally
sudo ./setup/install_crm.sh

If using a virtual env (recommended)

In addition to the above commands, run these to setup a virtual environment.

cd /path/to/contact-rich-manipulation
# create the virtual environment
python -m venv .venv
# activate it, use a peer activate script for your shell
.venv/bin/activate
# do not run as root when the venv is active
./setup/install_crm.sh --no-apt

Configure your IDE to use the .venv/ for the python runtime, if it doesn't detect it automatically.

Build docker image

Build

# On laptop/VM
cd /path/to/contact-rich-manipulation
docker build -t local-crm-build -f ./setup/crm.dockerfile .

Verify by running the container. Use the same run command above or with the tips below, but with local-crm-build as the image name:

docker run --interactive --tty -p 7000:7000 -p 8050:8050 local-crm-build

Tips

Data files, .bashrc, and other dotfiles

If you want data files, custom prompts, aliases, etc in your docker container, use -v arguments in the docker run command, before the image name:

-v ~/my-data  # ends up in /home/<your username>/my-data
-v ~/.bashrc_cmr:/root/.bashrc  # rename the file
-v ~/.bashrc_container:/root/.bashrc_container  # for shared things with bdaii container, which shoud be sourced from the /root/.bashrc file
-v ~/.config/powerline:/root/.config/powerline  # example for other configs

Note: "root" is the runas user in the container, which is why the configs need to be in /root not /home/$USER.

Consistent docker container name

This is especially useful if you run off your laptop with other docker containers.

Add --name to the docker run command

--name contact-rich-manipulation

This is a one-liner to stop and run a new container, such as when there are new dependencies

docker stop contact-rich-manipulation; docker rm contact-rich-manipulation; docker run --interactive ... --name contact-rich-manipulation ghcr.io/bdaiinstitute/contact-rich-manipulation:main

Multiple terminal windows in the docker container

You will likely want to get multiple terminal windows in the docker container, other than the docker run terminal window. To do this, run docker ps to grab the name of the container (look for a randomly generated name like strange_mongoose). Then, run docker exec -it <name> bash. This will give you a new terminal in the docker container.

Alternatively, when starting the container, add the --detach flag to start the container but not open the shell. This is useful when running with VSCode's "Attach Container" feature. Use docker exec to open as many terminals into the container.

Git

There are multiple ways to have git working inside the docker container. One way is to mount a .gitconfig which includes the following:

[url "https://$username:$password@github.com"]
	insteadOf = https://github.com

where $username is your Github username, and $password is your Github's personal access token.

pip

Installing the package with pip install -e .[dev] will error if pip's version is less than 24.2 (i.e., if pip's version is 22.2). Please upgrade pip if you are running into this issue.

Virtual environments and docker

Some editors (like vscode) will automatically default to using an existing virtual environment (found at .venv/, env/, etc), and ignore the base python environment of the docker. This can lead to dependency issues, and can be mitigated by either pointing the editor away from the venv, or by deleting the venv entirely.

Bazel build (experimental)

Currently, the Bazel build only supports diffusion_policy development.

It builds a limited subset of contact_rich_manipulation_cpp and qsim for tasks that uses CRM. It also includes python targets for diffusion_policy experiments.

TODO(duy): Full Bazel build after Dec-2023 demo.

Steps to use and test:

1. Make sure you have an Ubuntu 22.04 machine. (Some VMs come with Debian by default).

   lsb_release -a

2. Install Drake's Mandatory platform-specific instructions

   • Also install clang:

   sudo apt install clang

   (We don't use clang to build our software, but some third-party python packages, e.g. evdev, require clang.)

   TODO(duy): automate this step with an install_prereqs.sh script for this repo.

3. Install Bazel

4. Setup Git credentials so Bazel can clone private git repos. There are two ways to achieve this:

   • Via .netrc:

     echo "machine github.com login $username password $password" > ~/.netrc

   • Or via git config:

     git config --global url."https://$username:$password@github.com".insteadOf https://github.com

   where $username is your Github username, and $password is your Github's personal access token.

5. Build and test all targets:

   bazel build //...
   bazel test //...

   Or, if you just want to run a specific target:

   bazel run //tasks_diffusion_policy/planar_hand_ball:test_planar_hand_ball_qsim_env
   

6. If you update requirements.in, the lock file needs to be updated as well:

   bazel run //:requirements.update

   Also, remember to include the new packages in the corresponding targets' dependency list. (See, for example, diffusion_policy_requirements in diffpo/BUILD)