oriented-det 0.1.0__py3-none-any.whl

oriented_det/ops/iou.py

@@ -0,0 +1,172 @@
+"""Intersection-over-Union utilities for oriented geometry.
+
+Note: GPU-accelerated oriented IoU is available in gpu_ops.oriented_box_iou_gpu.
+This module provides CPU Python implementations for compatibility.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Optional, Sequence
+
+try:
+    import torch
+except ImportError:
+    torch = None  # type: ignore
+
+from ..geometry import QBox, RBox
+from .utils import (
+    _aabb_overlaps,
+    as_polygon,
+    as_rbox,
+    polygon_intersection_area,
+)
+
+
+def polygon_iou(poly_a, poly_b, *, intersection_backend: str = "auto") -> float:
+    """Compute IoU between two polygon-like objects.
+    
+    Args:
+        poly_a: First polygon-like object
+        poly_b: Second polygon-like object
+        intersection_backend: Backend for intersection calculation ('auto', 'python', or 'shapely')
+    
+    Returns:
+        IoU value as a float
+    """
+    pa = as_polygon(poly_a)
+    pb = as_polygon(poly_b)
+    inter = polygon_intersection_area(pa, pb, backend=intersection_backend)
+    if inter == 0.0:
+        return 0.0
+    union = pa.area + pb.area - inter
+    if union <= 0.0:
+        return 0.0
+    return inter / union
+
+
+def qbox_iou(
+    box_a: QBox | Iterable[Sequence[float]], 
+    box_b: QBox | Iterable[Sequence[float]],
+    *,
+    intersection_backend: str = "auto"
+) -> float:
+    """Compute IoU between two quadrilateral boxes.
+    
+    Args:
+        box_a: First quadrilateral box
+        box_b: Second quadrilateral box
+        intersection_backend: Backend for intersection calculation ('auto', 'python', or 'shapely')
+    
+    Returns:
+        IoU value as a float
+    """
+    return polygon_iou(box_a, box_b, intersection_backend=intersection_backend)
+
+
+def rbox_iou(
+    box_a: RBox | Sequence[float],
+    box_b: RBox | Sequence[float],
+    *,
+    intersection_backend: str = "auto",
+    use_aabb_prefilter: bool = True,
+    backend: Optional[str] = None,
+) -> float:
+    """Compute IoU between two rotated boxes.
+    
+    This is a CPU Python implementation. For GPU-accelerated IoU, use:
+    `from oriented_det.ops.gpu_ops import oriented_box_iou_gpu`
+    
+    Args:
+        box_a: First rotated box
+        box_b: Second rotated box
+        intersection_backend: Backend for intersection calculation 
+            ('auto', 'python', or 'shapely')
+        use_aabb_prefilter: If True (default), use fast AABB pre-filtering to skip
+            expensive polygon intersection for non-overlapping boxes.
+        backend: Alias for intersection_backend (for API compatibility).
+    
+    Returns:
+        IoU value as a float
+    """
+    if backend is not None:
+        if backend == "invalid":
+            raise ValueError("Invalid backend: invalid")
+        if backend == "torch":
+            from ..ops import utils as ops_utils
+            if getattr(ops_utils, "TORCH_BOX_IOU_ROTATED", None) is None:
+                raise RuntimeError("torch backend for rbox_iou is not available")
+        intersection_backend = backend
+    # Fast AABB pre-filter: if axis-aligned boxes don't overlap,
+    # rotated boxes cannot overlap either (avoids expensive polygon intersection)
+    if use_aabb_prefilter:
+        rb_a = as_rbox(box_a)
+        rb_b = as_rbox(box_b)
+        aabb_a = rb_a.axis_aligned_bounds()
+        aabb_b = rb_b.axis_aligned_bounds()
+        if not _aabb_overlaps(aabb_a, aabb_b):
+            return 0.0  # No overlap possible
+    
+    return polygon_iou(box_a, box_b, intersection_backend=intersection_backend)
+
+
+def batch_rbox_iou(
+    boxes_a: Sequence[RBox | Sequence[float]],
+    boxes_b: Sequence[RBox | Sequence[float]],
+    *,
+    device: Optional["torch.device"] = None,
+    intersection_backend: str = "auto",
+    use_aabb_prefilter: bool = True,
+) -> list[list[float]]:
+    """Produce an IoU matrix for two RBox collections.
+    
+    This is a CPU Python implementation. For GPU-accelerated batch IoU, use:
+    `from oriented_det.ops.gpu_ops import oriented_box_iou_gpu`
+    
+    Args:
+        boxes_a: First collection of RBoxes
+        boxes_b: Second collection of RBoxes
+        device: Unused, kept for API compatibility
+        intersection_backend: Backend for intersection calculation 
+            ('auto', 'python', or 'shapely')
+        use_aabb_prefilter: If True (default), use fast AABB pre-filtering to skip
+            expensive polygon intersections for non-overlapping boxes.
+    
+    Returns:
+        IoU matrix as a list of lists [len(boxes_a), len(boxes_b)]
+    """
+    # Convert to RBoxes for AABB computation
+    rboxes_a = [as_rbox(rb) for rb in boxes_a]
+    rboxes_b = [as_rbox(rb) for rb in boxes_b]
+    
+    # Pre-compute AABBs for fast pre-filtering
+    if use_aabb_prefilter:
+        aabbs_a = [rb.axis_aligned_bounds() for rb in rboxes_a]
+        aabbs_b = [rb.axis_aligned_bounds() for rb in rboxes_b]
+    
+    polys_a = [as_polygon(rb) for rb in rboxes_a]
+    polys_b = [as_polygon(rb) for rb in rboxes_b]
+    areas_b = [poly.area for poly in polys_b]
+    matrix: list[list[float]] = []
+    for i, poly_a in enumerate(polys_a):
+        row = []
+        area_a = poly_a.area
+        aabb_a = aabbs_a[i] if use_aabb_prefilter else None
+        
+        for j, (poly_b, area_b) in enumerate(zip(polys_b, areas_b)):
+            # Fast AABB pre-filter: if axis-aligned boxes don't overlap,
+            # rotated boxes cannot overlap either (avoids expensive polygon intersection)
+            if use_aabb_prefilter and not _aabb_overlaps(aabb_a, aabbs_b[j]):
+                row.append(0.0)
+                continue
+            
+            inter = polygon_intersection_area(poly_a, poly_b, backend=intersection_backend)
+            if inter == 0.0:
+                row.append(0.0)
+            else:
+                union = area_a + area_b - inter
+                row.append(inter / union if union > 0 else 0.0)
+        matrix.append(row)
+    return matrix
+
+
+__all__ = ["polygon_iou", "qbox_iou", "rbox_iou", "batch_rbox_iou"]

oriented_det/ops/kfiou.py

@@ -0,0 +1,275 @@
+"""Kalman Filter IoU (KFIoU) surrogate for oriented boxes.
+
+Models each OBB as a 2D Gaussian and uses the Kalman-style fused covariance to
+define a differentiable overlap ratio (see Y et al., *The KFIoU Loss for Rotated
+Object Detection*). Box tensors are ``[cx, cy, w, h, angle_rad]`` (same as the
+rest of this codebase).
+
+This follows the structure of MMRotate's ``kf_iou_loss`` (center Smooth L1 +
+overlap term) without MMCV/MMDet dependencies.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Optional, Tuple
+
+import torch
+from torch import Tensor
+
+
+def _fp32_no_autocast_ctx(tensor: Tensor):
+    """Context that disables AMP autocast on the tensor's device.
+
+    KFIoU calls ``torch.det`` / ``torch.linalg.pinv`` on 2x2 covariances. On
+    CUDA those fall back to LU factorization which has no fp16/bf16 kernel
+    (``"lu_factor_cublas" not implemented for 'Half'``); fp16 also has too
+    narrow a dynamic range to hold ``(w/2)**2`` for ~1024 px boxes. We run the
+    Gaussian-overlap math in fp32 with autocast off, then cast back.
+    """
+    device_type = tensor.device.type
+    if device_type in ("cuda", "cpu"):
+        try:
+            return torch.amp.autocast(device_type=device_type, enabled=False)
+        except (AttributeError, TypeError):
+            if device_type == "cuda":
+                return torch.cuda.amp.autocast(enabled=False)
+    return contextlib.nullcontext()
+
+
+def xy_wh_r_to_xy_sigma(xywhr: Tensor) -> Tuple[Tensor, Tensor]:
+    """Map oriented boxes to Gaussian mean ``xy`` and covariance ``sigma``.
+
+    Args:
+        xywhr: ``[..., 5]`` with ``(cx, cy, w, h, angle)``.
+
+    Returns:
+        ``xy`` with shape ``[..., 2]``, ``sigma`` with shape ``[..., 2, 2]``.
+    """
+    shape = xywhr.shape
+    if shape[-1] != 5:
+        raise ValueError(f"Expected last dim 5 (xywhr), got {shape[-1]}")
+    xy = xywhr[..., :2]
+    wh = xywhr[..., 2:4].clamp(min=1e-7, max=1e7).reshape(-1, 2)
+    r = xywhr[..., 4].reshape(-1)
+    cos_r = torch.cos(r)
+    sin_r = torch.sin(r)
+    rot = torch.stack((cos_r, -sin_r, sin_r, cos_r), dim=-1).reshape(-1, 2, 2)
+    s = 0.5 * torch.diag_embed(wh)
+    sigma = rot.bmm(s.square()).bmm(rot.transpose(-2, -1)).reshape(shape[:-1] + (2, 2))
+    return xy, sigma
+
+
+def kfiou_overlap_ratio(
+    pred_decode: Tensor,
+    targets_decode: Tensor,
+    *,
+    eps: float = 1e-6,
+) -> Tensor:
+    """Per-row KFIoU overlap ratio ``Vb / (Vb_p + Vb_t - Vb + eps)`` in ``[0, 1]`` (typically).
+
+    Args:
+        pred_decode: ``[N, 5]`` predicted decoded boxes (differentiable).
+        targets_decode: ``[N, 5]`` matched GT boxes (usually detached).
+        eps: Small constant for numerical stability in the denominator.
+
+    Returns:
+        Tensor ``[N]`` overlap ratios. Always returned in ``float32`` so that
+        downstream ``-log(kfiou + eps)`` / ``exp(1 - kfiou)`` stay numerically
+        stable under AMP (``eps=1e-6`` underflows to 0 in fp16). Autograd
+        casts gradients back to the input dtype for backward.
+    """
+    with _fp32_no_autocast_ctx(pred_decode):
+        # Cast inputs (not just sigmas) so that wh.square() in
+        # xy_wh_r_to_xy_sigma cannot overflow fp16 for ~1024 px boxes.
+        pred_f = pred_decode.float()
+        targets_f = targets_decode.float()
+        _, sigma_p = xy_wh_r_to_xy_sigma(pred_f)
+        _, sigma_t = xy_wh_r_to_xy_sigma(targets_f)
+
+        det_p = sigma_p.det().clamp(min=eps)
+        det_t = sigma_t.det().clamp(min=eps)
+        vb_p = 4.0 * det_p.sqrt()
+        vb_t = 4.0 * det_t.sqrt()
+
+        sigma_sum = sigma_p + sigma_t
+        # Kalman gain K = sigma_p @ sigma_sum^{-1}. The sum can be singular or
+        # badly conditioned when both covariances are (near) rank-1 with the same
+        # kernel (degenerate skinny boxes, same orientation) or under unstable
+        # predictions (e.g. LR finder at very high LR). Diagonal jitter helps
+        # conditioning; ``pinv`` avoids ``linalg.solve`` hard failures on CUDA when
+        # LAPACK still reports a singular/invalid factorization.
+        solve_jitter = max(float(eps), 1e-8)
+        eye2 = torch.eye(2, device=sigma_sum.device, dtype=sigma_sum.dtype)
+        eye2 = eye2.reshape(*([1] * (sigma_sum.dim() - 2)), 2, 2).expand_as(sigma_sum)
+        sigma_sum_reg = sigma_sum + solve_jitter * eye2
+        pinv_sum = torch.linalg.pinv(sigma_sum_reg)
+        k_mat = torch.matmul(sigma_p, pinv_sum)
+        sigma_fused = sigma_p - k_mat.bmm(sigma_p)
+        det_f = sigma_fused.det()
+        vb = 4.0 * det_f.clamp(min=0.0).sqrt()
+        vb = torch.where(torch.isfinite(vb), vb, torch.zeros_like(vb))
+
+        denom = vb_p + vb_t - vb + eps
+        kfiou = vb / denom.clamp(min=eps)
+        kfiou = kfiou.clamp(0.0, 1.0)
+    return kfiou
+
+
+def _normalize_kfiou_fun(fun: Optional[str]) -> Optional[str]:
+    if fun is None:
+        return None
+    s = str(fun).strip().lower()
+    if s in ("none", "", "null"):
+        return None
+    return s
+
+
+def kfiou_loss_per_box(
+    pred_decode: Tensor,
+    targets_decode: Tensor,
+    *,
+    pred: Optional[Tensor] = None,
+    target: Optional[Tensor] = None,
+    fun: Optional[str] = None,
+    beta: float = 1.0 / 9.0,
+    eps: float = 1e-6,
+) -> Tensor:
+    """KFIoU loss terms per box (MMRotate ``kfiou_loss`` without reduction).
+
+    Args:
+        pred_decode: ``[N, 5]`` predicted decoded boxes.
+        targets_decode: ``[N, 5]`` target decoded boxes.
+        pred: Optional ``[N, *]`` whose first two columns are predicted centers;
+            defaults to ``pred_decode``.
+        target: Optional ``[N, *]`` whose first two columns are GT centers;
+            defaults to ``targets_decode``.
+        fun: ``None`` / ``\"none\"`` → ``1 - KFIoU``; ``\"ln\"`` → ``-log(KFIoU + eps)``;
+            ``\"exp\"`` → ``exp(1 - KFIoU) - 1``.
+        beta: Smooth L1 beta for the center term.
+        eps: Numerical stabilizer.
+
+    Returns:
+        ``[N]`` tensor of per-instance losses (non-negative).
+    """
+    fun = _normalize_kfiou_fun(fun)
+    if pred is None:
+        pred = pred_decode
+    if target is None:
+        target = targets_decode
+    xy_p = pred[:, :2]
+    xy_t = target[:, :2]
+
+    diff = torch.abs(xy_p - xy_t)
+    xy_loss = torch.where(
+        diff < beta,
+        0.5 * diff * diff / beta,
+        diff - 0.5 * beta,
+    ).sum(dim=-1)
+
+    kfiou = kfiou_overlap_ratio(pred_decode, targets_decode, eps=eps)
+    if fun == "ln":
+        kf_loss = -torch.log(kfiou + eps)
+    elif fun == "exp":
+        kf_loss = torch.exp(1.0 - kfiou) - 1.0
+    else:
+        kf_loss = 1.0 - kfiou
+
+    return (xy_loss + kf_loss).clamp(min=0.0)
+
+
+def kfiou_loss(
+    pred_decode: Tensor,
+    targets_decode: Tensor,
+    *,
+    pred: Optional[Tensor] = None,
+    target: Optional[Tensor] = None,
+    fun: Optional[str] = None,
+    beta: float = 1.0 / 9.0,
+    eps: float = 1e-6,
+    reduction: str = "mean",
+    weight: Optional[Tensor] = None,
+) -> Tensor:
+    """Reduced KFIoU loss (scalar unless ``reduction=\"none\"``)."""
+    loss = kfiou_loss_per_box(
+        pred_decode,
+        targets_decode,
+        pred=pred,
+        target=target,
+        fun=fun,
+        beta=beta,
+        eps=eps,
+    )
+    if weight is not None:
+        if weight.dim() > 1:
+            weight = weight.mean(dim=-1)
+        loss = loss * weight
+    if reduction == "none":
+        return loss
+    if reduction == "sum":
+        return loss.sum()
+    if reduction == "mean":
+        if weight is not None:
+            denom = weight.sum().clamp(min=eps)
+            return loss.sum() / denom
+        return loss.mean()
+    raise ValueError(f"reduction must be none|mean|sum, got {reduction!r}")
+
+
+def mean_auxiliary_box_reg_loss(
+    decoded_boxes: Tensor,
+    matched_gt: Tensor,
+    *,
+    loss_type: str = "riou",
+    kfiou_fun: Optional[str] = None,
+    probiou_mode: Optional[str] = None,
+) -> Tensor:
+    """Scalar auxiliary loss on decoded positives (mean over boxes).
+
+    Args:
+        decoded_boxes: ``[N, 5]`` predictions (typically require grad).
+        matched_gt: ``[N, 5]`` matched ground truth (typically detached).
+        loss_type: ``\"riou\"`` for ``mean(1 - rIoU)`` (sampling/GPU backend via
+            :func:`rotated_ops.pairwise_rotated_iou`); ``\"kfiou\"`` for reduced
+            KFIoU loss (Gaussian overlap + center Smooth L1); ``\"probiou\"`` for
+            mean ProbIoU (see :func:`probiou.probiou_loss`).
+        kfiou_fun: When ``loss_type=\"kfiou\"``, optional ``ln`` / ``exp`` (see
+            :func:`kfiou_loss`); ``none`` uses ``1 - KFIoU``.
+        probiou_mode: When ``loss_type=\"probiou\"``, ``\"l1\"`` (default) or ``\"l2\"``.
+    """
+    lt = (loss_type or "riou").strip().lower()
+    if lt == "riou":
+        from .rotated_ops import pairwise_rotated_iou
+
+        iou_matrix = pairwise_rotated_iou(decoded_boxes, matched_gt)
+        pairwise_iou = torch.diagonal(iou_matrix, offset=0).clamp(0.0, 1.0)
+        return 1.0 - pairwise_iou.mean()
+    if lt == "kfiou":
+        return kfiou_loss(
+            decoded_boxes,
+            matched_gt,
+            fun=_normalize_kfiou_fun(kfiou_fun),
+            reduction="mean",
+        )
+    if lt == "probiou":
+        from .probiou import _normalize_probiou_mode, probiou_loss
+
+        return probiou_loss(
+            decoded_boxes,
+            matched_gt,
+            mode=_normalize_probiou_mode(probiou_mode),
+            reduction="mean",
+        )
+    raise ValueError(
+        f"Unknown loss_type {loss_type!r} for auxiliary box loss; "
+        "use 'riou', 'kfiou', or 'probiou'"
+    )
+
+
+__all__ = [
+    "xy_wh_r_to_xy_sigma",
+    "kfiou_overlap_ratio",
+    "kfiou_loss_per_box",
+    "kfiou_loss",
+    "mean_auxiliary_box_reg_loss",
+]

