Skip to content

Setup

System requirements

  • Ubuntu 20.04+ (tested target)
  • Kinect for Windows v1 + USB power adapter
  • Python 3.10+
  • Enough disk space for RGB-D captures (hundreds of MB per session)

Cross-platform note

The GUI runs on Linux, Windows, and macOS via Tkinter. Kinect v1 capture is primarily supported on Linux through libfreenect. On other systems you can still use reconstruction and measurement if you already have datasets.

Packaging note

See docs/PACKAGING.md for creating desktop bundles on Linux/Windows/macOS.

  • VXB 8-inch motorized display stand (USB or battery powered, ~16s per rotation, 7 lb capacity).

System packages

Install libfreenect and Python bindings: 

sudo apt install libfreenect-dev
# Ubuntu 20.04 to 22.04:
sudo apt install python3-freenect || true

Ubuntu 24.04+ removed python3-freenect from apt. ./setup and ./install now fall back to pip install freenect==0.1.0, which provides a Linux wheel for Python 3.12 and links against system libfreenect.

GUI package (optional): 

sudo apt install python3-tk

Recommended full install (Ubuntu): 

sudo apt update
sudo apt install -y libfreenect-dev python3-tk \
  build-essential pkg-config cmake
# Ubuntu 20.04 to 22.04:
sudo apt install -y python3-freenect || true

./install on Ubuntu performs the same dependency install by default. If python3-freenect is unavailable, ./setup and ./install install freenect==0.1.0 from PyPI into target venv instead. Use ./install --no-system-deps if you want to skip apt installs.

Ubuntu 24.04+ Kinect v1 path: 

./setup

USB permissions (udev)

If the Kinect opens only with sudo, install udev rules: 

./scripts/install_udev_rules.sh
Then unplug/replug the Kinect (or reboot).

The script auto-detects the connected Kinect USB IDs. If the device is not plugged in, rerun after connecting it or use: 

./scripts/install_udev_rules.sh --fallback-known

If you want to access the Kinect without sudo, you may need udev rules for the device. Refer to your distro's libfreenect package documentation for recommended rules.

Python environment

./update
./setup
python -m venv venv && source venv/bin/activate
pip install -e .[dev]

Verify hardware

python -m kinect_forge status

Launch GUI with the system venv (recommended when installed via ./install): 

./gui

Capture presets: 

# small objects (pots, keychains)
Capture preset: small-object

# faces (steady pose, good lighting)
Capture preset: face-scan

CLI example: 

python -m kinect_forge capture --capture-preset small-object --output captures

Preset configuration lives in src/kinect_forge/presets.json and is installed with the package. You can override with: 

export KINECT_FORGE_PRESETS=/path/to/presets.json

Tilt control (up/down only)

Kinect v1 supports tilt up/down (no left/right). Use: 

python -m kinect_forge tilt --angle 10

Tilt works while frames are streaming (live preview, tilt sweep), through libfreenect's sync API.

Kinect for Windows (USB ID 045e:02bf) and Xbox model 1473 route the motor and accelerometer through the audio device. When libfreenect cannot open that device it prints Could not open audio: <error code>, the accelerometer reads 0,0,0 and the motor does not move; the usual cause is that the audio firmware (audios.bin) is not installed. kinect-forge detects this and reports it: tilt exits with code 1 and capture logs a warning instead of claiming the tilt worked. Capture itself is unaffected. The firmware is Microsoft's and is not shipped here; libfreenect's fwfetcher.py and its README describe how to fetch and install it.

Tilt sweep during capture (CLI): 

python -m kinect_forge capture --capture-preset face-scan --tilt-sweep \
  --tilt-min -10 --tilt-max 10 --tilt-step 5 --tilt-hold-frames 30

Kinect live feed test (dev tool): 

./scripts/test_kinect.sh --list
./scripts/test_kinect.sh --index 0
./scripts/test_kinect.sh --index 0 --depth

End-to-end test (CLI)

Capture → preview → reconstruct → measure. 

python -m kinect_forge capture --output scans/test --frames 180 --mode turntable --fps 5 \
  --auto-stop --depth-min 0.4 --depth-max 1.2 --turntable-preset vxb-8

python -m kinect_forge view --dataset scans/test --every 10

python -m kinect_forge reconstruct --input-dir scans/test --output-mesh scans/test/model.glb \
  --preset small --icp --smooth 8 --fill-hole-radius 0.01

python -m kinect_forge measure --mesh scans/test/model.glb

End-to-end test (GUI)

python -m kinect_forge gui
Steps: 1) Status tab → Check Status. 2) Capture tab → Start Capture. 3) View tab → Open Viewer. 4) Reconstruct tab → Reconstruct. 5) Measure tab → Measure.

Optional calibration (better scale accuracy)

python -m kinect_forge calibrate --images calib/*.png --rows 7 --cols 9 --square-size 0.025 \
  --output intrinsics.json

python -m kinect_forge capture --output scans/calibrated --frames 200 --intrinsics-path intrinsics.json

Local checks

./lint
./test