easyannotate 0.4.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. data_factory/__init__.py +82 -0
  2. data_factory/__main__.py +6 -0
  3. data_factory/annotate/__init__.py +15 -0
  4. data_factory/annotate/attach.py +398 -0
  5. data_factory/annotate/demo.py +161 -0
  6. data_factory/annotate/images.py +443 -0
  7. data_factory/annotate/labels.py +399 -0
  8. data_factory/annotate/loop.py +359 -0
  9. data_factory/annotate/projects.py +207 -0
  10. data_factory/annotate/review.py +471 -0
  11. data_factory/annotate/schema.sql +171 -0
  12. data_factory/annotate/shapes.py +488 -0
  13. data_factory/annotate/store.py +292 -0
  14. data_factory/annotate/tools/__init__.py +39 -0
  15. data_factory/annotate/tools/fake.py +170 -0
  16. data_factory/annotate/tools/install.py +254 -0
  17. data_factory/annotate/tools/local.py +389 -0
  18. data_factory/annotate/tools/postprocess.py +175 -0
  19. data_factory/annotate/tools/protocol.py +238 -0
  20. data_factory/annotate/tools/registry.py +196 -0
  21. data_factory/annotate/tools/results.py +83 -0
  22. data_factory/annotate/tools/serve.py +106 -0
  23. data_factory/cli/__init__.py +21 -0
  24. data_factory/cli/main.py +837 -0
  25. data_factory/cli/menu.py +173 -0
  26. data_factory/cli/render.py +158 -0
  27. data_factory/core/__init__.py +11 -0
  28. data_factory/core/annotations/__init__.py +5 -0
  29. data_factory/core/annotations/coco.py +394 -0
  30. data_factory/core/annotations/csvfmt.py +174 -0
  31. data_factory/core/annotations/dota.py +98 -0
  32. data_factory/core/annotations/formats.py +626 -0
  33. data_factory/core/annotations/labelme.py +153 -0
  34. data_factory/core/annotations/model.py +334 -0
  35. data_factory/core/annotations/voc.py +231 -0
  36. data_factory/core/annotations/yolo.py +283 -0
  37. data_factory/core/bktree.py +89 -0
  38. data_factory/core/fs.py +245 -0
  39. data_factory/core/imaging.py +626 -0
  40. data_factory/core/ops/__init__.py +44 -0
  41. data_factory/core/ops/analyze.py +383 -0
  42. data_factory/core/ops/annotate_export.py +326 -0
  43. data_factory/core/ops/audit.py +274 -0
  44. data_factory/core/ops/augment.py +454 -0
  45. data_factory/core/ops/collect.py +241 -0
  46. data_factory/core/ops/combine.py +582 -0
  47. data_factory/core/ops/convert.py +212 -0
  48. data_factory/core/ops/dataset.py +246 -0
  49. data_factory/core/ops/dedup.py +235 -0
  50. data_factory/core/ops/export.py +168 -0
  51. data_factory/core/ops/image.py +407 -0
  52. data_factory/core/ops/labels.py +215 -0
  53. data_factory/core/ops/pairing.py +133 -0
  54. data_factory/core/ops/rename.py +154 -0
  55. data_factory/core/ops/report.py +323 -0
  56. data_factory/core/ops/visualize.py +164 -0
  57. data_factory/core/pairs.py +144 -0
  58. data_factory/core/parallel.py +191 -0
  59. data_factory/core/provenance.py +136 -0
  60. data_factory/core/registry.py +339 -0
  61. data_factory/core/stats.py +403 -0
  62. data_factory/core/types.py +148 -0
  63. data_factory/core/writer.py +194 -0
  64. data_factory/desktop.py +207 -0
  65. data_factory/hardware.py +243 -0
  66. data_factory/pipeline.py +192 -0
  67. data_factory/py.typed +0 -0
  68. data_factory/service/__init__.py +26 -0
  69. data_factory/service/app.py +483 -0
  70. data_factory/service/binding.py +174 -0
  71. data_factory/service/deps.py +133 -0
  72. data_factory/service/jobs.py +177 -0
  73. data_factory/service/limits.py +71 -0
  74. data_factory/service/routers/__init__.py +11 -0
  75. data_factory/service/routers/annotate.py +582 -0
  76. data_factory/service/routers/local.py +464 -0
  77. data_factory/service/routers/media.py +154 -0
  78. data_factory/service/routers/predictions.py +116 -0
  79. data_factory/service/routers/promote.py +182 -0
  80. data_factory/service/routers/tools.py +308 -0
  81. data_factory/service/static/annotate/api.js +246 -0
  82. data_factory/service/static/annotate/app.js +1696 -0
  83. data_factory/service/static/annotate/assist.js +106 -0
  84. data_factory/service/static/annotate/filmstrip.js +286 -0
  85. data_factory/service/static/annotate/hit.js +146 -0
  86. data_factory/service/static/annotate/labels.js +197 -0
  87. data_factory/service/static/annotate/render.js +286 -0
  88. data_factory/service/static/annotate/scene.js +277 -0
  89. data_factory/service/static/annotate/shapelist.js +72 -0
  90. data_factory/service/static/annotate/tools/box.js +96 -0
  91. data_factory/service/static/annotate/tools/line.js +96 -0
  92. data_factory/service/static/annotate/tools/obb.js +88 -0
  93. data_factory/service/static/annotate/tools/point.js +49 -0
  94. data_factory/service/static/annotate/tools/polygon.js +110 -0
  95. data_factory/service/static/annotate/tools/select.js +227 -0
  96. data_factory/service/static/annotate/undo.js +176 -0
  97. data_factory/service/static/annotate/viewport.js +156 -0
  98. data_factory/service/static/annotate.html +390 -0
  99. data_factory/service/static/index.html +632 -0
  100. data_factory/service/workspace.py +244 -0
  101. easyannotate/__init__.py +64 -0
  102. easyannotate/__main__.py +5 -0
  103. easyannotate/project.py +181 -0
  104. easyannotate/py.typed +0 -0
  105. easyannotate-0.4.0.dist-info/METADATA +767 -0
  106. easyannotate-0.4.0.dist-info/RECORD +109 -0
  107. easyannotate-0.4.0.dist-info/WHEEL +4 -0
  108. easyannotate-0.4.0.dist-info/entry_points.txt +4 -0
  109. easyannotate-0.4.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,626 @@
