rpi-camera-ensemble 0.4.3__py3-none-any.whl

rpi_camera_ensemble/__init__.py

@@ -0,0 +1,22 @@
+__author__ = "Lars B. Rollik"
+
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+try:
+    __version__ = version(Path(__file__).parent.name)
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev0"
+
+
+CURRENT_API_VERSION = "v1"
+API_PREFIX = f"/api/{CURRENT_API_VERSION}"
+
+FORMAT_DATETIME_FOR_FILENAME = "%Y%m%d%H%M%S"
+
+__all__ = [
+    "API_PREFIX",
+    "CURRENT_API_VERSION",
+    "FORMAT_DATETIME_FOR_FILENAME",
+    "__version__",
+]

rpi_camera_ensemble/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.4.3'
+__version_tuple__ = version_tuple = (0, 4, 3)
+
+__commit_id__ = commit_id = None

rpi_camera_ensemble/acquisition/acquisition.py

@@ -0,0 +1,210 @@
+import logging
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+import yaml
+
+from rpi_camera_ensemble.acquisition.camera.factory import create_camera
+from rpi_camera_ensemble.config.acquisition import (
+    AcquisitionConfigsResponse,
+    # AcquisitionDebugInfo,
+    AcquisitionPaths,
+    AcquisitionSession,
+    AcquisitionSettings,
+    AcquisitionStatusResponse,
+)
+from rpi_camera_ensemble.config.camera.camera import CameraConfig
+from rpi_camera_ensemble.utils.ttl.emitter import TTLEmitter, TTLEmitterBase
+from rpi_camera_ensemble.utils.ttl.receiver import TTLReceiver, TTLReceiverBase
+
+
+class Acquisition:
+    """Acquisition manages Camera & TTL objects"""
+
+    ttl_emitter: TTLEmitter | TTLEmitterBase | None = None
+    ttl_receiver: TTLReceiver | TTLReceiverBase | None = None
+
+    def __init__(
+        self,
+        session: AcquisitionSession,
+        settings: AcquisitionSettings,
+        paths: AcquisitionPaths,
+        camera_config: CameraConfig,
+        instance_name: str | None = None,
+    ) -> None:
+        # Inputs
+        self.session: AcquisitionSession = session
+        self.settings: AcquisitionSettings = settings
+        self.paths: AcquisitionPaths = paths
+        self.camera_config: CameraConfig = camera_config
+        self.instance_name: str = instance_name or "standalone"
+        self.logger = logging.getLogger(f"Acquisition[{self.instance_name}]")
+
+        # General settings
+        # TODO: max_recording_duration_sec limit for Acquisition shutdown not implemented  # noqa: E501
+        self.max_recording_duration_sec = self.settings.max_recording_duration_sec
+
+        # Make Camera & TTL objects
+        camera_init_args: dict[str, Any] = {
+            "config": camera_config,
+            "instance_name": self.instance_name,
+        }
+
+        if self.camera_config.ttl.out_pin is not None:
+            self.ttl_emitter = TTLEmitter(
+                library=self.camera_config.ttl.library,  # FIXME: value call necessary?
+                pin=self.camera_config.ttl.out_pin,
+                duration_us=self.camera_config.ttl.out_duration_us,
+            )
+
+            # wrapper to ignore encoder args
+            def pre_encoder_callback(*args, **kwargs):
+                self.ttl_emitter.emit()
+
+            camera_init_args["pre_encoder_callback"] = pre_encoder_callback
+
+        if self.camera_config.ttl.in_pin is not None:
+            self.ttl_receiver = TTLReceiver(
+                library=self.camera_config.ttl.library,
+                pin=self.camera_config.ttl.in_pin,
+            )
+
+        # Create camera
+        self.camera = create_camera(**camera_init_args)
+        # Write camera metadata & controls after warmup
+        self.write_metadata()
+
+        # Success
+        self.logger.info("Acquisition initialized")
+
+    def start_preview(self) -> bool:
+        """Start camera preview."""
+        return self.camera.start_preview()
+
+    def start_recording(self) -> UUID:
+        """Start recording session."""
+        # start listening to TTL-in
+        if self.ttl_receiver is not None and not self.ttl_receiver.is_recording():
+            self.ttl_receiver.start_recording()
+
+        success = self.camera.start_recording(
+            video_path=self.paths.video,
+            ttl_out_path=self.paths.ttl_out,
+        )
+        if not success:
+            raise RuntimeError("Camera recording failed to start")
+
+        self.logger.info(
+            f"Recording started (session: {self.session.acquisition_uuid})"
+        )
+        return self.session.acquisition_uuid
+
+    def stop(self, acquisition_uuid: UUID | str) -> bool:
+        """Stop recording and save data."""
+        if isinstance(acquisition_uuid, str):
+            acquisition_uuid = UUID(acquisition_uuid)
+
+        # Validate session ID to protect acquisition
+        if acquisition_uuid and acquisition_uuid != self.session.acquisition_uuid:
+            self.logger.error(
+                f"Acquisition uuid mismtach "
+                f"[{acquisition_uuid} != {self.session.acquisition_uuid}]"
+            )
+            return False
+
+        if not self.camera.is_previewing and not self.camera.is_recording:
+            self.logger.warning(
+                f"Acquisition stop called but status '{self.camera.status.value}'"
+            )
+            return False
+
+        # Stop camera
+        success = self.camera.stop()
+        if not success:
+            self.logger.error("Acquisition stop failed at camera stop")
+            return False
+
+        # Save TTL timestamps and metadata
+        if self.ttl_emitter is not None:
+            self.ttl_emitter.save_events(filepath=self.paths.debug_ttl_emitter)
+        if self.ttl_receiver is not None:
+            self.ttl_receiver.stop_recording()
+            self.ttl_receiver.save_events(
+                filepath=self.paths.ttl_in,
+            )
+
+        dts = round(
+            (
+                datetime.now()
+                - self.session.acquisition_start_time.replace(tzinfo=None)
+            ).total_seconds(),
+            3,
+        )
+        # dts = round((datetime.now() - self.session.acquisition_start_time).total_seconds(), 3)  # noqa: E501
+        self.logger.info(f"Acquisition stopped [{dts}s]")
+        return True
+
+    def get_status(self) -> AcquisitionStatusResponse:
+        """Get current acquisition status."""
+        status_resp = AcquisitionStatusResponse(
+            running=True,  # as we are evidently inside Acq class
+            acquisition_uuid=self.session.acquisition_uuid,
+            instance_name=self.instance_name,
+            status=self.camera.status,
+            camera_error=self.camera.last_error or "No error",
+            # TODO: add actual framerate, or submodel for debug info,
+            #  or print total frames from ttl emitter
+            # debug_info=AcquisitionDebugInfo(actual_framerate=FPS),
+        )
+        return status_resp
+
+    def get_config(self) -> AcquisitionConfigsResponse:
+        """Get acquisition configuration for metadata."""
+        config_dict = AcquisitionConfigsResponse(
+            running=True,  # evidently
+            session=self.session,
+            settings=self.settings,
+            paths=self.paths,
+            camera_config=self.camera_config,
+            camera_controls=self.camera.get_metadata(),
+        )
+        return config_dict
+
+    def write_metadata(self) -> None:
+        """Write camera control metadata after warmup"""
+        if self.camera is not None:
+            control_metadata = self.camera.get_metadata(as_dict=True)
+            configs = self.get_config()
+            status = self.get_status().to_dict()
+
+            metadata = {
+                "timestamp_saved": datetime.now().isoformat(),
+                "camera_controls": control_metadata,
+                "configs": configs.model_dump(),
+                "status": status,
+            }
+            try:
+                with Path(self.paths.debug_acq_meta).open("w") as f:
+                    yaml.dump(
+                        data=metadata,
+                        stream=f,
+                        default_flow_style=False,
+                        sort_keys=False,
+                        allow_unicode=True,
+                    )
+            except Exception as e:
+                print(e)
+
+    def cleanup(self):
+        """Cleanup acquisition resources."""
+        if self.camera:
+            # stop TTL listening + stop recording if active
+            if self.ttl_receiver is not None and self.ttl_receiver.is_recording():
+                self.ttl_receiver.stop_recording()
+
+            self.write_metadata()
+            self.camera.cleanup()
+
+        self.logger.info("Acquisition cleanup complete")

