easydetect 0.7.2__tar.gz → 0.7.4__tar.gz

{easydetect-0.7.2 → easydetect-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: easydetect
-Version: 0.7.2
+Version: 0.7.4
 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.7.2 → easydetect-0.7.4}/easydetect/__init__.py

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

{easydetect-0.7.2 → easydetect-0.7.4}/easydetect/benchmark.py

@@ -23,6 +23,8 @@ from pathlib import Path
 
 import numpy as np
 
+from easydetect.utils.imageio import imread  # any path, Hangul included
+
 
 def _model_files(spec) -> list[Path]:
     items = spec if isinstance(spec, (list, tuple)) else [spec]
@@ -75,7 +77,7 @@ def _picture(source) -> np.ndarray:
         return cv2.GaussianBlur(noise, (0, 0), 3)
     import cv2
 
-    img = cv2.imread(str(source))
+    img = imread(str(source))
     if img is None:
         raise FileNotFoundError(f"cannot read {source}")
     return img

{easydetect-0.7.2 → easydetect-0.7.4}/easydetect/data/dataset.py

@@ -19,6 +19,8 @@ import torch
 import yaml
 from torch.utils.data import Dataset
 
+from easydetect.utils.imageio import imread  # any path, Hangul included
+
 from . import augment as aug
 from .labels import label_path, label_row_to_box
 
@@ -201,7 +203,7 @@ class DetDataset(Dataset):
 
     def _raw(self, i):
         f = self.files[i]
-        img = cv2.imread(str(f))
+        img = imread(str(f))
         if img is None:
             raise FileNotFoundError(f)
         return img, self._load_labels(f)  # cls, cx, cy, w, h (normalized)

{easydetect-0.7.2 → easydetect-0.7.4}/easydetect/data/keypoints.py

@@ -22,6 +22,8 @@ from pathlib import Path
 import cv2
 import numpy as np
 
+from easydetect.utils.imageio import imread  # any path, Hangul included
+
 from ..pose import COCO, INPUT, KeypointSpec, box_to_crop, crop, crop_matrix
 from .augment import photometric
 
@@ -68,7 +70,7 @@ def _image_size(path: Path) -> tuple[int, int]:
         with Image.open(path) as im:
             return im.size
     except Exception:  # noqa: BLE001 — any reader trouble: decode it
-        img = cv2.imread(str(path))
+        img = imread(str(path))
         if img is None:
             raise FileNotFoundError(path) from None
         return img.shape[1], img.shape[0]
@@ -178,7 +180,7 @@ class KeypointDataset:
 
     def __getitem__(self, i: int):
         image_id, ann = self.items[i]
-        img = cv2.imread(str(self.images[image_id]))
+        img = imread(str(self.images[image_id]))
         if img is None:
             raise FileNotFoundError(self.images[image_id])
         kpts = np.asarray(ann["keypoints"], np.float64).reshape(-1, 3)

{easydetect-0.7.2 → easydetect-0.7.4}/easydetect/exporter.py

@@ -9,6 +9,8 @@ import threading
 import warnings
 from pathlib import Path
 
+from easydetect.utils.imageio import imread  # any path, Hangul included
+
 #: torch.onnx keeps global state while exporting ("in_onnx_export"), so two
 #: exports at once fail an assertion deep inside it. Serialise them — the
 #: whole export, names and conversion included, so that two threads exporting
@@ -168,7 +170,6 @@ def _int8_agreement(fp32, int8, images, imgsz) -> tuple[int, int]:
     """How many of the FP32 model's boxes (conf 0.5) the INT8 one finds again
     (same class, IoU 0.5) on some of the calibration pictures: NNCF quantizes
     without checking, and a model that loses objects should say so."""
-    import cv2
     import numpy as np
     import openvino as ov
 
