annodesk 0.3.1__py3-none-any.whl

annodesk/__init__.py

@@ -0,0 +1,3 @@
+"""AnnoDesk image annotation workbench."""
+
+__version__ = "0.3.1"

annodesk/__main__.py

@@ -0,0 +1,3 @@
+from annodesk.cli import main
+
+main()

annodesk/app.py

@@ -0,0 +1,102 @@
+"""Application factory for combined, API-only and UI-only deployment."""
+
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Literal
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from annodesk import __version__
+from annodesk.events import EventLog, log_routes
+from annodesk.storage import RevisionConflict
+
+
+class WorkbenchFiles(StaticFiles):
+    """Never reuse entry HTML across builds, including conditional requests."""
+
+    def file_response(self, full_path, stat_result, scope, status_code=200):
+        if Path(full_path).suffix.lower() == ".html":
+            response = FileResponse(
+                full_path,
+                status_code=status_code,
+                stat_result=stat_result,
+                headers={"Cache-Control": "no-store"},
+            )
+            # Avoid 304 responses that keep a browser's old asset manifest alive.
+            for name in ("etag", "last-modified"):
+                if name in response.headers:
+                    del response.headers[name]
+            return response
+        return super().file_response(full_path, stat_result, scope, status_code)
+
+
+def create_app(
+    mode: Literal["serve", "api", "ui"] = "serve",
+    api_url: str = "",
+    project: Path | None = None,
+    models_config: Path | None = None,
+    events: EventLog | None = None,
+) -> FastAPI:
+    events = events or EventLog()
+    router = None
+
+    @asynccontextmanager
+    async def lifespan(_app):
+        try:
+            yield
+        finally:
+            if router:
+                router.close()
+            events.close()
+
+    app = FastAPI(title="AnnoDesk", version=__version__, lifespan=lifespan)
+    app.state.events = events
+    app.include_router(log_routes(events))
+    app.add_middleware(
+        CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"]
+    )
+
+    @app.middleware("http")
+    async def fresh_json(request: Request, call_next):
+        response = await call_next(request)
+        if response.headers.get("content-type", "").startswith("application/json"):
+            response.headers["Cache-Control"] = "no-store"
+        return response
+
+    @app.exception_handler(ValueError)
+    async def invalid(_request: Request, error: ValueError):
+        events.emit("WARNING", str(error), event_type="request_error")
+        return JSONResponse(
+            {"detail": str(error)}, status_code=409 if isinstance(error, RevisionConflict) else 400
+        )
+
+    @app.exception_handler(KeyError)
+    async def missing(_request: Request, error: KeyError):
+        return JSONResponse({"detail": str(error)}, status_code=404)
+
+    if mode != "ui":
+        from annodesk.routes import project_routes
+
+        router = project_routes(project, models_config, events)
+        app.include_router(router)
+
+        @app.get("/api/v1/info")
+        def info():
+            return {"version": __version__, "protocol": 1, "name": "AnnoDesk"}
+
+    if mode != "api":
+
+        @app.get("/ui-config.json")
+        def ui_config():
+            base = api_url.rstrip("/")
+            return JSONResponse(
+                {"apiBase": f"{base}/api/v1"}, headers={"Cache-Control": "no-store"}
+            )
+
+        app.mount(
+            "/", WorkbenchFiles(directory=Path(__file__).parent / "web_dist", html=True), name="web"
+        )
+    return app

annodesk/assets/models/yolo11n/NOTICE.md

@@ -0,0 +1,12 @@
+# YOLO11n pretrained weights
+
+- Publisher: Ultralytics
+- Model: YOLO11n, COCO detection (80 classes)
+- Source: https://huggingface.co/Ultralytics/YOLO11
+- Upstream download: https://github.com/ultralytics/assets/releases/download/v8.3.0/yolo11n.pt
+- SHA256: `0ebbc80d4a7680d14987a577cd21342b65ecfd94632bd9a8da63ae6417644ee1`
+- Original license: AGPL-3.0; see https://www.ultralytics.com/license.
+
+This is the unmodified local checkpoint used in AnnoDesk's real-model validation.
+AnnoDesk's MIT declaration applies to its original source code, not to this
+third-party checkpoint or third-party dependencies. No model is downloaded at runtime.

