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,837 @@
1
+ """The command line, generated from the operation registry.
2
+
3
+ Every subcommand and every flag below is derived from what an operation
4
+ declares about itself. Nothing here knows what dedup or splitting actually do,
5
+ which is why adding an operation never means editing this file.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import argparse
11
+ import json
12
+ import sys
13
+ import time
14
+ from collections.abc import Sequence
15
+ from pathlib import Path
16
+ from typing import Any, TextIO
17
+
18
+ from .. import __version__
19
+ from ..core import (
20
+ ops, # noqa: F401 -- imported for registration side effects
21
+ registry,
22
+ )
23
+ from ..core.registry import Operation, ParamError
24
+ from ..core.types import Cancelled, Context
25
+ from . import render
26
+
27
+ PROGRAM = "easyannotate"
28
+
29
+
30
+ def build_parser() -> argparse.ArgumentParser:
31
+ parser = argparse.ArgumentParser(
32
+ prog=PROGRAM,
33
+ description=(
34
+ "EasyAnnotate -- annotate images with nothing to set up first, review a "
35
+ "model's predictions fast, and get a dataset out that is correct. "
36
+ f"Try '{PROGRAM} demo'. Run '{PROGRAM}' with no arguments for a menu."
37
+ ),
38
+ formatter_class=argparse.RawDescriptionHelpFormatter,
39
+ epilog=(
40
+ "examples:\n"
41
+ f" {PROGRAM} demo\n"
42
+ f" {PROGRAM} annotate ./my-images\n"
43
+ f" {PROGRAM} inspect.dataset --folder ./data\n"
44
+ f" {PROGRAM} clean.dedup --folders ./a ./b --method phash --dry-run\n"
45
+ f" {PROGRAM} export.coco --folder ./voc --output ./coco\n"
46
+ f" {PROGRAM} run recipes/door.yaml\n"
47
+ ),
48
+ )
49
+ parser.add_argument("--version", action="version", version=f"{PROGRAM} {__version__}")
50
+ subparsers = parser.add_subparsers(dest="command")
51
+
52
+ listing = subparsers.add_parser("list", help="list every available operation")
53
+ listing.set_defaults(_handler=_cmd_list)
54
+
55
+ explain = subparsers.add_parser("explain", help="show full help for one operation")
56
+ explain.add_argument("operation", help="operation name, e.g. clean.dedup")
57
+ explain.set_defaults(_handler=_cmd_explain)
58
+
59
+ schema = subparsers.add_parser(
60
+ "schema", help="dump the machine-readable operation schema (for a web UI)"
61
+ )
62
+ schema.add_argument("--output", type=Path, help="write to this file instead of stdout")
63
+ schema.set_defaults(_handler=_cmd_schema)
64
+
65
+ recipe = subparsers.add_parser("run", help="run a YAML or JSON recipe of steps")
66
+ recipe.add_argument("recipe", type=Path, help="path to the recipe file")
67
+ _add_common_flags(recipe)
68
+ recipe.add_argument(
69
+ "--set",
70
+ dest="overrides",
71
+ action="append",
72
+ metavar="KEY=VALUE",
73
+ help="override a recipe variable, e.g. --set root=D:/data (repeatable)",
74
+ )
75
+ recipe.add_argument(
76
+ "--continue-on-error", action="store_true", help="keep going after a failing step"
77
+ )
78
+ recipe.set_defaults(_handler=_cmd_run_recipe)
79
+
80
+ menu = subparsers.add_parser("menu", help="interactive menu")
81
+ menu.set_defaults(_handler=_cmd_menu)
82
+
83
+ serve = subparsers.add_parser(
84
+ "serve", help="run the local web interface (this is also the desktop app)"
85
+ )
86
+ serve.add_argument("--host", default="127.0.0.1",
87
+ help="bind address; 127.0.0.1 keeps it on this machine only")
88
+ serve.add_argument("--port", type=int, default=8765, help="port to listen on")
89
+ serve.add_argument("--workspace", help="where uploaded datasets are stored")
90
+ serve.add_argument("--no-browser", action="store_true", help="do not open a browser")
91
+ serve.add_argument(
92
+ "--headless",
93
+ action="store_true",
94
+ help="for a remote or GPU machine: no browser, and print how to reach it "
95
+ "from your own (an SSH tunnel keeps it off the network)",
96
+ )
97
+ serve.add_argument("--api-key", help="require this key in the X-API-Key header")
98
+ serve.add_argument("--reload", action="store_true", help="auto-reload on code changes")
99
+ serve.set_defaults(_handler=_cmd_serve)
100
+
101
+ annotate = subparsers.add_parser(
102
+ "annotate",
103
+ help="open a folder in the annotation editor, editing its labels in place",
104
+ )
105
+ annotate.add_argument("folder", help="folder of images to annotate")
106
+ annotate.add_argument("--name", default="", help="project name; defaults to the folder name")
107
+ annotate.add_argument("--port", type=int, default=8765, help="port to listen on")
108
+ annotate.add_argument("--host", default="127.0.0.1", help="bind address")
109
+ annotate.add_argument("--workspace", help="where the annotation database lives")
110
+ annotate.add_argument("--no-browser", action="store_true", help="do not open a browser")
111
+ annotate.add_argument(
112
+ "--no-import",
113
+ action="store_true",
114
+ help="ignore label files already in the folder instead of loading them",
115
+ )
116
+ annotate.set_defaults(_handler=_cmd_annotate)
117
+
118
+ demo = subparsers.add_parser(
119
+ "demo",
120
+ help="open a ready-made sample project: some labelled, some predicted, some to do",
121
+ )
122
+ demo.add_argument("--folder", help="where to build it; defaults beside the database")
123
+ demo.add_argument("--port", type=int, default=8765, help="port to listen on")
124
+ demo.add_argument("--host", default="127.0.0.1", help="bind address")
125
+ demo.add_argument("--workspace", help="where the annotation database lives")
126
+ demo.add_argument("--no-browser", action="store_true", help="do not open a browser")
127
+ demo.set_defaults(_handler=_cmd_demo)
128
+
129
+ tools = subparsers.add_parser(
130
+ "tools", help="model-backed helpers: SAM outlines and text-prompted detection"
131
+ )
132
+ tools.set_defaults(_handler=_cmd_tools_help)
133
+ tools_sub = tools.add_subparsers(dest="tools_command")
134
+ install = tools_sub.add_parser(
135
+ "install", help="make ~/.datafactory/tools and install easyannotate-tools into it"
136
+ )
137
+ install.add_argument("--gpu", action="store_true",
138
+ help="require the GPU build (default: chosen from this machine's hardware)")
139
+ install.add_argument("--cpu", action="store_true", help="install for CPU even if there is a GPU")
140
+ install.add_argument(
141
+ "--source", help="install from this checkout instead of PyPI (for developers)"
142
+ )
143
+ install.set_defaults(_handler=_cmd_tools_install)
144
+ status = tools_sub.add_parser("status", help="what the editor will find")
145
+ status.set_defaults(_handler=_cmd_tools_status)
146
+
147
+ predict = subparsers.add_parser(
148
+ "predict",
149
+ help="run a trained model over a project's unreviewed images, as predictions to review",
150
+ )
151
+ predict.add_argument("target", help="the folder you annotate, or a project id")
152
+ predict.add_argument("--model", help="an Ultralytics .pt; default: the project's latest trained model")
153
+ predict.add_argument("--conf", type=float, default=0.25, help="drop predictions below this confidence")
154
+ predict.add_argument("--workspace", help="where the annotation database lives")
155
+ predict.set_defaults(_handler=_cmd_predict)
156
+
157
+ trainer = subparsers.add_parser(
158
+ "train",
159
+ help="train a detector on the reviewed images, then predict the rest",
160
+ )
161
+ trainer.add_argument("target", help="the folder you annotate, or a project id")
162
+ trainer.add_argument("--epochs", type=int, default=30)
163
+ trainer.add_argument("--imgsz", type=int, default=640)
164
+ trainer.add_argument("--base", default="yolov8n.pt", help="the model to start from")
165
+ trainer.add_argument("--conf", type=float, default=0.25, help="for the predictions that follow")
166
+ trainer.add_argument("--no-predict", action="store_true", help="train only")
167
+ trainer.add_argument("--workspace", help="where the annotation database lives")
168
+ trainer.set_defaults(_handler=_cmd_train)
169
+
170
+ desktop = subparsers.add_parser(
171
+ "app", help="open EasyAnnotate in its own window (falls back to the browser)"
172
+ )
173
+ desktop.add_argument("--browser", action="store_true", help="use the browser, not a window")
174
+ desktop.set_defaults(_handler=_cmd_app)
175
+
176
+ for operation in registry.all_operations():
177
+ _add_operation_parser(subparsers, operation)
178
+
179
+ return parser
180
+
181
+
182
+ def _add_common_flags(parser: argparse.ArgumentParser) -> None:
183
+ parser.add_argument(
184
+ "--dry-run", action="store_true", help="show what would happen without changing anything"
185
+ )
186
+ parser.add_argument("--json", action="store_true", help="emit the result as JSON")
187
+ parser.add_argument("--verbose", action="store_true", help="list every action taken")
188
+ parser.add_argument("--quiet", action="store_true", help="suppress the progress display")
189
+ parser.add_argument(
190
+ "--yes", "-y", action="store_true", help="skip the confirmation prompt for destructive runs"
191
+ )
192
+
193
+
194
+ def _add_operation_parser(subparsers: Any, operation: Operation) -> None:
195
+ parser = subparsers.add_parser(
196
+ operation.name,
197
+ help=operation.summary,
198
+ description=f"{operation.title} -- {operation.summary}",
199
+ epilog=operation.notes,
200
+ formatter_class=argparse.RawDescriptionHelpFormatter,
201
+ )
202
+ for param in operation.params:
203
+ _add_param_argument(parser, param)
204
+ _add_common_flags(parser)
205
+ parser.set_defaults(_handler=_cmd_run_operation, _operation=operation)
206
+
207
+
208
+ def _add_param_argument(parser: argparse.ArgumentParser, param: registry.Param) -> None:
209
+ flag = "--" + param.name.replace("_", "-")
210
+ help_text = param.help
211
+ if param.default is not None:
212
+ help_text += f" (default: {param.default})"
213
+
214
+ if param.kind == "bool":
215
+ # Both polarities are always available, so a default of True is just as
216
+ # easy to turn off as a default of False is to turn on.
217
+ parser.add_argument(flag, dest=param.name, action="store_true", default=None, help=help_text)
218
+ parser.add_argument(
219
+ "--no-" + param.name.replace("_", "-"),
220
+ dest=param.name,
221
+ action="store_false",
222
+ default=None,
223
+ help=argparse.SUPPRESS,
224
+ )
225
+ return
226
+
227
+ if param.kind in ("dirs", "strs"):
228
+ parser.add_argument(flag, dest=param.name, nargs="+", default=None, help=help_text)
229
+ return
230
+
231
+ parser.add_argument(
232
+ flag,
233
+ dest=param.name,
234
+ default=None,
235
+ choices=list(param.choices) if param.choices else None,
236
+ help=help_text,
237
+ )
238
+
239
+
240
+ # -- commands ---------------------------------------------------------------
241
+
242
+ def _cmd_list(args: argparse.Namespace, out: TextIO, err: TextIO) -> int:
243
+ render.render_operation_list(registry.all_operations(), out)
244
+ return 0
245
+
246
+
247
+ def _cmd_explain(args: argparse.Namespace, out: TextIO, err: TextIO) -> int:
248
+ try:
249
+ operation = registry.get(args.operation)
250
+ except KeyError as exc:
251
+ err.write(f"{exc}\n")
252
+ return 2
253
+ render.render_operation_help(operation, out)
254
+ return 0
255
+
256
+
257
+ def _cmd_schema(args: argparse.Namespace, out: TextIO, err: TextIO) -> int:
258
+ document = json.dumps(registry.schema(), indent=2)
259
+ if args.output:
260
+ args.output.parent.mkdir(parents=True, exist_ok=True)
261
+ args.output.write_text(document, encoding="utf-8")
262
+ out.write(f"schema written to {args.output}\n")
263
+ else:
264
+ out.write(document + "\n")
265
+ return 0
266
+
267
+
268
+ def _cmd_menu(args: argparse.Namespace, out: TextIO, err: TextIO) -> int:
269
+ from .menu import run_menu
270
+
271
+ return run_menu(out, err)
272
+
273
+
274
+ def _local_fragment(args: argparse.Namespace) -> str:
275
+ """``#token=...`` when this server is for this machine only -- the key that
276
+ lets the browser open local folders (see service/routers/local.py). Never
277
+ minted for a server reachable from the network or behind an API key."""
278
+ import os
279
+
280
+ from ..annotate import projects
281
+ from ..service.routers.local import LOOPBACK_ENV, TOKEN_ENV, mint_token
282
+
283
+ loopback = args.host in ("127.0.0.1", "localhost", "::1")
284
+ # Both decided here, by this launch -- never inherited from whatever
285
+ # started this process.
286
+ if loopback:
287
+ os.environ[LOOPBACK_ENV] = "1"
288
+ else:
289
+ os.environ.pop(LOOPBACK_ENV, None)
290
+ os.environ.pop(TOKEN_ENV, None)
291
+ if not loopback or not projects.attached_allowed():
292
+ return ""
293
+ if getattr(args, "api_key", None) or os.environ.get("DATAFACTORY_API_KEY"):
294
+ return ""
295
+ return f"#token={mint_token()}"
296
+
297
+
298
+ def _url_host(host: str) -> str:
299
+ """What to put in a URL for a bind address: a name, or bracketed IPv6."""
300
+ if host in ("127.0.0.1", "0.0.0.0"):
301
+ return "localhost"
302
+ return f"[{host}]" if ":" in host else host
303
+
304
+
305
+ def _cmd_serve(args: argparse.Namespace, out: TextIO, err: TextIO) -> int:
306
+ """Start the local web interface.
307
+
308
+ This doubles as the desktop application: a local server plus the system
309
+ browser, which is how Jupyter and Netron ship. It avoids bundling a second
310
+ browser engine, works identically on Windows, macOS and Linux, and the
311
+ same code is what runs on a server -- so there is one thing to maintain
312
+ rather than a desktop build and a web build that drift.
313
+ """
314
+ import os
315
+
316
+ if args.workspace:
317
+ os.environ["DATAFACTORY_WORKSPACE"] = str(Path(args.workspace).expanduser())
318
+ if args.api_key:
319
+ os.environ["DATAFACTORY_API_KEY"] = args.api_key
320
+
321
+ try:
322
+ import uvicorn
323
+ except ImportError:
324
+ err.write(
325
+ "the web interface could not import uvicorn -- reinstall:\n"
326
+ " pip install --force-reinstall easyannotate\n"
327
+ )
328
+ return 2
329
+
330
+ url = f"http://{_url_host(args.host)}:{args.port}"
331
+ url += _local_fragment(args)
332
+ out.write(f"EasyAnnotate is at {url}\n")
333
+ if args.host == "0.0.0.0" and not args.api_key:
334
+ err.write(
335
+ "warning: binding to 0.0.0.0 exposes this to your whole network with no "
336
+ "authentication. Pass --api-key, or bind to 127.0.0.1.\n"
337
+ )
338
+ out.write("Press Ctrl+C to stop.\n")
339
+ out.flush()
340
+
341
+ if args.headless and args.host not in ("127.0.0.1", "localhost", "::1"):
342
+ args.no_browser = True
343
+ out.write(
344
+ f"headless, listening on {args.host}: reachable from the network.\n"
345
+ "Protect it with --api-key, or bind to 127.0.0.1 and use an SSH tunnel.\n"
346
+ )
347
+ out.flush()
348
+ elif args.headless:
349
+ args.no_browser = True
350
+ out.write(
351
+ "headless: nothing opens here. From your own computer:\n"
352
+ f" ssh -L {args.port}:localhost:{args.port} <this-machine>\n"
353
+ f" then open http://localhost:{args.port}\n"
354
+ "The server stays bound to this machine; the tunnel carries the editor to you.\n"
355
+ )
356
+ out.flush()
357
+
358
+ if not args.no_browser:
359
+ import threading
360
+ import webbrowser
361
+
362
+ # Opened on a delay so the server is listening by the time the tab
363
+ # loads; otherwise the first request races the startup and fails.
364
+ threading.Timer(1.0, lambda: webbrowser.open(url)).start()
365
+
366
+ import uvicorn
367
+
368
+ uvicorn.run(
369
+ "data_factory.service.app:app",
370
+ host=args.host,
371
+ port=args.port,
372
+ reload=args.reload,
373
+ log_level="warning",
374
+ )
375
+ return 0
376
+
377
+
378
+ def _cmd_annotate(args: argparse.Namespace, out: TextIO, err: TextIO) -> int:
379
+ """Open a folder for annotation, editing its label files in place.
380
+
381
+ This is the only way to create an attached project, and that is deliberate:
382
+ it takes a path, and no HTTP route is ever allowed to. The path comes from
383
+ a person typing it into their own terminal, not from a request.
384
+ """
385
+ import os
386
+
387
+ if args.workspace:
388
+ os.environ["DATAFACTORY_WORKSPACE"] = str(Path(args.workspace).expanduser())
389
+
390
+ from ..annotate import attach
391
+ from ..annotate.store import StoreError
392
+ from ..service.deps import get_store, store_path
393
+
394
+ folder = Path(args.folder).expanduser()
395
+ try:
396
+ summary = attach.open_folder(
397
+ get_store(),
398
+ folder,
399
+ name=args.name,
400
+ import_annotations=not args.no_import,
401
+ )
402
+ except StoreError as exc:
403
+ err.write(f"{exc}\n")
404
+ return 1
405
+
406
+ project = summary["project"]
407
+ out.write(f"\n{project.name}\n")
408
+ out.write(f" folder {project.root}\n")
409
+ out.write(
410
+ f" images {summary['images']}"
411
+ + (f" ({summary['new_images']} new)" if summary["reused"] else "")
412
+ + "\n"
413
+ )
414
+ if summary["shapes_imported"]:
415
+ out.write(f" imported {summary['shapes_imported']} existing shapes\n")
416
+ if summary["writes_back"]:
417
+ out.write(
418
+ f" writes to {summary['sidecar_format'].upper()} files in that folder, "
419
+ f"as you draw\n"
420
+ )
421
+ else:
422
+ out.write(
423
+ " writes to nothing on disk -- this format keeps one file for the\n"
424
+ " whole dataset, so use annotate.export to get it back\n"
425
+ )
426
+ out.write(f" database {store_path()}\n")
427
+ for warning in summary["warnings"]:
428
+ out.write(f" note {warning}\n")
429
+
430
+ return _serve_editor(project.id, args, out)
431
+
432
+
433
+ def _serve_editor(project_id: str, args: argparse.Namespace, out: TextIO) -> int:
434
+ """Start the server and open the editor on one project."""
435
+ url = f"http://{_url_host(args.host)}:{args.port}/annotate?project={project_id}" + _local_fragment(args)
436
+ out.write(f"\n{url}\n")
437
+ out.write("Press Ctrl+C to stop.\n")
438
+ out.flush()
439
+
440
+ if not args.no_browser:
441
+ import threading
442
+ import webbrowser
443
+
444
+ threading.Timer(1.0, lambda: webbrowser.open(url)).start()
445
+
446
+ import uvicorn
447
+
448
+ uvicorn.run(
449
+ "data_factory.service.app:app",
450
+ host=args.host,
451
+ port=args.port,
452
+ log_level="warning",
453
+ )
454
+ return 0
455
+
456
+
457
+ def _cmd_tools_help(args: argparse.Namespace, out: TextIO, err: TextIO) -> int:
458
+ out.write("usage: easyannotate tools install [--gpu] [--source DIR]\n"
459
+ " easyannotate tools status\n")
460
+ return 2
461
+
462
+
463
+ def _cmd_tools_install(args: argparse.Namespace, out: TextIO, err: TextIO) -> int:
464
+ """A separate environment for the heavy tools, chosen for this machine --
465
+ the CUDA build its driver supports, Metal, or CPU -- where torch's version
466
+ matrix is resolved on its own and can never break the editor's install."""
467
+ from ..annotate.tools import install as installer
468
+
469
+ device = "cpu" if args.cpu else ("cuda" if args.gpu else None)
470
+ try:
471
+ installer.install(
472
+ source=Path(args.source).expanduser() if args.source else None,
473
+ device=device,
474
+ on_line=lambda line: (out.write(f" {line}\n"), out.flush()),
475
+ )
476
+ except (installer.InstallError, OSError) as exc:
477
+ err.write(f"{exc}\n")
478
+ return 1
479
+ out.write("\nModel weights download on first use.\n")
480
+ return _cmd_tools_status(args, out, err)
481
+
482
+
483
+ def _cmd_tools_status(args: argparse.Namespace, out: TextIO, err: TextIO) -> int:
484
+ from ..annotate.tools import install as installer
485
+ from ..annotate.tools.registry import REGISTRY
486
+
487
+ state = installer.status()
488
+ plan = state["plan"]
489
+ out.write(f"this machine: {plan['summary']}\n")
490
+ for warning in plan.get("warnings") or []:
491
+ out.write(f" note: {warning}\n")
492
+ if state["installed"]:
493
+ profile = state["profile"]
494
+ out.write(
495
+ f"installed: {profile.get('summary', '?')} "
496
+ f"(PyTorch sees {profile.get('verified_device', '?')})\n"
497
+ )
498
+ else:
499
+ out.write(f"installed: no -- easyannotate tools install (about {plan['download_gb']:g} GB)\n")
500
+ return 1
501
+
502
+ report = REGISTRY.as_dict()
503
+ tools = report.get("tools") or []
504
+ if not tools:
505
+ health = report.get("health") or {}
506
+ out.write(f"no tools: {report.get('reason') or health.get('detail') or 'none found'}\n")
507
+ return 1
508
+ for tool in tools:
509
+ out.write(f" {tool['name']:<14} {tool.get('title', '')} [{tool.get('version', '')}]\n")
510
+ REGISTRY.close()
511
+ return 0
512
+
513
+
514
+ def _loop_target(args: argparse.Namespace, err: TextIO):
515
+ """A folder (opened, or reopened, as an attached project) or a project id.
516
+ Returns (store, project, image_root) or None after explaining why not."""
517
+ import os
518
+
519
+ if args.workspace:
520
+ os.environ["DATAFACTORY_WORKSPACE"] = str(Path(args.workspace).expanduser())
521
+ from ..annotate import attach
522
+ from ..annotate import projects as projects_mod
523
+ from ..annotate.store import StoreError
524
+ from ..service.deps import get_store, media_root
525
+
526
+ store = get_store()
527
+ target = Path(args.target).expanduser()
528
+ try:
529
+ if target.is_dir():
530
+ project = attach.open_folder(store, target)["project"]
531
+ else:
532
+ project = projects_mod.get(store, args.target, "local")
533
+ except StoreError as exc:
534
+ err.write(f"{exc}\n")
535
+ return None
536
+ root = Path(project.root) if project.is_attached and project.root else media_root(project.id)
537
+ return store, project, root
538
+
539
+
540
+ def _progress_line(out: TextIO):
541
+ last = [0.0]
542
+
543
+ def report(done: int, total: int, name: str) -> None:
544
+ now = time.time()
545
+ if done == total or now - last[0] > 0.5:
546
+ last[0] = now
547
+ out.write(f"\r {done}/{total} {name[:50]:<50}")
548
+ out.flush()
549
+ if done == total:
550
+ out.write("\n")
551
+
552
+ return report
553
+
554
+
555
+ def _summarise_predictions(report: dict, project, out: TextIO) -> int:
556
+ out.write(
557
+ f" {report['shapes']} prediction(s) on {report['predicted']} of {report['images']} "
558
+ f"unreviewed image(s) in {report['seconds']}s"
559
+ + (f"; {report['failed']} failed" if report["failed"] else "")
560
+ + "\n"
561
+ )
562
+ if report.get("first_error"):
563
+ out.write(f" first failure: {report['first_error']}\n")
564
+ if report["predicted"] == 0 and report["failed"]:
565
+ return 1
566
+ out.write(
567
+ " review them hardest first: open the editor and pick\n"
568
+ " 'predicted, least sure first' in the image list.\n"
569
+ )
570
+ return 0
571
+
572
+
573
+ def _cmd_predict(args: argparse.Namespace, out: TextIO, err: TextIO) -> int:
574
+ from ..annotate import loop
575
+
576
+ found = _loop_target(args, err)
577
+ if found is None:
578
+ return 1
579
+ store, project, root = found
580
+ model = Path(args.model).expanduser() if args.model else loop.latest_model(project)
581
+ if model is None:
582
+ err.write("no model given and none trained for this project yet -- pass --model, or run train\n")
583
+ return 1
584
+ out.write(f"{project.name}: predicting with {model.name}\n")
585
+ try:
586
+ report = loop.predict(store, project, root, model, conf=args.conf, on_progress=_progress_line(out))
587
+ except loop.LoopError as exc:
588
+ err.write(f"{exc}\n")
589
+ return 1
590
+ return _summarise_predictions(report, project, out)
591
+
592
+
593
+ def _cmd_train(args: argparse.Namespace, out: TextIO, err: TextIO) -> int:
594
+ from ..annotate import loop
595
+
596
+ found = _loop_target(args, err)
597
+ if found is None:
598
+ return 1
599
+ store, project, root = found
600
+ out.write(f"{project.name}\n")
601
+ try:
602
+ trained = loop.train(
603
+ store, project, epochs=args.epochs, imgsz=args.imgsz, base=args.base,
604
+ on_line=lambda line: (out.write(f" {line}\n"), out.flush()),
605
+ )
606
+ except loop.LoopError as exc:
607
+ err.write(f"{exc}\n")
608
+ return 1
609
+ metrics = trained["metrics"]
610
+ score = metrics.get("metrics/mAP50(B)")
611
+ out.write(
612
+ f" model saved: {trained['model']}"
613
+ + (f" (mAP50 {score:.3f})" if isinstance(score, (int, float)) else "")
614
+ + "\n"
615
+ )
616
+ if args.no_predict:
617
+ return 0
618
+ out.write("predicting the unreviewed images with it\n")
619
+ try:
620
+ report = loop.predict(store, project, root, trained["model"], conf=args.conf,
621
+ on_progress=_progress_line(out))
622
+ except loop.LoopError as exc:
623
+ err.write(f"{exc}\n")
624
+ return 1
625
+ return _summarise_predictions(report, project, out)
626
+
627
+
628
+ def _cmd_app(args: argparse.Namespace, out: TextIO, err: TextIO) -> int:
629
+ from .. import desktop
630
+
631
+ return desktop.main(["--browser"] if args.browser else [])
632
+
633
+
634
+ def _cmd_demo(args: argparse.Namespace, out: TextIO, err: TextIO) -> int:
635
+ """Build (once) and open the sample project.
636
+
637
+ The first minute with a tool decides whether there is a second. This is
638
+ one command from install to an editor with labelled images, predictions
639
+ to review, and images still to do.
640
+ """
641
+ import os
642
+ import tempfile
643
+
644
+ if args.workspace:
645
+ os.environ["DATAFACTORY_WORKSPACE"] = str(Path(args.workspace).expanduser())
646
+
647
+ from ..annotate import attach, demo, review
648
+ from ..service.deps import data_root, get_store
649
+
650
+ folder = Path(args.folder).expanduser() if args.folder else data_root() / "demo"
651
+ built = demo.build(folder)
652
+ store = get_store()
653
+ summary = attach.open_folder(store, folder, name="EasyAnnotate demo")
654
+ project = summary["project"]
655
+
656
+ if built["fresh"]:
657
+ with tempfile.TemporaryDirectory() as holding:
658
+ run = demo.write_predictions(built["predictions"], Path(holding) / "run")
659
+ report = review.import_predictions(store, project, run, name="demo model")
660
+ out.write(
661
+ f"\nEasyAnnotate demo -- {summary['images']} images in {folder}\n"
662
+ f" {summary['shapes_imported']} shapes labelled by hand\n"
663
+ f" {report['shapes_imported']} model predictions to review: "
664
+ f"A accepts an image, the slider hides weak guesses\n"
665
+ )
666
+ else:
667
+ out.write(f"\nEasyAnnotate demo -- reopening {folder}\n")
668
+ return _serve_editor(project.id, args, out)
669
+
670
+
671
+ def _cmd_run_operation(args: argparse.Namespace, out: TextIO, err: TextIO) -> int:
672
+ operation: Operation = args._operation
673
+ supplied = {
674
+ param.name: getattr(args, param.name)
675
+ for param in operation.params
676
+ if getattr(args, param.name, None) is not None
677
+ }
678
+
679
+ try:
680
+ bound = operation.bind(supplied)
681
+ except ParamError as exc:
682
+ err.write(f"error: {exc}\n")
683
+ return 2
684
+
685
+ if not _confirm(operation, bound, args, err):
686
+ return 1
687
+
688
+ ctx = _make_context(args, err)
689
+ try:
690
+ result = operation.run(supplied, ctx)
691
+ except Cancelled:
692
+ err.write("\ncancelled\n")
693
+ return 130
694
+ except (RuntimeError, OSError) as exc:
695
+ err.write(f"error: {exc}\n")
696
+ return 1
697
+ finally:
698
+ _clear_progress(args, err)
699
+
700
+ render.render_result(result, out, as_json=args.json, verbose=args.verbose)
701
+ return 0 if result.ok else 1
702
+
703
+
704
+ def _cmd_run_recipe(args: argparse.Namespace, out: TextIO, err: TextIO) -> int:
705
+ from ..pipeline import Recipe, RecipeError, run
706
+
707
+ overrides: dict[str, str] = {}
708
+ for item in args.overrides or []:
709
+ if "=" not in item:
710
+ err.write(f"error: --set expects KEY=VALUE, got {item!r}\n")
711
+ return 2
712
+ key, value = item.split("=", 1)
713
+ overrides[key.strip()] = value.strip()
714
+
715
+ try:
716
+ recipe = Recipe.load(args.recipe, overrides=overrides)
717
+ except (RecipeError, OSError, ValueError) as exc:
718
+ err.write(f"error: {exc}\n")
719
+ return 2
720
+
721
+ destructive = [
722
+ s
723
+ for s in recipe.steps
724
+ if not s.skip
725
+ and registry.get(s.op).destructive_for(registry.get(s.op).bind(s.params, check_paths=False))
726
+ ]
727
+ if destructive and not args.dry_run and not args.yes:
728
+ names = ", ".join(sorted({s.op for s in destructive}))
729
+ if not _ask(f"Recipe '{recipe.name}' runs destructive steps ({names}). Continue?", err):
730
+ err.write("aborted\n")
731
+ return 1
732
+
733
+ ctx = _make_context(args, err)
734
+
735
+ def announce(position: int, total: int, step: Any) -> None:
736
+ if not args.quiet and not args.json:
737
+ out.write(f"\n[{position}/{total}] {step.label}\n")
738
+
739
+ try:
740
+ report = run(recipe, ctx, continue_on_error=args.continue_on_error, on_step=announce)
741
+ except Cancelled:
742
+ err.write("\ncancelled\n")
743
+ return 130
744
+ finally:
745
+ _clear_progress(args, err)
746
+
747
+ if args.json:
748
+ json.dump(report.as_dict(), out, indent=2)
749
+ out.write("\n")
750
+ else:
751
+ for result in report.results:
752
+ render.render_result(result, out, verbose=args.verbose)
753
+ if report.stopped_at:
754
+ err.write(f"recipe stopped at step '{report.stopped_at}'\n")
755
+ return 0 if report.ok else 1
756
+
757
+
758
+ # -- shared helpers ---------------------------------------------------------
759
+
760
+ def _make_context(args: argparse.Namespace, err: TextIO) -> Context:
761
+ show_progress = not args.quiet and not args.json and hasattr(err, "isatty") and err.isatty()
762
+ return Context(dry_run=args.dry_run, progress=_progress_printer(err) if show_progress else None)
763
+
764
+
765
+ def _progress_printer(err: TextIO) -> Any:
766
+ """A single rewriting status line, throttled so it never dominates the run."""
767
+ state = {"last": 0.0}
768
+
769
+ def report(done: int, total: int, message: str = "") -> None:
770
+ now = time.monotonic()
771
+ if now - state["last"] < 0.08 and done != total:
772
+ return
773
+ state["last"] = now
774
+ share = f"{done}/{total}" if total else str(done)
775
+ line = f" {share} {message}"[:110]
776
+ err.write("\r\033[K" + line)
777
+ err.flush()
778
+
779
+ return report
780
+
781
+
782
+ def _clear_progress(args: argparse.Namespace, err: TextIO) -> None:
783
+ if not args.quiet and not args.json and hasattr(err, "isatty") and err.isatty():
784
+ err.write("\r\033[K")
785
+ err.flush()
786
+
787
+
788
+ def _confirm(
789
+ operation: Operation, bound: dict[str, Any], args: argparse.Namespace, err: TextIO
790
+ ) -> bool:
791
+ # Judged from the actual parameters: --action report writes nothing, so it
792
+ # should not demand a confirmation the way --action delete must.
793
+ if not operation.destructive_for(bound) or args.dry_run or args.yes:
794
+ return True
795
+ if not sys.stdin.isatty():
796
+ err.write(
797
+ f"error: {operation.name} changes files. Re-run with --dry-run to preview, "
798
+ "or --yes to confirm in a non-interactive session.\n"
799
+ )
800
+ return False
801
+ return _ask(f"{operation.name} will modify files on disk. Continue?", err)
802
+
803
+
804
+ def _ask(question: str, err: TextIO) -> bool:
805
+ try:
806
+ answer = input(f"{question} [y/N] ").strip().lower()
807
+ except (EOFError, KeyboardInterrupt):
808
+ err.write("\n")
809
+ return False
810
+ return answer in ("y", "yes")
811
+
812
+
813
+ def main(argv: Sequence[str] | None = None) -> int:
814
+ argv = list(sys.argv[1:] if argv is None else argv)
815
+ parser = build_parser()
816
+
817
+ # Bare invocation is the friendly path: show the menu rather than a usage error.
818
+ if not argv:
819
+ from .menu import run_menu
820
+
821
+ return run_menu(sys.stdout, sys.stderr)
822
+
823
+ args = parser.parse_args(argv)
824
+ handler = getattr(args, "_handler", None)
825
+ if handler is None:
826
+ parser.print_help()
827
+ return 0
828
+
829
+ try:
830
+ return handler(args, sys.stdout, sys.stderr)
831
+ except KeyboardInterrupt:
832
+ sys.stderr.write("\ninterrupted\n")
833
+ return 130
834
+
835
+
836
+ if __name__ == "__main__":
837
+ raise SystemExit(main())