apud 0.0.1__py3-none-any.whl

apud/__init__.py

@@ -0,0 +1,3 @@
+"""apud: IIIF-grounded, citable vision for historical documents."""
+
+__version__ = "0.0.1"

apud/annotations.py

@@ -0,0 +1,79 @@
+"""W3C Web Annotations anchored to IIIF canvases, plus IIIF Content State links for citation."""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any
+from urllib.parse import quote, unquote
+
+from apud.iiif.image import Region
+
+_FRAGMENT_SPEC = "http://www.w3.org/TR/media-frags/"
+
+
+def _target(canvas_id: str, manifest_id: str, region: Region) -> dict[str, Any]:
+    return {
+        "type": "SpecificResource",
+        "source": {
+            "id": canvas_id,
+            "type": "Canvas",
+            "partOf": [{"id": manifest_id, "type": "Manifest"}],
+        },
+        "selector": {
+            "type": "FragmentSelector",
+            "conformsTo": _FRAGMENT_SPEC,
+            "value": f"xywh={region.xywh}",
+        },
+    }
+
+
+def transcription_annotation(
+    annotation_id: str,
+    canvas_id: str,
+    manifest_id: str,
+    region: Region,
+    text: str,
+    *,
+    language: str | None = None,
+    generator: str | None = None,
+) -> dict[str, Any]:
+    """A transcription of ``region`` (canvas coordinates) as a Presentation 3 annotation."""
+    body: dict[str, Any] = {"type": "TextualBody", "value": text, "format": "text/plain"}
+    if language:
+        body["language"] = language
+    annotation: dict[str, Any] = {
+        "id": annotation_id,
+        "type": "Annotation",
+        "motivation": "supplementing",
+        "body": body,
+        "target": _target(canvas_id, manifest_id, region),
+    }
+    if generator:
+        annotation["generator"] = generator
+    return annotation
+
+
+def annotation_page(page_id: str, items: list[dict[str, Any]]) -> dict[str, Any]:
+    return {
+        "@context": "http://iiif.io/api/presentation/3/context.json",
+        "id": page_id,
+        "type": "AnnotationPage",
+        "items": items,
+    }
+
+
+def encode_content_state(canvas_id: str, manifest_id: str, region: Region) -> str:
+    """Encode a IIIF Content State pointing at a canvas region, for ``?iiif-content=`` links."""
+    state = {
+        "id": f"{canvas_id}#xywh={region.xywh}",
+        "type": "Canvas",
+        "partOf": [{"id": manifest_id, "type": "Manifest"}],
+    }
+    uri_encoded = quote(json.dumps(state, separators=(",", ":")), safe="-_.!~*'()")
+    return base64.urlsafe_b64encode(uri_encoded.encode()).decode().rstrip("=")
+
+
+def decode_content_state(encoded: str) -> dict[str, Any]:
+    padded = encoded + "=" * (-len(encoded) % 4)
+    return json.loads(unquote(base64.urlsafe_b64decode(padded).decode()))

apud/client.py

