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,464 @@
1
+ """The local link: the browser opens folders on this computer -- safely.
2
+
3
+ Everywhere else in the service a client may never name a filesystem path,
4
+ because a web server that reads paths from requests is a file-reading
5
+ primitive for anyone who can reach it. On your own machine that is still
6
+ true of *other* websites: any page you visit can make your browser send a
7
+ request to ``localhost:8765``.
8
+
9
+ So opening a folder by path is the one exception, and it is fenced four ways:
10
+
11
+ 1. **A per-launch secret.** The CLI (or desktop launcher) mints a token and
12
+ puts it in the URL's ``#fragment`` -- which a browser never sends to any
13
+ server, never logs, never leaks in a Referer. The page moves it into
14
+ session storage and sends it as ``X-Local-Token``. No other site has it.
15
+ 2. **Host must be this machine**, and so must the client. ``localhost``,
16
+ ``127.0.0.1`` or ``::1``, parsed strictly; the connection itself from a
17
+ loopback address. A DNS-rebinding attack arrives with the attacker's
18
+ hostname -- and while the server is bound to loopback, ``LocalHostFence``
19
+ refuses that on *every* route, not only these: projects, images and
20
+ shapes carry no token, and they are the user's own folders.
21
+ 3. **No foreign Origin.** A browser stamps cross-site requests with the
22
+ page's origin; anything but this server's own exact origin is refused.
23
+ (The custom header also forces a CORS preflight, which is never granted.)
24
+ 4. **Local mode at all.** Only the CLI and desktop launchers set the token,
25
+ only when bound to this machine with no API key -- the hosted and Docker
26
+ paths never do, and ``DATAFACTORY_ALLOW_ATTACHED=0`` turns it off. A
27
+ token inherited from a parent process is cleared, never honoured, and no
28
+ child process (sidecar, trainer, installer) is given it.
29
+
30
+ And it grants one capability: a folder becomes a project, and the page gets
31
+ the project's *id*. Operations still run through the sandbox; the editor
32
+ still never sees a path. That is the same thing the desktop window's
33
+ Open-folder button does, for a browser.
34
+ """
35
+
36
+ from __future__ import annotations
37
+
38
+ import ipaddress
39
+ import os
40
+ import re
41
+ import secrets
42
+ import subprocess
43
+ import sys
44
+ import threading
45
+ from pathlib import Path
46
+ from typing import Any
47
+ from urllib.parse import urlsplit
48
+
49
+ from fastapi import APIRouter, Depends, Header, HTTPException, Request
50
+ from pydantic import BaseModel
51
+ from starlette.responses import PlainTextResponse
52
+
53
+ from ...annotate import attach
54
+ from ...annotate import projects as projects_mod
55
+ from ...annotate.store import StoreError
56
+ from ...annotate.tools.local import child_environment
57
+ from ..deps import api_key, get_store, jobs_manager, media_root
58
+
59
+ TOKEN_ENV = "EASYANNOTATE_LOCAL_TOKEN"
60
+ #: Set by a launcher that binds to loopback: turns on ``LocalHostFence``.
61
+ LOOPBACK_ENV = "EASYANNOTATE_LOOPBACK"
62
+ LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
63
+ #: A Host header as a browser sends it: a name or bracketed IPv6, an optional
64
+ #: port, nothing else. ``evil@localhost`` and ``localhost/x`` are not hosts.
65
+ _HOST_SHAPE = re.compile(r"^(?:[A-Za-z0-9.-]+|\[[0-9A-Fa-f:.]+\])(?::[0-9]{1,5})?$")
66
+
67
+ router = APIRouter(prefix="/api/local", tags=["local"])
68
+
69
+
70
+ def mint_token() -> str:
71
+ """Called by a launcher that is serving this machine only."""
72
+ token = secrets.token_urlsafe(24)
73
+ os.environ[TOKEN_ENV] = token
74
+ return token
75
+
76
+
77
+ def local_mode_enabled() -> bool:
78
+ return bool(os.environ.get(TOKEN_ENV)) and projects_mod.attached_allowed() and not api_key()
79
+
80
+
81
+ def fence_active() -> bool:
82
+ # Not behind an API key: the key already stops a rebinding page, and a
83
+ # same-machine reverse proxy (TLS, a tunnel) forwards its public Host.
84
+ if api_key():
85
+ return False
86
+ return os.environ.get(LOOPBACK_ENV) == "1" or local_mode_enabled()
87
+
88
+
89
+ def host_is_local(value: str) -> bool:
90
+ """The Host header names this machine -- strictly parsed."""
91
+ return bool(value) and bool(_HOST_SHAPE.match(value)) and _hostname(value) in LOCAL_HOSTS
92
+
93
+
94
+ def client_is_loopback(request: Request) -> bool:
95
+ """The connection itself came from this machine, not just its Host header."""
96
+ if request.client is None:
97
+ return False
98
+ try:
99
+ address = ipaddress.ip_address(request.client.host)
100
+ except ValueError:
101
+ return False
102
+ if isinstance(address, ipaddress.IPv6Address) and address.ipv4_mapped:
103
+ address = address.ipv4_mapped
104
+ return address.is_loopback
105
+
106
+
107
+ class LocalHostFence:
108
+ """While the server is bound to this machine, answer only to its names.
109
+
110
+ A DNS-rebinding page reaches 127.0.0.1 under a hostname of its own. The
111
+ token keeps it out of ``/api/local``, but the project, image and shape
112
+ routes have no token -- without this fence such a page could read a
113
+ user's attached folders and rewrite their label files. Measured: it did.
114
+ """
115
+
116
+ def __init__(self, app: Any) -> None:
117
+ self.app = app
118
+
119
+ async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
120
+ if scope["type"] == "http" and fence_active():
121
+ hosts = [value.decode("latin-1") for key, value in scope.get("headers", []) if key == b"host"]
122
+ if len(hosts) != 1 or not host_is_local(hosts[0]):
123
+ response = PlainTextResponse(
124
+ "this EasyAnnotate serves this computer only -- open it at localhost", status_code=403
125
+ )
126
+ await response(scope, receive, send)
127
+ return
128
+ await self.app(scope, receive, send)
129
+
130
+
131
+ def _hostname(value: str) -> str:
132
+ """The host part of a Host header or an origin, without port or brackets."""
133
+ if not value:
134
+ return ""
135
+ if "://" not in value:
136
+ value = "http://" + value
137
+ try:
138
+ return (urlsplit(value).hostname or "").lower()
139
+ except ValueError:
140
+ return ""
141
+
142
+
143
+ def require_local(request: Request, x_local_token: str = Header(default="")) -> None:
144
+ expected = os.environ.get(TOKEN_ENV, "")
145
+ if not local_mode_enabled():
146
+ raise HTTPException(404, "local mode is off -- start EasyAnnotate on this computer")
147
+ # isascii first: compare_digest raises on non-ASCII text, and a 500 with a
148
+ # traceback is a worse answer than a refusal.
149
+ if not x_local_token or not x_local_token.isascii() or not secrets.compare_digest(x_local_token, expected):
150
+ raise HTTPException(403, "this page was not opened by EasyAnnotate on this computer")
151
+ hosts = request.headers.getlist("host")
152
+ if len(hosts) != 1 or not host_is_local(hosts[0]):
153
+ raise HTTPException(403, "local requests must be addressed to this computer")
154
+ if not client_is_loopback(request):
155
+ raise HTTPException(403, "local requests must come from this computer")
156
+ origin = request.headers.get("origin")
157
+ if origin is not None and origin.lower() != f"{request.url.scheme}://{hosts[0]}".lower():
158
+ raise HTTPException(403, "requests from other sites are refused")
159
+
160
+
161
+ class OpenIn(BaseModel):
162
+ path: str
163
+
164
+
165
+ @router.get("/status", dependencies=[Depends(require_local)])
166
+ def status() -> dict[str, Any]:
167
+ """The token works. Says whether a native folder dialog can be offered."""
168
+ return {"ok": True, "dialog": _dialog_available()}
169
+
170
+
171
+ @router.post("/open", dependencies=[Depends(require_local)])
172
+ def open_path(body: OpenIn, store=Depends(get_store)) -> dict[str, Any]:
173
+ raw = body.path.strip().strip('"')
174
+ # UNC shares and \\?\ / \\.\ device paths: each is a second spelling of
175
+ # some folder (so a second project writing the same label files), and
176
+ # \\.\C:\ is a whole drive. A mapped drive letter works; the CLI takes any.
177
+ if raw.startswith(("\\\\", "//")):
178
+ raise HTTPException(400, "network and device paths are not opened from the browser -- "
179
+ "use a drive letter, or `easyannotate annotate <folder>`")
180
+ folder = Path(raw).expanduser()
181
+ if not folder.is_absolute():
182
+ raise HTTPException(400, "give the full path to a folder, e.g. D:\\photos\\doors")
183
+ if not folder.is_dir():
184
+ raise HTTPException(400, f"there is no folder at {folder}")
185
+ resolved = folder.resolve()
186
+ if resolved.parent == resolved or resolved == Path.home().resolve():
187
+ raise HTTPException(400, "that is a whole drive or your home folder -- pick the folder of images")
188
+ return _opened(store, folder)
189
+
190
+
191
+ @router.post("/pick", dependencies=[Depends(require_local)])
192
+ def pick(store=Depends(get_store)) -> dict[str, Any]:
193
+ """The operating system's own folder dialog, on this computer."""
194
+ if not _dialog_available():
195
+ raise HTTPException(501, "no folder dialog here -- type the path instead")
196
+ if not _dialog_lock.acquire(blocking=False):
197
+ raise HTTPException(409, "a folder dialog is already open on this computer")
198
+ try:
199
+ chosen = _run_dialog()
200
+ finally:
201
+ _dialog_lock.release()
202
+ if not chosen:
203
+ return {"cancelled": True}
204
+ return _opened(store, Path(chosen))
205
+
206
+
207
+ # --------------------------------------------------------------- AI tools
208
+ #
209
+ # Installing software and training models are things only the person at this
210
+ # computer may start, so they sit behind the same fences as opening folders.
211
+ # None of them takes a path or a model file from the page: the installer
212
+ # chooses for the hardware, and training and prediction use the project's own
213
+ # latest model, found on the server.
214
+
215
+ class InstallIn(BaseModel):
216
+ device: str | None = None # "cpu" to skip the GPU build; None: detect
217
+
218
+
219
+ class LoopIn(BaseModel):
220
+ project: str
221
+ epochs: int = 30
222
+ predict: bool = True
223
+
224
+
225
+ #: "install", or "loop:<project id>" -> job id. One install at a time, one
226
+ #: train-or-predict per project: two runs over one project would mix two
227
+ #: models' predictions image by image.
228
+ _running: dict[str, str] = {}
229
+ _running_lock = threading.Lock()
230
+
231
+
232
+ def _job_running(key: str) -> dict[str, Any] | None:
233
+ jobs = jobs_manager()
234
+ job_id = _running.get(key)
235
+ job = jobs.get(job_id) if (jobs and job_id) else None
236
+ if job is not None and job.state in ("queued", "running"):
237
+ return job.as_dict()
238
+ return None
239
+
240
+
241
+ def _any_loop_running() -> bool:
242
+ return any(_job_running(key) for key in list(_running) if key.startswith("loop:"))
243
+
244
+
245
+ def _start_loop(project, operation: str, work) -> dict[str, Any]:
246
+ """Submit a train or predict job, or join/refuse the one already going."""
247
+ jobs = jobs_manager()
248
+ if jobs is None:
249
+ raise HTTPException(503, "no job runner in this process")
250
+ key = f"loop:{project.id}"
251
+ with _running_lock:
252
+ if _job_running("install"):
253
+ raise HTTPException(409, "the AI tools are being installed -- wait for that to finish")
254
+ running = _job_running(key)
255
+ if running:
256
+ if running.get("operation") == operation:
257
+ return running # a second click joins the first
258
+ raise HTTPException(409, "this project is already training or predicting -- wait for it")
259
+ # One training per machine: two at once on one GPU run out of memory.
260
+ if operation == "loop.train" and any(
261
+ (job := _job_running(other)) and job.get("operation") == "loop.train"
262
+ for other in list(_running) if other.startswith("loop:")
263
+ ):
264
+ raise HTTPException(409, "another project is training -- one at a time on this computer")
265
+ job = jobs.submit(secrets.token_hex(8), operation, project.id, work)
266
+ _running[key] = job.id
267
+ return job.as_dict()
268
+
269
+
270
+ def _checked(context, emit):
271
+ """Wrap a progress callback so a cancel request stops the work there."""
272
+ def callback(*args):
273
+ context.check_cancelled()
274
+ emit(*args)
275
+ return callback
276
+
277
+
278
+ def _source_checkout() -> Path | None:
279
+ """Running from a clone: install the tools from it, not from PyPI."""
280
+ root = Path(__file__).resolve().parents[3]
281
+ return root if (root / "tools" / "pyproject.toml").is_file() else None
282
+
283
+
284
+ @router.get("/tools", dependencies=[Depends(require_local)])
285
+ def tools_state() -> dict[str, Any]:
286
+ from ...annotate.tools import install as installer
287
+
288
+ return {**installer.status(), "job": _job_running("install")}
289
+
290
+
291
+ @router.post("/tools/install", dependencies=[Depends(require_local)])
292
+ def tools_install(body: InstallIn) -> dict[str, Any]:
293
+ from ...annotate.tools import install as installer
294
+ from ...annotate.tools.registry import REGISTRY
295
+ from ...core.types import OpResult
296
+
297
+ if body.device not in (None, "cpu", "cuda", "mps"):
298
+ raise HTTPException(400, "device must be cpu, cuda or mps")
299
+ jobs = jobs_manager()
300
+ if jobs is None:
301
+ raise HTTPException(503, "no job runner in this process")
302
+
303
+ def work(context) -> OpResult:
304
+ lines: list[str] = []
305
+
306
+ def on_line(line: str) -> None:
307
+ context.check_cancelled()
308
+ lines.append(line)
309
+ context.emit(len(lines), 0, line[-200:])
310
+
311
+ result = OpResult(op="tools.install")
312
+ # Stop the sidecar, and start none while this runs: it holds torch's
313
+ # files open, and on Windows an open DLL cannot be replaced -- a
314
+ # reinstall would half-remove it.
315
+ REGISTRY.pause("the AI tools are being installed")
316
+ try:
317
+ profile = installer.install(source=_source_checkout(), device=body.device, on_line=on_line)
318
+ except installer.InstallError as exc:
319
+ result.fail(str(exc))
320
+ result.data = {"log": lines[-40:]}
321
+ return result
322
+ finally:
323
+ REGISTRY.resume() # the Assist panel appears on the next look
324
+ result.data = {"profile": profile, "log": lines[-40:]}
325
+ return result
326
+
327
+ with _running_lock:
328
+ running = _job_running("install")
329
+ if running:
330
+ return running
331
+ if _any_loop_running():
332
+ raise HTTPException(409, "a model is training or predicting -- install when it has finished")
333
+ job = jobs.submit(secrets.token_hex(8), "tools.install", "local", work)
334
+ _running["install"] = job.id
335
+ return job.as_dict()
336
+
337
+
338
+ @router.post("/train", dependencies=[Depends(require_local)])
339
+ def train_project(body: LoopIn, store=Depends(get_store)) -> dict[str, Any]:
340
+ """Train on the reviewed images, then predict the rest with the result."""
341
+ from ...annotate import loop
342
+ from ...core.types import OpResult
343
+
344
+ project = _project(store, body.project)
345
+ if not 1 <= body.epochs <= 500:
346
+ raise HTTPException(400, "epochs must be between 1 and 500")
347
+
348
+ def work(context) -> OpResult:
349
+ result = OpResult(op="loop.train")
350
+ try:
351
+ trained = loop.train(
352
+ store, project, epochs=body.epochs,
353
+ on_line=_checked(context, lambda line: context.emit(0, 0, line[-200:])),
354
+ )
355
+ data: dict[str, Any] = {
356
+ "model": trained["model"].name,
357
+ "metrics": trained["metrics"],
358
+ }
359
+ if body.predict:
360
+ data["predicted"] = loop.predict(
361
+ store, project, _image_root(project), trained["model"],
362
+ on_progress=_checked(context, lambda done, total, name: context.emit(done, total, f"predicting {name}")),
363
+ )
364
+ result.data = data
365
+ except loop.LoopError as exc:
366
+ result.fail(str(exc))
367
+ return result
368
+
369
+ return _start_loop(project, "loop.train", work)
370
+
371
+
372
+ @router.post("/predict", dependencies=[Depends(require_local)])
373
+ def predict_project(body: LoopIn, store=Depends(get_store)) -> dict[str, Any]:
374
+ """Predict the unreviewed images with the project's latest trained model."""
375
+ from ...annotate import loop
376
+ from ...core.types import OpResult
377
+
378
+ project = _project(store, body.project)
379
+ model = loop.latest_model(project)
380
+ if model is None:
381
+ raise HTTPException(409, "no model trained for this project yet -- train one first")
382
+
383
+ def work(context) -> OpResult:
384
+ result = OpResult(op="loop.predict")
385
+ try:
386
+ predicted = loop.predict(
387
+ store, project, _image_root(project), model,
388
+ on_progress=_checked(context, lambda done, total, name: context.emit(done, total, f"predicting {name}")),
389
+ )
390
+ result.data = {"predicted": predicted, "model": model.name}
391
+ # Every image failing is a failure, not "0 predictions".
392
+ if predicted["failed"] and not predicted["predicted"]:
393
+ result.fail(f"every image failed -- first: {predicted['first_error'] or 'image files not found'}")
394
+ except loop.LoopError as exc:
395
+ result.fail(str(exc))
396
+ return result
397
+
398
+ return _start_loop(project, "loop.predict", work)
399
+
400
+
401
+ def _project(store, project_id: str):
402
+ try:
403
+ return projects_mod.get(store, project_id, "local")
404
+ except StoreError as exc:
405
+ raise HTTPException(404, str(exc)) from None
406
+
407
+
408
+ def _image_root(project) -> Path:
409
+ return Path(project.root) if project.is_attached and project.root else media_root(project.id)
410
+
411
+
412
+ def _opened(store, folder: Path) -> dict[str, Any]:
413
+ try:
414
+ summary = attach.open_folder(store, folder)
415
+ except StoreError as exc:
416
+ raise HTTPException(400, str(exc)) from None
417
+ project = summary["project"]
418
+ return {
419
+ "project": project.id,
420
+ "name": project.name,
421
+ "images": summary["images"],
422
+ "imported": summary["shapes_imported"],
423
+ "writes_back": summary["writes_back"],
424
+ }
425
+
426
+
427
+ def _dialog_available() -> bool:
428
+ # A frozen build has no interpreter to run the dialog in (and the desktop
429
+ # window has its own); a headless Linux box has no display to show it on.
430
+ if getattr(sys, "frozen", False):
431
+ return False
432
+ if sys.platform.startswith("linux") and not os.environ.get("DISPLAY") and not os.environ.get("WAYLAND_DISPLAY"):
433
+ return False
434
+ try:
435
+ import tkinter # noqa: F401
436
+ except ImportError:
437
+ return False
438
+ return True
439
+
440
+
441
+ _dialog_lock = threading.Lock()
442
+
443
+ _DIALOG = (
444
+ "import tkinter, tkinter.filedialog as d\n"
445
+ "r = tkinter.Tk(); r.withdraw(); r.attributes('-topmost', True)\n"
446
+ "print(d.askdirectory(title='Open a folder in EasyAnnotate') or '', end='')\n"
447
+ )
448
+
449
+
450
+ def _run_dialog() -> str:
451
+ """In a child process: Tk wants its own main thread, which a request
452
+ handler is not, and a dialog left open must not wedge the server."""
453
+ try:
454
+ # -I: isolated. `-c` otherwise imports from the working directory
455
+ # first, and a tkinter.py planted in a dataset folder would run.
456
+ # UTF-8 both ways, or a folder named in Hindi comes back "cancelled".
457
+ done = subprocess.run(
458
+ [sys.executable, "-I", "-c", _DIALOG],
459
+ capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=600,
460
+ env=child_environment(PYTHONIOENCODING="utf-8"),
461
+ )
462
+ except (OSError, subprocess.TimeoutExpired):
463
+ return ""
464
+ return done.stdout.strip()
@@ -0,0 +1,154 @@
1
+ """Serving the pixels: full images and filmstrip thumbnails.
2
+
3
+ The only routes in the service that read a file the *user* put somewhere, so
4
+ this is where containment is checked. The rule is unchanged from the batch
5
+ API: a client names a project id and an image id, and the path comes out of the
6
+ database. Nothing here accepts a path.
7
+
8
+ Thumbnails are generated on demand and cached to disk beside the project.
9
+ Decoding a 4000x3000 JPEG per filmstrip cell is roughly 40ms; doing that for
10
+ sixty visible cells on every scroll is what makes an annotation tool feel slow
11
+ in a way no amount of front-end work can fix.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import hashlib
17
+ from pathlib import Path
18
+
19
+ from fastapi import APIRouter, Depends, HTTPException, Response
20
+ from fastapi.responses import FileResponse
21
+
22
+ from ...annotate import images as images_mod
23
+ from ...annotate import projects as projects_mod
24
+ from ...annotate.store import Store, StoreError
25
+ from ...core import imaging
26
+ from ..deps import get_store, media_root, principal, require_key, resolve_media
27
+
28
+ router = APIRouter(prefix="/api", tags=["media"], dependencies=[Depends(require_key)])
29
+
30
+ #: Thumbnail long edge. One size, because two sizes is a cache with a policy.
31
+ THUMB_EDGE = 200
32
+ #: Past this many pixels a thumbnail is refused rather than decoded: 200 MP
33
+ #: is already 600 MB of BGR. Aerial and pathology images this big belong in
34
+ #: image.tile first, which is the tool for them.
35
+ MAX_DECODE_PIXELS = 200_000_000
36
+
37
+ #: Browsers cache these hard: the bytes for a given image id never change --
38
+ #: an edit changes shapes, not pixels.
39
+ CACHE_CONTROL = "private, max-age=86400"
40
+
41
+ CONTENT_TYPES = {
42
+ ".jpg": "image/jpeg",
43
+ ".jpeg": "image/jpeg",
44
+ ".png": "image/png",
45
+ ".bmp": "image/bmp",
46
+ ".webp": "image/webp",
47
+ ".tif": "image/tiff",
48
+ ".tiff": "image/tiff",
49
+ }
50
+
51
+
52
+ def _locate(store: Store, project_id: str, image_id: str, owner: str) -> tuple[Path, object]:
53
+ """Resolve an image id to a real file, or fail with a status code."""
54
+ try:
55
+ project = projects_mod.get(store, project_id, owner)
56
+ image = images_mod.get(store, project, image_id)
57
+ except StoreError as exc:
58
+ raise HTTPException(404, str(exc)) from None
59
+
60
+ root = Path(project.root) if project.is_attached and project.root else media_root(project.id)
61
+ path = resolve_media(root, image.rel_path)
62
+ if not path.is_file():
63
+ raise HTTPException(404, f"{image.rel_path} is no longer on disk")
64
+ return path, image
65
+
66
+
67
+ @router.get("/projects/{project_id}/images/{image_id}/file")
68
+ def image_file(
69
+ project_id: str,
70
+ image_id: str,
71
+ store: Store = Depends(get_store),
72
+ owner: str = Depends(principal),
73
+ ) -> FileResponse:
74
+ path, _ = _locate(store, project_id, image_id, owner)
75
+ return FileResponse(
76
+ path,
77
+ media_type=CONTENT_TYPES.get(path.suffix.lower(), "application/octet-stream"),
78
+ headers={"Cache-Control": CACHE_CONTROL},
79
+ )
80
+
81
+
82
+ @router.get("/projects/{project_id}/images/{image_id}/thumb")
83
+ def image_thumb(
84
+ project_id: str,
85
+ image_id: str,
86
+ store: Store = Depends(get_store),
87
+ owner: str = Depends(principal),
88
+ ) -> Response:
89
+ path, image = _locate(store, project_id, image_id, owner)
90
+
91
+ # An image already smaller than a thumbnail is its own thumbnail. Decoding
92
+ # and re-encoding it would cost a JPEG generation and, at these sizes,
93
+ # routinely produce a *bigger* file than the original.
94
+ width, height = int(image.width), int(image.height)
95
+ if not (width and height):
96
+ try:
97
+ width, height = imaging.image_size(path)
98
+ except Exception:
99
+ width = height = 0
100
+ if width and height and max(width, height) <= THUMB_EDGE:
101
+ return FileResponse(
102
+ path,
103
+ media_type=CONTENT_TYPES.get(path.suffix.lower(), "image/jpeg"),
104
+ headers={"Cache-Control": CACHE_CONTROL},
105
+ )
106
+
107
+ cache_dir = media_root(project_id) / ".thumbs"
108
+ # Keyed on the source path and its mtime, so replacing an image on disk in
109
+ # an attached project invalidates the thumbnail without a sweep.
110
+ try:
111
+ stamp = f"{path}:{path.stat().st_mtime_ns}"
112
+ except OSError:
113
+ raise HTTPException(404, "image unreadable") from None
114
+ key = hashlib.sha256(stamp.encode("utf-8")).hexdigest()[:32]
115
+ cached = cache_dir / f"{key}.jpg"
116
+
117
+ if cached.is_file():
118
+ return FileResponse(
119
+ cached, media_type="image/jpeg", headers={"Cache-Control": CACHE_CONTROL}
120
+ )
121
+
122
+ # A header can claim any size. Refusing past this before decoding is what
123
+ # stops one crafted PNG from asking the server for gigabytes.
124
+ # Unmeasurable counts as too large: Pillow refuses to read the header of
125
+ # a decompression bomb at all, and decoding "size unknown" with OpenCV --
126
+ # which has no such guard -- is exactly the hole this closes.
127
+ if not (width and height) or width * height > MAX_DECODE_PIXELS:
128
+ raise HTTPException(413, "that image is too large, or too damaged, to preview")
129
+ try:
130
+ pixels = imaging.load_reduced(path, imaging.reduction_for(width, height, THUMB_EDGE))
131
+ except Exception:
132
+ # A corrupt file is a normal thing to find in a dataset -- it is one of
133
+ # the defects inspect.health reports. It must not be a 500.
134
+ raise HTTPException(422, "that image could not be decoded") from None
135
+
136
+ height, width = pixels.shape[:2]
137
+ scale = min(THUMB_EDGE / max(1, width), THUMB_EDGE / max(1, height), 1.0)
138
+ if scale < 1.0:
139
+ transform = imaging.make_resize(
140
+ width, height, max(1, round(width * scale)), max(1, round(height * scale)), "fit"
141
+ )
142
+ pixels = transform.image(pixels)
143
+
144
+ data = imaging.encode(pixels, ".jpg", quality=78)
145
+ try:
146
+ cache_dir.mkdir(parents=True, exist_ok=True)
147
+ cached.write_bytes(data)
148
+ except OSError:
149
+ # A cache that cannot be written is a slow tool, not a broken one.
150
+ pass
151
+
152
+ return Response(
153
+ content=data, media_type="image/jpeg", headers={"Cache-Control": CACHE_CONTROL}
154
+ )