@@ -181,7 +182,7 @@ def _int8_agreement(fp32, int8, images, imgsz) -> tuple[int, int]:
     step = max(len(images) // AGREEMENT_PICTURES, 1)
     found = total = 0
     for path in images[::step][:AGREEMENT_PICTURES]:
-        img = cv2.imread(str(path))
+        img = imread(str(path))
         if img is None:
             continue
         x = preprocess_image(img, imgsz)
@@ -202,7 +203,6 @@ def _int8_agreement(fp32, int8, images, imgsz) -> tuple[int, int]:
 
 def _quantize(model, images, imgsz):
     """8-bit weights and activations, calibrated on ``images`` (paths)."""
-    import cv2
     import nncf
 
     from .predictor import preprocess_image
@@ -212,7 +212,7 @@ def _quantize(model, images, imgsz):
         raise ValueError("int8 needs pictures to calibrate on: give data=")
 
     def transform(path):
-        img = cv2.imread(path)
+        img = imread(path)
         if img is None:
             raise ValueError(f"cannot read {path}")
         return preprocess_image(img, imgsz)

{easydetect-0.7.2 → easydetect-0.7.4}/easydetect/model.py

@@ -26,6 +26,8 @@ from typing import Any
 
 import numpy as np
 
+from easydetect.utils.imageio import cv2_path, imwrite  # any path, Hangul included
+
 from . import downloads
 from .errors import ModelNotFoundError
 from .metrics import DetMetrics
@@ -457,6 +459,11 @@ class Detector:
         self.names = {int(k): str(v) for k, v in ckpt.get("names", {}).items()}
         self.net = DFINENet(ckpt["variant"], ckpt["num_classes"], pretrained_backbone=False)
         self.net.load_state_dict(ckpt["model"])
+        # trained with fewer queries: runs (and fine-tunes again) with as many
+        if ckpt.get("queries") and ckpt["queries"] != self.net.decoder.num_queries:
+            self.net.trim(queries=int(ckpt["queries"]))
+        if ckpt.get("denoising") is not None:
+            self.net.decoder.num_denoising = int(ckpt["denoising"])
         self.net.eval()
         self.ir_path = None
         self.predictor = None
@@ -505,6 +512,8 @@ class Detector:
         seg_epochs: int = 20,
         seg_batch: int = 16,
         seg_lr: float = 1e-4,
+        queries: int | None = None,
+        denoising: int | None = None,
         **kwargs: Any,
     ) -> Path:
         """Train on a data.yaml dataset. Returns the path of ``best.pt``.
@@ -518,6 +527,12 @@ class Detector:
         ``on_epoch_end`` is called with a dict of the epoch's numbers — the
         same row that lands in ``results.csv``.
 
+        ``queries`` (of 300) and ``denoising`` (training-only queries, 100)
+        make every step cheaper; on a CPU most of a step is spent on them, not
+        on the picture. ``queries=100, denoising=30`` trains dfine-n about
+        twice as fast on a laptop and suits scenes with a handful of objects;
+        the model keeps ``queries`` (it runs faster too).
+
         A keypoint dataset (``kpt_shape`` in its data.yaml, Ultralytics' pose
         format) also trains a keypoint network after the detector: on crops of
         the labelled boxes, from the detector's backbone, for ``pose_epochs``
@@ -561,6 +576,10 @@ class Detector:
         elif self.net.num_classes != cfg["nc"]:
             self.net = self._reheaded_net(cfg["nc"])
 
+        if queries is not None:
+            self.net.trim(queries=int(queries))
+        if denoising is not None:
+            self.net.decoder.num_denoising = int(denoising)
         device = _torch_device(device)
         trainer = Trainer(
             self.net,
@@ -898,7 +917,7 @@ class _OutputWriter:
             out = self.save_dir / f"{stem}.jpg"
             if out.exists():
                 out = self.save_dir / f"{stem}_{frame.index}.jpg"
-            cv2.imwrite(str(out), img)
+            imwrite(str(out), img)
             return
         writer = self.videos.get(frame.path)
         if writer is None:
@@ -906,7 +925,7 @@ class _OutputWriter:
             h, w = img.shape[:2]
             # H.264 plays in browsers; OpenCV's pip wheels often lack it, so fall back
             for codec in ("avc1", "mp4v"):
-                writer = cv2.VideoWriter(str(self.save_dir / f"{stem}.mp4"),
+                writer = cv2.VideoWriter(cv2_path(self.save_dir / f"{stem}.mp4"),
                                          cv2.VideoWriter_fourcc(*codec),
                                          frame.fps or 25.0,  # keep the source's timing
                                          (w, h))

{easydetect-0.7.2 → easydetect-0.7.4}/easydetect/results.py

@@ -20,6 +20,8 @@ from typing import Any
 
 import numpy as np
 
+from easydetect.utils.imageio import imwrite  # any path, Hangul included
+
 
 class Boxes:
     """Detected boxes for one image.
@@ -223,14 +225,13 @@ class Results:
 
     def save(self, filename: str | Path | None = None) -> Path:
         """Write the annotated image; returns the path written."""
-        import cv2
 
         if filename is None:
             stem = Path(self.path).stem or "image"
             filename = Path(f"{stem}.jpg")
         filename = Path(filename)
         filename.parent.mkdir(parents=True, exist_ok=True)
