lica-raw 0.1.1__py3-none-any.whl

lica_raw/__init__.py

@@ -0,0 +1,46 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+# ----------------
+# standard library
+# ----------------
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("lica-raw")
+except PackageNotFoundError:
+    __version__ = "0.0.0+dev"
+
+from .errors import (
+    MissingImageError,
+    MissingMandatoryFitsError,
+    OutOfBoundsError,
+    ReadMetadataError,
+    UnknownDateTimeFormatError,
+    UnsupportedCFAError,
+)
+from .models import ImageMetadata
+from .ports import ImageReader, ImageReaderFactory
+from .types import BayerIndex, BayerPattern, HeaderType, ImageType, IntArray2D
+from .rect import Rect, Point
+
+__all__ = [
+    "Rect",
+    "Point",
+    "ImageReader",
+    "ImageMetadata",
+    "ImageReaderFactory",
+    "BayerPattern",
+    "BayerIndex",
+    "HeaderType",
+    "ImageType",
+    "IntArray2D",
+    "UnsupportedCFAError",
+    "ReadMetadataError",
+    "UnknownDateTimeFormatError",
+    "MissingImageError",
+    "MissingMandatoryFitsError",
+    "OutOfBoundsError",
+]

lica_raw/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .factory import ImageReaderFactoryImpl
+
+__all__ = ["ImageReaderFactoryImpl"]

lica_raw/adapters/exif.py

