lannotex 0.1.0__tar.gz → 0.1.1__tar.gz

{lannotex-0.1.0 → lannotex-0.1.1}/CHANGELOG.md

@@ -6,6 +6,15 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.1] — 2026-10-14
+
+### Changed
+
+- **YOLO export is ready to train with Ultralytics:** `images/` (hard-linked when
+  possible, otherwise copied), matching `labels/`, and a `data.yaml` with class names.
+  Images that haven't been annotated yet are left out, so they don't become false
+  negatives.
+
 ## [0.1.0] — 2026-10-14
 
 First public release on PyPI: `pip install lannotex` or `uv tool install lannotex`.

{lannotex-0.1.0 → lannotex-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lannotex
-Version: 0.1.0
+Version: 0.1.1
 Summary: Fast, offline-first image annotation for classifications, boxes, and polygons.
 Author: Lourdhu Raju
 Maintainer: Lourdhu Raju
@@ -133,7 +133,7 @@ Every shortcut can be remapped. See the [annotating guide](https://lourdhu02.git
 | **Annotate** | Bounding boxes · polygons with vertex drag, insert, and delete · multi-label image classes · "no target" negatives · 100-step undo/redo · zoom under the pointer, pan, arrow-key nudging · focus mode · light and dark themes |
 | **Stay safe** | SQLite projects with versioned migrations · recovery drafts and 700 ms autosave · transactional saves · geometry validation · backup and restore · relinking for moved images · EXIF orientation handled |
 | **Scale** | Virtualized image list (at most 1,024 records in memory) · background import and decoding · 96 MB preview cache · coordinates normalized to the original resolution |
-| **Export** | Labelme JSON · YOLO · COCO JSON · classification CSV · lossless native JSONL · each export reports anything it skipped |
+| **Export** | Labelme JSON · ready-to-train YOLO (`images/`, `labels/`, `data.yaml`) · COCO JSON · classification CSV · lossless native JSONL · each export reports anything it skipped |
 | **Automate** | `lannotex export` and `lannotex analyze` run headless in CI, with no display needed |
 | **Collaborate** | Optional LAN host with per-reviewer tokens, background sync, revision conflicts you resolve explicitly, revocation, and an audit history |
 
@@ -181,8 +181,8 @@ hashes. There is no telemetry, no external AI service, and no automatic upload.
 
 ## Roadmap
 
-Next up: a ready-to-train YOLO layout (`images/`, `labels/`, `data.yaml`), more LabelMe
-shape types, VOC and YOLO-seg export, and number-key label selection. See the
+Next up: more LabelMe shape types (points, lines, circles), VOC and YOLO-seg export, and
+number-key label selection. See the
 [roadmap](https://lourdhu02.github.io/Lannotex/ROADMAP/) and the
 [measured performance](https://lourdhu02.github.io/Lannotex/PERFORMANCE/).
 

{lannotex-0.1.0 → lannotex-0.1.1}/README.md

@@ -91,7 +91,7 @@ Every shortcut can be remapped. See the [annotating guide](https://lourdhu02.git
 | **Annotate** | Bounding boxes · polygons with vertex drag, insert, and delete · multi-label image classes · "no target" negatives · 100-step undo/redo · zoom under the pointer, pan, arrow-key nudging · focus mode · light and dark themes |
 | **Stay safe** | SQLite projects with versioned migrations · recovery drafts and 700 ms autosave · transactional saves · geometry validation · backup and restore · relinking for moved images · EXIF orientation handled |
 | **Scale** | Virtualized image list (at most 1,024 records in memory) · background import and decoding · 96 MB preview cache · coordinates normalized to the original resolution |
-| **Export** | Labelme JSON · YOLO · COCO JSON · classification CSV · lossless native JSONL · each export reports anything it skipped |
+| **Export** | Labelme JSON · ready-to-train YOLO (`images/`, `labels/`, `data.yaml`) · COCO JSON · classification CSV · lossless native JSONL · each export reports anything it skipped |
 | **Automate** | `lannotex export` and `lannotex analyze` run headless in CI, with no display needed |
 | **Collaborate** | Optional LAN host with per-reviewer tokens, background sync, revision conflicts you resolve explicitly, revocation, and an audit history |
 
@@ -139,8 +139,8 @@ hashes. There is no telemetry, no external AI service, and no automatic upload.
 
 ## Roadmap
 
-Next up: a ready-to-train YOLO layout (`images/`, `labels/`, `data.yaml`), more LabelMe
-shape types, VOC and YOLO-seg export, and number-key label selection. See the
+Next up: more LabelMe shape types (points, lines, circles), VOC and YOLO-seg export, and
+number-key label selection. See the
 [roadmap](https://lourdhu02.github.io/Lannotex/ROADMAP/) and the
 [measured performance](https://lourdhu02.github.io/Lannotex/PERFORMANCE/).
 

{lannotex-0.1.0 → lannotex-0.1.1}/docs/guide/import-export.md

@@ -5,7 +5,7 @@
 | Format | Contains | Use it for |
 | --- | --- | --- |
 | **Labelme JSON** | One JSON per image: boxes as `rectangle`, polygons, classes as `flags` | LabelMe and tools that read its format |
-| **YOLO boxes** | One `.txt` per image: `class cx cy w h`, normalized | YOLO detection training |
+| **YOLO boxes** | Ready-to-train Ultralytics dataset: `images/`, `labels/`, `data.yaml` | YOLO detection training |
 | **COCO JSON** | One `coco.json` with boxes, polygon segmentations, and areas | Detection and instance segmentation |
 | **Classification CSV** | One row per image, one 0/1 column per class | Image classification |
 | **Native JSONL** | Every annotation with its ID and status | Lossless backup and round-trips |
@@ -24,10 +24,11 @@ Lannotex-export-1a2b3c4d/
 ├── classification.csv
 ├── images.jsonl
 ├── annotations.jsonl
-└── 00000001_street.json   # per-image files (Labelme JSON / YOLO .txt)
+└── 00000001_street.json   # per-image files (Labelme JSON)
 ```
 
-Images are **referenced, not copied**: exported records point to the original files.
+Images are **referenced, not copied**: exported records point to the original files. YOLO
+is the exception, described below.
 
 ### What gets skipped
 
@@ -39,11 +40,30 @@ An image is left out of the export, and listed in `manifest.json`, if:
 
 Run **View → Analysis** or `lannotex analyze` beforehand to find these images.
 
-!!! note "Training with Ultralytics YOLO"
-    The YOLO export writes label files named `<id>_<image name>.txt` plus `classes.json`.
-    Ultralytics expects `images/` and `labels/` folders with matching file names and a
-    `data.yaml`, so you currently have to arrange those yourself. A ready-to-train layout is
-    planned.
+### YOLO: ready to train
+
+The YOLO export is a complete [Ultralytics](https://docs.ultralytics.com/datasets/detect/)
+dataset:
+
+```text
+Lannotex-export-1a2b3c4d/
+├── data.yaml              # path, train/val, class names
+├── images/00000001_street.jpg
+└── labels/00000001_street.txt   # class cx cy w h, normalized
+```
+
+```bash
+yolo detect train data=Lannotex-export-1a2b3c4d/data.yaml model=yolo11n.pt
+```
+
+- Images are **hard-linked** into `images/` when the export is on the same drive, so they
+  take no extra space. Otherwise they're copied. Your originals are never modified.
+- Images marked **No target objects** get an empty label file, so YOLO learns them as
+  background.
+- Images you haven't annotated yet are **left out**. If they were included, YOLO would
+  treat them as "nothing here".
+- `train` and `val` point at the same images. Split them yourself for a real evaluation.
+- If you move the export folder, update `path:` in `data.yaml`.
 
 ## Importing annotations
 

{lannotex-0.1.0 → lannotex-0.1.1}/src/lannotex/__init__.py

@@ -1,2 +1,2 @@
 """Lannotex: offline-first image annotation."""
-__version__ = "0.1.0"
+__version__ = "0.1.1"

{lannotex-0.1.0 → lannotex-0.1.1}/src/lannotex/exporters.py

@@ -2,7 +2,9 @@
 from __future__ import annotations
 import csv
 import json
+import os
 from pathlib import Path
+import shutil
 import tempfile
 import uuid
 from . import __version__
@@ -76,6 +78,19 @@ def coco_record(image, annotations, labels):
     return {'images':[image],'categories':[{'id':i+1,'name':s} for i,s in enumerate(labels)],'annotations':output}
 
 
+def link_or_copy(source, target):
+    try: os.link(source, target)
+    except OSError: shutil.copy2(source, target)
+
+
+def yolo_data_yaml(root, labels):
+    names = '\n'.join(f'  {i}: {json.dumps(name)}' for i, name in enumerate(labels))
+    return ('# Ultralytics YOLO dataset exported by Lannotex.\n'
+            '# Train:  yolo detect train data=data.yaml model=yolo11n.pt\n'
+            "# Update 'path' if you move this folder. train and val use the same images; split them for real evaluation.\n"
+            f'path: {json.dumps(str(root))}\ntrain: images\nval: images\nnames:\n{names}\n')
+
+
 def export_project(root, destination, format_name, cancel, progress):
     """Stream a consistent DB snapshot; publish the completed directory by rename."""
     project = Project(root,create=False)
@@ -87,6 +102,8 @@ def export_project(root, destination, format_name, cancel, progress):
     try:
         labels = [r['name'] for r in project.labels()]
         atomic_text(output/'classes.json',json.dumps(labels,indent=2))
+        yolo = format_name == 'YOLO boxes'
+        if yolo: (output/'images').mkdir(); (output/'labels').mkdir()
         # Spool COCO arrays to disk, rather than keeping all annotations in RAM.
         with (output/'images.jsonl').open('w',encoding='utf-8') as ims, (output/'annotations.jsonl').open('w',encoding='utf-8') as anns, (output/'classification.csv').open('w',encoding='utf-8',newline='') as csvfile:
             writer = csv.writer(csvfile); writer.writerow(['image_id','image_path','status',*labels])
@@ -104,6 +121,10 @@ def export_project(root, destination, format_name, cancel, progress):
                     summary['skipped'] += 1
                     if len(summary['errors'])<100: summary['errors'].append(f"{row['path']}: {'; '.join(errors)}")
                     continue
+                if yolo and row['status']=='new':
+                    # YOLO reads an empty label file as "no objects"; never-annotated images would become false negatives.
+                    summary['unlabeled'] += 1
+                    continue
                 summary['included'] += 1
                 if row['status']=='new': summary['unlabeled'] += 1
                 name = f"{row['id']:08d}_{Path(row['path']).stem}"
@@ -112,9 +133,11 @@ def export_project(root, destination, format_name, cancel, progress):
                 ims.write(json.dumps(image)+'\n')
                 if format_name == 'Labelme JSON':
                     atomic_text(output/(name+'.json'),json.dumps(labelme_data(source,row['width'],row['height'],annotations,negative),indent=2))
-                elif format_name == 'YOLO boxes':
+                elif yolo:
                     lines = [yolo_line(a,labels.index(a.label)) for a in annotations if a.kind=='box']
-                    atomic_text(output/(name+'.txt'),'\n'.join(lines)+ ('\n' if lines else ''))
+                    source_path = project.resolve(row['path'])
+                    link_or_copy(source_path, output/'images'/(name+source_path.suffix.lower()))
+                    atomic_text(output/'labels'/(name+'.txt'),'\n'.join(lines)+ ('\n' if lines else ''))
                     summary['unsupported_annotations'] += sum(a.kind!='box' for a in annotations)
                 elif format_name == 'COCO JSON':
                     record = coco_record(image,annotations,labels)
@@ -138,9 +161,11 @@ def export_project(root, destination, format_name, cancel, progress):
                             stream.write(line.strip()); first=False
                     stream.write(sep)
                 stream.write(json.dumps([{'id':i+1,'name':s} for i,s in enumerate(labels)])+'}')
-        atomic_text(output/'manifest.json',json.dumps({'version':__version__,'format_version':1,'editable_local_export':True,'image_policy':'Referenced, not copied','summary':summary},indent=2))
+        policy = 'Hard-linked or copied into images/' if yolo else 'Referenced, not copied'
+        atomic_text(output/'manifest.json',json.dumps({'version':__version__,'format_version':1,'editable_local_export':True,'image_policy':policy,'summary':summary},indent=2))
         if not summary.get('cancelled'):
             final = destination/('Lannotex-export-'+uuid.uuid4().hex[:8]); output.rename(final); output=final
+            if yolo: atomic_text(output/'data.yaml', yolo_data_yaml(output.resolve(), labels))
         summary['path'] = str(output)
         return summary
     finally:

{lannotex-0.1.0 → lannotex-0.1.1}/src/lannotex.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lannotex
-Version: 0.1.0
+Version: 0.1.1
 Summary: Fast, offline-first image annotation for classifications, boxes, and polygons.
 Author: Lourdhu Raju
 Maintainer: Lourdhu Raju
@@ -133,7 +133,7 @@ Every shortcut can be remapped. See the [annotating guide](https://lourdhu02.git
 | **Annotate** | Bounding boxes · polygons with vertex drag, insert, and delete · multi-label image classes · "no target" negatives · 100-step undo/redo · zoom under the pointer, pan, arrow-key nudging · focus mode · light and dark themes |
 | **Stay safe** | SQLite projects with versioned migrations · recovery drafts and 700 ms autosave · transactional saves · geometry validation · backup and restore · relinking for moved images · EXIF orientation handled |
 | **Scale** | Virtualized image list (at most 1,024 records in memory) · background import and decoding · 96 MB preview cache · coordinates normalized to the original resolution |
-| **Export** | Labelme JSON · YOLO · COCO JSON · classification CSV · lossless native JSONL · each export reports anything it skipped |
+| **Export** | Labelme JSON · ready-to-train YOLO (`images/`, `labels/`, `data.yaml`) · COCO JSON · classification CSV · lossless native JSONL · each export reports anything it skipped |
 | **Automate** | `lannotex export` and `lannotex analyze` run headless in CI, with no display needed |
 | **Collaborate** | Optional LAN host with per-reviewer tokens, background sync, revision conflicts you resolve explicitly, revocation, and an audit history |
 
@@ -181,8 +181,8 @@ hashes. There is no telemetry, no external AI service, and no automatic upload.
 
 ## Roadmap
 
-Next up: a ready-to-train YOLO layout (`images/`, `labels/`, `data.yaml`), more LabelMe
-shape types, VOC and YOLO-seg export, and number-key label selection. See the
+Next up: more LabelMe shape types (points, lines, circles), VOC and YOLO-seg export, and
+number-key label selection. See the
 [roadmap](https://lourdhu02.github.io/Lannotex/ROADMAP/) and the
 [measured performance](https://lourdhu02.github.io/Lannotex/PERFORMANCE/).
 

{lannotex-0.1.0 → lannotex-0.1.1}/tests/test_exporters.py

@@ -1,7 +1,10 @@
 """Exporter primitives and headless project export."""
+import json
 from pathlib import Path
 import threading
 
+from PIL import Image
+
 from lannotex import __version__
 from lannotex.domain import Annotation
 from lannotex.exporters import coco_record, export_project, labelme_data, parse_labelme, yolo_line
@@ -61,3 +64,27 @@ def test_export_project_empty_creates_manifest(tmp_path):
     assert (out / "classes.json").exists()
     assert (out / "manifest.json").exists()
     assert (out / "images.jsonl").exists()
+
+
+def test_yolo_export_is_ultralytics_ready(tmp_path):
+    src = tmp_path / "imgs"; src.mkdir()
+    Image.new("RGB", (200, 100)).save(src / "a.png")
+    Image.new("RGB", (50, 50)).save(src / "b.jpg")
+    Image.new("RGB", (50, 50)).save(src / "c.png")
+    root = tmp_path / "project"; p = Project(root); p.add_label("cat"); p.add_label("dog")
+    a = p.add_image(src / "a.png", 200, 100); b = p.add_image(src / "b.jpg", 50, 50); p.add_image(src / "c.png", 50, 50)
+    p.save_annotations(a, [Annotation("dog", "box", [.1, .2, .5, .6]), Annotation("cat", "polygon", [[0, 0], [1, 0], [1, 1]])])
+    p.save_annotations(b, [], negative=True)
+    p.close()
+
+    result = export_project(root, tmp_path / "out", "YOLO boxes", threading.Event(), lambda *args: None)
+    out = Path(result["path"])
+    assert result["included"] == 2 and result["unlabeled"] == 1 and result["unsupported_annotations"] == 1
+    images = sorted(f.name for f in (out / "images").iterdir())
+    labels = sorted(f.name for f in (out / "labels").iterdir())
+    assert [Path(n).stem for n in images] == [Path(n).stem for n in labels] and len(images) == 2
+    assert (out / "labels" / labels[0]).read_text() == "1 0.300000 0.400000 0.400000 0.400000\n"
+    assert (out / "labels" / labels[1]).read_text() == ""
+    data = (out / "data.yaml").read_text()
+    assert "train: images" in data and '0: "cat"' in data and '1: "dog"' in data
+    assert json.loads(data.split("path: ")[1].splitlines()[0]) == str(out.resolve())