Real-time 3D scanning application using Kinect v1, volumetric TSDF reconstruction, and Unity-ready GLB export. Runs on Fedora 43 with optional CUDA acceleration.
- Live Kinect v1 capture via libfreenect (no OpenNI)
- High-Performance GPU Pipeline: Fully GPU-resident architecture optimized for NVIDIA RTX 30/40/50 series GPUs.
-
Image-Centric TSDF:
$O(W \times H)$ pixel-parallel integration for real-time fidelity. - Real-Time Super Resolution: CUDA-accelerated or OpenMP-parallelized AMD FidelityFX CAS filters for enhanced RGB clarity.
- GPU-Resident ICP: Multi-resolution tracking with block-reduced Hessian construction.
- Multi-Pass Marching Cubes: Parallel mesh extraction via CUDA/Thrust (< 2ms per scan).
- Navigation Gizmo: Blender-style interactive 3D axis gizmo for orientation control.
- OpenGL 3.3 real-time preview (point cloud + mesh modes)
- PLY (binary) and GLB (Unity-ready) export via tinygltf
- Qt5 GUI with live metrics panel
This guide covers the full setup for Fedora-based systems.
Install core development tools and library dependencies via dnf:
sudo dnf install -y \
cmake \
git \
ninja-build \
gcc-c++ \
qt5-qtbase-devel \
qt5-qtbase-gui \
libfreenect-devel \
eigen3-devel \
mesa-libGL-devel \
mesa-libGLU-devel \
libXrandr-devel \
libXi-devel \
libgomp \
pkgconf-pkg-configIf you have an NVIDIA GPU (RTX 30/40/50 series), install the CUDA toolkit:
sudo dnf install cudaEnsure /usr/local/cuda/bin is in your PATH.
git clone https://github.com/1vedantshinde/kinect_asset.git
cd kinect_asset
# Fetch bundled dependencies (tinygltf, stb)
bash scripts/fetch_deps.shConfigure udev rules to allow non-root access to the Kinect hardware:
# Copy and reload rules
sudo cp udev/99-kinect.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger
# Add your user to the plugdev group
sudo groupadd -f plugdev
sudo usermod -aG plugdev $USER
# NOTE: You must log out and back in for group changes to take effect!The build system uses CMake 3.18+ and is optimized for speed and reliability using Ninja and automated Qt tool handling (AUTOMOC).
mkdir build && cd build
# Recommended: Release build with Ninja
cmake .. -GNinja -DCMAKE_BUILD_TYPE=Release
ninja
# Alternative: Standard Make build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)Note: If you experience "undefined reference" errors after a git pull, it is highly recommended to perform a clean build (rm -rf build/*) to refresh the automated Qt metadata.
Note: The CMake configuration will output a diagnostic summary at the end of the cmake .. step, showing which features (CUDA, OpenMP, etc.) are enabled.
- Connect Kinect v1 via USB before launching the application.
- Launch the scanner:
QT_QPA_PLATFORM=xcb ./KinectFusionQt --verbose(from thebuilddirectory). - Click ▶ Start Capture — the pipeline will begin live tracking and volume integration.
- Scan: Move the Kinect slowly and steadily around your target object.
- View: Toggle between Point Cloud and Mesh modes to inspect quality in real-time.
- Navigate: Use Blender-like controls for inspection:
- LMB: Orbit around target.
- RMB + X/Y/Z: Axis-locked panning.
- Interactive Gizmo: Click and drag the XYZ gizmo in the bottom-right to rotate.
- Tab: Switch to Free Flight (WASD + Q/E to fly).
- F: Focus back on the origin.
- Export: Once satisfied, click Export PLY or Export GLB.
- Range: Maintain a distance of 0.3m to 2.5m for optimal depth precision (tunable via Depth min/max sliders).
- Lighting: Ensure consistent, non-flickering lighting for robust RGB-based ICP tracking.
- Volume: The default reconstruction cube is 2.56m. You can adjust the
originandvoxel_sizeininclude/tsdf/TSDFVolume.hfor smaller objects (e.g., setvoxel_sizeto 0.005 for 5mm precision). - Tracking Lost: If tracking is lost (indicated in the status panel), click Reset to clear the volume and start a new scan.
- Diagnostics: Start with
--verboseto see a detailed breakdown of tracking failures (correspondences, projections, filtering).
KinectFusionQt/
├── include/ # Header files (.h)
├── src/ # Implementation files (.cpp, .cu)
├── scripts/ # Dependency & utility scripts
├── third_party/ # External libraries (populated by fetch_deps.sh)
├── udev/ # Linux hardware rules
└── CMakeLists.txt # Main build configuration
Kinect HW
│
▼
KinectSensor (libfreenect, capture thread)
│ RawFrame (depth 11-bit + RGB 640×480)
▼
Preprocessor (Unified Backend: CPU/CUDA)
│ AMD FSR CAS Super Resolution + Denoising
▼
Pipeline (GPU Resident)
│
├──► Tracking ──────────► GPU ICP (Hessian reduction, pose-to-pose)
│ │ │ updated pose
│ └──────────────────────┤
│ ▼
└──► Integration ───────► Pixel-Parallel TSDF (CUDA)
│ │
│ Raycast (GPU) → ModelFrame (VRAM)
│
▼
Meshing Thread ──► GPU Marching Cubes (Thrust) ──► SharedMesh
│
┌──────┴──────┐
▼ ▼
PLYExporter GLBExporter
│
Unity-ready .glb
| Space | Axes | Notes |
|---|---|---|
| Kinect depth | X right, Y down, Z fwd | Right-handed |
| TSDF world | Same as Kinect at origin | Pose tracked via ICP |
| GLB export | X right, Y up, Z fwd | Right-handed (GLTF standard) |
| Unity import | X right, Y up, Z fwd | Left-handed (Z flipped auto) |
The GLBExporter applies Y → -Y to convert from Kinect Y-down to GLTF Y-up.
Unity's built-in GLTF importer then handles the right-to-left-handed flip automatically.
Scale is 1 unit = 1 metre throughout.
| Symptom | Fix |
|---|---|
| "No Kinect devices found" | Check udev rules; run lsusb to confirm device visible |
| Permission denied on USB | Add user to plugdev; re-login |
| Tracking immediately lost | Ensure scene has enough texture/geometry; reduce motion speed; Check --verbose logs for inliers and model_pts |
| Low FPS | Disable CUDA if GPU init fails; ensure Release build |
| GLB doesn't import to Unity | Ensure Unity 2019.4+ which includes built-in GLTF support, or use GLTFast package |
| Linker / Undefined Reference errors | Run rm -rf build/* and re-run cmake .. -GNinja to refresh Qt meta-object data |
| CUDA build fails | Check nvcc --version; set CMAKE_CUDA_ARCHITECTURES=86 for RTX 5070 |
MIT — see LICENSE file.