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,454 @@
1
+ """Offline augmentation, with the annotations carried along.
2
+
3
+ Augmentation is where a small dataset becomes a usable one, and where a careless
4
+ implementation quietly ruins it: flip the pixels but not the boxes and every
5
+ object is now mirrored onto empty background, which is worse than no
6
+ augmentation at all. Here the geometry goes through the same
7
+ :func:`~data_factory.core.imaging.transform_annotation` every other operation
8
+ uses, so a flip cannot desynchronise.
9
+
10
+ Two decisions worth stating:
11
+
12
+ *Offline, not on-the-fly.* Modern trainers augment per epoch in the data loader,
13
+ which is strictly better for the model. Offline augmentation is still worth
14
+ having, because it is inspectable -- you can open the folder and look at what
15
+ the model will actually be trained on, which is how you catch a hue shift that
16
+ turns every red light green.
17
+
18
+ *Seeded.* The same seed and the same inputs produce the same output files,
19
+ byte for byte. An augmented dataset you cannot reproduce is not a dataset, it
20
+ is an accident.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ import hashlib
26
+ from collections import Counter
27
+ from typing import Any
28
+
29
+ import numpy as np
30
+
31
+ from .. import imaging, parallel
32
+ from ..annotations.model import Annotation
33
+ from ..registry import Param, operation
34
+ from ..types import Context, OpResult
35
+ from ..writer import DatasetWriter
36
+ from .image import OUTPUT_FORMATS, SOURCE_FORMATS, _load
37
+
38
+ AUGMENT_PARAMS = (
39
+ Param("folder", "dir", "Dataset to augment.", required=True, must_exist=True),
40
+ Param("output", "dir", "Where the augmented dataset is written.", required=True),
41
+ Param(
42
+ "multiplier",
43
+ "int",
44
+ "Augmented variants to generate per source image.",
45
+ default=3,
46
+ minimum=1,
47
+ maximum=50,
48
+ ),
49
+ Param("include_original", "bool", "Copy the untouched original in as well.", default=True),
50
+ Param("seed", "int", "Random seed; the same seed reproduces the same output.", default=0),
51
+ # -- geometric
52
+ Param("flip_horizontal", "bool", "Mirror left-right.", default=True),
53
+ Param("flip_vertical", "bool", "Mirror top-bottom.", default=False),
54
+ Param("rotate90", "bool", "Rotate by a random quarter turn.", default=False),
55
+ Param(
56
+ "rotate",
57
+ "float",
58
+ "Maximum rotation in degrees (0 disables).",
59
+ default=0.0,
60
+ minimum=0.0,
61
+ maximum=180.0,
62
+ ),
63
+ Param(
64
+ "crop",
65
+ "float",
66
+ "Maximum random zoom-in, as a fraction of the frame (0 disables).",
67
+ default=0.0,
68
+ minimum=0.0,
69
+ maximum=0.5,
70
+ ),
71
+ # -- photometric
72
+ Param(
73
+ "brightness",
74
+ "float",
75
+ "Maximum brightness shift as a fraction (0 disables).",
76
+ default=0.2,
77
+ minimum=0.0,
78
+ maximum=1.0,
79
+ ),
80
+ Param(
81
+ "contrast",
82
+ "float",
83
+ "Maximum contrast shift as a fraction (0 disables).",
84
+ default=0.2,
85
+ minimum=0.0,
86
+ maximum=1.0,
87
+ ),
88
+ Param(
89
+ "saturation",
90
+ "float",
91
+ "Maximum saturation shift as a fraction (0 disables).",
92
+ default=0.0,
93
+ minimum=0.0,
94
+ maximum=1.0,
95
+ ),
96
+ Param(
97
+ "hue",
98
+ "float",
99
+ "Maximum hue shift in degrees (0 disables).",
100
+ default=0.0,
101
+ minimum=0.0,
102
+ maximum=180.0,
103
+ ),
104
+ Param("blur", "float", "Maximum blur radius in pixels (0 disables).", default=0.0, minimum=0.0),
105
+ Param(
106
+ "noise",
107
+ "float",
108
+ "Maximum gaussian noise as a fraction (0 disables).",
109
+ default=0.0,
110
+ minimum=0.0,
111
+ maximum=0.5,
112
+ ),
113
+ Param(
114
+ "grayscale",
115
+ "float",
116
+ "Probability a variant is converted to greyscale.",
117
+ default=0.0,
118
+ minimum=0.0,
119
+ maximum=1.0,
120
+ ),
121
+ Param("cutout", "int", "Number of random erased boxes (0 disables).", default=0, minimum=0),
122
+ Param(
123
+ "min_visibility",
124
+ "float",
125
+ "Fraction of an object that must remain visible for it to be kept.",
126
+ default=0.3,
127
+ minimum=0.0,
128
+ maximum=1.0,
129
+ ),
130
+ Param(
131
+ "keep_size",
132
+ "bool",
133
+ "Letterbox variants back to their source size, so the output stays uniform.",
134
+ default=True,
135
+ ),
136
+ Param("source_format", "choice", "Input format.", default="auto", choices=SOURCE_FORMATS),
137
+ Param("format", "choice", "Output format.", default="same", choices=OUTPUT_FORMATS),
138
+ Param("quality", "int", "JPEG/WebP quality.", default=95, minimum=1, maximum=100),
139
+ Param("recursive", "bool", "Include sub-folders.", default=True),
140
+ Param(
141
+ "splits",
142
+ "strs",
143
+ "Only augment these splits (blank means all). Usually: train",
144
+ default=None,
145
+ ),
146
+ Param("workers", "int", parallel.WORKERS_HELP, default=0, minimum=0, maximum=32),
147
+ )
148
+
149
+
150
+ @operation(
151
+ "augment.dataset",
152
+ title="Augment dataset",
153
+ category="augment",
154
+ summary="Generate seeded, annotation-aware variants: flips, rotation, colour, blur, noise, cutout.",
155
+ params=AUGMENT_PARAMS,
156
+ destructive=True,
157
+ notes=(
158
+ "Each variant independently rolls each enabled augmentation, so a run\n"
159
+ "with flip, rotate and brightness on gives a genuine mixture rather\n"
160
+ "than every image receiving all three.\n"
161
+ "\n"
162
+ "Augment the training split only. Augmenting validation makes the score\n"
163
+ "measure your augmentation rather than your model, and it usually\n"
164
+ "flatters it. Pass --splits train on a split dataset.\n"
165
+ "\n"
166
+ "Pick augmentations that match how the model will be used, not whatever\n"
167
+ "sounds thorough. Vertical flip on a door dataset teaches the model\n"
168
+ "that upside-down doors are normal; they are not.\n"
169
+ "\n"
170
+ "The same --seed reproduces the run exactly."
171
+ ),
172
+ )
173
+ def augment_dataset(params: dict[str, Any], ctx: Context) -> OpResult:
174
+ result = OpResult(op="augment.dataset", dry_run=ctx.dry_run)
175
+ dataset, target_format = _load(params, ctx, result)
176
+ if dataset is None:
177
+ return result
178
+
179
+ wanted = set(params["splits"] or [])
180
+ plan = _Plan(params)
181
+ if not plan.enabled:
182
+ result.fail(
183
+ "no augmentations are enabled -- everything is at its zero default. "
184
+ "Turn some on, e.g. --brightness 0.25 --rotate 10"
185
+ )
186
+ return result
187
+
188
+ writer = DatasetWriter(
189
+ params["output"], target_format, ctx, classes=dataset.labels, quality=params["quality"]
190
+ )
191
+ multiplier = params["multiplier"]
192
+ applied: Counter[str] = Counter()
193
+ generated = 0
194
+ copied = 0
195
+ dropped = 0
196
+ total = len(dataset.items)
197
+
198
+ quality = params["quality"]
199
+ seed = params["seed"]
200
+
201
+ def build_variants(item):
202
+ """Decode once, generate every variant, hand back encoded bytes.
203
+
204
+ Pure and thread-safe: each variant makes its own generator from a
205
+ stable seed, so nothing here depends on execution order.
206
+ """
207
+ if item.image is None:
208
+ return None
209
+ if wanted and item.split and item.split not in wanted:
210
+ return ("passthrough", [])
211
+ array = imaging.load(item.image)
212
+ produced = []
213
+ for variant in range(multiplier):
214
+ rng = np.random.default_rng(_seed_for(seed, item.stem, variant))
215
+ pixels, annotation, used = plan.apply(array, item.annotation, rng)
216
+ produced.append(
217
+ (annotation, imaging.encode(pixels, item.image.suffix, quality=quality), used)
218
+ )
219
+ return ("augment", produced)
220
+
221
+ def note_failure(item, exc: Exception) -> None:
222
+ result.warnings.append(f"{item.image.name if item.image else item.stem}: {exc}")
223
+
224
+ for item, outcome in parallel.map_bounded(
225
+ dataset.items,
226
+ build_variants,
227
+ ctx=ctx,
228
+ workers=params["workers"],
229
+ label=lambda item: item.stem,
230
+ on_error=note_failure,
231
+ ):
232
+ if outcome is None:
233
+ continue
234
+ kind, produced = outcome
235
+
236
+ if kind == "passthrough":
237
+ # Out of scope: pass it through untouched so the output is still a
238
+ # complete dataset rather than a train-only fragment.
239
+ writer.add(
240
+ item.annotation,
241
+ stem=item.stem,
242
+ source=item.image,
243
+ split=item.split,
244
+ suffix=item.image.suffix,
245
+ )
246
+ copied += 1
247
+ continue
248
+
249
+ if params["include_original"]:
250
+ writer.add(
251
+ item.annotation,
252
+ stem=item.stem,
253
+ source=item.image,
254
+ split=item.split,
255
+ suffix=item.image.suffix,
256
+ )
257
+ copied += 1
258
+
259
+ for variant, (annotation, encoded, used) in enumerate(produced, start=1):
260
+ dropped += max(0, len(item.annotation.shapes) - len(annotation.shapes))
261
+ applied.update(used)
262
+ writer.add(
263
+ annotation,
264
+ stem=f"{item.stem}_aug{variant}",
265
+ encoded=encoded,
266
+ source=item.image,
267
+ split=item.split,
268
+ suffix=item.image.suffix,
269
+ )
270
+ generated += 1
271
+
272
+ report = writer.close()
273
+ result.actions.extend(writer.actions)
274
+ result.counts.update(
275
+ {
276
+ "source_images": total,
277
+ "generated": generated,
278
+ "originals_kept": copied,
279
+ "total_images": generated + copied,
280
+ "objects_dropped": dropped,
281
+ }
282
+ )
283
+ result.warnings.extend(dataset.warnings)
284
+ result.warnings.extend(report["warnings"])
285
+ result.data.update(
286
+ {
287
+ "output": params["output"],
288
+ "format": target_format,
289
+ "seed": params["seed"],
290
+ "augmentations_enabled": sorted(plan.enabled),
291
+ "times_applied": dict(sorted(applied.items())),
292
+ }
293
+ )
294
+ if dropped:
295
+ result.warnings.append(
296
+ f"{dropped} object(s) rotated or cropped out of frame and were dropped; "
297
+ f"lower --min-visibility to keep partial objects"
298
+ )
299
+ return result
300
+
301
+
302
+ def _seed_for(seed: int, stem: str, variant: int) -> int:
303
+ """A stable per-(image, variant) seed.
304
+
305
+ Deliberately not ``hash((seed, stem, variant))``: Python randomises string
306
+ hashing per process, so that would reproduce within one run and silently
307
+ differ between runs -- the exact opposite of the guarantee this operation
308
+ makes. blake2b is stable across processes, machines and versions.
309
+
310
+ Seeding per image rather than per run also means adding one image to a
311
+ dataset does not reshuffle every other image's augmentations.
312
+ """
313
+ key = f"{seed}\x00{stem}\x00{variant}".encode()
314
+ return int.from_bytes(hashlib.blake2b(key, digest_size=8).digest(), "big") % (2**32)
315
+
316
+
317
+ class _Plan:
318
+ """The enabled augmentations, and how to roll one variant from them."""
319
+
320
+ def __init__(self, params: dict[str, Any]) -> None:
321
+ self.params = params
322
+ self.min_visibility = params["min_visibility"]
323
+ self.keep_size = params["keep_size"]
324
+ self.geometric = [
325
+ name
326
+ for name, on in (
327
+ ("flip_horizontal", params["flip_horizontal"]),
328
+ ("flip_vertical", params["flip_vertical"]),
329
+ ("rotate90", params["rotate90"]),
330
+ ("rotate", params["rotate"] > 0),
331
+ ("crop", params["crop"] > 0),
332
+ )
333
+ if on
334
+ ]
335
+ self.photometric = [
336
+ name
337
+ for name, on in (
338
+ ("brightness", params["brightness"] > 0),
339
+ ("contrast", params["contrast"] > 0),
340
+ ("saturation", params["saturation"] > 0),
341
+ ("hue", params["hue"] > 0),
342
+ ("blur", params["blur"] > 0),
343
+ ("noise", params["noise"] > 0),
344
+ ("grayscale", params["grayscale"] > 0),
345
+ ("cutout", params["cutout"] > 0),
346
+ )
347
+ if on
348
+ ]
349
+
350
+ @property
351
+ def enabled(self) -> list[str]:
352
+ return self.geometric + self.photometric
353
+
354
+ def apply(
355
+ self, array: np.ndarray, annotation: Annotation, rng: np.random.Generator
356
+ ) -> tuple[np.ndarray, Annotation, list[str]]:
357
+ used: list[str] = []
358
+ pixels = array
359
+ height, width = pixels.shape[:2]
360
+ source_size = (width, height)
361
+ steps: list[imaging.Transform] = []
362
+
363
+ for name in self.geometric:
364
+ # Half the time, per augmentation -- so variants differ from each
365
+ # other instead of all receiving the identical stack.
366
+ if rng.random() < 0.5:
367
+ continue
368
+ transform = self._geometric(name, width, height, rng)
369
+ if transform is None:
370
+ continue
371
+ steps.append(transform)
372
+ width, height = transform.out_size
373
+ used.append(name)
374
+
375
+ # Rotation expands the canvas to keep the corners, and random crop
376
+ # shrinks it, so a mixture of augmentations produces a mixture of
377
+ # sizes. Letterboxing back means a dataset resized to 640 stays at 640
378
+ # after augmentation instead of quietly acquiring 84 resolutions.
379
+ if steps and self.keep_size and (width, height) != source_size:
380
+ steps.append(
381
+ imaging.make_resize(width, height, source_size[0], source_size[1], "letterbox")
382
+ )
383
+ width, height = source_size
384
+
385
+ if steps:
386
+ combined = imaging.chain(*steps) if len(steps) > 1 else steps[0]
387
+ pixels = combined.image(pixels)
388
+ annotation = imaging.transform_annotation(
389
+ annotation, combined, min_visibility=self.min_visibility
390
+ )
391
+ else:
392
+ annotation = Annotation(
393
+ filename=annotation.filename,
394
+ width=width,
395
+ height=height,
396
+ depth=annotation.depth,
397
+ shapes=list(annotation.shapes),
398
+ folder=annotation.folder,
399
+ source_path=annotation.source_path,
400
+ )
401
+
402
+ for name in self.photometric:
403
+ if rng.random() < 0.5:
404
+ continue
405
+ pixels = self._photometric(name, pixels, rng)
406
+ used.append(name)
407
+
408
+ return pixels, annotation, used
409
+
410
+ def _geometric(
411
+ self, name: str, width: int, height: int, rng: np.random.Generator
412
+ ) -> imaging.Transform | None:
413
+ if name == "flip_horizontal":
414
+ return imaging.FlipH(out_size=(width, height))
415
+ if name == "flip_vertical":
416
+ return imaging.FlipV(out_size=(width, height))
417
+ if name == "rotate90":
418
+ turns = int(rng.integers(1, 4))
419
+ out = (height, width) if turns % 2 else (width, height)
420
+ return imaging.Rot90(out_size=out, turns=turns, src_size=(width, height))
421
+ if name == "rotate":
422
+ limit = float(self.params["rotate"])
423
+ degrees = float(rng.uniform(-limit, limit))
424
+ return imaging.make_rotate(width, height, degrees)
425
+ if name == "crop":
426
+ fraction = float(rng.uniform(0.0, self.params["crop"]))
427
+ new_w = max(8, int(width * (1.0 - fraction)))
428
+ new_h = max(8, int(height * (1.0 - fraction)))
429
+ left = int(rng.integers(0, max(1, width - new_w + 1)))
430
+ top = int(rng.integers(0, max(1, height - new_h + 1)))
431
+ return imaging.Crop(out_size=(new_w, new_h), left=left, top=top)
432
+ return None
433
+
434
+ def _photometric(
435
+ self, name: str, pixels: np.ndarray, rng: np.random.Generator
436
+ ) -> np.ndarray:
437
+ p = self.params
438
+ if name == "brightness":
439
+ return imaging.adjust_brightness(pixels, 1.0 + float(rng.uniform(-p["brightness"], p["brightness"])))
440
+ if name == "contrast":
441
+ return imaging.adjust_contrast(pixels, 1.0 + float(rng.uniform(-p["contrast"], p["contrast"])))
442
+ if name == "saturation":
443
+ return imaging.adjust_saturation(pixels, 1.0 + float(rng.uniform(-p["saturation"], p["saturation"])))
444
+ if name == "hue":
445
+ return imaging.adjust_hue(pixels, float(rng.uniform(-p["hue"], p["hue"])))
446
+ if name == "blur":
447
+ return imaging.blur(pixels, float(rng.uniform(0.5, max(0.5, p["blur"]))))
448
+ if name == "noise":
449
+ return imaging.add_noise(pixels, float(rng.uniform(0.0, p["noise"])), rng)
450
+ if name == "grayscale":
451
+ return imaging.to_grayscale(pixels) if rng.random() < p["grayscale"] else pixels
452
+ if name == "cutout":
453
+ return imaging.cutout(pixels, int(p["cutout"]), 0.15, rng)
454
+ return pixels
@@ -0,0 +1,241 @@
1
+ """Getting raw frames into the factory: from video files, or from a camera.
2
+
3
+ The webcam grabber existed only as a three-line unfinished stub; it is
4
+ implemented here properly, with the same result contract as everything else.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from pathlib import Path
10
+ from typing import Any
11
+
12
+ from .. import fs
13
+ from ..registry import Param, operation
14
+ from ..types import Action, Context, OpResult
15
+
16
+ FRAME_PARAMS = (
17
+ Param("source", "path", "A video file, or a folder of videos.", required=True, must_exist=True),
18
+ Param("output", "dir", "Folder to write frames into.", required=True),
19
+ Param("every_nth", "int", "Keep one frame out of every N.", default=1, minimum=1),
20
+ Param("max_frames", "int", "Stop after this many saved frames (0 = no limit).",
21
+ default=0, minimum=0),
22
+ Param("prefix", "str", "Filename prefix for saved frames.", default="frame"),
23
+ Param("pad", "int", "Zero-padding width for the frame number.", default=6, minimum=1, maximum=12),
24
+ Param("quality", "int", "JPEG quality.", default=95, minimum=1, maximum=100),
25
+ Param("resize_width", "int", "Downscale to this width, keeping aspect (0 = keep original).",
26
+ default=0, minimum=0),
27
+ Param("start_index", "int", "First frame number.", default=0, minimum=0),
28
+ )
29
+
30
+
31
+ @operation(
32
+ "collect.frames",
33
+ title="Extract frames from video",
34
+ category="collect",
35
+ summary="Turn one video or a whole folder of them into numbered JPEG frames.",
36
+ params=FRAME_PARAMS,
37
+ notes=(
38
+ "every_nth is the knob that matters. Consecutive frames of a video are near\n"
39
+ "identical, so extracting all of them mostly manufactures duplicates for\n"
40
+ "clean.dedup to find again. At 30fps, every_nth=15 gives two frames a second."
41
+ ),
42
+ )
43
+ def frames(params: dict[str, Any], ctx: Context) -> OpResult:
44
+ result = OpResult(op="collect.frames", dry_run=ctx.dry_run)
45
+ cv2 = _load_cv2()
46
+
47
+ source: Path = params["source"]
48
+ output: Path = params["output"]
49
+ videos = (
50
+ [source]
51
+ if source.is_file()
52
+ else list(fs.iter_files(source, recursive=False, exts=fs.VIDEO_EXTS))
53
+ )
54
+ if not videos:
55
+ result.fail(f"no video files found at {source}")
56
+ return result
57
+
58
+ fs.ensure_dir(output, ctx)
59
+ saved = int(params["start_index"])
60
+ limit = int(params["max_frames"])
61
+ every = int(params["every_nth"])
62
+ pad = int(params["pad"])
63
+
64
+ for video_path in videos:
65
+ ctx.check_cancelled()
66
+ capture = cv2.VideoCapture(str(video_path))
67
+ if not capture.isOpened():
68
+ result.warnings.append(f"cannot open {video_path.name}")
69
+ result.bump("videos_failed")
70
+ continue
71
+
72
+ total = int(capture.get(cv2.CAP_PROP_FRAME_COUNT)) or 0
73
+ read = 0
74
+ try:
75
+ while True:
76
+ ctx.check_cancelled()
77
+ ok, frame = capture.read()
78
+ if not ok:
79
+ break
80
+ if read % every == 0:
81
+ if params["resize_width"]:
82
+ frame = _resize_to_width(cv2, frame, int(params["resize_width"]))
83
+ destination = output / f"{params['prefix']}_{saved:0{pad}d}.jpg"
84
+ if not ctx.dry_run:
85
+ cv2.imwrite(
86
+ str(destination), frame, [cv2.IMWRITE_JPEG_QUALITY, int(params["quality"])]
87
+ )
88
+ result.record(Action.WRITE, video_path, destination, f"frame {read}")
89
+ saved += 1
90
+ result.bump("frames_saved")
91
+ if limit and result.counts.get("frames_saved", 0) >= limit:
92
+ break
93
+ read += 1
94
+ if total:
95
+ ctx.emit(read, total, video_path.name)
96
+ finally:
97
+ capture.release()
98
+
99
+ result.bump("videos_processed")
100
+ result.counts[f"frames_read:{video_path.name}"] = read
101
+ if limit and result.counts.get("frames_saved", 0) >= limit:
102
+ result.warnings.append(f"stopped at the {limit}-frame limit")
103
+ break
104
+
105
+ result.data["output"] = output
106
+ return result
107
+
108
+
109
+ WEBCAM_PARAMS = (
110
+ Param("output", "dir", "Folder to write captures into.", required=True),
111
+ Param("camera", "int", "Camera index.", default=0, minimum=0),
112
+ Param("count", "int", "How many images to capture (0 = until you quit).",
113
+ default=0, minimum=0),
114
+ Param("interval", "float", "Seconds between automatic captures (0 = manual, press SPACE).",
115
+ default=0.0, minimum=0.0),
116
+ Param("prefix", "str", "Filename prefix.", default="cam"),
117
+ Param("pad", "int", "Zero-padding width.", default=5, minimum=1, maximum=12),
118
+ Param("preview", "bool", "Show a live preview window.", default=True),
119
+ )
120
+
121
+
122
+ @operation(
123
+ "collect.webcam",
124
+ title="Capture images from a camera",
125
+ category="collect",
126
+ summary="Grab stills from a connected camera, manually or on a timer.",
127
+ params=WEBCAM_PARAMS,
128
+ notes=(
129
+ "With preview on: SPACE captures, Q or ESC quits. Set interval to capture\n"
130
+ "automatically instead. preview=False runs headless, which is what you want\n"
131
+ "over SSH or from a web backend -- pair it with count and interval."
132
+ ),
133
+ )
134
+ def webcam(params: dict[str, Any], ctx: Context) -> OpResult:
135
+ result = OpResult(op="collect.webcam", dry_run=ctx.dry_run)
136
+ cv2 = _load_cv2()
137
+ import time
138
+
139
+ output: Path = params["output"]
140
+ fs.ensure_dir(output, ctx)
141
+
142
+ capture = cv2.VideoCapture(int(params["camera"]))
143
+ if not capture.isOpened():
144
+ result.fail(f"cannot open camera {params['camera']}")
145
+ return result
146
+
147
+ target = int(params["count"])
148
+ interval = float(params["interval"])
149
+ preview = bool(params["preview"]) and not ctx.dry_run
150
+ pad = int(params["pad"])
151
+ saved = 0
152
+ last_capture = 0.0
153
+ window = "Data Factory - capture"
154
+
155
+ if preview and not _has_gui(cv2):
156
+ # The default install is opencv-python-headless, which has no window
157
+ # support at all. Falling back beats an unhandled cv2.error, and the
158
+ # timer path does the same job without a screen.
159
+ preview = False
160
+ result.warnings.append(
161
+ "no GUI support in this OpenCV build, so the preview window was skipped. "
162
+ "Install the 'gui' extra for a live preview, or pass --interval to "
163
+ "capture on a timer."
164
+ )
165
+ if interval <= 0:
166
+ interval = 1.0
167
+
168
+ try:
169
+ if preview:
170
+ cv2.namedWindow(window, cv2.WINDOW_NORMAL)
171
+ while True:
172
+ ctx.check_cancelled()
173
+ ok, frame = capture.read()
174
+ if not ok:
175
+ result.warnings.append("camera stopped returning frames")
176
+ break
177
+
178
+ now = time.monotonic()
179
+ take = False
180
+ if interval > 0 and now - last_capture >= interval:
181
+ take = True
182
+ if preview:
183
+ cv2.imshow(window, frame)
184
+ key = cv2.waitKey(1) & 0xFF
185
+ if key in (27, ord("q")):
186
+ break
187
+ if key == ord(" "):
188
+ take = True
189
+ elif interval <= 0:
190
+ # Headless with no timer would spin forever; one shot and out.
191
+ take = True
192
+
193
+ if take:
194
+ destination = output / f"{params['prefix']}_{saved:0{pad}d}.jpg"
195
+ if not ctx.dry_run:
196
+ cv2.imwrite(str(destination), frame)
197
+ result.record(Action.WRITE, Path(f"camera:{params['camera']}"), destination, "capture")
198
+ saved += 1
199
+ last_capture = now
200
+ result.bump("captured")
201
+ ctx.emit(saved, target or saved, f"captured {destination.name}")
202
+ if preview is False and interval <= 0:
203
+ break
204
+ if target and saved >= target:
205
+ break
206
+ finally:
207
+ capture.release()
208
+ if preview:
209
+ cv2.destroyAllWindows()
210
+
211
+ result.data["output"] = output
212
+ return result
213
+
214
+
215
+ def _has_gui(cv2: Any) -> bool:
216
+ """Whether this OpenCV build can open a window.
217
+
218
+ The headless wheel ships the same API surface but raises at call time, so
219
+ the only reliable check is the build information string.
220
+ """
221
+ try:
222
+ info = cv2.getBuildInformation()
223
+ except Exception:
224
+ return False
225
+ for backend in ("GTK", "QT", "WIN32 UI", "COCOA"):
226
+ if f"{backend}:" in info and "YES" in info.split(f"{backend}:")[1][:40]:
227
+ return True
228
+ return False
229
+
230
+
231
+ def _resize_to_width(cv2: Any, frame: Any, width: int) -> Any:
232
+ height = int(frame.shape[0] * (width / frame.shape[1]))
233
+ return cv2.resize(frame, (width, max(1, height)), interpolation=cv2.INTER_AREA)
234
+
235
+
236
+ def _load_cv2() -> Any:
237
+ try:
238
+ import cv2
239
+ except ImportError as exc: # pragma: no cover - depends on environment
240
+ raise RuntimeError(f"this operation needs opencv-python installed ({exc})") from exc
241
+ return cv2