Junhyeok Lee

Applies to v0.1.0.

Environment

The Python-side tools (the dataset collector and the validator) need a few packages. Set up an isolated virtual environment (venv) once and install into it. ROS needs one extra flag; that's below too.

Get the code

The example scripts, the requirements file, and the Dockerfiles all live in the Nano-sim repository. Clone it once. The simulator binary itself is a separate download.

git clone https://github.com/Hyeokk/Nano-sim.git
cd Nano-sim
  • examples/python_api/drive_keyboard.py — teleop over the Python API, stdlib only.
  • examples/ros1/nanosim_teleop_ros1.py — teleop over ROS 1, needs rospy.
  • examples/ros2/nanosim_teleop_ros2.py — teleop over ROS 2, needs rclpy.
  • examples/collect_dataset/ — collector, label helper, validator; needs the venv below.

How the teleop scripts behave

All three share the same terminal contract, so it is worth reading once rather than per transport.

  • Commands are latched— each press moves the value one step and it stays there. A terminal has no key-release event, and hold-to-drive would inherit the keyboard's ~0.5 s auto-repeat delay, which makes the car stutter.
  • The bottom two lines are pinned while log lines scroll above them.
  • POSIX only, and they need a real TTY — they read keys without Enter, so a redirected stdin exits immediately.
  • None of them hardcode a vehicle limit — each asks the simulator and prints what it got. Vehicle control explains why that matters.

Create the environment

From the repo root, once:

python3 -m venv nanovenv
source nanovenv/bin/activate        # macOS / Linux   (Windows: nanovenv\Scripts\activate)
pip install -U pip
pip install -r requirements/python_api.txt

The env is named nanovenv (a plain, non-hidden folder) so it stays visible in the repo and is easy to manage. Re-activate it (source nanovenv/bin/activate) in any new shell before running the tools.

Confirm the venv is active before installing. pip -V should print a path inside nanovenv. If it shows a system path, activatedidn't take and you're about to install into the system Python.

What gets installed

  • numpy — get_frame_bin payloads, segmentation colour ↔ index, npz validation.
  • pillow — image I/O.
  • opencv-python — faster JPEG/PNG encode and decode at 1920×1080. Purely a speed win: the dataset scripts try OpenCV first and fall back to Pillow, so Pillow alone is a complete, working install.

The RL / training stack (torch, stable-baselines3, …) is deliberately kept out of this file so the environment stays light. Install it in a separate venv when you start on training.

ROS: create the venv with --system-site-packages

rospy and rclpyaren't on PyPI. They come from the system ROS install. The ROS teleop examples need only those, so they run in system Python with no venv at all. If you want a venv and ROS in the same process (say numpy alongside rclpy), source ROS first and pass --system-site-packages so the system ROS packages stay visible:

source /opt/ros/humble/setup.bash        # ROS 1: /opt/ros/noetic/setup.bash
python3 -m venv --system-site-packages nanovenv-ros
source nanovenv-ros/bin/activate
pip install -r requirements/python_api.txt

Without that flag the venv walls off the system site-packages and import rclpy fails immediately.

Keep it out of git

The repo's .gitignore doesn't cover the venv, so add it yourself:

echo "nanovenv/"     >> .gitignore
echo "nanovenv-ros/" >> .gitignore