Add MoboleGaze model and update docs (#223)

Author: jamjamjon

.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Deploy MkDocs Documentation
+on:
+  push:
+    branches: [ main ]
+    paths: [ 'docs/**', 'mkdocs.yml' ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+        
+    - name: Install dependencies
+      run: |
+        pip install mkdocs-material pymdown-extensions
+        
+    - name: Build documentation
+      run: mkdocs build
+      
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

Cargo.toml

@@ -314,3 +314,8 @@ required-features = ["vision", "annotator"]
 name = "sapiens"
 path = "examples/sapiens/main.rs"
 required-features = ["vision", "annotator"]
+
+[[example]]
+name = "gaze-estimation"
+path = "examples/gaze-estimation/main.rs"
+required-features = ["vision", "annotator", "video"]

README.md

@@ -211,6 +211,15 @@ cargo run -r --example yolo -- --help
 
 </details>
 
+<details closed>
+<summary><b>👀 Gaze Estimation</b></summary>
+
+| Model | Task / Description | Demo | Dynamic Batch | TensorRT | FP32 | FP16 | Q8 | Q4f16 | BNB4 |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| [MobileGaze](https://github.com/yakhyo/gaze-estimation) | Eye Gaze Estimation | [demo](./examples/pose-estimation) | ✅ | ❓ |✅  | ✅  | ✅  | ✅  | ✅  |
+
+</details>
+
 <details closed>
 <summary><b>✂️ Image Matting & Portrait Segmentation</b></summary>
 

assets/gaze.png

@@ -0,0 +1,112 @@
+# Cargo Features
+
+**usls** is highly modular. Use feature flags to include only the models and hardware support you need, keeping your binary small and compilation fast.
+
+Features in ***italics*** are enabled by default.
+
+### Core & Utilities
+  - ***`ort-download-binaries`***: Automatically download prebuilt ONNX Runtime binaries from [pyke](https://ort.pyke.io/perf/execution-providers).
+  - **`ort-load-dynamic`**: Manually link ONNX Runtime. Useful for custom builds or unsupported platforms. See [Linking Guide](https://ort.pyke.io/setup/linking#static-linking) for more details.
+  - **`viewer`**: Real-time image/video visualization (similar to OpenCV `imshow`). Empowered by [minifb](https://github.com/emoon/rust_minifb).
+  - **`video`**: Video I/O support for reading and writing video streams. Empowered by [video-rs](https://github.com/oddity-ai/video-rs).
+  - **`hf-hub`**: Download model files from Hugging Face Hub.
+  - ***`annotator`***: Annotation utilities for drawing bounding boxes, keypoints, and masks on images.
+
+### Image Formats
+Additional image format support (optional for faster compilation):
+  
+  - **`image-all-formats`**: Enable all additional image formats.
+  - **`image-gif`**, **`image-bmp`**, **`image-ico`**, **`image-avif`**, **`image-tiff`**, **`image-dds`**, **`image-exr`**, **`image-ff`**, **`image-hdr`**, **`image-pnm`**, **`image-qoi`**, **`image-tga**: Individual image format support.
+
+### Model Categories
+  - ***`vision`***: Core vision models (Detection, Segmentation, Classification, Pose, etc.).
+  - **`vlm`**: Vision-Language Models (CLIP, BLIP, Florence2, etc.).
+  - **`mot`**: Multi-Object Tracking utilities.
+  - **`all-models`**: Enable all model categories.
+
+### Execution Providers
+Hardware acceleration for inference. Enable the one matching your hardware:
+
+  - **`cuda`**: NVIDIA CUDA execution provider (pure model inference acceleration).
+  - **`tensorrt`**: NVIDIA TensorRT execution provider (pure model inference acceleration).
+  - **`nvrtx`**: NVIDIA NvTensorRT-RTX execution provider (pure model inference acceleration).
+  - **`cuda-full`**: `cuda` + `cuda-runtime-build` (Model + Image Preprocessing acceleration).
+  - **`tensorrt-full`**: `tensorrt` + `cuda-runtime-build` (Model + Image Preprocessing acceleration).
+  - **`nvrtx-full`**: `nvrtx` + `cuda-runtime-build` (Model + Image Preprocessing acceleration).
+  - **`coreml`**: Apple Silicon (macOS/iOS).
+  - **`openvino`**: Intel CPU/GPU/VPU.
+  - **`onednn`**: Intel Deep Neural Network Library.
+  - **`directml`**: DirectML (Windows).
+  - **`webgpu`**: WebGPU (Web/Chrome).
+  - **`rocm`**: AMD GPU acceleration.
+  - **`cann`**: Huawei Ascend NPU.
+  - **`rknpu`**: Rockchip NPU.
+  - **`xnnpack`**: Mobile CPU optimization.
+  - **`acl`**: Arm Compute Library.
+  - **`armnn`**: Arm Neural Network SDK.
+  - **`azure`**: Azure ML execution provider.
+  - **`migraphx`**: AMD MIGraphX.
+  - **`nnapi`**: Android Neural Networks API.
+  - **`qnn`**: Qualcomm SNPE.
+  - **`tvm`**: Apache TVM.
+  - **`vitis`**: Xilinx Vitis AI.
+
+### CUDA Support
+NVIDIA GPU acceleration with CUDA image processing kernels (requires `cudarc`):
+
+  - **`cuda-full`**: Uses `cuda-version-from-build-system` (auto-detects via `nvcc`).
+  - **`cuda-11040`**, **`cuda-11050`**, **`cuda-11060`**, **`cuda-11070`**, **`cuda-11080`**: CUDA 11.x versions (Model + Preprocess).
+  - **`cuda-12000`**, **`cuda-12010`**, **`cuda-12020`**, **`cuda-12030`**, **`cuda-12040`**, **`cuda-12050`**, **`cuda-12060`**, **`cuda-12080`**, **`cuda-12090`**: CUDA 12.x versions (Model + Preprocess).
+  - **`cuda-13000`**, **`cuda-13010`**: CUDA 13.x versions (Model + Preprocess).
+
+### TensorRT Support
+NVIDIA TensorRT execution provider with CUDA runtime libraries:
+
+  - **`tensorrt-full`**: Uses `cuda-version-from-build-system` (auto-detects via `nvcc`).
+  - **`tensorrt-cuda-11040`**, **`tensorrt-cuda-11050`**, **`tensorrt-cuda-11060`**, **`tensorrt-cuda-11070`**, **`tensorrt-cuda-11080`**: TensorRT + CUDA 11.x runtime.
+  - **`tensorrt-cuda-12000`**, **`tensorrt-cuda-12010`**, **`tensorrt-cuda-12020`**, **`tensorrt-cuda-12030`**, **`tensorrt-cuda-12040`**, **`tensorrt-cuda-12050`**, **`tensorrt-cuda-12060`**, **`tensorrt-cuda-12080`**, **`tensorrt-cuda-12090`**: TensorRT + CUDA 12.x runtime.
+  - **`tensorrt-cuda-13000`**, **`tensorrt-cuda-13010`**: TensorRT + CUDA 13.x runtime.
+
+  > **Note**: `tensorrt-cuda-*` features enable **TensorRT execution provider** with CUDA runtime libraries for image processing. The "cuda" in the name refers to `cudarc` dependency.
+
+### NVRTX Support
+NVIDIA NvTensorRT-RTX execution provider with CUDA runtime libraries:
+
+  - **`nvrtx-full`**: Uses `cuda-version-from-build-system` (auto-detects via `nvcc`). 
+  - **`nvrtx-cuda-11040`**, **`nvrtx-cuda-11050`**, **`nvrtx-cuda-11060`**, **`nvrtx-cuda-11070`**, **`nvrtx-cuda-11080`**: NVRTX + CUDA 11.x runtime.
+  - **`nvrtx-cuda-12000`**, **`nvrtx-cuda-12010`**, **`nvrtx-cuda-12020`**, **`nvrtx-cuda-12030`**, **`nvrtx-cuda-12040`**, **`nvrtx-cuda-12050`**, **`nvrtx-cuda-12060`**, **`nvrtx-cuda-12080`**, **`nvrtx-cuda-12090`**: NVRTX + CUDA 12.x runtime.
+  - **`nvrtx-cuda-13000`**, **`nvrtx-cuda-13010`**: NVRTX + CUDA 13.x runtime.
+
+  > **Note**: `nvrtx-cuda-*` features enable **NVRTX execution provider** with CUDA runtime libraries for image processing. The "cuda" in the name refers to `cudarc` dependency.
+
+---
+
+## 🚀 Device Combination Guide
+
+| Scenario | Model Device (`--device`) | Processor Device (`--processor-device`) | Required Features (`-F`) |
+| :--- | :--- | :--- | :--- |
+| **CPU Only** | `cpu` | `cpu` | `vision` (default) |
+| **GPU Inference (Slow Preprocess)** | `cuda` | `cpu` | `cuda` |
+| **GPU Inference (Fast Preprocess)** | `cuda` | `cuda` | `cuda-full` or `cuda-120xxx` |
+| **TensorRT (Slow Preprocess)** | `tensorrt` | `cpu` | `tensorrt` |
+| **TensorRT (Fast Preprocess)** | `tensorrt` | `cuda` | `tensorrt-full` or `tensorrt-cuda-120xxx` |
+
+> ⚠️ In multi-GPU environments (e.g., `cuda:0`, `cuda:1`), you **MUST** ensure that both `--device` and `--processor-device` use the **SAME GPU ID**. 
+
+---
+
+## Common Pitfalls
+
+```toml
+# ❌ Don't mix multiple CUDA versions
+features = ["cuda-12040", "cuda-11080"]
+
+# ✅ Use one execution provider
+features = ["tensorrt-full"]
+
+# ✅ Use two execution provider: cuda EP + tensorrt EP + cuda image processing
+features = ["cuda-full", "tensorrt"]
+features = ["cuda", "tensorrt-full"]
+
+
+```

docs/cargo-features/overview.md

@@ -0,0 +1,46 @@
+# Contributing
+***TODO***
+
+<!-- 
+We welcome contributions to **usls**! Whether you're fixing bugs, adding new models, or improving documentation, your help is appreciated.
+## 🛠️ Development Setup
+
+1.  **Fork & Clone**:
+    ```bash
+    git clone https://github.com/your-username/usls.git
+    cd usls
+    ```
+
+2.  **Install Dependencies**: Ensure you have Rust (MSRV 1.87) and ONNX Runtime installed.
+
+3.  **Run Tests**:
+    ```bash
+    cargo test
+    ```
+
+## 🚀 Adding New Models
+
+If you'd like to contribute a new model to the Model Zoo:
+
+1.  **Logic**: Implement the model logic in `src/models/`.
+2.  **Config**: Add necessary configuration options in `src/config/`.
+3.  **Example**: Provide a working example in `examples/`.
+4.  **Documentation**: Update the corresponding page in `docs/model-zoo/`.
+
+## 📜 Coding Guidelines
+
+-   **Consistency**: Follow the existing naming conventions (e.g., `with_<module>_<field>` for configs).
+-   **Formatting**: Use `cargo fmt` before submitting a PR.
+-   **Linting**: Ensure `cargo clippy` passes without warnings.
+
+## 🤝 Pull Request Process
+
+1.  Create a new branch for your feature or bugfix.
+2.  Ensure all tests pass and documentation is updated.
+3.  Submit a PR with a clear description of the changes. -->
+
+---
+
+!!! info "Questions?"
+    If you're unsure where to start, feel free to open a [discussion](https://github.com/jamjamjon/usls/discussions) or join our community.
+

docs/contributing.md

@@ -0,0 +1,51 @@
+# FAQ
+
+***TODO***
+
+<!-- 
+
+Frequently asked questions about **usls**.
+## 🚀 General
+
+??? question "How do I install usls?"
+    Add usls to your `Cargo.toml`. See the [Installation](getting-started/installation.md) guide for details.
+
+??? question "What are the minimum requirements?"
+    - Rust 1.87+
+    - ONNX Runtime 1.22.0+
+    - (Optional) CUDA 11/12 or TensorRT 10 for GPU acceleration.
+
+## 🔧 Configuration
+
+??? question "CUDA vs. TensorRT?"
+    - **CUDA**: Easier setup, good flexibility.
+    - **TensorRT**: Maximum performance, requires an initial engine building step.
+
+??? question "Model Device vs. Processor Device?"
+    - **Model Device**: Where the neural network runs (Inference).
+    - **Processor Device**: Where image resizing and normalization happen (Preprocessing).
+
+## 🎯 Model Usage
+
+??? question "Can I use custom models?"
+    Yes, you can load any ONNX model using `Config::from_file("model.onnx")`.
+
+??? question "How do I optimize for speed?"
+    - Use `DType::Fp16`.
+    - Enable `TensorRT`.
+    - Use GPU preprocessing (`Device::Cuda(0)` for both model and processor).
+
+## 🐛 Troubleshooting
+
+??? question "CUDA not available error?"
+    Ensure you have the NVIDIA drivers and CUDA toolkit installed, and that you've enabled the `cuda` or `cuda-full` feature in your `Cargo.toml`.
+
+??? question "Out of Memory (OOM)?"
+    - Reduce the batch size.
+    - Use half-precision (`Fp16`).
+    - Use quantized models (`Q4`, `Q8`).
+
+--- -->
+
+!!! info "Still have questions?"
+    If you can't find what you're looking for, feel free to open a [GitHub Issue](https://github.com/jamjamjon/usls/issues).

docs/faq.md

@@ -0,0 +1,17 @@
+# Installation
+
+To use **usls** in your project, add it to your `Cargo.toml`.
+
+=== "Crates.io"
+
+    ```toml
+    [dependencies]
+    usls = { version = "latest-version", features = [ "cuda" ] }
+    ```
+
+=== "GitHub (Recommended)"
+
+    ```toml
+    [dependencies]
+    usls = { git = "https://github.com/jamjamjon/usls", branch = "main" }
+    ```

docs/getting-started/installation.md

@@ -0,0 +1,70 @@
+# Integration Workflow
+
+`usls` implements a clean, modular pipeline from data ingestion to results visualization.
+
+## The 4-Step Pipeline
+
+1.  **Configure Model**: Select a pre-configured model (e.g., `Config::rfdetr_nano()`), customize settings, and commit the configuration.
+2.  **Load Data**: Setup a `DataLoader` to handle your input sources (images, videos, etc.).
+3.  **Inference**: Iterate through the `DataLoader` and pass data to `model.run()` or `model.forward()`.
+4.  **Extract Results**: Access detections, masks, or embeddings from the unified `Y` output.
+5.  **Annotate (Optional)**: Use the `Annotator` to draw results back onto the original images.
+6.  **Visualize (Optional)**: Use the `Viewer` for real-time display or video recording.
+
+##  Basic Usage Example
+
+```rust
+use usls::*;
+
+fn main() -> anyhow::Result<()> {
+    // 1. Configure & Build Model
+    let config = Config::rfdetr_nano()
+        .with_model_device(Device::Cuda(0))
+        .commit()?;
+    let mut model = RFDETR::new(config)?;
+    
+    // 2. Setup DataLoader
+    let dl = DataLoader::new("image.jpg")?
+        .with_batch(model.batch())
+        .stream()?;
+    
+    // optional: Annotate
+    let annotator = Annotator::default();
+
+    // optional: Viewer
+    let mut viewer = Viewer::default();
+
+    // 3. Run Inference
+    for xs in dl {
+        let ys = model.run(&xs)?;
+        for (x, y) in xs.iter().zip(ys.iter()) {
+            // 4. Access results
+            for hb in y.hbbs() {
+                println!("{}", hb);
+            }
+
+            // optional: Check if the window is closed and exit if so.
+            if viewer.is_window_exist_and_closed() {
+                break;
+            }
+
+            // optional: Annotate
+            let image_annotated = annotator.annotate(x, y)?;
+
+            // optional: Display the current image.
+            viewer.imshow(&image_annotated)?;
+
+            // optional: Wait for a key press or timeout, and exit on Escape.
+            if let Some(key) = viewer.wait_key(10) {
+                if key == usls::Key::Escape {
+                    break;
+                }
+            }
+
+            // optional: Save the annotated image.
+            image_annotated.save("output.jpg")?;
+        }
+    }
+    Ok(())
+}
+```

docs/getting-started/integration.md

@@ -0,0 +1,18 @@
+# Getting Started Overview
+<p align="center">
+  <img src="https://github.com/jamjamjon/assets/releases/download/images/pipeline.png" width="800">
+</p>
+
+**usls** is a cross-platform Rust library powered by ONNX Runtime for efficient inference of SOTA vision and vision-language models (***typically under 1B parameters***).
+
+
+## 🌟 Highlights
+
+- **⚡ High Performance**: Multi-threading, SIMD, and CUDA-accelerated processing
+- **🌐 Cross-Platform**: Linux, macOS, Windows with ONNX Runtime execution providers (CUDA, TensorRT, CoreML, OpenVINO, DirectML, etc.)
+- **🏗️ Unified API**: Single `Model` trait inference with `run()`/`forward()`/`encode_images()`/`encode_texts()` and unified `Y` output
+- **📥 Auto-Management**: Automatic model download (HuggingFace/GitHub), caching and path resolution
+- **📦 Multiple Inputs**: Image, directory, video, webcam, stream and combinations
+- **🎯 Precision Support**: FP32, FP16, INT8, UINT8, Q4, Q4F16, BNB4, and more
+- **🛠️ Full-Stack Suite**: `DataLoader`, `Annotator`, and `Viewer` for complete workflows
+- **🌱 Model Ecosystem**: 50+ SOTA vision and VLM models