π Geometric Computer Vision Library for Spatial AI
Python artificial-intelligencecomputer-visiondeep-learninghacktoberfestimage-processingmachine-learningneural-networkpythonpytorchroboticsspatial-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.mdnew file mode 100644index 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.pyindex 183306e10..9cb425b8d 100644--- a/kornia/geometry/boxes.py+++ b/kornia/geometry/boxes.py@@ -22,6 +22,7 @@ from typing import Any, Optional, Tuple, castimport torchfrom torch import Size+from kornia.core._compat import _emit_deprecation_warningfrom kornia.core.check import _check_asyncfrom kornia.core.ops import eye_likefrom 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 atfixed 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 singlerow 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 singlerow broadcasts across the batch.inplace: If ``True``, clamp this object in place. Otherwise, return@@ -584,7 +584,7 @@ class Boxes:return objdef 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] = sizediff --git a/tests/geometry/test_boxes.py b/tests/geometry/test_boxes.pyindex 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 boxesdef 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):