rpi_camera_ensemble/acquisition/camera/base.py

@@ -0,0 +1,200 @@
+import logging
+import traceback
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from rpi_camera_ensemble.config.camera.camera import CameraConfig, CameraStatus
+
+
+class BaseCamera(ABC):
+    """Abstract base camera for hardware control with state machine."""
+
+    status: CameraStatus = CameraStatus.UNINITIALIZED
+    last_error: str | None = None
+
+    def __init__(
+        self, config: CameraConfig, instance_name: str | None = None, **kwargs
+    ) -> None:
+        """Initialize camera with config and optional TTL output callback.
+
+        Args:
+            config: Camera configuration (CameraConfig.get_camera_params())
+        """
+        self.config = config
+        self.instance_name = instance_name or "standalone"
+        self.logger = logging.getLogger(f"Camera[{self.instance_name}]")
+
+        try:
+            self._initialize_hardware()
+            self.status = CameraStatus.INITIALIZED
+            self.logger.info("Camera initialized successfully")
+        except Exception as e:
+            self._set_error_state(e)
+            raise
+
+    # Abstract methods for camera implementations
+    @abstractmethod
+    def _initialize_hardware(self):
+        """Initialize camera hardware and apply settings."""
+        pass
+
+    @abstractmethod
+    def _start_preview_impl(self) -> bool:
+        """Backend-specific preview start implementation."""
+        pass
+
+    @abstractmethod
+    def _start_recording_impl(
+        self,
+        video_path: str | Path,
+        ttl_out_path: str | Path | None = None,
+    ) -> bool:
+        """Backend-specific recording start implementation."""
+        pass
+
+    @abstractmethod
+    def _stop_impl(self):
+        """Backend-specific preview/recording stop implementation."""
+        pass
+
+    @abstractmethod
+    def _get_metadata_impl(self, as_dict: bool = False) -> dict:
+        """Backend-specific metadata get implementation."""
+        pass
+
+    @abstractmethod
+    def _cleanup_impl(self):
+        """Backend-specific cleanup implementation."""
+        pass
+
+    # Error handling helper
+    def _set_error_state(self, exception: Exception):
+        """Set error state and capture traceback."""
+        self.status = CameraStatus.ERROR
+        self.last_error = (
+            f"{type(exception).__name__}: {exception}\n{traceback.format_exc()}"
+        )
+        self.logger.error(f"Camera error: {exception}")
+
+    # State properties
+    @property
+    def is_initialized(self) -> bool:
+        return self.status == CameraStatus.INITIALIZED
+
+    @property
+    def is_previewing(self) -> bool:
+        return self.status == CameraStatus.PREVIEWING
+
+    @property
+    def is_recording(self) -> bool:
+        return self.status == CameraStatus.RECORDING
+
+    @property
+    def is_stopped(self) -> bool:
+        return self.status == CameraStatus.STOPPED
+
+    @property
+    def is_error(self) -> bool:
+        return self.status == CameraStatus.ERROR
+
+    # Public interface methods
+    def start_preview(self) -> bool:
+        """Start camera preview."""
+        if self.status not in [CameraStatus.INITIALIZED, CameraStatus.STOPPED]:
+            self.logger.warning(f"Cannot start preview from state: {self.status}")
+            return False
+
+        try:
+            success = self._start_preview_impl()
+            if success:
+                # Start streaming if configured
+                if getattr(self.config, "stream", None) and getattr(
+                    self.config.stream, "enabled", False
+                ):
+                    self._start_preview_impl()
+                self.status = CameraStatus.PREVIEWING
+                self.logger.info("Preview started")
+            return success
+        except Exception as e:
+            self._set_error_state(e)
+            return False
+
+    def start_recording(
+        self,
+        video_path: Path,
+        ttl_out_path: str | Path | None = None,
+    ) -> bool:
+        """Start video recording."""
+        if self.status not in [
+            CameraStatus.INITIALIZED,
+            CameraStatus.PREVIEWING,
+            CameraStatus.STOPPED,
+        ]:
+            self.logger.warning(f"Cannot start recording from state: {self.status}")
+            return False
+
+        try:
+            # if not already previewing, then start preview as well
+            if self.status != CameraStatus.PREVIEWING:
+                self._start_preview_impl()
+
+            success = self._start_recording_impl(
+                video_path=video_path,
+                ttl_out_path=ttl_out_path,
+            )
+            if success:
+                # Start streaming if configured and not already active
+                if (
+                    getattr(self.config, "stream", None)
+                    and getattr(self.config.stream, "enabled", False)
+                    and self.status != CameraStatus.PREVIEWING
+                ):
+                    self._start_preview_impl()
+
+                self.status = CameraStatus.RECORDING
+                self.logger.info(f"Recording started: {video_path}")
+            return success
+        except Exception as e:
+            self._set_error_state(e)
+            return False
+
+    def stop(self) -> bool:
+        """Stop video recording."""
+        if self.status not in [CameraStatus.PREVIEWING, CameraStatus.RECORDING]:
+            self.logger.warning(f"Cannot stop recording from state: {self.status}")
+            return False
+
+        try:
+            self._stop_impl()
+            self.status = CameraStatus.STOPPED
+            self.logger.info("Recording stopped")
+            return True
+        except Exception as e:
+            self._set_error_state(e)
+            return False
+
+    def get_metadata(self, as_dict: bool = False) -> dict:
+        try:
+            return self._get_metadata_impl(as_dict=as_dict)
+        except Exception as e:
+            self._set_error_state(e)
+            return {}
+
+    def cleanup(self):
+        """Cleanup camera resources."""
+        try:
+            if self.is_previewing or self.is_recording:
+                self.stop()
+
+            self._cleanup_impl()
+            self.status = CameraStatus.STOPPED
+            self.logger.info("Camera cleanup complete")
+        except Exception as e:
+            self._set_error_state(e)
+
+    # Context manager
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.cleanup()

