holocron.ops#

holocron.ops implements operators that are specific for Computer Vision.

Note

Those operators currently do not support TorchScript.

Boxes#

holocron.ops.box_giou(boxes1: Tensor, boxes2: Tensor) → Tensor[source]#

Computes the Generalized-IoU as described in “Generalized Intersection over Union: A Metric and A Loss for Bounding Box Regression”. This implementation was adapted from https://github.com/facebookresearch/detr/blob/master/util/box_ops.py

The generalized IoU is defined as follows:

\[GIoU = IoU - \frac{|C - A \cup B|}{|C|}\]

where \(IoU\) is the Intersection over Union, \(A \cup B\) is the area of the boxes’ union, and \(C\) is the area of the smallest enclosing box covering the two boxes.

Parameters:
Returns:

Generalized-IoU

Return type:

torch.Tensor[M, N]

holocron.ops.diou_loss(boxes1: Tensor, boxes2: Tensor) → Tensor[source]#

Computes the Distance-IoU loss as described in “Distance-IoU Loss: Faster and Better Learning for Bounding Box Regression”.

The loss is defined as follows:

\[\mathcal{L}_{DIoU} = 1 - IoU + \frac{\rho^2(b, b^{GT})}{c^2}\]

where \(IoU\) is the Intersection over Union, \(b\) and \(b^{GT}\) are the centers of the box and the ground truth box respectively, \(c\) c is the diagonal length of the smallest enclosing box covering the two boxes, and \(\rho(.)\) is the Euclidean distance.

https://github.com/frgfm/Holocron/releases/download/v0.1.3/diou_loss.png
Parameters:
Returns:

Distance-IoU loss

Return type:

torch.Tensor[M, N]

holocron.ops.ciou_loss(boxes1: Tensor, boxes2: Tensor) → Tensor[source]#

Computes the Complete IoU loss as described in “Distance-IoU Loss: Faster and Better Learning for Bounding Box Regression”.

The loss is defined as follows:

\[\mathcal{L}_{CIoU} = 1 - IoU + \frac{\rho^2(b, b^{GT})}{c^2} + \alpha v\]

where \(IoU\) is the Intersection over Union, \(b\) and \(b^{GT}\) are the centers of the box and the ground truth box respectively, \(c\) c is the diagonal length of the smallest enclosing box covering the two boxes, \(\rho(.)\) is the Euclidean distance, \(\alpha\) is a positive trade-off parameter, and \(v\) is the aspect ratio consistency.

More specifically:

\[v = \frac{4}{\pi^2} \Big(\arctan{\frac{w^{GT}}{h^{GT}}} - \arctan{\frac{w}{h}}\Big)^2\]

and

\[\alpha = \frac{v}{(1 - IoU) + v}\]
Parameters:
Returns:

Complete IoU loss

Return type:

torch.Tensor[M, N]

Example

>>> import torch
>>> from holocron.ops.boxes import box_ciou
>>> boxes1 = torch.tensor([[0, 0, 100, 100], [100, 100, 200, 200]], dtype=torch.float32)
>>> boxes2 = torch.tensor([[50, 50, 150, 150]], dtype=torch.float32)
>>> box_ciou(boxes1, boxes2)