@@ -0,0 +1,53 @@
+"""Thin HTTP client for IIIF endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from apud import __version__
+from apud.iiif.image import ImageService, Region, RegionRequest, parse_info
+from apud.iiif.manifest import Manifest, parse_manifest
+
+USER_AGENT = f"apud/{__version__} (+https://github.com/cadeos/apud)"
+
+
+class IIIFClient:
+    def __init__(self, timeout: float = 30.0, client: httpx.Client | None = None) -> None:
+        self._http = client or httpx.Client(
+            timeout=timeout, follow_redirects=True, headers={"User-Agent": USER_AGENT}
+        )
+
+    def __enter__(self) -> IIIFClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _json(self, url: str) -> dict[str, Any]:
+        response = self._http.get(url)
+        response.raise_for_status()
+        return response.json()
+
+    def manifest(self, url: str) -> Manifest:
+        return parse_manifest(self._json(url))
+
+    def image_service(self, service_id: str) -> ImageService:
+        url = (
+            service_id
+            if service_id.endswith("info.json")
+            else f"{service_id.rstrip('/')}/info.json"
+        )
+        return parse_info(self._json(url))
+
+    def region(
+        self, service: ImageService, region: Region, max_side: int
+    ) -> tuple[RegionRequest, bytes]:
+        request = service.region_request(region, max_side)
+        response = self._http.get(request.url)
+        response.raise_for_status()
+        return request, response.content

apud/iiif/__init__.py

@@ -0,0 +1,21 @@
+from apud.iiif.image import ImageService, Region, RegionRequest, UnsupportedRequest, parse_info
+from apud.iiif.manifest import (
+    Canvas,
+    Manifest,
+    canvas_to_image,
+    image_to_canvas,
+    parse_manifest,
+)
+
+__all__ = [
+    "Canvas",
+    "ImageService",
+    "Manifest",
+    "Region",
+    "RegionRequest",
+    "UnsupportedRequest",
+    "canvas_to_image",
+    "image_to_canvas",
+    "parse_info",
+    "parse_manifest",
+]

apud/iiif/image.py

@@ -0,0 +1,124 @@
+"""IIIF Image API: parse info.json (v2 and v3) and build region requests sized for a model."""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+_LEVEL_RE = re.compile(r"level([012])")
+
+
+class UnsupportedRequest(ValueError):
+    """The image service cannot serve the request at its declared compliance level."""
+
+
+@dataclass(frozen=True)
+class Region:
+    """A rectangle in full-resolution image pixels."""
+
+    x: int
+    y: int
+    w: int
+    h: int
+
+    def __post_init__(self) -> None:
+        if self.w <= 0 or self.h <= 0:
+            raise ValueError(f"region must have positive size, got {self.w}x{self.h}")
+        if self.x < 0 or self.y < 0:
+            raise ValueError(f"region origin must be non-negative, got {self.x},{self.y}")
+
+    def clamp(self, width: int, height: int) -> Region:
+        """Crop the region to the image bounds, as an IIIF server would."""
+        if self.x >= width or self.y >= height:
+            raise ValueError("region lies entirely outside the image")
+        return Region(self.x, self.y, min(self.w, width - self.x), min(self.h, height - self.y))
+
+    @property
+    def xywh(self) -> str:
+        return f"{self.x},{self.y},{self.w},{self.h}"
+
+
+@dataclass(frozen=True)
+class RegionRequest:
+    """A ready-to-fetch region URL plus the scale needed to map model output back to the image."""
+
+    url: str
+    region: Region
+    width: int
+    height: int
+
+    @property
+    def scale(self) -> float:
+        """Requested pixels per full-resolution pixel (<= 1, servers are never asked to upscale)."""
+        return self.width / self.region.w
+
+    def to_image(self, x: float, y: float) -> tuple[float, float]:
+        """Map a point in the returned crop to full-resolution image coordinates."""
+        return self.region.x + x / self.scale, self.region.y + y / self.scale
+
+
+@dataclass(frozen=True)
+class ImageService:
+    id: str
+    width: int
+    height: int
+    version: int
+    level: int
+    sizes: list[tuple[int, int]] = field(default_factory=list)
+    max_width: int | None = None
+    max_height: int | None = None
+    max_area: int | None = None
+
+    def region_request(self, region: Region, max_side: int, fmt: str = "jpg") -> RegionRequest:
+        """Build a region URL whose longer side is at most ``max_side``, honouring server limits.
+
+        Uses pixel regions and explicit ``w,h`` sizes, the forms required from Level 1 upward.
+        """
+        if self.level < 1:
+            raise UnsupportedRequest(
+                "Level 0 services do not support region requests; stitch tiles or use `sizes`"
+            )
+        region = region.clamp(self.width, self.height)
+        limit = max_side
+        if self.max_width is not None:
+            limit = min(limit, self.max_width, self.max_height or self.max_width)
+        if self.max_area is not None:
+            limit = min(limit, math.isqrt(self.max_area))
+        factor = min(1.0, limit / max(region.w, region.h))
+        w = max(1, math.floor(region.w * factor))
+        h = max(1, math.floor(region.h * factor))
+        url = f"{self.id.rstrip('/')}/{region.xywh}/{w},{h}/0/default.{fmt}"
+        return RegionRequest(url=url, region=region, width=w, height=h)
+
+
+def parse_info(info: dict[str, Any]) -> ImageService:
+    """Parse an Image API v2 or v3 info.json document."""
+    context = info.get("@context", "")
+    contexts = context if isinstance(context, list) else [context]
+    version = 3 if any("image/3" in str(c) for c in contexts) else 2
+    service_id = info.get("id") or info.get("@id")
+    if not service_id:
+        raise ValueError("info.json has no id")
+    sizes = [(s["width"], s["height"]) for s in info.get("sizes", [])]
+    return ImageService(
+        id=service_id,
+        width=int(info["width"]),
+        height=int(info["height"]),
+        version=version,
+        level=_parse_level(info.get("profile")),
+        sizes=sizes,
+        max_width=info.get("maxWidth"),
+        max_height=info.get("maxHeight"),
+        max_area=info.get("maxArea"),
+    )
+
+
+def _parse_level(profile: Any) -> int:
+    # v3: "level2"; v2: ["http://iiif.io/api/image/2/level2.json", {...}]
+    candidates = profile if isinstance(profile, list) else [profile]
+    for candidate in candidates:
+        if isinstance(candidate, str) and (match := _LEVEL_RE.search(candidate)):
+            return int(match.group(1))
+    return 0

apud/iiif/manifest.py

@@ -0,0 +1,112 @@
+"""IIIF Presentation API: lenient extraction of canvases from v2 and v3 manifests.
+
+Real-world manifests are often inconsistent (mixed v2/v3 keys, canvas sizes that differ from
+the image), so this module reads only what it needs and does not validate the whole document.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from apud.iiif.image import Region
+
+
+@dataclass(frozen=True)
+class Canvas:
+    id: str
+    width: int
+    height: int
+    label: str | None
+    image_service: str | None
+
+
+@dataclass(frozen=True)
+class Manifest:
+    id: str
+    label: str | None
+    canvases: list[Canvas]
+
+
+def parse_manifest(data: dict[str, Any]) -> Manifest:
+    manifest_id = data.get("id") or data.get("@id")
+    if not manifest_id:
+        raise ValueError("manifest has no id")
+    if "items" in data:
+        raw_canvases = data["items"]
+        to_canvas = _canvas_v3
+    else:
+        sequences = data.get("sequences") or [{}]
+        raw_canvases = sequences[0].get("canvases", [])
+        to_canvas = _canvas_v2
+    return Manifest(
+        id=manifest_id,
+        label=_label(data.get("label")),
+        canvases=[to_canvas(c) for c in raw_canvases],
+    )
+
+
+def image_to_canvas(region: Region, image_width: int, image_height: int, canvas: Canvas) -> Region:
+    """Rescale a region from image pixels to canvas coordinates (they can legitimately differ)."""
+    sx = canvas.width / image_width
+    sy = canvas.height / image_height
+    return Region(
+        round(region.x * sx), round(region.y * sy), round(region.w * sx), round(region.h * sy)
+    )
+
+
+def canvas_to_image(region: Region, image_width: int, image_height: int, canvas: Canvas) -> Region:
+    """Rescale a region from canvas coordinates to image pixels."""
+    sx = image_width / canvas.width
+    sy = image_height / canvas.height
+    return Region(
+        round(region.x * sx), round(region.y * sy), round(region.w * sx), round(region.h * sy)
+    )
+
+
+def _canvas_v3(c: dict[str, Any]) -> Canvas:
+    service = None
+    for page in c.get("items", []):
+        for anno in page.get("items", []):
+            service = _service_id(anno.get("body", {}))
+            if service:
+                break
+        if service:
+            break
+    return Canvas(c["id"], int(c["width"]), int(c["height"]), _label(c.get("label")), service)
+
+
+def _canvas_v2(c: dict[str, Any]) -> Canvas:
+    service = None
+    for image in c.get("images", []):
+        service = _service_id(image.get("resource", {}))
+        if service:
+            break
+    return Canvas(c["@id"], int(c["width"]), int(c["height"]), _label(c.get("label")), service)
+
+
+def _service_id(resource: dict[str, Any] | list[Any]) -> str | None:
+    if isinstance(resource, list):
+        resource = resource[0] if resource else {}
+    services = resource.get("service", [])
+    for service in services if isinstance(services, list) else [services]:
+        if isinstance(service, dict) and (sid := service.get("id") or service.get("@id")):
+            return sid
+    return None
+
+
+def _label(label: Any) -> str | None:
+    # v3 language map {"en": ["..."]}, v2 plain string or list of {"@value": ...}
+    if label is None:
+        return None
+    if isinstance(label, str):
+        return label
+    if isinstance(label, dict):
+        for values in label.values():
+            if values:
+                return str(values[0])
+        return None
+    if isinstance(label, list) and label:
+        first = label[0]
+        return first.get("@value") if isinstance(first, dict) else str(first)
+    return None

