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,394 @@
1
+ """COCO instances.json construction.
2
+
3
+ The category handling here is deliberate. The original converter keyed
4
+ categories on the raw XML string, so a dataset whose labels drifted between
5
+ ``Open`` and ``open`` came out with four classes instead of two -- exactly what
6
+ happened to Project_Door V3 (Close/Open/open/close split 1341/1385/645/500).
7
+ The builder now folds case by default and reports every merge it made, so the
8
+ drift is fixed *and* visible rather than silently baked into the export.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import json
14
+ from collections.abc import Iterable
15
+ from dataclasses import dataclass, field
16
+ from pathlib import Path
17
+ from typing import Any
18
+
19
+ from ..fs import write_text_atomic
20
+ from .model import Annotation, AnnotationError, Point, Shape
21
+
22
+ #: How to decide whether two label spellings are the same class.
23
+ CASE_POLICIES = ("exact", "casefold")
24
+
25
+
26
+ @dataclass
27
+ class CategoryTable:
28
+ """Assigns stable category ids, optionally folding case-variant spellings."""
29
+
30
+ case_policy: str = "casefold"
31
+ label_map: dict[str, str] = field(default_factory=dict)
32
+
33
+ _ids: dict[str, int] = field(default_factory=dict, init=False)
34
+ _names: dict[str, str] = field(default_factory=dict, init=False)
35
+ _variants: dict[str, set[str]] = field(default_factory=dict, init=False)
36
+
37
+ def key_for(self, label: str) -> str:
38
+ renamed = self.label_map.get(label, label).strip()
39
+ return renamed.casefold() if self.case_policy == "casefold" else renamed
40
+
41
+ def id_for(self, label: str) -> int:
42
+ renamed = self.label_map.get(label, label).strip()
43
+ key = self.key_for(label)
44
+ if key not in self._ids:
45
+ self._ids[key] = len(self._ids) + 1
46
+ # First spelling encountered becomes the exported display name; the
47
+ # scan is sorted, so this is reproducible across runs.
48
+ self._names[key] = renamed
49
+ self._variants[key] = set()
50
+ self._variants[key].add(renamed)
51
+ return self._ids[key]
52
+
53
+ def categories(self) -> list[dict[str, Any]]:
54
+ return [
55
+ {"id": self._ids[key], "name": self._names[key], "supercategory": "none"}
56
+ for key in sorted(self._ids, key=lambda k: self._ids[k])
57
+ ]
58
+
59
+ def merges(self) -> dict[str, list[str]]:
60
+ """Classes that absorbed more than one spelling, for reporting."""
61
+ return {
62
+ self._names[key]: sorted(variants)
63
+ for key, variants in self._variants.items()
64
+ if len(variants) > 1
65
+ }
66
+
67
+
68
+ class CocoBuilder:
69
+ """Accumulates images and annotations into a COCO dictionary."""
70
+
71
+ def __init__(
72
+ self,
73
+ description: str = "Data Factory export",
74
+ version: str = "1.0",
75
+ case_policy: str = "casefold",
76
+ label_map: dict[str, str] | None = None,
77
+ ) -> None:
78
+ if case_policy not in CASE_POLICIES:
79
+ raise ValueError(f"case_policy must be one of {CASE_POLICIES}")
80
+ self.description = description
81
+ self.version = version
82
+ self.categories = CategoryTable(case_policy=case_policy, label_map=label_map or {})
83
+ self.images: list[dict[str, Any]] = []
84
+ self.annotations: list[dict[str, Any]] = []
85
+ self.background_images = 0
86
+ self._next_image_id = 1
87
+ self._next_ann_id = 1
88
+
89
+ def add(self, annotation: Annotation, file_name: str | None = None) -> int:
90
+ """Add one annotated image; returns its COCO image id."""
91
+ image_id = self._next_image_id
92
+ self._next_image_id += 1
93
+ self.images.append(
94
+ {
95
+ "id": image_id,
96
+ "file_name": file_name or annotation.filename,
97
+ "width": annotation.width,
98
+ "height": annotation.height,
99
+ }
100
+ )
101
+ if annotation.is_background:
102
+ # Hard negatives belong in the export: an image entry with no
103
+ # annotations is how COCO expresses "nothing here, on purpose".
104
+ self.background_images += 1
105
+ for shape in annotation.shapes:
106
+ self._add_shape(shape, image_id)
107
+ return image_id
108
+
109
+ def _add_shape(self, shape: Shape, image_id: int) -> None:
110
+ xmin, ymin, xmax, ymax = shape.bbox
111
+ entry = {
112
+ "id": self._next_ann_id,
113
+ "image_id": image_id,
114
+ "category_id": self.categories.id_for(shape.label),
115
+ "bbox": [xmin, ymin, xmax - xmin, ymax - ymin],
116
+ "segmentation": [shape.flat_polygon()] if shape.has_polygon else [],
117
+ # Polygon area is the true mask area; falling back to the box
118
+ # keeps bbox-only objects comparable in COCO eval.
119
+ "area": round(shape.polygon_area(), 2),
120
+ "iscrowd": 0,
121
+ }
122
+ if shape.is_point:
123
+ # COCO has no point type; a visible keypoint with a one-pixel box
124
+ # is the form its keypoint evaluators and viewers both accept.
125
+ entry["bbox"] = [xmin, ymin, 1, 1]
126
+ entry["area"] = 1
127
+ entry["keypoints"] = [xmin, ymin, 2]
128
+ entry["num_keypoints"] = 1
129
+ self.annotations.append(entry)
130
+ self._next_ann_id += 1
131
+
132
+ def build(self) -> dict[str, Any]:
133
+ return {
134
+ "info": {"description": self.description, "version": self.version},
135
+ "licenses": [],
136
+ "images": self.images,
137
+ "annotations": self.annotations,
138
+ "categories": self.categories.categories(),
139
+ }
140
+
141
+ def write(self, path: Path) -> Path:
142
+ path.parent.mkdir(parents=True, exist_ok=True)
143
+ write_text_atomic(path, json.dumps(self.build(), indent=2))
144
+ return path
145
+
146
+ def stats(self) -> dict[str, int]:
147
+ return {
148
+ "images": len(self.images),
149
+ "annotations": len(self.annotations),
150
+ "categories": len(self.categories.categories()),
151
+ "background_images": self.background_images,
152
+ }
153
+
154
+
155
+ def load(path: Path) -> dict[str, Any]:
156
+ """Read an existing instances.json."""
157
+ return json.loads(Path(path).read_text(encoding="utf-8"))
158
+
159
+
160
+ def _score(ann: dict[str, Any]) -> float | None:
161
+ """A detection's confidence, if it has one."""
162
+ raw = ann.get("score")
163
+ if raw is None:
164
+ return None
165
+ try:
166
+ return float(raw)
167
+ except (TypeError, ValueError):
168
+ return None
169
+
170
+
171
+ def is_detection_results(document: Any) -> bool:
172
+ """Whether this is the *detection results* form rather than a dataset.
173
+
174
+ torchvision, mmdetection and Ultralytics all evaluate against a bare JSON
175
+ **list** of ``{image_id, category_id, bbox, score}`` -- no ``images``, no
176
+ ``categories``. It is what you get out of a model, and it is therefore the
177
+ exact file someone will try to load back in for review.
178
+ """
179
+ return isinstance(document, list)
180
+
181
+
182
+ def results_to_annotations(
183
+ results: list[dict[str, Any]],
184
+ *,
185
+ names: dict[Any, str] | None = None,
186
+ sizes: dict[Any, tuple[int, int]] | None = None,
187
+ filenames: dict[Any, str] | None = None,
188
+ ) -> list[Annotation]:
189
+ """Read the detection-results form into annotations.
190
+
191
+ Everything a dataset document would have carried -- image file names,
192
+ sizes, category names -- is absent here, because the file is designed to be
193
+ read *alongside* the dataset it was evaluated on. Callers pass what they
194
+ know; anything missing degrades to a usable stand-in rather than an error,
195
+ because refusing to show a person their model's output on a technicality
196
+ helps nobody.
197
+ """
198
+ names = names or {}
199
+ sizes = sizes or {}
200
+ filenames = filenames or {}
201
+ by_image: dict[Any, Annotation] = {}
202
+
203
+ for entry in results:
204
+ if not isinstance(entry, dict):
205
+ continue
206
+ image_id = entry.get("image_id")
207
+ bbox = entry.get("bbox") or [0, 0, 0, 0]
208
+ try:
209
+ x, y, w, h = (float(v) for v in bbox[:4])
210
+ except (TypeError, ValueError):
211
+ continue
212
+
213
+ annotation = by_image.get(image_id)
214
+ if annotation is None:
215
+ width, height = sizes.get(image_id, (0, 0))
216
+ annotation = Annotation(
217
+ filename=filenames.get(image_id, f"{image_id}"),
218
+ width=width,
219
+ height=height,
220
+ shapes=[],
221
+ )
222
+ by_image[image_id] = annotation
223
+
224
+ category = entry.get("category_id")
225
+ segmentation = entry.get("segmentation")
226
+ polygon = (
227
+ _first_polygon(segmentation)
228
+ if isinstance(segmentation, list) and segmentation
229
+ else None
230
+ )
231
+ annotation.shapes.append(
232
+ Shape(
233
+ label=names.get(category, f"class_{category}"),
234
+ bbox=(int(round(x)), int(round(y)), int(round(x + w)), int(round(y + h))),
235
+ polygon=polygon,
236
+ confidence=_score(entry),
237
+ )
238
+ )
239
+
240
+ for annotation in by_image.values():
241
+ if (annotation.width <= 0 or annotation.height <= 0) and annotation.shapes:
242
+ annotation.width = max(s.bbox[2] for s in annotation.shapes) + 1
243
+ annotation.height = max(s.bbox[3] for s in annotation.shapes) + 1
244
+
245
+ return [by_image[k] for k in sorted(by_image, key=lambda k: str(by_image[k].filename))]
246
+
247
+
248
+ def to_annotations(
249
+ coco: dict[str, Any], *, unsupported_out: list[str] | None = None
250
+ ) -> list[Annotation]:
251
+ """Explode a COCO document back into one :class:`Annotation` per image.
252
+
253
+ This is what makes COCO a two-way format rather than an export-only dead
254
+ end. Images carrying no annotations are preserved as backgrounds, since in
255
+ COCO that absence is meaningful rather than incidental.
256
+
257
+ RLE segmentations (``iscrowd=1``, or a dict-valued ``segmentation``) cannot
258
+ become a polygon without a mask decoder, so the box is kept and the fact is
259
+ reported through ``unsupported_out`` rather than passed off as a polygon.
260
+ """
261
+ if is_detection_results(coco):
262
+ # Previously this raised AttributeError deep inside a dict lookup,
263
+ # which told the user nothing about what they had actually handed over.
264
+ raise AnnotationError(
265
+ "this is a COCO *detection results* file (a bare list of "
266
+ "predictions), not a dataset. It has no images or categories of "
267
+ "its own -- load it against the project it was run on, with "
268
+ "results_to_annotations, or import it as predictions."
269
+ )
270
+ if not isinstance(coco, dict):
271
+ raise AnnotationError(
272
+ f"a COCO document must be an object, got {type(coco).__name__}"
273
+ )
274
+
275
+ names = {c["id"]: str(c.get("name", f"class_{c['id']}")) for c in coco.get("categories", [])}
276
+ by_image: dict[int, Annotation] = {}
277
+
278
+ for image in coco.get("images", []):
279
+ by_image[image["id"]] = Annotation(
280
+ filename=Path(str(image.get("file_name", ""))).name,
281
+ width=int(image.get("width") or 0),
282
+ height=int(image.get("height") or 0),
283
+ shapes=[],
284
+ )
285
+
286
+ rle_count = 0
287
+ for ann in coco.get("annotations", []):
288
+ annotation = by_image.get(ann.get("image_id"))
289
+ if annotation is None:
290
+ continue
291
+ bbox = ann.get("bbox") or [0, 0, 0, 0]
292
+ try:
293
+ x, y, w, h = (float(v) for v in bbox[:4])
294
+ except (TypeError, ValueError):
295
+ continue
296
+
297
+ segmentation = ann.get("segmentation")
298
+ polygon: list[Point] | None = None
299
+ if isinstance(segmentation, dict) or ann.get("iscrowd"):
300
+ rle_count += 1
301
+ elif isinstance(segmentation, list) and segmentation:
302
+ polygon = _first_polygon(segmentation)
303
+
304
+ annotation.shapes.append(
305
+ Shape(
306
+ label=names.get(ann.get("category_id"), f"class_{ann.get('category_id')}"),
307
+ bbox=(
308
+ int(round(x)),
309
+ int(round(y)),
310
+ int(round(x + w)),
311
+ int(round(y + h)),
312
+ ),
313
+ polygon=polygon,
314
+ # 'score' is what every detector writes and no ground-truth
315
+ # file has. Carrying it is what lets the review layer tell a
316
+ # prediction from a label rather than trusting a filename.
317
+ confidence=_score(ann),
318
+ )
319
+ )
320
+
321
+ if rle_count and unsupported_out is not None:
322
+ unsupported_out.append(
323
+ f"{rle_count} RLE/crowd segmentation(s) kept as bounding boxes only"
324
+ )
325
+
326
+ # Recover sizes the document omitted, so a YOLO export downstream is not
327
+ # left dividing by zero.
328
+ for annotation in by_image.values():
329
+ if (annotation.width <= 0 or annotation.height <= 0) and annotation.shapes:
330
+ annotation.width = max(s.bbox[2] for s in annotation.shapes) + 1
331
+ annotation.height = max(s.bbox[3] for s in annotation.shapes) + 1
332
+
333
+ return [by_image[k] for k in sorted(by_image, key=lambda k: by_image[k].filename)]
334
+
335
+
336
+ def _first_polygon(segmentation: list[Any]) -> list[Point] | None:
337
+ """Take the outer ring. Multi-part masks lose their holes, which is the
338
+ honest limit of a single-polygon model -- and what every VOC/YOLO consumer
339
+ downstream can represent anyway."""
340
+ for part in segmentation:
341
+ if isinstance(part, list) and len(part) >= 6:
342
+ values = [float(v) for v in part]
343
+ return [
344
+ (int(round(values[i])), int(round(values[i + 1])))
345
+ for i in range(0, len(values) - 1, 2)
346
+ ]
347
+ return None
348
+
349
+
350
+ def find_annotation_files(folder: Path) -> list[Path]:
351
+ """Locate COCO json files under the layouts exporters actually produce."""
352
+ candidates: list[Path] = []
353
+ for pattern in ("_annotations.coco.json", "instances*.json", "*.json"):
354
+ for path in sorted(folder.glob(pattern)):
355
+ if path.is_file() and path not in candidates:
356
+ candidates.append(path)
357
+ if candidates:
358
+ break
359
+ annotations_dir = folder / "annotations"
360
+ if annotations_dir.is_dir():
361
+ for path in sorted(annotations_dir.glob("*.json")):
362
+ if path not in candidates:
363
+ candidates.append(path)
364
+ return candidates
365
+
366
+
367
+ def summarise(coco: dict[str, Any]) -> dict[str, Any]:
368
+ """Headline numbers for an existing COCO file, including case collisions."""
369
+ categories: Iterable[dict[str, Any]] = coco.get("categories", [])
370
+ by_name = {c["id"]: c["name"] for c in categories}
371
+ counts: dict[str, int] = {}
372
+ segmented = 0
373
+ for ann in coco.get("annotations", []):
374
+ counts[by_name.get(ann.get("category_id"), "?")] = (
375
+ counts.get(by_name.get(ann.get("category_id"), "?"), 0) + 1
376
+ )
377
+ if ann.get("segmentation"):
378
+ segmented += 1
379
+
380
+ folded: dict[str, list[str]] = {}
381
+ for name in by_name.values():
382
+ folded.setdefault(name.strip().casefold(), []).append(name)
383
+ collisions = {k: sorted(v) for k, v in folded.items() if len(v) > 1}
384
+
385
+ image_ids_with_anns = {a.get("image_id") for a in coco.get("annotations", [])}
386
+ return {
387
+ "images": len(coco.get("images", [])),
388
+ "annotations": len(coco.get("annotations", [])),
389
+ "categories": len(by_name),
390
+ "per_category": dict(sorted(counts.items())),
391
+ "with_segmentation": segmented,
392
+ "background_images": len(coco.get("images", [])) - len(image_ids_with_anns),
393
+ "case_collisions": collisions,
394
+ }
@@ -0,0 +1,174 @@
1
+ """Flat CSV annotations -- one row per object.
2
+
3
+ Not a training format, a *working* format. A CSV opens in Excel, diffs in git,
4
+ and lets someone who does not write Python fix forty mislabelled boxes in two
5
+ minutes. Roboflow, TensorFlow's object-detection API and Keras-RetinaNet all
6
+ grew a CSV export for the same reason.
7
+
8
+ filename,width,height,class,xmin,ymin,xmax,ymax,polygon
9
+
10
+ ``polygon`` holds space-separated ``x y`` pairs and is blank for plain boxes,
11
+ so a detection-only dataset produces an unremarkable eight-column file.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import csv
17
+ import io
18
+ from collections.abc import Iterable, Sequence
19
+ from pathlib import Path
20
+
21
+ from ..fs import write_text_atomic
22
+ from .model import Annotation, AnnotationError, KINDS, Point, Shape
23
+
24
+ HEADER = ("filename", "width", "height", "class", "xmin", "ymin", "xmax", "ymax", "polygon", "kind")
25
+
26
+ #: Header spellings other tools use, mapped onto ours.
27
+ ALIASES = {
28
+ "image": "filename",
29
+ "image_name": "filename",
30
+ "image_id": "filename",
31
+ "name": "filename",
32
+ "label": "class",
33
+ "class_name": "class",
34
+ "category": "class",
35
+ "img_width": "width",
36
+ "img_height": "height",
37
+ "x_min": "xmin",
38
+ "y_min": "ymin",
39
+ "x_max": "xmax",
40
+ "y_max": "ymax",
41
+ "x1": "xmin",
42
+ "y1": "ymin",
43
+ "x2": "xmax",
44
+ "y2": "ymax",
45
+ "segmentation": "polygon",
46
+ }
47
+
48
+
49
+ def write(annotations: Iterable[Annotation], path: Path) -> Path:
50
+ """Write every object of every annotation as one row.
51
+
52
+ Background images get a row with an empty class, so a round trip does not
53
+ lose them -- an image absent from the CSV is indistinguishable from one
54
+ that was never annotated.
55
+ """
56
+ # Built in memory and written in one atomic swap, so a crash part-way
57
+ # through cannot leave a truncated CSV where a complete one used to be.
58
+ buffer = io.StringIO(newline="")
59
+ writer = csv.writer(buffer)
60
+ writer.writerow(HEADER)
61
+ for annotation in annotations:
62
+ if annotation.is_background:
63
+ writer.writerow(
64
+ [annotation.filename, annotation.width, annotation.height, "", "", "", "", "", "", ""]
65
+ )
66
+ continue
67
+ for shape in annotation.shapes:
68
+ polygon = ""
69
+ if shape.has_polygon or (shape.is_line and shape.polygon):
70
+ assert shape.polygon is not None
71
+ polygon = " ".join(f"{int(x)} {int(y)}" for x, y in shape.polygon)
72
+ writer.writerow(
73
+ [
74
+ annotation.filename,
75
+ annotation.width,
76
+ annotation.height,
77
+ shape.label,
78
+ *shape.bbox,
79
+ polygon,
80
+ shape.shape_kind,
81
+ ]
82
+ )
83
+ # newline="" because csv already emitted its own \r\n terminators.
84
+ return write_text_atomic(path, buffer.getvalue(), newline="")
85
+
86
+
87
+ def read(path: Path) -> list[Annotation]:
88
+ """Read a CSV back into one :class:`Annotation` per distinct filename."""
89
+ try:
90
+ text = path.read_text(encoding="utf-8-sig")
91
+ except OSError as exc:
92
+ raise AnnotationError(f"{path.name}: cannot read ({exc})") from exc
93
+
94
+ reader = csv.DictReader(text.splitlines())
95
+ if not reader.fieldnames:
96
+ raise AnnotationError(f"{path.name}: empty file")
97
+
98
+ columns = {_canonical(name): name for name in reader.fieldnames}
99
+ missing = {"filename", "class", "xmin", "ymin", "xmax", "ymax"} - set(columns)
100
+ if missing - {"class"}:
101
+ raise AnnotationError(
102
+ f"{path.name}: missing column(s) {', '.join(sorted(missing))}. "
103
+ f"Found: {', '.join(reader.fieldnames)}"
104
+ )
105
+
106
+ grouped: dict[str, Annotation] = {}
107
+ for number, row in enumerate(reader, start=2):
108
+ filename = (row.get(columns["filename"]) or "").strip()
109
+ if not filename:
110
+ continue
111
+ annotation = grouped.get(filename)
112
+ if annotation is None:
113
+ annotation = Annotation(
114
+ filename=filename,
115
+ width=_int(row.get(columns.get("width", ""), "")),
116
+ height=_int(row.get(columns.get("height", ""), "")),
117
+ source_path=path,
118
+ )
119
+ grouped[filename] = annotation
120
+
121
+ label = (row.get(columns.get("class", ""), "") or "").strip()
122
+ if not label:
123
+ continue # a background row: the image entry above is the point
124
+ try:
125
+ bbox = (
126
+ _int(row[columns["xmin"]]),
127
+ _int(row[columns["ymin"]]),
128
+ _int(row[columns["xmax"]]),
129
+ _int(row[columns["ymax"]]),
130
+ )
131
+ except (KeyError, ValueError) as exc:
132
+ raise AnnotationError(f"{path.name}:{number}: bad coordinates") from exc
133
+
134
+ kind = (row.get(columns.get("kind", ""), "") or "").strip().lower()
135
+ annotation.shapes.append(
136
+ Shape(
137
+ label=label,
138
+ bbox=bbox,
139
+ polygon=_parse_polygon(row.get(columns.get("polygon", ""), "")),
140
+ kind=kind if kind in KINDS else "",
141
+ )
142
+ )
143
+
144
+ for annotation in grouped.values():
145
+ if annotation.width <= 0 or annotation.height <= 0:
146
+ if annotation.shapes:
147
+ annotation.width = max(s.bbox[2] for s in annotation.shapes) + 1
148
+ annotation.height = max(s.bbox[3] for s in annotation.shapes) + 1
149
+
150
+ return [grouped[k] for k in sorted(grouped)]
151
+
152
+
153
+ def _canonical(name: str) -> str:
154
+ key = name.strip().lower().replace(" ", "_")
155
+ return ALIASES.get(key, key)
156
+
157
+
158
+ def _int(value: str | None) -> int:
159
+ if value is None or not str(value).strip():
160
+ return 0
161
+ return int(round(float(str(value).strip())))
162
+
163
+
164
+ def _parse_polygon(raw: str | None) -> list[Point] | None:
165
+ if not raw or not raw.strip():
166
+ return None
167
+ numbers: Sequence[str] = raw.replace(",", " ").split()
168
+ if len(numbers) < 6 or len(numbers) % 2:
169
+ return None
170
+ try:
171
+ values = [float(n) for n in numbers]
172
+ except ValueError:
173
+ return None
174
+ return [(int(round(values[i])), int(round(values[i + 1]))) for i in range(0, len(values), 2)]
@@ -0,0 +1,98 @@
1
+ """DOTA: rotated boxes as four corners, one ``.txt`` per image.
2
+
3
+ The aerial-imagery format, and what every rotated-box detector reads::
4
+
5
+ x1 y1 x2 y2 x3 y3 x4 y4 category difficult
6
+
7
+ Absolute pixels, corners in order around the box, class by *name* -- so unlike
8
+ YOLO there is no class list to lose. Files may start with ``imagesource:`` and
9
+ ``gsd:`` header lines, which are kept out of the way rather than rejected.
10
+
11
+ A rotated box is stored in the neutral model as a four-point polygon with
12
+ ``kind="obb"``; its axis-aligned ``bbox`` is derived, which is what lets a
13
+ rotated dataset still come out as plain YOLO or VOC boxes when asked.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from pathlib import Path
19
+
20
+ from ..fs import write_text_atomic
21
+ from .model import Annotation, AnnotationError, Point, Shape
22
+
23
+ HEADER_PREFIXES = ("imagesource:", "gsd:")
24
+
25
+
26
+ def read(path: Path, width: int, height: int, *, filename: str | None = None) -> Annotation:
27
+ shapes: list[Shape] = []
28
+ try:
29
+ text = path.read_text(encoding="utf-8")
30
+ except OSError as exc:
31
+ raise AnnotationError(f"{path.name}: cannot read ({exc})") from exc
32
+
33
+ for number, line in enumerate(text.splitlines(), start=1):
34
+ line = line.strip()
35
+ if not line or line.startswith(HEADER_PREFIXES):
36
+ continue
37
+ parts = line.split()
38
+ if len(parts) < 9:
39
+ raise AnnotationError(
40
+ f"{path.name}:{number}: expected 8 coordinates and a class, got {len(parts)} fields"
41
+ )
42
+ try:
43
+ values = [float(v) for v in parts[:8]]
44
+ except ValueError as exc:
45
+ raise AnnotationError(f"{path.name}:{number}: malformed coordinates") from exc
46
+ label = parts[8]
47
+ difficult = 0
48
+ if len(parts) > 9:
49
+ try:
50
+ difficult = 1 if int(float(parts[9])) else 0
51
+ except ValueError:
52
+ difficult = 0
53
+ shapes.append(corners_to_shape(label, values, difficult=difficult))
54
+
55
+ return Annotation(
56
+ filename=filename or path.with_suffix(".jpg").name,
57
+ width=width,
58
+ height=height,
59
+ shapes=shapes,
60
+ source_path=path,
61
+ )
62
+
63
+
64
+ def corners_to_shape(label: str, values: list[float], *, difficult: int = 0) -> Shape:
65
+ corners: list[Point] = [
66
+ (int(round(values[i])), int(round(values[i + 1]))) for i in range(0, 8, 2)
67
+ ]
68
+ xs = [p[0] for p in corners]
69
+ ys = [p[1] for p in corners]
70
+ return Shape(
71
+ label=label,
72
+ bbox=(min(xs), min(ys), max(xs), max(ys)),
73
+ polygon=corners,
74
+ difficult=difficult,
75
+ kind="obb",
76
+ )
77
+
78
+
79
+ def corners_of(shape: Shape) -> list[Point]:
80
+ """Four corners for any shape: its own if it is a rotated box, else the
81
+ corners of its axis-aligned box. A polygon that is not a rectangle is
82
+ written as its bounding box -- the honest rotated-box approximation is a
83
+ minimum-area rectangle, and that is a transformation the user should ask
84
+ for, not one a writer performs silently."""
85
+ if shape.shape_kind == "obb" and shape.polygon and len(shape.polygon) == 4:
86
+ return [(int(x), int(y)) for x, y in shape.polygon]
87
+ x1, y1, x2, y2 = shape.bbox
88
+ return [(x1, y1), (x2, y1), (x2, y2), (x1, y2)]
89
+
90
+
91
+ def write(annotation: Annotation, path: Path) -> Path:
92
+ lines = []
93
+ for shape in annotation.shapes:
94
+ if shape.shape_kind in ("point", "line"):
95
+ continue # nothing rotated-box shaped to say about these
96
+ coords = " ".join(f"{x} {y}" for x, y in corners_of(shape))
97
+ lines.append(f"{coords} {shape.label.replace(' ', '-')} {int(bool(shape.difficult))}")
98
+ return write_text_atomic(path, "\n".join(lines) + ("\n" if lines else ""))