labeltify 0.4.2__tar.gz → 0.5.0__tar.gz

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 (25) hide show
  1. {labeltify-0.4.2 → labeltify-0.5.0}/PKG-INFO +51 -9
  2. {labeltify-0.4.2 → labeltify-0.5.0}/README.md +49 -7
  3. {labeltify-0.4.2 → labeltify-0.5.0}/labeltify/__main__.py +9 -1
  4. {labeltify-0.4.2 → labeltify-0.5.0}/labeltify/client.py +180 -58
  5. labeltify-0.5.0/labeltify/corrupt.py +184 -0
  6. labeltify-0.5.0/labeltify/meta.py +274 -0
  7. {labeltify-0.4.2 → labeltify-0.5.0}/labeltify.egg-info/PKG-INFO +51 -9
  8. {labeltify-0.4.2 → labeltify-0.5.0}/labeltify.egg-info/SOURCES.txt +5 -1
  9. {labeltify-0.4.2 → labeltify-0.5.0}/pyproject.toml +3 -3
  10. {labeltify-0.4.2 → labeltify-0.5.0}/tests/test_client.py +182 -53
  11. labeltify-0.5.0/tests/test_corrupt.py +176 -0
  12. labeltify-0.5.0/tests/test_corrupt_eval.py +72 -0
  13. labeltify-0.5.0/tests/test_meta.py +60 -0
  14. labeltify-0.5.0/tests/test_meta_parity.py +33 -0
  15. labeltify-0.4.2/labeltify/corrupt.py +0 -189
  16. labeltify-0.4.2/tests/test_corrupt.py +0 -88
  17. {labeltify-0.4.2 → labeltify-0.5.0}/labeltify/__init__.py +0 -0
  18. {labeltify-0.4.2 → labeltify-0.5.0}/labeltify/dhash.py +0 -0
  19. {labeltify-0.4.2 → labeltify-0.5.0}/labeltify/download.py +0 -0
  20. {labeltify-0.4.2 → labeltify-0.5.0}/labeltify.egg-info/dependency_links.txt +0 -0
  21. {labeltify-0.4.2 → labeltify-0.5.0}/labeltify.egg-info/entry_points.txt +0 -0
  22. {labeltify-0.4.2 → labeltify-0.5.0}/labeltify.egg-info/requires.txt +1 -1
  23. {labeltify-0.4.2 → labeltify-0.5.0}/labeltify.egg-info/top_level.txt +0 -0
  24. {labeltify-0.4.2 → labeltify-0.5.0}/setup.cfg +0 -0
  25. {labeltify-0.4.2 → labeltify-0.5.0}/tests/test_download.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: labeltify
3
- Version: 0.4.2
3
+ Version: 0.5.0
4
4
  Summary: Upload frames and optional annotations into LabelTify with a pipeline token.
5
5
  Author: CleverTify
6
6
  Project-URL: Homepage, https://labeltify.com
@@ -14,10 +14,10 @@ Classifier: Programming Language :: Python :: 3 :: Only
14
14
  Classifier: Topic :: Scientific/Engineering :: Image Recognition
15
15
  Requires-Python: >=3.10
16
16
  Description-Content-Type: text/markdown
17
+ Requires-Dist: Pillow>=10
17
18
  Provides-Extra: test
18
19
  Requires-Dist: pytest>=8; extra == "test"
19
20
  Provides-Extra: images
20
- Requires-Dist: Pillow>=10; extra == "images"
21
21
 
22
22
  # labeltify
23
23
 
@@ -39,16 +39,25 @@ img = client.upload_image(
39
39
  "DATASET_ID",
40
40
  jpeg_bytes,
41
41
  filename="cam01.jpg",
42
+ captured_at="2026-06-01T12:00:00Z",
42
43
  camera="cam-01",
43
44
  pipeline="ds-prod",
44
45
  trigger="low_confidence",
46
+ model_name="park-net",
47
+ model_version="1.2",
45
48
  )
