mullion 0.1.0__py3-none-any.whl

mullion/__init__.py

@@ -0,0 +1,111 @@
+"""Mullion — get an image in correctly, once.
+
+A mullion is the upright that divides a window into panes: one stone member,
+every pane set against it. The name is the point of the library. Every
+application that accepts user images opens them somewhere, and if it opens them
+in six places it gets six different answers — which is not a hypothesis.
+Measured across one real codebase, the same transparent PNG came back on a
+**black** rectangle through three upload paths and correctly through four
+others, because each had reached for ``Image.open(...).convert("RGB")``
+independently.
+
+Nothing about that failure is loud. The response is a 200, the picture renders,
+the layout is right. It is only *wrong*, in a way a status-code test cannot see
+and a reviewer looking at one image at a time will not catch.
+
+So this library is deliberately small, and does the three things that keep
+coming back:
+
+:mod:`mullion.source`
+    One correct open — EXIF orientation applied, transparency resolved rather
+    than dropped — with adapters for the two things callers actually hold:
+    ``bytes`` from object storage and a filesystem path.
+
+:mod:`mullion.background`
+    Border-seeded background cleaning, so a near-white product shot sits flush
+    on a white surface without a global threshold eating the subject's own
+    highlights.
+
+:mod:`mullion.page`
+    Page geometry and DPI, so "A4 at 300" resolves to pixels that agree with
+    the resolution written into the file.
+
+Importing this package costs nothing: Pillow is imported inside the functions
+that need it, so a service that only reaches for :mod:`mullion.page`, or that
+imports at module scope and opens images rarely, does not pay for it at start-up.
+
+Quick start::
+
+    from mullion import open_bytes, open_path, clean_background, keeps_alpha
+
+    image = open_bytes(upload.read())              # RGB, upright, no black box
+    avatar = open_path(p, keep_alpha=True)         # RGBA preserved
+
+    mode = "flatten"
+    shot = open_path(p, keep_alpha=keeps_alpha(mode))
+    cleaned, result = clean_background(shot, mode=mode)
+    print(result.message)
+"""
+
+from __future__ import annotations
+
+from .background import (
+    DEFAULT_BORDER_COVERAGE,
+    DEFAULT_BORDER_TOLERANCE,
+    DEFAULT_TOLERANCE,
+    BackgroundCleanMode,
+    CleanResult,
+    clean_background,
+    keeps_alpha,
+    looks_like_white_background,
+)
+from .page import (
+    DEFAULT_DPI,
+    MM_PER_INCH,
+    NAMED_PAGE_SIZES_MM,
+    PageGeometry,
+    PageUnit,
+    named_page_geometry,
+    resolve_page_geometry,
+    to_pixels,
+    validate_dpi,
+)
+from .source import (
+    WHITE,
+    Matte,
+    flatten_onto,
+    has_transparency,
+    normalize,
+    open_bytes,
+    open_path,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_BORDER_COVERAGE",
+    "DEFAULT_BORDER_TOLERANCE",
+    "DEFAULT_DPI",
+    "DEFAULT_TOLERANCE",
+    "MM_PER_INCH",
+    "NAMED_PAGE_SIZES_MM",
+    "WHITE",
+    "BackgroundCleanMode",
+    "CleanResult",
+    "Matte",
+    "PageGeometry",
+    "PageUnit",
+    "__version__",
+    "clean_background",
+    "flatten_onto",
+    "has_transparency",
+    "keeps_alpha",
+    "looks_like_white_background",
+    "named_page_geometry",
+    "normalize",
+    "open_bytes",
+    "open_path",
+    "resolve_page_geometry",
+    "to_pixels",
+    "validate_dpi",
+]

mullion/background.py

