flashdet 1.0.0__py3-none-any.whl

flashdet/__init__.py

@@ -0,0 +1,23 @@
+"""FlashDet — Ultra-lightweight real-time object detection."""
+
+__version__ = "1.0.0"
+
+from flashdet.models.detector import FlashDet
+from flashdet.models.lora import apply_lora, apply_qlora, merge_lora_weights
+from flashdet.engine.trainer import Trainer
+from flashdet.engine.validator import Validator
+from flashdet.engine.predictor import Predictor
+from flashdet.engine.exporter import Exporter
+from flashdet.cfg import get_config
+from flashdet.trackers import ByteTracker
+from flashdet.solutions import ObjectCounter, SpeedEstimator, Heatmap, RegionCounter
+from flashdet.analytics import Benchmark
+
+__all__ = [
+    "FlashDet", "Trainer", "Validator", "Predictor", "Exporter",
+    "apply_lora", "apply_qlora", "merge_lora_weights", "get_config",
+    "ByteTracker",
+    "ObjectCounter", "SpeedEstimator", "Heatmap", "RegionCounter",
+    "Benchmark",
+    "__version__",
+]

flashdet/analytics/__init__.py

@@ -0,0 +1,19 @@
+"""Analytics — benchmarking, profiling and visualisation tools for FlashDet."""
+
+from flashdet.analytics.benchmark import Benchmark
+from flashdet.analytics.profiler import Profiler
+from flashdet.analytics.plots import (
+    plot_training_curves,
+    plot_pr_curve,
+    plot_confusion_matrix,
+    plot_map_curve,
+)
+
+__all__ = [
+    "Benchmark",
+    "Profiler",
+    "plot_training_curves",
+    "plot_pr_curve",
+    "plot_confusion_matrix",
+    "plot_map_curve",
+]

flashdet/analytics/benchmark.py

