A mobile application combining computer vision and machine learning to detect pool tables, locate ball positions, and map them onto ShotStudio-style overlays.

This project was derived from the pix2pockets dataset and research as a starting point for ball detection training.

Tableizer consists of three main components:

1. Native C++ Vision Engine (lib/) - Core detection and image processing with ONNX Runtime
2. Flutter Mobile App (app/) - iOS and Android real-time capture interface
3. Python Tooling (python/) - Model training, dataset transforms, and debugging utilities

tableizer/
├── app/                    # Flutter mobile application
│   ├── lib/               # Dart source code
│   │   ├── controllers/   # Business logic controllers
│   │   ├── models/        # Data structures
│   │   ├── screens/       # UI screens
│   │   ├── services/      # FFI services and detection logic
│   │   └── widgets/       # Reusable UI components
│   ├── ios/               # iOS native configuration
│   ├── android/           # Android native configuration
│   └── assets/            # App assets (models, images)
├── lib/                    # C++ native library
│   ├── src/               # Source files
│   ├── include/           # Header files
│   ├── libs/              # Dependencies (OpenCV, ONNX Runtime)
│   ├── build_ios.sh       # iOS build script
│   └── build_android.sh   # Android build script
├── python/                 # Python tooling
├── tableizer/              # Trained YOLO models
└── data/                   # Datasets and training images

• Flutter SDK >= 3.8.1
• CMake >= 3.10
• Ninja build system (for OpenCV builds)

• Xcode >= 15.0 (with command line tools)
• CocoaPods (sudo gem install cocoapods)
• Homebrew with opencv and onnxruntime installed

• Android Studio with NDK installed
• Android NDK r29+ (set ANDROID_NDK_HOME environment variable)
• Android SDK with platform 24+

• Python 3.10+
• Virtual environment recommended

The Flutter app requires pre-built native libraries for table and ball detection.

cd lib

# Build OpenCV and Tableizer for iOS (device + simulator)
./build_ios.sh

This script:

• Builds OpenCV static libraries for iOS device (arm64) and simulator
• Builds the libtableizer_lib.dylib shared library
• Copies libraries to app/ios/

Output files:

• app/ios/libtableizer_lib.dylib (device, default)
• app/ios/libtableizer_lib_device.dylib
• app/ios/libtableizer_lib_sim.dylib

# Set the NDK path (adjust version as needed)
export ANDROID_NDK_HOME=$ANDROID_SDK_ROOT/ndk/29.0.13599879

cd lib

# Build OpenCV and Tableizer for Android
./build_android.sh

This script:

• Builds OpenCV shared libraries for Android (arm64-v8a)
• Builds libtableizer_lib.so
• Copies all .so files to app/android/app/src/main/jniLibs/arm64-v8a/

Required libraries in jniLibs:

• libtableizer_lib.so
• libopencv_*.so (core, imgproc, dnn, etc.)
• libonnxruntime.so

cd app

# Get Flutter packages
flutter pub get

cd app/ios

# Install CocoaPods dependencies (includes ONNX Runtime)
pod install

Important: The iOS build uses ONNX Runtime from CocoaPods (pod 'onnxruntime-c').

cd app
flutter run -d <ios-device-id>

Or build for release:

flutter build ios --release

For simulator, configure the app to use the simulator library:

1. The library loader in app/lib/native/library_loader.dart handles device vs simulator detection
2. Ensure libtableizer_lib_sim.dylib is available in app/ios/

flutter run -d <ios-simulator-id>

cd app
flutter run -d <android-device-id>

Or build APK:

flutter build apk --debug
# or
flutter build apk --release

cd lib
mkdir build && cd build
cmake ..
make

This creates:

• tableizer_app - CLI executable for testing
• libtableizer_lib.a - Static library

cd lib/build
ctest

The native library exposes these functions for Flutter FFI:

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Train a new YOLO model using model_table.py:

1. Edit the CONFIG dict in model_table.py to point to your local dataset:

   CONFIG = {
       "srcImgDir": "data/my_dataset/images",  # Your images
       "srcLblDir": "data/my_dataset/labels",  # Your YOLO labels
       ...
   }

2. Run training:

   cd python
   python model_table.py

Export trained model to ONNX for mobile deployment:

yolo export model=tableizer/expN/weights/best.pt format=onnx device=cpu imgsz=1280 simplify=True dynamic=False opset=17 half=False

# Copy to Flutter app
cp tableizer/expN/weights/best.onnx ../app/assets/detection_model.onnx

Trained models are stored in tableizer/ (current production model: combined4).

See python/README.md for detailed training instructions.

Camera Frame (CameraAwesome)
    ↓
TableDetectionController.processImage()
    ↓
TableDetectionService → Isolate
    ↓
[C++ FFI] detect_table_bgra()
    ├── Table Detection (color analysis, contours)
    ├── Quad Analysis (orientation detection)
    └── Image Normalization (perspective transform)
    ↓
BallDetectionController.detectBalls()
    ↓
[C++ FFI] detect_balls_bgra() + YOLO inference
    ↓
TableResultsScreen (visualization)

Flutter:

• camerawesome - Live camera feed
• permission_handler - Camera permissions
• wakelock_plus - Keep screen on

C++:

• OpenCV - Image processing
• ONNX Runtime - YOLO inference

• Hold phone in landscape orientation (16:9 aspect ratio) for best detection
• Ensure adequate lighting on the pool table
• Position camera to capture entire table surface

• Some modules contain hard-coded absolute paths (see todo.md)
• Frame rate depends on image resolution
• 45-degree camera angles may affect orientation detection

Private project - not for redistribution.