46
- client.upload_file("DATASET_ID", "frames/cam02.jpg", camera="cam-02")
49
+ client.upload_file("DATASET_ID", "frames/cam02.jpg", captured_at="2026-06-01T12:00:05Z", camera="cam-02")
47
50
  ```
48
51
 
49
52
  The token knows its org, so you don't pass one. Timeouts, `429`, and `5xx` responses are retried with exponential backoff (`max_retries=4` by default). Anything else raises `LabelTifyError` with the API's message and `.status`.
50
53
 
51
- Annotations are optional. When you pass `labels` (COCO, LabelTify, or YOLO JSON bytes), `work_state` is required: `done`, `in_progress`, `unsure`, or `untouched`. There is no default; the client raises `LabelTifyError` before sending if it is missing. Images with no labels stay untouched.
54
+ `captured_at` is required. Pass an aware `datetime` or an ISO 8601 string with `Z` or an offset. A naive datetime is rejected before any request.
55
+
56
+ `original_detection` is what the device's model saw (COCO, LabelTify, or YOLO JSON bytes). LabelTify stores it and does not show it, and the frame stays untouched. `final_annotation` is a ready annotation file, the same import as before. With it, `work_state` must be `done` or `in_progress`. Images with no final annotation stay untouched.
57
+
58
+ `model_name`, `model_version`, `gps` (`(lat, lon)` or `{"lat", "lon"}`), and `additional_data` (a JSON object, at most 2 KiB) are optional and separate. `model_version` requires `model_name`.
59
+
60
+ Frames that score at least 0.5 on the corrupt detector are not uploaded. They come back in `report["files"]` with status `skipped_corrupt`, the score, and the reason. Pass `skip_corrupt=False` to upload them anyway (they are still scored, so the server can suggest them). Pillow is installed with the package.
52
61
 
53
62
  ### Upload a folder with its annotations
54
63
 
@@ -56,7 +65,10 @@ Annotations are optional. When you pass `labels` (COCO, LabelTify, or YOLO JSON
56
65
  report = client.upload_directory(
57
66
  "DATASET_ID",
58
67
  "datasets/parking",
68
+ captured_at="exif_or_mtime",
59
69
  work_state="done",
70
+ model_name="park-net",
71
+ model_version="1.2",
60
72
  )
61
73
  print(len(report["items"]), "images stored in", report["requests"], "requests;", report["imported"])
62
74
  ```