-        cv2.imwrite(str(filename), self.plot())
+        imwrite(str(filename), self.plot())
         return filename
 
     def show(self, title: str | None = None) -> None:

{easydetect-0.7.2 → easydetect-0.7.4}/easydetect/seg_trainer.py

@@ -25,6 +25,8 @@ from pathlib import Path
 
 import numpy as np
 
+from easydetect.utils.imageio import imread  # any path, Hangul included
+
 from .nn.sam_decoder import GRID, IMG_SIZE, LOW_RES, MASK_CHOICES
 
 BOX_JITTER = 0.05  # Gaussian sigma of each edge's shift, as a share of the box's side
@@ -103,13 +105,12 @@ class EmbeddingCache:
     def file(self, path: Path) -> tuple[Path, tuple[int, int]]:
         """``(the .npy file of the picture's embedding, (height, width))``,
         encoding the picture first if it has not been."""
-        import cv2
 
         file = self._key(path)
         meta = file.with_suffix(".json")
         if file.exists() and meta.exists():
             return file, tuple(json.loads(meta.read_text()))
-        img = cv2.imread(str(path))
+        img = imread(str(path))
         if img is None:
             raise FileNotFoundError(path)
         tensor, _ = self.segmenter.preprocess(img)

{easydetect-0.7.2 → easydetect-0.7.4}/easydetect/sources.py

@@ -33,6 +33,8 @@ from typing import Any
 
 import numpy as np
 
+from easydetect.utils.imageio import cv2_path, imread  # any path, Hangul included
+
 IMG_FORMATS = {".jpg", ".jpeg", ".png", ".bmp", ".webp", ".tif", ".tiff", ".dng", ".pfm"}
 VID_FORMATS = {".mp4", ".avi", ".mov", ".mkv", ".mpg", ".mpeg", ".m4v", ".wmv", ".webm", ".gif"}
 _URL_RE = re.compile(r"^(https?|rtsp|rtmp|tcp|udp)://", re.IGNORECASE)
@@ -252,12 +254,12 @@ class SourceLoader:
             elif kind == "url-image":
                 yield Frame(_read_url_image(payload), payload, i, self.total, "image")
             elif kind == "image":
-                img = cv2.imread(str(payload))
+                img = imread(str(payload))
                 if img is None:
                     raise ValueError(f"could not read image: {payload}")
                 yield Frame(img, payload, i, self.total, "image")
             else:  # video file, webcam index, or network stream
-                cap = cv2.VideoCapture(payload if isinstance(payload, int) else str(payload))
+                cap = cv2.VideoCapture(payload if isinstance(payload, int) else cv2_path(payload))
                 if not cap.isOpened():
                     raise ValueError(f"could not open {payload!r}")
                 frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT)) if kind == "video" else 0

{easydetect-0.7.2 → easydetect-0.7.4}/easydetect/trainer.py

@@ -436,6 +436,8 @@ class Trainer:
             # a resumed run started where its first attempt did
             "start": old.get("start") or self.origin,
             "imgsz": self.imgsz,
+            "queries": self.net.decoder.num_queries,
+            "denoising": self.net.decoder.num_denoising,
             "batch": self.batch,
             "epochs": self.epochs,
             "patience": self.patience,
@@ -736,6 +738,8 @@ class Trainer:
                 "scaler": self.scaler.state_dict() if self.amp else None,
                 "variant": net.variant,
                 "num_classes": net.num_classes,
+                "queries": net.decoder.num_queries,
+                "denoising": net.decoder.num_denoising,
                 "names": self.cfg["names"],
                 "epoch": epoch,
                 "best": self.best,

easydetect-0.7.4/easydetect/utils/imageio.py