@@ -0,0 +1,304 @@
+"""Clean a near-white background so a subject sits flush on a white surface.
+
+The problem is visible on any page or card built from photographed or
+JPEG-compressed source images: a "white" background is rarely ``#FFFFFF``. It
+is ``#FBFBFA`` from a scanner, ``#F7F8F9`` from a phone's auto white balance,
+or a ring of ``#FDFDFD`` compression noise around a cutout. Every one of those
+reads as a faint rectangle around the image — a grid looks gridded, a card
+looks pasted on, exactly where the design wanted neither.
+
+Two rules make this reliable rather than destructive.
+
+**Only clean what touches the border.** A global "every pixel brighter than
+``threshold`` becomes white" pass is the obvious implementation and it eats the
+subject: the highlight on a white mug, the page of an open book, a bride's
+dress, the sky behind a building. This module flood-fills *inward from the
+edges* instead, so a pixel is only cleaned when there is a continuous
+near-white path from it to the frame. Interior highlights are unreachable and
+are therefore never touched.
+
+**Decide per image whether there is a background at all.** An image whose
+border is not near-white — a full-bleed photograph, a dark render — is returned
+untouched rather than partially eaten. ``border_tolerance`` draws that line,
+and :func:`looks_like_white_background` answers it on its own so a caller can
+*report* the decision instead of silently doing nothing.
+
+Output modes differ only in what the cleaned region becomes:
+
+``flatten``      the region becomes the matte colour — what a white page wants.
+``transparent``  the region becomes alpha 0, for a caller compositing onto a
+                 non-white surface, or writing a cutout PNG.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING, Any, Protocol, cast
+
+from .source import WHITE, Matte
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from PIL.Image import Image as PILImage
+
+__all__ = [
+    "DEFAULT_BORDER_COVERAGE",
+    "DEFAULT_BORDER_TOLERANCE",
+    "DEFAULT_TOLERANCE",
+    "BackgroundCleanMode",
+    "CleanResult",
+    "clean_background",
+    "keeps_alpha",
+    "looks_like_white_background",
+]
+
+# A pixel is "near white" when every channel is at or above this value. 240 is
+# deliberately conservative: it clears JPEG noise and scanner grey while
+# leaving genuinely light-grey subject matter (a #E8E8E8 product shadow) alone.
+DEFAULT_TOLERANCE = 240
+
+# How near-white the frame itself must be, on average, before this image is
+# treated as having a white background at all.
+DEFAULT_BORDER_TOLERANCE = 232
+
+# Fraction of the border that must read as near-white. One dark object running
+# off the edge of an otherwise white product shot should not disqualify it.
+DEFAULT_BORDER_COVERAGE = 0.55
+
+
+class BackgroundCleanMode(StrEnum):
+    """What the detected background region becomes."""
+
+    OFF = "off"
+    FLATTEN = "flatten"
+    TRANSPARENT = "transparent"
+
+
+def keeps_alpha(mode: BackgroundCleanMode | str) -> bool:
+    """Whether ``mode`` needs the source image's own alpha channel preserved.
+
+    Exists so a caller picking an open mode does not have to restate the rule::
+
+        image = open_path(p, keep_alpha=keeps_alpha(mode))
+        cleaned, result = clean_background(image, mode=mode)
+
+    Getting it wrong is quiet rather than loud: an already-transparent PNG
+    opened without ``keep_alpha`` is flattened onto white *before* it is
+    cleaned, so its anti-aliased edges keep the white they were blended with
+    and the cutout comes back with a pale fringe.
+    """
+    return BackgroundCleanMode(str(mode)) is BackgroundCleanMode.TRANSPARENT
+
+
+@dataclass(frozen=True, slots=True)
+class CleanResult:
+    """What a clean pass did, so callers can report rather than guess."""
+
+    cleaned: bool
+    reason: str
+    background_ratio: float
+
+    @property
+    def message(self) -> str:
+        """A sentence fit to show a user, either way."""
+        if self.cleaned:
+            return f"Cleaned background ({self.background_ratio:.0%} of the image)."
+        return self.reason
+
+
+# ``Image.load()`` is typed ``PixelAccess | None``, and what a subscript on it
+# yields depends on the image's mode — a triple for ``RGB``, a single level for
+# ``L``. This module reads both, so one return type cannot be honest about
+# either. The two protocols below say which is expected, and the loaders below
+# them establish it: they assert the mode rather than assuming it, so a future
+# caller handing one of these functions the wrong image fails at the assert
+# instead of reading a shape nothing checks. That is the whole reason these are
+# not ``# type: ignore`` comments — an ignore would silence the checker without
+# recording what it was silenced *for*.
+
+
+class _RgbPixels(Protocol):
+    """Pixel access for an ``RGB`` image."""
+
+    def __getitem__(self, position: tuple[int, int]) -> tuple[int, int, int]: ...
+
+
+class _GreyPixels(Protocol):
+    """Pixel access for an ``L`` image."""
+
+    def __getitem__(self, position: tuple[int, int]) -> int: ...
+
+
+def _rgb_pixels(image: PILImage) -> _RgbPixels:
+    """Pixel access for ``image``, which must already be ``RGB``."""
+    if image.mode != "RGB":
+        raise ValueError(f"expected an RGB image, got mode {image.mode!r}")
+    access = image.load()
+    if access is None:  # pragma: no cover - Pillow only answers None for an unreadable image
+        raise ValueError("image has no pixel access")
+    return cast("_RgbPixels", access)
+
+
+def _grey_pixels(image: PILImage) -> _GreyPixels:
+    """Pixel access for ``image``, which must already be ``L``."""
+    if image.mode != "L":
+        raise ValueError(f"expected an L image, got mode {image.mode!r}")
+    access = image.load()
+    if access is None:  # pragma: no cover - Pillow only answers None for an unreadable image
+        raise ValueError("image has no pixel access")
+    return cast("_GreyPixels", access)
+
+
+def _border_pixels(image: PILImage) -> list[tuple[int, int, int]]:
+    """The one-pixel frame around ``image``, as RGB triples.
+
+    ``image`` must already be ``RGB`` — that is what makes the return type
+    true, and ``_rgb_pixels`` enforces it rather than trusting the caller.
+    """
+    width, height = image.size
+    if width == 0 or height == 0:
+        return []
+
+    pixels = _rgb_pixels(image)
+    frame: list[tuple[int, int, int]] = []
+    for x in range(width):
+        frame.append(pixels[x, 0])
+        if height > 1:
+            frame.append(pixels[x, height - 1])
+    for y in range(1, max(1, height - 1)):
+        frame.append(pixels[0, y])
+        if width > 1:
+            frame.append(pixels[width - 1, y])
+    return frame
+
+
+def looks_like_white_background(
+    image: PILImage | Any,
+    *,
+    border_tolerance: int = DEFAULT_BORDER_TOLERANCE,
+    border_coverage: float = DEFAULT_BORDER_COVERAGE,
+) -> bool:
+    """Whether enough of ``image``'s frame is near-white to call it a background.
+
+    Asked *before* any pixel is modified. An image that fails it is returned
+    untouched — a full-bleed photograph has no background to clean, and
+    flood-filling from its corners would eat whatever happens to be light
+    there.
+    """
+    frame = _border_pixels(image.convert("RGB"))
+    if not frame:
+        return False
+
+    near_white = sum(1 for pixel in frame if min(pixel) >= border_tolerance)
+    return (near_white / len(frame)) >= border_coverage
+
+
+def _background_mask(image: PILImage, *, tolerance: int) -> tuple[PILImage, float]:
+    """A mask of the edge-connected near-white region, and its area ratio.
+
+    White in the mask means background. Built by flood-filling a scratch canvas
+    inward from every border pixel that is already near-white, so interior
+    highlights of the same colour are unreachable and survive.
+    """
+    from PIL import ImageDraw
+
+    width, height = image.size
+    greyscale = image.convert("L")
+
+    # Everything near-white starts as a fill candidate (255); everything else
+    # is a wall (0). The flood then decides which candidates are edge-connected.
+    candidates = greyscale.point(lambda level: 255 if level >= tolerance else 0)
+
+    # Pillow's floodfill spreads across equal-ish values, so seeding a third
+    # value (128) marks exactly the reached region and leaves unreachable
+    # candidates at 255 to be discarded below.
+    working = candidates.copy()
+    working_pixels = _grey_pixels(working)
+
+    seeds: list[tuple[int, int]] = []
+    for x in range(width):
+        seeds.append((x, 0))
+        if height > 1:
+            seeds.append((x, height - 1))
+    for y in range(height):
+        seeds.append((0, y))
+        if width > 1:
+            seeds.append((width - 1, y))
+
+    for seed in seeds:
+        # Read through the access object rather than getpixel: floodfill
+        # mutates ``working`` in place and the access object sees it, so this
+        # also skips seeds an earlier flood has already swallowed.
+        if working_pixels[seed] == 255:
+            ImageDraw.floodfill(working, seed, 128, thresh=0)
+
+    mask = working.point(lambda level: 255 if level == 128 else 0)
+
+    histogram = mask.histogram()
+    background_pixels = histogram[255] if len(histogram) > 255 else 0
+    total = width * height
+    return mask, (background_pixels / total if total else 0.0)
+
+
+def clean_background(
+    image: PILImage | Any,
+    *,
+    mode: BackgroundCleanMode | str = BackgroundCleanMode.FLATTEN,
+    tolerance: int = DEFAULT_TOLERANCE,
+    border_tolerance: int = DEFAULT_BORDER_TOLERANCE,
+    border_coverage: float = DEFAULT_BORDER_COVERAGE,
+    feather: int = 1,
+    matte: Matte = WHITE,
+) -> tuple[PILImage, CleanResult]:
+    """Return ``image`` with its edge-connected near-white background cleaned.
+
+    ``feather`` softens the mask by that many pixels before it is applied,
+    which is what removes the grey halo left by anti-aliased cutout edges. Pass
+    ``0`` for a hard edge.
+
+    The image is never mutated; when nothing is cleaned it is returned as-is,
+    which is what lets a caller pass every image through unconditionally.
+    """
+    from PIL import Image, ImageChops, ImageFilter
+
+    normalized_mode = BackgroundCleanMode(str(mode))
+    if normalized_mode is BackgroundCleanMode.OFF:
+        return image, CleanResult(False, "Background cleaning is off.", 0.0)
+
+    if not 0 <= tolerance <= 255:
+        raise ValueError("tolerance must be between 0 and 255.")
+    if feather < 0:
+        raise ValueError("feather must be zero or greater.")
+
+    rgb = image.convert("RGB")
+    if not looks_like_white_background(
+        rgb,
+        border_tolerance=border_tolerance,
+        border_coverage=border_coverage,
+    ):
+        return image, CleanResult(
+            False,
+            "No white background detected; image left unchanged.",
+            0.0,
+        )
+
+    mask, background_ratio = _background_mask(rgb, tolerance=tolerance)
+    if background_ratio <= 0:
+        return image, CleanResult(
+            False,
+            "No background pixels matched the tolerance.",
+            0.0,
+        )
+
+    if feather:
+        mask = mask.filter(ImageFilter.GaussianBlur(radius=feather))
+
+    if normalized_mode is BackgroundCleanMode.TRANSPARENT:
+        cleaned = image.convert("RGBA")
+        # Subtract the background mask from whatever alpha the image already
+        # carries, so an already-cut-out PNG is not given its corners back.
+        cleaned.putalpha(ImageChops.subtract(cleaned.getchannel("A"), mask))
+    else:
+        cleaned = Image.composite(Image.new("RGB", rgb.size, matte), rgb, mask)
+
+    return cleaned, CleanResult(True, "Background cleaned.", background_ratio)

mullion/page.py

@@ -0,0 +1,146 @@
+"""Page size in physical units, and the DPI that makes it mean something.
+
+A page is usually specified in **pixels**. That is a complete description for a
+screen and an incomplete one for print: 3000 px is 10 inches at 300 DPI and
+41.7 inches at 72 DPI, and nothing in the file says which unless something
+writes the resolution into it.
+
+This module is the other half of that. It lets a caller say what they actually
+mean — "A4 at 300 DPI", "8x10in at 300" — and get back the pixel dimensions
+*together with* the DPI they were derived at, so the two numbers cannot
+disagree. Pass :attr:`PageGeometry.dpi` to your encoder (Pillow takes
+``dpi=(x, y)`` on both PNG and JPEG saves) and the file then says what it is.
+
+Nothing here imports Pillow, or anything else. It is arithmetic with the
+constants written down.
+
+.. note::
+   A PNG stores resolution in its ``pHYs`` chunk as pixels *per metre*, as an
+   integer. 300 DPI is 11811.02... px/m, so it is stored as 11811 and reads
+   back as 299.9994 rather than 300. That is the format, not a defect; compare
+   with a tolerance rather than for equality.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+__all__ = [
+    "DEFAULT_DPI",
+    "MM_PER_INCH",
+    "NAMED_PAGE_SIZES_MM",
+    "PageGeometry",
+    "PageUnit",
+    "named_page_geometry",
+    "resolve_page_geometry",
+    "to_pixels",
+    "validate_dpi",
+]
+
+# 300 DPI is the ordinary floor for photographic print. It is the default here
+# because the page presets are print-shaped (3000x4000 = 10x13.3in at 300).
+DEFAULT_DPI = 300
+
+MM_PER_INCH = 25.4
+
+PageUnit = Literal["px", "in", "mm"]
+
+# Common page sizes in millimetres, for callers that would rather name one.
+NAMED_PAGE_SIZES_MM: dict[str, tuple[float, float]] = {
+    "a4": (210.0, 297.0),
+    "a3": (297.0, 420.0),
+    "a5": (148.0, 210.0),
+    "letter": (215.9, 279.4),
+    "legal": (215.9, 355.6),
+    "tabloid": (279.4, 431.8),
+}
+
+
+@dataclass(frozen=True, slots=True)
+class PageGeometry:
+    """A page's pixel dimensions together with the DPI they were derived at."""
+
+    width_px: int
+    height_px: int
+    dpi: int
+
+    @property
+    def width_inches(self) -> float:
+        return self.width_px / self.dpi
+
+    @property
+    def height_inches(self) -> float:
+        return self.height_px / self.dpi
+
+    @property
+    def description(self) -> str:
+        return (
+            f"{self.width_px}x{self.height_px}px "
+            f"({self.width_inches:.2f}x{self.height_inches:.2f}in at {self.dpi} DPI)"
+        )
+
+
+def to_pixels(value: float, unit: PageUnit, dpi: int) -> int:
+    """Convert ``value`` in ``unit`` to whole pixels at ``dpi``."""
+    if value <= 0:
+        raise ValueError("Page dimensions must be greater than zero.")
+    if unit == "px":
+        pixels = value
+    elif unit == "in":
+        pixels = value * dpi
+    elif unit == "mm":
+        pixels = (value / MM_PER_INCH) * dpi
+    else:
+        raise ValueError(f"Unsupported unit '{unit}'. Use 'px', 'in' or 'mm'.")
+
+    rounded = int(round(pixels))
+    if rounded <= 0:
+        raise ValueError("Page dimensions rounded to zero pixels; increase the size or DPI.")
+    return rounded
+
+
+def resolve_page_geometry(
+    *,
+    page_width: float,
+    page_height: float,
+    unit: PageUnit = "px",
+    dpi: int = DEFAULT_DPI,
+) -> PageGeometry:
+    """Resolve a requested page size to pixels at ``dpi``.
+
+    With ``unit="px"`` the dimensions pass through unchanged and ``dpi`` only
+    decides what gets written into the exported file's metadata — which is the
+    backward-compatible path every existing caller takes.
+    """
+    validate_dpi(dpi)
+    return PageGeometry(
+        width_px=to_pixels(page_width, unit, dpi),
+        height_px=to_pixels(page_height, unit, dpi),
+        dpi=dpi,
+    )
+
+
+def named_page_geometry(name: str, *, dpi: int = DEFAULT_DPI) -> PageGeometry:
+    """Resolve a named page size (``a4``, ``letter``, ...) at ``dpi``."""
+    key = name.strip().lower()
+    if key not in NAMED_PAGE_SIZES_MM:
+        supported = ", ".join(sorted(NAMED_PAGE_SIZES_MM))
+        raise ValueError(f"Unknown page size '{name}'. Supported: {supported}.")
+
+    width_mm, height_mm = NAMED_PAGE_SIZES_MM[key]
+    return resolve_page_geometry(
+        page_width=width_mm,
+        page_height=height_mm,
+        unit="mm",
+        dpi=dpi,
+    )
+
+
+def validate_dpi(dpi: int) -> int:
+    """Reject a DPI that would make the export meaningless."""
+    if dpi <= 0:
+        raise ValueError("DPI must be greater than zero.")
+    if dpi > 1200:
+        raise ValueError("DPI above 1200 is not supported.")
+    return int(dpi)

