Software setup

Development environment

  1. Install pixi package manager.

  2. Install sandbox:

mkdir -p ~/sarcam/ws/src
cd ~/sarcam/ws/src
git clone https://gitlab.com/sar-eye/HorizonScanner/
cd HorizonScanner
git lfs install && git lfs pull  # pull binary libs and training data
pixi run setup   # clone external repository deps (gscam, nmea_navsat_driver)

  1. Build the sandbox:

pixi run build   # builds the sarcam codebase and its ROS2 parts

Next: How to develop if you just want to run the system as a developer.

Experimental features

Note

Only recommended if you really know what you do!

Boat detection + Tracking

Everything in this section needs the ai environment — see How to develop.

pixi run -e ai export-engine ~/sarcam/models/yolov10s.pt --imgsz 1440x2560 -o ~/sarcam/models/yolov10s_1440x2560_fp16.engine

An engine is built for one input resolution, so every camera needs its own — the thermal is 1280x1024, so repeat with --imgsz 1024x1280. A mismatched engine is the usual cause of “the detector finds nothing”. Engines live in models_dir (~/sarcam/models) and are chosen per sensor by the model launch argument.

Tuning lives in src/sarcam_detector/README.md, which gives each parameter the measurement behind its value.

Zenoh shared memory (SHM)

scripts/pixi_ros_activate.sh enables rmw_zenoh’s SHM configs so ~11 MB camera frames pass locally without a per-subscriber copy. It skips SHM in CI, or when /dev/shm or ulimit -l is too small (nodes would abort with OS error 12).

Each node mlocks its own pool plus every peer pool it maps — (1 + peers) × pool, pool = 128 MB (~11 colour frames; an exhausted pool falls back to copying). Allow 1 GB per process:

  • systemd desktop: DefaultLimitMEMLOCK=1G in /etc/systemd/system.conf and /etc/systemd/user.conf, then reboot (limits.d is ignored).

  • SSH / TTY: /etc/security/limits.d/99-sarcam-rtprio.conf, then check ulimit -l:

sarcam  -  memlock  1048576  # 1 GB (own + seven 128 MB peer pools)
sarcam  -  rtprio   98       # optional: silences watchdog priority warnings
sarcam  -  nice    -20       # optional

Deployment on ship

Note

Following steps are not needed as a generic developer!

Ships run the deployment environment (see How to develop): the development environment, plus the detector and the camera driver. sarcam-main.sh selects it with pixi -e deployment, so a rig gets both without anyone having to remember a flag.

Building is the same pixi run build as anywhere else; only what is installed underneath it differs.

The deployment assumes following things:

  • a user called sarcam with a home directory.

  • repo cloned to /home/sarcam/sarcam/ws/src/HorizonScanner

Note

A software package for easy install will follow later.

Desktop icon

  1. Copy src/sarcam_bringup/script/sarcam-main.sh to /home/sarcam/sarcam/ws/sarcam-main.sh and adjust for your deployment needs.

Tip

You can e.g. adjust the recording path to a external harddisk.

bash src/sarcam_bringup/services/install-services.sh

Copies sarcam-main.desktop to ~/Desktop. Click it to launch the sarcam-main.sh script in a terminal.

Window taskbar icons

Each GTK UI window (RGB cam, Thermal cam, Virtual Gamepad) gets a distinct taskbar icon with an emoji overlay (🌈 / 🔥 / 🕹️). Run this once after a fresh clone, and again whenever the base icon (sarcam_ui/ui/images/icon.png) changes:

pixi run generate-icons

This installs composited PNGs into ~/.local/share/icons/hicolor/256x256/apps/ and matching .desktop files into ~/.local/share/applications/, then refreshes the GNOME icon cache. The UI nodes load the icons from there at startup; if the files are missing they fall back to the system default and log a warning.

Next: How to develop.