Skip to content

Camera

Camera 

Camera(path: str | Path, use_photogrammetry: bool = False)

Camera sensor for video files and image sequences.

Supports three operating modes: 1. Photogrammetry mode: Loads pre-processed photogrammetry results from CSV 2. Sony RX0 MarkII mode: Extracts IMU telemetry from .mp4 files and computes orientation 3. Alvium industrial camera mode: Reads timestamp and frame number from log files

The camera data is stored as a tuple (DataFrame, model_string) in the data attribute after calling load_data().

Attributes:

Name Type Description
path Path

Path to video file, image directory, or photogrammetry CSV.
use_photogrammetry bool

Whether to use photogrammetry mode.
data tuple[DataFrame, str | None]

Camera data as (DataFrame, camera_model). Set by load_data(). camera_model is "sony", "alvium", or None for photogrammetry.
logpath (Path, optional)

Path to log file for timestamp extraction (set during load_data).

Examples:

>>> # Load Sony camera with IMU telemetry
>>> camera = Camera("/path/to/camera/folder")
>>> camera.load_data()
>>> df, model = camera.data
>>> print(model)  # "sony"
>>> print(df.columns)  # ['timestamp', 'gyro_x', 'gyro_y', 'gyro_z', ...]
>>>
>>> # Load photogrammetry results
>>> camera = Camera("/path/to/results.csv", use_photogrammetry=True)
>>> camera.load_data()
>>> df, model = camera.data
>>> print(model)  # None
>>> print(df.columns)  # ['timestamp', 'pitch', 'roll', 'yaw']

Initialize Camera sensor.

Parameters:

Name Type Description Default
path str | Path

Path to camera data. For Sony/Alvium cameras, this is a directory containing .mp4 files or .log files. For photogrammetry mode, this is the path to a CSV file with processed results.

 required
use_photogrammetry bool

If True, loads photogrammetry CSV. If False, auto-detects Sony or Alvium camera based on files in directory.

 False

Examples:

>>> camera = Camera("/path/to/camera/folder")
>>> camera = Camera("/path/to/photogrammetry.csv", use_photogrammetry=True)
Source code in pils/sensors/camera.py 
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
def __init__(self, path: str | Path, use_photogrammetry: bool = False) -> None:
    """Initialize Camera sensor.

    Parameters
    ----------
    path : str | Path
        Path to camera data. For Sony/Alvium cameras, this is a directory
        containing .mp4 files or .log files. For photogrammetry mode,
        this is the path to a CSV file with processed results.
    use_photogrammetry : bool, default False
        If True, loads photogrammetry CSV. If False, auto-detects Sony
        or Alvium camera based on files in directory.

    Examples
    --------
    >>> camera = Camera("/path/to/camera/folder")
    >>> camera = Camera("/path/to/photogrammetry.csv", use_photogrammetry=True)
    """
    self.path = Path(path)
    self.use_photogrammetry = use_photogrammetry

load_data 

load_data() -> None

Load camera data and store in self.data attribute.

Automatically detects camera type and loads appropriate data:

Photogrammetry mode (use_photogrammetry=True): Loads CSV file with columns: timestamp, pitch, roll, yaw Sets self.data = (DataFrame, None)

Sony RX0 MarkII mode (.mp4 files found): Extracts IMU telemetry from video, computes orientation using AHRS Requires .log file in parent directory with start timestamp Sets self.data = (DataFrame, "sony") DataFrame columns: timestamp, gyro_x/y/z, accel_x/y/z, roll, pitch, yaw, qw/qx/qy/qz

Alvium industrial camera mode (no .mp4, .log file found): Reads log file for frame timestamps and numbers Sets self.data = (DataFrame, "alvium") DataFrame columns: timestamp, frame_num

Raises:

Type Description
FileNotFoundError

If the camera data path does not exist or no valid files are found.

Examples:

>>> camera = Camera("/path/to/sony/folder")
>>> camera.load_data()
>>> df, model = camera.data
>>> print(model)  # "sony"
>>> df.select(['timestamp', 'pitch', 'roll', 'yaw'])
Source code in pils/sensors/camera.py 
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
def load_data(self) -> None:
    """Load camera data and store in self.data attribute.

    Automatically detects camera type and loads appropriate data:

    **Photogrammetry mode** (use_photogrammetry=True):
        Loads CSV file with columns: timestamp, pitch, roll, yaw
        Sets self.data = (DataFrame, None)

    **Sony RX0 MarkII mode** (.mp4 files found):
        Extracts IMU telemetry from video, computes orientation using AHRS
        Requires .log file in parent directory with start timestamp
        Sets self.data = (DataFrame, "sony")
        DataFrame columns: timestamp, gyro_x/y/z, accel_x/y/z, roll, pitch, yaw, qw/qx/qy/qz

    **Alvium industrial camera mode** (no .mp4, .log file found):
        Reads log file for frame timestamps and numbers
        Sets self.data = (DataFrame, "alvium")
        DataFrame columns: timestamp, frame_num

    Raises
    ------
    FileNotFoundError
        If the camera data path does not exist or no valid files are found.

    Examples
    --------
    >>> camera = Camera("/path/to/sony/folder")
    >>> camera.load_data()
    >>> df, model = camera.data
    >>> print(model)  # "sony"
    >>> df.select(['timestamp', 'pitch', 'roll', 'yaw'])
    """
    if not self.path.exists():
        raise FileNotFoundError(f"Camera data path does not exist: {self.path}")

    if self.use_photogrammetry:
        camera_data, camera_model = self._load_photogrammetry_data()
    else:
        video_files = list(self.path.glob("*.[Mm][Pp]4"))

        if len(video_files) > 0:
            camera_data, camera_model = self._load_sony_camera_data(video_files)
        else:
            camera_data, camera_model = self._load_alvium_camera_data()

    self.data = (camera_data, camera_model)