annodesk/batch.py

@@ -0,0 +1,388 @@
+"""Shared CLI/API batch coordinator; only this parent process commits labels."""
+
+import json
+import os
+import signal
+import threading
+import time
+from pathlib import Path
+
+from annodesk.detector import inspect_classes
+from annodesk.devices import DevicePlan, ExecutionOptions, resolve_plan
+from annodesk.events import EventLog
+from annodesk.execution import ImageExecutor, file_stamp
+from annodesk.inference import SegmentRequest, compute_annotation
+from annodesk.lease import ProjectLease
+from annodesk.models import ModelConfig, ModelRegistry
+from annodesk.operations import commit_result, eligible, prepare_detection, target_task
+from annodesk.storage import Project, atomic_write
+
+
+def new_report(dataset: Project, body: SegmentRequest) -> dict:
+    with dataset.lock:
+        ids = (
+            list(dict.fromkeys(body.image_ids))
+            if body.image_ids is not None
+            else list(dataset.entries)
+        )
+        if body.image_ids is not None and (not ids or any(i not in dataset.entries for i in ids)):
+            raise ValueError("Choose a non-empty image range belonging to this project")
+        paths = {image_id: dataset.entries[image_id]["path"] for image_id in ids}
+    return {
+        "operation": body.operation,
+        "image_paths": paths,
+        "skip_reasons": {"excluded": 0, "review_state": 0, "no_content": 0},
+        "boxes_added": 0,
+        "boxes_updated": 0,
+        "detections_discarded": 0,
+        "classes_added": 0,
+        "model": body.model,
+        "processed": 0,
+        "completed": 0,
+        "skipped": 0,
+        "failed": [],
+        "input_total": len(ids),
+        "total": len(ids),
+        "remaining": ids,
+        "request": body.model_dump(),
+        "prepared": False,
+        "status": "running",
+        "phase": "preflight",
+        "cancel": False,
+        "active_workers": [],
+        "results": [],
+        "started_at": time.time(),
+    }
+
+
+def run_batch(
+    dataset,
+    registry,
+    body,
+    report,
+    events,
+    persist,
+    *,
+    executor_factory=ImageExecutor,
+    available=None,
+    class_probe=None,
+):
+    project_id = dataset.metadata["id"]
+    context = {"project_id": project_id, "job_id": report.get("id")}
+    with dataset.lock:
+        # Older persisted reports lack paths. Never depend on mutable entries
+        # while recording a result (the image may have been removed externally).
+        if "image_paths" not in report:
+            report["image_paths"] = {
+                image_id: entry["path"] for image_id, entry in dataset.entries.items()
+            }
+        paths = report["image_paths"]
+
+    def class_snapshot():
+        with dataset.lock:
+            return sorted(
+                [
+                    {key: c[key] for key in ("id", "index", "name")}
+                    for c in dataset.metadata["classes"]
+                ],
+                key=lambda c: c["index"],
+            )
+
+    def failed(image_id, annotation, error, metrics=None):
+        path = paths.get(image_id, image_id)
+        if error:
+            report["failed"].append({"image": path, "error": error})
+            events.emit(
+                "ERROR",
+                f"{path}: {error}",
+                event_type="image_failed",
+                error_code=error,
+                **context,
+            )
+        else:
+            report["processed"] += 1
+            if body.operation == "detection":
+                report["project_classes"] = class_snapshot()
+        report.setdefault("results", []).append(
+            {
+                "image": path,
+                "status": "failed" if error else "saved",
+                "error": error,
+                **(metrics or {"elapsed_seconds": 0, "attempts": 0}),
+            }
+        )
+        for key in ("boxes_added", "boxes_updated", "detections_discarded", "classes_added"):
+            report[key] = report.get(key, 0) + (metrics or {}).get(key, 0)
+        report["completed"] += 1
+        report["remaining"].remove(image_id)
+        persist()
+
+    try:
+        if body.operation == "segmentation" and body.text:
+            raise ValueError("Batch segmentation only supports single masks from existing boxes")
+        # Resolve before preflight so invalid configuration never mutates labels.
+        geometry = body.operation == "boxes_from_masks"
+        if geometry:
+            if (
+                body.device_type not in ("auto", "cpu")
+                or body.devices != "auto"
+                or str(body.num_workers) not in ("auto", "1")
+            ):
+                raise ValueError(
+                    "Boxes from masks is CPU geometry; GPU and multiple workers are not used"
+                )
+            model, weights = "", None
+            plan = DevicePlan("cpu", ["cpu"], ["cpu"])
+            report.update(model="", plan=plan.to_dict())
+        elif report.get("frozen_config"):
+            if report.get("cuda_visible_devices") != os.environ.get("CUDA_VISIBLE_DEVICES"):
+                raise ValueError(
+                    "CUDA_VISIBLE_DEVICES changed; start a new job to use a different device mapping"
+                )
+            frozen = ModelRegistry.__new__(ModelRegistry)
+            frozen.path = Path(report["config_path"])
+            frozen.config = ModelConfig.model_validate(report["frozen_config"])
+            registry = frozen
+            model = report["model"]
+            weights = registry.weights(model)
+            if [weights.stat().st_mtime_ns, weights.stat().st_size] != report["weights_stamp"]:
+                raise ValueError("Checkpoint changed; start a new batch")
+            plan = DevicePlan(**report["plan"])
+        else:
+            initial_registry = ModelRegistry.__new__(ModelRegistry)
+            initial_registry.path = registry.path
+            initial_registry.config = registry.config.model_copy(deep=True)
+            registry = initial_registry.freeze()
+            model = registry.entry(body.model, body.operation).id
+            weights = registry.weights(model)
+            plan = resolve_plan(
+                ExecutionOptions(body.device_type, body.devices, str(body.num_workers)), available
+            )
+            config = registry.config.model_dump()
+            for entry in config["models"]:
+                if entry["id"] == model:
+                    entry["source"] = str(registry.resolve(model))
+            report.update(
+                plan=plan.to_dict(),
+                model=model,
+                weights=str(weights),
+                weights_stamp=[weights.stat().st_mtime_ns, weights.stat().st_size],
+                frozen_config=config,
+                config_path=str(registry.path),
+                cuda_visible_devices=os.environ.get("CUDA_VISIBLE_DEVICES"),
+            )
+        if not geometry:
+            frozen = ModelRegistry.__new__(ModelRegistry)
+            frozen.path = Path(report["config_path"])
+            frozen.config = ModelConfig.model_validate(report["frozen_config"])
+            registry = frozen
+        body = body.model_copy(update={"model": model})
+        if body.operation == "detection":
+            current_classes = class_snapshot()
+            if "project_classes" in report and report["project_classes"] != current_classes:
+                raise ValueError("Project class definitions changed; start a new batch")
+            report["project_classes"] = current_classes
+            names = report.get("class_names") or (class_probe or inspect_classes)(registry, model)
+            body = prepare_detection(dataset, body, {int(k): v for k, v in names.items()})
+            report["class_names"] = body.class_names
+        report["request"] = body.model_dump()
+        events.emit(
+            "INFO",
+            f"Model {model}: {weights}; devices={plan.devices}; workers={plan.workers}",
+            event_type="device_plan",
+            **context,
+        )
+        if len(plan.workers) < len(plan.devices):
+            events.emit(
+                "WARNING",
+                f"Unused devices: {plan.devices[len(plan.workers) :]}",
+                event_type="device_plan",
+                **context,
+            )
+        if not report["prepared"]:
+            last_checkpoint = time.monotonic()
+            for image_id in list(report["remaining"]):
+                if report["cancel"]:
+                    break
+                try:
+                    with dataset.lock:
+                        if image_id not in dataset.entries:
+                            raise ValueError("Image removed from project during processing")
+                        annotation = dataset.annotation(image_id, materialize=False)
+                    if not eligible(annotation, body):
+                        reason = (
+                            "excluded"
+                            if annotation.excluded
+                            else "review_state"
+                            if getattr(annotation, target_task(body) + "_review")
+                            not in body.review_states
+                            else "no_content"
+                        )
+                        report.setdefault(
+                            "skip_reasons", {"excluded": 0, "review_state": 0, "no_content": 0}
+                        )[reason] += 1
+                        report["skipped"] += 1
+                        report["remaining"].remove(image_id)
+                except Exception as error:
+                    failed(image_id, None, str(error))
+                report["total"] = report["input_total"] - report["skipped"]
+                if time.monotonic() - last_checkpoint >= 1:
+                    persist()
+                    last_checkpoint = time.monotonic()
+            persist()
+            if not report["cancel"]:
+                report["prepared"] = True
+        if geometry:
+            report["phase"] = "running"
+            persist()
+            for image_id in list(report["remaining"]):
+                if report["cancel"]:
+                    break
+                start = time.monotonic()
+                try:
+                    with dataset.lock:
+                        if image_id not in dataset.entries:
+                            raise ValueError("Image removed from project during processing")
+                        annotation = dataset.annotation(image_id)
+                        if not eligible(annotation, body):
+                            raise ValueError(
+                                "Image no longer matches the batch eligibility; start a new batch"
+                            )
+                        size = dataset.image_size(image_id)
+                        stamp = file_stamp(dataset.image_path(image_id))
+                    result = compute_annotation(
+                        dataset.image_path(image_id), size, annotation, body, None
+                    )
+                    if file_stamp(dataset.image_path(image_id)) != stamp:
+                        raise ValueError("Image changed during processing")
+                    result = commit_result(dataset, image_id, result, body)
+                    failed(
+                        image_id,
+                        result,
+                        None,
+                        {
+                            **result.operation_stats,
+                            "elapsed_seconds": round(time.monotonic() - start, 3),
+                            "attempts": 1,
+                        },
+                    )
+                except Exception as error:
+                    failed(image_id, None, str(error))
+        if not geometry and report["remaining"] and not report["cancel"]:
+            report["phase"] = "loading"
+            persist()
+            events.emit(
+                "INFO",
+                f"Batch loading {len(plan.workers)} workers; {report['total']} images require processing",
+                event_type="batch_start",
+                **context,
+            )
+            if [weights.stat().st_mtime_ns, weights.stat().st_size] != report["weights_stamp"]:
+                raise ValueError("Checkpoint changed while preparing the batch")
+            executor = executor_factory(registry, model, plan, events.bind(**context))
+            executor.expected_names = body.class_names if body.operation == "detection" else None
+            executor.start()
+            report["phase"] = "running"
+            persist()
+
+            def activity(workers):
+                report["active_workers"] = workers
+
+            executor.run(
+                dataset, list(report["remaining"]), body, failed, lambda: report["cancel"], activity
+            )
+        report["status"] = "cancelled" if report["cancel"] else "complete"
+        report["phase"] = report["status"]
+        events.emit(
+            "WARNING" if report["cancel"] else "SUCCESS",
+            f"Batch {report['status']}: {report['completed']}/{report['total']} finished · {report['processed']} succeeded · {len(report['failed'])} failed · {report['skipped']} skipped",
+            event_type="batch_complete",
+            **context,
+        )
+    except BaseException as error:
+        report.update(
+            status="interrupted" if isinstance(error, KeyboardInterrupt) else "failed",
+            phase="stopped",
+            error=str(error),
+        )
+        events.emit("CRITICAL", f"Batch stopped: {error}", event_type="batch_fatal", **context)
+        raise
+    finally:
+        report["active_workers"] = []
+        report["elapsed_seconds"] = round(time.time() - report["started_at"], 2)
+        persist()
+
+
+def segment_dataset(
+    project: Path,
+    model: str,
+    registry: ModelRegistry | None,
+    options: ExecutionOptions | None = None,
+    events: EventLog | None = None,
+    *,
+    executor_factory=ImageExecutor,
+    available=None,
+    request: SegmentRequest | None = None,
+    class_probe=None,
+) -> dict:
+    if request is None or request.operation != "boxes_from_masks":
+        registry.weights(
+            model or registry.entry("", request.operation if request else "segmentation").id
+        )
+    events = events or EventLog()
+    options = options or ExecutionOptions()
+    with ProjectLease(project):
+        dataset = Project(project)
+        events.emit(
+            "INFO",
+            f"Project write lease acquired: {dataset.root}",
+            event_type="project_lock",
+            project_id=dataset.metadata["id"],
+        )
+        body = request or SegmentRequest(model=model, **options.__dict__)
+        report = new_report(dataset, body)
+        report_path = (
+            dataset.private
+            / {
+                "segmentation": "segment-report.json",
+                "detection": "detect-report.json",
+                "boxes_from_masks": "boxes-from-masks-report.json",
+            }[body.operation]
+        )
+
+        def persist():
+            atomic_write(report_path, json.dumps(report, indent=2))
+
+        previous_handler = None
+        interrupts = 0
+
+        def interrupt(_signal, _frame):
+            nonlocal interrupts
+            interrupts += 1
+            if interrupts > 1:
+                raise KeyboardInterrupt
+            report["cancel"] = True
+            events.emit(
+                "WARNING",
+                "Cancellation requested; finishing active images. Press Ctrl+C again to terminate.",
+                event_type="batch_cancel",
+            )
+
+        if threading.current_thread() is threading.main_thread():
+            previous_handler = signal.signal(signal.SIGINT, interrupt)
+        try:
+            run_batch(
+                dataset,
+                registry,
+                body,
+                report,
+                events,
+                persist,
+                executor_factory=executor_factory,
+                available=available,
+                class_probe=class_probe,
+            )
+        finally:
+            if previous_handler is not None:
+                signal.signal(signal.SIGINT, previous_handler)
+        return report

