# Mobipick Labs Docker GUI
The Mobipick Labs Docker GUI is a PyQt5 desktop application that orchestrates the
Docker-based Mobipick Labs robotics simulation. Instead of manually invoking
`docker compose` yourself, you launch the `mobipick-labs-docker-gui` command (or
`python -m mobipick_gui`) and drive the bring-up,
monitoring, and shutdown of the simulation through an interactive interface.
The GUI reads the bundled configuration files, runs Docker commands on your
behalf, and streams live logs so you can follow what is happening in each
container.
<img src="doc/mobipick_labs_docker_gui.png" alt="mobipick tables sim and real" width="420">
## Repository layout
```
├── gui.py # Legacy CLI shim that forwards to the packaged entry point
├── mobipick_gui/
│ ├── resources/ # Bundled compose file, default configs, helper scripts
│ └── … # PyQt5 widgets, process orchestration, and helpers
├── MANIFEST.in # Source distribution manifest
└── pyproject.toml # Packaging metadata for PyPI distribution
```
The compose file is **not** intended to be executed directly. The GUI manages it
for you by spawning `docker compose` subprocesses, supervising their lifecycle,
and performing cleanup logic when you close the application.
## Prerequisites
* Ubuntu Linux (tested on versions 20.04, 22.04, and 24.04)
* Python 3.8+ with PyQt5 available (e.g. `pip install PyQt5`).
* Docker Engine and the Docker Compose plugin accessible to your user.
* Access to the Mobipick Labs image repository (for example
`ozkrelo/mobipick_labs:noetic`).
* An X11 server that allows the containers to create GUI windows. The GUI
issues the required `xhost` commands automatically when needed.
## Installation
- Install Docker Engine (`docker.io`) and ensure it is running.
```bash
sudo apt update && sudo apt install docker.io
sudo systemctl enable docker
sudo systemctl start docker
```
- Configure Docker to run without sudo:
```bash
sudo usermod -aG docker $USER
```
Then log out and back in.
- Install the Mobipick Labs GUI from PyPI (this also installs the package dependencies):
```bash
pip install mobipick-labs-docker-gui
```
- Install the Docker Compose plugin and pull the Mobipick Labs image.
```bash
sudo apt install docker-compose-plugin
# Verify that the Compose plugin is available
docker compose version
# pull mobipick labs docker image from docker hub
docker pull ozkrelo/mobipick_labs:noetic
```
- Optional but strongly recommended if you have an NVIDIA graphics card: install [nvidia-docker2](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/nvidia-docker.html). After installation, restart Docker and test with:
```bash
docker run --rm --gpus all nvidia/cuda:12.4.1-base nvidia-smi
```
Note: If you run Mobipick Labs on the CPU, the simulation will be very slow.
## Launching the GUI
1. Clone the repository *or* install the package from PyPI.
1. Start the application:
```bash
mobipick-labs-docker-gui
```
1. When the window opens, use the top row of buttons to bring up ROS core,
start or stop the simulator, toggle RViz/RQt, or open a Docker-backed
terminal. The GUI ensures the correct container sequence is followed.
You can interrupt the GUI with <kbd>Ctrl</kbd>+<kbd>C</kbd> in the launch
terminal; the application traps the signal, stops the running containers, and
then exits gracefully.
### Command-line options
The CLI accepts a single verbosity switch that controls how much diagnostic
information the GUI prints to its log tabs and the launch terminal:
```bash
mobipick-labs-docker-gui --verbose # Same as -v or --v
mobipick-labs-docker-gui -v 3 # Maximum verbosity
mobipick-labs-docker-gui -v 1 # Quietest mode (default)
```
You can also pass through any Qt-specific arguments (for example `-platform`)
after the GUI options; they are forwarded automatically to `QApplication`.
## Understanding the GUI workflow
* **Process supervision:** Each button spawns a `QProcess` that executes a
Docker command (`docker compose up`, `docker compose exec`, `docker cp`, etc.).
Environment variables from `mobipick_gui/resources/config/gui_settings.yaml` ensure the commands run
with consistent settings (for example `COMPOSE_IGNORE_ORPHANS=1`).
* **State polling:** Timers defined in `config/gui_settings.yaml` periodically
inspect Docker to reflect whether the ROS core, simulator, RViz, or RQt
containers are alive before updating the button states.
* **Log streaming:** Every subprocess pipes its stdout/stderr into a dedicated
tab, colourised via `mobipick_gui/ansi.py` so you can tail the container logs
without leaving the GUI.
* **Graceful shutdown:** When you exit, the GUI stops active containers in a
safe order, runs `clean.bash` (bundled in `mobipick_gui/resources/`) to remove
temporary resources, and only then closes the window.
## Configuring the GUI
All customisation lives in the `mobipick_gui/resources/config/` directory. You
can copy these files and adapt them to your workflow. When running from an
installed package the directory is read-only; export the environment variable
`MOBIPICK_GUI_DATA_ROOT` and point it at a writable copy of the resources if you
need to override the defaults.
* **`config/gui_settings.yaml`** – Controls UI behaviour such as window geometry
and log styling, defines timer intervals, button colours, terminal launcher
settings, and Docker environment variables. Most keys mirror the defaults
declared in `mobipick_gui/config.py` so you can override just the values you
need.
* **`config/worlds.yaml`** – Lists the world configurations that populate the
drop-down selector when launching the simulator. Edit or append entries to
expose additional Gazebo worlds shipped in your Mobipick Labs Docker image.
* **`config/docker_cp_image_tag.yaml`** – Declares optional `docker cp`
synchronisation rules keyed by image name. Host-to-container copies run
automatically after the container starts, while container-to-host copies are
triggered by the "Execute Docker cp" button inside the GUI.
## Working with the compose file
Although `docker-compose.yml` lives in the repository, the GUI is responsible for
translating user actions into compose commands. Typical sequences are:
1. **ROS core toggle:** `docker compose up roscore` starts the lightweight
orchestration container. The GUI remembers the container name and watches for
it to become healthy before enabling the simulator button.
2. **Simulator toggle:** `docker compose up mobipick-run` launches the main
Gazebo environment. When you stop it, the GUI optionally synchronises files
defined in `docker_cp_image_tag.yaml` and then calls `docker compose stop`
with a configurable timeout.
3. **Visualization tools:** RViz and RQt are launched with `docker compose run`
so each tool receives its own tabbed log stream.
Because the GUI tracks container state, you should avoid running the compose
file manually in parallel—it can confuse the state machine and lead to orphaned
containers. If you need a manual clean slate, run `mobipick_gui/resources/clean.bash`
with the GUI closed to remove stopped containers and networks.
## Tips and troubleshooting
* Verify that Docker commands succeed from your shell before launching the GUI;
it executes the same binaries with your current user.
* If the GUI cannot discover your Mobipick Labs image, adjust the
`images.discovery_filters` list in `mobipick_gui/resources/config/gui_settings.yaml`.
* When experimenting with new Gazebo worlds or launch files, consider adding a
custom button tab via `mobipick_gui/process_tab.py` so you can track logs in
the same window.
* Logs are retained up to `log.max_block_count` lines per tab. Lower the value
if you experience sluggishness on resource-constrained machines.
Raw data
{
"_id": null,
"home_page": null,
"name": "mobipick-labs-docker-gui",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mobipick, docker, gui, ros, simulation",
"author": "Mobipick Labs",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f0/d0/eddf1a75afed6969956f124599913a26bf246acc7e76a218bb3a39ac7c87/mobipick_labs_docker_gui-0.1.0.tar.gz",
"platform": null,
"description": "# Mobipick Labs Docker GUI\n\nThe Mobipick Labs Docker GUI is a PyQt5 desktop application that orchestrates the\nDocker-based Mobipick Labs robotics simulation. Instead of manually invoking\n`docker compose` yourself, you launch the `mobipick-labs-docker-gui` command (or\n`python -m mobipick_gui`) and drive the bring-up,\nmonitoring, and shutdown of the simulation through an interactive interface.\nThe GUI reads the bundled configuration files, runs Docker commands on your\nbehalf, and streams live logs so you can follow what is happening in each\ncontainer.\n\n<img src=\"doc/mobipick_labs_docker_gui.png\" alt=\"mobipick tables sim and real\" width=\"420\">\n\n## Repository layout\n\n```\n\u251c\u2500\u2500 gui.py # Legacy CLI shim that forwards to the packaged entry point\n\u251c\u2500\u2500 mobipick_gui/\n\u2502 \u251c\u2500\u2500 resources/ # Bundled compose file, default configs, helper scripts\n\u2502 \u2514\u2500\u2500 \u2026 # PyQt5 widgets, process orchestration, and helpers\n\u251c\u2500\u2500 MANIFEST.in # Source distribution manifest\n\u2514\u2500\u2500 pyproject.toml # Packaging metadata for PyPI distribution\n```\n\nThe compose file is **not** intended to be executed directly. The GUI manages it\nfor you by spawning `docker compose` subprocesses, supervising their lifecycle,\nand performing cleanup logic when you close the application.\n\n## Prerequisites\n\n* Ubuntu Linux (tested on versions 20.04, 22.04, and 24.04)\n* Python 3.8+ with PyQt5 available (e.g. `pip install PyQt5`).\n* Docker Engine and the Docker Compose plugin accessible to your user.\n* Access to the Mobipick Labs image repository (for example\n `ozkrelo/mobipick_labs:noetic`).\n* An X11 server that allows the containers to create GUI windows. The GUI\n issues the required `xhost` commands automatically when needed.\n\n## Installation\n\n- Install Docker Engine (`docker.io`) and ensure it is running.\n```bash\nsudo apt update && sudo apt install docker.io\nsudo systemctl enable docker\nsudo systemctl start docker\n```\n\n- Configure Docker to run without sudo:\n\n```bash\nsudo usermod -aG docker $USER\n```\n\nThen log out and back in.\n\n- Install the Mobipick Labs GUI from PyPI (this also installs the package dependencies):\n\n```bash\npip install mobipick-labs-docker-gui\n```\n\n- Install the Docker Compose plugin and pull the Mobipick Labs image.\n\n```bash\nsudo apt install docker-compose-plugin\n# Verify that the Compose plugin is available\ndocker compose version\n# pull mobipick labs docker image from docker hub\ndocker pull ozkrelo/mobipick_labs:noetic\n```\n\n- Optional but strongly recommended if you have an NVIDIA graphics card: install [nvidia-docker2](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/nvidia-docker.html). After installation, restart Docker and test with:\n\n```bash\ndocker run --rm --gpus all nvidia/cuda:12.4.1-base nvidia-smi\n```\n\nNote: If you run Mobipick Labs on the CPU, the simulation will be very slow.\n\n## Launching the GUI\n\n1. Clone the repository *or* install the package from PyPI.\n1. Start the application:\n ```bash\n mobipick-labs-docker-gui\n ```\n1. When the window opens, use the top row of buttons to bring up ROS core,\n start or stop the simulator, toggle RViz/RQt, or open a Docker-backed\n terminal. The GUI ensures the correct container sequence is followed.\n\nYou can interrupt the GUI with <kbd>Ctrl</kbd>+<kbd>C</kbd> in the launch\nterminal; the application traps the signal, stops the running containers, and\nthen exits gracefully.\n\n### Command-line options\n\nThe CLI accepts a single verbosity switch that controls how much diagnostic\ninformation the GUI prints to its log tabs and the launch terminal:\n\n```bash\nmobipick-labs-docker-gui --verbose # Same as -v or --v\nmobipick-labs-docker-gui -v 3 # Maximum verbosity\nmobipick-labs-docker-gui -v 1 # Quietest mode (default)\n```\n\nYou can also pass through any Qt-specific arguments (for example `-platform`)\nafter the GUI options; they are forwarded automatically to `QApplication`.\n\n## Understanding the GUI workflow\n\n* **Process supervision:** Each button spawns a `QProcess` that executes a\n Docker command (`docker compose up`, `docker compose exec`, `docker cp`, etc.).\n Environment variables from `mobipick_gui/resources/config/gui_settings.yaml` ensure the commands run\n with consistent settings (for example `COMPOSE_IGNORE_ORPHANS=1`).\n* **State polling:** Timers defined in `config/gui_settings.yaml` periodically\n inspect Docker to reflect whether the ROS core, simulator, RViz, or RQt\n containers are alive before updating the button states.\n* **Log streaming:** Every subprocess pipes its stdout/stderr into a dedicated\n tab, colourised via `mobipick_gui/ansi.py` so you can tail the container logs\n without leaving the GUI.\n* **Graceful shutdown:** When you exit, the GUI stops active containers in a\n safe order, runs `clean.bash` (bundled in `mobipick_gui/resources/`) to remove\n temporary resources, and only then closes the window.\n\n## Configuring the GUI\n\nAll customisation lives in the `mobipick_gui/resources/config/` directory. You\ncan copy these files and adapt them to your workflow. When running from an\ninstalled package the directory is read-only; export the environment variable\n`MOBIPICK_GUI_DATA_ROOT` and point it at a writable copy of the resources if you\nneed to override the defaults.\n\n* **`config/gui_settings.yaml`** \u2013 Controls UI behaviour such as window geometry\n and log styling, defines timer intervals, button colours, terminal launcher\n settings, and Docker environment variables. Most keys mirror the defaults\n declared in `mobipick_gui/config.py` so you can override just the values you\n need.\n* **`config/worlds.yaml`** \u2013 Lists the world configurations that populate the\n drop-down selector when launching the simulator. Edit or append entries to\n expose additional Gazebo worlds shipped in your Mobipick Labs Docker image.\n* **`config/docker_cp_image_tag.yaml`** \u2013 Declares optional `docker cp`\n synchronisation rules keyed by image name. Host-to-container copies run\n automatically after the container starts, while container-to-host copies are\n triggered by the \"Execute Docker cp\" button inside the GUI.\n\n## Working with the compose file\n\nAlthough `docker-compose.yml` lives in the repository, the GUI is responsible for\ntranslating user actions into compose commands. Typical sequences are:\n\n1. **ROS core toggle:** `docker compose up roscore` starts the lightweight\n orchestration container. The GUI remembers the container name and watches for\n it to become healthy before enabling the simulator button.\n2. **Simulator toggle:** `docker compose up mobipick-run` launches the main\n Gazebo environment. When you stop it, the GUI optionally synchronises files\n defined in `docker_cp_image_tag.yaml` and then calls `docker compose stop`\n with a configurable timeout.\n3. **Visualization tools:** RViz and RQt are launched with `docker compose run`\n so each tool receives its own tabbed log stream.\n\nBecause the GUI tracks container state, you should avoid running the compose\nfile manually in parallel\u2014it can confuse the state machine and lead to orphaned\ncontainers. If you need a manual clean slate, run `mobipick_gui/resources/clean.bash`\nwith the GUI closed to remove stopped containers and networks.\n\n## Tips and troubleshooting\n\n* Verify that Docker commands succeed from your shell before launching the GUI;\n it executes the same binaries with your current user.\n* If the GUI cannot discover your Mobipick Labs image, adjust the\n `images.discovery_filters` list in `mobipick_gui/resources/config/gui_settings.yaml`.\n* When experimenting with new Gazebo worlds or launch files, consider adding a\n custom button tab via `mobipick_gui/process_tab.py` so you can track logs in\n the same window.\n* Logs are retained up to `log.max_block_count` lines per tab. Lower the value\n if you experience sluggishness on resource-constrained machines.\n",
"bugtrack_url": null,
"license": "Proprietary",
"summary": "PyQt5 desktop controller for the Mobipick Labs Docker simulation",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/openai/mobipick_labs_docker_gui"
},
"split_keywords": [
"mobipick",
" docker",
" gui",
" ros",
" simulation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c0a9b5061ba3d2d816cff412767693d364e37b527a3588eac1b4be0fc5d1374e",
"md5": "b8d259ce620ea8fe15f534cf9425d769",
"sha256": "11df3c3afd3047829d706af4dd0d671cddda0a8f00c55511965448f2538b1d42"
},
"downloads": -1,
"filename": "mobipick_labs_docker_gui-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b8d259ce620ea8fe15f534cf9425d769",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 43274,
"upload_time": "2025-10-21T13:46:57",
"upload_time_iso_8601": "2025-10-21T13:46:57.634944Z",
"url": "https://files.pythonhosted.org/packages/c0/a9/b5061ba3d2d816cff412767693d364e37b527a3588eac1b4be0fc5d1374e/mobipick_labs_docker_gui-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f0d0eddf1a75afed6969956f124599913a26bf246acc7e76a218bb3a39ac7c87",
"md5": "8a06c46722202ce171986265290c194a",
"sha256": "5d428806aa09422138bb08d538110d9359c39ce526231dc99d249500513445c9"
},
"downloads": -1,
"filename": "mobipick_labs_docker_gui-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "8a06c46722202ce171986265290c194a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 42627,
"upload_time": "2025-10-21T13:46:58",
"upload_time_iso_8601": "2025-10-21T13:46:58.831942Z",
"url": "https://files.pythonhosted.org/packages/f0/d0/eddf1a75afed6969956f124599913a26bf246acc7e76a218bb3a39ac7c87/mobipick_labs_docker_gui-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 13:46:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openai",
"github_project": "mobipick_labs_docker_gui",
"github_not_found": true,
"lcname": "mobipick-labs-docker-gui"
}
JSON
