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.
- data_factory/__init__.py +82 -0
- data_factory/__main__.py +6 -0
- data_factory/annotate/__init__.py +15 -0
- data_factory/annotate/attach.py +398 -0
- data_factory/annotate/demo.py +161 -0
- data_factory/annotate/images.py +443 -0
- data_factory/annotate/labels.py +399 -0
- data_factory/annotate/loop.py +359 -0
- data_factory/annotate/projects.py +207 -0
- data_factory/annotate/review.py +471 -0
- data_factory/annotate/schema.sql +171 -0
- data_factory/annotate/shapes.py +488 -0
- data_factory/annotate/store.py +292 -0
- data_factory/annotate/tools/__init__.py +39 -0
- data_factory/annotate/tools/fake.py +170 -0
- data_factory/annotate/tools/install.py +254 -0
- data_factory/annotate/tools/local.py +389 -0
- data_factory/annotate/tools/postprocess.py +175 -0
- data_factory/annotate/tools/protocol.py +238 -0
- data_factory/annotate/tools/registry.py +196 -0
- data_factory/annotate/tools/results.py +83 -0
- data_factory/annotate/tools/serve.py +106 -0
- data_factory/cli/__init__.py +21 -0
- data_factory/cli/main.py +837 -0
- data_factory/cli/menu.py +173 -0
- data_factory/cli/render.py +158 -0
- data_factory/core/__init__.py +11 -0
- data_factory/core/annotations/__init__.py +5 -0
- data_factory/core/annotations/coco.py +394 -0
- data_factory/core/annotations/csvfmt.py +174 -0
- data_factory/core/annotations/dota.py +98 -0
- data_factory/core/annotations/formats.py +626 -0
- data_factory/core/annotations/labelme.py +153 -0
- data_factory/core/annotations/model.py +334 -0
- data_factory/core/annotations/voc.py +231 -0
- data_factory/core/annotations/yolo.py +283 -0
- data_factory/core/bktree.py +89 -0
- data_factory/core/fs.py +245 -0
- data_factory/core/imaging.py +626 -0
- data_factory/core/ops/__init__.py +44 -0
- data_factory/core/ops/analyze.py +383 -0
- data_factory/core/ops/annotate_export.py +326 -0
- data_factory/core/ops/audit.py +274 -0
- data_factory/core/ops/augment.py +454 -0
- data_factory/core/ops/collect.py +241 -0
- data_factory/core/ops/combine.py +582 -0
- data_factory/core/ops/convert.py +212 -0
- data_factory/core/ops/dataset.py +246 -0
- data_factory/core/ops/dedup.py +235 -0
- data_factory/core/ops/export.py +168 -0
- data_factory/core/ops/image.py +407 -0
- data_factory/core/ops/labels.py +215 -0
- data_factory/core/ops/pairing.py +133 -0
- data_factory/core/ops/rename.py +154 -0
- data_factory/core/ops/report.py +323 -0
- data_factory/core/ops/visualize.py +164 -0
- data_factory/core/pairs.py +144 -0
- data_factory/core/parallel.py +191 -0
- data_factory/core/provenance.py +136 -0
- data_factory/core/registry.py +339 -0
- data_factory/core/stats.py +403 -0
- data_factory/core/types.py +148 -0
- data_factory/core/writer.py +194 -0
- data_factory/desktop.py +207 -0
- data_factory/hardware.py +243 -0
- data_factory/pipeline.py +192 -0
- data_factory/py.typed +0 -0
- data_factory/service/__init__.py +26 -0
- data_factory/service/app.py +483 -0
- data_factory/service/binding.py +174 -0
- data_factory/service/deps.py +133 -0
- data_factory/service/jobs.py +177 -0
- data_factory/service/limits.py +71 -0
- data_factory/service/routers/__init__.py +11 -0
- data_factory/service/routers/annotate.py +582 -0
- data_factory/service/routers/local.py +464 -0
- data_factory/service/routers/media.py +154 -0
- data_factory/service/routers/predictions.py +116 -0
- data_factory/service/routers/promote.py +182 -0
- data_factory/service/routers/tools.py +308 -0
- data_factory/service/static/annotate/api.js +246 -0
- data_factory/service/static/annotate/app.js +1696 -0
- data_factory/service/static/annotate/assist.js +106 -0
- data_factory/service/static/annotate/filmstrip.js +286 -0
- data_factory/service/static/annotate/hit.js +146 -0
- data_factory/service/static/annotate/labels.js +197 -0
- data_factory/service/static/annotate/render.js +286 -0
- data_factory/service/static/annotate/scene.js +277 -0
- data_factory/service/static/annotate/shapelist.js +72 -0
- data_factory/service/static/annotate/tools/box.js +96 -0
- data_factory/service/static/annotate/tools/line.js +96 -0
- data_factory/service/static/annotate/tools/obb.js +88 -0
- data_factory/service/static/annotate/tools/point.js +49 -0
- data_factory/service/static/annotate/tools/polygon.js +110 -0
- data_factory/service/static/annotate/tools/select.js +227 -0
- data_factory/service/static/annotate/undo.js +176 -0
- data_factory/service/static/annotate/viewport.js +156 -0
- data_factory/service/static/annotate.html +390 -0
- data_factory/service/static/index.html +632 -0
- data_factory/service/workspace.py +244 -0
- easyannotate/__init__.py +64 -0
- easyannotate/__main__.py +5 -0
- easyannotate/project.py +181 -0
- easyannotate/py.typed +0 -0
- easyannotate-0.4.0.dist-info/METADATA +767 -0
- easyannotate-0.4.0.dist-info/RECORD +109 -0
- easyannotate-0.4.0.dist-info/WHEEL +4 -0
- easyannotate-0.4.0.dist-info/entry_points.txt +4 -0
- 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
|