Docker provides a sharable environment to run the code in this repository.
We provide separate Dockerfiles for real2sim reconstruction and different robot simulation environments:
docker/real2sim/Dockerfile— for Real2Sim preprocessing and reconstruction.docker/isaaclab/Dockerfile— for IsaacLab simulation and policy training.docker/mujoco/Dockerfile— for Mujoco simulation.
Each can be built and run independently depending on your use case.
Here are the steps to build and run the Docker container for this repository.
Make sure you have Docker installed and running on your machine.
You can check this by running:
docker --versionMake sure you have been added to the docker group to run docker commands without sudo.
if you encountered permission issues when running docker_build or docker_run, you can ask your administrator to try:
sudo usermod -aG docker $USERto add you to the docker group. You may need to log out and log back in for this to take effect.
if sometimes the group change does not take effect, you can also try:
newgrp dockerto switch to the docker group in the current terminal session.
You also need to have NVIDIA CUDA Container Toolkit installed. See: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
init.py at the repository root does the whole first-time setup: it checks docker
and the nvidia runtime, creates the host directories the containers write to,
pulls the images, and downloads the pretrained weights. From the repository root:
python3 init.py setupPulling the pre-built images is the normal way to get started; building them from the Dockerfiles takes hours. The packages are public, so the pull is anonymous and no GitHub token or login is needed.
The weights are about 22 GB and take around 20 minutes. setup skips them when
outputs/.weights_installed exists; --force-weights downloads them again and
--skip-weights leaves them out.
Build the images yourself only when you change a Dockerfile. Once the container is running, you can execute any of the scripts above inside it.
Build the container image From the repository root:
python3 init.py setup --buildThe reconstruction image installs its Python packages with uv. The dependency
list lives in docker/real2sim/requirements.docker.in and the Dockerfile
installs the resolved docker/real2sim/requirements.docker.lock; after editing
the .in file, regenerate the lock with the uv pip compile command recorded
in the lock's header.
Optionally, you may want to push the image to a remote registry (e.g., GitHub Container Registry) for easier sharing.
If so, you can tag the image and push it:
docker tag ghcr.io/licesma/openreal2sim/reconstruction:dev ghcr.io/<username>/openreal2sim/reconstruction:dev
docker push ghcr.io/<username>/openreal2sim/reconstruction:devDon't forget to change the visibility of the pushed image to public if you want others to access it.
Run one script in a container
python3 init.py run reconstruction -- python openreal2sim/openreal2sim.py preprocess
python3 init.py run simulation -- python <path_to_script>.pyEverything after -- is the command line executed inside the container, from
the repository root. The container is removed when the command ends.
Pick the GPUs
python3 init.py run reconstruction --gpus 0,1 -- python <path_to_script>.pyWithout --gpus the container sees every GPU on the host.
Publish a port for the GUIs
python3 init.py run reconstruction --port 7860:7860 -- python openreal2sim/gui/segmentation_annotator.py
python3 init.py run reconstruction --port 8000:5000 -- python openreal2sim/gui/gripper_pose_editor.pyOpen an interactive shell
python3 init.py shell reconstruction # or simulationshell takes the same --gpus and --port flags.
-
Install the Container Tools extension for setting up the docker container as a remote development environment.
-
Install the vscode-3d-preview extension for visualizing 3D point clouds directly in VSCode.
-
Install the glTF Model Viewer extension for visualizing textured meshes (.glb files) directly in VSCode.
init.py only assembles docker compose calls, so the raw commands still work:
docker compose -f docker/compose.yml pull reconstruction simulation
HOST_UID=$(id -u) HOST_GID=$(id -g) DOCKER_GID=$(getent group docker | cut -d: -f3) \
docker compose -p "$USER" -f docker/compose.yml run --rm --publish 7860:7860 reconstruction bashHOST_UID/HOST_GID keep the files the container writes owned by you, and
DOCKER_GID lets the reconstruction container reach the docker socket. Selecting
a subset of GPUs needs a second -f file overriding
deploy.resources.reservations.devices, which is what --gpus writes.