@@ -0,0 +1,156 @@
+"""Benchmark — measure FlashDet model speed, size and parameter count."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+import numpy as np
+
+
+class Benchmark:
+    """Benchmark FlashDet model speed and resource usage.
+
+    Parameters
+    ----------
+    model_path : str | Path
+        Path to a saved FlashDet checkpoint (``.pth`` / ``.onnx``).
+    device : str
+        ``"cuda"`` or ``"cpu"``.
+    input_size : int | tuple[int, int]
+        Network input resolution.  A single int is treated as
+        ``(input_size, input_size)``.
+    """
+
+    def __init__(
+        self,
+        model_path: Union[str, Path],
+        device: str = "cuda",
+        input_size: Union[int, tuple] = 320,
+    ):
+        self.model_path = Path(model_path)
+        self.device = device
+        self.input_size = (input_size, input_size) if isinstance(input_size, int) else tuple(input_size)
+
+        self._model: Optional[Any] = None
+        self._is_onnx: bool = self.model_path.suffix.lower() == ".onnx"
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def run(self, warmup: int = 10, iterations: int = 100) -> Dict[str, float]:
+        """Run a speed benchmark.
+
+        Returns
+        -------
+        dict
+            ``{"fps": …, "latency_ms": …, "params": …, "model_size_mb": …}``
+        """
+        model = self._load_model()
+        dummy = self._make_dummy_input()
+
+        if self._is_onnx:
+            return self._bench_onnx(model, dummy, warmup, iterations)
+        return self._bench_pytorch(model, dummy, warmup, iterations)
+
+    def compare(self, model_paths: List[Union[str, Path]]) -> List[Dict[str, Any]]:
+        """Compare multiple models side by side.
+
+        Parameters
+        ----------
+        model_paths : list[str | Path]
+            Paths to additional models to compare against the primary model.
+
+        Returns
+        -------
+        list[dict]
+            One result dict per model (primary model first).
+        """
+        all_paths = [self.model_path] + [Path(p) for p in model_paths]
+        results: List[Dict[str, Any]] = []
+        for p in all_paths:
+            bm = Benchmark(p, device=self.device, input_size=self.input_size)
+            res = bm.run()
+            res["model"] = str(p.name)
+            results.append(res)
+        return results
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _load_model(self):
+        if self._model is not None:
+            return self._model
+
+        if self._is_onnx:
+            import onnxruntime as ort
+            providers = ["CUDAExecutionProvider", "CPUExecutionProvider"] if self.device == "cuda" else ["CPUExecutionProvider"]
+            self._model = ort.InferenceSession(str(self.model_path), providers=providers)
+        else:
+            import torch
+            self._model = torch.load(str(self.model_path), map_location=self.device)
+            if hasattr(self._model, "eval"):
+                self._model.eval()
+        return self._model
+
+    def _make_dummy_input(self) -> np.ndarray:
+        return np.random.rand(1, 3, *self.input_size).astype(np.float32)
+
+    def _bench_pytorch(self, model, dummy: np.ndarray, warmup: int, iterations: int) -> Dict[str, float]:
+        import torch
+
+        tensor = torch.from_numpy(dummy).to(self.device)
+
+        # Warmup
+        with torch.no_grad():
+            for _ in range(warmup):
+                model(tensor)
+        if self.device == "cuda":
+            torch.cuda.synchronize()
+
+        # Timed runs
+        start = time.perf_counter()
+        with torch.no_grad():
+            for _ in range(iterations):
+                model(tensor)
+        if self.device == "cuda":
+            torch.cuda.synchronize()
+        elapsed = time.perf_counter() - start
+
+        latency_ms = (elapsed / iterations) * 1000
+        fps = iterations / elapsed
+
+        params = sum(p.numel() for p in model.parameters()) if hasattr(model, "parameters") else 0
+        size_mb = self.model_path.stat().st_size / (1024 * 1024)
+
+        return {
+            "fps": round(fps, 2),
+            "latency_ms": round(latency_ms, 3),
+            "params": params,
+            "model_size_mb": round(size_mb, 2),
+        }
+
+    def _bench_onnx(self, session, dummy: np.ndarray, warmup: int, iterations: int) -> Dict[str, float]:
+        input_name = session.get_inputs()[0].name
+
+        for _ in range(warmup):
+            session.run(None, {input_name: dummy})
+
+        start = time.perf_counter()
+        for _ in range(iterations):
+            session.run(None, {input_name: dummy})
+        elapsed = time.perf_counter() - start
+
+        latency_ms = (elapsed / iterations) * 1000
+        fps = iterations / elapsed
+        size_mb = self.model_path.stat().st_size / (1024 * 1024)
+
+        return {
+            "fps": round(fps, 2),
+            "latency_ms": round(latency_ms, 3),
+            "params": 0,  # ONNX doesn't expose param count easily
+            "model_size_mb": round(size_mb, 2),
+        }

flashdet/analytics/plots.py

@@ -0,0 +1,226 @@
+"""Plotting utilities — training curves, PR curves, mAP and confusion matrices."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Dict, List, Optional, Sequence, Union
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+
+
+def _get_plt():
+    """Lazy-import matplotlib to avoid hard dependency at module level."""
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+    return plt
+
+
+# ------------------------------------------------------------------
+# Training curves
+# ------------------------------------------------------------------
+
+def plot_training_curves(
+    log: Dict[str, List[float]],
+    keys: Optional[Sequence[str]] = None,
+    save_path: Optional[Union[str, Path]] = None,
+    title: str = "Training Curves",
+) -> "Figure":
+    """Plot one or more scalar metrics from a training log dict.
+
+    Parameters
+    ----------
+    log : dict[str, list[float]]
+        ``{"loss": [...], "lr": [...], "mAP": [...], ...}``
+    keys : sequence of str | None
+        Which keys to plot.  *None* plots everything.
+    save_path : str | Path | None
+        If given, save figure to this path.
+    title : str
+        Plot title.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+    """
+    plt = _get_plt()
+    keys = keys or list(log.keys())
+    n = len(keys)
+    fig, axes = plt.subplots(1, n, figsize=(5 * n, 4), squeeze=False)
+    axes = axes.flatten()
+
+    for ax, key in zip(axes, keys):
+        values = log[key]
+        ax.plot(values, linewidth=1.5)
+        ax.set_title(key)
+        ax.set_xlabel("Epoch")
+        ax.grid(True, alpha=0.3)
+
+    fig.suptitle(title, fontsize=14)
+    fig.tight_layout()
+
+    if save_path is not None:
+        fig.savefig(str(save_path), dpi=150, bbox_inches="tight")
+
+    return fig
+
+
+# ------------------------------------------------------------------
+# Precision-Recall curve
+# ------------------------------------------------------------------
+
+def plot_pr_curve(
+    precisions: np.ndarray,
+    recalls: np.ndarray,
+    ap: Optional[float] = None,
+    class_name: str = "all",
+    save_path: Optional[Union[str, Path]] = None,
+) -> "Figure":
+    """Plot a Precision-Recall curve.
+
+    Parameters
+    ----------
+    precisions, recalls : np.ndarray
+        1-D arrays of matched length.
+    ap : float | None
+        Average Precision value (shown in legend when provided).
+    class_name : str
+        Label for the curve.
+    save_path : str | Path | None
+        Optional file path.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+    """
+    plt = _get_plt()
+    fig, ax = plt.subplots(figsize=(6, 5))
+    label = f"{class_name}"
+    if ap is not None:
+        label += f" (AP={ap:.3f})"
+    ax.plot(recalls, precisions, linewidth=1.5, label=label)
+    ax.set_xlabel("Recall")
+    ax.set_ylabel("Precision")
+    ax.set_title("Precision-Recall Curve")
+    ax.set_xlim(0, 1)
+    ax.set_ylim(0, 1.05)
+    ax.legend(loc="lower left")
+    ax.grid(True, alpha=0.3)
+    fig.tight_layout()
+
+    if save_path is not None:
+        fig.savefig(str(save_path), dpi=150, bbox_inches="tight")
+
+    return fig
+
+
+# ------------------------------------------------------------------
+# mAP over IoU thresholds
+# ------------------------------------------------------------------
+
+def plot_map_curve(
+    iou_thresholds: np.ndarray,
+    map_values: np.ndarray,
+    save_path: Optional[Union[str, Path]] = None,
+) -> "Figure":
+    """Plot mAP at different IoU thresholds.
+
+    Parameters
+    ----------
+    iou_thresholds : np.ndarray
+        1-D array of IoU thresholds (e.g. 0.50, 0.55, …, 0.95).
+    map_values : np.ndarray
+        Corresponding mAP values.
+    save_path : str | Path | None
+        Optional save path.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+    """
+    plt = _get_plt()
+    fig, ax = plt.subplots(figsize=(6, 4))
+    ax.bar(iou_thresholds, map_values, width=0.03, color="steelblue", edgecolor="white")
+    ax.set_xlabel("IoU Threshold")
+    ax.set_ylabel("mAP")
+    ax.set_title("mAP @ IoU Thresholds")
+    ax.set_ylim(0, 1.0)
+    ax.grid(True, axis="y", alpha=0.3)
+    fig.tight_layout()
+
+    if save_path is not None:
+        fig.savefig(str(save_path), dpi=150, bbox_inches="tight")
+
+    return fig
+
+
+# ------------------------------------------------------------------
+# Confusion matrix
+# ------------------------------------------------------------------
+
+def plot_confusion_matrix(
+    matrix: np.ndarray,
+    class_names: Optional[List[str]] = None,
+    normalize: bool = True,
+    save_path: Optional[Union[str, Path]] = None,
+    title: str = "Confusion Matrix",
+) -> "Figure":
+    """Plot a confusion matrix as a heatmap.
+
+    Parameters
+    ----------
+    matrix : np.ndarray
+        Square confusion matrix of shape ``(n_classes, n_classes)``.
+    class_names : list[str] | None
+        Tick labels.  Auto-generated indices when *None*.
+    normalize : bool
+        Row-normalise the matrix before plotting.
+    save_path : str | Path | None
+        Optional save path.
+    title : str
+        Plot title.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+    """
+    plt = _get_plt()
+    n = matrix.shape[0]
+    if class_names is None:
+        class_names = [str(i) for i in range(n)]
+
+    if normalize:
+        row_sums = matrix.sum(axis=1, keepdims=True)
+        row_sums = np.where(row_sums == 0, 1, row_sums)
+        matrix = matrix.astype(np.float64) / row_sums
+
+    fig, ax = plt.subplots(figsize=(max(6, n * 0.6), max(5, n * 0.5)))
+    im = ax.imshow(matrix, interpolation="nearest", cmap="Blues")
+    fig.colorbar(im, ax=ax)
+
+    ax.set_xticks(range(n))
+    ax.set_yticks(range(n))
+    ax.set_xticklabels(class_names, rotation=45, ha="right", fontsize=8)
+    ax.set_yticklabels(class_names, fontsize=8)
+    ax.set_xlabel("Predicted")
+    ax.set_ylabel("True")
+    ax.set_title(title)
+
+    thresh = matrix.max() / 2
+    for i in range(n):
+        for j in range(n):
+            val = matrix[i, j]
+            text = f"{val:.2f}" if normalize else f"{int(val)}"
+            ax.text(
+                j, i, text, ha="center", va="center",
+                color="white" if val > thresh else "black", fontsize=7,
+            )
+
+    fig.tight_layout()
+    if save_path is not None:
+        fig.savefig(str(save_path), dpi=150, bbox_inches="tight")
+
+    return fig