@@ -64,21 +76,24 @@ print(len(report["items"]), "images stored in", report["requests"], "requests;",
64
76
  This sends the folder the way dropping it on the dataset's **Upload** page would: images, plus COCO (polygons and boxes), YOLO (`labels/*.txt` with `data.yaml` or `classes.txt`), Pascal VOC, LabelMe, CSV, `metadata.jsonl`, a folder per class, or a LabelTify export. The server reads the annotations; the client only splits the folder into requests (at most 100 images and 80 MB each). A COCO file is cut down to each request's images, so polygons stay polygons.
65
77
 
66
78
  - The dataset must already exist. Create it on the site. Parking polygons need type **Instance segmentation**. Traffic boxes need **Object detection**.
67
- - `work_state="done"` marks every image that received a shape. Images with no shape stay untouched. With any label file in the folder, `work_state` is required.
79
+ - `captured_at` is required. `exif` reads DateTimeOriginal and OffsetTimeOriginal (a missing offset names the file and stops). `mtime` uses the file's mtime as UTC. `exif_or_mtime` uses EXIF when the timestamp is there and mtime otherwise. You can also pass one aware datetime, a mapping of filename to datetime, or a function of the path. `meta_for` returns a full `ImageMeta` for one file.
80
+ - `work_state="done"` marks every image that received a final annotation. Images with no annotation stay untouched. With any annotation file in the folder, `work_state` must be `done` or `in_progress`.
81
+ - A zip in the folder is expanded here. Each member keeps its path as the upload filename, and each image is scored and gets its own metadata.
82
+ - Corrupt frames are left out unless you pass `skip_corrupt=False`.
68
83
  - Create the pipeline token on that dataset's **Upload** page.
69
84
  - One credit covers 10,000 uploaded images. A free dataset holds 100 photos.
70
85
  - Frame embeddings follow the dataset setting. Turn them off on the dataset before a large upload when you do not want that charge.
71
86
  - Use the portable pixel COCO files. The raw Studio shards store boxes as fractions from 0 to 1, and the server divides by width and height again.
72
87
  - Two images with the same file name in different folders stop the upload before anything is sent; rename one.
73
- - Images over 20 MiB, empty files, and files that are neither images nor annotations are listed in `report["files"]` and not sent. A zip is sent as it is when it holds at most 200 files and 20 MB; unzip anything bigger.
88
+ - Images over 20 MiB, empty files, and files that are neither images nor annotations are listed in `report["files"]` and not sent. A zip is expanded when it holds at most 200 files and 20 MB.
74
89
  - If a request fails after its retries, the error says how many images were already stored; run the folder again and only what is missing is uploaded (see below).
75
- - `compute_dhash=True` also skips near-duplicate frames, like the Upload page. It needs Pillow: `pip install "labeltify[images]"`.
90
+ - `compute_dhash=True` also skips near-duplicate frames, like the Upload page. Pillow is already installed.
76
91
 
77
92
  #### Migrating thousands of images
78
93
 
79
94
  ```bash
80
95
  export LABELTIFY_TOKEN=labeltify_…
81
- python -m labeltify upload ./photos --dataset DATASET_ID --workers 6 --work-state done
96
+ python -m labeltify upload ./photos --dataset DATASET_ID --captured-at exif_or_mtime --workers 6 --work-state done
82
97
  ```
83
98
 
84
99
  or `client.upload_directory(dataset_id, folder, workers=6, progress=print)`.
@@ -89,7 +104,34 @@ or `client.upload_directory(dataset_id, folder, workers=6, progress=print)`.
89
104
  - **Frame embeddings** follow the dataset setting and are made in the background after the upload: thousands of images take a while to get their vectors. The dataset's Images tab shows how many are done.
90
105
  - If a request fails, the requests not started yet are dropped, those already stored stay stored, and the error says how many; run the command again to continue.
91
106
 
92
- `upload_bundle(dataset_id, files, work_state=…)` sends one such request from bytes you already have (`files` is a list of `{"filename", "data", "content_type"}`).
107
+ `upload_bundle(dataset_id, files, images_meta=…, work_state=…)` sends one such request from bytes you already have (`files` is a list of `{"filename", "data", "content_type"}`, and `images_meta` is one `ImageMeta` per image).
108
+
109
+ ### Upgrade from 0.4
110
+
111
+ `labels` is gone. Capture time is required. Corrupt frames are skipped unless you opt in.
112
+
113
+ ```python
114
+ # 0.4
115
+ client.upload_image(dataset_id, data, "cam.jpg", labels=open("ann.json", "rb").read(), work_state="done")
116
+
117
+ # 0.5
118
+ client.upload_image(
119
+ dataset_id,
120
+ data,
121
+ filename="cam.jpg",
122
+ captured_at="2026-06-01T12:00:00Z",
123
+ final_annotation=open("ann.json", "rb").read(),
124
+ work_state="done",
125
+ )
126
+ ```
127
+
128
+ ```python
129
+ # 0.4
130
+ client.upload_directory(dataset_id, "frames", work_state="done")
131
+
132
+ # 0.5
133
+ client.upload_directory(dataset_id, "frames", captured_at="exif_or_mtime", work_state="done")
134
+ ```
93
135
 
94
136
  A deployment behind an access proxy can take extra headers on every request: `LabelTifyClient(token, base_url=…, headers={"CF-Access-Client-Id": …, "CF-Access-Client-Secret": …})`.
95
137
 
@@ -18,16 +18,25 @@ img = client.upload_image(
18
18
  "DATASET_ID",
19
19
  jpeg_bytes,
20
20
  filename="cam01.jpg",
21
+ captured_at="2026-06-01T12:00:00Z",
21
22
  camera="cam-01",
22
23
  pipeline="ds-prod",
23
24
  trigger="low_confidence",
25
+ model_name="park-net",
26
+ model_version="1.2",
24
27
  )
25
- client.upload_file("DATASET_ID", "frames/cam02.jpg", camera="cam-02")
28
+ client.upload_file("DATASET_ID", "frames/cam02.jpg", captured_at="2026-06-01T12:00:05Z", camera="cam-02")
26
29
  ```
27
30
 
28
31
  The token knows its org, so you don't pass one. Timeouts, `429`, and `5xx` responses are retried with exponential backoff (`max_retries=4` by default). Anything else raises `LabelTifyError` with the API's message and `.status`.
29
32
 
30
- Annotations are optional. When you pass `labels` (COCO, LabelTify, or YOLO JSON bytes), `work_state` is required: `done`, `in_progress`, `unsure`, or `untouched`. There is no default; the client raises `LabelTifyError` before sending if it is missing. Images with no labels stay untouched.
33
+ `captured_at` is required. Pass an aware `datetime` or an ISO 8601 string with `Z` or an offset. A naive datetime is rejected before any request.
34
+
35
+ `original_detection` is what the device's model saw (COCO, LabelTify, or YOLO JSON bytes). LabelTify stores it and does not show it, and the frame stays untouched. `final_annotation` is a ready annotation file, the same import as before. With it, `work_state` must be `done` or `in_progress`. Images with no final annotation stay untouched.
36
+
37
+ `model_name`, `model_version`, `gps` (`(lat, lon)` or `{"lat", "lon"}`), and `additional_data` (a JSON object, at most 2 KiB) are optional and separate. `model_version` requires `model_name`.
38
+
39
+ Frames that score at least 0.5 on the corrupt detector are not uploaded. They come back in `report["files"]` with status `skipped_corrupt`, the score, and the reason. Pass `skip_corrupt=False` to upload them anyway (they are still scored, so the server can suggest them). Pillow is installed with the package.
31
40
 
32
41
  ### Upload a folder with its annotations
33
42
 
@@ -35,7 +44,10 @@ Annotations are optional. When you pass `labels` (COCO, LabelTify, or YOLO JSON
35
44
  report = client.upload_directory(
36
45
  "DATASET_ID",
37
46
  "datasets/parking",
47
+ captured_at="exif_or_mtime",
38
48
  work_state="done",
49
+ model_name="park-net",
50
+ model_version="1.2",
39
51
  )
40
52
  print(len(report["items"]), "images stored in", report["requests"], "requests;", report["imported"])
41
53
  ```
@@ -43,21 +55,24 @@ print(len(report["items"]), "images stored in", report["requests"], "requests;",
43
55
  This sends the folder the way dropping it on the dataset's **Upload** page would: images, plus COCO (polygons and boxes), YOLO (`labels/*.txt` with `data.yaml` or `classes.txt`), Pascal VOC, LabelMe, CSV, `metadata.jsonl`, a folder per class, or a LabelTify export. The server reads the annotations; the client only splits the folder into requests (at most 100 images and 80 MB each). A COCO file is cut down to each request's images, so polygons stay polygons.
44
56
 
45
57
  - The dataset must already exist. Create it on the site. Parking polygons need type **Instance segmentation**. Traffic boxes need **Object detection**.
46
- - `work_state="done"` marks every image that received a shape. Images with no shape stay untouched. With any label file in the folder, `work_state` is required.
58
+ - `captured_at` is required. `exif` reads DateTimeOriginal and OffsetTimeOriginal (a missing offset names the file and stops). `mtime` uses the file's mtime as UTC. `exif_or_mtime` uses EXIF when the timestamp is there and mtime otherwise. You can also pass one aware datetime, a mapping of filename to datetime, or a function of the path. `meta_for` returns a full `ImageMeta` for one file.
59
+ - `work_state="done"` marks every image that received a final annotation. Images with no annotation stay untouched. With any annotation file in the folder, `work_state` must be `done` or `in_progress`.
60
+ - A zip in the folder is expanded here. Each member keeps its path as the upload filename, and each image is scored and gets its own metadata.
61
+ - Corrupt frames are left out unless you pass `skip_corrupt=False`.
47
62
  - Create the pipeline token on that dataset's **Upload** page.
48
63
  - One credit covers 10,000 uploaded images. A free dataset holds 100 photos.
49
64
  - Frame embeddings follow the dataset setting. Turn them off on the dataset before a large upload when you do not want that charge.
50
65
  - Use the portable pixel COCO files. The raw Studio shards store boxes as fractions from 0 to 1, and the server divides by width and height again.
51
66
  - Two images with the same file name in different folders stop the upload before anything is sent; rename one.
52
- - Images over 20 MiB, empty files, and files that are neither images nor annotations are listed in `report["files"]` and not sent. A zip is sent as it is when it holds at most 200 files and 20 MB; unzip anything bigger.
67
+ - Images over 20 MiB, empty files, and files that are neither images nor annotations are listed in `report["files"]` and not sent. A zip is expanded when it holds at most 200 files and 20 MB.
53
68
  - If a request fails after its retries, the error says how many images were already stored; run the folder again and only what is missing is uploaded (see below).
54
- - `compute_dhash=True` also skips near-duplicate frames, like the Upload page. It needs Pillow: `pip install "labeltify[images]"`.
69
+ - `compute_dhash=True` also skips near-duplicate frames, like the Upload page. Pillow is already installed.
55
70
 
56
71
  #### Migrating thousands of images
57
72
 
58
73
  ```bash
59
74
  export LABELTIFY_TOKEN=labeltify_…
60
- python -m labeltify upload ./photos --dataset DATASET_ID --workers 6 --work-state done
75
+ python -m labeltify upload ./photos --dataset DATASET_ID --captured-at exif_or_mtime --workers 6 --work-state done
61
76
  ```
62
77
 
63
78
  or `client.upload_directory(dataset_id, folder, workers=6, progress=print)`.
@@ -68,7 +83,34 @@ or `client.upload_directory(dataset_id, folder, workers=6, progress=print)`.
68
83
  - **Frame embeddings** follow the dataset setting and are made in the background after the upload: thousands of images take a while to get their vectors. The dataset's Images tab shows how many are done.
69
84
  - If a request fails, the requests not started yet are dropped, those already stored stay stored, and the error says how many; run the command again to continue.
70
85
 
71
- `upload_bundle(dataset_id, files, work_state=…)` sends one such request from bytes you already have (`files` is a list of `{"filename", "data", "content_type"}`).
86
+ `upload_bundle(dataset_id, files, images_meta=…, work_state=…)` sends one such request from bytes you already have (`files` is a list of `{"filename", "data", "content_type"}`, and `images_meta` is one `ImageMeta` per image).
87
+
88
+ ### Upgrade from 0.4
89
+
90
+ `labels` is gone. Capture time is required. Corrupt frames are skipped unless you opt in.
91
+
92
+ ```python
93
+ # 0.4
94
+ client.upload_image(dataset_id, data, "cam.jpg", labels=open("ann.json", "rb").read(), work_state="done")
95
+
96
+ # 0.5
97
+ client.upload_image(
98
+ dataset_id,
99
+ data,
100
+ filename="cam.jpg",
101
+ captured_at="2026-06-01T12:00:00Z",
102
+ final_annotation=open("ann.json", "rb").read(),
103
+ work_state="done",
104
+ )
105
+ ```
106
+
107
+ ```python
108
+ # 0.4
109
+ client.upload_directory(dataset_id, "frames", work_state="done")
110
+
111
+ # 0.5
112
+ client.upload_directory(dataset_id, "frames", captured_at="exif_or_mtime", work_state="done")
113
+ ```
72
114
 
73
115
  A deployment behind an access proxy can take extra headers on every request: `LabelTifyClient(token, base_url=…, headers={"CF-Access-Client-Id": …, "CF-Access-Client-Secret": …})`.
74
116
 
@@ -42,7 +42,11 @@ def build_parser() -> argparse.ArgumentParser:
42
42
  up.add_argument("--token", help="Pipeline token (default: the LABELTIFY_TOKEN environment variable).")
43
43
  up.add_argument("--base-url", default=os.environ.get("LABELTIFY_URL", DEFAULT_BASE_URL), help=f"API address (default {DEFAULT_BASE_URL}).")
44
44
  up.add_argument("--workers", type=int, default=DEFAULT_WORKERS, help=f"Requests at once, 1-{MAX_WORKERS} (default {DEFAULT_WORKERS}).")
45
- up.add_argument("--work-state", choices=WORK_STATES, help="State of images that come with labels (required when the folder has label files).")
45
+ up.add_argument("--captured-at", required=True, choices=["exif", "mtime", "exif_or_mtime"], help="Where each frame's capture time comes from.")
46
+ up.add_argument("--model-name", help="Model name stored on every uploaded frame.")
47
+ up.add_argument("--model-version", help="Model version stored on every uploaded frame. Requires --model-name.")
48
+ up.add_argument("--upload-corrupt", action="store_true", help="Upload frames the corrupt filter would skip. They are still scored.")
49
+ up.add_argument("--work-state", choices=WORK_STATES, help="State of images that come with final annotations: done or in_progress.")
46
50
  up.add_argument("--no-near-dup", action="store_true", help="Do not skip near-duplicates.")
47
51
  up.add_argument("--force", action="store_true", help="Store files even when the dataset already holds the same bytes.")
48
52
  up.add_argument("--no-skip-existing", action="store_true", help="Send every file even if the dataset already holds it.")
@@ -83,6 +87,10 @@ def run_upload(args: argparse.Namespace) -> int:
83
87
  report = client.upload_directory(
84
88
  args.dataset,
85
89
  args.directory,
90
+ captured_at=args.captured_at,
91
+ model_name=args.model_name,
92
+ model_version=args.model_version,
93
+ skip_corrupt=not args.upload_corrupt,
86
94
  work_state=args.work_state,
87
95
  skip_near_duplicates=not args.no_near_dup,
88
96
  force=args.force,