Skip to content

🐍 Geometric Computer Vision Library for Spatial AI

fix(geometry): deprecate Boxes.trim and stop advertising the unimplemented Boxes paths (#6327)

Prateekshit Jaiswal19861759ff6b
diff --git a/changelog.d/6327.added.md b/changelog.d/6327.added.md
new file mode 100644
index 000000000..bc40515fc
--- /dev/null
+++ b/changelog.d/6327.added.md
@@ -0,0 +1 @@
+`Boxes.trim`, which was never implemented and always raised `NotImplementedError`, is deprecated and now also emits a `DeprecationWarning`; it will be removed in a future release. `Boxes.clamp` is annotated to take tensor bounds only, and `'fast'` is no longer listed as a `Boxes.translate` method; both paths always raised.
diff --git a/kornia/geometry/boxes.py b/kornia/geometry/boxes.py
index 183306e10..9cb425b8d 100644
--- a/kornia/geometry/boxes.py
+++ b/kornia/geometry/boxes.py
@@ -22,6 +22,7 @@ from typing import Any, Optional, Tuple, cast
import torch
from torch import Size
+from kornia.core._compat import _emit_deprecation_warning
from kornia.core.check import _check_async
from kornia.core.ops import eye_like
from kornia.core.utils import is_compiling, is_exporting
@@ -255,8 +256,7 @@ class Boxes:
`#4014 <https://github.com/kornia/kornia/issues/4014>`_. The integer-input split is
`#4012 <https://github.com/kornia/kornia/issues/4012>`_. ``'vertices'`` subtracts the inclusive offset at
fixed vertex slots, so it deforms a quadrilateral that is not an axis-aligned rectangle in clockwise order:
- `#3934 <https://github.com/kornia/kornia/issues/3934>`_. ``trim``, ``translate(method='fast')`` and
- tuple-bound ``clamp`` are unimplemented:
+ `#3934 <https://github.com/kornia/kornia/issues/3934>`_. ``trim`` was never implemented and is deprecated:
`#4017 <https://github.com/kornia/kornia/issues/4017>`_.
"""
@@ -526,8 +526,8 @@ class Boxes:
def clamp(
self,
- topleft: Optional[torch.Tensor | tuple[int, int]] = None,
- botright: Optional[torch.Tensor | tuple[int, int]] = None,
+ topleft: Optional[torch.Tensor] = None,
+ botright: Optional[torch.Tensor] = None,
inplace: bool = False,
) -> Boxes:
"""Clamp every box vertex inside per-image coordinate limits.
@@ -540,10 +540,10 @@ class Boxes:
outside the bounds collapses onto the boundary instead of being removed.
Args:
- topleft: Tensor of shape :math:`(B, 2)` containing the minimum
+ topleft: Required tensor of shape :math:`(B, 2)` containing the minimum
``x`` and ``y`` coordinate allowed for each batch item. A single
row broadcasts across the batch.
- botright: Tensor of shape :math:`(B, 2)` containing the maximum
+ botright: Required tensor of shape :math:`(B, 2)` containing the maximum
``x`` and ``y`` coordinate allowed for each batch item. A single
row broadcasts across the batch.
inplace: If ``True``, clamp this object in place. Otherwise, return
@@ -584,7 +584,7 @@ class Boxes:
return obj
def trim(self, correspondence_preserve: bool = False, inplace: bool = False) -> Boxes:
- """Raise because trimming padded boxes is not implemented.
+ """Deprecated since 0.9.1 and never implemented: raises ``NotImplementedError``.
See the Convention block on :class:`~kornia.geometry.boxes.Boxes`.
@@ -596,6 +596,9 @@ class Boxes:
NotImplementedError: Always.
"""
+ _emit_deprecation_warning(
+ "Boxes.trim", None, "0.9.1", "It has never been implemented and raises NotImplementedError (kornia#4017)."
+ )
raise NotImplementedError("`Boxes.trim` is not implemented.")
def filter_boxes_by_area(
@@ -967,27 +970,20 @@ class Boxes:
See the Convention block on :class:`~kornia.geometry.boxes.Boxes`.
``size`` supplies one ``(x, y)`` translation per batch item. Only the
- ``"warp"`` method is implemented; ``"fast"`` raises
+ ``"warp"`` method is supported; any other method raises
:class:`NotImplementedError`.
Args:
size: translate size for x, y direction, shape of :math:`(B, 2)`.
- method: "warp" or "fast".
+ method: only "warp" is supported.
inplace: do transform in-place and return self.
Returns:
The transformed boxes.
"""
- if method == "fast":
- raise NotImplementedError(
- "`Boxes.translate(method='fast')` is not implemented; use `method='warp'` instead."
- )
if method != "warp":
- raise NotImplementedError(
- "`Boxes.translate` accepts `method='warp'` or `method='fast'` (not implemented); "
- f"got method={method!r}."
- )
+ raise NotImplementedError(f"`Boxes.translate` accepts `method='warp'`; got method={method!r}.")
M: torch.Tensor = eye_like(3, size)
M[:, :2, 2] = size
diff --git a/tests/geometry/test_boxes.py b/tests/geometry/test_boxes.py
index 449cee53c..42546735c 100644
--- a/tests/geometry/test_boxes.py
+++ b/tests/geometry/test_boxes.py
@@ -923,7 +923,7 @@ class TestBoxes2D(BaseTester):
self.assert_close(boxes.data, original, atol=0.0, rtol=0.0)
def test_wart_clamp_tuple_bounds_and_outside_box_behavior_4017(self, device, dtype):
- # Wart pin for kornia#4017: tuple bounds are advertised but unsupported;
+ # Wart pin for kornia#4017: tuple bounds are no longer advertised and raise, as documented;
# tensor bounds clamp every vertex, collapsing a wholly outside box.
boxes = Boxes.from_tensor(
torch.tensor([[[8.0, 9.0, 10.0, 11.0]]], device=device, dtype=dtype),
@@ -944,14 +944,19 @@ class TestBoxes2D(BaseTester):
rtol=0.0,
)
- def test_wart_trim_and_fast_translate_are_unimplemented_4017(self, device, dtype):
- # Wart pin for kornia#4017: both documented entry points raise instead
- # of implementing their advertised operations.
+ def test_wart_trim_is_deprecated_and_fast_translate_is_unsupported_4017(self, device, dtype):
+ # Wart pin for kornia#4017: trim warns that it's deprecated and still raises,
+ # and "fast" is no longer advertised and raises.
boxes = Boxes.from_tensor(torch.tensor([[[1.0, 2.0, 5.0, 4.0]]], device=device, dtype=dtype), mode="xyxy")
- with pytest.raises(NotImplementedError, match=r"Boxes\.trim.*not implemented"):
- boxes.trim()
- with pytest.raises(NotImplementedError, match=r"fast.*not implemented.*warp"):
+ with pytest.raises(NotImplementedError, match=r"accepts `method='warp'`"):
boxes.translate(torch.tensor([[1.0, 2.0]], device=device, dtype=dtype), method="fast")
+ with (
+ pytest.warns(DeprecationWarning, match=r"Boxes\.trim") as record,
+ pytest.raises(NotImplementedError, match=r"Boxes\.trim.*not implemented"),
+ ):
+ boxes.trim()
+ assert len(record) == 1
+ assert record[0].filename == __file__
def test_convention_transform_boxes_in_place_rebinds_data(self, device, dtype):
# transform_boxes leaves its input unchanged by default. Its in-place
@@ -992,9 +997,9 @@ class TestBoxes2D(BaseTester):
assert translated is not boxes
def test_translate_unknown_method_raises(self, device, dtype):
- # The message names the accepted methods and repeats the rejected one, so a typo is visible.
+ # The message names the accepted method and repeats the rejected one, so a typo is visible.
boxes = Boxes.from_tensor(torch.tensor([[[1.0, 2.0, 5.0, 4.0]]], device=device, dtype=dtype), mode="xyxy")
- with pytest.raises(NotImplementedError, match=r"method='warp'.*method='fast'.*got method='wrap'"):
+ with pytest.raises(NotImplementedError, match=r"accepts `method='warp'`; got method='wrap'"):
boxes.translate(torch.tensor([[1.0, 2.0]], device=device, dtype=dtype), method="wrap")
def test_wart_filter_boxes_by_area_zeroes_small_boxes_4010(self, device, dtype):