easyannotate 0.4.0__tar.gz → 0.4.2__tar.gz

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 (152) hide show
  1. {easyannotate-0.4.0 → easyannotate-0.4.2}/.gitignore +4 -0
  2. {easyannotate-0.4.0 → easyannotate-0.4.2}/PKG-INFO +17 -12
  3. {easyannotate-0.4.0 → easyannotate-0.4.2}/README.md +16 -11
  4. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/review.py +2 -2
  5. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/tools/install.py +15 -0
  6. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/annotations/coco.py +154 -36
  7. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/annotations/csvfmt.py +10 -3
  8. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/annotations/dota.py +11 -6
  9. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/annotations/formats.py +344 -92
  10. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/annotations/labelme.py +46 -11
  11. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/annotations/voc.py +56 -35
  12. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/annotations/yolo.py +155 -17
  13. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/bktree.py +1 -1
  14. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/imaging.py +1 -1
  15. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/convert.py +47 -12
  16. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/dataset.py +1 -1
  17. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/export.py +2 -2
  18. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/report.py +8 -2
  19. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/writer.py +23 -7
  20. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/pipeline.py +1 -1
  21. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/app.js +60 -9
  22. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/assist.js +1 -1
  23. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/render.js +9 -0
  24. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/tools/box.js +1 -1
  25. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate.html +1 -0
  26. {easyannotate-0.4.0 → easyannotate-0.4.2}/pyproject.toml +1 -1
  27. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/conftest.py +1 -1
  28. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_annotate_editor.py +239 -0
  29. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_annotations.py +1 -1
  30. easyannotate-0.4.2/tests/test_converter_fixes.py +932 -0
  31. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_dataset_ops.py +9 -1
  32. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_exif.py +1 -1
  33. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_export_classes.py +23 -0
  34. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_formats.py +8 -3
  35. easyannotate-0.4.2/tests/test_install_clip.py +98 -0
  36. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_new_ops.py +58 -3
  37. {easyannotate-0.4.0 → easyannotate-0.4.2}/LICENSE +0 -0
  38. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/__init__.py +0 -0
  39. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/__main__.py +0 -0
  40. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/__init__.py +0 -0
  41. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/attach.py +0 -0
  42. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/demo.py +0 -0
  43. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/images.py +0 -0
  44. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/labels.py +0 -0
  45. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/loop.py +0 -0
  46. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/projects.py +0 -0
  47. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/schema.sql +0 -0
  48. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/shapes.py +0 -0
  49. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/store.py +0 -0
  50. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/tools/__init__.py +0 -0
  51. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/tools/fake.py +0 -0
  52. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/tools/local.py +0 -0
  53. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/tools/postprocess.py +0 -0
  54. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/tools/protocol.py +0 -0
  55. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/tools/registry.py +0 -0
  56. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/tools/results.py +0 -0
  57. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/annotate/tools/serve.py +0 -0
  58. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/cli/__init__.py +0 -0
  59. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/cli/main.py +0 -0
  60. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/cli/menu.py +0 -0
  61. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/cli/render.py +0 -0
  62. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/__init__.py +0 -0
  63. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/annotations/__init__.py +0 -0
  64. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/annotations/model.py +0 -0
  65. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/fs.py +0 -0
  66. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/__init__.py +0 -0
  67. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/analyze.py +0 -0
  68. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/annotate_export.py +0 -0
  69. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/audit.py +0 -0
  70. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/augment.py +0 -0
  71. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/collect.py +0 -0
  72. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/combine.py +0 -0
  73. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/dedup.py +0 -0
  74. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/image.py +0 -0
  75. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/labels.py +0 -0
  76. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/pairing.py +0 -0
  77. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/rename.py +0 -0
  78. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/ops/visualize.py +0 -0
  79. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/pairs.py +0 -0
  80. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/parallel.py +0 -0
  81. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/provenance.py +0 -0
  82. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/registry.py +0 -0
  83. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/stats.py +0 -0
  84. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/core/types.py +0 -0
  85. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/desktop.py +0 -0
  86. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/hardware.py +0 -0
  87. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/py.typed +0 -0
  88. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/__init__.py +0 -0
  89. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/app.py +0 -0
  90. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/binding.py +0 -0
  91. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/deps.py +0 -0
  92. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/jobs.py +0 -0
  93. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/limits.py +0 -0
  94. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/routers/__init__.py +0 -0
  95. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/routers/annotate.py +0 -0
  96. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/routers/local.py +0 -0
  97. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/routers/media.py +0 -0
  98. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/routers/predictions.py +0 -0
  99. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/routers/promote.py +0 -0
  100. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/routers/tools.py +0 -0
  101. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/api.js +0 -0
  102. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/filmstrip.js +0 -0
  103. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/hit.js +0 -0
  104. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/labels.js +0 -0
  105. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/scene.js +0 -0
  106. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/shapelist.js +0 -0
  107. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/tools/line.js +0 -0
  108. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/tools/obb.js +0 -0
  109. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/tools/point.js +0 -0
  110. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/tools/polygon.js +0 -0
  111. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/tools/select.js +0 -0
  112. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/undo.js +0 -0
  113. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/annotate/viewport.js +0 -0
  114. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/static/index.html +0 -0
  115. {easyannotate-0.4.0 → easyannotate-0.4.2}/data_factory/service/workspace.py +0 -0
  116. {easyannotate-0.4.0 → easyannotate-0.4.2}/easyannotate/__init__.py +0 -0
  117. {easyannotate-0.4.0 → easyannotate-0.4.2}/easyannotate/__main__.py +0 -0
  118. {easyannotate-0.4.0 → easyannotate-0.4.2}/easyannotate/project.py +0 -0
  119. {easyannotate-0.4.0 → easyannotate-0.4.2}/easyannotate/py.typed +0 -0
  120. {easyannotate-0.4.0 → easyannotate-0.4.2}/examples/web_api.py +0 -0
  121. {easyannotate-0.4.0 → easyannotate-0.4.2}/recipes/model_loop.yaml +0 -0
  122. {easyannotate-0.4.0 → easyannotate-0.4.2}/recipes/train_ready_yolo.yaml +0 -0
  123. {easyannotate-0.4.0 → easyannotate-0.4.2}/recipes/voc_to_coco.yaml +0 -0
  124. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/fake_trainer.py +0 -0
  125. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_annotate_api.py +0 -0
  126. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_annotate_attach.py +0 -0
  127. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_annotate_store.py +0 -0
  128. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_clean_ops.py +0 -0
  129. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_compat.py +0 -0
  130. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_core.py +0 -0
  131. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_demo.py +0 -0
  132. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_desktop.py +0 -0
  133. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_imaging.py +0 -0
  134. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_infra.py +0 -0
  135. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_kinds.py +0 -0
  136. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_local_link.py +0 -0
  137. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_loop.py +0 -0
  138. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_pipeline_cli.py +0 -0
  139. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_postprocess.py +0 -0
  140. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_public_api.py +0 -0
  141. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_review.py +0 -0
  142. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_review_b_findings.py +0 -0
  143. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_review_c_findings.py +0 -0
  144. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_review_d_findings.py +0 -0
  145. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_review_queue.py +0 -0
  146. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_service.py +0 -0
  147. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_sidecar.py +0 -0
  148. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_tools.py +0 -0
  149. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_tools_api.py +0 -0
  150. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_tools_batch.py +0 -0
  151. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_trust.py +0 -0
  152. {easyannotate-0.4.0 → easyannotate-0.4.2}/tests/test_wire.py +0 -0