@@ -0,0 +1,222 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+# ----------------
+# Standard library
+# ----------------
+import logging
+import os
+from datetime import datetime, timezone
+from fractions import Fraction
+from typing import Any, Mapping
+from types import TracebackType
+
+# ---------------------
+# Third party libraries
+# ---------------------
+import exifread
+import numpy as np
+import rawpy
+from rawpy._rawpy import RawPy
+
+# ----------------
+# Own dependencies
+# ----------------
+from ..rect import Point, Rect
+from ..types import IntArray2D, BayerIndex, BayerPattern, HeaderType
+
+from ..errors import (
+    MissingImageError,
+    OutOfBoundsError,
+    ReadMetadataError,
+    UnknownDateTimeFormatError,
+    UnsupportedCFAError,
+    AlreadyClosedError,
+)
+from ..models import ImageMetadata
+from ..ports import ImageReader, RawPixels
+from ..utils import image_type_by_path
+
+# get the root logger
+log = logging.getLogger(__name__.split(".")[-1])
+
+
+def to_positive_float(value: Any | None) -> float | None:
+    if value in (0, "0", None):
+        return None
+    try:
+        result = round(float(Fraction(str(value))), 2)
+    except (ValueError, ZeroDivisionError, TypeError):
+        return None
+    return result if result > 0 else None
+
+
+def handle_date_obs(exif: Mapping[str, Any], path: str) -> datetime | None:
+    date_obs = None
+    for key in ("Image DateTime", "EXIF DateTimeOriginal"):
+        date_obs = exif.get(key)
+        if date_obs:
+            date_obs = str(date_obs)
+            break
+    if date_obs is None:
+        return None
+    new_date_obs = None
+    for fmt in ("%Y:%m:%d %H:%M:%S", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%dT%H:%M:%S%z"):
+        try:
+            new_date_obs = datetime.strptime(date_obs, fmt)
+        except Exception:
+            pass
+        else:
+            break
+    if new_date_obs is None:
+        raise UnknownDateTimeFormatError(date_obs)
+    return new_date_obs.replace(tzinfo=timezone.utc)
+
+
+class ExifReader(ImageReader):
+    def header_type(self) -> HeaderType:
+        return HeaderType.EXIF
+
+    def read_metadata(self, path: str) -> ImageMetadata:
+        with open(path, "rb") as fd:
+            exif = exifread.process_file(fd, details=True)
+        if not exif:
+            raise ReadMetadataError(os.path.basename(path))
+        make = exif.get("Image Make")
+        make = str(make).strip() if make is not None else None
+        model = exif.get("Image Model")
+        model = str(model).strip() if model is not None else None
+        focal_len = to_positive_float(exif.get("EXIF FocalLength"))
+        f_number = to_positive_float(exif.get("EXIF FNumber"))
+        iso = exif.get("EXIF ISOSpeedRatings")
+        iso = int(float(str(iso))) if iso is not None else None
+        exptime = exif.get("EXIF ExposureTime")
+        exptime = float(Fraction(str(exptime))) if exptime is not None else None
+        timestamp = handle_date_obs(exif, path)
+        image_type = image_type_by_path(path)
+        with rawpy.imread(path) as img:
+            height, width = img.raw_image.shape
+            black_levels = img.black_level_per_channel
+            black_level = int(round(sum(black_levels) / len(black_levels), 0))  # mean black level
+            color_desc = img.color_desc.decode("utf-8")
+            if color_desc != "RGBG":
+                raise UnsupportedCFAError(color_desc)
+            cfa = "".join(
+                map(
+                    lambda c: {"Gr": "G", "Gb": "G"}.get(c, c),
+                    [BayerIndex(i).name for i in img.raw_pattern.ravel()],
+                )
+            )
+            bayer = BayerPattern(cfa)
+            header_type = self.header_type()
+            extension = os.path.splitext(path)[1]
+
+        metadata = ImageMetadata(
+            width=width,
+            height=height,
+            make=make,
+            model=model,
+            exptime=exptime,
+            iso=iso,
+            gain=None,
+            black_level=black_level,
+            bayer=bayer,
+            imagetyp=image_type,
+            timestamp=timestamp,
+            focal_len=focal_len,
+            f_number=f_number,
+            header_type=header_type,
+            extension=extension,
+        )
+        return metadata
+
+    def read_pixels(self, path: str) -> RawPixels:
+        """returns an object that implements the RawPixels interface"""
+        if not os.path.isfile(path):
+            raise MissingImageError(path)
+        raw = rawpy.imread(path)
+        return ExifRawPixels(raw, path)
+
+
+class ExifRawPixels(RawPixels):
+    def __init__(self, raw: RawPy, path: str) -> None:
+        self.path = path
+        self.img = raw
+        self.black_levels = raw.black_level_per_channel
+        self.shape = raw.raw_image.shape
+        self.pattern = raw.raw_pattern
+
+    def close(self) -> None:
+        if self.img is not None:
+            self.img.close()
+            self.img = None
+
+    # No context managers here, we need to keep the internal numpy
+    # raw_pixels array alive while statistics are being computed
+    def __del__(self) -> None:
+        try:
+            if self.img is not None:
+                self.img.close()
+        finally:
+            self.img = None
+
+    def __enter__(self) -> "ExifRawPixels":
+            if self.img is None:
+                raise AlreadyClosedError(os.path.basename(self.path))
+            return self
+
+    def __exit__(
+            self,
+            exc_type: type[BaseException] | None,
+            exc_value: BaseException | None,
+            traceback: TracebackType | None,
+        ) -> None:
+            self.close()
+
+    def _section(
+        self,
+        x: int,
+        y: int,
+        section: Rect | None,
+    ) -> IntArray2D:
+        screen = Rect.from_points(Point.zero(), Point(x=self.shape[1], y=self.shape[0])) // 2
+        if section is None:
+            section = screen
+        elif not screen.contains(section):
+            raise OutOfBoundsError(section)
+        section = section * 2
+        x1 = x + section.x1
+        y1 = y + section.y1
+        x2 = section.x2
+        y2 = section.y2
+        return self.img.raw_image[y1:y2:2, x1:x2:2]
+
+    def r(self, section: Rect | None) -> IntArray2D:
+        y, x = np.argwhere(self.pattern == BayerIndex.R)[0]
+        return self._section(x, y, section)
+
+    def gr(self, section: Rect | None) -> IntArray2D:
+        y, x = np.argwhere(self.pattern == BayerIndex.Gr)[0]
+        return self._section(x, y, section)
+
+    def gb(self, section: Rect | None) -> IntArray2D:
+        y, x = np.argwhere(self.pattern == BayerIndex.Gb)[0]
+        return self._section(x, y, section)
+
+    def b(self, section: Rect | None) -> IntArray2D:
+        y, x = np.argwhere(self.pattern == BayerIndex.B)[0]
+        return self._section(x, y, section)
+
+    def r_black(self) -> int:
+        return self.black_levels[BayerIndex.R]
+
+    def gr_black(self) -> int:
+        return self.black_levels[BayerIndex.Gr]
+
+    def gb_black(self) -> int:
+        return self.black_levels[BayerIndex.Gb]
+
+    def b_black(self) -> int:
+        return self.black_levels[BayerIndex.B]

lica_raw/adapters/factory.py

@@ -0,0 +1,33 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+# ----------------
+# Standard library
+# ----------------
+import os
+
+# ----------------
+# Own dependencies
+# ----------------
+from ..errors import UnsupportedImageFormatError
+from ..ports import ImageReader, ImageReaderFactory
+
+FITS_EXTENSIONS = (".fit", ".fits", ".fts")
+
+RAW_EXTENSIONS = (".nef", ".cr2", ".cr3", ".arw", ".raf", ".orf", ".dng", ".rw2")
+
+
+class ImageReaderFactoryImpl(ImageReaderFactory):
+    def get_reader(self, path: str) -> ImageReader:
+        ext = os.path.splitext(path)[1].lower()
+        if ext in FITS_EXTENSIONS:
+            from .fits import FitsReader
+
+            return FitsReader()
+        if ext in RAW_EXTENSIONS:
+            from .exif import ExifReader
+
+            return ExifReader()
+        raise UnsupportedImageFormatError(path)

lica_raw/adapters/fits.py

@@ -0,0 +1,252 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+# ----------------
+# Standard library
+# ----------------
+import os
+from datetime import datetime, timezone
+from types import TracebackType
+
+# ---------------------
+# Third party libraries
+# ---------------------
+from astropy.io import fits
+from astropy.io.fits import HDUList
+
+# ----------------
+# Own dependencies
+# ----------------
+from ..rect import Point, Rect
+from ..types import BayerIndex, BayerPattern, HeaderType, IntArray2D
+
+from ..errors import (
+    MissingImageError,
+    MissingMandatoryFitsError,
+    OutOfBoundsError,
+    UnknownDateTimeFormatError,
+    AlreadyClosedError,
+    ReadMetadataError,
+)
+from ..models import ImageMetadata
+from ..ports import ImageReader, RawPixels
+
+# FITS relevant keywords
+NAXIS1: str = "NAXIS1"
+NAXIS2: str = "NAXIS2"
+HISTORY: str = "HISTORY"
+COMMENT: str = "COMMENT"
+INSTRUME: str = "INSTRUME"
+LOG_GAIN: str = "LOG-GAIN"
+BAYERPAT: str = "BAYERPAT"
+PEDESTAL: str = "PEDESTAL"
+XPIXSIZE: str = "XPIXSZ"
+YPIXSIZE: str = "YPIXSZ"
+IMAGETYP: str = "IMAGETYP"
+FOCALLEN: str = "FOCALLEN"
+APTDIA: str = "APTDIA"
+EXPTIME: str = "EXPTIME"
+DATE_OBS: str = "DATE-OBS"
+
+
+def bayer_layout(pattern: BayerPattern) -> list[tuple[int, int]]:
+    """
+    Turns a Bayyer pattern string into a 2x2 Bayer Matrix with the (row, column)
+    coordinates of R, Gr, B y Gb.
+    The matrix is given as a list, indexed by BayerIndex
+    """
+    coords = [(0, 0), (0, 0), (0, 0), (0, 0)]
+    p = pattern.value
+    # Patrón en orden fila-major:
+    #   p[0] p[1]
+    #   p[2] p[3]
+    raw = [
+        [p[0], p[1]],
+        [p[2], p[3]],
+    ]
+    r_coords = next(
+        (r, c) for r, row in enumerate(raw) for c, value in enumerate(row) if value == "R"
+    )
+    b_coords = next(
+        (r, c) for r, row in enumerate(raw) for c, value in enumerate(row) if value == "B"
+    )
+    # El otro G de la fila de R es Gr.
+    gr_coords = (r_coords[0], 1 - r_coords[1])
+    # El otro G de la fila de B es Gb.
+    gb_coords = (b_coords[0], 1 - b_coords[1])
+    coords[BayerIndex.R] = r_coords
+    coords[BayerIndex.Gr] = gr_coords
+    coords[BayerIndex.B] = b_coords
+    coords[BayerIndex.Gb] = gb_coords
+    return coords
+
+
+class FitsReader(ImageReader):
+    MANDATORY_KEYWORDS = {
+        NAXIS1,
+        NAXIS2,
+        BAYERPAT,
+    }
+
+    def header_type(self) -> HeaderType:
+        return HeaderType.FITS
+
+    def handle_date_obs(self, date_obs: str) -> datetime:
+        new_date_obs = None
+        for fmt in (
+            "%Y-%m-%d %H:%M:%S",
+            "%Y-%m-%dT%H:%M:%S",
+            "%Y-%m-%d %H:%M:%S.%f",
+            "%Y-%m-%dT%H:%M:%S.%f",
+            "%Y-%m-%dT%H:%M:%S:%:z",
+            "%Y-%m-%dT%H:%M:%S%Z",
+            "%Y-%m-%dT%H:%M:%S.%f%:z",
+            "%Y-%m-%dT%H:%M:%S.%f%Z",
+        ):
+            try:
+                new_date_obs = datetime.strptime(date_obs, fmt)
+            except Exception:
+                pass
+            else:
+                break
+        if new_date_obs is None:
+            raise UnknownDateTimeFormatError(date_obs)
+        return new_date_obs.replace(tzinfo=timezone.utc)
+
+    def read_metadata(self, path: str) -> ImageMetadata:
+        """returns an instance of ImageMetadata dataclass"""
+        try:
+            with fits.open(path) as hdul:
+                header = hdul[0].header
+                available = set(header.keys())
+                if not self.MANDATORY_KEYWORDS < available:
+                    raise MissingMandatoryFitsError(self.MANDATORY_KEYWORDS - available)
+                width = header[NAXIS1]
+                height = header[NAXIS2]
+                make = None
+                model = header.get(INSTRUME)
+                exptime = header.get(EXPTIME)
+                gain = header.get(LOG_GAIN)
+                black_level = header.get(PEDESTAL)
+                bayer = header[BAYERPAT]
+                image_type = header.get(IMAGETYP)
+                timestamp = self.handle_date_obs(header.get(DATE_OBS))
+                focal_len = header.get(FOCALLEN)
+                f_number = (
+                    None
+                    if header.get(APTDIA) is None or focal_len is None
+                    else round(focal_len / header[APTDIA], 2)
+                )
+                header_type = self.header_type()
+                extension = os.path.splitext(path)[1]
+                metadata = ImageMetadata(
+                    width=width,
+                    height=height,
+                    make=make,
+                    model=model,
+                    exptime=exptime,
+                    iso=None,
+                    gain=gain,
+                    black_level=black_level,
+                    bayer=bayer,
+                    imagetyp=image_type,
+                    timestamp=timestamp,
+                    focal_len=focal_len,
+                    f_number=f_number,
+                    header_type=header_type,
+                    extension=extension,
+                )
+                return metadata
+        except OSError:
+            raise ReadMetadataError(os.path.basename(path))
+
+    def read_pixels(self, path: str) -> RawPixels:
+        """returns an object that implements the RawPixels interface"""
+        if not os.path.isfile(path):
+            raise MissingImageError(path)
+        hdul = fits.open(path)
+        return FitsRawPixels(hdul, path)
+
+
+class FitsRawPixels(RawPixels):
+    def __init__(self, hdul: HDUList, path: str) -> None:
+        self.path= path
+        self.hdul = hdul
+        header = hdul[0].header
+        self.black_levels = [header.get(PEDESTAL)] * 4
+        self.shape = (header[NAXIS2], header[NAXIS1])
+        pattern = BayerPattern(header[BAYERPAT])
+        self.coords = bayer_layout(pattern)
+
+    def close(self) -> None:
+        if self.hdul is not None:
+            self.hdul.close()
+            self.hdul = None
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        finally:
+            self.hdul = None
+
+    def __enter__(self) -> "FitsRawPixels":
+            if self.hdul is None:
+                raise AlreadyClosedError(os.path.basename(self.path))
+            return self
+
+    def __exit__(
+            self,
+            exc_type: type[BaseException] | None,
+            exc_value: BaseException | None,
+            traceback: TracebackType | None,
+        ) -> None:
+            self.close()
+
+    def _section(
+        self,
+        x: int,
+        y: int,
+        section: Rect | None,
+    ) -> IntArray2D:
+        screen = Rect.from_points(Point.zero(), Point(x=self.shape[1], y=self.shape[0])) // 2
+        if section is None:
+            section = screen
+        elif not screen.contains(section):
+            raise OutOfBoundsError(section)
+        section = section * 2
+        x1 = x + section.x1
+        y1 = y + section.y1
+        x2 = section.x2
+        y2 = section.y2
+        img: IntArray2D = self.hdul[0].data
+        return img[y1:y2:2, x1:x2:2]
+
+    def r(self, section: Rect | None) -> IntArray2D:
+        y, x = self.coords[BayerIndex.R]
+        return self._section(x, y, section)
+
+    def gr(self, section: Rect | None) -> IntArray2D:
+        y, x = self.coords[BayerIndex.Gr]
+        return self._section(x, y, section)
+
+    def gb(self, section: Rect | None) -> IntArray2D:
+        y, x = self.coords[BayerIndex.Gb]
+        return self._section(x, y, section)
+
+    def b(self, section: Rect | None) -> IntArray2D:
+        y, x = self.coords[BayerIndex.B]
+        return self._section(x, y, section)
+
+    def r_black(self) -> int:
+        return self.black_levels[BayerIndex.R]
+
+    def gr_black(self) -> int:
+        return self.black_levels[BayerIndex.Gr]
+
+    def gb_black(self) -> int:
+        return self.black_levels[BayerIndex.Gb]
+
+    def b_black(self) -> int:
+        return self.black_levels[BayerIndex.B]

lica_raw/errors.py

@@ -0,0 +1,49 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+
+# ----------------
+# Own dependencies
+# ----------------
+
+
+class RawBaseError(Exception):
+    """Raw library base error"""
+
+    def __str__(self):
+        msg = self.__doc__
+        return f"{msg}: {self.args[0]}." if self.args else f"{msg}."
+
+
+class UnsupportedImageFormatError(RawBaseError):
+    """Unsupported image format"""
+
+
+class AlreadyClosedError(RawBaseError):
+    """Resource already closed"""
+
+
+class UnsupportedCFAError(RawBaseError):
+    """Unsupported Color Filter Array"""
+
+
+class ReadMetadataError(RawBaseError):
+    """Could not read image metadata"""
+
+
+class UnknownDateTimeFormatError(RawBaseError):
+    """unknown observation date format string"""
+
+
+class OutOfBoundsError(RawBaseError):
+    """out of bounds rectangle"""
+
+
+class MissingImageError(RawBaseError):
+    """Image path does not exists"""
+
+
+class MissingMandatoryFitsError(RawBaseError):
+    """Missing mandatory keywords in FITS image"""

lica_raw/models.py

@@ -0,0 +1,37 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+# ----------------
+# Standard library
+# ----------------
+from dataclasses import dataclass
+from datetime import datetime
+
+# ----------------
+# Own dependencies
+# ----------------
+from .types import BayerPattern, ImageType, HeaderType
+
+
+@dataclass
+class ImageMetadata:
+    width: int
+    height: int
+    make: str | None
+    model: str | None
+    exptime: float | None
+    iso: int | None
+    gain: float | None
+    black_level: int | None
+    bayer: BayerPattern
+    imagetyp: ImageType | None
+    timestamp: datetime | None
+    focal_len: float | None
+    f_number: float | None
+    header_type: HeaderType
+    extension: str
+
+    def __str__(self) -> str:
+        return f"{self.model} {self.width}x{self.height}"

lica_raw/ports.py

@@ -0,0 +1,56 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+# ----------------
+# Standard library
+# ----------------
+from types import TracebackType
+from typing import Protocol, Self
+
+# ----------------
+# Own dependencies
+# ----------------
+from .models import ImageMetadata
+from .rect import Rect
+from .types import HeaderType, IntArray2D
+
+
+class RawPixels(Protocol):
+    def r(self, section: Rect | None) -> IntArray2D: ...
+    def gr(self, section: Rect | None) -> IntArray2D: ...
+    def gb(self, section: Rect | None) -> IntArray2D: ...
+    def b(self, section: Rect | None) -> IntArray2D: ...
+
+    def r_black(self) -> int: ...
+    def gr_black(self) -> int: ...
+    def gb_black(self) -> int: ...
+    def b_black(self) -> int: ...
+
+    def __enter__(self) -> Self: ...
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None: ...
+
+
+class ImageReader(Protocol):
+    def header_type(self) -> HeaderType: ...
+
+    def read_metadata(self, path: str) -> ImageMetadata:
+        """returns an instance of ImageMetadata dataclass"""
+        ...
+
+    def read_pixels(self, path: str) -> RawPixels:
+        """returns an object that implements the RawPixels interface"""
+        ...
+
+
+class ImageReaderFactory(Protocol):
+    def get_reader(self, path: str) -> ImageReader:
+        """returns an object that implements the ImageReader interface"""
+        ...

lica_raw/rect.py

@@ -0,0 +1,109 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+# ----------------
+# Standard library
+# ----------------
+import re
+from typing import NamedTuple
+
+# ----------------
+# Own dependencies
+# ----------------
+from .errors import RawBaseError
+
+
+class InvalidRectStringError(RawBaseError):
+    """Rectangle string incorrectly formatted"""
+
+
+class Point(NamedTuple):
+    x: int
+    y: int
+
+    def __mul__(self, rhs: int) -> "Point":
+        return Point(self.x * rhs, self.y * rhs)
+
+    def __floordiv__(self, rhs: int) -> "Point":
+        return Point(self.x // rhs, self.y // rhs)
+
+    @classmethod
+    def zero(cls) -> "Point":
+        return cls(0, 0)
+
+
+PATTERN: re.Pattern[str] = re.compile(r"\[(\d+):(\d+),(\d+):(\d+)\]")
+
+
+class Rect(NamedTuple):
+    x1: int
+    y1: int
+    x2: int
+    y2: int
+
+    @classmethod
+    def from_points(cls, p1: Point, p2: Point) -> "Rect":
+        return cls(p1.x, p1.y, p2.x, p2.y)
+
+    @classmethod
+    def from_string(cls, value: str) -> "Rect":
+        match = re.fullmatch(PATTERN, value.strip())
+        if match is None:
+            raise InvalidRectStringError(f"{value!r}")
+        x1, y1, x2, y2 = map(int, match.groups())
+        return cls(x1, y1, x2, y2)
+
+    def width(self) -> int:
+        return self.x2 - self.x1
+
+    def height(self) -> int:
+        return self.y2 - self.y1
+
+    def dimensions(self) -> tuple[int, int]:
+        return self.x2 - self.x1, self.y2 - self.y1
+
+    def origin(self) -> Point:
+        return Point(self.x1, self.y1)
+
+    def central(self) -> Point:
+        return Point((self.x1 + self.x2) // 2, (self.y1 + self.y2) // 2)
+
+    def contains(self, other: "Rect") -> bool:
+        return (
+            (self.x1 <= other.x1)
+            and (self.y1 <= other.y1)
+            and (other.x2 <= self.x2)
+            and (other.y2 <= self.y2)
+        )
+
+    def recenter_on(self, screen: "Rect") -> "Rect":
+        c_screen = screen.central()
+        c_self = self.central()
+        dx = c_screen.x - c_self.x
+        dy = c_screen.y - c_self.y
+        return self + Point(dx, dy)
+
+    def __str__(self) -> str:
+        """as a numpy slice"""
+        return f"[{self.y1}:{self.y2},{self.x1}:{self.x2}]"
+
+    def __add__(self, rhs: Point) -> "Rect":
+        return Rect(self.x1 + rhs.x, self.y1 + rhs.y, self.x2 + rhs.x, self.y2 + rhs.y)
+
+    def __mul__(self, rhs: int) -> "Rect":
+        return Rect(self.x1 * rhs, self.y1 * rhs, self.x2 * rhs, self.y2 * rhs)
+
+    def __floordiv__(self, rhs: int) -> "Rect":
+        return Rect(self.x1 // rhs, self.y1 // rhs, self.x2 // rhs, self.y2 // rhs)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Rect):
+            return NotImplemented
+        return (
+            self.x1 == other.x1
+            and self.y1 == other.y1
+            and self.x2 == other.x2
+            and self.y2 == other.y2
+        )

lica_raw/types.py

@@ -0,0 +1,48 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+# ----------------
+# Standard library
+# ----------------
+from enum import IntEnum, StrEnum
+
+# ---------------------
+# Third party libraries
+# ---------------------
+import numpy as np
+
+# type alias
+type IntArray2D = np.ndarray[tuple[int, int], np.dtype[np.uint16]]
+
+# -----------------
+# Enumeration types
+# -----------------
+
+class HeaderType(StrEnum):
+    FITS = "FITS"
+    EXIF = "EXIF"
+
+
+class BayerPattern(StrEnum):
+    RGGB = "RGGB"
+    BGGR = "BGGR"
+    GRBG = "GRBG"
+    GBRG = "GBRG"
+
+
+class ImageType(StrEnum):
+    BIAS = "BIAS"
+    DARK = "DARK"
+    FLAT = "FLAT"
+    LIGHT = "LIGHT"
+
+
+class BayerIndex(IntEnum):
+    """Indexes to bidimensional 2x2 RGB Bayer pattern, black_level_per_channel and white_levels_per_channel"""
+
+    R = 0
+    Gr = 1
+    B = 2
+    Gb = 3

lica_raw/utils.py

@@ -0,0 +1,45 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+# ----------------
+# Standard library
+# ----------------
+import os
+import re
+
+# ----------------
+# Own dependencies
+# ----------------
+from .types import ImageType
+
+
+def mk_test_img_type(regexp: re.Pattern[str]):
+    def wrapper(path: str):
+        def test(name: str):
+            matchobj = regexp.search(name.upper())
+            return True if matchobj else False
+
+        filepath = os.path.basename(path)
+        dirname = os.path.basename(os.path.dirname(path))
+        return test(dirname) or test(filepath)
+
+    return wrapper
+
+is_flat = mk_test_img_type(re.compile(r"FLAT"))
+is_dark = mk_test_img_type(re.compile(r"(DARK|OSCURO)"))
+is_bias = mk_test_img_type(re.compile(r"BIAS"))
+
+def image_type_by_path(path: str) -> ImageType:
+    if is_flat(path):
+        result = ImageType.FLAT
+    elif is_dark(path):
+        result = ImageType.DARK
+    elif is_bias(path):
+        result = ImageType.BIAS
+    else:
+        result = ImageType.LIGHT
+    return result
+
+__all__ = ["image_type_by_path"]

lica_raw-0.1.1.dist-info/METADATA

@@ -0,0 +1,368 @@
+Metadata-Version: 2.4
+Name: lica-raw
+Version: 0.1.1
+Summary: LICA RGB Raw loader for DSLR images
+Author: Rafael González
+Author-email: Rafael González <rafael08@ucm.es>
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Dist: numpy>=2.5
+Requires-Dist: exifread>=3.5 ; extra == 'exif'
+Requires-Dist: rawpy>=0.27 ; extra == 'exif'
+Requires-Dist: astropy>=8.0 ; extra == 'fits'
+Requires-Python: >=3.12
+Provides-Extra: exif
+Provides-Extra: fits
+Description-Content-Type: text/markdown
+
+# lica-raw
+
+## Introduction
+
+`lica-raw` is a lightweight utility for reading metadata and raw Bayer pixel data from astronomical camera images. It defines minimal reader interfaces using `typing.Protocol` and provides adapters for FITS images and camera RAW files with EXIF metadata.
+
+The package supports Bayer colour-filter-array layouts, per-channel black levels, optional rectangular regions of interest, and automatic selection of a reader from the image file extension. Application code depends only on the `ImageReader`, `ImageReaderFactory`, and `RawPixels` protocols, while the concrete image-format behaviour is supplied by adapters.
+
+Objects returned by `read_pixels()` own the underlying image resource. They can be used as context managers, or closed explicitly with `close()` when batch processing makes a `with` block inconvenient.
+
+## Installation
+
+Install `lica-raw` directly from the `lica-ng` Git repository:
+
+```bash
+pip install lica-raw
+```
+
+or add it to your `pyproject.toml`:
+
+```toml
+[project]
+dependencies = [
+    "lica-raw",
+]
+```
+
+For FITS image support, `lica-raw[fits]` installs the needed dependency on `astropy`:
+
+```toml
+[project]
+dependencies = [
+    "lica-raw[fits]",
+]
+```
+
+For camera RAW file support,  `lica-raw[exif]` installs the needed dependencies `rawpy`, `exifread`, and `numpy`:
+
+```toml
+[project]
+dependencies = [
+    "lica-raw[exif]",
+]
+```
+
+## Interfaces
+
+`lica-raw` defines its image-access contracts using `typing.Protocol`. Adapters do not need to inherit from these protocols explicitly; they only need to provide the required methods and attributes.
+
+### Image reader
+
+```python
+from typing import Protocol
+
+from lica_raw import HeaderType, ImageMetadata
+from lica_raw.ports import RawPixels
+
+
+class ImageReader(Protocol):
+    def header_type(self) -> HeaderType: ...
+
+    def read_metadata(self, path: str) -> ImageMetadata: ...
+
+    def read_pixels(self, path: str) -> RawPixels: ...
+```
+
+### Raw pixels
+
+`RawPixels` objects support the context-manager protocol. Entering the context returns the pixel-data object; leaving it closes the underlying image resource, even if an exception occurs.
+
+```python
+from collections.abc import Generator
+from types import TracebackType
+from typing import Protocol, Self
+
+from lica_raw import IntArray2D, Rect
+
+
+class RawPixels(Protocol):
+    def r(self, section: Rect | None) -> IntArray2D: ...
+    def gr(self, section: Rect | None) -> IntArray2D: ...
+    def gb(self, section: Rect | None) -> IntArray2D: ...
+    def b(self, section: Rect | None) -> IntArray2D: ...
+
+    def r_black(self) -> int: ...
+    def gr_black(self) -> int: ...
+    def gb_black(self) -> int: ...
+    def b_black(self) -> int: ...
+
+    def close(self) -> None: ...
+
+    def __enter__(self) -> Self: ...
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None: ...
+```
+
+`close()` is idempotent and can be called explicitly. This is useful in batch-processing loops where wrapping every image in a `with` block would make the client code unnecessarily nested.
+
+### Reader factory
+
+```python
+from typing import Protocol
+
+from lica_raw.ports import ImageReader
+
+
+class ImageReaderFactory(Protocol):
+    def get_reader(self, path: str) -> ImageReader: ...
+```
+
+## Adapters
+
+| Adapter | Module | Extra | Description |
+|---|---|---|---|
+| `FitsReader` | `lica_raw.adapters.fits` | `astropy` | Reads metadata and raw Bayer pixels from FITS images. |
+| `ExifReader` | `lica_raw.adapters.exif` | `rawpy`, `exifread`, `numpy` | Reads metadata and raw Bayer pixels from camera RAW files using EXIF metadata and `rawpy`. |
+| `ImageReaderFactoryImpl` | `lica_raw.adapters` | — | Selects `FitsReader` for FITS extensions and `ExifReader` otherwise. |
+
+The factory recognises the following extensions as FITS:
+
+- `.fit`
+- `.fits`
+- `.fts`
+
+All other files are handled by `ExifReader`.
+
+```python
+from lica_raw.adapters import ImageReaderFactoryImpl
+
+factory = ImageReaderFactoryImpl()
+reader = factory.get_reader("image_001.fits")
+```
+
+## Image metadata
+
+`read_metadata()` returns an `ImageMetadata` dataclass:
+
+```python
+from datetime import datetime
+
+from lica_raw import BayerPattern, HeaderType, ImageType
+
+
+@dataclass
+class ImageMetadata:
+    width: int
+    height: int
+    make: str | None
+    model: str | None
+    exptime: float | None
+    iso: int | None
+    gain: float | None
+    black_level: int | None
+    bayer: BayerPattern
+    imagetyp: ImageType | None
+    timestamp: datetime | None
+    focal_len: float | None
+    f_number: float | None
+    header_type: HeaderType
+    extension: str
+```
+
+The supported Bayer patterns are defined in the `BayerPattern` enum as follows:
+
+- `RGGB`
+- `BGGR`
+- `GRBG`
+- `GBRG`
+
+The supported image types are defined in the `ImageType` enum as follows:
+
+- `BIAS`
+- `DARK`
+- `FLAT`
+- `LIGHT`
+
+For non-FITS images, `image_type_by_path()` infers the image type from the file name or immediate parent-directory name. Names containing `FLAT`, `DARK` or `OSCURO`, or `BIAS` are classified accordingly; all other images are treated as `LIGHT`.
+
+## FITS support
+
+`FitsReader` requires the following mandatory FITS keywords:
+
+- `NAXIS1`
+- `NAXIS2`
+- `BAYERPAT`
+
+It also reads optional metadata from these keywords:
+
+| Metadata | FITS keyword |
+|---|---|
+| Instrument or camera model | `INSTRUME` |
+| Exposure time | `EXPTIME` |
+| Gain | `LOG-GAIN` |
+| Black level | `PEDESTAL` |
+| Image type | `IMAGETYP` |
+| Observation date | `DATE-OBS` |
+| Focal length | `FOCALLEN` |
+| Aperture diameter | `APTDIA` |
+
+If `FOCALLEN` and `APTDIA` are both present, the focal ratio is calculated as `FOCALLEN / APTDIA`.
+
+The observation timestamp is interpreted in UTC. `FitsRawPixels` uses `PEDESTAL` as the black level for all four Bayer channels.
+
+## Camera RAW support
+
+`ExifReader` reads EXIF metadata with `exifread` and raw image data with `rawpy`. It extracts manufacturer, model, focal length, focal ratio, ISO, exposure time, observation date, image dimensions, black levels, and the Bayer pattern.
+
+The adapter currently requires a `RGBG` colour-filter-array description from `rawpy`. Other CFA layouts raise `UnsupportedCFAError`.
+
+The observation date is read from `Image DateTime` or `EXIF DateTimeOriginal`, interpreted in UTC, and accepts the following formats:
+
+- `%Y:%m:%d %H:%M:%S`
+- `%Y-%m-%dT%H:%M:%S`
+- `%Y-%m-%dT%H:%M:%S%z`
+
+## Regions of interest
+
+The `r()`, `gr()`, `gb()`, and `b()` methods return a two-dimensional NumPy array containing the pixels of one Bayer colour channel.
+
+If `section` is `None`, the full image is used. Otherwise, `section` must be a `Rect` expressed in output-channel coordinates; it is validated against the available image area and converted internally to the corresponding full-resolution Bayer coordinates.
+
+```python
+from lica_raw import Rect
+
+section = Rect(0, 0, 100, 100)
+
+red = pixels.r(section)
+green_red = pixels.gr(section)
+green_blue = pixels.gb(section)
+blue = pixels.b(section)
+```
+
+A section outside the valid area raises `OutOfBoundsError`.
+
+## Resource management
+
+`read_pixels()` returns an object that owns an open image resource. Prefer a context manager when the lifetime of the pixels is limited to a local block:
+
+```python
+with reader.read_pixels(path) as pixels:
+    red = pixels.r(None)
+```
+
+For batch processing, explicit closing is equally valid:
+
+```python
+for path in image_paths:
+    pixels = reader.read_pixels(path)
+    try:
+        red = pixels.r(None)
+        ...
+    finally:
+        pixels.close()
+```
+
+After `close()`, the pixel object must not be used to access image data.
+
+## Errors
+
+All package-specific errors derive from `RawBaseError`.
+
+| Error | Description |
+|---|---|
+| `UnsupportedCFAError` | The camera RAW file uses an unsupported colour-filter-array layout. |
+| `ReadMetadataError` | EXIF metadata could not be read. |
+| `UnknownDateTimeFormatError` | The observation-date string uses an unsupported format. |
+| `OutOfBoundsError` | The requested rectangular section lies outside the image. |
+| `MissingImageError` | The image path does not exist. |
+| `MissingMandatoryFitsError` | One or more mandatory FITS keywords are missing. |
+| `AlreadyClosedError` | Attempt to close an already closed FITS/EXIF image. |
+
+## Usage example
+
+```python
+from lica_raw import ImageReaderFactory, Rect
+from lica_raw.adapters import ImageReaderFactoryImpl
+
+path = "light_001.fits"
+
+factory: ImageReaderFactory = ImageReaderFactoryImpl()
+reader = factory.get_reader(path)
+
+metadata = reader.read_metadata(path)
+print(metadata.model, metadata.width, metadata.height)
+print(metadata.bayer, metadata.exptime, metadata.timestamp)
+
+with reader.read_pixels(path) as pixels:
+    # Gets the whole channel when section is None.
+    red = pixels.r(None)
+    green_red = pixels.gr(Rect(0, 0, 256, 256))
+    green_blue = pixels.gb(Rect(0, 0, 256, 256))
+    blue = pixels.b(Rect(0, 0, 256, 256))
+
+    print(
+        pixels.r_black(),
+        pixels.gr_black(),
+        pixels.gb_black(),
+        pixels.b_black(),
+    )
+```
+
+## Usage example, with lica-cli package
+
+```python
+import sys
+from argparse import ArgumentParser, Namespace
+
+from lica_cli import parse_args, run_cli
+from lica_raw import ImageReaderFactory
+from lica_raw.adapters import ImageReaderFactoryImpl
+
+from myprog import __version__
+
+DESCRIPTION = "My program short description"
+
+
+def add_args(parser: ArgumentParser) -> None:
+    parser.add_argument("image", help="FITS or camera RAW image path")
+
+
+def cli_main(args: Namespace) -> None:
+    factory: ImageReaderFactory = ImageReaderFactoryImpl()
+    reader = factory.get_reader(args.image)
+
+    metadata = reader.read_metadata(args.image)
+    print(metadata)
+
+    with reader.read_pixels(args.image) as pixels:
+        # Gets the whole channel when section is None.
+        print("Red channel shape:", pixels.r(None).shape)
+
+
+def main():
+    args = parse_args(add_args, __name__, __version__, DESCRIPTION)
+    return_code = run_cli(cli_main, args, __name__, __version__)
+    sys.exit(return_code)
+
+
+if __name__ == "__main__":
+    main()
+```

lica_raw-0.1.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+lica_raw/__init__.py,sha256=cpIcS3uegsUmIArm2-5tNM30z_6ghqPORyjtl1bT8Go,1182
+lica_raw/adapters/__init__.py,sha256=X3bYzLJV8ts7UsQ18E9maduM3HAY6_mhipGshwsPXXw,82
+lica_raw/adapters/exif.py,sha256=e-Wl9MsMI3lnB7XAYTKshXHocyudS0Sh4ZlFhw5hJ_0,7207
+lica_raw/adapters/factory.py,sha256=E8ZXq1xF12g85DZmt6Naolw7VL-haamgGVLVb0XCYh4,992
+lica_raw/adapters/fits.py,sha256=nIroDafrcaYid8bfTEqfeO_RT1HD-dtDOchk13y3jkk,7948
+lica_raw/errors.py,sha256=bMVp31aRzElKHKPnVFkNOW0gOIeke66lFvzunu8Feug,1143
+lica_raw/models.py,sha256=cyHotcZSpCG3EGL27L8K-tNf_nFV-e6WlFsSiAQOV_E,937
+lica_raw/ports.py,sha256=OrwanTRX5zieeyCVt6g75zKh_8gljHbaBMXjb8AvOt4,1636
+lica_raw/rect.py,sha256=X2-9lXl3AXyWX7JCAS1lUOetaHqlnSwhzk8-D_bgDic,3022
+lica_raw/types.py,sha256=hSpUJIzn7x016VKxJYk9hbVf1aOjVIAO-ngfa6R80do,998
+lica_raw/utils.py,sha256=6_qRZMDxb320-oR2mVN1QP7jrKiqjGVuod35fxIQVSc,1221
+lica_raw-0.1.1.dist-info/licenses/LICENSE,sha256=AAxFY4JFsUgATHGcfHy_aFXU7KbvycCxGfszmPiUCjA,1066
+lica_raw-0.1.1.dist-info/WHEEL,sha256=9IUYslYuG_asT4WlWvfk_K76nveuLvSTKDoLeL0cV-Q,80
+lica_raw-0.1.1.dist-info/METADATA,sha256=cqJb9zSGUBWbBu4uLWMQoTMPgkkWbjz4qX14iRvCSBk,10879
+lica_raw-0.1.1.dist-info/RECORD,,

lica_raw-0.1.1.dist-info/WHEEL

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

lica_raw-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guaix UCM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.