readinsp 0.1.0__py3-none-any.whl

readinsp/__init__.py

@@ -0,0 +1,41 @@
+"""Read Insta360 .insp still images into NumPy arrays."""
+
+from .core import (
+    InspFormatError,
+    InspMetadata,
+    InspTrailer,
+    extract_preview_jpeg,
+    primary_jpeg_bytes,
+    read,
+    read_insp,
+    read_metadata,
+    read_preview,
+    trailer_bytes,
+)
+from .projection import (
+    InspCalibration,
+    LensCalibration,
+    SphericalAngle,
+    read_gravity_vector,
+    read_rectilinear,
+    render_rectilinear,
+)
+
+__all__ = [
+    "InspFormatError",
+    "InspMetadata",
+    "InspTrailer",
+    "extract_preview_jpeg",
+    "primary_jpeg_bytes",
+    "read",
+    "read_insp",
+    "read_metadata",
+    "read_preview",
+    "read_gravity_vector",
+    "read_rectilinear",
+    "render_rectilinear",
+    "InspCalibration",
+    "LensCalibration",
+    "SphericalAngle",
+    "trailer_bytes",
+]

readinsp/core.py

@@ -0,0 +1,427 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from io import BytesIO
+from pathlib import Path
+from typing import Any, BinaryIO, Iterable, Optional, Tuple, Union
+
+import numpy as np
+from PIL import ExifTags, Image, ImageOps
+
+JPEG_SOI = b"\xff\xd8"
+JPEG_EOI = b"\xff\xd9"
+
+APP1 = 0xE1
+APP2 = 0xE2
+SOS = 0xDA
+
+SOF_MARKERS = {
+    0xC0,
+    0xC1,
+    0xC2,
+    0xC3,
+    0xC5,
+    0xC6,
+    0xC7,
+    0xC9,
+    0xCA,
+    0xCB,
+    0xCD,
+    0xCE,
+    0xCF,
+}
+
+TRAILER_FIELD_NAMES = {
+    1: "serial",
+    2: "camera_model",
+    3: "firmware",
+    5: "calibration",
+    9: "jpeg_end_offset_or_size",
+    10: "unknown_10",
+    19: "image_size_message",
+    24: "unknown_24",
+    25: "unknown_25",
+    26: "source_path_message",
+    27: "dimension_message",
+    31: "orientation_or_pose",
+    65: "thumbnail_size_message",
+}
+
+
+class InspFormatError(ValueError):
+    """Raised when a file does not look like the observed .insp format."""
+
+
+@dataclass(frozen=True)
+class JPEGSegment:
+    marker: int
+    offset: int
+    payload: bytes
+
+
+@dataclass(frozen=True)
+class InspTrailer:
+    raw: bytes
+    prefix: bytes
+    fields: dict[str, Any]
+    decoded_until: int
+
+
+@dataclass(frozen=True)
+class InspMetadata:
+    path: Path
+    width: int
+    height: int
+    precision: int
+    components: int
+    preview_size: Optional[Tuple[int, int]]
+    preview_bytes: int
+    trailer_bytes: int
+    exif: dict[str, Any]
+    trailer: Optional[InspTrailer]
+
+
+def read_insp(
+    path: Union[str, Path, BinaryIO],
+    *,
+    mode: Optional[str] = "RGB",
+    apply_exif_orientation: bool = False,
+) -> np.ndarray:
+    """Read the primary .insp image as a NumPy array.
+
+    Parameters
+    ----------
+    path:
+        File path or binary file object.
+    mode:
+        Optional Pillow mode conversion. The default returns RGB arrays.
+        Pass `None` to keep Pillow's decoded mode.
+    apply_exif_orientation:
+        Apply Pillow's EXIF orientation transform before conversion.
+    """
+
+    return _decode_image(path, mode=mode, apply_exif_orientation=apply_exif_orientation)
+
+
+read = read_insp
+
+
+def read_preview(
+    path: Union[str, Path],
+    *,
+    mode: Optional[str] = "RGB",
+    apply_exif_orientation: bool = False,
+) -> np.ndarray:
+    """Read the APP2 preview JPEG as a NumPy array."""
+
+    preview = extract_preview_jpeg(path)
+    return _decode_image(
+        BytesIO(preview),
+        mode=mode,
+        apply_exif_orientation=apply_exif_orientation,
+    )
+
+
+def read_metadata(path: Union[str, Path]) -> InspMetadata:
+    """Inspect the JPEG structure and best-effort Insta360 trailer metadata."""
+
+    path = Path(path)
+    data = path.read_bytes()
+    width, height, precision, components = _jpeg_shape(data)
+    preview = _preview_jpeg(data)
+    preview_size = None
+    if preview is not None:
+        preview_width, preview_height, _, _ = _jpeg_shape(preview)
+        preview_size = (preview_width, preview_height)
+
+    raw_trailer = _trailer_bytes(data)
+    return InspMetadata(
+        path=path,
+        width=width,
+        height=height,
+        precision=precision,
+        components=components,
+        preview_size=preview_size,
+        preview_bytes=len(preview) if preview is not None else 0,
+        trailer_bytes=len(raw_trailer),
+        exif=_read_exif(path),
+        trailer=parse_trailer(raw_trailer) if raw_trailer else None,
+    )
+
+
+def primary_jpeg_bytes(path: Union[str, Path]) -> bytes:
+    """Return the primary JPEG stream, excluding the post-EOI trailer."""
+
+    data = Path(path).read_bytes()
+    eoi = data.rfind(JPEG_EOI)
+    if eoi < 0:
+        raise InspFormatError("missing JPEG EOI marker")
+    return data[: eoi + len(JPEG_EOI)]
+
+
+def trailer_bytes(path: Union[str, Path]) -> bytes:
+    """Return the bytes after the final JPEG EOI marker."""
+
+    return _trailer_bytes(Path(path).read_bytes())
+
+
+def extract_preview_jpeg(path: Union[str, Path]) -> bytes:
+    """Return the JPEG preview stored across APP2 segments."""
+
+    data = Path(path).read_bytes()
+    preview = _preview_jpeg(data)
+    if preview is None:
+        raise InspFormatError("missing APP2 preview JPEG")
+    return preview
+
+
+def parse_trailer(raw: bytes) -> InspTrailer:
+    """Best-effort decoder for the protobuf-like Insta360 trailer."""
+
+    start, rows = _find_trailer_message(raw)
+    fields: dict[str, Any] = {}
+    decoded_until = start
+
+    for field, wire_type, value, _, end in rows:
+        decoded_until = end
+        name = TRAILER_FIELD_NAMES.get(field, f"field_{field}")
+        fields[name] = _decode_trailer_value(value, wire_type)
+
+    return InspTrailer(
+        raw=raw,
+        prefix=raw[:start],
+        fields=fields,
+        decoded_until=decoded_until,
+    )
+
+
+def _decode_image(
+    source: Union[str, Path, BinaryIO],
+    *,
+    mode: Optional[str],
+    apply_exif_orientation: bool,
+) -> np.ndarray:
+    with Image.open(source) as image:
+        if apply_exif_orientation:
+            image = ImageOps.exif_transpose(image)
+        if mode is not None:
+            image = image.convert(mode)
+        return np.array(image)
+
+
+def _iter_header_segments(data: bytes) -> Iterable[JPEGSegment]:
+    if not data.startswith(JPEG_SOI):
+        raise InspFormatError("missing JPEG SOI marker")
+
+    offset = len(JPEG_SOI)
+    while offset < len(data):
+        if data[offset] != 0xFF:
+            raise InspFormatError(f"expected JPEG marker at byte {offset}")
+
+        marker_offset = offset
+        while offset < len(data) and data[offset] == 0xFF:
+            offset += 1
+        if offset >= len(data):
+            raise InspFormatError("truncated JPEG marker")
+
+        marker = data[offset]
+        offset += 1
+
+        if marker == SOS:
+            length = _segment_length(data, offset)
+            payload = data[offset + 2 : offset + length]
+            yield JPEGSegment(marker=marker, offset=marker_offset, payload=payload)
+            return
+
+        if marker == 0xD9:
+            yield JPEGSegment(marker=marker, offset=marker_offset, payload=b"")
+            return
+
+        if marker == 0x01 or 0xD0 <= marker <= 0xD7:
+            yield JPEGSegment(marker=marker, offset=marker_offset, payload=b"")
+            continue
+
+        length = _segment_length(data, offset)
+        payload = data[offset + 2 : offset + length]
+        yield JPEGSegment(marker=marker, offset=marker_offset, payload=payload)
+        offset += length
+
+    raise InspFormatError("truncated JPEG header")
+
+
+def _segment_length(data: bytes, offset: int) -> int:
+    if offset + 2 > len(data):
+        raise InspFormatError("truncated JPEG segment length")
+    length = int.from_bytes(data[offset : offset + 2], "big")
+    if length < 2:
+        raise InspFormatError("invalid JPEG segment length")
+    if offset + length > len(data):
+        raise InspFormatError("truncated JPEG segment payload")
+    return length
+
+
+def _jpeg_shape(data: bytes) -> tuple[int, int, int, int]:
+    for segment in _iter_header_segments(data):
+        if segment.marker in SOF_MARKERS:
+            payload = segment.payload
+            if len(payload) < 6:
+                raise InspFormatError("truncated JPEG SOF segment")
+            precision = payload[0]
+            height = int.from_bytes(payload[1:3], "big")
+            width = int.from_bytes(payload[3:5], "big")
+            components = payload[5]
+            return width, height, precision, components
+
+        if segment.marker == SOS:
+            break
+
+    raise InspFormatError("missing JPEG SOF segment")
+
+
+def _preview_jpeg(data: bytes) -> Optional[bytes]:
+    chunks = [
+        segment.payload
+        for segment in _iter_header_segments(data)
+        if segment.marker == APP2
+    ]
+    if not chunks:
+        return None
+
+    preview = b"".join(chunks)
+    if not preview.startswith(JPEG_SOI) or not preview.endswith(JPEG_EOI):
+        raise InspFormatError("APP2 payloads do not form a JPEG preview")
+    return preview
+
+
+def _trailer_bytes(data: bytes) -> bytes:
+    eoi = data.rfind(JPEG_EOI)
+    if eoi < 0:
+        raise InspFormatError("missing JPEG EOI marker")
+    return data[eoi + len(JPEG_EOI) :]
+
+
+def _read_exif(path: Path) -> dict[str, Any]:
+    with Image.open(path) as image:
+        exif = image.getexif()
+        out: dict[str, Any] = {}
+        for tag, value in exif.items():
+            name = ExifTags.TAGS.get(tag, str(tag))
+            out[name] = value
+        return out
+
+
+def _find_trailer_message(raw: bytes) -> tuple[int, list[tuple[int, int, Any, int, int]]]:
+    best_start = 0
+    best_rows: list[tuple[int, int, Any, int, int]] = []
+    best_score = (-1, -1)
+
+    for start in range(min(len(raw), 32)):
+        rows = _parse_protobuf_prefix(raw, start)
+        if not rows:
+            continue
+
+        names = {field for field, _, _, _, _ in rows}
+        text_fields = sum(
+            1
+            for field, wire_type, value, _, _ in rows
+            if field in {1, 2, 3, 5} and wire_type == 2 and _looks_like_text(value)
+        )
+        score = (text_fields + len(names & {1, 2, 3, 5, 19, 26, 27}), len(rows))
+        if score > best_score:
+            best_start = start
+            best_rows = rows
+            best_score = score
+
+    return best_start, best_rows
+
+
+def _parse_protobuf_prefix(
+    raw: bytes,
+    start: int,
+) -> list[tuple[int, int, Any, int, int]]:
+    offset = start
+    rows: list[tuple[int, int, Any, int, int]] = []
+
+    while offset < len(raw):
+        field_start = offset
+        try:
+            key, offset = _read_varint(raw, offset)
+            field = key >> 3
+            wire_type = key & 0x07
+
+            if field == 0:
+                break
+
+            if wire_type == 0:
+                value, offset = _read_varint(raw, offset)
+            elif wire_type == 1:
+                if offset + 8 > len(raw):
+                    break
+                value = raw[offset : offset + 8]
+                offset += 8
+            elif wire_type == 2:
+                length, offset = _read_varint(raw, offset)
+                if offset + length > len(raw):
+                    break
+                value = raw[offset : offset + length]
+                offset += length
+            elif wire_type == 5:
+                if offset + 4 > len(raw):
+                    break
+                value = raw[offset : offset + 4]
+                offset += 4
+            else:
+                break
+        except InspFormatError:
+            break
+
+        rows.append((field, wire_type, value, field_start, offset))
+
+    return rows
+
+
+def _read_varint(raw: bytes, offset: int) -> tuple[int, int]:
+    value = 0
+    shift = 0
+    while offset < len(raw):
+        byte = raw[offset]
+        offset += 1
+        value |= (byte & 0x7F) << shift
+        if byte < 0x80:
+            return value, offset
+        shift += 7
+        if shift > 70:
+            break
+    raise InspFormatError("invalid varint")
+
+
+def _decode_trailer_value(value: Any, wire_type: int) -> Any:
+    if wire_type == 0:
+        return value
+    if wire_type == 1 and isinstance(value, bytes):
+        return int.from_bytes(value, "little")
+    if wire_type == 2 and isinstance(value, bytes):
+        if _looks_like_text(value):
+            return value.decode("utf-8")
+        nested = _parse_protobuf_prefix(value, 0)
+        if nested and nested[-1][-1] == len(value):
+            return {
+                TRAILER_FIELD_NAMES.get(field, f"field_{field}"): _decode_trailer_value(
+                    nested_value, nested_wire_type
+                )
+                for field, nested_wire_type, nested_value, _, _ in nested
+            }
+        return value
+    if wire_type == 5 and isinstance(value, bytes):
+        return int.from_bytes(value, "little")
+    return value
+
+
+def _looks_like_text(value: bytes) -> bool:
+    if not value:
+        return False
+    try:
+        text = value.decode("utf-8")
+    except UnicodeDecodeError:
+        return False
+    return all(32 <= ord(char) < 127 for char in text)