@@ -0,0 +1,64 @@
+# Apache-2.0
+"""Pictures in and out by any path, Hangul included.
+
+OpenCV's ``imread``/``imwrite`` take the path as bytes in the system code
+page; on Windows a path with characters outside it (a folder called
+``바탕 화면``, a OneDrive in Korean) reads as nothing. Reading the file's
+bytes with Python and decoding them in memory works for every path.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+
+def imread(path, flags: int = cv2.IMREAD_COLOR):
+    """``cv2.imread`` for any path: the picture, or ``None`` when it cannot be read."""
+    try:
+        data = np.fromfile(str(path), dtype=np.uint8)
+    except OSError:
+        return None
+    if data.size == 0:
+        return None
+    return cv2.imdecode(data, flags)
+
+
+def imwrite(path, img, params=None) -> bool:
+    """``cv2.imwrite`` for any path; the format follows the file's extension."""
+    ext = Path(str(path)).suffix or ".jpg"
+    ok, buf = cv2.imencode(ext, img, params or [])
+    if not ok:
+        return False
+    buf.tofile(str(path))
+    return True
+
+
+def cv2_path(path) -> str:
+    """A path OpenCV's video reader and writer can open. On Windows a path
+    outside the code page becomes its short (8.3) form, which is plain ASCII;
+    elsewhere, or when it is ASCII already, the path as it is. A file that
+    does not exist yet (a video about to be written) keeps its name and gets
+    its folder's short form."""
+    text = str(path)
+    import os
+    import sys
+
+    if sys.platform != "win32" or text.isascii():
+        return text
+    import ctypes
+
+    def short(p: str) -> str:
+        size = ctypes.windll.kernel32.GetShortPathNameW(p, None, 0)
+        if not size:
+            return p
+        buf = ctypes.create_unicode_buffer(size)
+        ctypes.windll.kernel32.GetShortPathNameW(p, buf, size)
+        return buf.value
+
+    if os.path.exists(text):
+        return short(text)
+    folder, name = os.path.split(text)
+    return os.path.join(short(folder), name)

{easydetect-0.7.2 → easydetect-0.7.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "easydetect"
-version = "0.7.2"
+version = "0.7.4"
 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.7.2 → easydetect-0.7.4}/tests/test_robustness.py

@@ -236,3 +236,37 @@ def test_matching_all_layers_at_once_gives_the_same_loss():
     apart, _ = crit(out, targets)
     assert calls and calls[0] > 2                    # the last layer, the others, the encoder
     assert torch.allclose(together, apart)
+
+
+def test_pictures_in_a_hangul_folder_read_and_write(tmp_path):
+    """Windows' OpenCV cannot open such a path itself (바탕 화면, a Korean OneDrive)."""
+    import numpy as np
+
+    from easydetect.utils.imageio import cv2_path, imread, imwrite
+
+    folder = tmp_path / "바탕 화면" / "사진"
+    folder.mkdir(parents=True)
+    img = np.full((20, 30, 3), 120, np.uint8)
+    assert imwrite(folder / "고양이.png", img)
+    back = imread(folder / "고양이.png")
+    assert back is not None and back.shape == img.shape and (back == img).all()
+    assert imread(folder / "없음.jpg") is None
+    assert imread(folder / "고양이.png").dtype == np.uint8
+    assert cv2_path(folder / "a.mp4").endswith("a.mp4")
+
+
+@needs_torch
+def test_a_dataset_in_a_hangul_folder_trains(dataset, tmp_path):
+    import shutil
+
+    import yaml
+
+    from easydetect.data.dataset import DetDataset
+
+    root = tmp_path / "바탕 화면" / "데이터"
+    shutil.copytree(dataset.parent, root)
+    cfg = yaml.safe_load(dataset.read_text())
+    (root / "data.yaml").write_text(yaml.safe_dump(dict(cfg, path=str(root))), encoding="utf-8")
+    ds = DetDataset(root / "data.yaml", "train", 64, augment=True)
+    img, labels = ds[0]
+    assert img.shape[-2:] == (64, 64)

{easydetect-0.7.2 → easydetect-0.7.4}/tests/test_sources_threads.py

@@ -114,9 +114,11 @@ def pictures(tmp_path):
 
 
 def test_pictures_are_read_ahead_of_the_model(pictures, monkeypatch):
+    from easydetect import sources
+
     read = []
-    real = cv2.imread
-    monkeypatch.setattr(cv2, "imread", lambda p, *a: read.append(p) or real(p, *a))
+    real = sources.imread
+    monkeypatch.setattr(sources, "imread", lambda p, *a: read.append(p) or real(p, *a))
     frames = iter(SourceLoader(pictures))
     first = next(frames)
     deadline = time.time() + 3

{easydetect-0.7.2 → easydetect-0.7.4}/tests/test_train_export.py

