openflexure_microscope_server.things.camera.picamera.StreamingPiCamera2

class documentation

class StreamingPiCamera2(BaseCamera, ABC): (source)

Known subclasses: openflexure_microscope_server.things.camera.picamera.PiCameraHQ, openflexure_microscope_server.things.camera.picamera.PiCameraV2

Constructor: StreamingPiCamera2(thing_server_interface, camera_num)

View In Hierarchy

A Thing that provides and interface to the Raspberry Pi Camera.

This is an abstract base class for all picamera models. Use a subclass specific to the camera model.

Method __enter__ Start streaming when the Thing context manager is opened.
Method __exit__ Close the picamera connection when the Thing context manager is closed.
Method __init__ Initialise the camera with the given camera number.
Method analogue_gain The Analogue gain applied by the camera sensor.
Method analogue_gain.setter Undocumented
Method auto_expose_from_minimum Adjust exposure until a the target white level is reached.
Method calibrate_lens_shading Take an image and use it for flat-field correction.
Method capture_as_array Acquire one image from the camera and return as an array.
Method colour_correction_matrix.setter Undocumented
Method colour_gains The red and blue colour gains, must be between 0.0 and 32.0.
Method colour_gains.setter Undocumented
Method discard_frames Discard frames so that the next frame captured is fresh.
Method exposure_time The camera exposure time in microseconds.
Method exposure_time.setter Undocumented
Method flat_lens_shading Disable flat-field correction.
Method flat_lens_shading_chrominance Disable flat-field correction for colour only.
Method full_auto_calibrate Perform a full auto-calibration.
Method reset_ccm Overwrite the colour correction matrix in camera tuning with default values.
Method reset_lens_shading Revert to default lens shading settings.
Method save_settings Override save_settings to ensure that camera properties don't recurse.
Method set_ce_enable_to_off Set the contrast enhancement to disabled.
Method set_static_green_equalisation Set the green equalisation to a static value.
Class Variable mjpeg_bitrate Bitrate for MJPEG stream (None for default).
Class Variable supports_focus_fom Undocumented
Instance Variable default_tuning Undocumented
Instance Variable stream_active Whether the MJPEG stream is active.
Instance Variable streaming_mode Undocumented
Instance Variable tuning The Raspberry PiCamera Tuning File JSON.
Property calibration_required Whether the camera needs calibrating.
Property camera_configuration The "configuration" dictionary of the picamera2 object.
Property capture_metadata Return the metadata from the camera.
Property capture_modes Modes the camera can use for capturing.
Property colour_correction_matrix The colour_correction_matrix from the tuning file.
Property focus_fom Return the focus figure of merit.
Property gamma_correction Return the gamma correction curve from the tuning file.
Property lens_shading_tables The current lens shading (i.e. flat-field correction).
Property manual_camera_settings The camera settings to expose as property controls in the settings panel.
Property primary_calibration_actions The calibration actions for both calibration wizard and settings panel.
Property secondary_calibration_actions The calibration actions that appear only in settings panel.
Property sensor_resolution The native resolution of the camera's sensor.
Property streaming True if the camera is streaming.
Property streaming_modes Modes the camera can stream in.
Property thing_state Update generic camera metadata with Picamera-specific data.
Method _capture_image Acquire one image from the camera and return it as a PIL Image.
Method _create_picam_config_from_mode_info Create the dictionary to pass to Picamera2.configure.
Method _ensure_mode_for_capture Ensure in correct mode for capture.
Method _get_persistent_controls Undocumented
Method _initialise_picamera Acquire the picamera device and store it as self._picamera.
Method _on_frame_complete Undocumented
Method _start_streaming Start the MJPEG stream. This is where persistent controls are sent to camera.
Method _stop_streaming Stop the MJPEG stream.
Method _streaming_picamera Lock access to picamera and return the underlying Picamera2 instance.
Class Variable _camera_board Undocumented
Class Variable _sensor_info Undocumented
Instance Variable _analogue_gain Undocumented
Instance Variable _camera_num Undocumented
Instance Variable _colour_gains Undocumented
Instance Variable _exposure_time Undocumented
Instance Variable _focus_fom Undocumented
Instance Variable _picamera Undocumented
Instance Variable _picamera_lock Undocumented
Instance Variable _setting_save_in_progress Undocumented

