Make hand tracking a Frametop component

- Programs: ft-camd (the camera broker), ft-hands (the tracker), and
  ft-handreplay and ft-ringplay for recordings, built by hands/build.sh
  into hands/build/ with one Makefile. The first build fetches ncnn at
  frame-hands' pinned tag and builds it with the same options.
- ft-camd gets its privileges from file capabilities (CAP_SYS_PTRACE,
  CAP_PERFMON, CAP_DAC_READ_SEARCH) that hands/run.sh install sets with
  sudo, and drops them once set up. It still works under sudo. It runs
  on the host, linked statically, as frametop-camd.service. ft-hands
  runs in the dev container as frametop-hands.service. Both start and
  stop with SteamVR.
- Files move to /run/user/UID/frametop/ (cam-ring, hands, gestures),
  not $XDG_RUNTIME_DIR, which a terminal in the Frametop desktop has
  its own of. SIGUSR1 recordings go to ~/.local/share/frametop/hands.
- The calibration is read through /run/host in the container.
- Settings: HANDS_SWAP_SIDES and HANDS_CPUS in frametop.conf.
- install.sh offers hand tracking as an optional last step.
- The container gets jsoncpp-devel, glibc-static, and NumPy and OpenCV
  for the Python tools.
- tools/ring.py reads the ring, and models/NOTICE credits the
  Apache-2.0 models.

Checked: ft-handreplay gives identical summaries and byte-identical
depth dumps to frame-hands' fh-replay on both 2026-09-29 recordings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DeeJanuzandClaude Opus 5.5 committed 2026-09-30 09:15:07 -06:00
1 parent 3e3d31c728
commit 499035216c
41 files changed
+727 -402

No files matched your search

+7 -7
View File
@@ -1,11 +1,11 @@
// fh-ringplay: play a recording (fh-tracker --record) into a frame ring in real time, the
// way fh-camd publishes live cameras, so fh-tracker --ring PATH processes the same frames
// run after run. For A/B tests of how the tracker runs (probes/core-ab.sh).
// ft-ringplay: play a recording (ft-hands --record) into a frame ring in real time, the
// way ft-camd publishes live cameras, so ft-hands --ring PATH processes the same frames
// run after run. For A/B tests of how the tracker runs.
//
// fh-ringplay DIR --ring PATH [--from S] [--to S] [--loop] [--cpus 0,1]
// ft-ringplay DIR --ring PATH [--from S] [--to S] [--loop] [--cpus 0,1]
//
// Frames are stamped as they're published, so the tracker's latency figures stay
// meaningful. Cameras carry their calibration name and no device node (fh-tracker maps
// meaningful. Cameras carry their calibration name and no device node (ft-hands maps
// them by name), so a recording made with the right names needs no --swap-sides.
// Dark frames (<name>_dk) are skipped. Needs no root: the ring is an ordinary file.
#include "record.h"
@@ -139,7 +139,7 @@ int main(int argc, char **argv) {
while (have && set_time(cams) - rec0 < from && !g_stop) have = in.next(cams, px, want);
if (!have) return std::fprintf(stderr, "%s: nothing after %.1f s\n", dir.c_str(), from), 1;
// the ring: the recording's bright cameras, as fh-camd lays them out
// the ring: the recording's bright cameras, as ft-camd lays them out
std::vector<int> pub; // set camera index of each ring camera
for (size_t k = 0; k < cams.size() && pub.size() < FH_RING_MAX_CAMS; ++k)
if (!is_dark(cams[k].name)) pub.push_back(int(k));
@@ -162,7 +162,7 @@ int main(int argc, char **argv) {
for (size_t r = 0; r < pub.size(); ++r) {
const fh_set_cam_t &c = cams[pub[r]];
fh_ring_cam_t &rc = hdr->cams[r];
std::snprintf(rc.sensor, sizeof rc.sensor, "fh-ringplay");
std::snprintf(rc.sensor, sizeof rc.sensor, "ft-ringplay");
std::snprintf(rc.name, sizeof rc.name, "%s", c.name);
rc.node = -1;
rc.format = FH_FMT_GREY8;