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,326 @@
1
+ """Export an annotation project into any of the five dataset formats.
2
+
3
+ This is the single bridge between the annotation world and the batch world.
4
+ Annotation is stateful CRUD and cannot be expressed as an operation; *export*
5
+ genuinely is folder-out, so it becomes one -- and gets the job manager, the
6
+ progress UI, the dry run and the recipe support for free.
7
+
8
+ Two rules are enforced here rather than left to the caller:
9
+
10
+ **The class order comes from the project's label table.** Not from sorting the
11
+ names that happen to appear in this export. The label table allocates an index
12
+ once and never moves it, so exporting today and exporting after adding a class
13
+ produce the same indices for the classes that existed before. Getting this
14
+ wrong is silent -- the ``.txt`` files still parse, they just mean something
15
+ else -- which is why the ordering lives in a table with a test rather than in
16
+ whichever call site remembered.
17
+
18
+ **Only reviewed images are exported by default.** Feeding a model's own
19
+ unreviewed predictions back in as ground truth is how a model poisons itself,
20
+ and it does so without a single error message. Widening the selection is
21
+ possible, explicit, and warned about.
22
+ """
23
+
24
+ from __future__ import annotations
25
+
26
+ from pathlib import Path
27
+ from typing import Any
28
+
29
+ from ..annotations import formats
30
+ from ..annotations.model import Annotation
31
+ from ..registry import Param, operation
32
+ from ..types import Context, OpResult
33
+
34
+ #: The states this operation trusts unless told otherwise.
35
+ DEFAULT_STATES = "reviewed"
36
+
37
+ #: Anything outside this earns a warning: it is either unfinished work or an
38
+ #: explicit "I could not tell", and neither belongs in a training set by accident.
39
+ TRUSTED_STATES = frozenset({"reviewed"})
40
+
41
+ EXPORT_PARAMS = (
42
+ Param(
43
+ "database",
44
+ "file",
45
+ "The annotations.db holding the project.",
46
+ required=True,
47
+ must_exist=True,
48
+ ),
49
+ Param("project", "str", "Project id to export.", required=True),
50
+ Param("output", "dir", "Where the exported dataset is written.", required=True),
51
+ Param("to", "choice", "Target format.", default="yolo", choices=formats.FORMATS),
52
+ Param(
53
+ "images",
54
+ "dir",
55
+ "Folder holding the image files. Defaults to the project's own root.",
56
+ default=None,
57
+ ),
58
+ Param(
59
+ "states",
60
+ "strs",
61
+ "Image states to include. Default is reviewed only, on purpose.",
62
+ default=DEFAULT_STATES,
63
+ ),
64
+ Param(
65
+ "classes",
66
+ "strs",
67
+ "Override the project's class order. Rarely correct -- see the notes.",
68
+ default=None,
69
+ ),
70
+ Param("owner", "str", "Owner the project belongs to.", default="local"),
71
+ Param("copy_images", "bool", "Copy the image files alongside the labels.", default=True),
72
+ Param(
73
+ "segmentation",
74
+ "bool",
75
+ "Keep polygon outlines where the target format supports them.",
76
+ default=True,
77
+ ),
78
+ Param(
79
+ "include_empty",
80
+ "bool",
81
+ "Include images with no objects, as hard negatives.",
82
+ default=True,
83
+ ),
84
+ )
85
+
86
+
87
+ @operation(
88
+ "annotate.export",
89
+ title="Export an annotation project",
90
+ category="export",
91
+ summary="Turn a project's annotations into a VOC, YOLO, COCO, LabelMe or CSV dataset.",
92
+ params=EXPORT_PARAMS,
93
+ destructive=True,
94
+ hidden_from_web=True,
95
+ notes=(
96
+ "The class order is the project's own label order, and label indices\n"
97
+ "never move: renaming a class keeps its index, retiring one keeps its\n"
98
+ "slot, and a new class is appended. Export twice with a class added in\n"
99
+ "between and the original indices are identical -- which is what makes\n"
100
+ "the .txt files you exported last month still mean what they said.\n"
101
+ "\n"
102
+ "'classes' overrides that order. It exists for the case where you are\n"
103
+ "matching a class list someone else fixed, and it is otherwise a way to\n"
104
+ "reintroduce exactly the bug the label table removes. Any class present\n"
105
+ "but unlisted is appended rather than inserted.\n"
106
+ "\n"
107
+ "'states' defaults to 'reviewed' because unreviewed images may hold raw\n"
108
+ "model predictions. Exporting those back into training teaches a model\n"
109
+ "its own mistakes, and nothing about the output looks wrong."
110
+ ),
111
+ )
112
+ def annotate_export(params: dict[str, Any], ctx: Context) -> OpResult:
113
+ # Imported here, not at module scope, so `core` keeps its own import graph
114
+ # free of the annotation package -- and so a build without it still lists
115
+ # every other operation instead of failing to import ops entirely.
116
+ from ...annotate import images as images_mod
117
+ from ...annotate import labels as labels_mod
118
+ from ...annotate import projects as projects_mod
119
+ from ...annotate import shapes as shapes_mod
120
+ from ...annotate.store import Store, StoreError
121
+
122
+ result = OpResult(op="annotate.export", dry_run=ctx.dry_run)
123
+ output: Path = params["output"]
124
+ target: str = params["to"]
125
+
126
+ try:
127
+ store = Store(params["database"])
128
+ project = projects_mod.get(store, params["project"], params["owner"])
129
+ except StoreError as exc:
130
+ # The commonest way to get here is running the shipped recipe without
131
+ # setting the project, so say what to do rather than only what broke.
132
+ result.fail(f"{exc}. {_project_hint(store, params)}")
133
+ return result
134
+
135
+ try:
136
+ return _export(
137
+ params, ctx, result, store, project, output, target,
138
+ images_mod, labels_mod, shapes_mod,
139
+ )
140
+ finally:
141
+ store.close()
142
+
143
+
144
+ def _default_image_root(database: Path, project: Any) -> Path | None:
145
+ """Where this project's images live, when the caller did not say.
146
+
147
+ An *attached* project knows: it is the folder the user opened. A *managed*
148
+ project's images sit beside the database, at ``projects/<id>/`` -- derived
149
+ from the database path rather than imported from the service layer, so
150
+ ``core`` keeps its own import graph and the two cannot drift into
151
+ disagreeing about the layout by accident.
152
+
153
+ Without this, exporting a managed project quietly produced labels and no
154
+ images, which reads as "the export is broken" rather than "you did not say
155
+ where the pictures were".
156
+ """
157
+ if project.root:
158
+ return Path(project.root)
159
+ candidate = Path(database).parent / "projects" / project.id
160
+ return candidate if candidate.is_dir() else None
161
+
162
+
163
+ def _project_hint(store: Any, params: dict[str, Any]) -> str:
164
+ """Name the projects that *are* in this database, if any."""
165
+ from ...annotate import projects as projects_mod
166
+
167
+ try:
168
+ found = projects_mod.listing(store, params["owner"])
169
+ except Exception:
170
+ return ""
171
+ if not found:
172
+ return (
173
+ f"There are no projects in {params['database']} yet -- run "
174
+ f"'datafactory annotate <folder>' to make one."
175
+ )
176
+ listed = ", ".join(f"{p.name} ({p.id})" for p in found[:5])
177
+ return f"Projects here: {listed}"
178
+
179
+
180
+ def _export(
181
+ params, ctx, result, store, project, output, target,
182
+ images_mod, labels_mod, shapes_mod,
183
+ ) -> OpResult:
184
+ from ...annotate.store import StoreError
185
+
186
+ wanted = [s.strip() for s in (params["states"] or []) if s.strip()]
187
+ unknown = [s for s in wanted if s not in images_mod.STATES]
188
+ if unknown:
189
+ result.fail(
190
+ f"unknown image state(s): {', '.join(unknown)}. "
191
+ f"Valid: {', '.join(images_mod.STATES)}"
192
+ )
193
+ return result
194
+ if not wanted:
195
+ wanted = [DEFAULT_STATES]
196
+
197
+ risky = sorted(set(wanted) - TRUSTED_STATES)
198
+ if risky:
199
+ result.warnings.append(
200
+ f"exporting unreviewed images ({', '.join(risky)}): any model "
201
+ f"predictions among them have not been checked by a person"
202
+ )
203
+
204
+ # The class order. The project's own unless explicitly overridden.
205
+ order = [c.strip() for c in (params["classes"] or []) if c.strip()]
206
+ if order:
207
+ result.warnings.append(
208
+ "'classes' overrode the project's label order; indices in this "
209
+ "export may not match previous ones"
210
+ )
211
+ else:
212
+ order = labels_mod.class_list(store, project)
213
+ if not order:
214
+ result.fail("this project has no labels yet, so there is nothing to export")
215
+ return result
216
+
217
+ supplied = params["images"]
218
+ if supplied is not None and not Path(supplied).is_dir():
219
+ # Asked for explicitly and not there. Falling back would produce a
220
+ # labels-only export that looks like the exporter is broken, when in
221
+ # fact the path was wrong -- so it fails, and says which path.
222
+ result.fail(f"images: no such folder: {supplied}")
223
+ return result
224
+
225
+ root = supplied or _default_image_root(params["database"], project)
226
+ copy_images = bool(params["copy_images"]) and root is not None
227
+ if params["copy_images"] and root is None:
228
+ result.warnings.append(
229
+ "no image folder was found for this project, so only labels were "
230
+ "written. Pass 'images' to point at the pictures."
231
+ )
232
+
233
+ items: list[formats.Item] = []
234
+ missing_files = 0
235
+ skipped_empty = 0
236
+ selected = [img for state in wanted for img in _all_in_state(store, project, images_mod, state)]
237
+ selected.sort(key=lambda i: i.seq)
238
+
239
+ total = len(selected)
240
+ ctx.emit(0, total, f"{project.name} -> {target}")
241
+
242
+ for done, image in enumerate(selected, start=1):
243
+ ctx.check_cancelled()
244
+ try:
245
+ annotation: Annotation = shapes_mod.annotation_for(store, project, image)
246
+ except StoreError as exc:
247
+ result.warnings.append(f"{image.rel_path}: {exc}")
248
+ continue
249
+
250
+ if not annotation.shapes and not params["include_empty"]:
251
+ skipped_empty += 1
252
+ continue
253
+
254
+ image_path: Path | None = None
255
+ if root is not None:
256
+ candidate = Path(root) / image.rel_path
257
+ if candidate.is_file():
258
+ image_path = candidate
259
+ else:
260
+ missing_files += 1
261
+
262
+ items.append(formats.Item(annotation=annotation, image=image_path))
263
+ if done % 200 == 0 or done == total:
264
+ ctx.emit(done, total, image.name)
265
+
266
+ if not items:
267
+ result.fail(
268
+ f"no images matched state(s) {', '.join(wanted)}. "
269
+ f"Counts: {images_mod.counts(store, project)}"
270
+ )
271
+ return result
272
+
273
+ dataset = formats.Dataset(items=items, source_format="annotate", classes=order)
274
+ report = formats.write_dataset(
275
+ dataset,
276
+ output,
277
+ target,
278
+ ctx=ctx,
279
+ copy_images=copy_images,
280
+ segmentation=params["segmentation"],
281
+ on_action=lambda action: result.actions.append(action),
282
+ )
283
+
284
+ stats = dataset.stats()
285
+ result.counts.update(
286
+ {
287
+ "images": stats["images"],
288
+ "objects": stats["objects"],
289
+ "classes": len(order),
290
+ "backgrounds": stats["backgrounds"],
291
+ "labels_written": int(report["written"]),
292
+ "images_copied": int(report["images"]),
293
+ "skipped_empty": skipped_empty,
294
+ }
295
+ )
296
+ if missing_files:
297
+ result.warnings.append(
298
+ f"{missing_files} image file(s) named in the project were not found "
299
+ f"under {root}; their labels were still written"
300
+ )
301
+ result.warnings.extend(str(w) for w in report["warnings"]) # type: ignore[union-attr]
302
+ result.data.update(
303
+ {
304
+ "project": project.name,
305
+ "project_id": project.id,
306
+ "target_format": target,
307
+ "output": output,
308
+ "classes": order,
309
+ "states": wanted,
310
+ }
311
+ )
312
+ return result
313
+
314
+
315
+ def _all_in_state(store, project, images_mod, state: str) -> list[Any]:
316
+ """Every image in one state, paged so a 50,000-image project does not
317
+ build one enormous result set."""
318
+ out: list[Any] = []
319
+ offset = 0
320
+ page = 2000
321
+ while True:
322
+ batch = images_mod.listing(store, project, state=state, limit=page, offset=offset)
323
+ out.extend(batch)
324
+ if len(batch) < page:
325
+ return out
326
+ offset += page
@@ -0,0 +1,274 @@
1
+ """Dataset health reports -- the "what shape is this data actually in" command.
2
+
3
+ No original script did this. Every check here corresponds to a defect that has
4
+ really occurred in this repository: case-variant classes that split a class in
5
+ two, polygons the converter could not read, labels whose image is gone, and
6
+ boxes whose coordinates fall outside the image they annotate.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from collections import Counter
12
+ from pathlib import Path
13
+ from typing import Any
14
+
15
+ from ..annotations import coco as coco_format
16
+ from ..annotations import voc
17
+ from ..annotations.model import AnnotationError
18
+ from ..pairs import PairIndex
19
+ from ..registry import Param, operation
20
+ from ..types import Context, OpResult
21
+
22
+ PARAMS = (
23
+ Param("folder", "dir", "Dataset folder to audit.", required=True, must_exist=True),
24
+ Param("recursive", "bool", "Include sub-folders.", default=True),
25
+ Param("check_images", "bool",
26
+ "Open every image to verify it decodes and matches the size in its label.",
27
+ default=False),
28
+ Param("check_duplicates", "choice", "Also scan for duplicate images.",
29
+ default="none", choices=("none", "exact", "phash")),
30
+ Param("threshold", "int", "Hamming distance for phash duplicate detection.",
31
+ default=8, minimum=0, maximum=64),
32
+ Param("label_ext", "str", "Sidecar label extension.", default=".xml"),
33
+ )
34
+
35
+
36
+ @operation(
37
+ "inspect.dataset",
38
+ title="Audit a dataset",
39
+ category="inspect",
40
+ summary="One report: pairing, classes, geometry problems, corrupt files, and optional duplicates.",
41
+ params=PARAMS,
42
+ notes=(
43
+ "Read-only -- it changes nothing, so it is always safe to run first.\n\n"
44
+ "check_images decodes every file, which is slow on a big set but is the only\n"
45
+ "way to catch truncated JPEGs and labels whose <size> disagrees with the\n"
46
+ "actual image (a common cause of boxes that look right in the XML and land\n"
47
+ "in the wrong place at training time)."
48
+ ),
49
+ )
50
+ def inspect_dataset(params: dict[str, Any], ctx: Context) -> OpResult:
51
+ result = OpResult(op="inspect.dataset", dry_run=ctx.dry_run)
52
+ folder: Path = params["folder"]
53
+
54
+ index = PairIndex.scan(folder, recursive=params["recursive"], label_ext=params["label_ext"])
55
+ result.counts.update(index.summary())
56
+
57
+ labels: Counter[str] = Counter()
58
+ corrupt: list[dict[str, str]] = []
59
+ geometry: list[dict[str, Any]] = []
60
+ size_mismatch: list[dict[str, Any]] = []
61
+ unreadable_images: list[str] = []
62
+ backgrounds = 0
63
+ polygon_objects = 0
64
+ total_objects = 0
65
+
66
+ pairs = index.complete()
67
+ for position, pair in enumerate(pairs, start=1):
68
+ ctx.check_cancelled()
69
+ ctx.emit(position, len(pairs), pair.stem)
70
+ assert pair.image is not None and pair.label is not None
71
+
72
+ try:
73
+ annotation = voc.read(pair.label)
74
+ except AnnotationError as exc:
75
+ corrupt.append({"file": str(pair.label), "error": str(exc)})
76
+ continue
77
+
78
+ if annotation.is_background:
79
+ backgrounds += 1
80
+
81
+ width, height = annotation.width, annotation.height
82
+ if params["check_images"]:
83
+ actual = _image_size(pair.image)
84
+ if actual is None:
85
+ unreadable_images.append(str(pair.image))
86
+ elif (width, height) != actual and width > 0 and height > 0:
87
+ size_mismatch.append(
88
+ {"file": str(pair.image), "label_says": [width, height], "actual": list(actual)}
89
+ )
90
+ width, height = actual
91
+
92
+ for shape in annotation.shapes:
93
+ total_objects += 1
94
+ labels[shape.label] += 1
95
+ if shape.has_polygon:
96
+ polygon_objects += 1
97
+ problem = _geometry_problem(shape, width, height)
98
+ if problem:
99
+ geometry.append(
100
+ {"file": str(pair.label), "label": shape.label,
101
+ "bbox": list(shape.bbox), "problem": problem}
102
+ )
103
+
104
+ folded: dict[str, list[str]] = {}
105
+ for label in labels:
106
+ folded.setdefault(label.strip().casefold(), []).append(label)
107
+ variants = {k: sorted(v) for k, v in folded.items() if len(v) > 1}
108
+
109
+ result.counts.update(
110
+ {
111
+ "objects": total_objects,
112
+ "classes": len(labels),
113
+ "background_images": backgrounds,
114
+ "polygon_objects": polygon_objects,
115
+ "bbox_only_objects": total_objects - polygon_objects,
116
+ "corrupt_labels": len(corrupt),
117
+ "geometry_problems": len(geometry),
118
+ }
119
+ )
120
+ if params["check_images"]:
121
+ result.counts["unreadable_images"] = len(unreadable_images)
122
+ result.counts["size_mismatches"] = len(size_mismatch)
123
+
124
+ result.data["per_label"] = dict(sorted(labels.items()))
125
+ result.data["case_variants"] = variants
126
+ result.data["corrupt_labels"] = corrupt[:200]
127
+ result.data["geometry_problems"] = geometry[:200]
128
+ result.data["size_mismatches"] = size_mismatch[:200]
129
+ result.data["unreadable_images"] = unreadable_images[:200]
130
+
131
+ if params["check_duplicates"] != "none":
132
+ result.data["duplicates"] = _duplicate_scan(index, params, result, ctx)
133
+
134
+ result.data["issues"] = _issues(result, index, variants, corrupt, geometry, size_mismatch)
135
+ return result
136
+
137
+
138
+ def _geometry_problem(shape: Any, width: int, height: int) -> str | None:
139
+ xmin, ymin, xmax, ymax = shape.bbox
140
+ if xmax <= xmin or ymax <= ymin:
141
+ return "zero or negative area"
142
+ if xmin < 0 or ymin < 0:
143
+ return "negative coordinates"
144
+ if width > 0 and height > 0 and (xmax > width or ymax > height):
145
+ return f"extends past the {width}x{height} image"
146
+ if shape.polygon is not None and 0 < len(shape.polygon) < 3:
147
+ return f"polygon has only {len(shape.polygon)} point(s)"
148
+ return None
149
+
150
+
151
+ def _duplicate_scan(
152
+ index: PairIndex, params: dict[str, Any], result: OpResult, ctx: Context
153
+ ) -> dict[str, Any]:
154
+ """Reuse the dedup machinery in report-only mode.
155
+
156
+ Bound through the registry rather than by hand: that fills in defaults for
157
+ every parameter we do not care about here, so adding one to clean.dedup
158
+ cannot silently break this call site.
159
+ """
160
+ from ..registry import get as get_operation
161
+
162
+ method = params["check_duplicates"]
163
+ preview = Context(dry_run=True, progress=ctx.progress, cancel_check=ctx.cancel_check)
164
+ dedup_op = get_operation("clean.dedup")
165
+ found = dedup_op.func(
166
+ dedup_op.bind(
167
+ {
168
+ "folders": [index.root],
169
+ "method": method,
170
+ "threshold": int(params["threshold"]),
171
+ "action": "report",
172
+ "recursive": params["recursive"],
173
+ }
174
+ ),
175
+ preview,
176
+ )
177
+ result.counts["duplicate_images"] = found.counts.get("duplicates", 0)
178
+ return {"method": method, "count": found.counts.get("duplicates", 0), "groups": found.data.get("groups", {})}
179
+
180
+
181
+ def _issues(
182
+ result: OpResult,
183
+ index: PairIndex,
184
+ variants: dict[str, list[str]],
185
+ corrupt: list[dict[str, str]],
186
+ geometry: list[dict[str, Any]],
187
+ size_mismatch: list[dict[str, Any]],
188
+ ) -> list[dict[str, str]]:
189
+ """Turn raw findings into a prioritised, human-readable list."""
190
+ issues: list[dict[str, str]] = []
191
+
192
+ def add(severity: str, headline: str, fix: str) -> None:
193
+ issues.append({"severity": severity, "issue": headline, "fix": fix})
194
+
195
+ if variants:
196
+ joined = "; ".join(" / ".join(v) for v in variants.values())
197
+ add("high", f"classes differing only by case: {joined}",
198
+ "datafactory labels.rename --folder <dir> --fold-case")
199
+ if corrupt:
200
+ add("high", f"{len(corrupt)} label file(s) could not be parsed",
201
+ "inspect the files listed in data.corrupt_labels and re-annotate or delete them")
202
+ if index.label_only():
203
+ add("medium", f"{len(index.label_only())} label(s) have no matching image",
204
+ "datafactory clean.orphans --folder <dir> --scope labels")
205
+ if index.image_only():
206
+ add("low", f"{len(index.image_only())} image(s) have no label",
207
+ "datafactory clean.unannotated --folder <dir> --target <to_annotate>")
208
+ if geometry:
209
+ add("medium", f"{len(geometry)} object(s) have out-of-bounds or degenerate boxes",
210
+ "review data.geometry_problems; these usually come from resizing images after annotating")
211
+ if size_mismatch:
212
+ add("high", f"{len(size_mismatch)} label(s) record a different size than the image",
213
+ "the coordinates are relative to the old size and will be wrong; re-annotate or rescale")
214
+ if result.counts.get("duplicate_images"):
215
+ add("medium", f"{result.counts['duplicate_images']} duplicate image(s)",
216
+ "datafactory clean.dedup --folders <dir> --method phash")
217
+ if not issues:
218
+ add("none", "no problems found", "")
219
+ return issues
220
+
221
+
222
+ COCO_PARAMS = (
223
+ Param("file", "file", "Path to an instances.json.", required=True, must_exist=True),
224
+ )
225
+
226
+
227
+ @operation(
228
+ "inspect.coco",
229
+ title="Audit a COCO annotations file",
230
+ category="inspect",
231
+ summary="Summarise an existing instances.json and flag case-collided categories.",
232
+ params=COCO_PARAMS,
233
+ notes="Read-only. Use it to check an export before handing the dataset to training.",
234
+ )
235
+ def inspect_coco(params: dict[str, Any], ctx: Context) -> OpResult:
236
+ result = OpResult(op="inspect.coco", dry_run=ctx.dry_run)
237
+ path: Path = params["file"]
238
+ try:
239
+ document = coco_format.load(path)
240
+ except Exception as exc:
241
+ result.fail(f"{path.name}: {exc}")
242
+ return result
243
+
244
+ summary = coco_format.summarise(document)
245
+ result.counts.update(
246
+ {
247
+ "images": summary["images"],
248
+ "annotations": summary["annotations"],
249
+ "categories": summary["categories"],
250
+ "with_segmentation": summary["with_segmentation"],
251
+ "background_images": summary["background_images"],
252
+ }
253
+ )
254
+ result.data["per_category"] = summary["per_category"]
255
+ result.data["case_collisions"] = summary["case_collisions"]
256
+ if summary["case_collisions"]:
257
+ joined = "; ".join(" / ".join(v) for v in summary["case_collisions"].values())
258
+ result.warnings.append(
259
+ f"categories differing only by case: {joined} -- "
260
+ "re-export with case_policy=casefold, or fix the source labels first"
261
+ )
262
+ return result
263
+
264
+
265
+ def _image_size(path: Path) -> tuple[int, int] | None:
266
+ try:
267
+ from PIL import Image
268
+
269
+ with Image.open(path) as image:
270
+ image.verify()
271
+ with Image.open(path) as image:
272
+ return image.size
273
+ except Exception:
274
+ return None