flashdet/analytics/profiler.py

@@ -0,0 +1,199 @@
+"""Profiler — layer-wise latency and memory analysis for FlashDet models."""
+
+from __future__ import annotations
+
+import time
+from collections import OrderedDict
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+import numpy as np
+
+
+class Profiler:
+    """Profile a FlashDet PyTorch model layer-by-layer.
+
+    Hooks into every ``nn.Module`` child to record per-layer forward time
+    and (optionally) memory consumption.
+
+    Parameters
+    ----------
+    model_path : str | Path
+        Path to a FlashDet ``.pth`` checkpoint.
+    device : str
+        ``"cuda"`` or ``"cpu"``.
+    input_size : int | tuple[int, int]
+        Network input resolution.
+    """
+
+    def __init__(
+        self,
+        model_path: Union[str, Path],
+        device: str = "cuda",
+        input_size: Union[int, tuple] = 320,
+    ):
+        self.model_path = Path(model_path)
+        self.device = device
+        self.input_size = (input_size, input_size) if isinstance(input_size, int) else tuple(input_size)
+
+        self._model: Optional[Any] = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def run(self, warmup: int = 5, iterations: int = 20) -> List[Dict[str, Any]]:
+        """Profile the model and return per-layer statistics.
+
+        Returns
+        -------
+        list[dict]
+            Each dict has keys:
+            ``{"name", "type", "time_ms", "time_pct", "params", "output_shape"}``.
+        """
+        import torch
+
+        model = self._load_model()
+        dummy = torch.randn(1, 3, *self.input_size, device=self.device)
+
+        timings: OrderedDict[str, List[float]] = OrderedDict()
+        shapes: Dict[str, tuple] = {}
+        hooks = []
+
+        def _make_hook(name: str):
+            def _hook(module, inp, out):
+                if self.device == "cuda":
+                    torch.cuda.synchronize()
+                timings[name].append(time.perf_counter())
+                if isinstance(out, torch.Tensor):
+                    shapes[name] = tuple(out.shape)
+                elif isinstance(out, (tuple, list)) and len(out) > 0 and isinstance(out[0], torch.Tensor):
+                    shapes[name] = tuple(out[0].shape)
+            return _hook
+
+        for name, module in model.named_modules():
+            if len(list(module.children())) > 0:
+                continue  # only leaf modules
+            timings[name] = []
+            hooks.append(module.register_forward_hook(_make_hook(name)))
+
+        # Warmup
+        with torch.no_grad():
+            for _ in range(warmup):
+                model(dummy)
+
+        # Timed runs — record wall-clock per forward hook invocation
+        layer_times: OrderedDict[str, List[float]] = OrderedDict()
+        for name in timings:
+            layer_times[name] = []
+
+        for _ in range(iterations):
+            for name in timings:
+                timings[name].clear()
+
+            if self.device == "cuda":
+                torch.cuda.synchronize()
+            with torch.no_grad():
+                model(dummy)
+
+            sorted_names = sorted(timings.keys(), key=lambda n: timings[n][0] if timings[n] else float("inf"))
+            for i, name in enumerate(sorted_names):
+                if not timings[name]:
+                    continue
+                t_end = timings[name][0]
+                if i == 0:
+                    t_start = t_end
+                    layer_times[name].append(0.0)
+                else:
+                    prev_name = sorted_names[i - 1]
+                    t_start = timings[prev_name][0] if timings[prev_name] else t_end
+                    layer_times[name].append((t_end - t_start) * 1000)
+
+        for h in hooks:
+            h.remove()
+
+        # Aggregate
+        results: List[Dict[str, Any]] = []
+        total_ms = 0.0
+        for name in layer_times:
+            vals = layer_times[name]
+            mean_ms = float(np.mean(vals)) if vals else 0.0
+            total_ms += mean_ms
+
+        for name in layer_times:
+            vals = layer_times[name]
+            mean_ms = float(np.mean(vals)) if vals else 0.0
+            module = dict(model.named_modules()).get(name)
+            n_params = sum(p.numel() for p in module.parameters()) if module is not None else 0
+            mod_type = type(module).__name__ if module is not None else "Unknown"
+            results.append({
+                "name": name,
+                "type": mod_type,
+                "time_ms": round(mean_ms, 4),
+                "time_pct": round(mean_ms / total_ms * 100, 2) if total_ms > 0 else 0.0,
+                "params": n_params,
+                "output_shape": shapes.get(name),
+            })
+
+        return results
+
+    def summary(self, warmup: int = 5, iterations: int = 20) -> str:
+        """Return a human-readable profiling summary table."""
+        rows = self.run(warmup=warmup, iterations=iterations)
+
+        lines = [
+            f"{'Layer':<50} {'Type':<18} {'Time(ms)':>10} {'%':>7} {'Params':>10}",
+            "-" * 100,
+        ]
+        for r in rows:
+            lines.append(
+                f"{r['name']:<50} {r['type']:<18} {r['time_ms']:>10.4f} "
+                f"{r['time_pct']:>6.2f}% {r['params']:>10,}"
+            )
+        total_ms = sum(r["time_ms"] for r in rows)
+        total_params = sum(r["params"] for r in rows)
+        lines.append("-" * 100)
+        lines.append(
+            f"{'TOTAL':<50} {'':<18} {total_ms:>10.4f} {'100.00%':>7} {total_params:>10,}"
+        )
+        return "\n".join(lines)
+
+    def memory_report(self) -> Dict[str, float]:
+        """Return GPU memory usage summary (CUDA only).
+
+        Returns
+        -------
+        dict
+            ``{"allocated_mb", "reserved_mb", "peak_mb"}``
+        """
+        import torch
+
+        if not torch.cuda.is_available() or self.device != "cuda":
+            return {"allocated_mb": 0.0, "reserved_mb": 0.0, "peak_mb": 0.0}
+
+        model = self._load_model()
+        dummy = torch.randn(1, 3, *self.input_size, device=self.device)
+        torch.cuda.reset_peak_memory_stats()
+
+        with torch.no_grad():
+            model(dummy)
+        torch.cuda.synchronize()
+
+        return {
+            "allocated_mb": round(torch.cuda.memory_allocated() / 1024 ** 2, 2),
+            "reserved_mb": round(torch.cuda.memory_reserved() / 1024 ** 2, 2),
+            "peak_mb": round(torch.cuda.max_memory_allocated() / 1024 ** 2, 2),
+        }
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _load_model(self):
+        if self._model is not None:
+            return self._model
+        import torch
+        self._model = torch.load(str(self.model_path), map_location=self.device)
+        if hasattr(self._model, "eval"):
+            self._model.eval()
+        return self._model

flashdet/cfg/__init__.py

@@ -0,0 +1,5 @@
+from flashdet.cfg.config import get_config, ModelConfig, DataConfig, TrainConfig
+from flashdet.cfg.config import Config as FlashDetConfig
+from flashdet.cfg.config import load_yaml_config
+
+__all__ = ["get_config", "load_yaml_config", "ModelConfig", "DataConfig", "TrainConfig", "FlashDetConfig"]