rasterregions 0.1.0__py3-none-any.whl

rasterregions/__init__.py

@@ -0,0 +1,78 @@
+"""Raster-region detection primitives.
+
+The package deliberately knows nothing about OCR, handwriting, glyph labels, or
+application-specific semantics. It detects foreground pixels and anonymous
+ordered regions only.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .components import components, isolate_component
+from .detect import detect_regions, detect_rows
+from .mask import foreground_mask
+from .models import (
+    BBox,
+    CleanupConfig,
+    Component,
+    ComponentDecision,
+    DetectionConfig,
+    DetectionDiagnostics,
+    DetectionResult,
+    DetectionStatus,
+    ExpectedCountScope,
+    GroupingConfig,
+    IsolationCandidate,
+    IsolationReason,
+    IsolationResult,
+    MaskConfig,
+    MaskMethod,
+    MaskMode,
+    MaskResult,
+    PartitionBoundary,
+    PartitionConfig,
+    Region,
+    RowBand,
+)
+from .regions import crop, tighten_bbox
+
+try:
+    from ._version import __version__
+except ImportError:
+    try:
+        __version__ = version("rasterregions")
+    except PackageNotFoundError:  # source checkout before installation
+        __version__ = "0+unknown"
+
+__all__ = [
+    "BBox",
+    "CleanupConfig",
+    "Component",
+    "ComponentDecision",
+    "DetectionConfig",
+    "DetectionDiagnostics",
+    "DetectionResult",
+    "DetectionStatus",
+    "ExpectedCountScope",
+    "GroupingConfig",
+    "IsolationReason",
+    "MaskConfig",
+    "IsolationCandidate",
+    "IsolationResult",
+    "MaskMethod",
+    "MaskMode",
+    "MaskResult",
+    "PartitionBoundary",
+    "PartitionConfig",
+    "Region",
+    "RowBand",
+    "__version__",
+    "components",
+    "crop",
+    "detect_regions",
+    "detect_rows",
+    "foreground_mask",
+    "isolate_component",
+    "tighten_bbox",
+]

rasterregions/__main__.py

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

rasterregions/_cleanup.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from ._grouping import _size_scale
+from .components import components as label_components
+from .models import CleanupConfig, Component, ComponentDecision
+
+
+@dataclass(frozen=True)
+class CleanedPage:
+    mask: np.ndarray
+    components: tuple[Component, ...]
+    primary_area: float
+    median_height: float
+    warnings: tuple[str, ...]
+    component_decisions: tuple[ComponentDecision, ...]
+
+
+def _is_page_artifact(
+    component: Component,
+    width: int,
+    height: int,
+    config: CleanupConfig | None = None,
+) -> bool:
+    config = config or CleanupConfig()
+    page_area = max(1, width * height)
+    box_area = component.width * component.height
+    box_fraction = box_area / page_area
+    area_fraction = component.area / page_area
+    fill_ratio = component.area / max(1, box_area)
+    touches_border = (
+        component.bbox.x0 == 0
+        or component.bbox.y0 == 0
+        or component.bbox.x1 == width
+        or component.bbox.y1 == height
+    )
+    horizontal_rule = (
+        component.width / max(1, width) >= config.rule_min_span_ratio
+        and component.width / max(1, component.height) >= config.rule_aspect_ratio
+    )
+    vertical_rule = (
+        component.height / max(1, height) >= config.rule_min_span_ratio
+        and component.height / max(1, component.width) >= config.rule_aspect_ratio
+    )
+    if horizontal_rule or vertical_rule:
+        return True
+    if touches_border and (
+        component.width >= width * config.border_span_ratio
+        or component.height >= height * config.border_span_ratio
+    ):
+        return True
+    if (
+        touches_border
+        and box_fraction > config.border_bbox_ratio
+        and fill_ratio < config.border_fill_ratio
+    ):
+        return True
+    return area_fraction > config.max_component_area_ratio
+
+
+def clean_page_mask(mask: np.ndarray, config: CleanupConfig | None = None) -> CleanedPage:
+    config = config or CleanupConfig()
+    height, width = mask.shape
+    found = label_components(mask)
+    if not found:
+        return CleanedPage(
+            mask.copy(),
+            (),
+            0.0,
+            0.0,
+            ("No foreground components were detected.",),
+            (),
+        )
+    artifacts = {
+        component.index: _is_page_artifact(component, width, height, config) for component in found
+    }
+    non_artifacts = [component for component in found if not artifacts[component.index]]
+    primary_area, _ = _size_scale(non_artifacts)
+    cleaned = np.array(mask, dtype=bool, copy=True)
+    warnings: list[str] = []
+    decisions: list[ComponentDecision] = []
+    kept_components: list[Component] = []
+    for component in found:
+        reason = None
+        if artifacts[component.index]:
+            reason = "page border, rule, or oversized artifact"
+        elif primary_area and component.area < primary_area * config.tiny_area_ratio:
+            reason = "tiny isolated noise"
+        if reason:
+            cleaned[component.ys, component.xs] = False
+            warnings.append(f"Removed component {component.index}: {reason}.")
+        else:
+            kept_components.append(component)
+        decisions.append(
+            ComponentDecision(
+                component.index,
+                component.bbox,
+                component.area,
+                "removed" if reason else "kept",
+                reason,
+            )
+        )
+    kept = tuple(kept_components)
+    primary_area, median_height = _size_scale(kept)
+    return CleanedPage(
+        cleaned,
+        kept,
+        primary_area,
+        median_height,
+        tuple(warnings),
+        tuple(decisions),
+    )

rasterregions/_grouping.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import numpy as np
+from PIL import Image
+
+from .models import BBox, Component, GroupingConfig, Region, RowBand
+from .regions import crop, tighten_bbox
+
+
+def _size_scale(found: tuple[Component, ...] | list[Component]) -> tuple[float, float]:
+    if not found:
+        return 0.0, 0.0
+    areas = np.asarray([component.area for component in found], dtype=float)
+    upper_half = np.sort(areas)[len(areas) // 2 :]
+    primary_area = float(np.median(upper_half))
+    body = [component for component in found if component.area >= primary_area * 0.2]
+    median_height = float(np.median([component.height for component in body])) if body else 0.0
+    return primary_area, median_height
+
+
+def _body_components(
+    found: tuple[Component, ...] | list[Component],
+    primary_area: float,
+    median_height: float,
+    config: GroupingConfig | None = None,
+) -> list[Component]:
+    if not found:
+        return []
+    config = config or GroupingConfig()
+    minimum_area = primary_area * config.body_min_area_ratio
+    minimum_height = median_height * config.body_min_height_ratio
+    bodies = [
+        component
+        for component in found
+        if component.area >= minimum_area
+        and (component.height >= minimum_height or component.width >= minimum_height)
+    ]
+    return bodies or [max(found, key=lambda component: component.area)]
+
+
+def _group_nearby_bodies(
+    bodies: list[Component], median_height: float, config: GroupingConfig
+) -> list[list[Component]]:
+    groups: list[list[Component]] = []
+    for component in sorted(bodies, key=lambda item: item.bbox.x0):
+        if not groups:
+            groups.append([component])
+            continue
+        previous = groups[-1]
+        previous_right = max(member.bbox.x1 for member in previous)
+        previous_top = min(member.bbox.y0 for member in previous)
+        previous_bottom = max(member.bbox.y1 for member in previous)
+        gap = component.bbox.x0 - previous_right
+        overlap = min(previous_bottom, component.bbox.y1) - max(previous_top, component.bbox.y0)
+        if gap <= max(1.0, median_height * config.body_join_gap_ratio) and overlap > 0:
+            previous.append(component)
+        else:
+            groups.append([component])
+    return groups
+
+
+def _satellite_score(
+    satellite: Component,
+    body: Component,
+    median_height: float,
+    config: GroupingConfig,
+) -> float | None:
+    if satellite.area >= body.area * config.satellite_max_area_ratio:
+        return None
+    horizontal_gap = max(
+        body.bbox.x0 - satellite.bbox.x1,
+        satellite.bbox.x0 - body.bbox.x1,
+        0,
+    )
+    vertical_gap = max(
+        body.bbox.y0 - satellite.bbox.y1,
+        satellite.bbox.y0 - body.bbox.y1,
+        0,
+    )
+    if (
+        horizontal_gap > median_height * config.satellite_max_horizontal_gap_ratio
+        or vertical_gap > median_height * config.satellite_max_vertical_gap_ratio
+    ):
+        return None
+    overlaps_x = max(
+        0,
+        min(body.bbox.x1, satellite.bbox.x1) - max(body.bbox.x0, satellite.bbox.x0),
+    )
+    return (
+        horizontal_gap / max(1.0, median_height)
+        + vertical_gap / max(1.0, median_height)
+        - 0.35 * overlaps_x / max(1.0, median_height)
+    )
+
+
+def _make_region(
+    image: Image.Image,
+    mask: np.ndarray,
+    bbox: BBox,
+    *,
+    region_id: str,
+    row_index: int,
+    column_index: int,
+    reading_order: int,
+    confidence: float,
+    component_indices: tuple[int, ...],
+    padding: int,
+    clip: BBox | None = None,
+) -> Region:
+    height, width = mask.shape
+    clip = clip or BBox(0, 0, width, height)
+    expanded = BBox(
+        max(clip.x0, bbox.x0 - padding),
+        max(clip.y0, bbox.y0 - padding),
+        min(clip.x1, bbox.x1 + padding),
+        min(clip.y1, bbox.y1 + padding),
+    )
+    tight = tighten_bbox(mask, expanded, pad=padding)
+    return Region(
+        region_id=region_id,
+        bbox=tight,
+        row_index=row_index,
+        column_index=column_index,
+        reading_order=reading_order,
+        confidence=float(np.clip(confidence, 0.0, 1.0)),
+        component_indices=component_indices,
+        image=crop(image, tight),
+        mask=mask[tight.y0 : tight.y1, tight.x0 : tight.x1],
+    )
+
+
+def _automatic_regions(
+    image: Image.Image,
+    mask: np.ndarray,
+    found: tuple[Component, ...],
+    primary_area: float,
+    median_height: float,
+    rows: tuple[RowBand, ...],
+    padding: int,
+    grouping: GroupingConfig,
+) -> list[Region]:
+    bodies = _body_components(found, primary_area, median_height, grouping)
+    body_indices = {component.index for component in bodies}
+    groups_by_row = [
+        _group_nearby_bodies(
+            [component for component in bodies if component.index in row.component_indices],
+            median_height,
+            grouping,
+        )
+        for row in rows
+    ]
+    attached_by_row: list[list[list[Component]]] = [
+        [[] for _ in groups] for groups in groups_by_row
+    ]
+    satellites = [component for component in found if component.index not in body_indices]
+    for satellite in satellites:
+        options: list[tuple[float, int, int]] = []
+        for row_index, groups in enumerate(groups_by_row):
+            for group_index, group in enumerate(groups):
+                scores = [
+                    score
+                    for body in group
+                    if (score := _satellite_score(satellite, body, median_height, grouping))
+                    is not None
+                ]
+                if scores:
+                    options.append((min(scores), row_index, group_index))
+        if options:
+            _, row_index, group_index = min(options)
+            attached_by_row[row_index][group_index].append(satellite)
+
+    regions: list[Region] = []
+    reading_order = 0
+    for row_index, groups in enumerate(groups_by_row):
+        for column_index, group in enumerate(groups):
+            marks = attached_by_row[row_index][column_index]
+            members = [*group, *marks]
+            box = BBox(
+                min(component.bbox.x0 for component in members),
+                min(component.bbox.y0 for component in members),
+                max(component.bbox.x1 for component in members),
+                max(component.bbox.y1 for component in members),
+            )
+            next_group = groups[column_index + 1] if column_index + 1 < len(groups) else None
+            previous_group = groups[column_index - 1] if column_index else None
+            left_gap = (
+                group[0].bbox.x0 - max(component.bbox.x1 for component in previous_group)
+                if previous_group
+                else median_height
+            )
+            right_gap = (
+                min(component.bbox.x0 for component in next_group)
+                - max(component.bbox.x1 for component in group)
+                if next_group
+                else median_height
+            )
+            separation = float(
+                np.clip(min(left_gap, right_gap) / max(1.0, median_height * 0.5), 0.0, 1.0)
+            )
+            body_areas = np.asarray([component.area for component in group], dtype=float)
+            median_area = float(np.median(body_areas))
+            size_consistency = float(
+                np.clip(
+                    1.0 - np.median(np.abs(body_areas - median_area)) / max(1.0, median_area),
+                    0.0,
+                    1.0,
+                )
+            )
+            confidence = 0.65 * separation + 0.35 * size_consistency
+            regions.append(
+                _make_region(
+                    image,
+                    mask,
+                    box,
+                    region_id=f"region-{reading_order:03d}",
+                    row_index=row_index,
+                    column_index=column_index,
+                    reading_order=reading_order,
+                    confidence=confidence,
+                    component_indices=tuple(sorted(component.index for component in members)),
+                    padding=padding,
+                )
+            )
+            reading_order += 1
+    return regions

rasterregions/_image.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+from PIL import Image, ImageOps
+
+
+@dataclass(frozen=True)
+class NormalizedImage:
+    image: Image.Image = field(repr=False, compare=False)
+    rgb: np.ndarray = field(repr=False, compare=False)
+    source_path: Path | None = None
+
+
+def _normalized_pixels(
+    pixels: np.ndarray,
+    *,
+    alpha_background: tuple[int, int, int],
+    source_path: Path | None,
+) -> NormalizedImage:
+    array = np.asarray(pixels)
+    if array.ndim not in (2, 3) or array.shape[0] == 0 or array.shape[1] == 0:
+        raise ValueError("image must be non-empty and have grayscale, RGB, or RGBA dimensions")
+    if array.ndim == 3 and array.shape[2] not in (3, 4):
+        raise ValueError("image must be grayscale, RGB, or RGBA")
+    if array.dtype.kind not in "uif":
+        raise ValueError("image pixels must be numeric")
+
+    values = np.asarray(array, dtype=np.float32)
+    if not np.isfinite(values).all():
+        raise ValueError("image pixels must be finite")
+    if np.issubdtype(array.dtype, np.floating) and values.max(initial=0.0) <= 1.0:
+        values = values * 255.0
+    values = np.clip(values, 0.0, 255.0)
+
+    if values.ndim == 2:
+        rgb = np.repeat(values[:, :, None], 3, axis=2)
+    elif values.shape[2] == 4:
+        alpha = values[:, :, 3:4] / 255.0
+        background = np.asarray(alpha_background, dtype=np.float32).reshape(1, 1, 3)
+        rgb = values[:, :, :3] * alpha + background * (1.0 - alpha)
+    else:
+        rgb = values
+
+    rgb = np.array(np.clip(rgb, 0.0, 255.0), dtype=np.float32, copy=True)
+    rgb.setflags(write=False)
+    image = Image.fromarray(np.rint(rgb).astype(np.uint8))
+    return NormalizedImage(image=image, rgb=rgb, source_path=source_path)
+
+
+def _normalize_pil(
+    image: Image.Image,
+    *,
+    alpha_background: tuple[int, int, int],
+    source_path: Path | None,
+) -> NormalizedImage:
+    oriented = ImageOps.exif_transpose(image)
+    rgba = np.asarray(oriented.convert("RGBA"), dtype=np.uint8)
+    return _normalized_pixels(
+        rgba,
+        alpha_background=alpha_background,
+        source_path=source_path,
+    )
+
+
+def normalize_image(
+    source: str | Path | Image.Image | np.ndarray,
+    *,
+    alpha_background: tuple[int, int, int] = (255, 255, 255),
+) -> NormalizedImage:
+    """Normalize a raster source to orientation-corrected RGB pixels."""
+    if isinstance(source, (str, Path)):
+        path = Path(source)
+        with Image.open(path) as image:
+            return _normalize_pil(
+                image,
+                alpha_background=alpha_background,
+                source_path=path,
+            )
+    if isinstance(source, Image.Image):
+        return _normalize_pil(
+            source,
+            alpha_background=alpha_background,
+            source_path=None,
+        )
+    return _normalized_pixels(
+        np.asarray(source),
+        alpha_background=alpha_background,
+        source_path=None,
+    )