1
+ """Image I/O and annotation-aware geometry.
2
+
3
+ Resizing, tiling and augmentation all face the same problem: move the pixels,
4
+ and the boxes and polygons have to move with them or the dataset is quietly
5
+ ruined. Solving that once, here, is why those three operations are small.
6
+
7
+ A :class:`Transform` knows two things -- how to redraw the image, and where a
8
+ single point lands afterwards. :func:`transform_annotation` does the rest: it
9
+ maps every polygon vertex, rebuilds each box from its four transformed corners
10
+ (so rotation stays correct rather than degenerating into a box of a box), clips
11
+ to the new frame, and drops objects that fell out of view.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import math
17
+ from collections.abc import Iterable
18
+ from dataclasses import dataclass
19
+ from pathlib import Path
20
+ from typing import Any
21
+
22
+ import cv2
23
+ import numpy as np
24
+
25
+ from .annotations.model import Annotation, Point, Shape
26
+
27
+ #: Pixels below this in either dimension make an object worthless for training.
28
+ MIN_OBJECT_PIXELS = 2
29
+
30
+ #: EXIF tag 0x0112. 1 is upright; 5-8 additionally transpose width and height.
31
+ EXIF_ORIENTATION_TAG = 0x0112
32
+
33
+
34
+ # --------------------------------------------------------------------- I/O
35
+
36
+ def stored_size(path: Path) -> tuple[int, int]:
37
+ """``(width, height)`` exactly as written in the file header.
38
+
39
+ Ignores EXIF orientation, so for a sideways phone photo this is the
40
+ *unrotated* frame. Rarely what you want -- see :func:`image_size`.
41
+ """
42
+ from PIL import Image # local import: keeps module import cheap
43
+
44
+ with Image.open(path) as im:
45
+ return im.size
46
+
47
+
48
+ def image_size(path: Path) -> tuple[int, int]:
49
+ """``(width, height)`` as everything else in this package sees the image.
50
+
51
+ Read from the header, so auditing 7,000 images costs no JPEG decodes.
52
+
53
+ **This honours EXIF orientation, and has to.** A phone photo is commonly
54
+ stored sideways with a tag saying "rotate me". OpenCV's ``imdecode`` --
55
+ which :func:`load` uses, and therefore every operation that touches pixels
56
+ -- applies that tag. Browsers apply it too. ``PIL.Image.size`` does not.
57
+
58
+ Reporting the stored size while the pixels arrive rotated is a silent
59
+ mismatch: the ``<size>`` written into a VOC file would be transposed
60
+ relative to the image the annotator drew on and the trainer loads, with
61
+ nothing anywhere reporting an error.
62
+
63
+ Verified on the current Project_Door data: 3,000 of 3,000 images are
64
+ orientation 1, so nothing is corrupt today. It arrives with the first phone
65
+ photo a public tool receives.
66
+ """
67
+ from PIL import Image
68
+
69
+ with Image.open(path) as im:
70
+ width, height = im.size
71
+ orientation = int(im.getexif().get(EXIF_ORIENTATION_TAG, 1) or 1)
72
+ # 5-8 transpose the axes; 2, 3 and 4 are mirrors and a half turn, which
73
+ # move pixels but keep the frame.
74
+ return (height, width) if orientation in (5, 6, 7, 8) else (width, height)
75
+
76
+
77
+ def ingest(path: Path, destination: Path | None = None, *, quality: int = 95) -> tuple[int, int]:
78
+ """Settle an image into one coordinate space, once, on the way in.
79
+
80
+ Returns the upright ``(width, height)``.
81
+
82
+ An image whose stored frame already matches its displayed frame is left
83
+ **byte for byte alone** -- re-encoding a JPEG that needs nothing done costs
84
+ quality every time and buys nothing. Anything carrying a transposing tag is
85
+ decoded (which applies the rotation) and re-encoded upright, so the tag is
86
+ gone and stored size, displayed size and pixel array can never disagree
87
+ again.
88
+
89
+ Doing this at ingest is what lets the editor, the store and the exporters
90
+ stop thinking about orientation entirely.
91
+ """
92
+ orientation = exif_orientation(path)
93
+ if orientation in (0, 1):
94
+ width, height = stored_size(path)
95
+ if destination is not None and destination != path:
96
+ destination.parent.mkdir(parents=True, exist_ok=True)
97
+ destination.write_bytes(path.read_bytes())
98
+ return width, height
99
+
100
+ # load() decodes through OpenCV, which already applies the orientation --
101
+ # so the array is upright here and must NOT be rotated a second time.
102
+ array = load(path)
103
+ save(array, destination or path, quality=quality)
104
+ return array.shape[1], array.shape[0]
105
+
106
+
107
+ def load(path: Path) -> np.ndarray:
108
+ """Decode to a BGR array, tolerating non-ASCII paths on Windows.
109
+
110
+ ``cv2.imread`` silently returns None for paths it cannot encode, which on a
111
+ Windows box with accented folder names looks exactly like a corrupt file.
112
+ """
113
+ data = np.fromfile(str(path), dtype=np.uint8)
114
+ if data.size == 0:
115
+ raise OSError(f"empty file: {path}")
116
+ image = cv2.imdecode(data, cv2.IMREAD_COLOR)
117
+ if image is None:
118
+ raise OSError(f"not a decodable image: {path}")
119
+ return image
120
+
121
+
122
+ _REDUCED = {
123
+ 1: cv2.IMREAD_COLOR,
124
+ 2: cv2.IMREAD_REDUCED_COLOR_2,
125
+ 4: cv2.IMREAD_REDUCED_COLOR_4,
126
+ 8: cv2.IMREAD_REDUCED_COLOR_8,
127
+ }
128
+
129
+
130
+ def load_reduced(path: Path, factor: int) -> np.ndarray:
131
+ """Decode at 1/``factor`` scale (1, 2, 4 or 8), orientation applied.
132
+
133
+ For JPEG the reduction happens inside the decoder, so a 50 MP photo
134
+ becomes a thumbnail without ever existing as a 150 MB array -- faster,
135
+ and the difference between a preview and an out-of-memory server.
136
+ """
137
+ data = np.fromfile(str(path), dtype=np.uint8)
138
+ if data.size == 0:
139
+ raise OSError(f"empty file: {path}")
140
+ image = cv2.imdecode(data, _REDUCED.get(int(factor), cv2.IMREAD_COLOR))
141
+ if image is None:
142
+ raise OSError(f"not a decodable image: {path}")
143
+ return image
144
+
145
+
146
+ def reduction_for(width: int, height: int, edge: int) -> int:
147
+ """The largest decode reduction that still leaves ``edge`` pixels."""
148
+ longest = max(int(width), int(height))
149
+ for factor in (8, 4, 2):
150
+ if longest // factor >= edge:
151
+ return factor
152
+ return 1
153
+
154
+
155
+ def encode(image: np.ndarray, suffix: str, *, quality: int = 95) -> bytes:
156
+ """Compress to bytes without touching the disk.
157
+
158
+ Split out from :func:`save` so the expensive half can run on a worker
159
+ thread while the write stays on the calling thread -- encoding a JPEG is
160
+ most of the cost of saving one.
161
+ """
162
+ suffix = (suffix or ".jpg").lower()
163
+ params: list[int] = []
164
+ if suffix in (".jpg", ".jpeg"):
165
+ params = [cv2.IMWRITE_JPEG_QUALITY, int(quality)]
166
+ elif suffix == ".webp":
167
+ params = [cv2.IMWRITE_WEBP_QUALITY, int(quality)]
168
+ elif suffix == ".png":
169
+ # PNG is lossless; map the 0-100 dial onto compression effort instead.
170
+ params = [cv2.IMWRITE_PNG_COMPRESSION, max(0, min(9, 9 - int(quality) // 12))]
171
+ ok, buffer = cv2.imencode(suffix, image, params)
172
+ if not ok:
173
+ raise OSError(f"could not encode a {suffix} image")
174
+ return buffer.tobytes()
175
+
176
+
177
+ def save(image: np.ndarray, path: Path, *, quality: int = 95) -> Path:
178
+ """Encode and write, via a buffer so Unicode paths survive on Windows."""
179
+ return write_bytes(encode(image, path.suffix, quality=quality), path)
180
+
181
+
182
+ def write_bytes(data: bytes, path: Path) -> Path:
183
+ """Write already-encoded image bytes."""
184
+ path.parent.mkdir(parents=True, exist_ok=True)
185
+ path.write_bytes(data)
186
+ return path
187
+
188
+
189
+ def exif_orientation(path: Path) -> int:
190
+ """The EXIF orientation tag (1 = upright), or 1 when absent."""
191
+ from PIL import Image
192
+
193
+ try:
194
+ with Image.open(path) as im:
195
+ exif = im.getexif()
196
+ return int(exif.get(EXIF_ORIENTATION_TAG, 1) or 1)
197
+ except Exception:
198
+ return 1
199
+
200
+
201
+ # -------------------------------------------------------------- transforms
202
+
203
+ @dataclass(slots=True)
204
+ class Transform:
205
+ """Base transform: identity, and the interface the others fill in.
206
+
207
+ ``out_size`` is the frame the result lives in, which is what annotations
208
+ are clipped against.
209
+ """
210
+
211
+ out_size: tuple[int, int]
212
+
213
+ def image(self, im: np.ndarray) -> np.ndarray:
214
+ return im
215
+
216
+ def point(self, x: float, y: float) -> tuple[float, float]:
217
+ return x, y
218
+
219
+ def describe(self) -> str:
220
+ return type(self).__name__.lower()
221
+
222
+
223
+ @dataclass(slots=True)
224
+ class Identity(Transform):
225
+ """Pixels change, geometry does not -- every photometric augmentation."""
226
+
227
+
228
+ @dataclass(slots=True)
229
+ class Resize(Transform):
230
+ """Independent x/y scaling. Distorts aspect ratio; cheap and predictable."""
231
+
232
+ scale_x: float = 1.0
233
+ scale_y: float = 1.0
234
+
235
+ def image(self, im: np.ndarray) -> np.ndarray:
236
+ w, h = self.out_size
237
+ # Shrinking and growing want different filters; INTER_AREA avoids the
238
+ # aliasing that makes downscaled thin objects vanish.
239
+ interp = cv2.INTER_AREA if (w < im.shape[1] or h < im.shape[0]) else cv2.INTER_LINEAR
240
+ return cv2.resize(im, (w, h), interpolation=interp)
241
+
242
+ def point(self, x: float, y: float) -> tuple[float, float]:
243
+ return x * self.scale_x, y * self.scale_y
244
+
245
+
246
+ @dataclass(slots=True)
247
+ class Letterbox(Transform):
248
+ """Uniform scale plus padding -- aspect ratio preserved, nothing cropped."""
249
+
250
+ scale: float = 1.0
251
+ pad_x: int = 0
252
+ pad_y: int = 0
253
+ colour: tuple[int, int, int] = (114, 114, 114)
254
+
255
+ def image(self, im: np.ndarray) -> np.ndarray:
256
+ w, h = self.out_size
257
+ inner_w = max(1, int(round(im.shape[1] * self.scale)))
258
+ inner_h = max(1, int(round(im.shape[0] * self.scale)))
259
+ interp = cv2.INTER_AREA if self.scale < 1 else cv2.INTER_LINEAR
260
+ resized = cv2.resize(im, (inner_w, inner_h), interpolation=interp)
261
+ canvas = np.full((h, w, 3), self.colour, dtype=np.uint8)
262
+ canvas[self.pad_y : self.pad_y + inner_h, self.pad_x : self.pad_x + inner_w] = resized
263
+ return canvas
264
+
265
+ def point(self, x: float, y: float) -> tuple[float, float]:
266
+ return x * self.scale + self.pad_x, y * self.scale + self.pad_y
267
+
268
+
269
+ @dataclass(slots=True)
270
+ class Crop(Transform):
271
+ """Take a rectangular window. Backs both tiling and random-crop zoom."""
272
+
273
+ left: int = 0
274
+ top: int = 0
275
+
276
+ def image(self, im: np.ndarray) -> np.ndarray:
277
+ w, h = self.out_size
278
+ window = im[self.top : self.top + h, self.left : self.left + w]
279
+ if window.shape[0] != h or window.shape[1] != w:
280
+ # Windows running off the edge are padded rather than shrunk, so
281
+ # every tile in a grid comes out the same size.
282
+ padded = np.zeros((h, w, 3), dtype=im.dtype)
283
+ padded[: window.shape[0], : window.shape[1]] = window
284
+ return padded
285
+ return window
286
+
287
+ def point(self, x: float, y: float) -> tuple[float, float]:
288
+ return x - self.left, y - self.top
289
+
290
+
291
+ @dataclass(slots=True)
292
+ class FlipH(Transform):
293
+ def image(self, im: np.ndarray) -> np.ndarray:
294
+ return cv2.flip(im, 1)
295
+
296
+ def point(self, x: float, y: float) -> tuple[float, float]:
297
+ return self.out_size[0] - 1 - x, y
298
+
299
+
300
+ @dataclass(slots=True)
301
+ class FlipV(Transform):
302
+ def image(self, im: np.ndarray) -> np.ndarray:
303
+ return cv2.flip(im, 0)
304
+
305
+ def point(self, x: float, y: float) -> tuple[float, float]:
306
+ return x, self.out_size[1] - 1 - y
307
+
308
+
309
+ @dataclass(slots=True)
310
+ class Rot90(Transform):
311
+ """Lossless 90-degree rotation. ``turns`` is counter-clockwise quarters."""
312
+
313
+ turns: int = 1
314
+ src_size: tuple[int, int] = (0, 0)
315
+
316
+ def image(self, im: np.ndarray) -> np.ndarray:
317
+ return np.ascontiguousarray(np.rot90(im, k=self.turns % 4))
318
+
319
+ def point(self, x: float, y: float) -> tuple[float, float]:
320
+ w, h = self.src_size
321
+ turns = self.turns % 4
322
+ for _ in range(turns):
323
+ x, y = y, w - 1 - x
324
+ w, h = h, w
325
+ return x, y
326
+
327
+
328
+ @dataclass(slots=True)
329
+ class Rotate(Transform):
330
+ """Arbitrary rotation about the centre, expanding the frame to fit."""
331
+
332
+ degrees: float = 0.0
333
+ matrix: Any = None
334
+
335
+ def image(self, im: np.ndarray) -> np.ndarray:
336
+ w, h = self.out_size
337
+ return cv2.warpAffine(
338
+ im, self.matrix, (w, h), flags=cv2.INTER_LINEAR, borderValue=(114, 114, 114)
339
+ )
340
+
341
+ def point(self, x: float, y: float) -> tuple[float, float]:
342
+ m = self.matrix
343
+ return (
344
+ m[0, 0] * x + m[0, 1] * y + m[0, 2],
345
+ m[1, 0] * x + m[1, 1] * y + m[1, 2],
346
+ )
347
+
348
+
349
+ def make_rotate(width: int, height: int, degrees: float) -> Rotate:
350
+ """Build a rotation that keeps the whole image, growing the canvas."""
351
+ centre = (width / 2.0, height / 2.0)
352
+ matrix = cv2.getRotationMatrix2D(centre, degrees, 1.0)
353
+ cos, sin = abs(matrix[0, 0]), abs(matrix[0, 1])
354
+ new_w = int(round(height * sin + width * cos))
355
+ new_h = int(round(height * cos + width * sin))
356
+ matrix[0, 2] += new_w / 2.0 - centre[0]
357
+ matrix[1, 2] += new_h / 2.0 - centre[1]
358
+ return Rotate(out_size=(new_w, new_h), degrees=degrees, matrix=matrix)
359
+
360
+
361
+ def make_resize(
362
+ width: int, height: int, target_w: int, target_h: int, mode: str = "letterbox"
363
+ ) -> Transform:
364
+ """Pick the transform for a target size under the requested fit mode.
365
+
366
+ ``stretch`` fills the frame and distorts, ``letterbox`` pads, ``crop``
367
+ fills by scaling up and cutting the overflow (centre-anchored), and ``fit``
368
+ scales the long edge only, leaving the other free.
369
+ """
370
+ if mode == "stretch":
371
+ return Resize(
372
+ out_size=(target_w, target_h),
373
+ scale_x=target_w / width,
374
+ scale_y=target_h / height,
375
+ )
376
+ if mode == "fit":
377
+ scale = min(target_w / width, target_h / height)
378
+ out_w, out_h = max(1, round(width * scale)), max(1, round(height * scale))
379
+ return Resize(out_size=(out_w, out_h), scale_x=out_w / width, scale_y=out_h / height)
380
+ if mode == "crop":
381
+ scale = max(target_w / width, target_h / height)
382
+ scaled_w, scaled_h = max(1, round(width * scale)), max(1, round(height * scale))
383
+ left = (scaled_w - target_w) // 2
384
+ top = (scaled_h - target_h) // 2
385
+ return _Chain(
386
+ out_size=(target_w, target_h),
387
+ steps=(
388
+ Resize(out_size=(scaled_w, scaled_h), scale_x=scale, scale_y=scale),
389
+ Crop(out_size=(target_w, target_h), left=left, top=top),
390
+ ),
391
+ )
392
+ scale = min(target_w / width, target_h / height)
393
+ inner_w, inner_h = max(1, round(width * scale)), max(1, round(height * scale))
394
+ return Letterbox(
395
+ out_size=(target_w, target_h),
396
+ scale=scale,
397
+ pad_x=(target_w - inner_w) // 2,
398
+ pad_y=(target_h - inner_h) // 2,
399
+ )
400
+
401
+
402
+ @dataclass(slots=True)
403
+ class _Chain(Transform):
404
+ """Two or more transforms applied in order, as one."""
405
+
406
+ steps: tuple[Transform, ...] = ()
407
+
408
+ def image(self, im: np.ndarray) -> np.ndarray:
409
+ for step in self.steps:
410
+ im = step.image(im)
411
+ return im
412
+
413
+ def point(self, x: float, y: float) -> tuple[float, float]:
414
+ for step in self.steps:
415
+ x, y = step.point(x, y)
416
+ return x, y
417
+
418
+
419
+ def chain(*steps: Transform) -> Transform:
420
+ return _Chain(out_size=steps[-1].out_size, steps=steps)
421
+
422
+
423
+ # ------------------------------------------------- annotation-aware mapping
424
+
425
+ def transform_annotation(
426
+ annotation: Annotation,
427
+ transform: Transform,
428
+ *,
429
+ min_visibility: float = 0.25,
430
+ filename: str | None = None,
431
+ ) -> Annotation:
432
+ """Move every shape through ``transform`` and clip it to the new frame.
433
+
434
+ ``min_visibility`` is the fraction of an object's original area that must
435
+ survive clipping for it to be kept. Without it, tiling produces slivers --
436
+ two pixels of a door at the edge of a tile, labelled "door" -- which teach
437
+ a model that almost nothing is a door.
438
+ """
439
+ out_w, out_h = transform.out_size
440
+ kept: list[Shape] = []
441
+
442
+ for shape in annotation.shapes:
443
+ moved = _transform_shape(shape, transform)
444
+ if moved is None:
445
+ continue
446
+ before = max(1.0, float(shape.bbox_area))
447
+ clipped = moved.clamped(out_w, out_h)
448
+ if clipped.width < MIN_OBJECT_PIXELS or clipped.height < MIN_OBJECT_PIXELS:
449
+ continue
450
+ # Compare against the *transformed* area, so a legitimate downscale is
451
+ # not mistaken for the object having been cropped away.
452
+ expected = max(1.0, float(moved.bbox_area))
453
+ if expected / before > 0.0 and clipped.bbox_area / expected < min_visibility:
454
+ continue
455
+ kept.append(clipped)
456
+
457
+ return Annotation(
458
+ filename=filename or annotation.filename,
459
+ width=out_w,
460
+ height=out_h,
461
+ depth=annotation.depth,
462
+ shapes=kept,
463
+ folder=annotation.folder,
464
+ source_path=annotation.source_path,
465
+ )
466
+
467
+
468
+ def _transform_shape(shape: Shape, transform: Transform) -> Shape | None:
469
+ polygon: list[Point] | None = None
470
+ if shape.has_polygon:
471
+ assert shape.polygon is not None
472
+ polygon = [_ipoint(transform.point(x, y)) for x, y in shape.polygon]
473
+
474
+ # Rebuild the box from all four transformed corners. Transforming only the
475
+ # two opposite corners is right for scaling and wrong for rotation.
476
+ xmin, ymin, xmax, ymax = shape.bbox
477
+ corners = [
478
+ transform.point(xmin, ymin),
479
+ transform.point(xmax, ymin),
480
+ transform.point(xmax, ymax),
481
+ transform.point(xmin, ymax),
482
+ ]
483
+ xs = [c[0] for c in corners]
484
+ ys = [c[1] for c in corners]
485
+ box = (
486
+ int(math.floor(min(xs))),
487
+ int(math.floor(min(ys))),
488
+ int(math.ceil(max(xs))),
489
+ int(math.ceil(max(ys))),
490
+ )
491
+ return Shape(
492
+ label=shape.label,
493
+ bbox=box,
494
+ polygon=polygon,
495
+ pose=shape.pose,
496
+ truncated=shape.truncated,
497
+ difficult=shape.difficult,
498
+ occluded=shape.occluded,
499
+ )
500
+
501
+
502
+ def _ipoint(pair: tuple[float, float]) -> Point:
503
+ return int(round(pair[0])), int(round(pair[1]))
504
+
505
+
506
+ # ------------------------------------------------------------ photometric
507
+
508
+ def adjust_brightness(im: np.ndarray, factor: float) -> np.ndarray:
509
+ return cv2.convertScaleAbs(im, alpha=1.0, beta=(factor - 1.0) * 255.0 * 0.5)
510
+
511
+
512
+ def adjust_contrast(im: np.ndarray, factor: float) -> np.ndarray:
513
+ mean = float(im.mean())
514
+ return np.clip((im.astype(np.float32) - mean) * factor + mean, 0, 255).astype(np.uint8)
515
+
516
+
517
+ def adjust_saturation(im: np.ndarray, factor: float) -> np.ndarray:
518
+ hsv = cv2.cvtColor(im, cv2.COLOR_BGR2HSV).astype(np.float32)
519
+ hsv[..., 1] = np.clip(hsv[..., 1] * factor, 0, 255)
520
+ return cv2.cvtColor(hsv.astype(np.uint8), cv2.COLOR_HSV2BGR)
521
+
522
+
523
+ def adjust_hue(im: np.ndarray, degrees: float) -> np.ndarray:
524
+ hsv = cv2.cvtColor(im, cv2.COLOR_BGR2HSV).astype(np.int16)
525
+ # OpenCV packs hue into 0-179, so a degree is half a unit.
526
+ hsv[..., 0] = (hsv[..., 0] + int(degrees / 2.0)) % 180
527
+ return cv2.cvtColor(hsv.astype(np.uint8), cv2.COLOR_HSV2BGR)
528
+
529
+
530
+ def blur(im: np.ndarray, radius: float) -> np.ndarray:
531
+ k = max(1, int(radius) * 2 + 1)
532
+ return cv2.GaussianBlur(im, (k, k), 0)
533
+
534
+
535
+ def add_noise(im: np.ndarray, amount: float, rng: np.random.Generator) -> np.ndarray:
536
+ noise = rng.normal(0.0, amount * 255.0, im.shape)
537
+ return np.clip(im.astype(np.float32) + noise, 0, 255).astype(np.uint8)
538
+
539
+
540
+ def to_grayscale(im: np.ndarray) -> np.ndarray:
541
+ """Grey pixels, still three channels -- models expect a 3-channel input."""
542
+ return cv2.cvtColor(cv2.cvtColor(im, cv2.COLOR_BGR2GRAY), cv2.COLOR_GRAY2BGR)
543
+
544
+
545
+ def cutout(
546
+ im: np.ndarray, count: int, fraction: float, rng: np.random.Generator
547
+ ) -> np.ndarray:
548
+ """Erase random rectangles. Teaches a model not to rely on one landmark."""
549
+ out = im.copy()
550
+ h, w = out.shape[:2]
551
+ box_w = max(1, int(w * fraction))
552
+ box_h = max(1, int(h * fraction))
553
+ for _ in range(count):
554
+ x = int(rng.integers(0, max(1, w - box_w)))
555
+ y = int(rng.integers(0, max(1, h - box_h)))
556
+ out[y : y + box_h, x : x + box_w] = int(rng.integers(0, 256))
557
+ return out
558
+
559
+
560
+ def apply_exif(im: np.ndarray, orientation: int) -> np.ndarray:
561
+ """Bake an EXIF orientation into the pixels."""
562
+ if orientation == 2:
563
+ return cv2.flip(im, 1)
564
+ if orientation == 3:
565
+ return cv2.rotate(im, cv2.ROTATE_180)
566
+ if orientation == 4:
567
+ return cv2.flip(im, 0)
568
+ if orientation == 5:
569
+ return cv2.flip(cv2.rotate(im, cv2.ROTATE_90_CLOCKWISE), 1)
570
+ if orientation == 6:
571
+ return cv2.rotate(im, cv2.ROTATE_90_CLOCKWISE)
572
+ if orientation == 7:
573
+ return cv2.flip(cv2.rotate(im, cv2.ROTATE_90_COUNTERCLOCKWISE), 1)
574
+ if orientation == 8:
575
+ return cv2.rotate(im, cv2.ROTATE_90_COUNTERCLOCKWISE)
576
+ return im
577
+
578
+
579
+ def exif_transform(orientation: int, width: int, height: int) -> Transform:
580
+ """The geometry matching :func:`apply_exif`, for moving the annotations."""
581
+ if orientation in (1,):
582
+ return Identity(out_size=(width, height))
583
+ if orientation == 2:
584
+ return FlipH(out_size=(width, height))
585
+ if orientation == 3:
586
+ return Rot90(out_size=(width, height), turns=2, src_size=(width, height))
587
+ if orientation == 4:
588
+ return FlipV(out_size=(width, height))
589
+ if orientation == 6:
590
+ return Rot90(out_size=(height, width), turns=3, src_size=(width, height))
591
+ if orientation == 8:
592
+ return Rot90(out_size=(height, width), turns=1, src_size=(width, height))
593
+ if orientation == 5:
594
+ return chain(
595
+ Rot90(out_size=(height, width), turns=3, src_size=(width, height)),
596
+ FlipH(out_size=(height, width)),
597
+ )
598
+ if orientation == 7:
599
+ return chain(
600
+ Rot90(out_size=(height, width), turns=1, src_size=(width, height)),
601
+ FlipH(out_size=(height, width)),
602
+ )
603
+ return Identity(out_size=(width, height))
604
+
605
+
606
+ def tile_windows(
607
+ width: int, height: int, tile_w: int, tile_h: int, overlap: float
608
+ ) -> Iterable[tuple[int, int, int, int]]:
609
+ """Grid of overlapping windows covering the image.
610
+
611
+ Overlap matters: an object straddling a tile boundary is cut in half by a
612
+ naive grid, and with enough overlap it lands whole in at least one tile.
613
+ """
614
+ step_x = max(1, int(tile_w * (1.0 - overlap)))
615
+ step_y = max(1, int(tile_h * (1.0 - overlap)))
616
+ xs = list(range(0, max(1, width - tile_w + 1), step_x))
617
+ ys = list(range(0, max(1, height - tile_h + 1), step_y))
618
+ # Always include a window flush with the right/bottom edge, or the last
619
+ # strip of a non-divisible image is never seen.
620
+ if xs[-1] + tile_w < width:
621
+ xs.append(max(0, width - tile_w))
622
+ if ys[-1] + tile_h < height:
623
+ ys.append(max(0, height - tile_h))
624
+ for y in ys:
625
+ for x in xs:
626
+ yield x, y, tile_w, tile_h
@@ -0,0 +1,44 @@
1
+ """Importing this package registers every operation.
2
+
3
+ Modules are imported for their decorator side effects. A new operation module
4
+ added here becomes available to the CLI, the menu, the YAML runner, and the web
5
+ schema at once -- no front-end needs editing.
6
+ """
7
+
8
+ from . import (
9
+ analyze,
10
+ annotate_export,
11
+ audit,
12
+ augment,
13
+ collect,
14
+ combine,
15
+ convert,
16
+ dataset,
17
+ dedup,
18
+ export,
19
+ image,
20
+ labels,
21
+ pairing,
22
+ rename,
23
+ report,
24
+ visualize,
25
+ )
26
+
27
+ __all__ = [
28
+ "analyze",
29
+ "annotate_export",
30
+ "audit",
31
+ "augment",
32
+ "collect",
33
+ "combine",
34
+ "convert",
35
+ "dataset",
36
+ "dedup",
37
+ "export",
38
+ "image",
39
+ "labels",
40
+ "pairing",
41
+ "rename",
42
+ "report",
43
+ "visualize",
44
+ ]