mullion/source.py

@@ -0,0 +1,162 @@
+"""One correct way to open an image, whatever you are holding.
+
+Every consumer of a user-supplied image opens it, and the obvious spelling —
+``Image.open(...).convert("RGB")`` — is wrong in two ways that both render as a
+*plausible* picture rather than an error. That is why neither is noticed by a
+status-code test, a screenshot review, or a human looking at one image at a
+time.
+
+**Transparency composites against black.** ``convert("RGB")`` on an ``RGBA``
+image drops the alpha channel and keeps whatever RGB sits underneath it. In a
+PNG written by almost every tool, fully transparent pixels carry ``(0, 0, 0)``
+— so a cutout PNG lands on a white page inside a black rectangle. The same is
+true of ``LA`` (greyscale + alpha), and of palette ``P`` images carrying a
+``transparency`` entry, which is what most "small" PNGs are saved as. That last
+one is the one that is easy to miss: the alpha is not in the mode string, it is
+a key in ``info``.
+
+**EXIF orientation is ignored.** A photo shot in portrait on a phone is stored
+landscape with an orientation tag telling the viewer to rotate it. Pillow does
+not apply that tag on open, so the image is placed rotated — and because most
+placement is aspect-preserving, a wrongly-rotated image is merely *small and
+sideways* rather than obviously broken.
+
+:func:`normalize` fixes both, once. The two adapters exist because callers hold
+different things: a web service holds ``bytes`` it just read from object
+storage, and a desktop or batch tool holds a filesystem path. Neither should
+have to reach for ``PIL`` to get an image in correctly.
+"""
+
+from __future__ import annotations
+
+import os
+from io import BytesIO
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from PIL.Image import Image as PILImage
+
+__all__ = [
+    "WHITE",
+    "Matte",
+    "flatten_onto",
+    "has_transparency",
+    "normalize",
+    "open_bytes",
+    "open_path",
+]
+
+# Modes that carry per-pixel transparency. ``P`` is deliberately absent: it
+# carries transparency out of band, in ``info["transparency"]``, and is handled
+# separately in :func:`has_transparency`.
+_ALPHA_MODES = frozenset({"RGBA", "LA", "PA"})
+
+#: An RGB triple to composite transparency onto.
+Matte = tuple[int, int, int]
+
+#: The default matte. White, because the surfaces that flatten are pages and
+#: cards, which are white.
+WHITE: Matte = (255, 255, 255)
+
+
+def has_transparency(image: PILImage | Any) -> bool:
+    """Whether ``image`` carries transparency in any of its three shapes.
+
+    Reads attributes rather than importing Pillow, so this stays usable against
+    a stand-in in a test that does not want the dependency.
+    """
+    mode = getattr(image, "mode", "")
+    if mode in _ALPHA_MODES:
+        return True
+    return mode == "P" and "transparency" in getattr(image, "info", {})
+
+
+def flatten_onto(image: PILImage | Any, matte: Matte = WHITE) -> PILImage:
+    """Composite ``image`` onto a solid ``matte``, returning ``RGB``.
+
+    An image with no transparency is simply converted, so this is safe to call
+    unconditionally.
+    """
+    from PIL import Image
+
+    if not has_transparency(image):
+        return image.convert("RGB")
+
+    # Normalize every transparent shape to RGBA first. Converting a P-mode
+    # image straight to RGB would discard info["transparency"] silently; going
+    # via RGBA is what promotes it to a real alpha channel.
+    rgba = image.convert("RGBA")
+    background = Image.new("RGBA", rgba.size, (*matte, 255))
+    return Image.alpha_composite(background, rgba).convert("RGB")
+
+
+def normalize(
+    image: PILImage | Any,
+    *,
+    keep_alpha: bool = False,
+    matte: Matte = WHITE,
+) -> PILImage:
+    """Return ``image`` upright, with its transparency resolved.
+
+    ``keep_alpha=False`` composites transparency onto ``matte`` and returns
+    ``RGB`` — what an opaque destination wants, since it has no use for an
+    alpha channel and dropping one carelessly is the black-rectangle defect
+    this module exists for. ``keep_alpha=True`` returns ``RGBA`` instead, for a
+    caller that will composite itself or write a cutout.
+
+    Always returns a new image; the input is never mutated.
+    """
+    from PIL import ImageOps
+
+    # exif_transpose returns a new image with the tag applied and removed, and
+    # is a no-op for a file with no orientation tag. Older Pillow returns None
+    # rather than a copy in that case, hence the fallback.
+    upright = ImageOps.exif_transpose(image) or image
+
+    if not has_transparency(upright):
+        # Convert unconditionally rather than returning ``upright`` as-is: the
+        # adapters below open inside a ``with`` block, so a lazily-loaded image
+        # would be read from a file that has since closed. ``convert`` forces
+        # the load, which is what makes the return value safe to outlive it.
+        return upright.convert("RGBA") if keep_alpha else upright.convert("RGB")
+
+    if keep_alpha:
+        return upright.convert("RGBA")
+    return flatten_onto(upright, matte)
+
+
+def open_bytes(
+    data: bytes | bytearray | memoryview,
+    *,
+    keep_alpha: bool = False,
+    matte: Matte = WHITE,
+) -> PILImage:
+    """Open image ``data`` held in memory, normalized.
+
+    The adapter a web service wants: an upload or an object-storage read hands
+    you bytes, and there is no file to point Pillow at.
+
+    Raises whatever ``Image.open`` raises for data that is not an image —
+    callers that treat an unreadable upload as a refusal already handle it.
+    """
+    from PIL import Image
+
+    with Image.open(BytesIO(bytes(data))) as source:
+        return normalize(source, keep_alpha=keep_alpha, matte=matte)
+
+
+def open_path(
+    path: str | os.PathLike[str],
+    *,
+    keep_alpha: bool = False,
+    matte: Matte = WHITE,
+) -> PILImage:
+    """Open the image at ``path``, normalized.
+
+    The adapter a batch or desktop tool wants. The file handle is closed before
+    this returns; see :func:`normalize` for why that is safe.
+    """
+    from PIL import Image
+
+    with Image.open(path) as source:
+        return normalize(source, keep_alpha=keep_alpha, matte=matte)