readinsp/projection.py

@@ -0,0 +1,483 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Sequence, Tuple, Union
+
+import numpy as np
+from PIL import ExifTags, Image
+
+from .core import read_insp, read_metadata
+
+
+@dataclass(frozen=True)
+class SphericalAngle:
+    """Center of a rectilinear view on the stitched sphere, in degrees."""
+
+    yaw: float
+    pitch: float = 0.0
+    roll: float = 0.0
+    gravity_level: bool = False
+
+
+@dataclass(frozen=True)
+class LensCalibration:
+    center_x: float
+    center_y: float
+    radius: float
+    rotation_degrees: Tuple[float, float, float] = (0.0, 0.0, 0.0)
+
+
+@dataclass(frozen=True)
+class InspCalibration:
+    lenses: Tuple[LensCalibration, LensCalibration]
+    image_size: Tuple[int, int]
+    raw: Optional[str] = None
+
+    @classmethod
+    def from_string(cls, calibration: str) -> "InspCalibration":
+        values = [float(part) for part in calibration.split("_")]
+        if len(values) < 16:
+            raise ValueError("expected at least 16 values in the calibration string")
+
+        # Observed format:
+        # mode, lens0_y, lens0_x, lens0_r, lens0_rx, lens0_ry, lens0_roll,
+        #       lens1_y, lens1_x, lens1_r, lens1_rx, lens1_ry, lens1_roll,
+        #       image_width, image_height, ...
+        lens0 = LensCalibration(
+            center_x=values[2],
+            center_y=values[1],
+            radius=values[3],
+            rotation_degrees=(values[4], values[5], values[6]),
+        )
+        lens1 = LensCalibration(
+            center_x=values[8],
+            center_y=values[7],
+            radius=values[9],
+            rotation_degrees=(values[10], values[11], values[12]),
+        )
+        return cls(
+            lenses=(lens0, lens1),
+            image_size=(int(round(values[13])), int(round(values[14]))),
+            raw=calibration,
+        )
+
+    @classmethod
+    def from_image_shape(cls, image_shape: Sequence[int]) -> "InspCalibration":
+        height = int(image_shape[0])
+        width = int(image_shape[1])
+        radius = min(width / 4.0, height / 2.0)
+        return cls(
+            lenses=(
+                LensCalibration(width / 4.0, height / 2.0, radius),
+                LensCalibration(3.0 * width / 4.0, height / 2.0, radius),
+            ),
+            image_size=(width, height),
+        )
+
+
+def read_rectilinear(
+    path: Union[str, Path],
+    spherical_angle: Union[SphericalAngle, Sequence[float]],
+    hfov: float,
+    vfov: float,
+    *,
+    width: int = 1024,
+    height: Optional[int] = None,
+    fisheye_fov: float = 190.0,
+    blend_width: float = 8.0,
+    use_lens_roll: bool = False,
+    gravity_vector: Optional[Sequence[float]] = None,
+) -> np.ndarray:
+    """Read an .insp file and render a regular rectilinear view.
+
+    `spherical_angle` is `(yaw, pitch)` or `(yaw, pitch, roll)` in degrees.
+    Yaw 0 points at the left lens optical axis, yaw 180 points at the right
+    lens optical axis, and positive pitch looks upward.
+    """
+
+    path = Path(path)
+    angle, gravity_level = _angle_spec(spherical_angle)
+    if gravity_level and gravity_vector is None:
+        gravity_vector = read_gravity_vector(path)
+    if gravity_level and gravity_vector is None:
+        raise ValueError("gravity-leveling requested, but no gravity vector was found")
+
+    image = read_insp(path)
+    metadata = read_metadata(path)
+    calibration_text = None
+    if metadata.trailer is not None:
+        calibration_text = metadata.trailer.fields.get("calibration")
+
+    calibration = (
+        InspCalibration.from_string(calibration_text)
+        if isinstance(calibration_text, str)
+        else InspCalibration.from_image_shape(image.shape)
+    )
+    return render_rectilinear(
+        image,
+        calibration,
+        SphericalAngle(*angle, gravity_level=gravity_level),
+        hfov,
+        vfov,
+        width=width,
+        height=height,
+        fisheye_fov=fisheye_fov,
+        blend_width=blend_width,
+        use_lens_roll=use_lens_roll,
+        gravity_vector=gravity_vector,
+    )
+
+
+def render_rectilinear(
+    image: np.ndarray,
+    calibration: Optional[InspCalibration],
+    spherical_angle: Union[SphericalAngle, Sequence[float]],
+    hfov: float,
+    vfov: float,
+    *,
+    width: int = 1024,
+    height: Optional[int] = None,
+    fisheye_fov: float = 190.0,
+    blend_width: float = 8.0,
+    use_lens_roll: bool = False,
+    gravity_vector: Optional[Sequence[float]] = None,
+) -> np.ndarray:
+    """Render a rectilinear view from a dual-fisheye image array."""
+
+    if calibration is None:
+        calibration = InspCalibration.from_image_shape(image.shape)
+
+    angle, gravity_level = _angle_spec(spherical_angle)
+    basis = _raw_basis()
+    if gravity_level:
+        if gravity_vector is None:
+            raise ValueError("gravity_vector is required for gravity-leveled rendering")
+        basis = _gravity_leveled_basis(gravity_vector)
+
+    out_width, out_height = _output_size(width, height, hfov, vfov)
+    directions = _view_directions(
+        angle,
+        hfov,
+        vfov,
+        out_width,
+        out_height,
+        basis,
+    )
+    sampled = _sample_dual_fisheye(
+        image,
+        calibration,
+        directions,
+        fisheye_fov=fisheye_fov,
+        blend_width=blend_width,
+        use_lens_roll=use_lens_roll,
+    )
+    return _restore_dtype(sampled, image.dtype)
+
+
+def read_gravity_vector(path: Union[str, Path]) -> Optional[Tuple[float, float, float]]:
+    """Return the normalized camera-space gravity/down vector, if present.
+
+    The inspected .insp files store this in the first three underscore-separated
+    numbers of the EXIF MakerNote. The vector is returned in the same raw camera
+    coordinate system used by `render_rectilinear`.
+    """
+
+    with Image.open(path) as image:
+        maker_note = image.getexif().get_ifd(ExifTags.IFD.Exif).get(0x927C)
+    return _gravity_from_maker_note(maker_note)
+
+
+def _output_size(
+    width: int,
+    height: Optional[int],
+    hfov: float,
+    vfov: float,
+) -> Tuple[int, int]:
+    if width <= 0:
+        raise ValueError("width must be positive")
+    _validate_fov(hfov, "hfov")
+    _validate_fov(vfov, "vfov")
+
+    if height is None:
+        ratio = np.tan(np.deg2rad(vfov) / 2.0) / np.tan(np.deg2rad(hfov) / 2.0)
+        height = max(1, int(round(width * ratio)))
+    if height <= 0:
+        raise ValueError("height must be positive")
+    return int(width), int(height)
+
+
+def _validate_fov(value: float, name: str) -> None:
+    if not 0.0 < value < 180.0:
+        raise ValueError(f"{name} must be between 0 and 180 degrees")
+
+
+def _angle_spec(
+    angle: Union[SphericalAngle, Sequence[float]],
+) -> Tuple[Tuple[float, float, float], bool]:
+    if isinstance(angle, SphericalAngle):
+        return (angle.yaw, angle.pitch, angle.roll), angle.gravity_level
+    if len(angle) == 2:
+        return (float(angle[0]), float(angle[1]), 0.0), False
+    if len(angle) == 3:
+        return (float(angle[0]), float(angle[1]), float(angle[2])), False
+    raise ValueError("spherical_angle must contain yaw/pitch or yaw/pitch/roll")
+
+
+def _view_directions(
+    angle: Tuple[float, float, float],
+    hfov: float,
+    vfov: float,
+    width: int,
+    height: int,
+    basis: Tuple[np.ndarray, np.ndarray, np.ndarray],
+) -> np.ndarray:
+    yaw, pitch, roll = np.deg2rad(angle)
+    basis_right, basis_up, basis_forward = basis
+    center = (
+        np.sin(yaw) * np.cos(pitch) * basis_right
+        + np.sin(pitch) * basis_up
+        + np.cos(yaw) * np.cos(pitch) * basis_forward
+    )
+    center /= np.linalg.norm(center)
+
+    if abs(float(np.dot(center, basis_up))) > 0.999:
+        right = basis_right.copy()
+    else:
+        right = np.cross(basis_up, center)
+        right /= np.linalg.norm(right)
+    up = np.cross(center, right)
+    up /= np.linalg.norm(up)
+
+    if roll:
+        cos_roll = np.cos(roll)
+        sin_roll = np.sin(roll)
+        rolled_right = cos_roll * right + sin_roll * up
+        rolled_up = -sin_roll * right + cos_roll * up
+        right, up = rolled_right, rolled_up
+
+    xs = (
+        (np.arange(width, dtype=np.float32) + 0.5) / float(width) * 2.0 - 1.0
+    ) * np.tan(np.deg2rad(hfov) / 2.0)
+    ys = (
+        1.0 - (np.arange(height, dtype=np.float32) + 0.5) / float(height) * 2.0
+    ) * np.tan(np.deg2rad(vfov) / 2.0)
+    xx, yy = np.meshgrid(xs, ys)
+    directions = (
+        center[None, None, :]
+        + xx[:, :, None] * right[None, None, :]
+        + yy[:, :, None] * up[None, None, :]
+    )
+    directions /= np.linalg.norm(directions, axis=2, keepdims=True)
+    return directions.astype(np.float32, copy=False)
+
+
+def _raw_basis() -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    return (
+        np.array([1.0, 0.0, 0.0], dtype=np.float32),
+        np.array([0.0, 1.0, 0.0], dtype=np.float32),
+        np.array([0.0, 0.0, 1.0], dtype=np.float32),
+    )
+
+
+def _gravity_leveled_basis(
+    gravity_vector: Sequence[float],
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    gravity = _normalize_vector(np.asarray(gravity_vector, dtype=np.float32))
+    up = -gravity
+
+    for anchor in _raw_basis()[::-1]:
+        forward = anchor - float(np.dot(anchor, up)) * up
+        norm = float(np.linalg.norm(forward))
+        if norm > 1e-6:
+            forward = forward / norm
+            right = np.cross(up, forward)
+            right /= np.linalg.norm(right)
+            forward = np.cross(right, up)
+            forward /= np.linalg.norm(forward)
+            return (
+                right.astype(np.float32),
+                up.astype(np.float32),
+                forward.astype(np.float32),
+            )
+
+    raise ValueError("could not construct a gravity-leveled basis")
+
+
+def _normalize_vector(vector: np.ndarray) -> np.ndarray:
+    if vector.shape != (3,) or not np.all(np.isfinite(vector)):
+        raise ValueError("gravity vector must contain three finite numbers")
+    norm = float(np.linalg.norm(vector))
+    if norm < 1e-6:
+        raise ValueError("gravity vector is too small")
+    return vector / norm
+
+
+def _gravity_from_maker_note(
+    maker_note: object,
+) -> Optional[Tuple[float, float, float]]:
+    if not isinstance(maker_note, bytes):
+        return None
+
+    text = maker_note.split(b"\0", 1)[0].decode("ascii", "ignore")
+    try:
+        values = [float(part) for part in text.split("_")]
+    except ValueError:
+        return None
+    if len(values) < 3:
+        return None
+
+    vector = np.asarray(values[:3], dtype=np.float32)
+    if not np.all(np.isfinite(vector)):
+        return None
+    norm = float(np.linalg.norm(vector))
+    if norm < 0.25:
+        return None
+    vector = vector / norm
+    return tuple(float(value) for value in vector)
+
+
+def _sample_dual_fisheye(
+    image: np.ndarray,
+    calibration: InspCalibration,
+    directions: np.ndarray,
+    *,
+    fisheye_fov: float,
+    blend_width: float,
+    use_lens_roll: bool,
+) -> np.ndarray:
+    if image.ndim not in {2, 3}:
+        raise ValueError("image must be a 2D or 3D array")
+    if len(calibration.lenses) != 2:
+        raise ValueError("expected calibration for exactly two lenses")
+    if not 0.0 < fisheye_fov <= 360.0:
+        raise ValueError("fisheye_fov must be between 0 and 360 degrees")
+    if blend_width < 0.0:
+        raise ValueError("blend_width must be non-negative")
+
+    source = image[:, :, None] if image.ndim == 2 else image
+    coordinates = [
+        _fisheye_coordinates(
+            directions,
+            calibration.lenses[0],
+            lens_index=0,
+            fisheye_fov=fisheye_fov,
+            use_lens_roll=use_lens_roll,
+        ),
+        _fisheye_coordinates(
+            directions,
+            calibration.lenses[1],
+            lens_index=1,
+            fisheye_fov=fisheye_fov,
+            use_lens_roll=use_lens_roll,
+        ),
+    ]
+    samples = [_bilinear_sample(source, x, y, valid) for x, y, valid, _ in coordinates]
+
+    if blend_width > 0.0:
+        weights = []
+        blend = np.deg2rad(blend_width)
+        for _, _, valid, theta in coordinates:
+            half_fov = np.deg2rad(fisheye_fov) / 2.0
+            weight = np.clip((half_fov - theta) / blend, 0.0, 1.0)
+            weights.append(np.where(valid, np.maximum(weight, 1e-6), 0.0))
+        total = weights[0] + weights[1]
+        out = np.zeros_like(samples[0], dtype=np.float32)
+        has_weight = total > 0.0
+        out[has_weight] = (
+            samples[0][has_weight] * weights[0][has_weight, None]
+            + samples[1][has_weight] * weights[1][has_weight, None]
+        ) / total[has_weight, None]
+    else:
+        valid0 = coordinates[0][2]
+        valid1 = coordinates[1][2]
+        score0 = np.where(valid0, np.cos(coordinates[0][3]), -np.inf)
+        score1 = np.where(valid1, np.cos(coordinates[1][3]), -np.inf)
+        use1 = score1 > score0
+        out = np.where(use1[:, :, None], samples[1], samples[0])
+        out[~(valid0 | valid1)] = 0.0
+
+    return out[:, :, 0] if image.ndim == 2 else out
+
+
+def _fisheye_coordinates(
+    directions: np.ndarray,
+    lens: LensCalibration,
+    *,
+    lens_index: int,
+    fisheye_fov: float,
+    use_lens_roll: bool,
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    if lens_index == 0:
+        axis = np.array([0.0, 0.0, 1.0], dtype=np.float32)
+        x_axis = np.array([1.0, 0.0, 0.0], dtype=np.float32)
+    else:
+        axis = np.array([0.0, 0.0, -1.0], dtype=np.float32)
+        x_axis = np.array([-1.0, 0.0, 0.0], dtype=np.float32)
+    y_axis = np.array([0.0, -1.0, 0.0], dtype=np.float32)
+
+    local_x = np.tensordot(directions, x_axis, axes=([2], [0]))
+    local_y = np.tensordot(directions, y_axis, axes=([2], [0]))
+    local_z = np.tensordot(directions, axis, axes=([2], [0]))
+    local_z = np.clip(local_z, -1.0, 1.0)
+
+    if use_lens_roll:
+        roll = np.deg2rad(lens.rotation_degrees[2])
+        cos_roll = np.cos(roll)
+        sin_roll = np.sin(roll)
+        rolled_x = cos_roll * local_x - sin_roll * local_y
+        rolled_y = sin_roll * local_x + cos_roll * local_y
+        local_x, local_y = rolled_x, rolled_y
+
+    theta = np.arccos(local_z)
+    half_fov = np.deg2rad(fisheye_fov) / 2.0
+    sin_theta = np.sqrt(np.maximum(1.0 - local_z * local_z, 0.0))
+    radius = lens.radius * theta / half_fov
+    scale = np.divide(
+        radius,
+        sin_theta,
+        out=np.zeros_like(radius, dtype=np.float32),
+        where=sin_theta > 1e-7,
+    )
+
+    x = lens.center_x + local_x * scale
+    y = lens.center_y + local_y * scale
+    valid = theta <= half_fov + 1e-6
+    return x, y, valid, theta
+
+
+def _bilinear_sample(
+    image: np.ndarray,
+    x: np.ndarray,
+    y: np.ndarray,
+    valid: np.ndarray,
+) -> np.ndarray:
+    height, width = image.shape[:2]
+    in_bounds = (x >= 0.0) & (x <= width - 1) & (y >= 0.0) & (y <= height - 1)
+    valid = valid & in_bounds
+
+    x0 = np.floor(np.clip(x, 0, width - 1)).astype(np.int64)
+    y0 = np.floor(np.clip(y, 0, height - 1)).astype(np.int64)
+    x1 = np.clip(x0 + 1, 0, width - 1)
+    y1 = np.clip(y0 + 1, 0, height - 1)
+
+    wx = (x - x0)[:, :, None]
+    wy = (y - y0)[:, :, None]
+
+    top = image[y0, x0].astype(np.float32) * (1.0 - wx) + image[y0, x1].astype(
+        np.float32
+    ) * wx
+    bottom = image[y1, x0].astype(np.float32) * (1.0 - wx) + image[y1, x1].astype(
+        np.float32
+    ) * wx
+    out = top * (1.0 - wy) + bottom * wy
+    out[~valid] = 0.0
+    return out
+
+
+def _restore_dtype(image: np.ndarray, dtype: np.dtype) -> np.ndarray:
+    dtype = np.dtype(dtype)
+    if np.issubdtype(dtype, np.integer):
+        info = np.iinfo(dtype)
+        return np.clip(np.rint(image), info.min, info.max).astype(dtype)
+    return image.astype(dtype, copy=False)

readinsp-0.1.0.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: readinsp
+Version: 0.1.0
+Summary: Read Insta360 .insp still images into NumPy arrays
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: Pillow
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+# readinsp
+
+`readinsp` reads Insta360 `.insp` still-image files into NumPy arrays.
+
+## Usage
+
+```python
+from readinsp import read_insp, read_metadata, read_preview
+
+image = read_insp("example.insp")
+print(image.shape, image.dtype)  # (3040, 6080, 3) uint8
+
+preview = read_preview("example.insp")
+print(preview.shape)  # (960, 1920, 3)
+
+metadata = read_metadata("example.insp")
+print(metadata.width, metadata.height, metadata.preview_size)
+print(metadata.exif.get("Model"))
+print(metadata.trailer.fields.get("camera_model"))
+```
+
+## Rectilinear views
+
+`read_rectilinear` undistorts the two circular fisheye images, combines the two lenses, and renders a regular perspective view:
+
+```python
+from readinsp import read_rectilinear
+
+view = read_rectilinear(
+    "example.insp",
+    spherical_angle=(0, 0),  # yaw, pitch in degrees
+    hfov=90,
+    vfov=60,
+    width=1200,
+)
+print(view.shape)  # (693, 1200, 3)
+```
+
+Angle convention: yaw `0` points at the left fisheye lens, yaw `180` points at the right fisheye lens, and positive pitch looks up. `spherical_angle` may also include a third roll value: `(yaw, pitch, roll)`. When `height` is omitted, it is computed from the FOVs so the output has approximately square angular sampling near the view center. The default dual-fisheye model assumes a `190` degree fisheye per lens with an `8` degree blend near the stitch boundary. Both values can be overridden.
+
+Gravity leveling is available for files with a valid EXIF MakerNote gravity vector:
+
+```python
+from readinsp import SphericalAngle, read_rectilinear
+
+floor = read_rectilinear(
+    "example.insp",
+    spherical_angle=SphericalAngle(yaw=0, pitch=-90, gravity_level=True),
+    hfov=90,
+    vfov=70,
+    width=1000,
+)
+```
+
+With `gravity_level=True`, positive pitch looks opposite gravity and negative pitch looks along gravity. Yaw is still camera-relative because the inspected files do not include a usable magnetic-north heading.
+
+Install for local development from the repository root with:
+
+```bash
+python -m pip install -e readinsp
+```
+
+## Limitations
+
+This is a reverse-engineered parser based on samples from the OneR and OneRS cameras and might not work for other camera models. Rectilinear rendering is an approximate open implementation and will not match Insta360 Studio's proprietary stitching exactly, especially near the lens seam.

readinsp-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+readinsp/__init__.py,sha256=a6CkH31nD5I9E4NxDZRrdD5WiMpF_pYdgREk2Vmr_4A,796
+readinsp/core.py,sha256=3C9aQzpRSGn8ukENWQK9Igxqo1urWeo1yLGqXafU9To,11934
+readinsp/projection.py,sha256=FdLxweclVgfEMjmfGnoRiQ4vlDRCFvJBU-RnEyEehbs,15615
+readinsp-0.1.0.dist-info/METADATA,sha256=5GAXgl_dWvWwKWOTC50OxXEvUqnOLXcIqrnki-Z2SG4,2630
+readinsp-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+readinsp-0.1.0.dist-info/top_level.txt,sha256=mEXpNW4_GSc4MIqBwxcolZWTG7fVnfWxy6s-LVid_h8,9
+readinsp-0.1.0.dist-info/RECORD,,

readinsp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

readinsp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+readinsp