colosseum-microcontroller 0.1.3__tar.gz

colosseum_microcontroller-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aqshal Nur Ikhsan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

colosseum_microcontroller-0.1.3/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: colosseum-microcontroller
+Version: 0.1.3
+Summary: Train compact single-class object detectors for microcontrollers
+Author: Aqshal Nur Ikhsan
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Aqshalikhsan/Colosseum-Microcontroller
+Project-URL: Repository, https://github.com/Aqshalikhsan/Colosseum-Microcontroller
+Project-URL: Documentation, https://github.com/Aqshalikhsan/Colosseum-Microcontroller/blob/main/README.md
+Keywords: object detection,microcontroller,ESP32-S3,TinyML,PyTorch
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.1
+Requires-Dist: Pillow>=10
+Requires-Dist: PyYAML>=6
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Aqshalikhsan/Colosseum-Microcontroller/main/assets/colosseum_banner.png" width="900" alt="Colosseum letter-tile logo">
+</p>
+
+Colosseum is a compact single-class object detection framework designed for microcontroller deployment. Install it to train a detector for your own target object. The package also includes 18 example checkpoints from six datasets and three seeds.
+
+```bash
+python -m pip install colosseum-microcontroller
+```
+
+```python
+from colosseum import Colosseum
+
+model = Colosseum()
+checkpoints = model.train(
+    data="my_dataset/data.yaml",
+    name="my_object",
+    label="my object",
+    grid="4x4",
+)
+print(checkpoints[0])
+print(model.metrics)  # AP50, AP75, AP50:95, precision, recall, F1
+boxes = model.predict("path/to/image.jpg")
+```
+
+Training starts from scratch, saves a compact checkpoint and `metrics.json` under `runs/custom/my_object/seed0/`, and loads it for inference. Metrics are computed on the validation split. One checkpoint detects one target class. Your dataset uses images and normalized bounding-box text annotations; see the [training guide](https://github.com/Aqshalikhsan/Colosseum-Microcontroller/blob/main/docs/TRAINING.md) for the layout.
+
+The command-line equivalent is:
+
+```bash
+colosseum train --data my_dataset/data.yaml --name my_object --label "my object" --grid 4x4
+```
+
+The bundled example names are `uc3m`, `gtsdb`, `shwd`, `ccpd`, `drone`, and `amlpr`, plus `_seed1` and `_seed2` variants. For inference you can pass either one of these names or the path to your own compact checkpoint. See the [repository](https://github.com/Aqshalikhsan/Colosseum-Microcontroller) for benchmarks. The weights are floating-point PyTorch checkpoints; ESP32-S3 deployment uses the separate INT8 runtime.
+
+[Open the training notebook in Google Colab](https://colab.research.google.com/github/Aqshalikhsan/Colosseum-Microcontroller/blob/main/notebooks/Train_Colosseum.ipynb) to upload a dataset and run the full pipeline.

colosseum_microcontroller-0.1.3/PYPI_README.md

@@ -0,0 +1,36 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Aqshalikhsan/Colosseum-Microcontroller/main/assets/colosseum_banner.png" width="900" alt="Colosseum letter-tile logo">
+</p>
+
+Colosseum is a compact single-class object detection framework designed for microcontroller deployment. Install it to train a detector for your own target object. The package also includes 18 example checkpoints from six datasets and three seeds.
+
+```bash
+python -m pip install colosseum-microcontroller
+```
+
+```python
+from colosseum import Colosseum
+
+model = Colosseum()
+checkpoints = model.train(
+    data="my_dataset/data.yaml",
+    name="my_object",
+    label="my object",
+    grid="4x4",
+)
+print(checkpoints[0])
+print(model.metrics)  # AP50, AP75, AP50:95, precision, recall, F1
+boxes = model.predict("path/to/image.jpg")
+```
+
+Training starts from scratch, saves a compact checkpoint and `metrics.json` under `runs/custom/my_object/seed0/`, and loads it for inference. Metrics are computed on the validation split. One checkpoint detects one target class. Your dataset uses images and normalized bounding-box text annotations; see the [training guide](https://github.com/Aqshalikhsan/Colosseum-Microcontroller/blob/main/docs/TRAINING.md) for the layout.
+
+The command-line equivalent is:
+
+```bash
+colosseum train --data my_dataset/data.yaml --name my_object --label "my object" --grid 4x4
+```
+
+The bundled example names are `uc3m`, `gtsdb`, `shwd`, `ccpd`, `drone`, and `amlpr`, plus `_seed1` and `_seed2` variants. For inference you can pass either one of these names or the path to your own compact checkpoint. See the [repository](https://github.com/Aqshalikhsan/Colosseum-Microcontroller) for benchmarks. The weights are floating-point PyTorch checkpoints; ESP32-S3 deployment uses the separate INT8 runtime.
+
+[Open the training notebook in Google Colab](https://colab.research.google.com/github/Aqshalikhsan/Colosseum-Microcontroller/blob/main/notebooks/Train_Colosseum.ipynb) to upload a dataset and run the full pipeline.

colosseum_microcontroller-0.1.3/README.md

@@ -0,0 +1,135 @@
+<p align="center">
+  <img src="assets/colosseum_banner.png" width="900" alt="Colosseum letter-tile logo">
+</p>
+
+<p align="center">
+  Compact object detection for microcontrollers, with reproducible training and benchmarks.
+</p>
+
+<p align="center">
+  <a href="#quick-start"><img alt="Python 3.11" src="https://img.shields.io/badge/Python-3.11-3776AB?logo=python&amp;logoColor=white"></a>
+  <a href="#model-zoo"><img alt="PyTorch models" src="https://img.shields.io/badge/PyTorch-models-EE4C2C?logo=pytorch&amp;logoColor=white"></a>
+  <a href="#benchmarks"><img alt="ESP32-S3 benchmark" src="https://img.shields.io/badge/ESP32--S3-benchmark-00979D?logo=espressif&amp;logoColor=white"></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/License-MIT-2DA44E"></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">🚀 Quick start</a> &nbsp;·&nbsp;
+  <a href="notebooks/Train_Colosseum.ipynb">📓 Training notebook</a> &nbsp;·&nbsp;
+  <a href="#model-zoo">🧠 Models</a> &nbsp;·&nbsp;
+  <a href="#benchmarks">📊 Benchmarks</a> &nbsp;·&nbsp;
+  <a href="#train-on-your-data">🛠️ Train on your data</a>
+</p>
+
+**Colosseum** is a compact, single-class object detector designed for microcontroller deployment. It uses fixed image-gradient features, residual convolution blocks, three-scale fusion, and separate confidence and box heads. The network has **81,403 parameters**. A checkpoint detects one target class; use a different checkpoint for a different class.
+
+Install Colosseum as a Python library to train a detector on your own images. The repository also provides **18 ready-to-use PyTorch checkpoints** (six datasets × three seeds) for examples and benchmarks. Input is grayscale, letterboxed to **256 × 192** pixels. Colosseum outputs bounding boxes, not text recognition.
+
+## Quick start
+
+Tested with Python 3.11. Install the package from PyPI:
+
+```bash
+python -m pip install colosseum-microcontroller
+```
+
+[Open the training notebook in Google Colab](https://colab.research.google.com/github/Aqshalikhsan/Colosseum-Microcontroller/blob/main/notebooks/Train_Colosseum.ipynb) to upload your own dataset, train through the Python API, view validation metrics, and download the checkpoints.
+
+Create `my_dataset/data.yaml` and train your own detector from Python:
+
+```python
+from colosseum import Colosseum
+
+model = Colosseum()
+checkpoints = model.train(
+    data="my_dataset/data.yaml",
+    name="my_object",
+    label="my object",
+    grid="4x4",
+)
+print(checkpoints[0])  # runs/custom/my_object/seed0/colosseum.pt
+print(model.metrics)    # AP50, AP75, AP50:95, precision, recall, F1
+boxes = model.predict("path/to/image.jpg")
+```
+
+This trains the Colosseum network from scratch, evaluates the validation split, loads the resulting checkpoint, and returns its path. Each seed writes a `metrics.json` with AP50, AP75, AP50:95, precision, recall, and F1. Call `model.evaluate("my_dataset/data.yaml")` to evaluate a loaded checkpoint again. Each checkpoint detects **one target class**. The dataset uses ordinary image files and text files with normalized box coordinates; the [training guide](docs/TRAINING.md) shows the exact layout. No Ultralytics package or YOLO model is used. For a source checkout, use `python -m pip install -e .` to install the library in editable mode.
+
+The equivalent command-line interface is:
+
+```bash
+colosseum train --data my_dataset/data.yaml --name my_object --label "my object" --grid 4x4
+colosseum predict --weights runs/custom/my_object/seed0/colosseum.pt --source path/to/image.jpg
+```
+
+The pip package also includes all **18 example checkpoints**, so a model name such as `uc3m`, `shwd`, or `uc3m_seed1` works without downloading another file. To try one, run `colosseum predict --weights uc3m --source path/to/image.jpg`.
+
+Annotated images and machine-readable `predictions.json` are written to `runs/predict/`. Use `--source path/to/folder` for a folder of images, `--conf 0.25` to adjust the confidence cutoff, and `--device cuda:0` for a CUDA GPU.
+
+To load a previously trained checkpoint in another script:
+
+```python
+from colosseum import Colosseum
+
+model = Colosseum("runs/custom/my_object/seed0/colosseum.pt")
+for box in model.predict("path/to/image.jpg", conf=0.35):
+    print(box.label, box.confidence, box.x1, box.y1, box.x2, box.y2)
+```
+
+The coordinates are pixels in the original image after EXIF orientation is applied. The prediction threshold only filters results; it does not change the model. Local confidence peaks are used to select candidate boxes.
+
+## Model zoo
+
+All included weights are **final checkpoints** from the reported three-seed training runs. The top-level weights are seed 0; seed 1 and 2 are in `weights/seeds/`. They are also bundled with the pip package. The complete training state was stripped; each file contains model tensors and the metadata required for inference. The `weights/manifest.json` file records SHA-256 hashes.
+
+| Weights | Training dataset | Detects | Output stride |
+|---|---|---|---|
+| [`uc3m.pt`](weights/uc3m.pt) | UC3M-LP | license plate | 2 × 8 |
+| [`gtsdb.pt`](weights/gtsdb.pt) | GTSDB | prohibitory traffic sign | 4 × 4 |
+| [`shwd.pt`](weights/shwd.pt) | SHWD | safety helmet | 4 × 4 |
+| [`ccpd.pt`](weights/ccpd.pt) | CCPD2019 | license plate | 2 × 8 |
+| [`drone.pt`](weights/drone.pt) | Drone | drone | 4 × 4 |
+| [`amlpr.pt`](weights/amlpr.pt) | AMLPR | license plate | 2 × 8 |
+
+For example, use `weights/seeds/uc3m_seed1.pt` or `weights/seeds/uc3m_seed2.pt` to select another UC3M seed. The same naming convention applies to every dataset.
+
+The dataset name identifies the training domain; three plate checkpoints are separate models trained on different images. Choose the checkpoint closest to the images you expect. These are floating-point PyTorch weights. They are not directly loadable by ESP32-S3 firmware; device deployment requires the separately quantized INT8 program and C runtime.
+
+## Benchmarks
+
+The plots below reproduce the **initial matched comparisons** in the paper: validation mean and sample SD across three seeds. The separate SHWD and Drone reruns changed two narrow initial rankings; see the paper before interpreting those datasets. The [accuracy data](assets/benchmark_results.csv), [device data](assets/benchmark_device.csv), and [plot script](scripts/plot_benchmark.py) are included.
+
+![Float validation AP50, AP75, and AP50:95 across six datasets](assets/benchmark_float.png)
+
+![Post-training INT8 validation AP50, AP75, and AP50:95 across six datasets](assets/benchmark_int8.png)
+
+The device comparison below is for **UC3M seed 0** on a 240 MHz ESP32-S3 with an embedded frame. Training throughput is a separate RTX 5060 pilot, not a device speed measurement.
+
+![UC3M training throughput and ESP32-S3 deployment measurements](assets/benchmark_device.png)
+
+The following paper figure shows selected **validation examples**, not aggregate performance. Green boxes are targets; red boxes are the top prediction when present.
+
+![Qualitative validation examples for Colosseum and three baselines](assets/qualitative_results.png)
+
+## Train on your data
+
+Colosseum uses YOLO-format single-class annotations. For a new dataset, put images and labels in `images/train`, `images/val`, `labels/train`, and `labels/val`, then make a `data.yaml`. One command trains both stages and packages weights:
+
+```bash
+colosseum train --data my_dataset/data.yaml --name my_object --label "my object" --grid 4x4
+colosseum predict --weights runs/custom/my_object/seed0/colosseum.pt --source path/to/image.jpg
+```
+
+The script computes box-size priors from training labels only. Use `--grid 2x8` for elongated horizontal targets, `--seeds 0 1 2` for three runs, and `--source-class N` when the target's YOLO class ID is not zero. See the [full custom-training guide](docs/TRAINING.md) for the dataset layout, options, and manual commands. Raw datasets and official test images are not included here.
+
+## Reproducibility
+
+- Input: grayscale, bilinear resize preserving aspect ratio, gray padding value 114.
+- Architecture: fixed-gradient stem, regular bottleneck blocks, multiscale fusion, one confidence channel and four geometry channels.
+- Geometry: normalized boxes with a prior-log width and height encoding; priors are saved in each checkpoint.
+- The implementation is packaged under `colosseum/`; `src/` keeps compatibility imports for older source-checkout commands.
+
+Please cite the Colosseum paper when it becomes available. The datasets remain subject to their source terms; no raw dataset images are redistributed here.
+
+## License
+
+Code and the 18 Colosseum weight files are released under the [MIT License](LICENSE). Third-party datasets are excluded.

colosseum_microcontroller-0.1.3/akros/__init__.py

@@ -0,0 +1,5 @@
+"""Compatibility imports for earlier public checkpoints and scripts."""
+
+from .api import AKROS, Colosseum, Detection
+
+__all__ = ["AKROS", "Colosseum", "Detection"]

colosseum_microcontroller-0.1.3/akros/api.py

@@ -0,0 +1,7 @@
+"""Compatibility interface for the earlier AKROS package name."""
+
+from colosseum.api import Colosseum, Detection
+
+AKROS = Colosseum
+
+__all__ = ["AKROS", "Colosseum", "Detection"]

colosseum_microcontroller-0.1.3/colosseum/__init__.py

@@ -0,0 +1,5 @@
+"""Public Colosseum inference interface."""
+
+from .api import Colosseum, Detection
+
+__all__ = ["Colosseum", "Detection"]

colosseum_microcontroller-0.1.3/colosseum/__main__.py

@@ -0,0 +1,7 @@
+"""Allow ``python -m colosseum`` as an alternative to the console script."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

colosseum_microcontroller-0.1.3/colosseum/_core/__init__.py

@@ -0,0 +1 @@
+"""Colosseum architecture and training components."""

colosseum_microcontroller-0.1.3/colosseum/_core/mergdet.py

@@ -0,0 +1,27 @@
+"""Canonical public interface for the shared MERG-Det architecture."""
+
+from .platedet_u import (
+    AsymmetricResidualBlock,
+    ConvBNAct,
+    Detection,
+    EdgeMicroStem,
+    GeometryCodec,
+    GeometryPrior,
+    MergDet,
+    decode,
+    filter_by_geometry,
+    parameter_count,
+)
+
+__all__ = [
+    "AsymmetricResidualBlock",
+    "ConvBNAct",
+    "Detection",
+    "EdgeMicroStem",
+    "GeometryCodec",
+    "GeometryPrior",
+    "MergDet",
+    "decode",
+    "filter_by_geometry",
+    "parameter_count",
+]

colosseum_microcontroller-0.1.3/colosseum/_core/mergdet_m.py

@@ -0,0 +1,191 @@
+"""MERG-Det-M: scaled MERG-Det family (S/M/L) with a three-scale readout.
+
+Same input path, anisotropic 2x8 output grid, five-channel head layout,
+codec, loss and decoder as MERG-Det, so every existing training and
+evaluation tool applies unchanged. Differences are capacity only: wider
+stages, repeated blocks, a fourth downsampling stage, a top-down fusion of
+three scales onto the 2x8 grid, and a decoupled two-layer head. Operators stay
+conv / BN / ReLU6 / add / nearest upsample. This is an engineering variant,
+not a novelty claim; the 11k MERG-Det stays a separate result.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import torch
+from torch import Tensor, nn
+from torch.nn import functional as F
+
+from .platedet_u import AsymmetricResidualBlock, ConvBNAct, EdgeMicroStem
+
+
+@dataclass(frozen=True)
+class MergDetMConfig:
+    name: str
+    channels: tuple[int, int, int, int, int]  # stem, stage1, stage2, stage3, stage4
+    repeats: tuple[int, int, int, int]  # extra non-strided blocks per stage
+    neck: int  # lateral / fused channels on every scale
+    head: int  # objectness branch channels
+    head_depth: int = 2
+    geometry_head: int | None = None  # defaults to head for historical configs
+    geometry_head_depth: int | None = None  # defaults to head_depth
+
+
+# Budget ladder bracketing the Stage B candidates at 144x192 (single class):
+#   S 104,005 params / 54.4M Conv MAC   (~ESPDet-Pico / 3.5)
+#   M 368,813 params / 129.4M Conv MAC  (~ESPDet-Pico 361k, 2.7x its MAC)
+#   L 927,661 params / 226.0M Conv MAC  (~YOLOX-Nano 897k, 2.5x its MAC)
+# MACs stay above the candidates' at equal parameters because the 2x8 grid
+# keeps 72 rows; this is reported, not hidden.
+CONFIGS: dict[str, MergDetMConfig] = {
+    # V4 high-resolution narrow candidates. They retain V3's 192x256 canvas,
+    # repeats and 2x8 readout while reducing channel traffic enough to target
+    # the ESPDet/Tinyissimo latency range. V4T is the SRAM-first arm; V4S is
+    # the less aggressive accuracy-first arm.
+    "V4T": MergDetMConfig("V4T", (8, 12, 24, 56, 112), (1, 1, 2, 3), 16, 16),
+    "V4S": MergDetMConfig("V4S", (8, 16, 24, 48, 72), (1, 1, 2, 3), 32, 32),
+    # Accuracy-first rebalance after V4T's frozen pilot: spend compute at the
+    # input/detail path and use one wider head block; recover budget in stage3.
+    "V4A": MergDetMConfig("V4A", (10, 12, 24, 40, 128), (1, 1, 2, 3), 16, 24, 1),
+    # V4B static-screen arms: retain V4A's backbone and spend only on box
+    # regression, since V4A's localization diagnostic found size/vertical
+    # errors rather than an AP50/objectness bottleneck.
+    "V4B1": MergDetMConfig("V4B1", (10, 12, 24, 40, 128), (1, 1, 2, 3), 16, 16, 1, 24, 2),
+    "V4B2": MergDetMConfig("V4B2", (10, 12, 24, 40, 128), (1, 1, 2, 3), 16, 16, 1, 32, 2),
+    "V4B3": MergDetMConfig("V4B3", (10, 12, 24, 40, 128), (1, 1, 2, 3), 24, 16, 1, 32, 2),
+    # V4C restores V4A's objectness width after V4B1 failed its epoch-50 AP50
+    # gate, while retaining the geometry-only depth intervention.
+    "V4C1": MergDetMConfig("V4C1", (10, 12, 24, 40, 128), (1, 1, 2, 3), 16, 24, 1, 24, 2),
+    "V4C2": MergDetMConfig("V4C2", (10, 12, 24, 40, 128), (1, 1, 2, 3), 16, 24, 1, 32, 2),
+    # V5 accuracy-first/hardware-bounded arm. Restore richer multi-scale
+    # fusion while keeping the V4A detail path and a shallow deployable head.
+    "V5A": MergDetMConfig("V5A", (10, 12, 24, 40, 128), (1, 1, 2, 3), 32, 24, 1),
+    "S": MergDetMConfig("S", (16, 24, 32, 72, 112), (1, 1, 2, 3), 48, 48),
+    "M": MergDetMConfig("M", (24, 32, 48, 112, 224), (1, 2, 3, 4), 64, 64),
+    "L": MergDetMConfig("L", (24, 32, 64, 160, 320), (1, 2, 4, 6), 64, 64),
+}
+
+STRIDES = ((1, 2), (1, 2), (2, 2), (2, 2))  # after the stride-2 stem: grid 2x8, 4x16, 8x32
+
+# Grid ablation (docs/GRID_ABLATION_PROTOCOL.md): the output grid is set by the
+# strides of stages 1-2 only; stages 3-4 keep (2, 2) and the neck upsamples by
+# size. Parameters are grid-independent by construction; MAC is not.
+GRID_STRIDES: dict[tuple[int, int], tuple[tuple[int, int], tuple[int, int]]] = {
+    (2, 8): ((1, 2), (1, 2)),  # anisotropic default: 72x24 cells at 144x192
+    (4, 4): ((1, 1), (2, 2)),  # isotropic at equal cell count: 36x48
+    (8, 2): ((2, 1), (2, 1)),  # wrong-direction control: 18x96
+    (8, 8): ((2, 2), (2, 2)),  # conventional coarse grid: 18x24
+}
+
+
+class RegularBottleneckBlock(nn.Module):
+    """Hardware-oriented bottleneck using one regular 3x3 spatial convolution."""
+
+    def __init__(self, in_channels: int, out_channels: int, stride: int | tuple[int, int] = 1) -> None:
+        super().__init__()
+        stride_y, stride_x = (stride, stride) if isinstance(stride, int) else stride
+        self.stride_y, self.stride_x = stride_y, stride_x
+        hidden = max(4, min(in_channels, out_channels) // 4)
+        self.reduce = ConvBNAct(in_channels, hidden, 1)
+        self.spatial = ConvBNAct(hidden, hidden, 3, stride=(stride_y, stride_x), padding=1)
+        self.expand = ConvBNAct(hidden, out_channels, 1, activation=False)
+        if stride_y == 1 and stride_x == 1 and in_channels == out_channels:
+            self.skip: nn.Module = nn.Identity()
+        else:
+            self.skip = ConvBNAct(in_channels, out_channels, 1, stride=(stride_y, stride_x), activation=False)
+        self.activation = nn.ReLU6(inplace=True)
+
+    def forward(self, source: Tensor) -> Tensor:
+        residual = self.skip(source)
+        features = self.expand(self.spatial(self.reduce(source)))
+        return self.activation(features + residual)
+
+
+def _stage(in_channels: int, out_channels: int, stride: tuple[int, int], repeats: int,
+           block_type: type[nn.Module]) -> nn.Sequential:
+    blocks = [block_type(in_channels, out_channels, stride=stride)]
+    blocks += [block_type(out_channels, out_channels) for _ in range(repeats)]
+    return nn.Sequential(*blocks)
+
+
+class MergDetM(nn.Module):
+    def __init__(
+        self,
+        size: str = "M",
+        objectness_prior: float | None = None,
+        output_stride: tuple[int, int] = (2, 8),
+        block_kind: str = "asymmetric",
+        gradient_mode: str = "fixed",
+        fusion_mode: str = "multiscale",
+    ) -> None:
+        super().__init__()
+        config = CONFIGS[size]
+        self.config = config
+        output_stride = (int(output_stride[0]), int(output_stride[1]))
+        if output_stride not in GRID_STRIDES:
+            raise ValueError(f"output_stride must be one of {sorted(GRID_STRIDES)}, got {output_stride}")
+        self.output_stride = output_stride
+        if block_kind not in ("asymmetric", "regular"):
+            raise ValueError(f"block_kind must be 'asymmetric' or 'regular', got {block_kind!r}")
+        if fusion_mode not in ("multiscale", "detail_only"):
+            raise ValueError(f"fusion_mode must be 'multiscale' or 'detail_only', got {fusion_mode!r}")
+        self.block_kind = block_kind
+        self.gradient_mode = gradient_mode
+        self.fusion_mode = fusion_mode
+        block_type = AsymmetricResidualBlock if block_kind == "asymmetric" else RegularBottleneckBlock
+        stride1, stride2 = GRID_STRIDES[output_stride]
+        c0, c1, c2, c3, c4 = config.channels
+        r1, r2, r3, r4 = config.repeats
+        self.stem = EdgeMicroStem(c0, gradient_mode=gradient_mode)
+        self.stage1 = _stage(c0, c1, stride1, r1, block_type)
+        self.stage2 = _stage(c1, c2, stride2, r2, block_type)  # output grid (detail)
+        self.stage3 = _stage(c2, c3, STRIDES[2], r3, block_type)  # 4x16
+        self.stage4 = _stage(c3, c4, STRIDES[3], r4, block_type)  # 8x32
+        neck = config.neck
+        self.lateral2 = ConvBNAct(c2, neck, 1, activation=False)
+        self.lateral3 = ConvBNAct(c3, neck, 1, activation=False)
+        self.lateral4 = ConvBNAct(c4, neck, 1, activation=False)
+        self.smooth3 = block_type(neck, neck)
+        self.smooth2 = block_type(neck, neck)
+        self.activation = nn.ReLU6(inplace=True)
+        geometry_head = config.geometry_head if config.geometry_head is not None else config.head
+        geometry_depth = (
+            config.geometry_head_depth
+            if config.geometry_head_depth is not None
+            else config.head_depth
+        )
+        self.objectness_branch = self._branch(neck, config.head, config.head_depth, block_type)
+        self.geometry_branch = self._branch(neck, geometry_head, geometry_depth, block_type)
+        self.objectness_head = nn.Conv2d(config.head, 1, 1)
+        self.geometry_head = nn.Conv2d(geometry_head, 4, 1)
+        if objectness_prior is not None:
+            if not 0.0 < objectness_prior < 1.0:
+                raise ValueError("objectness_prior must lie in (0, 1)")
+            with torch.no_grad():
+                self.objectness_head.bias.fill_(-math.log((1.0 - objectness_prior) / objectness_prior))
+
+    @staticmethod
+    def _branch(in_channels: int, channels: int, depth: int,
+                block_type: type[nn.Module] = AsymmetricResidualBlock) -> nn.Sequential:
+        # The 2x8 grid has 1728 cells at 144x192, so a dense 3x3 head would
+        # dominate the MAC budget; keep the head asymmetric-depthwise like the
+        # stages and spend parameters in the coarse stages instead.
+        layers = [block_type(in_channels, channels)]
+        layers += [block_type(channels, channels) for _ in range(depth - 1)]
+        return nn.Sequential(*layers)
+
+    def forward(self, image: Tensor) -> Tensor:
+        s2 = self.stage2(self.stage1(self.stem(image)))
+        if self.fusion_mode == "multiscale":
+            s3 = self.stage3(s2)
+            s4 = self.stage4(s3)
+            p4 = self.lateral4(s4)
+            p3 = self.smooth3(self.activation(self.lateral3(s3) + F.interpolate(p4, size=s3.shape[-2:], mode="nearest")))
+            p2 = self.smooth2(self.activation(self.lateral2(s2) + F.interpolate(p3, size=s2.shape[-2:], mode="nearest")))
+        else:
+            p2 = self.smooth2(self.activation(self.lateral2(s2)))
+        # objectness, dx, dy, normalized width, normalized height — MERG-Det layout
+        return torch.cat(
+            (self.objectness_head(self.objectness_branch(p2)), self.geometry_head(self.geometry_branch(p2))), dim=1
+        )