MGIoU

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

(★ 23)

Official Implementation of Marginalized Generalized IOU (MGIoU)

MGIoU Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Marginalized Generalized IoU (MGIoU): Unifying Parametric Shape Optimization
A PyTorch implementation of **MGIoU**, **MGIoU⁺**, and **MGIoU⁻** for 2D and 3D object detection and collision-aware trajectory prediction.
<p align="center">
  <a href="https://ldtho.github.io/MGIoU/" target="_blank">
    <img src="https://img.shields.io/badge/Project&nbsp;Page-MGIoU-blue?logo=githubpages&logoColor=white" alt="Project Page">
  </a>
&nbsp;
  <a href="https://arxiv.org/abs/2504.16443" target="_blank">
    <img src="https://img.shields.io/badge/ArXiv-2504.16443-B31B1B?logo=arxiv&logoColor=white" alt="arXiv">
  </a>
&nbsp;
  <a href="https://pypi.org/project/MGIoU/0.1.0/" target="_blank">
    <img src="https://img.shields.io/pypi/v/MGIoU?label=PyPI&logo=pypi&logoColor=white&color=brightgreen" alt="PyPI">
  </a>
</p>

---

### 🎉 **Accepted to AAAI 2026 (Oral Presentation)!** 🎉

</div>

---

## TODO / Road-map
- [x] **v0.1.0** • Release MGIoU, MGIoU⁺, MGIoU⁻  
- [x] Release PyPI package and samples.  
- [ ] Sub-repos for experiments in the paper  
  - [ ] 3D Rotated Object Detection  
  - [ ] 2D Rotated Object Detection  
  - [ ] 2D Quadrangle Detection

*PRs and feature requests are welcome!*

---

## Installation

### Requirements
* PyTorch ≥ 1.12 (≥ 2.0 to use built-in `torch.vmap`; otherwise we transparently fall back to **functorch**)

### 💡 Option 1 — via **pip** (recommended)

```bash
pip install mgiou          # pulls the latest release from PyPI
```
### 💡 Option 2 — from source
```bash
git clone https://github.com/ldtho/MGIoU.git
cd MGIoU
pip install -e .           # editable install for development
```

## Quickstart

```python
import torch
from mgiou import MGIoU3D, MGIoU2D, MGIoU2DPlus, MGIoU2DMinus

# -------------------------------------------------------------------------
# 3-D MGIoU
# -------------------------------------------------------------------------
B = 4
pred_3d   = torch.rand(B, 8, 3)  # 8 corners per box (v0–v7 in the order described below)
target_3d = torch.rand(B, 8, 3)
#          v4_____________________v5
#           /|                    /|
#          / |                   / |
#         /  |                  /  |
#        /___|_________________/   |
#    v0 |    |              v1 |   |
#       |    |                 |   |
#       |    |                 |   |
#       |    |                 |   |
#       |    |_________________|___|
#       |   / v7               |   /v6
#       |  /                   |  /
#       | /                    | /
#       |/_____________________|/
#      v3                     v2
#
#    MGIOU3D assumes **v0-v1**, **v0-v3**, **v0-v4** form the three face normals.

# default: mean reduction, fast_mode=False
loss3d = MGIoU3D()  
print("MGIoU-3D loss (mean over batch):", loss3d(pred_3d, target_3d))

# you can change reduction or enable fast projections:
loss3d_sum = MGIoU3D(reduction="sum", fast_mode=True)
print("MGIoU-3D loss (sum):", loss3d_sum(pred_3d, target_3d))

# -------------------------------------------------------------------------
# 2-D rotated rectangles
# -------------------------------------------------------------------------
# one box in (x, y, w, h, θ) format
pred_boxes = torch.tensor([[0.0, 0.0, 4.0, 2.0, 0.3]], dtype=torch.float32)
tgt_boxes  = torch.tensor([[0.0, 0.0, 4.0, 2.0, 0.0]], dtype=torch.float32)

# default: "rect" representation (x, y, w, h, θ), mean reduction
loss2d = MGIoU2D()
print("MGIoU-2D loss (rect):", loss2d(pred_boxes, tgt_boxes))

# corner mode: supply (B,4,2) directly
corners1 = loss2d._rect_to_corners(pred_boxes)  # reuse helper
corners2 = loss2d._rect_to_corners(tgt_boxes)
loss2d_corner = MGIoU2D(representation="corner", reduction="none")
print("Per-sample MGIoU-2D (corners, none):", loss2d_corner(corners1, corners2))

# override reduction at call-time
print("Same, but summed over batch:",
      MGIoU2D(reduction="none")(pred_boxes, tgt_boxes, reduction_override="sum"))

# -------------------------------------------------------------------------
# 2-D quadrangles with convexity penalty (MGIoU⁺)
# -------------------------------------------------------------------------
pred_quads   = torch.rand(B, 4, 2)
target_quads = torch.rand(B, 4, 2)

# w=0.3 convexity weight, default mean reduction
loss_plus = MGIoU2DPlus(convex_weight=0.3)
print("MGIoU-quad⁺ loss (mean):", loss_plus(pred_quads, target_quads).item())

# sum reduction, fast mode
loss_plus_sum = MGIoU2DPlus(convex_weight=0.3, fast_mode=True, reduction="sum")
print("MGIoU-quad⁺ loss (sum):", loss_plus_sum(pred_quads, target_quads))

# -------------------------------------------------------------------------
# Pairwise MGIoU⁻ (MGIoU2DMinus)
# -------------------------------------------------------------------------
# Using rotated-rect inputs
pairwise_rect = MGIoU2DMinus(representation="rect")(pred_boxes.repeat(B,1))
print("Pairwise MGIoU⁻ matrix (rect):\n", pairwise_rect)

# Using explicit corners and summing all off-diagonals
pairwise_corner_sum = MGIoU2DMinus(
    representation="corner", reduction="sum"
)(corners1.repeat(B,1,1))
print("Sum of all off-diagonal MGIoU⁻:", pairwise_corner_sum.item())
```

## API at a glance
```text
# 3-D boxes as 8 corner points → per-sample loss
MGIoU3D(
    reduction: str = "mean",     # "none" | "mean" | "sum"
    fast_mode: bool = False
)

# 2-D rotated rectangles or explicit corners → per-sample loss
MGIoU2D(
    representation: str = "rect", # "rect" | "corner"
    reduction: str = "mean",      # "none" | "mean" | "sum"
    loss_weight: float = 1.0,
    fast_mode: bool = False
)

# 2-D arbitrary convex quads + convexity penalty → per-sample loss
MGIoU2DPlus(
    convex_weight: float = 0.0,   # 0 = pure MGIoU, >0 adds convexity penalty
    fast_mode: bool = False,
    reduction: str = "mean"       # "none" | "mean" | "sum"
)

# Pairwise MGIoU⁻ matrix → scalar or tensor
MGIoU2DMinus(
    representation: str = "rect", # "rect" | "corner"
    fast_mode: bool = False,
    reduction: str = "mean"       # "none" | "mean" | "sum"
)
```

## Citation 
If you find this repo useful, please cite
```bibtex
@article{le2025marginalized,
  title={Marginalized Generalized IoU (MGIoU): A Unified Objective Function for Optimizing Any Convex Parametric Shapes},
  author={Le, Duy-Tho and Pham, Trung and Cai, Jianfei and Rezatofighi, Hamid},
  journal={arXiv preprint arXiv:2504.16443},
  year={2025}
}
```

## License
This project is licensed under the terms of the MIT license.

MGIoU

MGIoU Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

MGIoU

MGIoU Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README