rpi_camera_ensemble/acquisition/camera/factory.py

@@ -0,0 +1,57 @@
+import logging
+
+from rpi_camera_ensemble.acquisition.camera.base import BaseCamera
+from rpi_camera_ensemble.config.camera.camera import CameraBackend, CameraConfig
+
+
+class CameraFactory:
+    """Factory for creating camera instances with explicit backend selection."""
+
+    _logger = logging.getLogger("CameraFactory")
+
+    @classmethod
+    def get_backend_class(cls, backend: CameraBackend) -> type[BaseCamera]:
+        """Get camera implementation class for backend."""
+        if backend == CameraBackend.PICAMERA2:
+            from rpi_camera_ensemble.acquisition.camera.picamera2_impl import (
+                Picamera2Impl,
+            )
+
+            return Picamera2Impl
+        # NOTE: other backends go here
+        # elif backend == CameraBackend.PICAMERA:
+        #     from .picamera_impl import PiCameraImpl
+        #     return PiCameraImpl
+        else:
+            raise ValueError(f"Unknown backend: {backend}")
+
+    @classmethod
+    def create_camera(cls, config: CameraConfig, **kwargs) -> BaseCamera:
+        """Create camera instance based on explicit backend config."""
+        backend = config.backend
+        cls._logger.info(f"Creating camera with backend: {backend.value}")
+
+        try:
+            camera_class = cls.get_backend_class(backend)
+            camera = camera_class(config, **kwargs)
+            cls._logger.info(f"Camera created: {camera.__class__.__name__}")
+            return camera
+        except ImportError as e:
+            raise RuntimeError(f"Backend {backend.value} not available: {e}") from e
+        except Exception as e:
+            cls._logger.error(f"Failed to create camera: {e}")
+            raise
+
+    @classmethod
+    def is_backend_available(cls, backend: CameraBackend) -> bool:
+        """Check if backend is available."""
+        try:
+            cls.get_backend_class(backend)
+            return True
+        except ImportError:
+            return False
+
+
+def create_camera(config: CameraConfig, **kwargs) -> BaseCamera:
+    """Convenience function to create camera."""
+    return CameraFactory.create_camera(config, **kwargs)