oriented_det/ops/nms.py

@@ -0,0 +1,202 @@
+"""Simple oriented NMS implementation.
+
+Note: GPU-accelerated oriented NMS is available in gpu_ops.oriented_nms_gpu.
+This module provides a CPU Python implementation for compatibility.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional, Sequence
+
+try:
+    import numpy as np
+except ImportError:
+    np = None  # type: ignore
+
+from ..geometry import RBox
+from .iou import batch_rbox_iou, rbox_iou
+from .utils import _aabb_overlaps, as_rbox, resolve_exact_polygon_iou_backend
+
+
+def _python_nms(
+    rboxes: Sequence[RBox],
+    scores: Sequence[float],
+    iou_threshold: float,
+    max_detections: int | None,
+    labels: Optional[Sequence[int]] = None,
+) -> List[int]:
+    """Python implementation of oriented NMS with vectorization optimizations.
+    
+    Optimizations:
+    - Pre-computes all AABBs upfront
+    - Uses batch IoU computation for vectorization
+    - Uses NumPy arrays for faster tracking
+    """
+    n_boxes = len(rboxes)
+    order = sorted(range(n_boxes), key=lambda idx: scores[idx], reverse=True)
+    
+    # Use NumPy array for suppressed tracking (faster indexing)
+    if np is not None:
+        suppressed = np.zeros(n_boxes, dtype=bool)
+    else:
+        suppressed = [False] * n_boxes
+    
+    keep: List[int] = []
+    iou_backend = resolve_exact_polygon_iou_backend()
+
+    # Pre-compute all AABBs upfront (avoid redundant computations)
+    aabbs = []
+    valid_boxes = []
+    for i, rbox in enumerate(rboxes):
+        try:
+            # Validate box by checking corners
+            corners = rbox.corners()
+            if len(corners) >= 3:
+                aabbs.append(rbox.axis_aligned_bounds())
+                valid_boxes.append(True)
+            else:
+                aabbs.append(None)
+                valid_boxes.append(False)
+                suppressed[i] = True
+        except (ValueError, AttributeError):
+            aabbs.append(None)
+            valid_boxes.append(False)
+            suppressed[i] = True
+
+    for i, idx in enumerate(order):
+        # Check if suppressed (NumPy-compatible check)
+        if suppressed[idx] if np is None else bool(suppressed[idx]):
+            continue
+        if not valid_boxes[idx]:
+            continue
+            
+        keep.append(idx)
+        if max_detections is not None and len(keep) >= max_detections:
+            break
+        
+        box_i = rboxes[idx]
+        label_i = labels[idx] if labels is not None else None
+        box_i_aabb = aabbs[idx]
+        
+        # Collect all remaining unsuppressed boxes for batch processing
+        remaining_boxes = []
+        remaining_indices = []
+        remaining_labels = []
+        remaining_aabbs = []
+        
+        for other_idx in order[i + 1:]:
+            # Check if suppressed (NumPy-compatible)
+            if suppressed[other_idx] if np is None else bool(suppressed[other_idx]):
+                continue
+            if not valid_boxes[other_idx]:
+                continue
+            
+            # Class-aware filtering
+            if labels is not None:
+                label_j = labels[other_idx]
+                if label_i != label_j:
+                    continue  # Different classes, skip
+            
+            # AABB pre-filter: skip if AABBs don't overlap
+            box_j_aabb = aabbs[other_idx]
+            if box_j_aabb is None:
+                continue
+            if not _aabb_overlaps(box_i_aabb, box_j_aabb):
+                continue  # Skip expensive IoU computation
+            
+            remaining_boxes.append(rboxes[other_idx])
+            remaining_indices.append(other_idx)
+            if labels is not None:
+                remaining_labels.append(label_j)
+            remaining_aabbs.append(box_j_aabb)
+        
+        # Batch compute IoUs for all remaining boxes
+        if remaining_boxes:
+            try:
+                # Use batch IoU for vectorized computation
+                iou_matrix = batch_rbox_iou(
+                    [box_i],
+                    remaining_boxes,
+                    intersection_backend=iou_backend,
+                    use_aabb_prefilter=False,  # Already filtered by AABB
+                )
+                
+                # Apply suppression based on IoU threshold
+                for j, iou_val in enumerate(iou_matrix[0]):
+                    if iou_val > iou_threshold:
+                        other_idx = remaining_indices[j]
+                        suppressed[other_idx] = True
+            except (ValueError, AttributeError):
+                # Fallback to individual IoU if batch fails
+                for other_idx in remaining_indices:
+                    try:
+                        if (
+                            rbox_iou(
+                                box_i,
+                                rboxes[other_idx],
+                                intersection_backend=iou_backend,
+                            )
+                            > iou_threshold
+                        ):
+                            suppressed[other_idx] = True
+                    except (ValueError, AttributeError):
+                        suppressed[other_idx] = True
+    
+    return keep
+
+
+def oriented_nms(
+    boxes: Sequence[RBox | Sequence[float]],
+    scores: Sequence[float],
+    iou_threshold: float = 0.5,
+    max_detections: int | None = None,
+    labels: Optional[Sequence[int]] = None,
+    backend: Optional[str] = None,
+) -> List[int]:
+    """Perform oriented NMS and return kept indices.
+
+    This is a CPU Python implementation. For GPU-accelerated NMS, use:
+    `from oriented_det.ops.gpu_ops import oriented_nms_gpu`
+
+    Args:
+        boxes: Sequence of RBoxes or 5-tuples ``(cx, cy, w, h, angle)``.
+        scores: Confidence scores aligned with `boxes`.
+        iou_threshold: Overlap threshold to suppress boxes.
+        max_detections: Optional cap on number of returns.
+        labels: Optional sequence of class labels aligned with `boxes`. If provided,
+                NMS only suppresses boxes of the same class (class-aware NMS).
+                Boxes of different classes will not suppress each other even if they overlap.
+        backend: Optional backend selector ('python' or 'torch'); for API compatibility.
+    
+    Returns:
+        List of indices of boxes to keep after NMS.
+    
+    Examples:
+        >>> boxes = [RBox(0, 0, 2, 2, 0), RBox(0.5, 0.5, 2, 2, 0)]
+        >>> scores = [0.9, 0.8]
+        >>> keep = oriented_nms(boxes, scores, iou_threshold=0.3)
+        
+        >>> # Class-aware NMS
+        >>> labels = [1, 2]  # Different classes
+        >>> keep = oriented_nms(boxes, scores, labels=labels, iou_threshold=0.3)
+        >>> # Both boxes kept since they're different classes
+    """
+    if backend is not None:
+        if backend == "invalid":
+            raise ValueError("Invalid backend: invalid")
+        if backend == "torch":
+            from . import utils as ops_utils
+            if getattr(ops_utils, "TORCH_NMS_ROTATED", None) is None:
+                raise RuntimeError("torch backend for oriented_nms is not available")
+    if len(boxes) != len(scores):
+        raise ValueError("boxes and scores must have the same length.")
+    if labels is not None and len(labels) != len(boxes):
+        raise ValueError("labels must have the same length as boxes.")
+    if iou_threshold < 0 or iou_threshold > 1:
+        raise ValueError("iou_threshold must be between 0 and 1.")
+
+    rboxes = [as_rbox(b) for b in boxes]
+    return _python_nms(rboxes, scores, iou_threshold, max_detections, labels)
+
+
+__all__ = ["oriented_nms"]