@@ -15,6 +15,10 @@ Models/
15
15
  *.mp4
16
16
  *.avi
17
17
  *.mov
18
+ # Except the demo's own media: CC0 photos and the recording made from them.
19
+ !docs/demo_photos/*.jpg
20
+ !docs/demo.mp4
21
+ !docs/segmentation.mp4
18
22
 
19
23
  # ── Python ────────────────────────────────────────────────────────────────
20
24
  .venv/
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: easyannotate
3
- Version: 0.4.0
3
+ Version: 0.4.2
4
4
  Summary: Image annotation with nothing to set up: draw, review model predictions fast, export a correct dataset
5
5
  Project-URL: Homepage, https://shivpratapsinghpanwar.github.io/EasyAnnotate/
6
6
  Project-URL: Source, https://github.com/shivpratapsinghpanwar/EasyAnnotate
@@ -49,7 +49,7 @@ Description-Content-Type: text/markdown
49
49
 
50
50
  # EasyAnnotate
51
51
 
52
- ![EasyAnnotate: draw, name a class, review a model's predictions, export](https://raw.githubusercontent.com/shivpratapsinghpanwar/EasyAnnotate/main/docs/demo.gif)
52
+ ![EasyAnnotate on real photos: draw a box, outline with SAM, find every person, dog and car with a text prompt, review least sure first](https://raw.githubusercontent.com/shivpratapsinghpanwar/EasyAnnotate/main/docs/demo.gif)
53
53
 
54
54
  **Image annotation with nothing to set up.** Open a folder, draw a box, type a
55
55
  class name — that is the whole workflow. Load a model's predictions and review
@@ -120,7 +120,7 @@ What you get instead:
120
120
  arrives as a prediction to review, dashed, with a confidence slider and one
121
121
  key to accept. The models run in their own environment, so the editor's
122
122
  install never depends on PyTorch, and without them it works unchanged.
123
- - **Dataset tooling built in.** 28 operations — convert between five formats,
123
+ - **Dataset tooling built in.** 28 operations — convert between six formats,
124
124
  find duplicates and train/val leakage, health reports, augmentation that
125
125
  moves the labels with the pixels — one `pip install` away.
126
126
 
@@ -339,9 +339,11 @@ easyannotate tools install --cpu # skip the GPU build
339
339
  easyannotate tools status # what this machine gets, and what is installed
340
340
  ```
341
341
 
342
- From a source checkout, before the first PyPI release:
343
- `easyannotate tools install --source .` The desktop app has the same thing
344
- as an "Install AI tools" button.
342
+ The tools come from PyPI as
343
+ [`easyannotate-tools`](https://pypi.org/project/easyannotate-tools/), pinned
344
+ to your `easyannotate` version. From a source checkout,
345
+ `easyannotate tools install --source .` installs your working copy instead.
346
+ The desktop app has the same thing as an "Install AI tools" button.
345
347
 
346
348
  The installer reads the GPU, its memory and its driver. NVIDIA cards get the
347
349
  PyTorch CUDA build their driver was made for (12.8 or 12.6; PyTorch 2.7 with
@@ -356,6 +358,9 @@ Then the Assist panel appears in the editor:
356
358
 
357
359
  - **Outline (SAM)** — drag a box, or click, on an object: SAM 2.1 traces it
358
360
  and you get a simplified polygon with draggable vertices.
361
+
362
+ ![Segmentation with SAM 2.1: a car from one rough box, three dogs from one click each, three people from a box each, every one a filled mask](https://raw.githubusercontent.com/shivpratapsinghpanwar/EasyAnnotate/main/docs/segmentation.gif)
363
+
359
364
  - **Find every…** — type a class name (or several: `door, handle`) and run it
360
365
  on this image, or on *every unreviewed image* as a job. The results are
361
366
  predictions: dashed, scored, filtered by the slider, accepted with `A`,
@@ -485,8 +490,8 @@ remembers to do.
485
490
  preview is a faithful description of the real run, not an approximation.
486
491
 
487
492
  **Formats meet in the middle.** Readers parse into a neutral `Annotation`;
488
- writers serialise out of it. Five formats cost five readers and five writers,
489
- not twenty converters. Adding CreateML is one file, and it converts to and from
493
+ writers serialise out of it. Six formats cost six readers and six writers,
494
+ not thirty converters. Adding CreateML is one file, and it converts to and from
490
495
  everything already here.
491
496
 
492
497
  **Geometry is solved once.** Resize, tile and augment share one transform layer.
@@ -503,7 +508,7 @@ consumer; a web API is another.
503
508
 
504
509
  ## What it catches
505
510
 
506
- Run on the real Project_Door V3 set (3,686 images, 3,871 objects):
511
+ Run on the real door dataset, V3 (3,686 images, 3,871 objects):
507
512
 
508
513
  ```
509
514
  $ easyannotate inspect.health --folder ./pascal_voc
@@ -631,7 +636,7 @@ downloads); `easyannotate train` on 4 reviewed images, 3 epochs, then
631
636
  predicting 20 more: 16 s end to end.
632
637
 
633
638
  Decode-bound stages run across threads, in input order, so results stay
634
- reproducible. Measured on the real Project_Door set:
639
+ reproducible. Measured on the real door dataset:
635
640
 
636
641
  | Stage | Serial | Parallel | |
637
642
  |---|---|---|---|
@@ -715,7 +720,7 @@ not batch operations.
715
720
 
716
721
  - **COCO exported four classes where there were two.** Categories were keyed on
717
722
  the raw XML string, so `Open` and `open` became separate classes — splitting
718
- Project_Door V3 as 1341/1385/645/500. Export now folds case by default and
723
+ the door dataset's V3 as 1341/1385/645/500. Export now folds case by default and
719
724
  *reports* every merge; `labels.rename --fold-case` fixes it at the source, and
720
725
  `inspect.health` now flags it as an error before you get that far.
721
726
  - **SAM polygons exported as empty masks.** The two annotation tools write
@@ -762,6 +767,6 @@ landed, which is the failure that silently ruins a dataset.
762
767
 
763
768
  ## Datasets in this repository
764
769
 
765
- `Projects/Project_Door/` holds the door-state dataset (V3: 3686 images, 3871
770
+ `Projects/` holds the door-state dataset (V3: 3686 images, 3871
766
771
  objects) and `Models/Sam2.1_tiny/` the SAM 2.1 tiny checkpoint. Neither is
767
772
  tracked by git.
@@ -1,6 +1,6 @@
1
1
  # EasyAnnotate
2
2
 
3
- ![EasyAnnotate: draw, name a class, review a model's predictions, export](https://raw.githubusercontent.com/shivpratapsinghpanwar/EasyAnnotate/main/docs/demo.gif)
3
+ ![EasyAnnotate on real photos: draw a box, outline with SAM, find every person, dog and car with a text prompt, review least sure first](https://raw.githubusercontent.com/shivpratapsinghpanwar/EasyAnnotate/main/docs/demo.gif)
4
4
 
5
5
  **Image annotation with nothing to set up.** Open a folder, draw a box, type a
6
6
  class name — that is the whole workflow. Load a model's predictions and review
@@ -71,7 +71,7 @@ What you get instead:
71
71
  arrives as a prediction to review, dashed, with a confidence slider and one
72
72
  key to accept. The models run in their own environment, so the editor's
73
73
  install never depends on PyTorch, and without them it works unchanged.
74
- - **Dataset tooling built in.** 28 operations — convert between five formats,
74
+ - **Dataset tooling built in.** 28 operations — convert between six formats,
75
75
  find duplicates and train/val leakage, health reports, augmentation that
76
76
  moves the labels with the pixels — one `pip install` away.
77
77
 
@@ -290,9 +290,11 @@ easyannotate tools install --cpu # skip the GPU build
290
290
  easyannotate tools status # what this machine gets, and what is installed
291
291
  ```
292
292
 
293
- From a source checkout, before the first PyPI release:
294
- `easyannotate tools install --source .` The desktop app has the same thing
295
- as an "Install AI tools" button.
293
+ The tools come from PyPI as
294
+ [`easyannotate-tools`](https://pypi.org/project/easyannotate-tools/), pinned
295
+ to your `easyannotate` version. From a source checkout,
296
+ `easyannotate tools install --source .` installs your working copy instead.
297
+ The desktop app has the same thing as an "Install AI tools" button.
296
298
 
297
299
  The installer reads the GPU, its memory and its driver. NVIDIA cards get the
298
300
  PyTorch CUDA build their driver was made for (12.8 or 12.6; PyTorch 2.7 with
@@ -307,6 +309,9 @@ Then the Assist panel appears in the editor:
307
309
 
308
310
  - **Outline (SAM)** — drag a box, or click, on an object: SAM 2.1 traces it
309
311
  and you get a simplified polygon with draggable vertices.
312
+
313
+ ![Segmentation with SAM 2.1: a car from one rough box, three dogs from one click each, three people from a box each, every one a filled mask](https://raw.githubusercontent.com/shivpratapsinghpanwar/EasyAnnotate/main/docs/segmentation.gif)
314
+
310
315
  - **Find every…** — type a class name (or several: `door, handle`) and run it
311
316
  on this image, or on *every unreviewed image* as a job. The results are
312
317
  predictions: dashed, scored, filtered by the slider, accepted with `A`,
@@ -436,8 +441,8 @@ remembers to do.
436
441
  preview is a faithful description of the real run, not an approximation.
437
442
 
438
443
  **Formats meet in the middle.** Readers parse into a neutral `Annotation`;
439
- writers serialise out of it. Five formats cost five readers and five writers,
440
- not twenty converters. Adding CreateML is one file, and it converts to and from
444
+ writers serialise out of it. Six formats cost six readers and six writers,
445
+ not thirty converters. Adding CreateML is one file, and it converts to and from
441
446
  everything already here.
442
447
 
443
448
  **Geometry is solved once.** Resize, tile and augment share one transform layer.
@@ -454,7 +459,7 @@ consumer; a web API is another.
454
459
 
455
460
  ## What it catches
456
461
 
457
- Run on the real Project_Door V3 set (3,686 images, 3,871 objects):
462
+ Run on the real door dataset, V3 (3,686 images, 3,871 objects):
458
463
 
459
464
  ```
460
465
  $ easyannotate inspect.health --folder ./pascal_voc
@@ -582,7 +587,7 @@ downloads); `easyannotate train` on 4 reviewed images, 3 epochs, then
582
587
  predicting 20 more: 16 s end to end.
583
588
 
584
589
  Decode-bound stages run across threads, in input order, so results stay
585
- reproducible. Measured on the real Project_Door set:
590
+ reproducible. Measured on the real door dataset:
586
591
 
587
592
  | Stage | Serial | Parallel | |
588
593
  |---|---|---|---|
@@ -666,7 +671,7 @@ not batch operations.
666
671
 
667
672
  - **COCO exported four classes where there were two.** Categories were keyed on
668
673
  the raw XML string, so `Open` and `open` became separate classes — splitting
669
- Project_Door V3 as 1341/1385/645/500. Export now folds case by default and
674
+ the door dataset's V3 as 1341/1385/645/500. Export now folds case by default and
670
675
  *reports* every merge; `labels.rename --fold-case` fixes it at the source, and
671
676
  `inspect.health` now flags it as an error before you get that far.
672
677
  - **SAM polygons exported as empty masks.** The two annotation tools write
@@ -713,6 +718,6 @@ landed, which is the failure that silently ruins a dataset.
713
718
 
714
719
  ## Datasets in this repository
715
720
 
716
- `Projects/Project_Door/` holds the door-state dataset (V3: 3686 images, 3871
721
+ `Projects/` holds the door-state dataset (V3: 3686 images, 3871
717
722
  objects) and `Models/Sam2.1_tiny/` the SAM 2.1 tiny checkpoint. Neither is
718
723
  tracked by git.
@@ -90,7 +90,7 @@ def read_predictions(
90
90
  if not candidate.is_file():
91
91
  continue
92
92
  try:
93
- document = json.loads(candidate.read_text(encoding="utf-8"))
93
+ document = json.loads(candidate.read_text(encoding="utf-8-sig"))
94
94
  except (OSError, ValueError):
95
95
  continue
96
96
  if coco_fmt.is_detection_results(document):
@@ -203,7 +203,7 @@ def _read_json(
203
203
  path: Path, project_classes: list[str] | None, notes: list[str]
204
204
  ) -> tuple[list[Annotation], list[str]]:
205
205
  try:
206
- document = json.loads(path.read_text(encoding="utf-8"))
206
+ document = json.loads(path.read_text(encoding="utf-8-sig"))
207
207
  except (OSError, ValueError) as exc:
208
208
  raise ReviewError(f"{path.name}: not readable JSON ({exc})") from exc
209
209
 
@@ -40,6 +40,13 @@ from .local import child_environment, python_for_tools
40
40
  PROFILE = "profile.json"
41
41
  PYTHON_VERSION = "3.12"
42
42
 
43
+ #: YOLO-World's text encoder. Ultralytics installs it on first use, with git;
44
+ #: measured on a fresh install from PyPI with no git on PATH, that failed and
45
+ #: text prompts said "No module named 'clip'". The app's environment has no
46
+ #: pip for it either. So the installer brings it: a GitHub archive, which
47
+ #: needs no git, pinned to one commit.
48
+ CLIP = "clip @ https://github.com/ultralytics/CLIP/archive/7ffa84b3bfa40c42ecc1c77147a855e69cb2dd40.zip"
49
+
43
50
  #: Run in the new environment. Real work on the device, not
44
51
  #: torch.cuda.is_available(): measured on a 529 driver with the cu126 build,
45
52
  #: that said True while every allocation failed ("device busy or unavailable").
@@ -205,6 +212,14 @@ def install(
205
212
  packages = [f"easyannotate-tools=={__version__}"]
206
213
  on_line("installing the EasyAnnotate tools and Ultralytics")
207
214
  run(pip + packages)
215
+ # A step of its own: a network that reaches PyPI but not github.com then
216
+ # loses text prompts, not the whole install.
217
+ on_line("installing CLIP for text prompts, from github.com")
218
+ try:
219
+ run(pip + [CLIP])
220
+ except InstallError:
221
+ on_line("warning: CLIP did not install (is github.com reachable?) -- "
222
+ "outlines work; text prompts will not until a reinstall")
208
223
 
209
224
  profile = {
210
225
  "device": chosen.device,
@@ -3,7 +3,7 @@
3
3
  The category handling here is deliberate. The original converter keyed
4
4
  categories on the raw XML string, so a dataset whose labels drifted between
5
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).
6
+ happened to the door dataset's V3 (Close/Open/open/close split 1341/1385/645/500).
7
7
  The builder now folds case by default and reports every merge it made, so the
8
8
  drift is fixed *and* visible rather than silently baked into the export.
9
9
  """
@@ -70,16 +70,21 @@ class CocoBuilder:
70
70
 
71
71
  def __init__(
72
72
  self,
73
- description: str = "Data Factory export",
73
+ description: str = "EasyAnnotate export",
74
74
  version: str = "1.0",
75
75
  case_policy: str = "casefold",
76
76
  label_map: dict[str, str] | None = None,
77
+ categories: CategoryTable | None = None,
77
78
  ) -> None:
78
79
  if case_policy not in CASE_POLICIES:
79
80
  raise ValueError(f"case_policy must be one of {CASE_POLICIES}")
80
81
  self.description = description
81
82
  self.version = version
82
- self.categories = CategoryTable(case_policy=case_policy, label_map=label_map or {})
83
+ # A dataset written as several files (one per split) passes the same
84
+ # table to each builder, so an id names the same class in all of them.
85
+ self.categories = categories or CategoryTable(
86
+ case_policy=case_policy, label_map=label_map or {}
87
+ )
83
88
  self.images: list[dict[str, Any]] = []
84
89
  self.annotations: list[dict[str, Any]] = []
85
90
  self.background_images = 0
@@ -119,6 +124,10 @@ class CocoBuilder:
119
124
  "area": round(shape.polygon_area(), 2),
120
125
  "iscrowd": 0,
121
126
  }
127
+ # Written only when there is one, as the VOC writer does, so a
128
+ # hand-drawn label is unchanged. The reader has always read it back.
129
+ if shape.confidence is not None:
130
+ entry["score"] = round(float(shape.confidence), 6)
122
131
  if shape.is_point:
123
132
  # COCO has no point type; a visible keypoint with a one-pixel box
124
133
  # is the form its keypoint evaluators and viewers both accept.
@@ -140,7 +149,7 @@ class CocoBuilder:
140
149
 
141
150
  def write(self, path: Path) -> Path:
142
151
  path.parent.mkdir(parents=True, exist_ok=True)
143
- write_text_atomic(path, json.dumps(self.build(), indent=2))
152
+ write_text_atomic(path, json.dumps(self.build(), indent=2), newline="\n")
144
153
  return path
145
154
 
146
155
  def stats(self) -> dict[str, int]:
@@ -152,9 +161,45 @@ class CocoBuilder:
152
161
  }
153
162
 
154
163
 
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"))
164
+ def load(path: Path) -> Any:
165
+ """Read an existing instances.json.
166
+
167
+ A file that is not JSON raises :class:`AnnotationError` naming it, like
168
+ every other reader here -- a truncated download is a normal thing to be
169
+ handed, and a ``JSONDecodeError`` traceback tells nobody which file.
170
+ """
171
+ path = Path(path)
172
+ try:
173
+ # utf-8-sig: a byte order mark at the start is not part of the JSON.
174
+ return json.loads(path.read_text(encoding="utf-8-sig"))
175
+ except OSError as exc:
176
+ raise AnnotationError(f"{path.name}: cannot read ({exc})") from exc
177
+ except ValueError as exc:
178
+ raise AnnotationError(f"{path.name}: cannot parse ({exc})") from exc
179
+
180
+
181
+ def _entries(coco: dict[str, Any], key: str) -> list[Any]:
182
+ """One of the document's three lists; absent is empty, anything else is
183
+ not a COCO document."""
184
+ value = coco.get(key)
185
+ if value is None:
186
+ return []
187
+ if not isinstance(value, list):
188
+ raise AnnotationError(f"'{key}' must be a list, got {type(value).__name__}")
189
+ return value
190
+
191
+
192
+ def _dimension(value: Any) -> int:
193
+ """An image width or height, or 0 when the entry holds no usable one."""
194
+ try:
195
+ return max(0, int(float(value or 0)))
196
+ except (TypeError, ValueError, OverflowError):
197
+ return 0
198
+
199
+
200
+ def _usable_id(entry: Any) -> bool:
201
+ """Whether an image or category entry can be referred to at all."""
202
+ return isinstance(entry, dict) and isinstance(entry.get("id"), (int, float, str))
158
203
 
159
204
 
160
205
  def _score(ann: dict[str, Any]) -> float | None:
@@ -168,6 +213,23 @@ def _score(ann: dict[str, Any]) -> float | None:
168
213
  return None
169
214
 
170
215
 
216
+ def is_dataset(document: Any) -> bool:
217
+ """Whether a parsed JSON document is a COCO dataset.
218
+
219
+ Judged by its own top-level keys: an object holding an ``images``,
220
+ ``annotations`` or ``categories`` list, and no ``shapes`` (which is what a
221
+ LabelMe file has). Looking for those words in the first few kilobytes of
222
+ text instead got it wrong both ways -- a file whose ``images`` list came
223
+ first and ran past the window was not COCO, and a LabelMe file with a
224
+ class called "categories" was.
225
+ """
226
+ return (
227
+ isinstance(document, dict)
228
+ and "shapes" not in document
229
+ and any(isinstance(document.get(key), list) for key in ("images", "annotations", "categories"))
230
+ )
231
+
232
+
171
233
  def is_detection_results(document: Any) -> bool:
172
234
  """Whether this is the *detection results* form rather than a dataset.
173
235
 
@@ -272,45 +334,77 @@ def to_annotations(
272
334
  f"a COCO document must be an object, got {type(coco).__name__}"
273
335
  )
274
336
 
275
- names = {c["id"]: str(c.get("name", f"class_{c['id']}")) for c in coco.get("categories", [])}
276
- by_image: dict[int, Annotation] = {}
337
+ names = {
338
+ c["id"]: str(c.get("name", f"class_{c['id']}"))
339
+ for c in _entries(coco, "categories")
340
+ if _usable_id(c)
341
+ }
342
+ by_image: dict[Any, Annotation] = {}
277
343
 
278
- for image in coco.get("images", []):
344
+ for image in _entries(coco, "images"):
345
+ if not _usable_id(image):
346
+ continue
279
347
  by_image[image["id"]] = Annotation(
280
348
  filename=Path(str(image.get("file_name", ""))).name,
281
- width=int(image.get("width") or 0),
282
- height=int(image.get("height") or 0),
349
+ width=_dimension(image.get("width")),
350
+ height=_dimension(image.get("height")),
283
351
  shapes=[],
284
352
  )
285
353
 
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:
354
+ rle_count = orphans = unusable = in_parts = 0
355
+ for ann in _entries(coco, "annotations"):
356
+ if not isinstance(ann, dict):
357
+ unusable += 1
290
358
  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):
359
+ image_id = ann.get("image_id")
360
+ annotation = by_image.get(image_id) if isinstance(image_id, (int, float, str)) else None
361
+ if annotation is None:
362
+ orphans += 1
295
363
  continue
296
364
 
297
365
  segmentation = ann.get("segmentation")
298
366
  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:
367
+ is_mask = isinstance(segmentation, dict) or bool(ann.get("iscrowd"))
368
+ if not is_mask and isinstance(segmentation, list) and segmentation:
302
369
  polygon = _first_polygon(segmentation)
303
370
 
371
+ box = _box(ann.get("bbox"))
372
+ if box is None and polygon:
373
+ # No usable bbox, but an outline: the box is the outline's own.
374
+ xs, ys = [p[0] for p in polygon], [p[1] for p in polygon]
375
+ box = (min(xs), min(ys), max(xs), max(ys))
376
+ if box is None:
377
+ unusable += 1
378
+ continue
379
+ if is_mask:
380
+ rle_count += 1
381
+ elif polygon and sum(1 for part in segmentation if _is_ring(part)) > 1:
382
+ in_parts += 1
383
+
384
+ kind = ""
385
+ keypoints = ann.get("keypoints")
386
+ if (
387
+ polygon is None
388
+ and isinstance(keypoints, list)
389
+ and len(keypoints) == 3
390
+ and box[2] - box[0] <= 1
391
+ and box[3] - box[1] <= 1
392
+ ):
393
+ # One keypoint in a one-pixel box is how the writer here stores a
394
+ # point; read it back as the point it was, not as a tiny box.
395
+ point = _box([keypoints[0], keypoints[1], 0, 0])
396
+ if point is not None:
397
+ box, kind = point, "point"
398
+
399
+ category = ann.get("category_id")
304
400
  annotation.shapes.append(
305
401
  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
- ),
402
+ label=names.get(category, f"class_{category}")
403
+ if isinstance(category, (int, float, str))
404
+ else f"class_{category}",
405
+ bbox=box,
313
406
  polygon=polygon,
407
+ kind=kind,
314
408
  # 'score' is what every detector writes and no ground-truth
315
409
  # file has. Carrying it is what lets the review layer tell a
316
410
  # prediction from a label rather than trusting a filename.
@@ -318,10 +412,17 @@ def to_annotations(
318
412
  )
319
413
  )
320
414
 
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"
415
+ if unsupported_out is not None:
416
+ counted = (
417
+ (rle_count, "RLE/crowd segmentation(s) kept as bounding boxes only"),
418
+ (orphans, "annotation(s) name an image that is not in 'images' and were skipped"),
419
+ (unusable, "annotation(s) have no usable bbox or outline and were skipped"),
420
+ (
421
+ in_parts,
422
+ "object(s) have an outline in several parts; only the first part of each was kept",
423
+ ),
324
424
  )
425
+ unsupported_out.extend(f"{count} {text}" for count, text in counted if count)
325
426
 
326
427
  # Recover sizes the document omitted, so a YOLO export downstream is not
327
428
  # left dividing by zero.
@@ -333,13 +434,29 @@ def to_annotations(
333
434
  return [by_image[k] for k in sorted(by_image, key=lambda k: by_image[k].filename)]
334
435
 
335
436
 
437
+ def _box(raw: Any) -> tuple[int, int, int, int] | None:
438
+ """A COCO ``[x, y, width, height]`` as corners, or ``None`` if it is not one."""
439
+ try:
440
+ x, y, w, h = (float(v) for v in raw[:4])
441
+ return int(round(x)), int(round(y)), int(round(x + w)), int(round(y + h))
442
+ except (TypeError, ValueError, OverflowError):
443
+ return None
444
+
445
+
446
+ def _is_ring(part: Any) -> bool:
447
+ return isinstance(part, list) and len(part) >= 6
448
+
449
+
336
450
  def _first_polygon(segmentation: list[Any]) -> list[Point] | None:
337
451
  """Take the outer ring. Multi-part masks lose their holes, which is the
338
452
  honest limit of a single-polygon model -- and what every VOC/YOLO consumer
339
453
  downstream can represent anyway."""
340
454
  for part in segmentation:
341
455
  if isinstance(part, list) and len(part) >= 6:
342
- values = [float(v) for v in part]
456
+ try:
457
+ values = [float(v) for v in part]
458
+ except (TypeError, ValueError):
459
+ continue
343
460
  return [
344
461
  (int(round(values[i])), int(round(values[i + 1])))
345
462
  for i in range(0, len(values) - 1, 2)
@@ -351,14 +468,15 @@ def find_annotation_files(folder: Path) -> list[Path]:
351
468
  """Locate COCO json files under the layouts exporters actually produce."""
352
469
  candidates: list[Path] = []
353
470
  for pattern in ("_annotations.coco.json", "instances*.json", "*.json"):
354
- for path in sorted(folder.glob(pattern)):
471
+ # By name as text: Path objects sort without regard to case on Windows.
472
+ for path in sorted(folder.glob(pattern), key=lambda p: p.name):
355
473
  if path.is_file() and path not in candidates:
356
474
  candidates.append(path)
357
475
  if candidates:
358
476
  break
359
477
  annotations_dir = folder / "annotations"
360
478
  if annotations_dir.is_dir():
361
- for path in sorted(annotations_dir.glob("*.json")):
479
+ for path in sorted(annotations_dir.glob("*.json"), key=lambda p: p.name):
362
480
  if path not in candidates:
363
481
  candidates.append(path)
364
482
  return candidates
@@ -87,11 +87,17 @@ def write(annotations: Iterable[Annotation], path: Path) -> Path:
87
87
  def read(path: Path) -> list[Annotation]:
88
88
  """Read a CSV back into one :class:`Annotation` per distinct filename."""
89
89
  try:
90
- text = path.read_text(encoding="utf-8-sig")
90
+ # newline="" hands the csv module the file as it is, which is what it
91
+ # asks for: a quoted field may hold a line break, and splitting the
92
+ # text into lines first cut such a row in two.
93
+ with path.open(encoding="utf-8-sig", newline="") as handle:
94
+ text = handle.read()
91
95
  except OSError as exc:
92
96
  raise AnnotationError(f"{path.name}: cannot read ({exc})") from exc
97
+ except UnicodeDecodeError as exc:
98
+ raise AnnotationError(f"{path.name}: not UTF-8 text ({exc})") from exc
93
99
 
94
- reader = csv.DictReader(text.splitlines())
100
+ reader = csv.DictReader(io.StringIO(text, newline=""))
95
101
  if not reader.fieldnames:
96
102
  raise AnnotationError(f"{path.name}: empty file")
97
103
 
@@ -165,7 +171,8 @@ def _parse_polygon(raw: str | None) -> list[Point] | None:
165
171
  if not raw or not raw.strip():
166
172
  return None
167
173
  numbers: Sequence[str] = raw.replace(",", " ").split()
168
- if len(numbers) < 6 or len(numbers) % 2:
174
+ # Two points are enough: that is a line, and the writer emits it.
175
+ if len(numbers) < 4 or len(numbers) % 2:
169
176
  return None
170
177
  try:
171
178
  values = [float(n) for n in numbers]
@@ -19,16 +19,14 @@ from pathlib import Path
19
19
 
20
20
  from ..fs import write_text_atomic
21
21
  from .model import Annotation, AnnotationError, Point, Shape
22
+ from .yolo import read_label_text
22
23
 
23
24
  HEADER_PREFIXES = ("imagesource:", "gsd:")
24
25
 
25
26
 
26
27
  def read(path: Path, width: int, height: int, *, filename: str | None = None) -> Annotation:
27
28
  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
29
+ text = read_label_text(path)
32
30
 
33
31
  for number, line in enumerate(text.splitlines(), start=1):
34
32
  line = line.strip()
@@ -88,11 +86,18 @@ def corners_of(shape: Shape) -> list[Point]:
88
86
  return [(x1, y1), (x2, y1), (x2, y2), (x1, y2)]
89
87
 
90
88
 
89
+ def class_name(label: str) -> str:
90
+ """A class name as DOTA can hold it. Fields are separated by spaces, so a
91
+ space inside a name would split it; it is written as a hyphen instead.
92
+ The converter reports every name this changes."""
93
+ return label.replace(" ", "-")
94
+
95
+
91
96
  def write(annotation: Annotation, path: Path) -> Path:
92
97
  lines = []
93
98
  for shape in annotation.shapes:
94
99
  if shape.shape_kind in ("point", "line"):
95
100
  continue # nothing rotated-box shaped to say about these
96
101
  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 ""))
102
+ lines.append(f"{coords} {class_name(shape.label)} {int(bool(shape.difficult))}")
103
+ return write_text_atomic(path, "\n".join(lines) + ("\n" if lines else ""), newline="\n")