app.py

"""Gradio demo application for Vision-Edge object detection.

Three tabs:
1. Detect Objects - Upload image, select quantization variant, get annotated results.
2. Benchmark Comparison - View benchmark tables and charts.
3. Model Info - Architecture details and methodology.
"""

from __future__ import annotations

import numpy as np
import gradio as gr
from PIL import Image, ImageDraw, ImageFont


# --- Demo mode utilities (random dummy detections) ---

DEMO_CLASSES = [
    "person", "bicycle", "car", "motorcycle", "bus",
    "truck", "cat", "dog", "bird", "bottle",
]

DEMO_COLORS = [
    (255, 0, 0), (0, 255, 0), (0, 0, 255), (255, 255, 0), (255, 0, 255),
    (0, 255, 255), (128, 0, 0), (0, 128, 0), (0, 0, 128), (128, 128, 0),
]

BENCHMARK_DATA = [
    {"variant": "FP32", "size_mb": 5.80, "latency_ms": 28.3, "map_50": 0.6820},
    {"variant": "FP16", "size_mb": 3.10, "latency_ms": 22.1, "map_50": 0.6815},
    {"variant": "INT8", "size_mb": 1.55, "latency_ms": 12.4, "map_50": 0.6680},
]


def generate_dummy_detections(
    image: Image.Image,
    variant: str,
    seed: int = 42,
) -> tuple[Image.Image, str, str]:
    """Generate random bounding box detections on the input image.

    Returns annotated image, detection list text, and latency info.
    """
    rng = np.random.default_rng(seed + hash(variant) % 1000)

    width, height = image.size
    num_detections = rng.integers(2, 7)

    annotated = image.copy()
    draw = ImageDraw.Draw(annotated)

    try:
        font = ImageFont.truetype("arial.ttf", 14)
    except (OSError, IOError):
        font = ImageFont.load_default()

    detection_lines = []

    for i in range(num_detections):
        cls_id = int(rng.integers(0, len(DEMO_CLASSES)))
        cls_name = DEMO_CLASSES[cls_id]
        confidence = float(rng.uniform(0.45, 0.98))

        x1 = int(rng.uniform(0, width * 0.6))
        y1 = int(rng.uniform(0, height * 0.6))
        x2 = int(rng.uniform(x1 + width * 0.1, min(x1 + width * 0.4, width)))
        y2 = int(rng.uniform(y1 + height * 0.1, min(y1 + height * 0.4, height)))

        color = DEMO_COLORS[cls_id % len(DEMO_COLORS)]

        # Draw box
        for offset in range(2):
            draw.rectangle(
                [x1 - offset, y1 - offset, x2 + offset, y2 + offset],
                outline=color,
            )

        # Draw label
        label = f"{cls_name} {confidence:.2f}"
        text_bbox = draw.textbbox((x1, y1), label, font=font)
        text_h = text_bbox[3] - text_bbox[1]
        text_w = text_bbox[2] - text_bbox[0]

        label_y = max(y1 - text_h - 4, 0)
        draw.rectangle(
            [x1, label_y, x1 + text_w + 4, label_y + text_h + 4],
            fill=color,
        )
        draw.text((x1 + 2, label_y + 2), label, fill=(255, 255, 255), font=font)

        detection_lines.append(
            f"{i + 1}. {cls_name}: {confidence:.2f} "
            f"[{x1}, {y1}, {x2}, {y2}]"
        )

    # Simulate variant-dependent latency
    latency_map = {"FP32": 28.3, "FP16": 22.1, "INT8": 12.4}
    latency = latency_map.get(variant, 28.3)
    jitter = float(rng.uniform(-2, 2))
    actual_latency = latency + jitter

    detection_text = "\n".join(detection_lines) if detection_lines else "No detections"
    latency_text = (
        f"Variant: {variant}\n"
        f"Inference time: {actual_latency:.1f} ms\n"
        f"Detections: {num_detections}"
    )

    return annotated, detection_text, latency_text