Inherited from BaseCamera:

Method background_detector_name The name of the active background selector.
Method background_detector_name.setter Validate and set background_detector_name.
Method capture Acquire one image from the camera.
Method capture_and_save_to_path Capture an image and save it to disk.
Method capture_downsampled_array Acquire one image from the camera, downsample, and return as an array.
Method capture_to_memory Capture an image to memory. This can be saved later with save_from_memory.
Method change_streaming_mode Change the mode the camera is streaming in.
Method clear_buffers Clear all images in memory.
Method grab_as_array Acquire one image from the preview stream and return as an array.
Method grab_jpeg Acquire one image from the preview stream and return as blob of JPEG data.
Method grab_jpeg_size Acquire one image from the preview stream and return its size.
Method image_is_sample Label the current image as either background or sample.
Method kill_mjpeg_streams Kill the streams now as the server is shutting down.
Method record_framerate Record MJPEG stream framerate statistics.
Method save_from_memory Save an image that has been captured to memory.
Method set_background Grab an image, and use its statistics to set the background.
Method settle Sleep for the settling time, ready to provide a fresh frame.
Async Method snapshot Return a snapshot from the microscope.
Class Variable downsampled_array_factor The downsampling factor when calling capture_downsampled_array.
Class Variable lores_mjpeg_stream Undocumented
Class Variable mjpeg_stream Undocumented
Class Variable settling_time The settling time when calling the settle() method.
Class Variable supported_image_formats Undocumented
Property background_detector The active background detector instance.
Method _add_metadata_to_capture Add the EXIF metadata for a JPEG image.
Method _collect_ofm_metadata Return the metadata for a capture.
Async Method _monitor_framerate Asynchronously monitor the timing on incoming frames.
Method _validate_capture_mode Check input capture mode exists, always returns a valid mode.
Class Variable _all_background_detectors Undocumented
Class Variable _class_settings Undocumented
Class Variable _memory_buffer Undocumented
Instance Variable _background_detector_name Undocumented
Instance Variable _default_background_detector Undocumented
Instance Variable _framerate_monitor_running Undocumented

Inherited from OFMThing (via BaseCamera):

Method create_data_path Create a RelativeDataPath object with this Thing set as the saving Thing.
Property data_dir The data directory for this thing.
Property show_data_in_gallery Whether to show in the Gallery.
Class Variable _show_data_in_gallery Undocumented
Instance Variable _data_dir Undocumented
def __enter__(self) -> Self: (source)
overrides openflexure_microscope_server.things.camera.BaseCamera.__enter__

Start streaming when the Thing context manager is opened.

This opens the picamera connection, initialises the camera, sets the property, and then starts the streams.

def __exit__(self, exc_type: type[BaseException], exc_value: BaseException | None, traceback: TracebackType | None): (source)
overrides openflexure_microscope_server.things.camera.BaseCamera.__exit__

Close the picamera connection when the Thing context manager is closed.

def __init__(self, thing_server_interface: lt.ThingServerInterface, camera_num: int = 0): (source)
overrides openflexure_microscope_server.things.camera.BaseCamera.__init__

Initialise the camera with the given camera number.

This makes no connection to the camera (except to get the default tuning file).

Parameters
thing_server_interface:lt.ThingServerInterfaceThe interface between this Thing and the server.
camera_num:intThe number of the camera. This should generally be left as 0 as most Raspberry Pi boards only support 1 camera.
@lt.setting
def analogue_gain(self) -> float: (source)

The Analogue gain applied by the camera sensor.

def analogue_gain(self, value: float): (source)

Undocumented

@lt.action
def auto_expose_from_minimum(self, target_white_level: int | None = None, percentile: float = 99.9): (source)

Adjust exposure until a the target white level is reached.

Starting from the minimum exposure, gradually increase exposure until the image reaches the specified white level.

