From 0821b1013eb5b790ddaeaffd46cd86ffb6c49ea1 Mon Sep 17 00:00:00 2001 From: DeeJanuz <45082401+DeeJanuz@users.noreply.github.com> Date: Mon, 5 Oct 2026 16:54:03 -0600 Subject: [PATCH] Settings: HANDS_SWAP_SIDES defaults to auto, and old untouched configs move to it frametop.conf.example said HANDS_SWAP_SIDES=0, and desktops.sh copies it on a fresh install, so every new install forced ft-camd's side camera names and turned the hand tracker's own side check off. Some SteamVR restarts swap those names, and then hands land beside their cutouts and recordings are mislabelled. The example now says auto. scripts/conf-migrate.sh, run by install.sh and hands/rec/install.sh, replaces the old line only where it's still exactly as the example wrote it. Co-Authored-By: Claude Opus 5.5 --- docs/reference.md | 2 +- hands/README.md | 2 +- hands/rec/install.sh | 1 + install.sh | 1 + scripts/conf-migrate.sh | 25 +++++++++++++++++++++++++ session/frametop.conf.example | 2 +- 6 files changed, 30 insertions(+), 3 deletions(-) create mode 100755 scripts/conf-migrate.sh diff --git a/docs/reference.md b/docs/reference.md index e84b47c..7a69a46 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -263,7 +263,7 @@ Your hands show over the screens: where a tracked hand is between an eye and a s - `ft-camd` borrows XRService's camera buffers and publishes the four IR tracking cameras to `/run/user/UID/frametop-hands/cam-ring`. It runs on the host as `frametop-camd.service`, with file capabilities that `hands/run.sh install` sets through sudo, and it drops them once set up. A rebuild clears them: `hands/run.sh caps`. - `ft-hands` runs in the `dev` container as `frametop-hands.service`. It finds and triangulates the hands, and publishes `hands` (read by ft-screens' cutouts) and `gestures` (pinches and grips, read by the pointer helper) next to the ring. - The install leaves both off, and they don't start with SteamVR. `ft-handsctl on` starts them while SteamVR runs, and `ft-handsctl off` stops them; they also stop with SteamVR. The install links `ft-handsctl` into `~/.local/bin`. `ft-handsctl status` and `ft-handsctl log` (or `hands/run.sh status` and `log`) show how they're doing, `ft-handsctl cutouts on|off` turns just the cutouts off, and `ft-handsctl gestures` shows pinches and grips live. -- Settings in `~/.config/frametop.conf`: `HANDS_SWAP_SIDES` (after some SteamVR restarts the side cameras' names come out swapped, and hands land beside the holes; `hands/tools/check_sides.py --ring` tells), `HANDS_CPUS`, the cameras it tracks with (`HANDS_CAMERAS`, `HANDS_BRIGHT`, `HANDS_BRIGHT_ON`, `HANDS_BRIGHT_OFF`, `HANDS_COLOR_LEFT`, `HANDS_COLOR_CROP`), and the pointer helper's `POINTER_HANDS`, `POINTER_PINCH_GAIN`, `POINTER_PINCH_DEADZONE`, `POINTER_GRIP_GAIN`, `POINTER_GRIP_BELOW`, and `POINTER_PINCH_TYPING`. The example config explains each. +- Settings in `~/.config/frametop.conf`: `HANDS_SWAP_SIDES` (`auto`, the default: ft-hands tells from the hands when some SteamVR restart has swapped the side cameras' names, and fixes them; `0` or `1` force them, and `hands/tools/check_sides.py --ring` tells which is right), `HANDS_CPUS`, the cameras it tracks with (`HANDS_CAMERAS`, `HANDS_BRIGHT`, `HANDS_BRIGHT_ON`, `HANDS_BRIGHT_OFF`, `HANDS_COLOR_LEFT`, `HANDS_COLOR_CROP`), and the pointer helper's `POINTER_HANDS`, `POINTER_PINCH_GAIN`, `POINTER_PINCH_DEADZONE`, `POINTER_GRIP_GAIN`, `POINTER_GRIP_BELOW`, and `POINTER_PINCH_TYPING`. The example config explains each. Details, options, and the recording and replay tools are in [hands/README.md](../hands/README.md). diff --git a/hands/README.md b/hands/README.md index 5b84901..fd6a9bc 100644 --- a/hands/README.md +++ b/hands/README.md @@ -36,7 +36,7 @@ hands/run.sh uninstall Settings in `~/.config/frametop.conf` (`FT_` in the environment overrides them), read when ft-camd and ft-hands start: -- `HANDS_SWAP_SIDES=auto` (the default): ft-hands tells from the hands which side camera is which, and corrects ft-camd's names when they're backwards (see "Which camera is which" below). `1` forces them exchanged and `0` forces ft-camd's names; ft-hands still checks and logs a warning if the hands disagree. +- `HANDS_SWAP_SIDES=auto` (the default): ft-hands tells from the hands which side camera is which, and corrects ft-camd's names when they're backwards (see "Which camera is which" below). `1` forces them exchanged and `0` forces ft-camd's names; ft-hands still checks, and if the hands disagree it logs a warning and publishes the hands' answer as the truth (`sides.json`), so recordings are labelled right. The example config said `0` until 2026-10-05; `scripts/conf-migrate.sh` (run by `install.sh` and `hands/rec/install.sh`) turns that untouched line into `auto`. - `HANDS_CPUS=5,6,7`: the CPUs the model threads run on (below). - `HANDS_CAMERAS` (`auto`), `HANDS_BRIGHT` (`all`), `HANDS_BRIGHT_ON` (40), `HANDS_BRIGHT_OFF` (25): which cameras ft-hands tracks with, as `--cams`, `--bright`, `--bright-on` and `--bright-off` (see ft-hands). `HANDS_CAMERAS=mono` also keeps ft-camd off the colour cameras. - `HANDS_COLOR_LEFT` (`color_video0`), `HANDS_COLOR_CROP` (`subtract`): how the colour module's calibration maps onto its images, as `--color-left` and `--color-crop`. diff --git a/hands/rec/install.sh b/hands/rec/install.sh index 92a1c0d..22da7be 100755 --- a/hands/rec/install.sh +++ b/hands/rec/install.sh @@ -23,6 +23,7 @@ case ${1:-install} in "$root/hands/rec/build.sh" echo "== 4/4 ft-camd's capabilities (asks for your password) and the menu entry" "$root/hands/run.sh" caps + "$root/scripts/conf-migrate.sh" # HANDS_SWAP_SIDES=0, the old default, becomes auto fill_template "$root/hands/rec/ft-handrec.desktop" | on_frame "mkdir -p ~/.local/share/applications && cat > $entry" echo diff --git a/install.sh b/install.sh index 9c0775e..eb04347 100755 --- a/install.sh +++ b/install.sh @@ -93,6 +93,7 @@ step "7/10 multi-screen desktop (ft-screens), Frametop Input Settings, and Frame "$root/remote/install.sh" on_frame "sed -i 's/^POINTER=0/POINTER=1/' ~/.config/frametop.conf; grep -q '^POINTER=' ~/.config/frametop.conf || echo 'POINTER=1' >> ~/.config/frametop.conf" echo "the launcher's Desktop entry now opens the multi-screen desktop; 3D mouse on (POINTER=1 in ~/.config/frametop.conf)" +"$root/scripts/conf-migrate.sh" step "8/10 gaze mode (optional, experimental: the pointer goes where you look)" gaze=0 diff --git a/scripts/conf-migrate.sh b/scripts/conf-migrate.sh new file mode 100755 index 0000000..b1d4acc --- /dev/null +++ b/scripts/conf-migrate.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash +# Update the lines of ~/.config/frametop.conf that still read exactly as an older +# frametop.conf.example wrote them. A line you changed stays as it is. install.sh and +# hands/rec/install.sh run this on every install and update. +# HANDS_SWAP_SIDES=0: the example's value until 2026-10-05. It made ft-hands keep ft-camd's side +# camera names even when they're backwards (some SteamVR restarts swap them), so hands landed +# beside their cutouts and the hand recorder labelled the side cameras wrong. auto tells from +# the hands. +set -euo pipefail +root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +. "$root/scripts/_env.sh" + +on_frame_script <<'EOF' +f=~/.config/frametop.conf +[ -f "$f" ] || exit 0 +old="HANDS_SWAP_SIDES=0 # hand tracking (hands/run.sh install): 1 = the side cameras' names are swapped, which some SteamVR restarts cause (hands/tools/check_sides.py --ring tells)" +new="HANDS_SWAP_SIDES=auto # hand tracking: which side camera is which. auto = ft-hands tells from the hands and fixes ft-camd's names, which some SteamVR restarts swap | 0 = keep ft-camd's | 1 = exchange them" +if grep -qxF "$old" "$f"; then + tmp=$(mktemp) + awk -v old="$old" -v new="$new" '$0 == old { print new; next } { print }' "$f" > "$tmp" + cat "$tmp" > "$f" # in place: the file keeps its owner and mode + rm -f "$tmp" + echo "settings: HANDS_SWAP_SIDES=0 (the old default) is now auto: hand tracking tells the side cameras apart itself" +fi +EOF diff --git a/session/frametop.conf.example b/session/frametop.conf.example index 1886482..4250a0d 100644 --- a/session/frametop.conf.example +++ b/session/frametop.conf.example @@ -40,7 +40,7 @@ POINTER_HEAD_DEADZONE=0.5 # keyboard clicks at the gaze (Meta+J, Meta+K): degre POINTER_KEY_TAP=0.25 # keyboard clicks: let go within this (s) and it clicks where the dot was at the press, and tells the gaze tracker it was right GAZE_TRACKER=auto # gaze service: auto = our own eye tracker when it's installed (gaze/tracker/install.sh, which install.sh offers), else SteamVR's | own = ours | steam = SteamVR's. Each keeps its own calibration (Calibrate on Frametop Input Settings' Gaze page) GAZE_EYE=auto # gaze service: eye bias. auto = each eye weighted by how far off it was at your recent nudges | left | right = that eye counts twice -HANDS_SWAP_SIDES=0 # hand tracking (hands/run.sh install): 1 = the side cameras' names are swapped, which some SteamVR restarts cause (hands/tools/check_sides.py --ring tells) +HANDS_SWAP_SIDES=auto # hand tracking: which side camera is which. auto = ft-hands tells from the hands and fixes ft-camd's names, which some SteamVR restarts swap | 0 = keep ft-camd's | 1 = exchange them HANDS_CPUS=5,6,7 # hand tracking: the CPUs its model threads run on HANDS_CAMERAS=auto # hand tracking: auto (by the light) | mono (the IR cameras; also keeps ft-camd off the colour ones) | color | all HANDS_BRIGHT=all # hand tracking, auto: the cameras in bright light, all | color