emberlens-sdk 0.2.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.
emberlens/__init__.py ADDED
@@ -0,0 +1,15 @@
1
+ """Emberlens SDK: open a Emberlens export (COCO, YOLO or Pascal VOC) and use it for training.
2
+
3
+ import emberlens
4
+ ds = emberlens.load("fruit-stand-coco.zip")
5
+ print(ds.summary())
6
+ unripe = ds.filter(cls="Mango", condition="Unripe")
7
+
8
+ See sdk/README.md for the full guide.
9
+ """
10
+
11
+ from .model import Box, Dataset, Image
12
+ from .load import load
13
+
14
+ __version__ = "0.2.0"
15
+ __all__ = ["Box", "Dataset", "Image", "load", "__version__"]
emberlens/__main__.py ADDED
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ sys.exit(main())
emberlens/card.py ADDED
@@ -0,0 +1,47 @@
1
+ """The emberlens.json dataset card (sdk/schema/emberlens-card.schema.json).
2
+
3
+ It maps every label name in the export to its parts, so a joined name like
4
+ "mango_alphonso_ripe" is split without guessing.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ from pathlib import Path
11
+ from typing import Dict, Optional, Tuple
12
+
13
+ CARD_FILE = "emberlens.json"
14
+ CARD_VERSION = 1
15
+
16
+
17
+ def read_card(root: Path) -> Optional[dict]:
18
+ path = root / CARD_FILE
19
+ if not path.is_file():
20
+ return None
21
+ try:
22
+ card = json.loads(path.read_text(encoding="utf-8"))
23
+ except (OSError, ValueError):
24
+ return None
25
+ if not isinstance(card, dict):
26
+ return None
27
+ version = card.get("emberlens_card_version")
28
+ if isinstance(version, int) and version > CARD_VERSION:
29
+ from .errors import EmberlensError
30
+
31
+ raise EmberlensError(
32
+ "This export was made by a newer Emberlens app. Get the newest SDK "
33
+ "from the Emberlens repository and try again."
34
+ )
35
+ return card
36
+
37
+
38
+ def label_parts(card: Optional[dict]) -> Dict[str, Tuple[str, Dict[str, str]]]:
39
+ """{label name: (class, {sub-category: value})} from the card."""
40
+ out: Dict[str, Tuple[str, Dict[str, str]]] = {}
41
+ if not card:
42
+ return out
43
+ for entry in card.get("labels") or []:
44
+ name = entry.get("name")
45
+ if isinstance(name, str):
46
+ out[name] = (str(entry.get("class") or name), dict(entry.get("attributes") or {}))
47
+ return out
emberlens/cli.py ADDED
@@ -0,0 +1,331 @@
1
+ """The `emberlens` command. Run `emberlens help` for the list."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import json
7
+ import shlex
8
+ import sys
9
+ import webbrowser
10
+ from pathlib import Path
11
+ from typing import List, Optional
12
+
13
+ from . import __version__
14
+ from .command import command, program_name
15
+ from .errors import MissingExtra, EmberlensError
16
+ from .load import load
17
+ from .paths import export_stem, free_path
18
+
19
+ _EXAMPLES = """
20
+ examples:
21
+ {prog} info fruit-stand-coco.zip
22
+ {prog} recipe "Fruit survey.emberlens-project.json"
23
+ {prog} preview fruit-stand-coco.zip
24
+ {prog} convert fruit-stand-coco.zip --to yolo
25
+ {prog} convert fruit-stand-coco.zip --to yolo --where class=Mango --labels condition
26
+ {prog} crops fruit-stand-coco.zip
27
+ {prog} train classify fruit-stand-coco.zip --labels condition
28
+ {prog} train detect fruit-stand-coco.zip
29
+ {prog} export-model fruit-stand-coco-classify-model
30
+ {prog} predict fruit-stand-coco-classify-model photo.jpg
31
+ """
32
+
33
+
34
+ def examples() -> str:
35
+ return _EXAMPLES.format(prog=program_name())
36
+
37
+
38
+ def _parse_split(text: str):
39
+ try:
40
+ parts = [float(x) for x in text.replace(",", "/").split("/")]
41
+ except ValueError:
42
+ parts = []
43
+ if len(parts) != 3 or sum(parts) <= 0 or min(parts) < 0:
44
+ raise EmberlensError('Write the split as three numbers, like --split 80/10/10.')
45
+ return parts
46
+
47
+
48
+ def _dataset(args):
49
+ ds = load(args.export)
50
+ for cond in args.where or []:
51
+ if "=" not in cond:
52
+ raise EmberlensError(f'Write --where as name=value, like --where class=Mango (got "{cond}").')
53
+ key, value = (s.strip() for s in cond.split("=", 1))
54
+ val = None if value.lower() in ("none", "null", "") else value
55
+ if key.lower() == "split":
56
+ ds = ds.split(value)
57
+ elif key.lower() in ("class", "cls"):
58
+ ds = ds.filter(cls=value, keep_other_boxes=False)
59
+ else:
60
+ ds = ds.filter(**{key: val})
61
+ if len(ds) == 0:
62
+ raise EmberlensError(f"No boxes match {cond}.")
63
+ if getattr(args, "split", None):
64
+ ds = ds.resplit(*_parse_split(args.split))
65
+ if getattr(args, "labels", None) and args.labels != "label":
66
+ ds = ds.relabel(args.labels)
67
+ return ds
68
+
69
+
70
+ # ------------------------------------------------------------------ commands
71
+
72
+
73
+ def cmd_info(args):
74
+ ds = _dataset(args)
75
+ print(ds.summary())
76
+ print("\nLabels in the files:")
77
+ for name, n in ds.counts("label").items():
78
+ print(f" {name:<32} {n}")
79
+
80
+
81
+ def cmd_recipe(args):
82
+ from .recipe import describe, load_recipe
83
+
84
+ print(describe(load_recipe(args.file)))
85
+
86
+
87
+ def cmd_preview(args):
88
+ ds = _dataset(args)
89
+ out = Path(args.out) if args.out else free_path(Path(f"{export_stem(args.export)}-preview.html"))
90
+ path = ds.preview(out)
91
+ print(f"Wrote {path}")
92
+ if not args.no_open:
93
+ webbrowser.open(path.as_uri())
94
+
95
+
96
+ def cmd_convert(args):
97
+ ds = _dataset(args)
98
+ fmt = args.to.lower()
99
+ if fmt == "json":
100
+ out = Path(args.out) if args.out else free_path(Path(f"{export_stem(args.export)}.json"))
101
+ print(f"Wrote {ds.to_json(out)}")
102
+ return
103
+ out = Path(args.out) if args.out else free_path(Path(f"{export_stem(args.export)}-{fmt}"))
104
+ path = getattr(ds, f"to_{fmt}")(out)
105
+ print(f"Wrote {len(ds)} photos, {ds.box_count} boxes to {path}")
106
+
107
+
108
+ def cmd_crops(args):
109
+ ds = _dataset(args)
110
+ out = Path(args.out) if args.out else free_path(Path(f"{export_stem(args.export)}-crops"))
111
+ ds.crops(out, padding=args.pad, size=args.size)
112
+
113
+
114
+ def cmd_train(args):
115
+ from .train import train_classifier, train_detector
116
+
117
+ ds = _dataset(argparse.Namespace(**{**vars(args), "labels": None}))
118
+ target = args.labels or "label"
119
+ out = Path(args.out) if args.out else free_path(Path(f"{export_stem(args.export)}-{args.kind}-model"))
120
+ common = dict(target=target, pretrained=not args.no_pretrained, device=args.device)
121
+ if args.kind == "classify":
122
+ train_classifier(ds, out, epochs=args.epochs or 5, **common)
123
+ else:
124
+ train_detector(ds, out, epochs=args.epochs or 10, **common)
125
+ print(f"Next: {command('predict', shlex.quote(str(out)), '<photo.jpg>')}")
126
+ print(f"Or make the file for the app: {command('export-model', shlex.quote(str(out)))}")
127
+
128
+
129
+ def cmd_export_model(args):
130
+ from .export_model import export_model
131
+
132
+ model = Path(args.model).expanduser()
133
+ out = Path(args.out) if args.out else free_path(Path(f"{model.name or 'model'}.onnx"))
134
+ path = export_model(model, out)
135
+ print(f"Send {path.name} to your iPhone (AirDrop or Files), then add it in Project settings > Your model.")
136
+
137
+
138
+ def cmd_predict(args):
139
+ from .model import Box, Dataset, Image
140
+ from .train import predict
141
+
142
+ results = predict(args.model, args.images, threshold=args.threshold)
143
+ out = Path(args.out) if args.out else free_path(Path("predictions.json"))
144
+ out.write_text(json.dumps(results, indent=2), encoding="utf-8")
145
+ for r in results:
146
+ if "label" in r:
147
+ print(f"{r['file']}: {r['label']} ({r['score']:.0%})")
148
+ else:
149
+ shown = r["boxes"][:10]
150
+ found = ", ".join(f"{b['label']} {b['score']:.0%}" for b in shown) or "nothing found"
151
+ if len(r["boxes"]) > 10:
152
+ found += f" (+{len(r['boxes']) - 10} more)"
153
+ print(f"{r['file']}: {found}")
154
+ print(f"Wrote {out}")
155
+ if results and "boxes" in results[0]:
156
+ images = [
157
+ Image(
158
+ id=Path(r["file"]).stem,
159
+ path=Path(r["file"]),
160
+ width=r["width"],
161
+ height=r["height"],
162
+ split="test",
163
+ boxes=[Box(label=b["label"], cls=b["label"], x=b["x"], y=b["y"], w=b["w"], h=b["h"]) for b in r["boxes"]],
164
+ )
165
+ for r in results
166
+ ]
167
+ page = Dataset(name="Predictions", format="model", root=Path("."), images=images).preview(out.with_suffix(".html"))
168
+ print(f"Wrote {page}")
169
+ if not args.no_open:
170
+ webbrowser.open(page.as_uri())
171
+
172
+
173
+ def cmd_run(args):
174
+ """Run your own Python script, with `import emberlens` working."""
175
+ import runpy
176
+
177
+ script = Path(args.script)
178
+ if not script.is_file():
179
+ raise EmberlensError(f"Can't find {script}.")
180
+ sys.argv = [str(script), *args.args]
181
+ sys.path.insert(0, str(script.resolve().parent))
182
+ runpy.run_path(str(script), run_name="__main__")
183
+
184
+
185
+ def _tests_folder() -> Path:
186
+ return Path(__file__).resolve().parent.parent / "tests"
187
+
188
+
189
+ def _is_sdk_tests(tests: Path) -> bool:
190
+ """True only for the SDK's own tests, not another package's `tests` folder in site-packages."""
191
+ return (tests / "test_command.py").is_file() and (tests / "helpers.py").is_file()
192
+
193
+
194
+ def cmd_selftest(args):
195
+ """Check that the SDK works on this computer."""
196
+ import unittest
197
+
198
+ tests = _tests_folder()
199
+ if not (tests.is_dir() and _is_sdk_tests(tests)):
200
+ print(f"The Emberlens SDK {__version__} is installed. The full checks come with the source code.")
201
+ return
202
+ suite = unittest.defaultTestLoader.discover(str(tests), top_level_dir=str(tests.parent))
203
+ result = unittest.TextTestRunner(verbosity=1).run(suite)
204
+ if not result.wasSuccessful():
205
+ raise EmberlensError("Some checks failed. See above.")
206
+ print("The Emberlens SDK works on this computer.")
207
+
208
+
209
+ def cmd_install(args):
210
+ from .extras import install
211
+
212
+ install(args.extra)
213
+
214
+
215
+ # ---------------------------------------------------------------------- main
216
+
217
+
218
+ def build_parser() -> argparse.ArgumentParser:
219
+ p = argparse.ArgumentParser(
220
+ prog=program_name(),
221
+ description="Use your Emberlens exports for training. EXPORT is the .zip from the app (or its folder).",
222
+ epilog=examples(),
223
+ formatter_class=argparse.RawDescriptionHelpFormatter,
224
+ )
225
+ p.add_argument("--version", action="version", version=f"emberlens-sdk {__version__}")
226
+ sub = p.add_subparsers(dest="command", metavar="COMMAND")
227
+
228
+ def with_export(sp, labels=True, split=True):
229
+ sp.add_argument("export", help="the .zip from the app, or its folder")
230
+ sp.add_argument("--where", action="append", metavar="NAME=VALUE", help="keep only matching boxes, e.g. class=Mango or condition=Unripe (repeatable)")
231
+ if labels:
232
+ sp.add_argument("--labels", metavar="WHAT", help="label, class, joined, or a sub-category name (default: label)")
233
+ if split:
234
+ sp.add_argument("--split", metavar="T/V/T", help="new train/val/test split, e.g. 80/10/10")
235
+ return sp
236
+
237
+ s = with_export(sub.add_parser("info", help="show what is in an export"), labels=False, split=False)
238
+ s.set_defaults(func=cmd_info)
239
+
240
+ s = sub.add_parser("recipe", help="show the labels in a project file")
241
+ s.add_argument("file", help="an .emberlens-project.json or .emberlens-invite file")
242
+ s.set_defaults(func=cmd_recipe)
243
+
244
+ s = with_export(sub.add_parser("preview", help="make an HTML page with every photo and box"), labels=False, split=False)
245
+ s.add_argument("--out", help="the .html file to write")
246
+ s.add_argument("--no-open", action="store_true", help="do not open the browser")
247
+ s.set_defaults(func=cmd_preview)
248
+
249
+ s = with_export(sub.add_parser("convert", help="write the dataset as coco, yolo, voc or json"))
250
+ s.add_argument("--to", required=True, choices=["coco", "yolo", "voc", "json"], help="the new format")
251
+ s.add_argument("--out", help="the folder (or .json file) to write")
252
+ s.set_defaults(func=cmd_convert)
253
+
254
+ s = with_export(sub.add_parser("crops", help="save each box as its own image, one folder per label (needs Pillow)"), split=False)
255
+ s.add_argument("--out", help="the folder to write")
256
+ s.add_argument("--pad", type=float, default=0.0, help="extra space around each box, e.g. 0.1 = 10%%")
257
+ s.add_argument("--size", type=int, help="resize every crop to SIZE x SIZE pixels")
258
+ s.set_defaults(func=cmd_crops)
259
+
260
+ s = sub.add_parser("train", help="train a model with PyTorch (needs PyTorch)")
261
+ s.add_argument("kind", choices=["classify", "detect"], help="classify = name the object in a box; detect = find objects in a photo")
262
+ with_export(s)
263
+ s.add_argument("--epochs", type=int, help="training rounds (default: 5 classify, 10 detect)")
264
+ s.add_argument("--out", help="the model folder to write")
265
+ s.add_argument("--no-pretrained", action="store_true", help="start from scratch (no download; needs much more data)")
266
+ s.add_argument("--device", help="cpu, cuda or mps (default: the fastest found)")
267
+ s.set_defaults(func=cmd_train)
268
+
269
+ s = sub.add_parser("predict", help="run a trained model on photos")
270
+ s.add_argument("model", help=f"the model folder from {command('train')}")
271
+ s.add_argument("images", nargs="+", help="one or more photos")
272
+ s.add_argument("--threshold", type=float, default=0.5, help="detector: lowest score to keep (0..1)")
273
+ s.add_argument("--out", help="the .json file to write")
274
+ s.add_argument("--no-open", action="store_true", help="do not open the browser")
275
+ s.set_defaults(func=cmd_predict)
276
+
277
+ s = sub.add_parser("export-model", help="turn a trained model into one .onnx file for the app (needs onnx)")
278
+ s.add_argument("model", help=f"the model folder from {command('train', 'classify')} or {command('train', 'detect')}")
279
+ s.add_argument("--out", help="the .onnx file to write")
280
+ s.set_defaults(func=cmd_export_model)
281
+
282
+ s = sub.add_parser("install", help="install optional parts: images (Pillow), train (PyTorch) or onnx")
283
+ s.add_argument("extra", choices=["images", "train", "onnx"])
284
+ s.set_defaults(func=cmd_install)
285
+
286
+ s = sub.add_parser("run", help="run your own Python script that uses `import emberlens`")
287
+ s.add_argument("script", help="your .py file")
288
+ s.add_argument("args", nargs=argparse.REMAINDER, help="arguments for your script")
289
+ s.set_defaults(func=cmd_run)
290
+
291
+ s = sub.add_parser("selftest", help="check that the SDK works on this computer")
292
+ s.set_defaults(func=cmd_selftest)
293
+
294
+ sub.add_parser("help", help="show this help")
295
+ return p
296
+
297
+
298
+ def main(argv: Optional[List[str]] = None) -> int:
299
+ parser = build_parser()
300
+ args = parser.parse_args(argv)
301
+ if not getattr(args, "func", None):
302
+ parser.print_help()
303
+ return 0
304
+ try:
305
+ args.func(args)
306
+ return 0
307
+ except MissingExtra as e:
308
+ if sys.stdin.isatty():
309
+ answer = input(f"{e.packages} is needed for this. Install it now? [Y/n] ").strip().lower()
310
+ if answer in ("", "y", "yes"):
311
+ from .extras import install
312
+
313
+ try:
314
+ install(e.extra)
315
+ except EmberlensError as err:
316
+ print(f"Error: {err}", file=sys.stderr)
317
+ return 1
318
+ print("Run your command again.")
319
+ return 0
320
+ print(f"Error: {e}", file=sys.stderr)
321
+ return 1
322
+ except EmberlensError as e:
323
+ print(f"Error: {e}", file=sys.stderr)
324
+ return 1
325
+ except KeyboardInterrupt:
326
+ print("Stopped.", file=sys.stderr)
327
+ return 130
328
+
329
+
330
+ if __name__ == "__main__":
331
+ sys.exit(main())
emberlens/command.py ADDED
@@ -0,0 +1,35 @@
1
+ """The command the user can run, for use in messages.
2
+
3
+ The repo launcher says `./emberlens`; a pip install may be a script at
4
+ `~/.emberlens/bin/emberlens` or on the PATH; `python -m emberlens` works anywhere.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import os
10
+ import shutil
11
+ import sys
12
+ from pathlib import Path
13
+ from typing import Mapping, Optional
14
+
15
+
16
+ def program_name(argv0: Optional[str] = None, env: Optional[Mapping[str, str]] = None) -> str:
17
+ env = os.environ if env is None else env
18
+ if env.get("EMBERLENS_PROG"):
19
+ return env["EMBERLENS_PROG"]
20
+ argv0 = sys.argv[0] if argv0 is None else argv0
21
+ if not argv0 or Path(argv0).name == "__main__.py":
22
+ return "python -m emberlens"
23
+ if not os.path.basename(argv0).startswith("emberlens"):
24
+ return "python -m emberlens" # for example Jupyter's ipykernel_launcher.py
25
+ found = shutil.which(os.path.basename(argv0))
26
+ if found and os.path.realpath(found) == os.path.realpath(argv0):
27
+ return os.path.basename(argv0)
28
+ home = str(Path.home())
29
+ if argv0 == home or argv0.startswith(home + os.sep):
30
+ return "~" + argv0[len(home):].replace(os.sep, "/")
31
+ return argv0
32
+
33
+
34
+ def command(*parts: str) -> str:
35
+ return " ".join([program_name(), *parts])
emberlens/crops.py ADDED
@@ -0,0 +1,61 @@
1
+ """Save each box as its own image, sorted into one folder per label.
2
+
3
+ The layout out/<split>/<label>/<photo>_<n>.jpg is what most image
4
+ classification tools expect ("ImageFolder").
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import re
10
+ from pathlib import Path
11
+ from typing import Optional
12
+
13
+ from .errors import EmberlensError
14
+ from .extras import require_pillow
15
+
16
+
17
+ def safe_name(text: str) -> str:
18
+ name = re.sub(r"[^\w.\- ]+", "_", text).strip(" .")
19
+ return name or "_"
20
+
21
+
22
+ def crop_box(pil_image, box, padding: float = 0.0):
23
+ """Crop one box out of a Pillow image, with `padding` (share of box size) around it."""
24
+ W, H = pil_image.size
25
+ x0, y0, x1, y1 = box.pixels(W, H)
26
+ px, py = (x1 - x0) * padding, (y1 - y0) * padding
27
+ left, top = max(0, int(x0 - px)), max(0, int(y0 - py))
28
+ right, bottom = min(W, int(round(x1 + px))), min(H, int(round(y1 + py)))
29
+ right, bottom = max(right, left + 1), max(bottom, top + 1)
30
+ return pil_image.crop((left, top, right, bottom))
31
+
32
+
33
+ def crop_for_model(pil_image, box, padding: float = 0.1, size: int = 224):
34
+ """The one crop rule for models: 10% padding, then stretch to size x size.
35
+
36
+ Training, `export-model` and the app all use this rule, so a model sees
37
+ the same pixels in training and on the phone. Do not change it without
38
+ changing the ONNX metadata keys (crop_pad, resize_mode) and the app.
39
+ """
40
+ return crop_box(pil_image, box, padding).resize((size, size))
41
+
42
+
43
+ def write_crops(ds, out_dir, padding: float = 0.0, size: Optional[int] = None) -> Path:
44
+ require_pillow()
45
+ out = Path(out_dir).expanduser()
46
+ if out.exists() and any(out.iterdir()):
47
+ raise EmberlensError(f"{out} is not empty. Choose a new folder.")
48
+ count = 0
49
+ for img in ds.images:
50
+ if not img.boxes:
51
+ continue
52
+ photo = img.open().convert("RGB")
53
+ for n, box in enumerate(img.boxes, 1):
54
+ crop = crop_for_model(photo, box, padding, size) if size else crop_box(photo, box, padding)
55
+ folder = out / img.split / safe_name(box.label)
56
+ folder.mkdir(parents=True, exist_ok=True)
57
+ crop.save(folder / f"{safe_name(img.id)}_{n}.jpg", quality=95)
58
+ count += 1
59
+ out.mkdir(parents=True, exist_ok=True)
60
+ print(f"Saved {count} crops in {out}")
61
+ return out
emberlens/errors.py ADDED
@@ -0,0 +1,24 @@
1
+ """Errors with messages that a non-programmer can act on."""
2
+
3
+ from .command import command
4
+
5
+
6
+ class EmberlensError(Exception):
7
+ """Something the user can fix. The message says how."""
8
+
9
+ def _render_traceback_(self):
10
+ # IPython (Colab, Kaggle) shows this instead of a traceback.
11
+ return [str(self)]
12
+
13
+
14
+ class MissingExtra(EmberlensError):
15
+ """An optional library (Pillow, PyTorch) is not installed."""
16
+
17
+ def __init__(self, extra: str, packages: str):
18
+ self.extra = extra
19
+ self.packages = packages
20
+ super().__init__(
21
+ f"This needs {packages}. Install it with:\n"
22
+ f" {command('install', extra)}\n"
23
+ f"(or: pip install {packages})"
24
+ )