Parameters
target_white_level:int | NoneRaw target white level, this should be an integer within the range set by the bit-depth of the camera sensor (10-bit for PiCamera v2, 12 Bit for Picamera HQ. If None the default will be used for the current sensor. This is approximately 40% saturated, but after gamma curve is applied, the pixel values will have a value around 200.
percentile:floatThe percentile to use instead of maximum. Default 99.9. When calculating the brightest pixel, a percentile is used rather than the maximum in order to be robust to a small number of noisy/bright pixels.
@lt.action
def calibrate_lens_shading(self): (source)

Take an image and use it for flat-field correction.

This method requires an empty (i.e. bright) field of view. It will take a raw image and effectively divide every subsequent image by the current one. This uses the camera's "tuning" file to correct the preview and the processed images. It should not affect raw images.

@lt.action
def capture_as_array(self, capture_mode: str = 'standard', raw: bool = False) -> NDArray: (source)
overrides openflexure_microscope_server.things.camera.BaseCamera.capture_as_array

Acquire one image from the camera and return as an array.

This function will produce a nested list containing an uncompressed RGB image. It's likely to be highly inefficient - raw and/or uncompressed captures using binary image formats will be added in due course.

Parameters
capture_mode:str(Optional) The name of the capture mode as defined by the camera.
raw:boolWhether to capture RAW data. Capturing RAW data may ignore some of the camera mode settings.
Returns
NDArrayUndocumented
Raises
TimeoutErrorif this time is exceeded during capture.
def colour_correction_matrix(self, value: tuple[float, float, float, float, float, float, float, float, float]): (source)

Undocumented

@lt.setting
def colour_gains(self) -> tuple[float, float]: (source)

The red and blue colour gains, must be between 0.0 and 32.0.

def colour_gains(self, value: tuple[float, float]): (source)

Undocumented

@lt.action
def discard_frames(self): (source)
overrides openflexure_microscope_server.things.camera.BaseCamera.discard_frames

Discard frames so that the next frame captured is fresh.

@lt.setting
def exposure_time(self) -> int: (source)

The camera exposure time in microseconds.

When setting this property the camera will adjust the set value to the nearest allowed value that is lower than the current setting.

def exposure_time(self, value: int): (source)

Undocumented

@lt.action
def flat_lens_shading(self): (source)

Disable flat-field correction.

This method will set a completely flat lens shading table. It is not the same as the default behaviour, which is to use an adaptive lens shading table.

This flat table is used to take an image with no lens shading so that the correct lens shading table can be calibrated.

@lt.action
def flat_lens_shading_chrominance(self): (source)

Disable flat-field correction for colour only.

This method will set the chrominance of the lens shading table to be flat, i.e. we'll correct vignetting of intensity, but not any change in colour across the image.

@lt.action
def full_auto_calibrate(self): (source)

Perform a full auto-calibration.

This function will call the other calibration actions in sequence:

  • flat_lens_shading to disable flat-field
  • auto_expose_from_minimum
  • set_static_green_equalisation to set geq offset to max
  • calibrate_lens_shading (also sets colour gains for white balance)
  • set_background
@lt.action
def reset_ccm(self): (source)

Overwrite the colour correction matrix in camera tuning with default values.

@lt.action
def reset_lens_shading(self): (source)

Revert to default lens shading settings.

This method will restore the default "adaptive" lens shading method used by the Raspberry Pi camera.

def save_settings(self): (source)

Override save_settings to ensure that camera properties don't recurse.

This method is run by any Thing when a setting is saved. However, the method reads the setting. As reading the setting talks to the camera and calls save_settings if the value is not as expected, this could cause recursion. Also this means that saving one setting causes all others to be read each time.

@lt.action
def set_ce_enable_to_off(self): (source)

Set the contrast enhancement to disabled.

Adaptive contrast enhancement modifies settings to adapt to each field of view, causing inconsistent settings when capturing.

@lt.action
def set_static_green_equalisation(self, offset: int = 65535): (source)

Set the green equalisation to a static value.

Green equalisation avoids the debayering algorithm becoming confused by the two green channels having different values, which is a problem when the chief ray angle isn't what the sensor was designed for, and that's the case in e.g. a microscope using camera module v2.

A value of 0 here does nothing, a value of 65535 is maximum correction.

mjpeg_bitrate: int | None = (source)

Bitrate for MJPEG stream (None for default).

supports_focus_fom: bool = (source)
overrides openflexure_microscope_server.things.camera.BaseCamera.supports_focus_fom

Undocumented

default_tuning = (source)

Undocumented

stream_active: bool = (source)
overrides openflexure_microscope_server.things.camera.BaseCamera.stream_active

Whether the MJPEG stream is active.

streaming_mode = (source)
overrides openflexure_microscope_server.things.camera.BaseCamera.streaming_mode

Undocumented

tuning: dict = (source)

The Raspberry PiCamera Tuning File JSON.

@lt.property
calibration_required: bool = (source)
overrides openflexure_microscope_server.things.camera.BaseCamera.calibration_required

Whether the camera needs calibrating.

@lt.property
camera_configuration: Mapping = (source)

The "configuration" dictionary of the picamera2 object.

The "configuration" sets the resolution and format of the camera's streams. Together with the "tuning" it determines how the sensor is configured and how the data is processed.

Note that the configuration may be modified when taking still images, and this property refers to whatever configuration is currently in force - usually the one used for the preview stream.

@lt.property
capture_metadata: dict = (source)

Return the metadata from the camera.

@abstractmethod
@lt.property
capture_modes: Mapping[str, PiCamera2CaptureMode] = (source)
overrides openflexure_microscope_server.things.camera.BaseCamera.capture_modes
overridden in openflexure_microscope_server.things.camera.picamera.PiCameraHQ, openflexure_microscope_server.things.camera.picamera.PiCameraV2

Modes the camera can use for capturing.

@lt.property
colour_correction_matrix: tuple[float, float, float, float, float, float, float, float, float] = (source)

The colour_correction_matrix from the tuning file.

This is broken out into its own property for convenience and compatibility with the micromanager API

It is a 9 value tuple used to specify the 3x3 matrix that the GPU pipeline uses to convert from the camera R,G,B vector to the standard R,G,B.

@property
focus_fom: int = (source)
overrides openflexure_microscope_server.things.camera.BaseCamera.focus_fom

Return the focus figure of merit.

@lt.property
gamma_correction: list[int] = (source)

Return the gamma correction curve from the tuning file.

@lt.property
lens_shading_tables: tf_utils.LensShadingModel | None = (source)

The current lens shading (i.e. flat-field correction).

Return the current lens shading correction, as three 2D lists each with dimensions 16x12.

The colour temperature is returned. If the colour temperature us 5000 then this means the lens shading tables have been calibrated (with our illumination which has a 5000k colour temperature). Other numbers are set when flatening or resetting the table.

@lt.property
manual_camera_settings: list[PropertyControl] = (source)
overrides openflexure_microscope_server.things.camera.BaseCamera.manual_camera_settings

The camera settings to expose as property controls in the settings panel.

@lt.property
primary_calibration_actions: list[ActionButton] = (source)
overrides openflexure_microscope_server.things.camera.BaseCamera.primary_calibration_actions

The calibration actions for both calibration wizard and settings panel.

@lt.property
secondary_calibration_actions: list[ActionButton] = (source)
overrides openflexure_microscope_server.things.camera.BaseCamera.secondary_calibration_actions

The calibration actions that appear only in settings panel.

@lt.property
sensor_resolution: tuple[int, int] | None = (source)

The native resolution of the camera's sensor.

@property
streaming: bool = (source)

True if the camera is streaming.

@abstractmethod
@lt.property
streaming_modes: Mapping[str, PiCamera2StreamingMode] = (source)
overrides openflexure_microscope_server.things.camera.BaseCamera.streaming_modes
overridden in openflexure_microscope_server.things.camera.picamera.PiCameraHQ, openflexure_microscope_server.things.camera.picamera.PiCameraV2

Modes the camera can stream in.

@property
thing_state: Mapping[str, Any] = (source)
overrides openflexure_microscope_server.things.camera.BaseCamera.thing_state

Update generic camera metadata with Picamera-specific data.

def _capture_image(self, capture_mode: str = 'standard') -> Image.Image: (source)
overrides openflexure_microscope_server.things.camera.BaseCamera._capture_image

Acquire one image from the camera and return it as a PIL Image.

Parameters
capture_mode:strThe capture mode to use. See the description field of each mode in capture_modes for more detail.
Returns
Image.ImageUndocumented
Raises
TimeoutErrorif this time is exceeded during capture.
def _create_picam_config_from_mode_info(self, picam: Picamera2, controls: dict[str, Any], mode_info: PiCamera2StreamingMode) -> dict[str, Any]: (source)

Create the dictionary to pass to Picamera2.configure.

Parameters
picam:Picamera2Undocumented
controls:dict[str, Any]The controls for the camera. Note that running _get_persistent_controls() should be done before getting the picamera lock to ensure that the current settings are read from the camera.
mode_info:PiCamera2StreamingModeUndocumented
Returns
dict[str, Any]Undocumented
@contextmanager
def _ensure_mode_for_capture(self, capture_mode_info: PiCamera2CaptureMode) -> Iterator[Picamera2]: (source)

Ensure in correct mode for capture.

If the camera is already in the correct mode, the stream isn't paused and this is the same as using self._streaming_picamera().

Otherwise, pause stream, and switch mode. Mode is reset and stream restarts after the context manager closes.

def _get_persistent_controls(self) -> dict: (source)

Undocumented

def _initialise_picamera(self, check_sensor_model: bool = False): (source)

Acquire the picamera device and store it as self._picamera.

This duplicates logic in Picamera2.__init__ to provide a tuning file that will be read when the camera system initialises.

Parameters
check_sensor_model:boolSet to true to check the sensor model is the expected sensor model. This is used on __enter__ to confirm that the real camera matches the expected camera.
Raises
PicameraModelErrorIf check_sensor_model is True and the real camera sensor model doesn't match the expected sensor model.
def _on_frame_complete(self, request: Request): (source)

Undocumented

def _start_streaming(self, mode: str = 'default'): (source)
overrides openflexure_microscope_server.things.camera.BaseCamera._start_streaming

Start the MJPEG stream. This is where persistent controls are sent to camera.

Sets the camera stream resoltuons based on input mode

Create two streams:

  • lores_mjpeg_stream for autofocus at lores_resolution
  • mjpeg_stream for preview. This is at the main_resolution unless
    use_lores_as_preview is True, in which case it is a copy of lores_mjpeg_stream
def _stop_streaming(self, stop_web_stream: bool = True): (source)

Stop the MJPEG stream.

@contextmanager
def _streaming_picamera(self, pause_stream: bool = False) -> Iterator[Picamera2]: (source)

Lock access to picamera and return the underlying Picamera2 instance.

Optionally the stream can be paused to allow updating the camera settings.

Parameters
pause_stream:bool

If False the Picamera2 instance is simply yielded. If True:

  • Stop the MJPEG Stream
  • Yield the Picamera2 instance for function calling the context manager to
    make changes.
  • On closing of the context manager the stream will restart.
Returns
Iterator[Picamera2]Undocumented
_camera_board: str = (source)
overridden in openflexure_microscope_server.things.camera.picamera.PiCameraHQ, openflexure_microscope_server.things.camera.picamera.PiCameraV2

Undocumented

_sensor_info: recalibrate_utils.SensorInfo = (source)

Undocumented

_analogue_gain: float = (source)

Undocumented

_camera_num = (source)

Undocumented

_colour_gains: tuple[float, float] = (source)

Undocumented

_exposure_time: int = (source)

Undocumented

_focus_fom: int = (source)

Undocumented

_picamera = (source)

Undocumented

_picamera_lock = (source)

Undocumented

_setting_save_in_progress: bool = (source)

Undocumented