def run_detection(
    image: Image.Image | None,
    variant: str,
) -> tuple[Image.Image | None, str, str]:
    """Process uploaded image with selected quantization variant."""
    if image is None:
        return None, "Please upload an image.", ""

    if isinstance(image, np.ndarray):
        image = Image.fromarray(image)

    return generate_dummy_detections(image, variant)


# --- Benchmark tab ---

def get_benchmark_table() -> str:
    """Generate markdown benchmark comparison table."""
    lines = [
        "| Variant | Size (MB) | Latency (ms) | mAP@0.5 | Size Reduction | Speedup |",
        "|---------|-----------|-------------|---------|----------------|---------|",
    ]

    baseline = BENCHMARK_DATA[0]
    for bm in BENCHMARK_DATA:
        size_red = f"{baseline['size_mb'] / bm['size_mb']:.1f}x"
        speedup = f"{baseline['latency_ms'] / bm['latency_ms']:.1f}x"
        lines.append(
            f"| {bm['variant']} | {bm['size_mb']:.2f} | "
            f"{bm['latency_ms']:.1f} | {bm['map_50']:.4f} | "
            f"{size_red} | {speedup} |"
        )

    return "\n".join(lines)


def create_benchmark_charts() -> Image.Image:
    """Create bar charts comparing model variants."""
    import matplotlib
    matplotlib.use("Agg")
    import matplotlib.pyplot as plt

    fig, axes = plt.subplots(1, 3, figsize=(14, 4))

    variants = [b["variant"] for b in BENCHMARK_DATA]
    colors = ["#2196F3", "#4CAF50", "#FF9800"]

    # Size chart
    sizes = [b["size_mb"] for b in BENCHMARK_DATA]
    axes[0].bar(variants, sizes, color=colors)
    axes[0].set_title("Model Size (MB)")
    axes[0].set_ylabel("MB")
    for i, v in enumerate(sizes):
        axes[0].text(i, v + 0.1, f"{v:.2f}", ha="center", fontsize=10)

    # Latency chart
    latencies = [b["latency_ms"] for b in BENCHMARK_DATA]
    axes[1].bar(variants, latencies, color=colors)
    axes[1].set_title("Inference Latency (ms)")
    axes[1].set_ylabel("ms")
    for i, v in enumerate(latencies):
        axes[1].text(i, v + 0.5, f"{v:.1f}", ha="center", fontsize=10)

    # mAP chart
    maps = [b["map_50"] for b in BENCHMARK_DATA]
    axes[2].bar(variants, maps, color=colors)
    axes[2].set_title("mAP@0.5")
    axes[2].set_ylabel("mAP")
    axes[2].set_ylim(0, 1.0)
    for i, v in enumerate(maps):
        axes[2].text(i, v + 0.02, f"{v:.4f}", ha="center", fontsize=10)

    plt.tight_layout()

    # Convert to PIL Image
    fig.canvas.draw()
    w, h = fig.canvas.get_width_height()
    buf = np.frombuffer(fig.canvas.buffer_rgba(), dtype=np.uint8).reshape(h, w, 4)
    plt.close(fig)

    return Image.fromarray(buf[:, :, :3])


# --- Model Info tab ---