mullion-0.1.0.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.5
+Name: mullion
+Version: 0.1.0
+Summary: One correct way to open an image: EXIF orientation applied, transparency resolved, backgrounds cleaned.
+Project-URL: Homepage, https://github.com/sigrix-io/mullion
+Project-URL: Source, https://github.com/sigrix-io/mullion
+Project-URL: Issues, https://github.com/sigrix-io/mullion/issues
+Project-URL: Changelog, https://github.com/sigrix-io/mullion/blob/main/CHANGELOG.md
+Author: Sigrix
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: background-removal,dpi,exif,images,pillow,png,transparency
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pillow>=10.0
+Provides-Extra: dev
+Requires-Dist: mypy==2.3.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.16.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Mullion
+
+**One correct way to open an image.** EXIF orientation applied, transparency
+resolved rather than dropped, and a background cleaner that does not eat the
+subject.
+
+A mullion is the upright that divides a window into panes — one stone member,
+every pane set against it. That is the argument of this library: an application
+that opens user images in six places gets six different answers, and the fix is
+one member they all lean on.
+
+```python
+from mullion import open_bytes, open_path
+
+image = open_bytes(upload.read())        # RGB, upright, no black rectangle
+avatar = open_path(path, keep_alpha=True)  # RGBA preserved
+```
+
+## The defect this exists for
+
+`Image.open(...).convert("RGB")` is the spelling everyone reaches for, and it is
+wrong in two ways that both render as a *plausible* picture rather than an error.
+
+**Transparency composites against black.** `convert("RGB")` on an `RGBA` image
+drops the alpha channel and keeps whatever RGB sits underneath. In a PNG written
+by almost every tool, fully transparent pixels carry `(0, 0, 0)` — so a cutout
+lands on a white page inside a black box.
+
+```python
+>>> from PIL import Image
+>>> logo = Image.open("cutout.png")          # RGBA, transparent corners
+>>> logo.convert("RGB").getpixel((0, 0))
+(0, 0, 0)
+>>> open_path("cutout.png").getpixel((0, 0))
+(255, 255, 255)
+```
+
+The same is true of `LA` (greyscale + alpha) and of palette `P` images carrying
+a `transparency` entry — which is what most "small" PNGs are saved as, and the
+one that is easiest to miss, because the alpha is not in the mode string at all.
+It is a key in `info`.
+
+**EXIF orientation is ignored.** A photo shot in portrait on a phone is stored
+landscape with a tag telling the viewer to rotate it. Pillow does not apply that
+tag on open. Because placement is usually aspect-preserving, a wrongly-rotated
+photo comes out *small and sideways* rather than obviously broken.
+
+Neither is loud. The response is a 200, the picture renders, the layout is
+right. A status-code test cannot see it and a reviewer looking at one image at a
+time will not catch it.
+
+This is measured, not hypothetical. Across one production codebase the same
+transparent PNG came back on a black rectangle through three upload paths and
+correctly through four others, because each had been written independently.
+
+## Install
+
+```bash
+pip install mullion
+```
+
+Python 3.11+, and Pillow is the only dependency.
+
+Importing the package costs nothing — Pillow is imported inside the functions
+that need it, so a service that imports at module scope and opens images rarely
+does not pay for it at start-up.
+
+## What it does
+
+### `mullion.source` — one correct open
+
+```python
+from mullion import normalize, open_bytes, open_path, has_transparency, flatten_onto
+
+normalize(pil_image)                       # the core: any Image in, upright RGB out
+normalize(pil_image, keep_alpha=True)      # RGBA out instead
+normalize(pil_image, matte=(18, 18, 22))   # composite onto something other than white
+
+open_bytes(data)                           # adapter: bytes from object storage or an upload
+open_path("photo.jpg")                     # adapter: a filesystem path
+```
+
+`normalize` is the whole rule and the adapters are three lines each. That split
+is deliberate: a path-only API is unusable from a web service holding bytes, and
+a bytes-only API forces a batch tool to read every file into memory first.
+
+`keep_alpha=False` composites transparency onto `matte` and returns `RGB` — what
+an opaque destination wants. `keep_alpha=True` returns `RGBA`, for a caller that
+will composite itself or write a cutout. Neither mutates the input.
+
+### `mullion.background` — clean a near-white background
+
+A "white" background is rarely `#FFFFFF`. It is `#FBFBFA` from a scanner,
+`#F7F8F9` from a phone's auto white balance, or a ring of `#FDFDFD` compression
+noise around a cutout. Each reads as a faint rectangle around the image.
+
+```python
+from mullion import clean_background, keeps_alpha
+
+mode = "flatten"                                    # or "transparent", or "off"
+image = open_path(path, keep_alpha=keeps_alpha(mode))
+cleaned, result = clean_background(image, mode=mode)
+
+print(result.message)
+# Cleaned background (63% of the image).
+# ...or: No white background detected; image left unchanged.
+```
+
+Two rules make this safe to run over everything:
+
+- **Only what touches the border is cleaned.** A global "brighter than
+  *threshold* becomes white" pass is the obvious implementation and it eats the
+  subject — the highlight on a white mug, the page of an open book, a bride's
+  dress, the sky behind a building. This flood-fills *inward from the edges*, so
+  a pixel is cleaned only when there is a continuous near-white path from it to
+  the frame. Interior highlights are unreachable and survive.
+- **Each image decides whether it has a background at all.** An image whose
+  border is not near-white — a full-bleed photograph, a dark render — comes back
+  untouched rather than partly eaten, and `result` says so. Ask
+  `looks_like_white_background()` directly if you want the verdict without the
+  work.
+
+There is deliberately no `open_and_clean` convenience. It would have to restate
+every keyword argument of both halves, and `keeps_alpha()` already names the one
+coupling between them — opening without it flattens an existing cutout onto
+white *before* cleaning, which leaves a pale fringe on the anti-aliased edges.
+
+### `mullion.page` — page geometry and DPI
+
+3000 px is 10 inches at 300 DPI and 41.7 inches at 72. Nothing in a file says
+which unless something writes the resolution into it.
+
+```python
+from mullion import named_page_geometry, resolve_page_geometry
+
+page = named_page_geometry("a4", dpi=300)
+page.description          # '2480x3508px (8.27x11.69in at 300 DPI)'
+
+page = resolve_page_geometry(page_width=8, page_height=10, unit="in", dpi=300)
+canvas = Image.new("RGB", (page.width_px, page.height_px), "white")
+canvas.save("out.png", dpi=(page.dpi, page.dpi))
+```
+
+The pixels and the DPI travel together, so the two cannot disagree. `a4`, `a3`,
+`a5`, `letter`, `legal` and `tabloid` are named; anything else is `px`, `in` or
+`mm`. This module imports nothing at all — it is arithmetic with the constants
+written down.
+
+> A PNG stores resolution in its `pHYs` chunk as pixels *per metre*, as an
+> integer. 300 DPI is 11811.02… px/m, so it is stored as 11811 and reads back as
+> 299.9994. That is the format, not a defect — compare with a tolerance.
+
+## What it is not
+
+Not a general imaging toolkit. Pillow already is one, and this library is a thin
+correctness layer over it, not a wrapper around it — you get a real
+`PIL.Image.Image` back and do whatever you like with it.
+
+Specifically out of scope: resizing and cropping (`ImageOps.fit` and friends
+already do this well), format conversion, colour management, subject-aware or
+model-based background removal, and laying multiple images out on a page. That
+last one is where the line falls: **this library handles one image; composing
+several is the application's job.**
+
+## Versioning
+
+Pre-1.0. Nothing is stable, and any `0.x` release may break any other — see
+[VERSIONING.md](VERSIONING.md), which is blunt about what that means. If you are
+building on `0.x`, please [open an issue](../../issues) saying so; the practical
+difference between an announced breaking change and a surprising one is knowing
+somebody is out there.
+
+## Contributing
+
+[CONTRIBUTING.md](CONTRIBUTING.md) is candid about what a small team can promise.
+Security findings go to **security@sigrix.io** and never to a public issue —
+[SECURITY.md](SECURITY.md).
+
+## Licence
+
+[Apache-2.0](LICENSE).

mullion-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+mullion/__init__.py,sha256=QCt-nnv_nvlOtEu27gfLNhtnrOgJElvIYb74HzHfDgU,3293
+mullion/background.py,sha256=NQXI5EpiAyXLwOsEVSzmnzPJrzvnfVwmQr5A-TXK1nk,11677
+mullion/page.py,sha256=F2IKoc0lByhrNmmAd23Jhvgs63S8VWXk-q7lK873Zps,4628
+mullion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mullion/source.py,sha256=0WMTynEsOIWnXGDjrJTLcs_XNtORsnuj78Tems5coDA,6127
+mullion-0.1.0.dist-info/METADATA,sha256=3geLAR41hnnNkaVmrdALvRB7z50ZYaVt2g1CvH_G5TY,8975
+mullion-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+mullion-0.1.0.dist-info/licenses/LICENSE,sha256=oHcgULuYGIbHR4QEnAgN4_coCdJLwrsNUQ6_TGdOHEk,11336
+mullion-0.1.0.dist-info/RECORD,,

mullion-0.1.0.dist-info/WHEEL

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

mullion-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Sigrix
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.