apud-0.0.1.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.5
+Name: apud
+Version: 0.0.1
+Summary: IIIF-grounded, citable vision for historical documents: region crops for VLMs, W3C annotations out
+Author: cadeos
+License-Expression: Apache-2.0
+Keywords: digital-humanities,htr,iiif,manuscripts,vlm,web-annotation
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# apud
+
+Core library of [apud](https://github.com/cadeos/apud): IIIF Image/Presentation API parsing,
+model-sized region requests, W3C Web Annotations and IIIF Content State citations.

apud-0.0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+apud/__init__.py,sha256=ofYJOMOEezs1comrzhek5Kui_T8JPUwK2vmmUV35LL8,91
+apud/annotations.py,sha256=UY2Yja5AZJyt4R59_Wb3P4ukw-f8adfVWWTJfuof2mM,2471
+apud/client.py,sha256=4w6LpIaFZlWHMCVAM7ih7dS0N0t7Lo32n6wopqlHR40,1600
+apud/iiif/__init__.py,sha256=JJtv3Pbdq8Fnk4qC4NEsgsvMDL8lXeRMUs1_YxyxjOE,431
+apud/iiif/image.py,sha256=nR2SrQhfzUJuQH8YnbaMyg2QdBSfUOM7LCSSfPgD3vw,4429
+apud/iiif/manifest.py,sha256=YEmUemFpRq37AKRxDMe-LCrtyj9wEsVX7Pn_z68Cszg,3575
+apud-0.0.1.dist-info/METADATA,sha256=zwvS-uSHOt42TCFf8Q2CYGwPZqZDDgWf3_dNwZYlSgY,761
+apud-0.0.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+apud-0.0.1.dist-info/RECORD,,

apud-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any