easydetect 0.2.2__tar.gz → 0.3.0__tar.gz

{easydetect-0.2.2 → easydetect-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: easydetect
-Version: 0.2.2
+Version: 0.3.0
 Summary: Easy real-time object detection you can ship: D-FINE with PyTorch training, OpenVINO inference on CPU/GPU/NPU, and a browser app to label and train. Apache-2.0 throughout.
 Project-URL: Homepage, https://github.com/themakerrobot/easydetect
 Project-URL: Source, https://github.com/themakerrobot/easydetect

{easydetect-0.2.2 → easydetect-0.3.0}/easydetect/__init__.py

@@ -24,7 +24,7 @@ needs numpy/opencv/openvino/pyyaml; training adds
 
 from __future__ import annotations
 
-__version__ = "0.2.2"
+__version__ = "0.3.0"
 
 from .errors import DownloadError, EasyDetectError, ModelNotFoundError
 from .metrics import BoxMetrics, DetMetrics

{easydetect-0.2.2 → easydetect-0.3.0}/easydetect/cli.py

@@ -28,8 +28,8 @@ Modes:
 
 Common keys:
   model=dfine-n|s|m|l|x|best.pt|model.xml   source=bus.jpg|dir|video.mp4|0|url
-  data=data.yaml  epochs=100  imgsz=640  batch=8  conf=0.25  iou=0.7|none  device=0|cpu|AUTO
-  project=runs  name=predict  save=true  show=false  format=openvino  half=true
+  data=data.yaml  epochs=100  imgsz=640  batch=8  conf=0.5  iou=0.7|none  device=0|cpu|AUTO
+  contain=0.8  project=runs  name=predict  save=true  show=false  format=openvino  half=true
 
 Examples:
   easydetect predict model=dfine-s source=bus.jpg conf=0.5

{easydetect-0.2.2 → easydetect-0.3.0}/easydetect/model.py

@@ -114,12 +114,13 @@ class Detector:
     def predict(
         self,
         source: Any = None,
-        conf: float = 0.25,
+        conf: float = 0.5,
         imgsz: int | None = None,
         device: str | None = None,
         max_det: int = 300,
         classes: list[int] | None = None,
         iou: float | None = 0.7,
+        contain: float | None = None,
         stream: bool = False,
         save: bool = False,
         show: bool = False,
@@ -133,9 +134,14 @@ class Detector:
         """Run detection on any supported source.
 
         Returns a ``list[Results]``, or a generator when ``stream=True`` (the
-        only sane option for a long video or a live camera). ``iou`` drops a
-        box covering a higher-scoring one by more than that IoU — the same
-        object found twice, sometimes under two classes; ``None`` keeps all.
+        only sane option for a long video or a live camera). ``conf=0.5``
+        is where D-FINE's boxes are mostly right (70% on COCO, against 32% at
+        YOLO's usual 0.25). ``iou`` drops a box covering a higher-scoring one
+        by more than that IoU — the same object found twice, sometimes under
+        two classes; ``None`` keeps all. ``contain=0.8`` also merges a box
+        with 80% of its area inside another of its class — the visible pieces
+        of a half hidden object beside the whole of it — into one box; off by
+        default, as on COCO it removes more real objects than it fixes.
         """
         if source is None:
             raise ValueError("predict() needs a source (image, folder, video, url, camera index)")
@@ -152,6 +158,7 @@ class Detector:
             max_det=max_det,
             classes=classes,
             iou=iou,
+            contain=contain,
             save=save,
             show=show,
             project=project,
@@ -166,8 +173,9 @@ class Detector:
     def track(
         self,
         source: Any = None,
-        conf: float = 0.25,
+        conf: float = 0.5,
         iou: float | None = 0.7,
+        contain: float | None = None,
         match_iou: float = 0.3,
         max_age: int = 30,
         persist: bool = False,
@@ -176,7 +184,7 @@ class Detector:
     ) -> Any:
         """Predict, and keep an id on each box across frames (``boxes.id``).
 
-        ``iou`` is the duplicate filter, as in :meth:`predict`. ``match_iou``
+        ``iou`` and ``contain`` filter duplicates, as in :meth:`predict`. ``match_iou``
         is how much a box must overlap a track in the previous frame to carry
         its id on; ``max_age`` is how many frames a track waits for its object.
         """
@@ -185,7 +193,7 @@ class Detector:
         if self.tracker is None or not persist:
             self.tracker = IoUTracker(iou=match_iou, max_age=max_age)
         kwargs.setdefault("name", "track")
-        gen = self._run(source, conf=conf, iou=iou, tracker=self.tracker,
+        gen = self._run(source, conf=conf, iou=iou, contain=contain, tracker=self.tracker,
                         **self._track_kwargs(kwargs))
         return _Stream(gen, "track") if stream else list(gen)
 
@@ -203,12 +211,13 @@ class Detector:
     def _run(
         self,
         source: Any,
-        conf: float = 0.25,
+        conf: float = 0.5,
         imgsz: int | None = None,
         device: str | None = None,
         max_det: int = 300,
         classes: list[int] | None = None,
         iou: float | None = 0.7,
+        contain: float | None = None,
         save: bool = False,
         show: bool = False,
         project: str = "runs",
@@ -230,7 +239,7 @@ class Detector:
         try:
             for frame in loader:
                 det, speed = predictor(frame.img, conf=conf, max_det=max_det, classes=classes,
-                                       iou=iou)
+                                       iou=iou, contain=contain)
                 if tracker is not None:
                     det = tracker.update(det)
                 result = Results(

{easydetect-0.2.2 → easydetect-0.3.0}/easydetect/predictor.py

@@ -128,6 +128,12 @@ def read_names(model_path: Path) -> dict[int, str]:
 #: Default for ``iou``: above this IoU, two boxes are one object.
 IOU = 0.7
 
+#: Default for ``conf``. D-FINE gives an unsure box 0.3-0.5 where YOLO would
+#: give it under 0.25, so YOLO's 0.25 shows mostly mistakes here: dfine-m on
+#: COCO val2017 (NMS 0.7) shows boxes 32% right at 0.25, 70% at 0.5, while
+#: still finding 67% of the objects. See docs/performance.md.
+CONF = 0.5
+
 
 def drop_duplicates(xyxy: np.ndarray, iou: float = IOU) -> np.ndarray:
     """Indices of the boxes to keep, from boxes sorted best first.
@@ -158,6 +164,52 @@ def drop_duplicates(xyxy: np.ndarray, iou: float = IOU) -> np.ndarray:
     return np.nonzero(alive)[0]
 
 
+#: How much less sure an enclosing box may be than the box inside it and still
+#: count as the whole object rather than a loose box around several.
+CONTAIN_MARGIN = 0.1
+
+
+def drop_contained(xyxy: np.ndarray, scores: np.ndarray, cls: np.ndarray,
+                   contain: float) -> np.ndarray:
+    """Indices of the boxes to keep when a box lies inside another of its class.
+
+    IoU cannot see a part inside a whole: a chair half hidden behind a person
+    can come back as the whole chair (0.64) plus its two visible pieces (0.67,
+    0.61), and each piece overlaps the whole by an IoU of only its share of the
+    area. Measured as the overlap over the *smaller* box instead, a piece sits
+    near 1.0, so a pair of one class sharing at least ``contain`` of the
+    smaller box is one object, and one box goes:
+
+    * the inner one, when the enclosing box is about as sure (within
+      ``CONTAIN_MARGIN``) — the whole object and a piece of it;
+    * the enclosing one, when it is much less sure than the box inside — a
+      loose box around a group, which must not erase the members.
+
+    NMS's "keep the best" would not do here: the best box is a piece, and once
+    it has removed the whole, the other piece no longer overlaps anything and
+    stays — two half chairs. Same class only: a cup on a table is not part of
+    the table. The cost is a real object inside another of its class, a child
+    held by an adult, so this is off unless asked for.
+    """
+    x1, y1, x2, y2 = xyxy.T
+    area = np.clip(x2 - x1, 0, None) * np.clip(y2 - y1, 0, None)
+    gone = np.zeros(len(xyxy), bool)
+    for i in range(len(xyxy)):
+        for j in range(i + 1, len(xyxy)):
+            if cls[i] != cls[j]:
+                continue
+            iw = max(0.0, min(x2[i], x2[j]) - max(x1[i], x1[j]))
+            ih = max(0.0, min(y2[i], y2[j]) - max(y1[i], y1[j]))
+            if iw * ih < contain * max(min(area[i], area[j]), 1e-9):
+                continue
+            big, small = (i, j) if area[i] >= area[j] else (j, i)
+            if scores[big] >= scores[small] - CONTAIN_MARGIN:
+                gone[small] = True
+            else:
+                gone[big] = True
+    return np.nonzero(~gone)[0]
+
+
 def _split_outputs(arrays: list[np.ndarray]) -> tuple[np.ndarray, np.ndarray]:
     """``(boxes, scores)`` for the one image in a batch, whatever order they come in."""
     boxes = next((a for a in arrays if a.shape[-1] == 4), None)
@@ -231,16 +283,19 @@ class Predictor:
         boxes: np.ndarray,
         scores: np.ndarray,
         orig_shape: tuple[int, int],
-        conf: float = 0.25,
+        conf: float = CONF,
         max_det: int = 300,
         classes: list[int] | None = None,
         iou: float | None = IOU,
+        contain: float | None = None,
     ) -> np.ndarray:
         """-> ``(N, 6)`` array of ``x1 y1 x2 y2 conf cls`` in pixels.
 
         ``iou`` drops a box that covers a higher-scoring one by more than that
         IoU, whatever the two classes (``None`` keeps them all): see
-        :func:`drop_duplicates`.
+        :func:`drop_duplicates`. ``contain`` (off by default) also drops a box
+        lying mostly inside another of its class: see
+        :func:`drop_contained`.
         """
         if _looks_like_logits(scores):
             scores = 1.0 / (1.0 + np.exp(-scores))
@@ -263,6 +318,9 @@ class Predictor:
         if iou is not None and len(xyxy) > 1:
             kept = drop_duplicates(xyxy, iou)
             xyxy, best, cls = xyxy[kept], best[kept], cls[kept]
+        if contain is not None and len(xyxy) > 1:
+            kept = drop_contained(xyxy, best, cls, contain)
+            xyxy, best, cls = xyxy[kept], best[kept], cls[kept]
         return np.concatenate(
             [xyxy, best.astype(np.float32)[:, None], cls.astype(np.float32)[:, None]], axis=1
         )
@@ -270,10 +328,11 @@ class Predictor:
     def __call__(
         self,
         img: np.ndarray,
-        conf: float = 0.25,
+        conf: float = CONF,
         max_det: int = 300,
         classes: list[int] | None = None,
         iou: float | None = IOU,
+        contain: float | None = None,
     ) -> tuple[np.ndarray, dict[str, float]]:
         """Run one image; returns ``(detections (N,6), speed dict in ms)``."""
         import time
@@ -283,7 +342,8 @@ class Predictor:
         t1 = time.perf_counter()
         boxes, scores = self.infer(tensor)
         t2 = time.perf_counter()
-        det = self.postprocess(boxes, scores, img.shape[:2], conf, max_det, classes, iou)
+        det = self.postprocess(boxes, scores, img.shape[:2], conf, max_det, classes, iou,
+                               contain)
         t3 = time.perf_counter()
         speed = {
             "preprocess": (t1 - t0) * 1e3,

{easydetect-0.2.2 → easydetect-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "easydetect"
-version = "0.2.2"
+version = "0.3.0"
 description = "Easy real-time object detection you can ship: D-FINE with PyTorch training, OpenVINO inference on CPU/GPU/NPU, and a browser app to label and train. Apache-2.0 throughout."
 readme = "README.md"
 requires-python = ">=3.10"

{easydetect-0.2.2 → easydetect-0.3.0}/tests/test_predictor.py

@@ -147,3 +147,69 @@ def test_one_predictor_can_be_shared_between_threads(tiny_ir):
     for thread in threads:
         thread.join()
     assert failures == []
+
+
+def test_a_half_hidden_object_and_its_pieces_become_one_box():
+    from easydetect.predictor import drop_contained, drop_duplicates
+
+    # best first: a piece (0.67), the whole chair (0.64), another piece (0.61),
+    # and a second chair beside it that only touches the first
+    xyxy = np.array([[320, 520, 372, 640],     # lower right piece
+                     [285, 455, 373, 640],     # the whole chair
+                     [285, 470, 330, 640],     # left piece
+                     [380, 455, 470, 640]],    # another chair
+                    np.float32)
+    scores = np.array([0.67, 0.64, 0.61, 0.60])
+    cls = np.array([56, 56, 56, 56])
+    assert list(drop_duplicates(xyxy, 0.7)) == [0, 1, 2, 3]     # IoU sees four chairs
+    # the whole chair stays, its pieces go; the chair beside it is left alone
+    assert list(drop_contained(xyxy, scores, cls, 0.8)) == [1, 3]
+
+
+def test_a_loose_box_around_a_group_does_not_erase_its_members():
+    from easydetect.predictor import drop_contained
+
+    xyxy = np.array([[0, 0, 50, 100], [50, 0, 100, 100], [0, 0, 100, 100]], np.float32)
+    scores = np.array([0.9, 0.85, 0.3])               # two people, and a box around both
+    assert list(drop_contained(xyxy, scores, np.zeros(3), 0.8)) == [0, 1]
+
+
+def test_containment_never_crosses_classes():
+    from easydetect.predictor import drop_contained
+
+    xyxy = np.array([[0, 0, 100, 100], [10, 10, 40, 40]], np.float32)   # a cup on a table
+    scores = np.array([0.8, 0.7])
+    assert list(drop_contained(xyxy, scores, np.array([60, 41]), 0.8)) == [0, 1]
+    assert list(drop_contained(xyxy, scores, np.array([60, 60]), 0.8)) == [0]
+
+
+def test_the_whole_path_merges_pieces_only_when_asked():
+    """postprocess as predict() runs it: model outputs in, boxes out, at 640 x 720."""
+    from easydetect.predictor import Predictor
+
+    pieces = [(320, 520, 372, 640, 0.67), (285, 455, 373, 640, 0.64), (285, 470, 330, 640, 0.61),
+              (40, 100, 340, 640, 0.97)]                   # three chair boxes and a person
+    boxes = np.array([[(x1 + x2) / 2 / 640, (y1 + y2) / 2 / 720, (x2 - x1) / 640,
+                       (y2 - y1) / 720] for x1, y1, x2, y2, _ in pieces], np.float32)
+    scores = np.zeros((4, 80), np.float32)
+    for i, (*_, s) in enumerate(pieces):
+        scores[i, 0 if i == 3 else 56] = s
+    post = Predictor.postprocess.__get__(object.__new__(Predictor))
+    default = post(boxes, scores, (720, 640), conf=0.5)
+    merged = post(boxes, scores, (720, 640), conf=0.5, contain=0.8)
+    assert len(default) == 4                                # NMS at 0.7 keeps every piece
+    assert sorted(merged[:, 5].tolist()) == [0, 56]         # one person, one chair
+    chair = merged[merged[:, 5] == 56][0]
+    assert chair[:4].round().tolist() == [285, 455, 373, 640]   # the whole of it
+
+
+def test_the_defaults_are_the_measured_ones():
+    """conf 0.5, NMS 0.7, contain off: docs/performance.md, 'Confidence and overlap defaults'."""
+    import inspect
+
+    from easydetect import Detector
+
+    for method in (Detector.predict, Detector.track):
+        params = inspect.signature(method).parameters
+        assert params["conf"].default == 0.5 and params["iou"].default == 0.7
+        assert params["contain"].default is None

{easydetect-0.2.2 → easydetect-0.3.0}/tools/hub_README.md

@@ -29,7 +29,7 @@ pip install easydetect          # OpenVINO and ONNX Runtime, no PyTorch
 from easydetect import Detector
 
 model = Detector("dfine-s")                 # downloads dfine-s/ from this repo once
-results = model("photo.jpg", conf=0.25)
+results = model("photo.jpg", conf=0.5)
 results[0].save("result.jpg")
 
 for r in model.predict(0, stream=True, show=True):   # webcam; q or Esc quits