MODEL_INFO_TEXT = """
## MobileNetV3-SSD Architecture

### Backbone: MobileNetV3Small

MobileNetV3Small is a lightweight convolutional neural network designed for mobile
and edge devices. It uses:

- **Inverted residual blocks** with depthwise separable convolutions
- **Squeeze-and-excitation** attention modules for channel recalibration
- **h-swish activation** for improved accuracy without computational overhead
- **Neural Architecture Search (NAS)** optimized topology

The backbone is pretrained on ImageNet and extracts feature maps at two spatial
resolutions for multi-scale object detection.

### Detection Head: SSD (Single Shot Detector)

The SSD head operates on each feature map independently:

1. A 1x1 convolution refines features from the backbone
2. A 3x3 convolution predicts class scores for each anchor
3. A separate 3x3 convolution predicts bounding box offsets for each anchor
4. Predictions from all scales are concatenated

**Loss function:** Combines Smooth L1 (localization) with cross-entropy
(classification) using hard negative mining at a 3:1 negative-to-positive ratio.

### Post-Processing: Non-Maximum Suppression

After inference, overlapping detections are filtered using greedy NMS:
- Sort detections by confidence score (descending)
- Iteratively keep the highest-scored box and suppress boxes with IoU > 0.45
- Apply score threshold (default: 0.3) and maximum detection limit (default: 100)

## Quantization Methodology

### FP32 (Baseline)
Full 32-bit floating point precision. No quantization applied.
Serves as the accuracy reference for all comparisons.

### FP16 (Half Precision)
Weights quantized to 16-bit floating point. Activations remain FP32 at runtime
on CPU, or use FP16 on GPU-capable devices. Typical 2x size reduction with
negligible accuracy impact.

### INT8 (Full Integer Quantization)
Both weights and activations quantized to 8-bit integers. Requires a
representative calibration dataset (100 samples) to determine activation
ranges. Achieves approximately 4x size reduction and significant latency
improvement on devices with INT8 acceleration support (e.g., ARM NEON, Edge TPU).

Calibration process:
1. Generate representative dataset from training data distribution
2. Run inference on calibration samples to collect activation statistics
3. Compute optimal quantization parameters (scale and zero-point) per tensor
4. Apply symmetric or asymmetric quantization based on value distribution
"""


# --- Build Gradio app ---

def build_app() -> gr.Blocks:
    """Build the Gradio demo application."""
    with gr.Blocks(title="Vision-Edge: MobileNetV3-SSD Detection") as demo:
        gr.Markdown("# Vision-Edge: MobileNetV3-SSD Object Detection")
        gr.Markdown(
            "Lightweight object detection with quantization-aware deployment. "
            "Upload an image to see detection results across FP32, FP16, and INT8 variants."
        )

        with gr.Tabs():
            # Tab 1: Detection
            with gr.TabItem("Detect Objects"):
                with gr.Row():
                    with gr.Column():
                        input_image = gr.Image(
                            type="pil",
                            label="Upload Image",
                        )
                        variant_dropdown = gr.Dropdown(
                            choices=["FP32", "FP16", "INT8"],
                            value="FP32",
                            label="Quantization Variant",
                        )
                        detect_btn = gr.Button("Run Detection", variant="primary")

                    with gr.Column():
                        output_image = gr.Image(
                            type="pil",
                            label="Detection Results",
                        )
                        detection_list = gr.Textbox(
                            label="Detections",
                            lines=6,
                        )
                        latency_info = gr.Textbox(
                            label="Performance",
                            lines=3,
                        )

                detect_btn.click(
                    fn=run_detection,
                    inputs=[input_image, variant_dropdown],
                    outputs=[output_image, detection_list, latency_info],
                )

            # Tab 2: Benchmark Comparison
            with gr.TabItem("Benchmark Comparison"):
                gr.Markdown("## Quantization Benchmark Results")
                gr.Markdown(get_benchmark_table())

                gr.Markdown("## Visual Comparison")
                benchmark_img = gr.Image(
                    value=create_benchmark_charts(),
                    type="pil",
                    label="Benchmark Charts",
                    interactive=False,
                )

                gr.Markdown(
                    "**Methodology:** Latency measured over 50 runs with 5 warmup "
                    "iterations on CPU. mAP computed using 11-point interpolation "
                    "at IoU=0.5. INT8 calibration uses 100 representative samples."
                )

            # Tab 3: Model Info
            with gr.TabItem("Model Info"):
                gr.Markdown(MODEL_INFO_TEXT)

    return demo


if __name__ == "__main__":
    app = build_app()
    app.launch()