rpi_camera_ensemble/acquisition/camera/picamera2_encoder.py

@@ -0,0 +1,133 @@
+import logging
+import time
+from collections.abc import Callable
+from pathlib import Path
+
+import numpy as np
+
+try:
+    from picamera2.encoders import H264Encoder
+except ImportError as _err:
+    raise ImportError(
+        "picamera2 is required for TimestampH264Encoder. "
+        "Please install it via 'pip install picamera2'."
+    ) from _err
+
+from rpi_camera_ensemble.config.camera.picamera2_impl import Picamera2VideoEncoder
+
+
+class TimestampH264Encoder(H264Encoder):
+    """Timestamp-capturing encoder based on H264Encoder"""
+
+    def __init__(
+        self,
+        *args,
+        pre_encode_callback: Callable | None = None,
+        timestamp_save_path: str | Path | None = None,
+        instance_name: str = "",
+        max_frames: int = 2_000_000,
+        **kwargs,
+    ):
+        super().__init__(*args, **kwargs)
+        # inputs
+        self.pre_encode_callback: Callable | None = pre_encode_callback
+        self.timestamp_save_path = timestamp_save_path
+        self.instance_name = instance_name or "standalone"
+        assert isinstance(max_frames, int)
+        self.max_frames = max_frames
+
+        # vars
+        self.frame_count = 0
+        # Pre-allocate for 2 hours at 120Hz + 10% buffer
+        self.timestamps = np.zeros((self.max_frames, 2), dtype=np.int64)
+        self.timestamps.fill(-1)
+        self.logger = logging.getLogger(
+            f"{self.__class__.__name__}[{self.instance_name}]"
+        )
+
+    # def set_callback(self, callback: Callable):
+    #     """Set the pre-encode callback."""
+    #     self.pre_encode_callback = callback
+
+    def encode(self, stream, request):
+        """
+        Override picamera2 base encoder's `encode` method
+        with timestamp capture logic.
+        """
+        # 1) Call callback with encode signature
+        if self.pre_encode_callback:
+            self.pre_encode_callback(self, stream, request)
+
+        # 2) Store timestamps
+        self._store_timestamp(request)
+
+        # 3) Call super class encode
+        return super().encode(stream, request)
+
+    def _store_timestamp(self, request):
+        """Helper method to store timestamps in numpy array."""
+        if self.frame_count < len(self.timestamps):
+            sensor_ts = request.get_metadata().get("SensorTimestamp", -1)
+            monotonic_ts = time.monotonic_ns()
+
+            self.timestamps[self.frame_count, 0] = sensor_ts
+            self.timestamps[self.frame_count, 1] = monotonic_ts
+            self.frame_count += 1
+
+    def get_timestamps(self):
+        """Return captured timestamps, trimmed to actual count."""
+        return self.timestamps[: self.frame_count, :]
+
+    def save_timestamps(self, path: str | None = None):
+        """Save timestamps to numpy file."""
+        save_path = path or self.timestamp_save_path
+        if save_path:
+            ts = self.get_timestamps()
+            np.savez(
+                save_path,
+                sensor_ts=ts[:, 0],
+                monotonic_ts=ts[:, 1],
+            )
+            self.logger.info(
+                f"Saved frame timestamps to '{str(save_path)}' [frames = {ts.shape[0]}]"
+            )
+
+    def __del__(self):
+        """Auto-save timestamps on destruction if path provided."""
+        if self.timestamp_save_path:
+            self.save_timestamps()
+
+
+class EncoderFactory:
+    """Factory for creating timestamp-capturing encoders."""
+
+    @staticmethod
+    def create(
+        encoder: Picamera2VideoEncoder = Picamera2VideoEncoder.H264_TTL,
+        pre_encode_callback: Callable | None = None,
+        timestamp_save_path: str | Path | None = None,
+        *args,
+        **kwargs,
+    ):
+        """
+        Create TSEncoder subclass of the given encoder.
+
+        Args:
+            encoder: Encoder class to subclass (default: Picamera2VideoEncoder.H264)
+            pre_encode_callback: Callback called before each encode
+            timestamp_save_path: Path to save timestamps on exit
+            *args, **kwargs: Arguments for encoder constructor
+        """
+        if encoder == Picamera2VideoEncoder.H264_TTL:
+            ts_encoder = TimestampH264Encoder(
+                *args,
+                pre_encode_callback=pre_encode_callback,
+                timestamp_save_path=timestamp_save_path,
+                **kwargs,
+            )
+
+            return ts_encoder
+        else:
+            raise NotImplementedError(
+                "Only TimestampH264Encoder is currently supported."
+            )