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,175 @@
1
+ """Turning a model's mask into a shape a person can edit.
2
+
3
+ This lives in the **base package**, not in the tools distribution, and that is
4
+ deliberate. A segmentation model returns a raster mask; what an annotation tool
5
+ needs is an outline with a manageable number of draggable vertices. Those are
6
+ different problems, and only the second one is ours.
7
+
8
+ The legacy SAM script did no simplification at all: it wrote every boundary
9
+ pixel as a polygon vertex, which is why its XML ran to hundreds of kilobytes
10
+ per image and why dragging a point in it was hopeless. A 512x512 mask has a
11
+ boundary thousands of pixels long. Nobody edits a two-thousand-vertex polygon.
12
+
13
+ So: contours, then Douglas-Peucker simplification, then a hard vertex cap, then
14
+ clamping to the image. Pure OpenCV and numpy -- no torch, nothing that only
15
+ exists when a sidecar is installed, and therefore testable without one.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ from typing import Any
21
+
22
+ import numpy as np
23
+
24
+ from ...core.annotations.model import Point, Shape
25
+
26
+ #: Simplification tolerance as a fraction of the contour's own perimeter.
27
+ #: Scale-free on purpose: a fixed pixel epsilon over-simplifies small objects
28
+ #: and under-simplifies large ones, and datasets contain both.
29
+ DEFAULT_EPSILON = 0.004
30
+
31
+ #: Above this, a polygon stops being editable and starts being a blob. The cap
32
+ #: is enforced by relaxing epsilon until it fits, so the shape degrades
33
+ #: smoothly instead of being truncated into nonsense.
34
+ MAX_VERTICES = 80
35
+
36
+ #: Below this many pixels a "mask" is noise, not an object.
37
+ MIN_AREA = 24
38
+
39
+
40
+ class MaskError(ValueError):
41
+ """Raised when a mask cannot be turned into a usable outline."""
42
+
43
+
44
+ def _as_binary(mask: Any) -> np.ndarray:
45
+ """Accept whatever a model handed back and make it a 0/1 uint8 array."""
46
+ array = np.asarray(mask)
47
+ if array.ndim == 3:
48
+ # A single-channel mask with a trailing axis, or a batch of one.
49
+ if array.shape[-1] == 1:
50
+ array = array[..., 0]
51
+ elif array.shape[0] == 1:
52
+ array = array[0]
53
+ else:
54
+ raise MaskError(f"expected a 2D mask, got shape {array.shape}")
55
+ if array.ndim != 2:
56
+ raise MaskError(f"expected a 2D mask, got {array.ndim} dimensions")
57
+
58
+ if array.dtype == bool:
59
+ return array.astype(np.uint8)
60
+ if np.issubdtype(array.dtype, np.floating):
61
+ # Models emit logits or probabilities; 0.5 is the conventional cut.
62
+ return (array > 0.5).astype(np.uint8)
63
+ return (array > 0).astype(np.uint8)
64
+
65
+
66
+ def mask_to_polygon(
67
+ mask: Any,
68
+ *,
69
+ epsilon: float = DEFAULT_EPSILON,
70
+ max_vertices: int = MAX_VERTICES,
71
+ min_area: int = MIN_AREA,
72
+ ) -> list[Point] | None:
73
+ """The largest outline in ``mask``, simplified to something editable.
74
+
75
+ Returns ``None`` when the mask holds nothing worth keeping, which is a
76
+ normal answer -- a click on background produces an empty mask, and that
77
+ should leave the canvas alone rather than raise.
78
+
79
+ Only the largest contour is kept. A mask with several disconnected blobs
80
+ almost always means the model caught something extra, and one shape per
81
+ click is what the interaction promises; the alternative -- silently
82
+ creating four shapes from one click -- is worse.
83
+ """
84
+ import cv2
85
+
86
+ binary = _as_binary(mask)
87
+ if not binary.any():
88
+ return None
89
+
90
+ contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
91
+ if not contours:
92
+ return None
93
+
94
+ largest = max(contours, key=cv2.contourArea)
95
+ if cv2.contourArea(largest) < min_area:
96
+ return None
97
+
98
+ simplified = _simplify(largest, epsilon, max_vertices)
99
+ points = [(int(p[0][0]), int(p[0][1])) for p in simplified]
100
+ # Fewer than three points cannot enclose an area, and every format
101
+ # downstream would reject it.
102
+ return points if len(points) >= 3 else None
103
+
104
+
105
+ def _simplify(contour: Any, epsilon: float, max_vertices: int) -> Any:
106
+ """Douglas-Peucker, relaxed until the vertex cap is met.
107
+
108
+ Doubling epsilon rather than truncating the point list matters: dropping
109
+ the tail of a contour leaves a shape with a straight line where the object
110
+ used to be, which looks like a bug. Relaxing keeps the outline closed and
111
+ recognisable, just coarser.
112
+ """
113
+ import cv2
114
+
115
+ perimeter = cv2.arcLength(contour, True)
116
+ if perimeter <= 0:
117
+ return contour
118
+
119
+ tolerance = epsilon
120
+ simplified = cv2.approxPolyDP(contour, tolerance * perimeter, True)
121
+ attempts = 0
122
+ while len(simplified) > max_vertices and attempts < 12:
123
+ tolerance *= 1.7
124
+ simplified = cv2.approxPolyDP(contour, tolerance * perimeter, True)
125
+ attempts += 1
126
+ return simplified
127
+
128
+
129
+ def mask_to_shape(
130
+ mask: Any,
131
+ label: str,
132
+ width: int,
133
+ height: int,
134
+ *,
135
+ confidence: float | None = None,
136
+ **options: Any,
137
+ ) -> Shape | None:
138
+ """A mask, as a clamped, labelled :class:`Shape` ready to store."""
139
+ polygon = mask_to_polygon(mask, **options)
140
+ if polygon is None:
141
+ return None
142
+
143
+ xs = [p[0] for p in polygon]
144
+ ys = [p[1] for p in polygon]
145
+ shape = Shape(
146
+ label=label,
147
+ bbox=(min(xs), min(ys), max(xs), max(ys)),
148
+ polygon=polygon,
149
+ confidence=confidence,
150
+ )
151
+ # The same clamp the editor's own saves go through, so a mask that runs off
152
+ # the edge of the image cannot produce coordinates no format can express.
153
+ return shape.clamped(width, height) if width and height else shape
154
+
155
+
156
+ def simplify_polygon(
157
+ points: list[Point],
158
+ *,
159
+ epsilon: float = DEFAULT_EPSILON,
160
+ max_vertices: int = MAX_VERTICES,
161
+ ) -> list[Point]:
162
+ """Simplify an outline that is already a polygon.
163
+
164
+ For predictions imported from a model that emitted polygons directly --
165
+ those are just as capable of arriving with two thousand vertices as a mask
166
+ is, and they land in exactly the same editor.
167
+ """
168
+ if len(points) <= 3:
169
+ return list(points)
170
+
171
+
172
+ contour = np.array([[list(p)] for p in points], dtype=np.int32)
173
+ simplified = _simplify(contour, epsilon, max_vertices)
174
+ out = [(int(p[0][0]), int(p[0][1])) for p in simplified]
175
+ return out if len(out) >= 3 else list(points)
@@ -0,0 +1,238 @@
1
+ """The contract between the editor and a heavy tool.
2
+
3
+ A "heavy tool" is anything that wants PyTorch and ideally a GPU -- SAM, a
4
+ detector running inference. The base package must never import torch, and must
5
+ never import a module that imports torch, because:
6
+
7
+ * ``import torch`` costs 3-8 seconds and roughly 500 MB of RSS. In-process,
8
+ every user pays that at startup, including the ones who never use it.
9
+ * A CUDA out-of-memory or a native segfault takes down whatever process it
10
+ happens in. In a sidecar that is the sidecar; the editor greys out one button
11
+ and **the person keeps drawing boxes**.
12
+ * The torch x CUDA x numpy version matrix is exactly what makes ``pip install``
13
+ fail. A separate process means a separate environment, which means our
14
+ dependency resolver is never involved in it.
15
+
16
+ So the boundary is a process, always -- including on a laptop. This module
17
+ defines what crosses it, and nothing here imports anything heavier than the
18
+ standard library.
19
+
20
+ The wire is newline-delimited JSON, one object per line. The same messages
21
+ travel over a subprocess's stdio and over HTTP to a hosted GPU service, so the
22
+ two implementations differ only in transport.
23
+
24
+ -> {"id": 8, "method": "invoke",
25
+ "params": {"tool": "sam2.box", "image_id": "8f3c", "box": [1,2,3,4]}}
26
+ <- {"id": 8, "ok": true, "result": {"shapes": [...], "ms": 48}}
27
+ <- {"id": 8, "ok": false, "error": {"code": "not_ready", "retry_after_ms": 800}}
28
+
29
+ **Every request gets exactly one reply, including when the handler raises.**
30
+ That rule has a test, because breaking it is precisely how the legacy SAM
31
+ script hung: its worker caught exceptions, printed them, and put nothing on the
32
+ queue, while the UI blocked forever on a read inside a mouse callback.
33
+ """
34
+
35
+ from __future__ import annotations
36
+
37
+ import json
38
+ from dataclasses import dataclass, field
39
+ from typing import Any, Protocol
40
+
41
+ #: Bumped when a change would stop an older peer understanding a newer one.
42
+ PROTOCOL_VERSION = 1
43
+
44
+ #: How long each method may take before the caller gives up. Encoding an image
45
+ #: is genuinely slow; answering a click is not, and a slow one is a bug.
46
+ DEFAULT_TIMEOUTS = {
47
+ # Generous: a sidecar answers one request at a time, and a native model
48
+ # load can hold the GIL for tens of seconds. A short health timeout used
49
+ # to kill a perfectly busy sidecar.
50
+ "describe": 30.0,
51
+ "health": 30.0,
52
+ "prepare": 30.0,
53
+ # A tool replies promptly or says not_ready -- except that a native model
54
+ # load (torch.jit.load of CLIP's 338 MB) can hold the GIL for tens of
55
+ # seconds and delay even that reply. Timing out kills and restarts the
56
+ # sidecar, which would throw the loaded models away, so this is generous.
57
+ "invoke": 45.0,
58
+ }
59
+
60
+
61
+ class ToolError(Exception):
62
+ """A tool failed. Carries a machine-readable code so callers can branch."""
63
+
64
+ def __init__(self, message: str, *, code: str = "error", retry_after_ms: int = 0) -> None:
65
+ super().__init__(message)
66
+ self.code = code
67
+ self.retry_after_ms = retry_after_ms
68
+
69
+ def as_dict(self) -> dict[str, Any]:
70
+ out: dict[str, Any] = {"code": self.code, "message": str(self)}
71
+ if self.retry_after_ms:
72
+ out["retry_after_ms"] = self.retry_after_ms
73
+ return out
74
+
75
+
76
+ class ToolUnavailable(ToolError):
77
+ """The tool is not installed, or its process will not start.
78
+
79
+ Not an error condition for the product: the editor simply does not show the
80
+ button. Manual annotation is never blocked by a missing tool.
81
+ """
82
+
83
+ def __init__(self, message: str) -> None:
84
+ super().__init__(message, code="unavailable")
85
+
86
+
87
+ class ToolNotReady(ToolError):
88
+ """Correct request, but the tool needs a moment -- usually a cold encode.
89
+
90
+ Distinct from a failure on purpose: the UI spins on this one click and
91
+ retries, rather than showing an error the user can do nothing about.
92
+ """
93
+
94
+ def __init__(self, message: str, *, retry_after_ms: int = 500) -> None:
95
+ super().__init__(message, code="not_ready", retry_after_ms=retry_after_ms)
96
+
97
+
98
+ @dataclass(frozen=True)
99
+ class ToolSpec:
100
+ """What a tool is, described well enough for the UI to render it.
101
+
102
+ ``inputs`` is a JSON-schema fragment, so the tools panel builds its controls
103
+ generically -- the same "declare once, render everywhere" the operation
104
+ registry already uses, applied to the second contract. Shipping a new tool
105
+ means shipping a sidecar that advertises a spec; no front-end change.
106
+ """
107
+
108
+ name: str # 'sam2.box', 'detect.infer'
109
+ title: str
110
+ summary: str
111
+ kind: str = "interactive" # 'interactive' | 'batch'
112
+ inputs: dict[str, Any] = field(default_factory=dict)
113
+ version: str = "0"
114
+ requires: tuple[str, ...] = () # 'gpu', 'prepare'
115
+
116
+ def as_dict(self) -> dict[str, Any]:
117
+ return {
118
+ "name": self.name,
119
+ "title": self.title,
120
+ "summary": self.summary,
121
+ "kind": self.kind,
122
+ "inputs": dict(self.inputs),
123
+ "version": self.version,
124
+ "requires": list(self.requires),
125
+ }
126
+
127
+ @classmethod
128
+ def from_dict(cls, raw: dict[str, Any]) -> ToolSpec:
129
+ if not isinstance(raw, dict) or not raw.get("name"):
130
+ raise ToolError(f"a tool spec needs a name, got {raw!r}", code="bad_spec")
131
+ return cls(
132
+ name=str(raw["name"]),
133
+ title=str(raw.get("title") or raw["name"]),
134
+ summary=str(raw.get("summary") or ""),
135
+ kind=str(raw.get("kind") or "interactive"),
136
+ inputs=dict(raw.get("inputs") or {}),
137
+ version=str(raw.get("version") or "0"),
138
+ requires=tuple(str(r) for r in raw.get("requires") or ()),
139
+ )
140
+
141
+
142
+ @dataclass(frozen=True)
143
+ class ToolHealth:
144
+ """Whether a tool can be used right now, and why not if it cannot."""
145
+
146
+ state: str # 'ready' | 'loading' | 'unavailable'
147
+ detail: str = ""
148
+
149
+ @property
150
+ def ready(self) -> bool:
151
+ return self.state == "ready"
152
+
153
+ def as_dict(self) -> dict[str, Any]:
154
+ return {"state": self.state, "detail": self.detail}
155
+
156
+ @classmethod
157
+ def from_dict(cls, raw: dict[str, Any]) -> ToolHealth:
158
+ return cls(state=str(raw.get("state") or "unavailable"), detail=str(raw.get("detail") or ""))
159
+
160
+
161
+ READY = ToolHealth("ready")
162
+
163
+
164
+ class Tool(Protocol):
165
+ """What every backend implements, whatever is behind it."""
166
+
167
+ def describe(self) -> list[ToolSpec]: ...
168
+
169
+ def health(self, name: str = "") -> ToolHealth: ...
170
+
171
+ def prepare(self, name: str, image_id: str, source: Any) -> None:
172
+ """Warm a tool for an image -- the encode-ahead hook.
173
+
174
+ Cheap and idempotent by contract, because the editor calls it for the
175
+ current image and the next one every time you navigate.
176
+ """
177
+ ...
178
+
179
+ def invoke(self, name: str, request: dict[str, Any]) -> dict[str, Any]: ...
180
+
181
+
182
+ # ------------------------------------------------------------------ framing
183
+
184
+ def encode_message(payload: dict[str, Any]) -> bytes:
185
+ """One JSON object, one line.
186
+
187
+ ``ensure_ascii`` keeps the frame single-byte-safe regardless of what the
188
+ pipe's encoding turns out to be on Windows, and the explicit separators
189
+ guarantee no stray newline can appear inside a frame.
190
+ """
191
+ line = json.dumps(payload, ensure_ascii=True, separators=(",", ":"))
192
+ return (line + "\n").encode("utf-8")
193
+
194
+
195
+ def decode_message(line: str | bytes) -> dict[str, Any]:
196
+ if isinstance(line, bytes):
197
+ line = line.decode("utf-8", errors="replace")
198
+ text = line.strip()
199
+ if not text:
200
+ raise ToolError("empty frame", code="protocol")
201
+ try:
202
+ payload = json.loads(text)
203
+ except json.JSONDecodeError as exc:
204
+ raise ToolError(f"unparseable frame: {text[:120]!r}", code="protocol") from exc
205
+ if not isinstance(payload, dict):
206
+ raise ToolError(f"a frame must be an object, got {type(payload).__name__}", code="protocol")
207
+ return payload
208
+
209
+
210
+ def request(message_id: int, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
211
+ return {"v": PROTOCOL_VERSION, "id": message_id, "method": method, "params": params or {}}
212
+
213
+
214
+ def ok(message_id: int, result: Any) -> dict[str, Any]:
215
+ return {"v": PROTOCOL_VERSION, "id": message_id, "ok": True, "result": result}
216
+
217
+
218
+ def fail(message_id: int, error: BaseException | ToolError) -> dict[str, Any]:
219
+ detail = (
220
+ error.as_dict()
221
+ if isinstance(error, ToolError)
222
+ else {"code": type(error).__name__, "message": str(error)}
223
+ )
224
+ return {"v": PROTOCOL_VERSION, "id": message_id, "ok": False, "error": detail}
225
+
226
+
227
+ def raise_for(payload: dict[str, Any]) -> Any:
228
+ """Turn a reply into a result or an exception of the right class."""
229
+ if payload.get("ok"):
230
+ return payload.get("result")
231
+ error = payload.get("error") or {}
232
+ code = str(error.get("code") or "error")
233
+ message = str(error.get("message") or "the tool failed without saying why")
234
+ if code == "not_ready":
235
+ raise ToolNotReady(message, retry_after_ms=int(error.get("retry_after_ms") or 500))
236
+ if code == "unavailable":
237
+ raise ToolUnavailable(message)
238
+ raise ToolError(message, code=code, retry_after_ms=int(error.get("retry_after_ms") or 0))
@@ -0,0 +1,196 @@
1
+ """Which heavy tools exist right now, if any.
2
+
3
+ The rule this module enforces: **a heavy tool's absence is never an error.**
4
+ ``available()`` returning an empty list is a normal, tested state — it is what
5
+ the base wheel does, and the editor must be fully usable in it. Manual
6
+ annotation is never blocked by a missing tool.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import os
12
+ import shutil
13
+ import sys
14
+ from typing import Any
15
+
16
+ from .local import LocalTool, python_for_tools
17
+ from .protocol import Tool, ToolHealth, ToolNotReady, ToolSpec
18
+
19
+ #: Set to a module name to run that sidecar, e.g. ``data_factory.annotate.tools.fake``.
20
+ #: The real SAM tool ships in a separate distribution and names itself here.
21
+ TOOLS_MODULE_ENV = "DATAFACTORY_TOOLS_MODULE"
22
+
23
+ #: Set to "0" to force the base-wheel behaviour even where a tool is installed.
24
+ TOOLS_ENABLED_ENV = "DATAFACTORY_TOOLS"
25
+ #: What `easyannotate tools install` sets up. Used only when a tools
26
+ #: environment exists, so a plain install never spawns a doomed subprocess.
27
+ DEFAULT_TOOLS_MODULE = "easyannotate_tools.sidecar"
28
+
29
+
30
+ class NullTool:
31
+ """The default backend: nothing installed, nothing offered."""
32
+
33
+ def describe(self) -> list[ToolSpec]:
34
+ return []
35
+
36
+ def health(self, name: str = "") -> ToolHealth:
37
+ return ToolHealth("unavailable", "no heavy tools are installed")
38
+
39
+ def prepare(self, name: str, image_id: str, source: Any = None) -> None:
40
+ return None
41
+
42
+ def invoke(self, name: str, payload: dict[str, Any]) -> dict[str, Any]:
43
+ from .protocol import ToolUnavailable
44
+
45
+ raise ToolUnavailable("no heavy tools are installed")
46
+
47
+ def close(self) -> None:
48
+ return None
49
+
50
+
51
+ class ToolRegistry:
52
+ """Discovers a backend once and answers questions about it.
53
+
54
+ Discovery is lazy and never raises: the first call decides, and a failure
55
+ to start becomes an empty tool list plus a reason, not an exception in a
56
+ request handler.
57
+ """
58
+
59
+ def __init__(self, backend: Tool | None = None) -> None:
60
+ self._backend: Tool | None = backend
61
+ self._resolved = backend is not None
62
+ self._reason = ""
63
+ self._paused = ""
64
+
65
+ # -- discovery ---------------------------------------------------------
66
+ def pause(self, reason: str) -> None:
67
+ """Stop the sidecar and start none until ``resume``.
68
+
69
+ For an install: the editor keeps asking (the tool list, a prepare on
70
+ every image), and each ask would start a sidecar from the very
71
+ environment being replaced -- importing torch, whose DLLs Windows
72
+ then refuses to let the installer overwrite.
73
+ """
74
+ self._paused = reason
75
+ self.close()
76
+
77
+ def resume(self) -> None:
78
+ self._paused = ""
79
+ self.close() # rediscover on the next look
80
+
81
+ def backend(self) -> Tool:
82
+ if self._paused:
83
+ self._reason = self._paused
84
+ return NullTool()
85
+ if not self._resolved:
86
+ self._backend = self._discover()
87
+ self._resolved = True
88
+ assert self._backend is not None
89
+ return self._backend
90
+
91
+ def _discover(self) -> Tool:
92
+ if os.environ.get(TOOLS_ENABLED_ENV, "1") in ("0", "false", "no"):
93
+ self._reason = f"disabled by {TOOLS_ENABLED_ENV}"
94
+ return NullTool()
95
+
96
+ module = os.environ.get(TOOLS_MODULE_ENV, "").strip()
97
+ interpreter = python_for_tools()
98
+ if not module:
99
+ if interpreter == sys.executable and not os.environ.get("DATAFACTORY_TOOLS_PYTHON"):
100
+ self._reason = "no tools installed -- run: easyannotate tools install"
101
+ return NullTool()
102
+ module = DEFAULT_TOOLS_MODULE
103
+
104
+ if not shutil.which(interpreter) and not os.path.isfile(interpreter):
105
+ self._reason = f"interpreter not found: {interpreter}"
106
+ return NullTool()
107
+
108
+ tool = LocalTool([interpreter, "-m", module])
109
+ try:
110
+ tool.describe() # the handshake: if this fails, we have nothing
111
+ except Exception as exc:
112
+ self._reason = f"{module} did not start: {exc}"
113
+ try:
114
+ tool.close()
115
+ except Exception:
116
+ pass
117
+ return NullTool()
118
+ self._reason = ""
119
+ return tool
120
+
121
+ # -- queries -----------------------------------------------------------
122
+ def available(self) -> list[ToolSpec]:
123
+ """Every usable tool. Empty is normal."""
124
+ try:
125
+ return self.backend().describe()
126
+ except Exception as exc:
127
+ self._reason = str(exc)
128
+ return []
129
+
130
+ def health(self, name: str = "") -> ToolHealth:
131
+ try:
132
+ return self.backend().health(name)
133
+ except Exception as exc:
134
+ return ToolHealth("unavailable", str(exc))
135
+
136
+ def as_dict(self) -> dict[str, Any]:
137
+ """What ``GET /api/tools`` returns.
138
+
139
+ The UI renders a button only for a tool that is listed *and* healthy,
140
+ so there are never dead buttons and never install nags in the toolbar.
141
+ """
142
+ specs = self.available()
143
+ health = self.health() if specs else ToolHealth("unavailable", self._reason)
144
+ return {
145
+ "tools": [
146
+ {**spec.as_dict(), "health": health.as_dict()}
147
+ for spec in specs
148
+ if health.ready
149
+ ],
150
+ "detail": self._reason or health.detail,
151
+ }
152
+
153
+ def prepare(self, name: str, image_id: str, source: Any = None) -> None:
154
+ """Warm a tool for an image. Best-effort by contract.
155
+
156
+ Never raises: this is called speculatively for the next image on every
157
+ navigation, and a failed warm-up must not interrupt annotating.
158
+ """
159
+ try:
160
+ self.backend().prepare(name, image_id, source)
161
+ except Exception:
162
+ return
163
+
164
+ def invoke(self, name: str, payload: dict[str, Any]) -> dict[str, Any]:
165
+ """Run a tool. Raises ToolError subclasses, which the router maps to
166
+ HTTP status codes."""
167
+ return self.backend().invoke(name, payload)
168
+
169
+ def invoke_waiting(self, name: str, payload: dict[str, Any], *, budget_s: float = 300.0) -> dict[str, Any]:
170
+ """Run a tool, waiting through not_ready replies -- a model loading,
171
+ an image still being worked on -- for up to ``budget_s``. For batch
172
+ work, where nobody is watching a single request. Other errors raise."""
173
+ import time
174
+
175
+ deadline = time.time() + budget_s
176
+ while True:
177
+ try:
178
+ return self.backend().invoke(name, payload)
179
+ except ToolNotReady as exc:
180
+ if time.time() >= deadline:
181
+ raise
182
+ time.sleep(max(0.2, (exc.retry_after_ms or 500) / 1000.0))
183
+
184
+ def spec(self, name: str) -> ToolSpec | None:
185
+ return next((s for s in self.available() if s.name == name), None)
186
+
187
+ def close(self) -> None:
188
+ backend = self._backend
189
+ self._backend = None
190
+ self._resolved = False
191
+ if backend is not None and hasattr(backend, "close"):
192
+ backend.close()
193
+
194
+
195
+ #: The process-wide registry the service uses.
196
+ REGISTRY = ToolRegistry()
@@ -0,0 +1,83 @@
1
+ """A tool's reply, read into shapes -- whichever form it chose.
2
+
3
+ Shared by the HTTP routes and the command line (``easyannotate predict``),
4
+ which is why it lives here and not in the service layer: ``annotate/`` must
5
+ not import FastAPI, and the CLI must not need it.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from typing import Any
11
+
12
+ from . import postprocess
13
+
14
+
15
+ def shapes_from_result(result: Any, label: str, width: int, height: int) -> list[Any]:
16
+ """Read a tool's reply into shapes, whichever form it used.
17
+
18
+ A tool may answer with a mask, with polygons, or with boxes. All three are
19
+ reasonable things for a model to produce, and none of them should require
20
+ a different endpoint.
21
+ """
22
+ if not isinstance(result, dict):
23
+ return []
24
+ made = []
25
+ name = label or "object"
26
+
27
+ from ...core.annotations.model import AnnotationError, Shape
28
+
29
+ # Ready-made shapes: the most natural form for a tool to answer in, and
30
+ # what the reference sidecar uses. Parsed through Shape.from_dict because
31
+ # a sidecar is a separate process -- possibly a third party's -- and its
32
+ # output is no more trusted than a browser's.
33
+ for raw in result.get("shapes") or []:
34
+ if not isinstance(raw, dict):
35
+ continue
36
+ payload = dict(raw)
37
+ if label:
38
+ payload["label"] = label
39
+ payload.setdefault("label", name)
40
+ try:
41
+ shape = Shape.from_dict(payload)
42
+ except AnnotationError:
43
+ continue
44
+ if shape.polygon and len(shape.polygon) > 3:
45
+ shape.polygon = postprocess.simplify_polygon(shape.polygon)
46
+ made.append(shape.clamped(width, height) if width and height else shape)
47
+
48
+ mask = result.get("mask")
49
+ if mask is not None:
50
+ shape = postprocess.mask_to_shape(
51
+ mask, name, width, height, confidence=result.get("score")
52
+ )
53
+ if shape is not None:
54
+ made.append(shape)
55
+
56
+ for polygon in result.get("polygons") or []:
57
+ points = [(int(x), int(y)) for x, y in polygon]
58
+ if len(points) < 3:
59
+ continue
60
+ simplified = postprocess.simplify_polygon(points)
61
+ xs = [p[0] for p in simplified]
62
+ ys = [p[1] for p in simplified]
63
+ made.append(
64
+ Shape(
65
+ label=name,
66
+ bbox=(min(xs), min(ys), max(xs), max(ys)),
67
+ polygon=simplified,
68
+ confidence=result.get("score"),
69
+ ).clamped(width, height)
70
+ )
71
+
72
+ for box in result.get("boxes") or []:
73
+ try:
74
+ x1, y1, x2, y2 = (int(v) for v in box[:4])
75
+ except (TypeError, ValueError):
76
+ continue
77
+ made.append(
78
+ Shape(label=name, bbox=(x1, y1, x2, y2), confidence=result.get("score")).clamped(
79
+ width, height
80
+ )
81
+ )
82
+
83
+ return made