@@ -477,3 +477,20 @@ def test_multiscale_mosaic_and_mixup_train_and_are_recorded(dataset, tmp_path, m
     assert any("mixup" in line for line in setup["augment"])
     assert any("random size, 32–64" in line for line in setup["augment"])
     assert (32, 32) in sizes  # the batches went through at the drawn size
+
+
+def test_fewer_queries_train_and_stay_with_the_model(dataset, tmp_path, monkeypatch):
+    monkeypatch.setattr("easydetect.nn.hgnetv2.HGNetv2.load_imagenet", lambda self, name, url: None)
+    model = Detector("dfine-n", verbose=False, pretrained=False)
+    best = model.train(data=str(dataset), project=str(tmp_path), epochs=1, imgsz=64, batch=2,
+                       workers=0, device="cpu", val=False, amp=False, queries=40, denoising=10)
+    again = Detector(str(best), verbose=False)
+    again._ensure_net()
+    assert again.net.decoder.num_queries == 40 and again.net.decoder.num_denoising == 10
+    # at 160 px the encoder has more than 300 candidates: only the trim limits it
+    onnx = again.export(format="onnx", imgsz=160, out_dir=tmp_path / "x", verbose=False)
+    import onnxruntime as ort
+
+    out = ort.InferenceSession(str(onnx)).run(None, {"images": np.zeros((1, 3, 160, 160),
+                                                                       np.float32)})
+    assert any(o.shape[1] == 40 for o in out if o.ndim == 3)

{easydetect-0.7.2 → easydetect-0.7.4}/tools/bench_finetune.py

@@ -141,14 +141,17 @@ def train_dfine(data: Path, out: Path, args) -> tuple[Path, float]:
     # in a process of its own, as the yolo command is: a crash in what training
     # leaves behind (loader workers, CUDA) then takes only that process down
     started = time.time()
-    code = ("import sys; from easydetect import Detector; "
+    extra = {k: v for k, v in (("queries", args.queries), ("denoising", args.denoising),
+                               ("freeze", args.freeze)) if v is not None}
+    code = ("import json, sys; from easydetect import Detector; "
             "print('BEST', Detector(sys.argv[1], verbose=False).train(data=sys.argv[2], "
             "epochs=int(sys.argv[3]), imgsz=int(sys.argv[4]), batch=int(sys.argv[5]), "
             "patience=int(sys.argv[3]), project=sys.argv[6], name=sys.argv[1], "
-            "workers=int(sys.argv[7])))")
+            "workers=int(sys.argv[7]), **json.loads(sys.argv[8])))")
     best = None
     with subprocess.Popen([sys.executable, "-c", code, args.dfine, str(data), str(args.epochs),
-                           str(args.imgsz), str(args.batch), str(out), str(args.workers)],
+                           str(args.imgsz), str(args.batch), str(out), str(args.workers),
+                           json.dumps(extra)],
                           env=UNBUFFERED, stdout=subprocess.PIPE, text=True) as proc:
         for line in proc.stdout:                    # passed on as it comes
             print(line, end="", flush=True)
@@ -276,6 +279,9 @@ def main():
     parser.add_argument("--yolo", default="yolo26s.pt")
     parser.add_argument("--dfine", default="dfine-s")
     parser.add_argument("--device", default="CPU", help="OpenVINO device for scoring")
+    parser.add_argument("--queries", type=int, help="D-FINE decoder queries (of 300)")
+    parser.add_argument("--denoising", type=int, help="D-FINE denoising queries (100)")
+    parser.add_argument("--freeze", help="D-FINE parts not trained (backbone)")
     parser.add_argument("--rescore", action="store_true",
                         help="score finished datasets again (their trained models are reused)")
     args = parser.parse_args()

{easydetect-0.7.2 → easydetect-0.7.4}/tools/profile_train.py

@@ -35,6 +35,9 @@ def main():
     parser.add_argument("--steps", type=int, default=40)
     parser.add_argument("--warmup", type=int, default=10)
     parser.add_argument("--no-amp", action="store_true")
+    parser.add_argument("--freeze", default=None, help="backbone, encoder, …: parts not trained")
+    parser.add_argument("--queries", type=int, help="decoder queries while training (of 300)")
+    parser.add_argument("--denoising", type=int, help="denoising queries while training (100)")
     parser.add_argument("--trace", action="store_true", help="also PyTorch's operator table")
     parser.add_argument("--syncs", action="store_true",
                         help="list the lines of easydetect where a step waits for the GPU")
@@ -44,9 +47,14 @@ def main():
 
     nc = load_data_yaml(args.data)["nc"]
     net = DFINENet(args.model, nc)
+    if args.queries:
+        net.trim(queries=args.queries)
+    if args.denoising is not None:
+        net.decoder.num_denoising = args.denoising
     with tempfile.TemporaryDirectory() as tmp:
         tr = Trainer(net, args.data, epochs=1, imgsz=args.imgsz, batch=args.batch,
-                     workers=args.workers, project=tmp, amp=not args.no_amp)
+                     workers=args.workers, project=tmp, amp=not args.no_amp,
+                     freeze=args.freeze)
         ds = DetDataset(args.data, "train", args.imgsz, augment=True)
         dl = tr._loader(ds)
         net = tr.net.to(tr.device).train()