annodesk/candidates.py

@@ -0,0 +1,153 @@
+"""Stateless, read-only mask previews and revision-checked explicit application."""
+
+import base64
+import io
+import math
+
+import numpy as np
+from PIL import Image
+from pydantic import BaseModel, Field
+
+from annodesk.inference import SegmentRequest
+from annodesk.masks import contours, decode_mask, encode_mask
+from annodesk.storage import RevisionConflict
+
+
+class CandidateRequest(SegmentRequest):
+    expected_revision: int = Field(ge=0)
+    project_id: str
+    multimask_output: bool = True
+
+
+class CandidateApply(BaseModel):
+    project_id: str
+    instance_id: str
+    revision: int = Field(ge=0)
+    image_stamp: str
+    model: str
+    mask: dict
+
+
+def image_stamp(project, image_id):
+    stat = project.image_path(image_id).stat()
+    # Preserve nanosecond precision across JavaScript JSON round trips.
+    return f"{stat.st_mtime_ns}:{stat.st_size}"
+
+
+def target(annotation, instance_id):
+    obj = next((o for o in annotation.instances if o.id == instance_id), None)
+    if annotation.excluded:
+        raise ValueError("Image is excluded")
+    if obj is None:
+        raise ValueError("Select an object with points or a box prompt")
+    if obj.locked:
+        raise ValueError("Object is locked")
+    if obj.hidden:
+        raise ValueError("Unhide this object before generating candidates")
+    if not (obj.box or obj.prompt_box or obj.points):
+        raise ValueError("Select an object with points or a box prompt")
+    return obj
+
+
+def overlay(mask, color):
+    rgba = np.zeros((*mask.shape, 4), dtype=np.uint8)
+    rgba[:, :, :3] = [int(color[i : i + 2], 16) for i in (1, 3, 5)]
+    rgba[:, :, 3] = mask * 110
+    output = io.BytesIO()
+    Image.fromarray(rgba).save(output, format="PNG")
+    return "data:image/png;base64," + base64.b64encode(output.getvalue()).decode("ascii")
+
+
+def preview_candidates(project, image_id, body, adapter):
+    if body.operation != "segmentation" or body.text:
+        raise ValueError("Mask candidates require a point/box segmentation model, not text")
+    with project.lock:
+        if body.project_id != project.metadata["id"]:
+            raise RevisionConflict("Project changed; generate candidates again")
+        annotation = project.annotation(image_id, materialize=False)
+        if annotation.revision != body.expected_revision:
+            raise RevisionConflict("Annotation changed; generate candidates again")
+        obj = target(annotation, body.instance_id)
+        width, height = project.image_size(image_id)
+        stamp = image_stamp(project, image_id)
+        color = next(
+            (c["color"] for c in project.metadata["classes"] if c["id"] == obj.class_id), "#657286"
+        )
+    if body.multimask_output:
+        if not callable(getattr(adapter, "predict_candidates", None)):
+            raise ValueError("This model adapter does not support mask candidates")
+        predictions = adapter.predict_candidates(
+            project.image_path(image_id), body.model, obj.prompt_box or obj.box, obj.points
+        )
+    else:
+        predictions = [
+            (mask, None)
+            for mask in adapter.predict(
+                project.image_path(image_id), body.model, obj.prompt_box or obj.box, obj.points, ""
+            )[:1]
+        ]
+    valid = []
+    for mask, score in predictions:
+        if mask.shape != (height, width):
+            raise ValueError("Model mask size does not match the original image")
+        binary = (mask != 0).astype(np.uint8)
+        if not binary.any():
+            continue
+        score = float(score) if score is not None and math.isfinite(float(score)) else None
+        valid.append((binary, score))
+    if not valid:
+        raise ValueError("No mask returned; existing annotations were preserved")
+    valid.sort(
+        key=lambda item: (item[1] is not None, item[1] if item[1] is not None else 0), reverse=True
+    )
+    with project.lock:
+        if (
+            image_stamp(project, image_id) != stamp
+            or project.annotation(image_id, materialize=False).revision != annotation.revision
+        ):
+            raise RevisionConflict("Image or annotation changed; generate candidates again")
+    return {
+        "project_id": project.metadata["id"],
+        "image_id": image_id,
+        "instance_id": obj.id,
+        "revision": annotation.revision,
+        "image_stamp": stamp,
+        "model": body.model,
+        "items": [
+            {
+                "mask": encode_mask(mask),
+                "polygons": contours(mask),
+                "quality": score,
+                "overlay": overlay(mask, color),
+            }
+            for mask, score in valid[:3]
+        ],
+    }
+
+
+def apply_candidate(project, image_id, body):
+    with project.lock:
+        if project.metadata["id"] != body.project_id:
+            raise RevisionConflict("Project changed; generate candidates again")
+        annotation = project.annotation(image_id)
+        if (
+            annotation.revision != body.revision
+            or image_stamp(project, image_id) != body.image_stamp
+        ):
+            raise RevisionConflict("Image or annotation changed; generate candidates again")
+        obj = target(annotation, body.instance_id)
+        width, height = project.image_size(image_id)
+        if body.mask.get("size") != [height, width] or not isinstance(body.mask.get("counts"), str):
+            raise ValueError("Candidate mask size does not match the image")
+        try:
+            binary = decode_mask(body.mask)
+        except (ValueError, TypeError, OverflowError) as error:
+            raise ValueError("Invalid candidate mask") from error
+        if binary.shape != (height, width) or not binary.any():
+            raise ValueError("Candidate mask is empty or has invalid dimensions")
+        obj.mask, obj.polygons, obj.source = encode_mask(binary), contours(binary), body.model
+        annotation.segmentation_review = "pending"
+        annotation.explicit_empty["segmentation"] = False
+        if image_stamp(project, image_id) != body.image_stamp:
+            raise RevisionConflict("Image changed; generate candidates again")
+        return project.save(image_id, annotation)