Reference for ultralytics/nn/modules/head.py#

class Detect(nn.Module):
    """YOLO Detect head for object detection models.

    This class implements the detection head used in YOLO models for predicting bounding boxes and class probabilities.
    It supports both training and inference modes, with optional end-to-end detection capabilities.

    Attributes:
        dynamic (bool): Force grid reconstruction.
        export (bool): Export mode flag.
        format (str): Export format.
        end2end (bool): End-to-end detection mode.
        max_det (int): Maximum detections per image.
        agnostic_nms (bool): Whether to select top-k detections class-agnostically in end-to-end mode.
        shape (tuple): Input shape.
        anchors (torch.Tensor): Anchor points.
        strides (torch.Tensor): Feature map strides.
        legacy (bool): Backward compatibility for v3/v5/v8/v9 models.
        xyxy (bool): Output format, xyxy or xywh.
        nc (int): Number of classes.
        nl (int): Number of detection layers.
        reg_max (int): DFL channels.
        no (int): Number of outputs per anchor.
        stride (torch.Tensor): Strides computed during build.
        cv2 (nn.ModuleList): Convolution layers for box regression.
        cv3 (nn.ModuleList): Convolution layers for classification.
        dfl (nn.Module): Distribution Focal Loss layer.
        one2one_cv2 (nn.ModuleList): One-to-one convolution layers for box regression.
        one2one_cv3 (nn.ModuleList): One-to-one convolution layers for classification.

    Methods:
        forward: Perform forward pass and return predictions.
        bias_init: Initialize detection head biases.
        decode_bboxes: Decode bounding boxes from predictions.
        postprocess: Post-process model predictions.

    Examples:
        Create a detection head for 80 classes
        >>> detect = Detect(nc=80, ch=(256, 512, 1024))
        >>> x = [torch.randn(1, 256, 80, 80), torch.randn(1, 512, 40, 40), torch.randn(1, 1024, 20, 20)]
        >>> outputs = detect(x)
    """

    dynamic = False  # force grid reconstruction
    export = False  # export mode
    format = None  # export format
    max_det = 300  # max_det
    agnostic_nms = False
    shape = None
    anchors = torch.empty(0)  # init
    strides = torch.empty(0)  # init
    legacy = False  # backward compatibility for v3/v5/v8/v9 models
    xyxy = False  # xyxy or xywh output

    @staticmethod
    def _grouped_topk(x: torch.Tensor, k: int, groups: int = 8) -> tuple[torch.Tensor, torch.Tensor]:
        """Select exact top-k values through smaller grouped selections."""
        n = x.shape[1]
        while groups > 1 and (n % groups or n // groups < k):
            groups //= 2
        if groups == 1:  # nothing to gain, e.g. a short axis or one that does not divide evenly
            return x.topk(k, dim=1)
        size = n // groups
        values, index = x.reshape(x.shape[0], groups, size).topk(k, dim=-1)
        values, winners = values.flatten(1).topk(k, dim=1)
        return values, winners // k * size + index.flatten(1).gather(1, winners)

    def _gather(self, x: torch.Tensor, index: torch.Tensor) -> torch.Tensor:
        """Select index (batch, k) rows of x (batch, n, channels) along dim 1."""
        return x.gather(1, index if x.ndim == 2 else index[..., None].expand(-1, -1, x.shape[-1]))

    def __init__(self, nc: int = 80, reg_max: int = 16, end2end: bool = False, ch: list[int] | tuple[int, ...] = ()):
        """Initialize the YOLO detection layer with specified number of classes and channels.

        Args:
            nc (int): Number of classes.
            reg_max (int): Maximum number of DFL channels.
            end2end (bool): Whether to use end-to-end NMS-free detection.
            ch (list[int] | tuple[int, ...]): Channel sizes from backbone feature maps.
        """
        super().__init__()
        self.nc = nc  # number of classes
        self.nl = len(ch)  # number of detection layers
        self.reg_max = reg_max  # DFL channels
        self.no = nc + self.reg_max * 4  # number of outputs per anchor
        self.stride = torch.zeros(self.nl)  # strides computed during build
        c2, c3 = max((16, ch[0] // 4, self.reg_max * 4)), max(ch[0], min(self.nc, 100))  # channels
        self.cv2 = nn.ModuleList(
            nn.Sequential(Conv(x, c2, 3), Conv(c2, c2, 3), nn.Conv2d(c2, 4 * self.reg_max, 1)) for x in ch
        )
        self.cv3 = (
            nn.ModuleList(nn.Sequential(Conv(x, c3, 3), Conv(c3, c3, 3), nn.Conv2d(c3, self.nc, 1)) for x in ch)
            if self.legacy
            else nn.ModuleList(
                nn.Sequential(
                    nn.Sequential(DWConv(x, x, 3), Conv(x, c3, 1)),
                    nn.Sequential(DWConv(c3, c3, 3), Conv(c3, c3, 1)),
                    nn.Conv2d(c3, self.nc, 1),
                )
                for x in ch
            )
        )
        self.dfl = DFL(self.reg_max) if self.reg_max > 1 else nn.Identity()

        if end2end:
            self.one2one_cv2 = copy.deepcopy(self.cv2)
            self.one2one_cv3 = copy.deepcopy(self.cv3)

@property
def one2many(self):
    """Return the one-to-many head components, here for v3/v5/v8/v9/v11 backward compatibility."""
    return {"box_head": self.cv2, "cls_head": self.cv3}

@property
def one2one(self):
    """Return the one-to-one head components."""
    return {"box_head": self.one2one_cv2, "cls_head": self.one2one_cv3}

@property
def end2end(self):
    """Select one-to-one inference when requested or when fusion has removed the one-to-many head."""
    return getattr(self, "one2one_cv2", None) is not None and (getattr(self, "_end2end", False) or self.cv2 is None)

def _gather(self, x: torch.Tensor, index: torch.Tensor) -> torch.Tensor:
    """Select index (batch, k) rows of x (batch, n, channels) along dim 1."""
    return x.gather(1, index if x.ndim == 2 else index[..., None].expand(-1, -1, x.shape[-1]))

def _get_decode_boxes(self, x: dict[str, torch.Tensor]) -> torch.Tensor:
    """Get decoded boxes based on anchors and strides."""
    shape = x["feats"][0].shape  # BCHW
    if self.dynamic or self.shape != shape:
        self.anchors, self.strides = (a.transpose(0, 1) for a in make_anchors(x["feats"], self.stride, 0.5))
        self.shape = shape

    dbox = self.decode_bboxes(self.dfl(x["boxes"]), self.anchors.unsqueeze(0), x.get("angle")) * self.strides
    return dbox

@staticmethod
def _grouped_topk(x: torch.Tensor, k: int, groups: int = 8) -> tuple[torch.Tensor, torch.Tensor]:
    """Select exact top-k values through smaller grouped selections."""
    n = x.shape[1]
    while groups > 1 and (n % groups or n // groups < k):
        groups //= 2
    if groups == 1:  # nothing to gain, e.g. a short axis or one that does not divide evenly
        return x.topk(k, dim=1)
    size = n // groups
    values, index = x.reshape(x.shape[0], groups, size).topk(k, dim=-1)
    values, winners = values.flatten(1).topk(k, dim=1)
    return values, winners // k * size + index.flatten(1).gather(1, winners)

def _inference(self, x: dict[str, torch.Tensor]) -> torch.Tensor:
    """Decode predicted bounding boxes and class probabilities based on multiple-level feature maps.

    Args:
        x (dict[str, torch.Tensor]): Dictionary of predictions from detection layers.

    Returns:
        (torch.Tensor): Concatenated tensor of decoded bounding boxes and class probabilities.
    """
    # Inference path
    dbox = self._get_decode_boxes(x)
    return torch.cat((dbox, x["scores"].sigmoid()), 1)

def bias_init(self):
    """Initialize Detect() biases, WARNING: requires stride availability."""
    for i, (a, b) in enumerate(zip(self.one2many["box_head"], self.one2many["cls_head"])):  # from
        a[-1].bias.data[:] = 2.0  # box
        b[-1].bias.data[: self.nc] = math.log(
            5 / self.nc / (640 / self.stride[i]) ** 2
        )  # cls (.01 objects, 80 classes, 640 img)
    if getattr(self, "one2one_cv2", None) is not None:
        for i, (a, b) in enumerate(zip(self.one2one["box_head"], self.one2one["cls_head"])):  # from
            a[-1].bias.data[:] = 2.0  # box
            b[-1].bias.data[: self.nc] = math.log(
                5 / self.nc / (640 / self.stride[i]) ** 2
            )  # cls (.01 objects, 80 classes, 640 img)

def decode_bboxes(
    self, bboxes: torch.Tensor, anchors: torch.Tensor, angle: torch.Tensor | None = None
) -> torch.Tensor:
    """Decode bounding boxes from predictions, angle is only used by the OBB head."""
    return dist2bbox(bboxes, anchors, xywh=not self.end2end and not self.xyxy, dim=1)

@end2end.setter
def end2end(self, value):
    """Select the inference head without changing dual-head training."""
    if value and getattr(self, "one2one_cv2", None) is None:
        LOGGER.warning("This model has no one-to-one head; using one-to-many outputs.")
    elif not value and self.cv2 is None:
        LOGGER.warning("The one-to-many head was removed by fusion; using the remaining one-to-one head.")
    self._end2end = value

def forward(
    self, x: list[torch.Tensor]
) -> dict[str, torch.Tensor] | torch.Tensor | tuple[torch.Tensor, dict[str, torch.Tensor]]:
    """Run the detection head on multi-level feature maps.

    Args:
        x (list[torch.Tensor]): Feature maps from each detection level.

    Returns:
        (dict | torch.Tensor | tuple): In training, the raw prediction dict (with "one2many" and "one2one" keys for
            end-to-end heads). In inference, decoded predictions of shape (B, 4 + nc, num_anchors), or (B, max_det,
            6) with [x1, y1, x2, y2, score, class_index] when end-to-end; returned alone in export mode and
            otherwise as a (predictions, raw prediction dict) tuple.
    """
    preds = self.forward_head(x, **self.one2many)
    if getattr(self, "one2one_cv2", None) is not None:
        x_detach = [xi.detach() for xi in x] if self.training else x  # detach keeps one2one out of the backbone
        one2one = self.forward_head(x_detach, **self.one2one)
        preds = {"one2many": preds, "one2one": one2one}
    if self.training:
        return preds
    y = self._inference(preds["one2one" if self.end2end else "one2many"] if "one2one" in preds else preds)
    if self.end2end:
        y = self.postprocess(y.permute(0, 2, 1))
    return y if self.export else (y, preds)

def forward_head(
    self, x: list[torch.Tensor], box_head: nn.Module | None = None, cls_head: nn.Module | None = None
) -> dict[str, torch.Tensor]:
    """Concatenate and return predicted bounding boxes and class probabilities."""
    if box_head is None or cls_head is None:  # for fused inference
        return {}
    bs = x[0].shape[0]  # batch size
    boxes = torch.cat([box_head[i](x[i]).view(bs, 4 * self.reg_max, -1) for i in range(self.nl)], dim=-1)
    scores = torch.cat([cls_head[i](x[i]).view(bs, self.nc, -1) for i in range(self.nl)], dim=-1)
    return {"boxes": boxes, "scores": scores, "feats": x}

def fuse(self) -> None:
    """Remove the unused detection branch for inference."""
    end2end = self.end2end
    for name in tuple(self._modules):
        if name.startswith("one2one_"):
            setattr(self, name[8:] if end2end else name, None)

def get_topk_index(self, scores: torch.Tensor, max_det: int) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
    """Get top-k indices from scores.

    Args:
        scores (torch.Tensor): Scores tensor with shape (batch_size, num_anchors, num_classes).
        max_det (int): Maximum detections per image.

    Returns:
        scores (torch.Tensor): Top-k scores with shape (batch_size, k, 1).
        labels (torch.Tensor): Class indices as float with shape (batch_size, k, 1).
        index (torch.Tensor): Anchor indices of the top-k detections with shape (batch_size, k).
    """
    anchors, nc = scores.shape[1:]  # i.e. shape(16,8400,80)
    k = min(max_det, anchors)
    if self.agnostic_nms:
        scores, labels = scores.max(dim=-1)
        scores, index = self._grouped_topk(scores, k, 1)
        return scores[..., None], self._gather(labels[..., None].float(), index), index
    groups = 8 if self.export and self.format == "engine" and not self.dynamic else 1
    ori_index = self._grouped_topk(scores.max(dim=-1)[0], k, groups)[1]
    scores = self._gather(scores, ori_index)
    scores, index = self._grouped_topk(scores.flatten(1), k, groups)
    return scores[..., None], (index % nc)[..., None].float(), self._gather(ori_index, index // nc)

def postprocess(self, preds: torch.Tensor) -> torch.Tensor:
    """Post-processes YOLO model predictions.

    Args:
        preds (torch.Tensor): Raw predictions with shape (batch_size, num_anchors, 4 + nc + extra) with last
            dimension format [x1, y1, x2, y2, class_probs, extra], where extra holds the mask coefficients,
            keypoints or angle of the Segment, Pose and OBB heads and is empty for Detect.

    Returns:
        (torch.Tensor): Processed predictions with shape (batch_size, min(max_det, num_anchors), 6 + extra) and last
            dimension format [x1, y1, x2, y2, score, class_index, extra].
    """
    # Segment, Pose and OBB carry task channels after the class scores, Detect has none
    boxes, scores, *extra = preds.split([s for s in (4, self.nc, preds.shape[-1] - 4 - self.nc) if s], dim=-1)
    scores, conf, idx = self.get_topk_index(scores, self.max_det)
    return torch.cat([self._gather(boxes, idx), scores, conf, *(self._gather(e, idx) for e in extra)], dim=-1)

class Segment(Detect):
    """YOLO Segment head for segmentation models.

    This class extends the Detect head to include mask prediction capabilities for instance segmentation tasks.

    Attributes:
        nm (int): Number of masks.
        npr (int): Number of protos.
        proto (Proto): Prototype generation module.
        cv4 (nn.ModuleList): Convolution layers for mask coefficients.

    Methods:
        forward: Return model outputs and mask coefficients.

    Examples:
        Create a segmentation head
        >>> segment = Segment(nc=80, nm=32, npr=256, ch=(256, 512, 1024))
        >>> x = [torch.randn(1, 256, 80, 80), torch.randn(1, 512, 40, 40), torch.randn(1, 1024, 20, 20)]
        >>> outputs = segment(x)
    """

    def __init__(
        self,
        nc: int = 80,
        nm: int = 32,
        npr: int = 256,
        reg_max: int = 16,
        end2end: bool = False,
        ch: list[int] | tuple[int, ...] = (),
    ):
        """Initialize the YOLO model attributes such as the number of masks, prototypes, and the convolution layers.

        Args:
            nc (int): Number of classes.
            nm (int): Number of masks.
            npr (int): Number of protos.
            reg_max (int): Maximum number of DFL channels.
            end2end (bool): Whether to use end-to-end NMS-free detection.
            ch (list[int] | tuple[int, ...]): Channel sizes from backbone feature maps.
        """
        super().__init__(nc, reg_max, end2end, ch)
        self.nm = nm  # number of masks
        self.npr = npr  # number of protos
        self.proto = Proto(ch[0], self.npr, self.nm)  # protos

        c4 = max(ch[0] // 4, self.nm)
        self.cv4 = nn.ModuleList(nn.Sequential(Conv(x, c4, 3), Conv(c4, c4, 3), nn.Conv2d(c4, self.nm, 1)) for x in ch)
        if end2end:
            self.one2one_cv4 = copy.deepcopy(self.cv4)

@property
def one2many(self):
    """Return the one-to-many head components, here for backward compatibility."""
    return {"box_head": self.cv2, "cls_head": self.cv3, "mask_head": self.cv4}

@property
def one2one(self):
    """Return the one-to-one head components."""
    return {"box_head": self.one2one_cv2, "cls_head": self.one2one_cv3, "mask_head": self.one2one_cv4}

def _inference(self, x: dict[str, torch.Tensor]) -> torch.Tensor:
    """Decode predicted bounding boxes and class probabilities, concatenated with mask coefficients."""
    preds = super()._inference(x)
    return torch.cat([preds, x["mask_coefficient"]], dim=1)

def forward(self, x: list[torch.Tensor]) -> tuple | list[torch.Tensor] | dict[str, torch.Tensor]:
    """Return predictions with mask prototypes.

    Returns raw predictions with prototypes attached in training, `(outputs, proto)` in export mode, and
    `((outputs, proto), raw predictions)` otherwise.
    """
    outputs = super().forward(x)
    preds = outputs[1] if isinstance(outputs, tuple) else outputs
    proto = self.proto(x[0])  # mask protos
    if isinstance(preds, dict):  # training and validating during training
        if "one2one" in preds:
            preds["one2many"]["proto"] = proto
            preds["one2one"]["proto"] = proto.detach()
        else:
            preds["proto"] = proto
    if self.training:
        return preds
    return (outputs, proto) if self.export else ((outputs[0], proto), preds)

def forward_head(
    self, x: list[torch.Tensor], box_head: torch.nn.Module, cls_head: torch.nn.Module, mask_head: torch.nn.Module
) -> dict[str, torch.Tensor]:
    """Concatenate and return predicted bounding boxes, class probabilities, and mask coefficients."""
    preds = super().forward_head(x, box_head, cls_head)
    if mask_head is not None:
        bs = x[0].shape[0]  # batch size
        preds["mask_coefficient"] = torch.cat([mask_head[i](x[i]).view(bs, self.nm, -1) for i in range(self.nl)], 2)
    return preds

class Segment26(Segment):
    """YOLO26 Segment head for segmentation models.

    This class extends the Segment head with Proto26 for mask prediction in instance segmentation tasks.

    Attributes:
        nm (int): Number of masks.
        npr (int): Number of protos.
        proto (Proto26): Prototype generation module.
        cv4 (nn.ModuleList): Convolution layers for mask coefficients.

    Methods:
        forward: Return model outputs and mask coefficients.

    Examples:
        Create a segmentation head
        >>> segment = Segment26(nc=80, nm=32, npr=256, ch=(256, 512, 1024))
        >>> x = [torch.randn(1, 256, 80, 80), torch.randn(1, 512, 40, 40), torch.randn(1, 1024, 20, 20)]
        >>> outputs = segment(x)
    """

    def __init__(
        self,
        nc: int = 80,
        nm: int = 32,
        npr: int = 256,
        reg_max: int = 16,
        end2end: bool = False,
        ch: list[int] | tuple[int, ...] = (),
    ):
        """Initialize the YOLO model attributes such as the number of masks, prototypes, and the convolution layers.

        Args:
            nc (int): Number of classes.
            nm (int): Number of masks.
            npr (int): Number of protos.
            reg_max (int): Maximum number of DFL channels.
            end2end (bool): Whether to use end-to-end NMS-free detection.
            ch (list[int] | tuple[int, ...]): Channel sizes from backbone feature maps.
        """
        super().__init__(nc, nm, npr, reg_max, end2end, ch)
        self.proto = Proto26(ch, self.npr, self.nm, nc)  # protos

def forward(self, x: list[torch.Tensor]) -> tuple | list[torch.Tensor] | dict[str, torch.Tensor]:
    """Return predictions with mask prototypes.

    Returns raw predictions with prototypes attached in training, `(outputs, proto)` in export mode, and
    `((outputs, proto), raw predictions)` otherwise.
    """
    outputs = Detect.forward(self, x)
    preds = outputs[1] if isinstance(outputs, tuple) else outputs
    proto = self.proto(x)  # mask protos
    if isinstance(preds, dict):  # training and validating during training
        if "one2one" in preds:
            preds["one2many"]["proto"] = proto
            preds["one2one"]["proto"] = (
                tuple(p.detach() for p in proto) if isinstance(proto, tuple) else proto.detach()
            )
        else:
            preds["proto"] = proto
    if self.training:
        return preds
    return (outputs, proto) if self.export else ((outputs[0], proto), preds)

def fuse(self) -> None:
    """Remove the unused detection branch and training-only prototype layers for inference."""
    super().fuse()
    if hasattr(self.proto, "fuse"):
        self.proto.fuse()

class OBB(Detect):
    """YOLO OBB detection head for detection with rotation models.

    This class extends the Detect head to include oriented bounding box prediction with rotation angles.

    Attributes:
        ne (int): Number of extra parameters.
        cv4 (nn.ModuleList): Convolution layers for angle prediction.

    Methods:
        forward: Concatenate and return predicted bounding boxes and class probabilities.
        decode_bboxes: Decode rotated bounding boxes.

    Examples:
        Create an OBB detection head
        >>> obb = OBB(nc=80, ne=1, ch=(256, 512, 1024))
        >>> x = [torch.randn(1, 256, 80, 80), torch.randn(1, 512, 40, 40), torch.randn(1, 1024, 20, 20)]
        >>> outputs = obb(x)
    """

    def __init__(
        self, nc: int = 80, ne: int = 1, reg_max: int = 16, end2end: bool = False, ch: list[int] | tuple[int, ...] = ()
    ):
        """Initialize OBB with number of classes `nc` and layer channels `ch`.

        Args:
            nc (int): Number of classes.
            ne (int): Number of extra parameters.
            reg_max (int): Maximum number of DFL channels.
            end2end (bool): Whether to use end-to-end NMS-free detection.
            ch (list[int] | tuple[int, ...]): Channel sizes from backbone feature maps.
        """
        super().__init__(nc, reg_max, end2end, ch)
        self.ne = ne  # number of extra parameters

        c4 = max(ch[0] // 4, self.ne)
        self.cv4 = nn.ModuleList(nn.Sequential(Conv(x, c4, 3), Conv(c4, c4, 3), nn.Conv2d(c4, self.ne, 1)) for x in ch)
        if end2end:
            self.one2one_cv4 = copy.deepcopy(self.cv4)

@property
def one2many(self):
    """Return the one-to-many head components, here for backward compatibility."""
    return {"box_head": self.cv2, "cls_head": self.cv3, "angle_head": self.cv4}

@property
def one2one(self):
    """Return the one-to-one head components."""
    return {"box_head": self.one2one_cv2, "cls_head": self.one2one_cv3, "angle_head": self.one2one_cv4}

def _inference(self, x: dict[str, torch.Tensor]) -> torch.Tensor:
    """Decode predicted bounding boxes and class probabilities, concatenated with rotation angles."""
    preds = super()._inference(x)
    return torch.cat([preds, x["angle"]], dim=1)

def decode_bboxes(self, bboxes: torch.Tensor, anchors: torch.Tensor, angle: torch.Tensor) -> torch.Tensor:
    """Decode rotated bounding boxes."""
    return dist2rbox(bboxes, angle, anchors, dim=1)

def forward_head(
    self, x: list[torch.Tensor], box_head: torch.nn.Module, cls_head: torch.nn.Module, angle_head: torch.nn.Module
) -> dict[str, torch.Tensor]:
    """Concatenate and return predicted bounding boxes, class probabilities, and angles."""
    preds = super().forward_head(x, box_head, cls_head)
    if angle_head is not None:
        bs = x[0].shape[0]  # batch size
        angle = torch.cat(
            [angle_head[i](x[i]).view(bs, self.ne, -1) for i in range(self.nl)], 2
        )  # OBB theta logits
        angle = (angle.sigmoid() - 0.25) * math.pi  # [-pi/4, 3pi/4]
        preds["angle"] = angle
    return preds

class OBB26(OBB):
    """YOLO26 OBB detection head for detection with rotation models.

    This class extends the OBB head with modified angle processing that outputs raw angle predictions without the
    sigmoid transformation used by the original OBB class.

    Attributes:
        ne (int): Number of extra parameters.
        cv4 (nn.ModuleList): Convolution layers for angle prediction.

    Methods:
        forward_head: Concatenate and return predicted bounding boxes, class probabilities, and raw angles.

    Examples:
        Create an OBB26 detection head
        >>> obb26 = OBB26(nc=80, ne=1, ch=(256, 512, 1024))
        >>> x = [torch.randn(1, 256, 80, 80), torch.randn(1, 512, 40, 40), torch.randn(1, 1024, 20, 20)]
        >>> outputs = obb26(x)
    """

def forward_head(
    self, x: list[torch.Tensor], box_head: torch.nn.Module, cls_head: torch.nn.Module, angle_head: torch.nn.Module
) -> dict[str, torch.Tensor]:
    """Concatenate and return predicted bounding boxes, class probabilities, and raw angles."""
    preds = Detect.forward_head(self, x, box_head, cls_head)
    if angle_head is not None:
        bs = x[0].shape[0]  # batch size
        angle = torch.cat(
            [angle_head[i](x[i]).view(bs, self.ne, -1) for i in range(self.nl)], 2
        )  # OBB theta logits (raw output without sigmoid transformation)
        preds["angle"] = angle
    return preds

class Pose(Detect):
    """YOLO Pose head for keypoints models.

    This class extends the Detect head to include keypoint prediction capabilities for pose estimation tasks.

    Attributes:
        kpt_shape (tuple): Number of keypoints and dimensions (2 for x,y or 3 for x,y,visible).
        nk (int): Total number of keypoint values.
        cv4 (nn.ModuleList): Convolution layers for keypoint prediction.

    Methods:
        forward: Perform forward pass through YOLO model and return predictions.
        kpts_decode: Decode keypoints from predictions.

    Examples:
        Create a pose detection head
        >>> pose = Pose(nc=80, kpt_shape=(17, 3), ch=(256, 512, 1024))
        >>> x = [torch.randn(1, 256, 80, 80), torch.randn(1, 512, 40, 40), torch.randn(1, 1024, 20, 20)]
        >>> outputs = pose(x)
    """

    def __init__(
        self,
        nc: int = 80,
        kpt_shape: tuple = (17, 3),
        reg_max: int = 16,
        end2end: bool = False,
        ch: list[int] | tuple[int, ...] = (),
    ):
        """Initialize YOLO network with default parameters and Convolutional Layers.

        Args:
            nc (int): Number of classes.
            kpt_shape (tuple): Number of keypoints, number of dims (2 for x,y or 3 for x,y,visible).
            reg_max (int): Maximum number of DFL channels.
            end2end (bool): Whether to use end-to-end NMS-free detection.
            ch (list[int] | tuple[int, ...]): Channel sizes from backbone feature maps.
        """
        super().__init__(nc, reg_max, end2end, ch)
        self.kpt_shape = kpt_shape  # number of keypoints, number of dims (2 for x,y or 3 for x,y,visible)
        self.nk = kpt_shape[0] * kpt_shape[1]  # number of keypoints total

        c4 = max(ch[0] // 4, self.nk)
        self.cv4 = nn.ModuleList(nn.Sequential(Conv(x, c4, 3), Conv(c4, c4, 3), nn.Conv2d(c4, self.nk, 1)) for x in ch)
        if end2end:
            self.one2one_cv4 = copy.deepcopy(self.cv4)

@property
def one2many(self):
    """Return the one-to-many head components, here for backward compatibility."""
    return {"box_head": self.cv2, "cls_head": self.cv3, "pose_head": self.cv4}

@property
def one2one(self):
    """Return the one-to-one head components."""
    return {"box_head": self.one2one_cv2, "cls_head": self.one2one_cv3, "pose_head": self.one2one_cv4}

def _inference(self, x: dict[str, torch.Tensor]) -> torch.Tensor:
    """Decode predicted bounding boxes and class probabilities, concatenated with keypoints."""
    preds = super()._inference(x)
    return torch.cat([preds, self.kpts_decode(x["kpts"])], dim=1)

def forward_head(
    self, x: list[torch.Tensor], box_head: torch.nn.Module, cls_head: torch.nn.Module, pose_head: torch.nn.Module
) -> dict[str, torch.Tensor]:
    """Concatenate and return predicted bounding boxes, class probabilities, and keypoints."""
    preds = super().forward_head(x, box_head, cls_head)
    if pose_head is not None:
        bs = x[0].shape[0]  # batch size
        preds["kpts"] = torch.cat([pose_head[i](x[i]).view(bs, self.nk, -1) for i in range(self.nl)], 2)
    return preds

def kpts_decode(self, kpts: torch.Tensor) -> torch.Tensor:
    """Decode keypoints from predictions."""
    ndim = self.kpt_shape[1]
    bs = kpts.shape[0]
    if self.export:
        y = kpts.view(bs, *self.kpt_shape, -1)
        a = (y[:, :, :2] * 2.0 + (self.anchors - 0.5)) * self.strides
        if ndim == 3:
            a = torch.cat((a, y[:, :, 2:3].sigmoid()), 2)
        return a.view(bs, self.nk, -1)
    else:
        y = kpts.clone()
        if ndim == 3:
            y[:, 2::ndim] = y[:, 2::ndim].sigmoid()
        y[:, 0::ndim] = (y[:, 0::ndim] * 2.0 + (self.anchors[0] - 0.5)) * self.strides
        y[:, 1::ndim] = (y[:, 1::ndim] * 2.0 + (self.anchors[1] - 0.5)) * self.strides
        return y

class Pose26(Pose):
    """YOLO26 Pose head for keypoints models.

    This class extends the Pose head with normalizing flow for keypoint prediction in pose estimation tasks.

    Attributes:
        kpt_shape (tuple): Number of keypoints and dimensions (2 for x,y or 3 for x,y,visible).
        nk (int): Total number of keypoint values.
        cv4 (nn.ModuleList): Convolution layers for keypoint prediction.

    Methods:
        forward: Perform forward pass through YOLO model and return predictions.
        kpts_decode: Decode keypoints from predictions.

    Examples:
        Create a pose detection head
        >>> pose = Pose26(nc=80, kpt_shape=(17, 3), ch=(256, 512, 1024))
        >>> x = [torch.randn(1, 256, 80, 80), torch.randn(1, 512, 40, 40), torch.randn(1, 1024, 20, 20)]
        >>> outputs = pose(x)
    """

    def __init__(
        self,
        nc: int = 80,
        kpt_shape: tuple = (17, 3),
        reg_max: int = 16,
        end2end: bool = False,
        ch: list[int] | tuple[int, ...] = (),
    ):
        """Initialize YOLO network with default parameters and Convolutional Layers.

        Args:
            nc (int): Number of classes.
            kpt_shape (tuple): Number of keypoints, number of dims (2 for x,y or 3 for x,y,visible).
            reg_max (int): Maximum number of DFL channels.
            end2end (bool): Whether to use end-to-end NMS-free detection.
            ch (list[int] | tuple[int, ...]): Channel sizes from backbone feature maps.
        """
        super().__init__(nc, kpt_shape, reg_max, end2end, ch)
        self.flow_model = RealNVP()

        c4 = max(ch[0] // 4, kpt_shape[0] * (kpt_shape[1] + 2))
        self.cv4 = nn.ModuleList(nn.Sequential(Conv(x, c4, 3), Conv(c4, c4, 3)) for x in ch)

        self.cv4_kpts = nn.ModuleList(nn.Conv2d(c4, self.nk, 1) for _ in ch)
        self.nk_sigma = kpt_shape[0] * 2  # sigma_x, sigma_y for each keypoint
        self.cv4_sigma = nn.ModuleList(nn.Conv2d(c4, self.nk_sigma, 1) for _ in ch)

        if end2end:
            self.one2one_cv4 = copy.deepcopy(self.cv4)
            self.one2one_cv4_kpts = copy.deepcopy(self.cv4_kpts)
            self.one2one_cv4_sigma = copy.deepcopy(self.cv4_sigma)

@property
def one2many(self):
    """Return the one-to-many head components, here for backward compatibility."""
    return {
        "box_head": self.cv2,
        "cls_head": self.cv3,
        "pose_head": self.cv4,
        "kpts_head": self.cv4_kpts,
        "kpts_sigma_head": self.cv4_sigma,
    }

@property
def one2one(self):
    """Return the one-to-one head components."""
    return {
        "box_head": self.one2one_cv2,
        "cls_head": self.one2one_cv3,
        "pose_head": self.one2one_cv4,
        "kpts_head": self.one2one_cv4_kpts,
        "kpts_sigma_head": self.one2one_cv4_sigma,
    }

def forward_head(
    self,
    x: list[torch.Tensor],
    box_head: torch.nn.Module,
    cls_head: torch.nn.Module,
    pose_head: torch.nn.Module,
    kpts_head: torch.nn.Module,
    kpts_sigma_head: torch.nn.Module,
) -> dict[str, torch.Tensor]:
    """Concatenate and return predicted bounding boxes, class probabilities, and keypoints."""
    preds = Detect.forward_head(self, x, box_head, cls_head)
    if pose_head is not None:
        bs = x[0].shape[0]  # batch size
        features = [pose_head[i](x[i]) for i in range(self.nl)]
        preds["kpts"] = torch.cat([kpts_head[i](features[i]).view(bs, self.nk, -1) for i in range(self.nl)], 2)
        if self.training:
            preds["kpts_sigma"] = torch.cat(
                [kpts_sigma_head[i](features[i]).view(bs, self.nk_sigma, -1) for i in range(self.nl)], 2
            )
    return preds

def fuse(self) -> None:
    """Remove the unused detection branch and training-only layers for inference."""
    super().fuse()
    self.flow_model = None
    setattr(self, "one2one_cv4_sigma" if self.end2end else "cv4_sigma", None)

def kpts_decode(self, kpts: torch.Tensor) -> torch.Tensor:
    """Decode keypoints from predictions."""
    ndim = self.kpt_shape[1]
    bs = kpts.shape[0]
    if self.export:
        y = kpts.view(bs, *self.kpt_shape, -1)
        # NCNN fix
        a = (y[:, :, :2] + self.anchors) * self.strides
        if ndim == 3:
            a = torch.cat((a, y[:, :, 2:3].sigmoid()), 2)
        return a.view(bs, self.nk, -1)
    else:
        y = kpts.clone()
        if ndim == 3:
            y[:, 2::ndim] = y[:, 2::ndim].sigmoid()
        y[:, 0::ndim] = (y[:, 0::ndim] + self.anchors[0]) * self.strides
        y[:, 1::ndim] = (y[:, 1::ndim] + self.anchors[1]) * self.strides
        return y

class Depth(nn.Module):
    """YOLO Depth head for monocular depth estimation.

    A dense prediction head that takes multi-scale backbone features and produces a single-channel depth map via
    progressive upsampling and fusion.

    Attributes:
        export (bool): Export mode flag.
        nl (int): Number of pyramid levels.
        proj (nn.ModuleList): 1x1 projections of each pyramid level to c_mid channels.
        refine (nn.ModuleList): Refinement blocks applied after each top-down fusion step.
        head (nn.Sequential): Output head that upsamples 2x and predicts a single-channel log-depth map.
        cal_a (torch.Tensor): Log-affine calibration scale buffer, identity 1.0 by default.
        cal_b (torch.Tensor): Log-affine calibration offset buffer, identity 0.0 by default.

    Examples:
        >>> depth = Depth(ch=(256, 512, 1024))
        >>> x = [torch.randn(1, 256, 80, 80), torch.randn(1, 512, 40, 40), torch.randn(1, 1024, 20, 20)]
        >>> out = depth(x)  # training: {"depth": (1, 1, 160, 160)} at P2 resolution (input/4)
    """

    export = False  # export mode

    def __init__(self, c_mid: int = 256, ch: list[int] | tuple[int, ...] = ()):
        """Initialize Depth head.

        Args:
            c_mid (int): Number of intermediate channels for the fusion decoder.
            ch (list[int] | tuple[int, ...]): Input channel sizes from backbone feature maps (P3, P4, P5).
        """
        super().__init__()
        self.nl = len(ch)  # number of detection layers (pyramid levels)

        # Project each pyramid level to c_mid channels
        self.proj = nn.ModuleList(Conv(c, c_mid, k=1) for c in ch)

        # Refinement blocks after each of the nl-1 fusion steps (the coarsest level is not refined)
        self.refine = nn.ModuleList(nn.Sequential(Conv(c_mid, c_mid, k=3), Conv(c_mid, c_mid, k=3)) for _ in ch[:-1])

        self.head = nn.Sequential(
            Conv(c_mid, c_mid // 2, k=3),
            nn.ConvTranspose2d(c_mid // 2, c_mid // 2, kernel_size=2, stride=2, bias=True),
            Conv(c_mid // 2, c_mid // 4, k=3),
            nn.Conv2d(c_mid // 4, 1, kernel_size=1),
        )
        # Initialize to ~1.2 m so early exp() outputs stay well-conditioned.
        self.head[-1].bias.data.fill_(0.182)

        # Scale-only log-affine calibration d' = exp(a·log d + b); identity by default.
        self.register_buffer("cal_a", torch.ones(1))
        self.register_buffer("cal_b", torch.zeros(1))

def forward(self, x: list[torch.Tensor]) -> dict[str, torch.Tensor] | torch.Tensor:
    """Fuse multi-scale features and predict depth.

    Args:
        x (list[torch.Tensor]): Feature tensors [P3, P4, P5] from the backbone/neck.

    Returns:
        (dict[str, torch.Tensor] | torch.Tensor): In training, a dict {"depth": (B, 1, H/4, W/4)} with the raw head
            output the loss supervises. In eval, a (B, 1, H/4, W/4) tensor with calibration applied; the
            predictor/validator resize it to image/GT size. In export mode, a (B, 1, H, W) tensor upsampled 4x to
            the input size. Depth values are positive (exp of the clamped head output).
    """
    # Project all levels to same channel dim
    feats = [self.proj[i](x[i]) for i in range(self.nl)]

    out = feats[-1]
    for i in range(self.nl - 2, -1, -1):
        # align_corners=True is baked into the released depth weights. Constant scale (consecutive pyramid
        # levels) keeps the upsample static for dynamic-shape CoreML export; output size is identical.
        out = F.interpolate(out, scale_factor=2, mode="bilinear", align_corners=True)
        out = out + feats[i]
        out = self.refine[i](out)

    out = self.head(out)  # (B, 1, H/4, W/4)
    depth = torch.exp(out.clamp(-4.0, 5.0))

    if self.training:
        return {"depth": depth}

    depth = depth.pow(self.cal_a) * self.cal_b.exp()
    if self.export:  # same align_corners=True resize as the depth loss, calibration and validator
        depth = F.interpolate(depth, scale_factor=4.0, mode="bilinear", align_corners=True)
    return depth

class Classify(nn.Module):
    """YOLO classification head, i.e. x(b,c1,20,20) to x(b,c2).

    This class implements a classification head that transforms feature maps into class predictions.

    Attributes:
        export (bool): Export mode flag.
        conv (Conv): Convolutional layer for feature transformation.
        pool (nn.AdaptiveAvgPool2d): Global average pooling layer.
        drop (nn.Dropout): Dropout layer for regularization.
        linear (nn.Linear): Linear layer for final classification.

    Methods:
        forward: Perform forward pass on input feature maps.

    Examples:
        Create a classification head
        >>> classify = Classify(c1=1024, c2=1000)
        >>> x = torch.randn(1, 1024, 20, 20)
        >>> output = classify(x)
    """

    export = False  # export mode

    def __init__(self, c1: int, c2: int, k: int = 1, s: int = 1, p: int | None = None, g: int = 1):
        """Initialize YOLO classification head to transform input tensor from (b,c1,20,20) to (b,c2) shape.

        Args:
            c1 (int): Number of input channels.
            c2 (int): Number of output classes.
            k (int): Kernel size.
            s (int): Stride.
            p (int, optional): Padding.
            g (int): Groups.
        """
        super().__init__()
        c_ = 1280  # efficientnet_b0 size
        self.conv = Conv(c1, c_, k, s, p, g)
        self.pool = nn.AdaptiveAvgPool2d(1)  # to x(b,c_,1,1)
        self.drop = nn.Dropout(p=0.0, inplace=True)
        self.linear = nn.Linear(c_, c2)  # to x(b,c2)

def forward(self, x: list[torch.Tensor] | torch.Tensor) -> torch.Tensor | tuple:
    """Perform forward pass on input feature maps.

    Args:
        x (list[torch.Tensor] | torch.Tensor): Input feature map, or a list of feature maps concatenated along the
            channel dimension.

    Returns:
        (torch.Tensor | tuple): Logits of shape (B, c2) in training; softmax probabilities in export mode; otherwise
            a (probabilities, logits) tuple.
    """
    if isinstance(x, list):
        x = torch.cat(x, 1)
    x = self.linear(self.drop(self.pool(self.conv(x)).flatten(1)))
    if self.training:
        return x
    y = x.softmax(1)  # get final output
    return y if self.export else (y, x)

class WorldDetect(Detect):
    """Head for integrating YOLO detection models with semantic understanding from text embeddings.

    This class extends the standard Detect head to incorporate text embeddings for enhanced semantic understanding in
    object detection tasks.

    Attributes:
        cv3 (nn.ModuleList): Convolution layers for embedding features.
        cv4 (nn.ModuleList): Contrastive head layers for text-vision alignment.

    Methods:
        forward: Concatenate and return predicted bounding boxes and class probabilities.
        bias_init: Initialize detection head biases.

    Examples:
        Create a WorldDetect head
        >>> world_detect = WorldDetect(nc=80, embed=512, with_bn=False, ch=(256, 512, 1024))
        >>> x = [torch.randn(1, 256, 80, 80), torch.randn(1, 512, 40, 40), torch.randn(1, 1024, 20, 20)]
        >>> text = torch.randn(1, 80, 512)
        >>> outputs = world_detect(x, text)
    """

    def __init__(
        self,
        nc: int = 80,
        embed: int = 512,
        with_bn: bool = False,
        reg_max: int = 16,
        end2end: bool = False,
        ch: list[int] | tuple[int, ...] = (),
    ):
        """Initialize YOLO detection layer with nc classes and layer channels ch.

        Args:
            nc (int): Number of classes.
            embed (int): Embedding dimension.
            with_bn (bool): Whether to use batch normalization in contrastive head.
            reg_max (int): Maximum number of DFL channels.
            end2end (bool): Whether to use end-to-end NMS-free detection.
            ch (list[int] | tuple[int, ...]): Channel sizes from backbone feature maps.
        """
        super().__init__(nc, reg_max=reg_max, end2end=end2end, ch=ch)
        c3 = max(ch[0], min(self.nc, 100))
        self.cv3 = nn.ModuleList(nn.Sequential(Conv(x, c3, 3), Conv(c3, c3, 3), nn.Conv2d(c3, embed, 1)) for x in ch)
        self.cv4 = nn.ModuleList(BNContrastiveHead(embed) if with_bn else ContrastiveHead() for _ in ch)

def bias_init(self):
    """Initialize box biases; class scores come from text-embedding similarity, so cv3 keeps its defaults."""
    for a in self.cv2:
        a[-1].bias.data[:] = 1.0  # box

def forward(self, x: list[torch.Tensor], text: torch.Tensor) -> dict[str, torch.Tensor] | tuple:
    """Concatenate and return predicted bounding boxes and class probabilities.

    Args:
        x (list[torch.Tensor]): Feature maps from each detection level.
        text (torch.Tensor): Text embeddings with shape (B, nc, embed).

    Returns:
        (dict[str, torch.Tensor] | torch.Tensor | tuple): Raw prediction dict in training, decoded predictions of
            shape (B, 4 + nc, num_anchors) in export mode, otherwise a (predictions, raw prediction dict) tuple.
    """
    feats = list(x)  # snapshot references for anchor generation; the loop below reassigns x[i], never mutates
    for i in range(self.nl):
        x[i] = torch.cat((self.cv2[i](x[i]), self.cv4[i](self.cv3[i](x[i]), text)), 1)
    self.no = self.nc + self.reg_max * 4  # self.nc could be changed when inference with different texts
    bs = x[0].shape[0]
    x_cat = torch.cat([xi.view(bs, self.no, -1) for xi in x], 2)
    boxes, scores = x_cat.split((self.reg_max * 4, self.nc), 1)
    preds = {"boxes": boxes, "scores": scores, "feats": feats}
    if self.training:
        return preds
    y = self._inference(preds)
    return y if self.export else (y, preds)

class LRPCHead(nn.Module):
    """Lightweight Region Proposal and Classification Head for efficient object detection.

    This head combines region proposal filtering with classification to enable efficient detection with dynamic
    vocabulary support.

    Attributes:
        vocab (nn.Module): Vocabulary/classification layer.
        pf (nn.Module): Proposal filter module.
        loc (nn.Module): Localization module.
        enabled (bool): Whether the head is enabled.

    Methods:
        conv2linear: Convert a 1x1 convolutional layer to a linear layer.
        forward: Process classification and localization features to generate detection proposals.

    Examples:
        Create an LRPC head
        >>> vocab = nn.Conv2d(256, 80, 1)
        >>> pf = nn.Conv2d(256, 1, 1)
        >>> loc = nn.Conv2d(256, 4, 1)
        >>> head = LRPCHead(vocab, pf, loc, enabled=True)
    """

    def __init__(self, vocab: nn.Module, pf: nn.Module, loc: nn.Module, enabled: bool = True):
        """Initialize LRPCHead with vocabulary, proposal filter, and localization components.

        Args:
            vocab (nn.Module): Vocabulary/classification module.
            pf (nn.Module): Proposal filter module.
            loc (nn.Module): Localization module.
            enabled (bool): Whether to enable the head functionality.
        """
        super().__init__()
        self.vocab = self.conv2linear(vocab) if enabled else vocab
        self.pf = pf
        self.loc = loc
        self.enabled = enabled

@staticmethod
def conv2linear(conv: nn.Conv2d) -> nn.Linear:
    """Convert a 1x1 convolutional layer to a linear layer."""
    assert isinstance(conv, nn.Conv2d) and conv.kernel_size == (1, 1)
    linear = nn.Linear(conv.in_channels, conv.out_channels).requires_grad_(conv.weight.requires_grad)
    linear.weight.data = conv.weight.view(conv.out_channels, -1).data
    linear.bias.data = conv.bias.data
    return linear

def forward(self, cls_feat: torch.Tensor, loc_feat: torch.Tensor, conf: float) -> tuple[tuple, torch.Tensor]:
    """Process classification and localization features to generate detection proposals.

    Args:
        cls_feat (torch.Tensor): Classification features with shape (B, C, H, W).
        loc_feat (torch.Tensor): Localization features with shape (B, C, H, W).
        conf (float): Proposal filter confidence threshold; 0 keeps every anchor (static export).

    Returns:
        loc (torch.Tensor): Box regression output of the localization module.
        cls (torch.Tensor): Class scores with shape (B, num_classes, N) for the N kept anchors.
        mask (torch.Tensor | None): Boolean mask of anchors kept by any image, or None when `conf` is 0 and the head
            is enabled.
    """
    if self.enabled:
        if not conf:  # static export, every anchor passes the proposal filter
            cls_feat = self.vocab(cls_feat.flatten(2).transpose(-1, -2))
            return self.loc(loc_feat), cls_feat.transpose(-1, -2), None
        keep = self.pf(cls_feat)[:, 0].flatten(1).sigmoid() > conf  # (B, N) per-image proposals
        mask = keep.any(0)  # batch union, then suppress anchors each image's own filter rejected
        cls_feat = self.vocab(cls_feat.flatten(2).transpose(-1, -2)[:, mask])
        cls_feat = cls_feat.masked_fill(~keep[:, mask, None], float("-inf"))
        return self.loc(loc_feat), cls_feat.transpose(-1, -2), mask
    else:
        cls_feat = self.vocab(cls_feat)
        loc_feat = self.loc(loc_feat)
        return (
            loc_feat,
            cls_feat.flatten(2),
            cls_feat.new_ones(cls_feat.shape[2] * cls_feat.shape[3], dtype=torch.bool),
        )

class YOLOEDetect(Detect):
    """Head for integrating YOLO detection models with semantic understanding from text embeddings.

    This class extends the standard Detect head to support text-guided detection with enhanced semantic understanding
    through text embeddings and visual prompt embeddings.

    Attributes:
        is_fused (bool): Whether the model is fused for inference.
        cv3 (nn.ModuleList): Convolution layers for embedding features.
        cv4 (nn.ModuleList): Contrastive head layers for text-vision alignment.
        reprta (Residual): Residual block for text prompt embeddings.
        savpe (SAVPE): Spatial-aware visual prompt embeddings module.
        embed (int): Embedding dimension.

    Methods:
        fuse: Fuse text features with model weights for efficient inference.
        get_tpe: Get text prompt embeddings with normalization.
        get_vpe: Get visual prompt embeddings with spatial awareness.
        forward_lrpc: Process features with fused text embeddings for prompt-free model.
        forward: Process features with class prompt embeddings to generate detections.
        bias_init: Initialize biases for detection heads.

    Examples:
        Create a YOLOEDetect head
        >>> yoloe_detect = YOLOEDetect(nc=80, embed=512, with_bn=True, ch=(256, 512, 1024))
        >>> x = [torch.randn(1, 256, 80, 80), torch.randn(1, 512, 40, 40), torch.randn(1, 1024, 20, 20)]
        >>> cls_pe = torch.randn(1, 80, 512)
        >>> outputs = yoloe_detect([*x, cls_pe])
    """

    is_fused = False

    def __init__(
        self,
        nc: int = 80,
        embed: int = 512,
        with_bn: bool = True,
        reg_max: int = 16,
        end2end: bool = False,
        ch: list[int] | tuple[int, ...] = (),
    ):
        """Initialize YOLO detection layer with nc classes and layer channels ch.

        Args:
            nc (int): Number of classes.
            embed (int): Embedding dimension.
            with_bn (bool): Whether to use batch normalization in contrastive head. Must be True.
            reg_max (int): Maximum number of DFL channels.
            end2end (bool): Whether to use end-to-end NMS-free detection.
            ch (list[int] | tuple[int, ...]): Channel sizes from backbone feature maps.
        """
        super().__init__(nc, reg_max, end2end, ch)
        c3 = max(ch[0], min(self.nc, 100))
        assert c3 <= embed
        assert with_bn
        self.cv3 = (
            nn.ModuleList(nn.Sequential(Conv(x, c3, 3), Conv(c3, c3, 3), nn.Conv2d(c3, embed, 1)) for x in ch)
            if self.legacy
            else nn.ModuleList(
                nn.Sequential(
                    nn.Sequential(DWConv(x, x, 3), Conv(x, c3, 1)),
                    nn.Sequential(DWConv(c3, c3, 3), Conv(c3, c3, 1)),
                    nn.Conv2d(c3, embed, 1),
                )
                for x in ch
            )
        )
        self.cv4 = nn.ModuleList(BNContrastiveHead(embed) for _ in ch)
        if end2end:
            self.one2one_cv3 = copy.deepcopy(self.cv3)  # overwrite with new cv3
            self.one2one_cv4 = copy.deepcopy(self.cv4)

        self.reprta = Residual(SwiGLUFFN(embed, embed))
        self.savpe = SAVPE(ch, c3, embed)
        self.embed = embed

@property
def one2many(self):
    """Return the one-to-many head components, here for v3/v5/v8/v9/v11 backward compatibility."""
    return {"box_head": self.cv2, "cls_head": self.cv3, "contrastive_head": self.cv4}

@property
def one2one(self):
    """Return the one-to-one head components."""
    return {"box_head": self.one2one_cv2, "cls_head": self.one2one_cv3, "contrastive_head": self.one2one_cv4}

def _fuse_tp(self, txt_feats: torch.Tensor, cls_head: torch.nn.Module, bn_head: torch.nn.Module) -> None:
    """Fuse text prompt embeddings with model weights for efficient inference."""
    for cls_h, bn_h in zip(cls_head, bn_head):
        assert isinstance(cls_h, nn.Sequential)
        assert isinstance(bn_h, BNContrastiveHead)
        conv = cls_h[-1]
        assert isinstance(conv, nn.Conv2d)
        logit_scale = bn_h.logit_scale
        bias = bn_h.bias
        norm = bn_h.norm

        t = txt_feats * logit_scale.exp()
        conv: nn.Conv2d = fuse_conv_and_bn(conv, norm)

        w = conv.weight.data.squeeze(-1).squeeze(-1)
        b = conv.bias.data

        w = t @ w
        b1 = (t @ b.reshape(-1).unsqueeze(-1)).squeeze(-1)
        b2 = torch.ones_like(b1) * bias

        conv = (
            nn.Conv2d(
                conv.in_channels,
                w.shape[0],
                kernel_size=1,
            )
            .requires_grad_(False)
            .to(conv.weight.device, conv.weight.dtype)
        )

        conv.weight.data.copy_(w.unsqueeze(-1).unsqueeze(-1))
        conv.bias.data.copy_(b1 + b2)
        cls_h[-1] = conv

        bn_h.fuse()

def _get_decode_boxes(self, x):
    """Decode predicted bounding boxes for inference."""
    dbox = super()._get_decode_boxes(x)
    if hasattr(self, "lrpc"):
        dbox = dbox if x["index"] is None else dbox[..., x["index"]]
    return dbox

def bias_init(self):
    """Initialize Detect() biases, WARNING: requires stride availability."""
    for i, (a, b, c) in enumerate(
        zip(self.one2many["box_head"], self.one2many["cls_head"], self.one2many["contrastive_head"])
    ):
        a[-1].bias.data[:] = 2.0  # box
        b[-1].bias.data[:] = 0.0
        c.bias.data[:] = math.log(5 / self.nc / (640 / self.stride[i]) ** 2)
    if getattr(self, "one2one_cv2", None) is not None:
        for i, (a, b, c) in enumerate(
            zip(self.one2one["box_head"], self.one2one["cls_head"], self.one2one["contrastive_head"])
        ):
            a[-1].bias.data[:] = 2.0  # box
            b[-1].bias.data[:] = 0.0
            c.bias.data[:] = math.log(5 / self.nc / (640 / self.stride[i]) ** 2)

def forward(self, x: list[torch.Tensor]) -> torch.Tensor | tuple:
    """Process features with class prompt embeddings to generate detections.

    Args:
        x (list[torch.Tensor]): Feature maps from each detection level followed by class prompt embeddings with
            shape (B, nc, embed).

    Returns:
        (dict | torch.Tensor | tuple): Same outputs as `Detect.forward`.
    """
    if hasattr(self, "lrpc"):  # for prompt-free inference
        return self.forward_lrpc(x[:3])
    return super().forward(x)

def forward_head(self, x, box_head, cls_head, contrastive_head):
    """Concatenate and return predicted bounding boxes, class probabilities, and contrastive scores."""
    assert len(x) == 4, f"Expected 4 features including 3 feature maps and 1 text embeddings, but got {len(x)}."
    if box_head is None or cls_head is None:  # for fused inference
        return {}
    bs = x[0].shape[0]  # batch size
    boxes = torch.cat([box_head[i](x[i]).view(bs, 4 * self.reg_max, -1) for i in range(self.nl)], dim=-1)
    self.nc = int(x[-1].shape[1])
    scores = torch.cat(
        [contrastive_head[i](cls_head[i](x[i]), x[-1]).reshape(bs, self.nc, -1) for i in range(self.nl)], dim=-1
    )
    self.no = self.nc + self.reg_max * 4  # self.nc could be changed when inference with different texts
    return {"boxes": boxes, "scores": scores, "feats": x[:3]}

def forward_lrpc(self, x: list[torch.Tensor]) -> torch.Tensor | tuple:
    """Process features with fused text embeddings to generate detections for prompt-free model."""
    boxes, scores, index = [], [], []
    bs = x[0].shape[0]
    cv2 = self.one2one_cv2 if self.end2end else self.cv2
    cv3 = self.one2one_cv3 if self.end2end else self.cv3
    lrpc = self.one2one_lrpc if self.end2end and hasattr(self, "one2one_lrpc") else self.lrpc
    conf = 0 if self.export and not self.dynamic else getattr(self, "conf", 0.001)
    for i in range(self.nl):
        cls_feat = cv3[i](x[i])
        loc_feat = cv2[i](x[i])
        assert isinstance(lrpc[i], LRPCHead)
        box, score, idx = lrpc[i](cls_feat, loc_feat, conf)
        boxes.append(box.view(bs, self.reg_max * 4, -1))
        scores.append(score)
        index.append(idx)
    index = torch.cat(index) if conf else None
    preds = {
        "boxes": torch.cat(boxes, 2),
        "scores": torch.cat(scores, 2),
        "feats": x,
        "index": index,
        **self.forward_mask(x, index),
    }
    y = self._inference(preds)
    if self.end2end:
        y = self.postprocess(y.permute(0, 2, 1))
    return y if self.export else (y, preds)

def forward_mask(self, x: list[torch.Tensor], index: torch.Tensor | None) -> dict[str, torch.Tensor]:
    """Return the prompt-free mask coefficients, which the detection head does not produce."""
    return {}

@smart_inference_mode(False)  # fused layers stay in the model, so they must not be inference tensors
def fuse(self, txt_feats: torch.Tensor | None = None):
    """Fuse text features with model weights for efficient inference.

    Args:
        txt_feats (torch.Tensor, optional): Text prompt embeddings to fuse into the classification heads. If None,
            only the unused detection branch is removed.
    """
    if txt_feats is None:  # remove the unused detection branch
        super().fuse()
        return
    if self.is_fused:
        return

    assert not self.training
    txt_feats = txt_feats.to(next(self.parameters()).dtype).squeeze(0)
    if self.cv3 and self.cv4:
        self._fuse_tp(txt_feats, self.cv3, self.cv4)
    if getattr(self, "one2one_cv2", None) is not None:
        self._fuse_tp(txt_feats, self.one2one_cv3, self.one2one_cv4)
    del self.reprta
    self.reprta = nn.Identity()
    self.is_fused = True

def get_tpe(self, tpe: torch.Tensor | None) -> torch.Tensor | None:
    """Get text prompt embeddings with normalization."""
    return None if tpe is None else F.normalize(self.reprta(tpe), dim=-1, p=2)

def get_vpe(self, x: list[torch.Tensor], vpe: torch.Tensor) -> torch.Tensor:
    """Get visual prompt embeddings with spatial awareness."""
    if vpe.shape[1] == 0:  # no visual prompt embeddings
        return torch.zeros(x[0].shape[0], 0, self.embed, device=x[0].device)
    if vpe.ndim == 4:  # (B, N, H, W)
        vpe = self.savpe(x, vpe)
    assert vpe.ndim == 3  # (B, N, D)
    return vpe

class YOLOESegment(YOLOEDetect):
    """YOLO segmentation head with text embedding capabilities.

    This class extends YOLOEDetect to include mask prediction capabilities for instance segmentation tasks with
    text-guided semantic understanding.

    Attributes:
        nm (int): Number of masks.
        npr (int): Number of protos.
        proto (Proto): Prototype generation module.
        cv5 (nn.ModuleList): Convolution layers for mask coefficients.

    Methods:
        forward: Return model outputs and mask coefficients.

    Examples:
        Create a YOLOESegment head
        >>> yoloe_segment = YOLOESegment(nc=80, nm=32, npr=256, embed=512, with_bn=True, ch=(256, 512, 1024))
        >>> x = [torch.randn(1, 256, 80, 80), torch.randn(1, 512, 40, 40), torch.randn(1, 1024, 20, 20)]
        >>> text = torch.randn(1, 80, 512)
        >>> outputs = yoloe_segment([*x, text])
    """

    def __init__(
        self,
        nc: int = 80,
        nm: int = 32,
        npr: int = 256,
        embed: int = 512,
        with_bn: bool = True,
        reg_max: int = 16,
        end2end: bool = False,
        ch: list[int] | tuple[int, ...] = (),
    ):
        """Initialize YOLOESegment with class count, mask parameters, and embedding dimensions.

        Args:
            nc (int): Number of classes.
            nm (int): Number of masks.
            npr (int): Number of protos.
            embed (int): Embedding dimension.
            with_bn (bool): Whether to use batch normalization in contrastive head. Must be True.
            reg_max (int): Maximum number of DFL channels.
            end2end (bool): Whether to use end-to-end NMS-free detection.
            ch (list[int] | tuple[int, ...]): Channel sizes from backbone feature maps.
        """
        super().__init__(nc, embed, with_bn, reg_max, end2end, ch)
        self.nm = nm
        self.npr = npr
        self.proto = Proto(ch[0], self.npr, self.nm)

        c5 = max(ch[0] // 4, self.nm)
        self.cv5 = nn.ModuleList(nn.Sequential(Conv(x, c5, 3), Conv(c5, c5, 3), nn.Conv2d(c5, self.nm, 1)) for x in ch)
        if end2end:
            self.one2one_cv5 = copy.deepcopy(self.cv5)

@property
def one2many(self):
    """Return the one-to-many head components, here for v3/v5/v8/v9/v11 backward compatibility."""
    return {"box_head": self.cv2, "cls_head": self.cv3, "mask_head": self.cv5, "contrastive_head": self.cv4}

@property
def one2one(self):
    """Return the one-to-one head components."""
    return {
        "box_head": self.one2one_cv2,
        "cls_head": self.one2one_cv3,
        "mask_head": self.one2one_cv5,
        "contrastive_head": self.one2one_cv4,
    }

def _inference(self, x: dict[str, torch.Tensor]) -> torch.Tensor:
    """Decode predicted bounding boxes and class probabilities, concatenated with mask coefficients."""
    preds = super()._inference(x)
    return torch.cat([preds, x["mask_coefficient"]], dim=1)

def forward(self, x: list[torch.Tensor]) -> tuple | list[torch.Tensor] | dict[str, torch.Tensor]:
    """Return predictions with mask prototypes.

    Returns raw predictions with prototypes attached in training, `(outputs, proto)` in export mode, and
    `((outputs, proto), raw predictions)` otherwise.
    """
    outputs = super().forward(x)
    preds = outputs[1] if isinstance(outputs, tuple) else outputs
    proto = self.proto(x[0])  # mask protos
    if isinstance(preds, dict):  # training and validating during training
        if "one2one" in preds:
            preds["one2many"]["proto"] = proto
            preds["one2one"]["proto"] = proto.detach()
        else:
            preds["proto"] = proto
    if self.training:
        return preds
    return (outputs, proto) if self.export else ((outputs[0], proto), preds)

def forward_head(
    self,
    x: list[torch.Tensor],
    box_head: torch.nn.Module,
    cls_head: torch.nn.Module,
    mask_head: torch.nn.Module,
    contrastive_head: torch.nn.Module,
) -> dict[str, torch.Tensor]:
    """Concatenate and return predicted bounding boxes, class probabilities, and mask coefficients."""
    preds = super().forward_head(x, box_head, cls_head, contrastive_head)
    if mask_head is not None:
        bs = x[0].shape[0]  # batch size
        preds["mask_coefficient"] = torch.cat([mask_head[i](x[i]).view(bs, self.nm, -1) for i in range(self.nl)], 2)
    return preds

def forward_mask(self, x: list[torch.Tensor], index: torch.Tensor | None) -> dict[str, torch.Tensor]:
    """Return the prompt-free mask coefficients of the anchors the proposal filter kept."""
    cv5 = self.one2one_cv5 if self.end2end else self.cv5
    mc = torch.cat([cv5[i](x[i]).view(x[0].shape[0], self.nm, -1) for i in range(self.nl)], 2)
    return {"mask_coefficient": mc if index is None else mc[..., index]}

def fuse(self, txt_feats: torch.Tensor | None = None):
    """Fuse text features with model weights for efficient inference."""
    super().fuse(txt_feats)
    if txt_feats is None and hasattr(self.proto, "fuse"):  # remove training-only prototype layers
        self.proto.fuse()

class YOLOESegment26(YOLOESegment):
    """YOLOE-style segmentation head module using Proto26 for mask generation.

    This class extends the YOLOESegment functionality to include segmentation capabilities by integrating a Proto26
    generation module and convolutional layers to predict mask coefficients.

    Args:
        nc (int): Number of classes. Defaults to 80.
        nm (int): Number of masks. Defaults to 32.
        npr (int): Number of prototype channels. Defaults to 256.
        embed (int): Embedding dimensionality. Defaults to 512.
        with_bn (bool): Whether to use Batch Normalization. Must be True.
        reg_max (int): Maximum number of DFL channels. Defaults to 16.
        end2end (bool): Whether to use end-to-end detection mode. Defaults to False.
        ch (list[int] | tuple[int, ...]): Input channels for each scale.

    Attributes:
        nm (int): Number of segmentation masks.
        npr (int): Number of prototype channels.
        proto (Proto26): Prototype generation module for segmentation.
        cv5 (nn.ModuleList): Convolutional layers for generating mask coefficients from features.
        one2one_cv5 (nn.ModuleList, optional): Deep copy of cv5 for end-to-end detection branches.
    """

    def __init__(
        self,
        nc: int = 80,
        nm: int = 32,
        npr: int = 256,
        embed: int = 512,
        with_bn: bool = True,
        reg_max: int = 16,
        end2end: bool = False,
        ch: list[int] | tuple[int, ...] = (),
    ):
        """Initialize YOLOESegment26 with class count, mask parameters, and embedding dimensions."""
        YOLOEDetect.__init__(self, nc, embed, with_bn, reg_max, end2end, ch)
        self.nm = nm
        self.npr = npr
        self.proto = Proto26(ch, self.npr, self.nm, nc)  # protos

        c5 = max(ch[0] // 4, self.nm)
        self.cv5 = nn.ModuleList(nn.Sequential(Conv(x, c5, 3), Conv(c5, c5, 3), nn.Conv2d(c5, self.nm, 1)) for x in ch)
        if end2end:
            self.one2one_cv5 = copy.deepcopy(self.cv5)

def forward(self, x: list[torch.Tensor]) -> tuple | list[torch.Tensor] | dict[str, torch.Tensor]:
    """Return predictions with mask prototypes.

    Returns raw predictions with prototypes attached in training, `(outputs, proto)` in export mode, and
    `((outputs, proto), raw predictions)` otherwise.
    """
    outputs = YOLOEDetect.forward(self, x)
    preds = outputs[1] if isinstance(outputs, tuple) else outputs
    proto = self.proto([xi.detach() for xi in x], return_semantic=False)  # mask protos

    if isinstance(preds, dict):  # training and validating during training
        if "one2one" in preds:  # dual-head outputs, not prompt-free
            preds["one2many"]["proto"] = proto
            preds["one2one"]["proto"] = proto.detach()
        else:
            preds["proto"] = proto
    if self.training:
        return preds
    return (outputs, proto) if self.export else ((outputs[0], proto), preds)

class RTDETRDecoder(nn.Module):
    """Real-Time Deformable Transformer Decoder (RTDETRDecoder) module for object detection.

    This decoder module utilizes Transformer architecture along with deformable convolutions to predict bounding boxes
    and class labels for objects in an image. It integrates features from multiple layers and runs through a series of
    Transformer decoder layers to output the final predictions.

    Attributes:
        export (bool): Export mode flag.
        hidden_dim (int): Dimension of hidden layers.
        nhead (int): Number of heads in multi-head attention.
        nl (int): Number of feature levels.
        nc (int): Number of classes.
        num_queries (int): Number of query points.
        num_decoder_layers (int): Number of decoder layers.
        input_proj (nn.ModuleList): Input projection layers for backbone features.
        decoder (DeformableTransformerDecoder): Transformer decoder module.
        denoising_class_embed (nn.Embedding): Class embeddings for denoising.
        num_denoising (int): Number of denoising queries.
        label_noise_ratio (float): Label noise ratio for training.
        box_noise_scale (float): Box noise scale for training.
        learnt_init_query (bool): Whether to learn initial query embeddings.
        tgt_embed (nn.Embedding): Target embeddings for queries.
        query_pos_head (MLP): Query position head.
        enc_output (nn.Sequential): Encoder output layers.
        enc_score_head (nn.Linear): Encoder score prediction head.
        enc_bbox_head (MLP): Encoder bbox prediction head.
        dec_score_head (nn.ModuleList): Decoder score prediction heads.
        dec_bbox_head (nn.ModuleList): Decoder bbox prediction heads.

    Methods:
        forward: Run forward pass and return bounding box and classification scores.

    Examples:
        Create an RTDETRDecoder
        >>> decoder = RTDETRDecoder(nc=80, ch=(512, 1024, 2048), hd=256, nq=300)
        >>> x = [torch.randn(1, 512, 64, 64), torch.randn(1, 1024, 32, 32), torch.randn(1, 2048, 16, 16)]
        >>> outputs = decoder(x)
    """

    export = False  # export mode
    format = None  # export format
    max_det = 300  # max detections per image
    shapes = []
    anchors = torch.empty(0)
    valid_mask = torch.empty(0)
    dynamic = False

    def __init__(
        self,
        nc: int = 80,
        ch: list[int] | tuple[int, ...] = (512, 1024, 2048),
        hd: int = 256,  # hidden dim
        nq: int = 300,  # num queries
        ndp: int = 4,  # num decoder points
        nh: int = 8,  # num head
        ndl: int = 6,  # num decoder layers
        d_ffn: int = 1024,  # dim of feedforward
        dropout: float = 0.0,
        act: nn.Module | None = None,
        eval_idx: int = -1,
        # Training args
        nd: int = 100,  # num denoising
        label_noise_ratio: float = 0.5,
        box_noise_scale: float = 1.0,
        learnt_init_query: bool = False,
    ):
        """Initialize the RTDETRDecoder module with the given parameters.

        Args:
            nc (int): Number of classes.
            ch (list[int] | tuple[int, ...]): Channels in the backbone feature maps.
            hd (int): Dimension of hidden layers.
            nq (int): Number of query points.
            ndp (int): Number of sampling points per attention head per feature level in the decoder.
            nh (int): Number of heads in multi-head attention.
            ndl (int): Number of decoder layers.
            d_ffn (int): Dimension of the feed-forward networks.
            dropout (float): Dropout rate.
            act (nn.Module, optional): Activation function. Defaults to nn.ReLU() if None.
            eval_idx (int): Index of the decoder layer used for inference; negative values count from the end.
            nd (int): Number of denoising queries.
            label_noise_ratio (float): Label noise ratio.
            box_noise_scale (float): Box noise scale.
            learnt_init_query (bool): Whether to learn initial query embeddings.
        """
        super().__init__()
        act = nn.ReLU() if act is None else act
        self.hidden_dim = hd
        self.nhead = nh
        self.nl = len(ch)  # num level
        self.nc = nc
        self.num_queries = nq
        self.num_decoder_layers = ndl

        # Backbone feature projection
        self.input_proj = nn.ModuleList(nn.Sequential(nn.Conv2d(x, hd, 1, bias=False), nn.BatchNorm2d(hd)) for x in ch)
        # NOTE: simplified version but it's not consistent with .pt weights.
        # self.input_proj = nn.ModuleList(Conv(x, hd, act=False) for x in ch)

        # Transformer module
        decoder_layer = DeformableTransformerDecoderLayer(hd, nh, d_ffn, dropout, act, self.nl, ndp)
        self.decoder = DeformableTransformerDecoder(hd, decoder_layer, ndl, eval_idx)

        # Denoising part
        self.denoising_class_embed = nn.Embedding(nc, hd)
        self.num_denoising = nd
        self.label_noise_ratio = label_noise_ratio
        self.box_noise_scale = box_noise_scale

        # Decoder embedding
        self.learnt_init_query = learnt_init_query
        if learnt_init_query:
            self.tgt_embed = nn.Embedding(nq, hd)
        self.query_pos_head = MLP(4, 2 * hd, hd, num_layers=2)

        # Encoder head
        self.enc_output = nn.Sequential(nn.Linear(hd, hd), nn.LayerNorm(hd))
        self.enc_score_head = nn.Linear(hd, nc)
        self.enc_bbox_head = MLP(hd, hd, 4, num_layers=3)

        # Decoder head
        self.dec_score_head = nn.ModuleList([nn.Linear(hd, nc) for _ in range(ndl)])
        self.dec_bbox_head = nn.ModuleList([MLP(hd, hd, 4, num_layers=3) for _ in range(ndl)])

        self._reset_parameters()

@staticmethod
def _generate_anchors(
    shapes: list[list[int]],
    feats: torch.Tensor,
    grid_size: float = 0.05,
    eps: float = 1e-2,
) -> tuple[torch.Tensor, torch.Tensor]:
    """Generate anchor bounding boxes for given shapes with specific grid size and validate them.

    Args:
        shapes (list): List of feature map shapes.
        feats (torch.Tensor): Tensor whose dtype and device the anchors inherit.
        grid_size (float, optional): Base size of grid cells.
        eps (float, optional): Small value for numerical stability.

    Returns:
        anchors (torch.Tensor): Anchor boxes in inverse-sigmoid (logit) space with shape (1, sum(h * w), 4), set to
            inf where invalid.
        valid_mask (torch.Tensor): Boolean mask of valid anchors with shape (1, sum(h * w), 1).
    """
    anchors = []
    for i, (h, w) in enumerate(shapes):
        sy = torch.arange(h).type_as(feats)  # type_as inherits the runtime device in traces, unlike device=
        sx = torch.arange(w).type_as(feats)
        grid_y, grid_x = torch.meshgrid(sy, sx, indexing="ij") if TORCH_1_11 else torch.meshgrid(sy, sx)
        grid_xy = torch.stack([(grid_x + 0.5) / w, (grid_y + 0.5) / h], -1)[None]  # (1, h, w, 2)
        wh = torch.full_like(grid_xy, grid_size * (2.0**i))
        anchors.append(torch.cat([grid_xy, wh], -1).view(-1, h * w, 4))  # (1, h*w, 4)

    anchors = torch.cat(anchors, 1)  # (1, h*w*nl, 4)
    valid_mask = ((anchors > eps) & (anchors < 1 - eps)).all(-1, keepdim=True)  # 1, h*w*nl, 1
    anchors = torch.log(anchors / (1 - anchors))
    anchors = anchors.masked_fill(~valid_mask, float("inf"))
    return anchors, valid_mask

def _get_decoder_input(
    self,
    feats: torch.Tensor,
    shapes: list[list[int]],
    dn_embed: torch.Tensor | None = None,
    dn_bbox: torch.Tensor | None = None,
) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
    """Generate and prepare the input required for the decoder from the provided features and shapes.

    Args:
        feats (torch.Tensor): Processed features from encoder.
        shapes (list): List of feature map shapes.
        dn_embed (torch.Tensor, optional): Denoising embeddings.
        dn_bbox (torch.Tensor, optional): Denoising bounding boxes.

    Returns:
        embeddings (torch.Tensor): Query embeddings for decoder.
        refer_bbox (torch.Tensor): Reference bounding boxes as unnormalized logits.
        enc_bboxes (torch.Tensor): Encoder top-k bounding boxes, sigmoid-normalized.
        enc_scores (torch.Tensor): Encoder top-k class logits.
    """
    bs = feats.shape[0]
    if self.dynamic or self.shapes != shapes:
        self.anchors, self.valid_mask = self._generate_anchors(shapes, feats)
        self.shapes = shapes

    # Prepare input for decoder
    features = self.enc_output(self.valid_mask * feats)  # bs, h*w, 256
    enc_outputs_scores = self.enc_score_head(features)  # (bs, h*w, nc)

    # Query selection
    # (bs*num_queries,)
    groups = 8 if self.export and self.format == "engine" and not self.dynamic else 1
    k = (
        torch._shape_as_tensor(enc_outputs_scores)[1].clamp(max=self.num_queries)
        if self.dynamic
        else min(self.num_queries, enc_outputs_scores.shape[1])
    )
    topk_ind = Detect._grouped_topk(enc_outputs_scores.max(-1).values, k, groups)[1].view(-1)
    # (bs*num_queries,)
    batch_ind = torch.arange(end=bs, dtype=topk_ind.dtype).unsqueeze(-1).repeat(1, k).view(-1)

    # (bs, num_queries, 256)
    top_k_features = features[batch_ind, topk_ind].view(bs, k, -1)
    # (bs, num_queries, 4)
    top_k_anchors = self.anchors[:, topk_ind].view(bs, k, -1)

    # Dynamic anchors + static content
    refer_bbox = self.enc_bbox_head(top_k_features) + top_k_anchors

    enc_bboxes = refer_bbox.sigmoid()
    if dn_bbox is not None:
        refer_bbox = torch.cat([dn_bbox, refer_bbox], 1)
    enc_scores = enc_outputs_scores[batch_ind, topk_ind].view(bs, k, -1)

    embeddings = (
        self.tgt_embed.weight[:k].unsqueeze(0).repeat(bs, 1, 1) if self.learnt_init_query else top_k_features
    )
    if self.training:
        refer_bbox = refer_bbox.detach()
        if not self.learnt_init_query:
            embeddings = embeddings.detach()
    if dn_embed is not None:
        embeddings = torch.cat([dn_embed, embeddings], 1)

    return embeddings, refer_bbox, enc_bboxes, enc_scores

def _get_encoder_input(self, x: list[torch.Tensor]) -> tuple[torch.Tensor, list[list[int]]]:
    """Process and return encoder inputs by getting projection features from input and concatenating them.

    Args:
        x (list[torch.Tensor]): List of feature maps from the backbone.

    Returns:
        feats (torch.Tensor): Processed features.
        shapes (list): List of feature map shapes.
    """
    # Get projection features
    x = [self.input_proj[i](feat) for i, feat in enumerate(x)]
    # Get encoder inputs
    feats = []
    shapes = []
    for feat in x:
        h, w = feat.shape[2:]
        # [b, c, h, w] -> [b, h*w, c]
        feats.append(feat.flatten(2).permute(0, 2, 1))
        # [nl, 2]
        shapes.append([h, w])

    # [b, h*w, c]
    feats = torch.cat(feats, 1)
    return feats, shapes

def _reset_parameters(self):
    """Initialize or reset the parameters of the model's various components with predefined weights and biases."""
    # Class and bbox head init
    bias_cls = bias_init_with_prob(0.01) / 80 * self.nc
    constant_(self.enc_score_head.bias, bias_cls)
    constant_(self.enc_bbox_head.layers[-1].weight, 0.0)
    constant_(self.enc_bbox_head.layers[-1].bias, 0.0)
    for cls_, reg_ in zip(self.dec_score_head, self.dec_bbox_head):
        constant_(cls_.bias, bias_cls)
        constant_(reg_.layers[-1].weight, 0.0)
        constant_(reg_.layers[-1].bias, 0.0)

    xavier_uniform_(self.enc_output[0].weight)
    if self.learnt_init_query:
        xavier_uniform_(self.tgt_embed.weight)
    xavier_uniform_(self.query_pos_head.layers[0].weight)
    xavier_uniform_(self.query_pos_head.layers[1].weight)
    for layer in self.input_proj:
        xavier_uniform_(layer[0].weight)

def forward(self, x: list[torch.Tensor], batch: dict | None = None) -> tuple | torch.Tensor:
    """Run the forward pass of the module, returning bounding box and classification scores for the input.

    Args:
        x (list[torch.Tensor]): List of feature maps from the backbone.
        batch (dict, optional): Batch information for training.

    Returns:
        (tuple | torch.Tensor): During training, a tuple of (dec_bboxes, dec_scores, enc_bboxes, enc_scores,
            dn_meta). During inference, a tensor of shape (bs, k, 6) with [cx, cy, w, h, score, class_index] (see
            `postprocess`), returned alone in export mode and otherwise as a (predictions, raw outputs) tuple.
    """
    from ultralytics.models.utils.ops import get_cdn_group

    # Input projection and embedding
    feats, shapes = self._get_encoder_input(x)

    # Prepare denoising training
    dn_embed, dn_bbox, attn_mask, dn_meta = get_cdn_group(
        batch,
        self.nc,
        min(self.num_queries, feats.shape[1]),
        self.denoising_class_embed.weight,
        self.num_denoising,
        self.label_noise_ratio,
        self.box_noise_scale,
        self.training,
    )

    embed, refer_bbox, enc_bboxes, enc_scores = self._get_decoder_input(feats, shapes, dn_embed, dn_bbox)

    # Decoder
    dec_bboxes, dec_scores = self.decoder(
        embed,
        refer_bbox,
        feats,
        shapes,
        self.dec_bbox_head,
        self.dec_score_head,
        self.query_pos_head,
        attn_mask=attn_mask,
    )
    if self.training and dn_meta is None:
        # Touch denoising_class_embed so DDP sees it as used when batch has zero GTs.
        dec_bboxes = dec_bboxes + 0 * self.denoising_class_embed.weight.sum()
    x = dec_bboxes, dec_scores, enc_bboxes, enc_scores, dn_meta
    if self.training:
        return x
    # (bs, num_queries, 4), (bs, num_queries, nc)
    y = self.postprocess(dec_bboxes.squeeze(0), dec_scores.squeeze(0).sigmoid())
    return y if self.export else (y, x)

def postprocess(self, boxes: torch.Tensor, scores: torch.Tensor) -> torch.Tensor:
    """Post-process predictions to select top-k detections.

    Args:
        boxes (torch.Tensor): Predicted bounding boxes with shape (batch_size, num_queries, 4) in xywh format.
        scores (torch.Tensor): Class scores with shape (batch_size, num_queries, nc).

    Returns:
        (torch.Tensor): Processed predictions with shape (batch_size, num_queries, 6), limited to max_det during
            export, and last dimension format [cx, cy, w, h, score, class_index].
    """
    k = min(self.num_queries, self.max_det) if self.export else self.num_queries
    k = (
        (torch._shape_as_tensor(scores)[1] * self.nc).clamp(max=k)
        if self.dynamic
        else min(k, scores.shape[1] * self.nc)
    )
    groups = 8 if self.export and self.format == "engine" and not self.dynamic else 1
    scores, index = Detect._grouped_topk(scores.flatten(1), k, groups)
    # CoreML MIL lacks integer floor-div and mod lowering: use torch.div(rounding_mode="floor") and (index - q*nc).
    query_idx = torch.div(index, self.nc, rounding_mode="floor")
    boxes = boxes.gather(dim=1, index=query_idx.unsqueeze(-1).expand(-1, -1, 4).long())
    return torch.cat([boxes, scores[..., None], (index - query_idx * self.nc)[..., None].float()], dim=-1)

class v10Detect(Detect):
    """v10 Detection head from https://arxiv.org/pdf/2405.14458.

    This class implements the YOLOv10 detection head with dual-assignment training and consistent dual predictions for
    improved efficiency and performance.

    Attributes:
        end2end (bool): End-to-end detection mode.
        max_det (int): Maximum number of detections.
        cv3 (nn.ModuleList): Light classification head layers.
        one2one_cv3 (nn.ModuleList): One-to-one classification head layers.

    Methods:
        __init__: Initialize the v10Detect object with specified number of classes and input channels.
        forward: Perform forward pass of the v10Detect module.
        bias_init: Initialize biases of the Detect module.
        fuse: Remove the unused detection branch for inference.

    Examples:
        Create a v10Detect head
        >>> v10_detect = v10Detect(nc=80, ch=(256, 512, 1024))
        >>> x = [torch.randn(1, 256, 80, 80), torch.randn(1, 512, 40, 40), torch.randn(1, 1024, 20, 20)]
        >>> outputs = v10_detect(x)
    """

    def __init__(self, nc: int = 80, ch: list[int] | tuple[int, ...] = ()):
        """Initialize the v10Detect object with the specified number of classes and input channels.

        Args:
            nc (int): Number of classes.
            ch (list[int] | tuple[int, ...]): Channel sizes from backbone feature maps.
        """
        super().__init__(nc, end2end=True, ch=ch)
        c3 = max(ch[0], min(self.nc, 100))  # channels
        # Light cls head
        self.cv3 = nn.ModuleList(
            nn.Sequential(
                nn.Sequential(Conv(x, x, 3, g=x), Conv(x, c3, 1)),
                nn.Sequential(Conv(c3, c3, 3, g=c3), Conv(c3, c3, 1)),
                nn.Conv2d(c3, self.nc, 1),
            )
            for x in ch
        )
        self.one2one_cv3 = copy.deepcopy(self.cv3)

class SemanticSegment(nn.Module):
    """YOLO semantic segmentation head for per-pixel classification.

    This head produces dense per-pixel class predictions. Unlike instance segmentation, no bounding boxes or instance
    masks are produced.

    Attributes:
        nc (int): Number of semantic classes.
        nl (int): Number of input feature levels.
        stride (torch.Tensor): Feature map strides.
        export (bool): Export mode flag.
        format (str): Export format.
        bake_argmax (bool): Whether TensorRT or Hailo exports bake the argmax class map into the output.
        classifier (nn.Sequential): Final convolutional classifier head.
        aux_head (nn.Sequential | None): Auxiliary classifier on P4 for deep supervision.
    """

    export = False  # export mode
    format = None  # export format
    bake_argmax = False  # export: emit [B, H, W] class map (TensorRT>=10 and multi-class Hailo-10/15)

    def __init__(self, nc: int = 19, ch: list[int] | tuple[int, ...] = ()):
        """Initialize the semantic segmentation head.

        Args:
            nc (int): Number of semantic classes.
            ch (list[int] | tuple[int, ...]): Channel sizes from neck feature maps (P3, P4).
        """
        super().__init__()
        self.nc = nc
        self.nl = len(ch)
        self.stride = torch.zeros(self.nl)

        c_mid = ch[0]  # use P3 channel width as intermediate dimension
        # Final classifier
        self.classifier = nn.Sequential(Conv(c_mid, c_mid, 3), nn.Conv2d(c_mid, nc, 1))
        # Auxiliary head on P4 (index 1) for training
        self.aux_head = nn.Sequential(Conv(ch[1], c_mid, 3), nn.Conv2d(c_mid, nc, 1)) if len(ch) > 1 else None

def forward(self, x):
    """Forward pass: fuse multi-scale features and predict per-pixel classes.

    Args:
        x (list[torch.Tensor]): List of feature maps [P3, P4].

    Returns:
        (torch.Tensor | tuple): Logits of shape [B, nc, H/8, W/8] during training (or a (main, aux) tuple when
            aux_head is present) and inference. ONNX, MNN, OpenVINO, TensorRT>=10, and multi-class Hailo-10/15
            export bake in the class reduction and return a compact map of shape [B, H, W] (uint8 when nc <= 256,
            else int32). Other export formats return upsampled logits of shape [B, nc, H, W].
    """
    # Classify
    logits = self.classifier(x[0])  # [B, nc, H/8, W/8]
    if self.training:
        if self.aux_head is not None:
            return logits, self.aux_head(x[1])  # main + aux (P4)
        return logits
    if self.export:
        y = F.interpolate(logits, scale_factor=8, mode="bilinear", align_corners=False)  # [B, nc, H, W]
        # Bake class reduction: emit [B, H, W] map, shrinking the D2H copy ~80x. ONNX/MNN/OpenVINO and
        # multi-class Hailo-10/15 preserve the integer output; TensorRT supports uint8 graph outputs only on
        # TRT>=10, so engine and Hailo baking are gated by the exporter.
        if self.format in {"onnx", "mnn", "openvino"} or (self.format in {"engine", "hailo"} and self.bake_argmax):
            cls = y.argmax(1) if self.nc > 1 else y.squeeze(1) > 0
            return cls.to(torch.uint8 if self.nc <= 256 else torch.int32)
        return y
    return logits