camera.cv

camera.cv#

Description#

Plugin to control generic cameras over OpenCV.

param device:

Device ID (0 for the first camera, 1 for the second etc.) or path (e.g. /dev/video0).

param kwargs:

Extra arguments to be passed up to CameraPlugin.

Configuration#

camera.cv:
  # [Optional]
  # Color transformation to apply to the captured frames. See
  # https://docs.opencv.org/3.2.0/d7/d1b/group__imgproc__misc.html for a full list of supported color
  # transformations (default: "``COLOR_RGB2BGR``")
  # color_transform: COLOR_BGR2RGB  # type=Optional[str]

  # [Optional]
  # Default video type to use when exporting captured frames to camera (default: 0, infers the
  # type from the video file extension). See
  # `here <https://docs.opencv.org/4.0.1/dd/d9e/classcv_1_1VideoWriter.html#afec93f94dc6c0b3e28f4dd153bc5a7f0>`_
  # for a reference on the supported types (e.g. 'MJPEG', 'XVID', 'H264', 'X264', 'AVC1' etc.)
  # video_type: XVID  # type=str

  # [Optional]
  # Class to be used to write frames to a video file. Supported values:
  #
  #     - ``ffmpeg``: Use the FFmpeg writer (default, and usually more reliable - it requires ``ffmpeg``
  #         installed).
  #     - ``cv``: Use the native OpenCV writer.
  #
  # The FFmpeg video writer requires ``scikit-video`` (``pip install scikit-video``) and ``ffmpeg``.
  # video_writer: ffmpeg  # type=str

  # [Optional]
  # Identifier of the default capturing device.
  # device:   # type=Union[str, int, NoneType]

  # [Optional]
  # Default resolution, as a tuple of two integers.
  # resolution: (640, 480)  # type=Tuple[int, int]

  # [Optional]
  # Directory where the camera frames will be stored
  # (default: ``~/.local/share/platypush/<plugin.name>/frames``)
  # frames_dir:   # type=Optional[str]

  # [Optional]
  # Cameras usually take a while to adapt their
  # luminosity and focus to the environment when taking a picture.
  # This parameter allows you to specify the number of "warmup" frames
  # to capture upon picture command before actually capturing a frame
  # (default: 5 but you may want to calibrate this parameter for your
  # camera)
  # warmup_frames: 5  # type=int

  # [Optional]
  # Number of seconds to wait before a picture is
  # taken or the first frame of a video/sequence is captured (default:
  # 0).
  # warmup_seconds: 0.0  # type=Optional[float]

  # [Optional]
  # Maximum number of seconds to wait between the
  # programmed termination of a capture session and the moment the
  # device is released.
  # capture_timeout: 20.0  # type=Optional[float]

  # [Optional]
  # If set, the images will be scaled along the x-axis by
  # the specified factor
  # scale_x:   # type=Optional[float]

  # [Optional]
  # If set, the images will be scaled along the y-axis by
  # the specified factor
  # scale_y:   # type=Optional[float]

  # [Optional]
  # If set, the images will be rotated by the specified
  # number of degrees
  # rotate:   # type=Optional[float]

  # [Optional]
  # Whether the output should be converted to grayscale.
  # grayscale:   # type=Optional[bool]

  # [Optional]
  # Frames per second (default: 25).
  # fps: 16  # type=float

  # [Optional]
  # If set, the images will be flipped on the
  # horizontal axis.
  # horizontal_flip: False  # type=bool

  # [Optional]
  # If set, the images will be flipped on the vertical
  # axis.
  # vertical_flip: False  # type=bool

  # [Optional]
  # Plugin-specific format/type for the input stream.
  # input_format:   # type=Optional[str]

  # [Optional]
  # Plugin-specific format/type for the output videos.
  # output_format:   # type=Optional[str]

  # [Optional]
  # Default format for the output when streamed to a
  # network device. Available:
  #
  #     - ``mjpeg`` (default)
  #     - ``h264`` (over ``ffmpeg``)
  #     - ``h265`` (over ``ffmpeg``)
  #     - ``mkv`` (over ``ffmpeg``)
  #     - ``mp4`` (over ``ffmpeg``)
  # stream_format: mjpeg  # type=str

  # [Optional]
  # Default port to be used for streaming over TCP
  # (default: 5000).
  # listen_port: 5000  # type=Optional[int]

  # [Optional]
  # Default bind address for TCP streaming (default:
  # 0.0.0.0, accept connections on any network interface).
  # bind_address: 0.0.0.0  # type=str

  # [Optional]
  # If set, the camera will start streaming on the
  # specified ``bind_address`` and ``listen_port`` as soon as the plugin
  # is started. Otherwise, the stream will be started only when the
  # `CameraPlugin.start_streaming <https://docs.platypush.tech/platypush/plugins/camera.html#platypush.plugins.camera.CameraPlugin.start_streaming>`_ method is called. Default: False.
  # stream_on_start: False  # type=bool

  # [Optional]
  # Path to the ffmpeg binary (default: ``ffmpeg``).
  # ffmpeg_bin: ffmpeg  # type=str

  # [Optional]
  # Specify the ffmpeg video codec (``-vcodec``) used
  # for the input.
  # input_codec:   # type=Optional[str]

  # [Optional]
  # Specify the ffmpeg video codec (``-vcodec``) to be
  # used for encoding the output. For some ffmpeg output formats (e.g.
  # ``h264`` and ``rtp``) this may default to ``libxvid``.
  # output_codec:   # type=Optional[str]

  # [Optional]
  # How often the `RunnablePlugin.loop <https://docs.platypush.tech/platypush/plugins/.html#platypush.plugins.RunnablePlugin.loop>`_ function should be
  # executed (default: 15 seconds). *NOTE*: For back-compatibility
  # reasons, the `poll_seconds` argument is also supported, but it's
  # deprecated.
  # poll_interval: 15  # type=Optional[float]

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Dependencies#

pip

pip install opencv-python numpy Pillow

Alpine

apk add py3-numpy py3-opencv py3-pillow

Debian

apt install python3-pillow python3-opencv python3-numpy

Fedora

yum install python-pillow python-opencv python-numpy

Arch Linux

pacman -S python-pillow python-opencv python-numpy

Actions#

Module reference#

class platypush.plugins.camera.cv.CameraCvPlugin(color_transform: str | None = 'COLOR_BGR2RGB', video_type: str = 'XVID', video_writer: str = 'ffmpeg', **kwargs)[source]#

Bases: CameraPlugin

Plugin to control generic cameras over OpenCV.

__init__(color_transform: str | None = 'COLOR_BGR2RGB', video_type: str = 'XVID', video_writer: str = 'ffmpeg', **kwargs)[source]#
Parameters:

  • device – Device ID (0 for the first camera, 1 for the second etc.) or path (e.g. /dev/video0).

  • video_type – Default video type to use when exporting captured frames to camera (default: 0, infers the type from the video file extension). See here for a reference on the supported types (e.g. ‘MJPEG’, ‘XVID’, ‘H264’, ‘X264’, ‘AVC1’ etc.)

  • color_transform – Color transformation to apply to the captured frames. See https://docs.opencv.org/3.2.0/d7/d1b/group__imgproc__misc.html for a full list of supported color transformations (default: “COLOR_RGB2BGR”)

  • video_writer –

    Class to be used to write frames to a video file. Supported values:

    • ffmpeg: Use the FFmpeg writer (default, and usually more reliable - it requires ffmpeg

      installed).

    • cv: Use the native OpenCV writer.

    The FFmpeg video writer requires scikit-video (pip install scikit-video) and ffmpeg.

  • kwargs – Extra arguments to be passed up to platypush.plugins.camera.CameraPlugin.

capture_frame(camera: Camera, *args, **kwargs)[source]#

Capture a frame from a device using the plugin-specific logic - to be implemented by the derived classes.

Parameters:

device – An initialized platypush.plugins.camera.Camera object.

capture_image(image_file: str, device: str | int | None = None, preview: bool = False, **camera) → str#

Capture an image.

Parameters:

  • image_file – Path where the output image will be stored.

  • device – Name/path/ID of the device to capture from (default: None, use the default device).

  • camera – Camera parameters override - see constructors parameters.

  • preview – Show a preview of the camera frames.

Returns:

The local path to the saved image.

capture_preview(device: str | int | None = None, duration: float | None = None, n_frames: int | None = None, **camera) → dict#

Start a camera preview session.

Parameters:

  • device – Name/path/ID of the device to capture from (default: None, use the default device).

  • duration – Preview duration (default: until stop_capture() is called).

  • n_frames – Number of frames to display before closing (default: until stop_capture() is called).

  • camera – Camera object properties.

Returns:

The status of the device.

capture_sequence(device: str | int | None = None, duration: float | None = None, n_frames: int | None = None, preview: bool = False, **camera) → str | None#

Capture a sequence of frames from a camera and store them to a directory.

Parameters:

  • device – Name/path/ID of the device to capture from (default: None, use the default device).

  • duration – Duration of the sequence in seconds (default: until stop_capture() is called).

  • n_frames – Number of images to be captured (default: until stop_capture() is called).

  • camera – Camera parameters override - see constructors parameters. frames_dir and fps in particular can be specifically tuned for capture_sequence.

  • preview – Show a preview of the camera frames.

Returns:

The directory where the image files have been stored.

capture_video(device: str | int | None = None, duration: float | None = None, video_file: str | None = None, preview: bool = False, **camera) → str | dict | None#

Capture a video.

Parameters:

  • device – Name/path/ID of the device to capture from (default: None, use the default device).

  • duration – Record duration in seconds (default: None, record until stop_capture).

  • video_file – If set, the stream will be recorded to the specified video file (default: None).

  • camera – Camera parameters override - see constructors parameters.

  • preview – Show a preview of the camera frames.

Returns:

If duration is specified, the method will wait until the recording is done and return the local path to the recorded resource. Otherwise, it will return the status of the camera device after starting it.

capturing_thread(camera: Camera, duration: float | None = None, video_file: str | None = None, image_file: str | None = None, n_frames: int | None = None, preview: bool = False, **kwargs)#

Camera capturing thread.

Parameters:

  • camera – An initialized platypush.plugins.camera.Camera object.

  • duration – Capturing session duration in seconds (default: until stop_capture() is called).

  • video_file – If set, the session will be recorded to this output video file (video capture mode).

  • image_file – If set, the output of the session will be a single image file (photo mode).

  • n_frames – Number of frames to be captured (default: until stop_capture() is called).

  • preview – Start a preview window.

  • kwargs – Extra arguments to be passed to capture_frame().

close_device(camera: Camera, wait_capture: bool = True) → None#

Close and release a device.

static encode_frame(frame, encoding: str = 'jpeg') → bytes#

Encode a frame to a target type. The default implementation assumes that frame is a PIL.Image object.

Parameters:

  • frame – Image frame (default: a PIL.Image object).

  • encoding – Image encoding (e.g. jpeg).

static flip_frame(frame, horizontal_flip: bool = False, vertical_flip: bool = False)#

Frame flip logic. Does nothing unless implemented by a derived plugin.

Parameters:

  • frame – Image frame (default: a PIL.Image object).

  • horizontal_flip – Flip along the horizontal axis.

  • vertical_flip – Flip along the vertical axis.

open(device: str | int | None = None, stream: bool = False, redis_queue: str | None = None, **info) → Generator[Camera, None, None]#

Initialize and open a device using a context manager pattern.

Parameters:

  • device – Capture device by name, path or ID.

  • stream – If set, the frames will be streamed to camera.stream.

  • redis_queue – If set, the frames will be streamed to redis_queue.

  • info – Camera parameters override - see constructors parameters.

Returns:

The initialized platypush.plugins.camera.Camera object.

open_device(device: str | int | None = None, stream: bool = False, redis_queue: str | None = None, ctx: dict | None = None, **params) → Camera#

Initialize and open a device.

Returns:

The initialized camera device.

Raises:

platypush.plugins.camera.CaptureSessionAlreadyRunningException

prepare_device(device: Camera, **_)[source]#

Prepare a device using the plugin-specific logic - to be implemented by the derived classes.

Parameters:

device – An initialized platypush.plugins.camera.Camera object.

release_device(device: Camera)[source]#

Release a device using the plugin-specific logic - to be implemented by the derived classes.

Parameters:

device – An initialized platypush.plugins.camera.Camera object.

static rotate_frame(frame, rotation: float | int | None = None)#

Frame rotation logic. The default implementation assumes that frame is a PIL.Image object.

Parameters:

  • frame – Image frame (default: a PIL.Image object).

  • rotation – Rotation angle in degrees.

static scale_frame(frame, scale_x: float | None = None, scale_y: float | None = None)#

Frame scaling logic. The default implementation assumes that frame is a PIL.Image object.

Parameters:

  • frame – Image frame (default: a PIL.Image object).

  • scale_x – X-scale factor.

  • scale_y – Y-scale factor.

start_camera(camera: Camera, *args, preview: bool = False, **kwargs)#

Start a camera capture session.

Parameters:

  • camera – An initialized platypush.plugins.camera.Camera object.

  • preview – Show a preview of the camera frames.

start_streaming(device: str | int | None = None, duration: float | None = None, stream_format: str | None = None, **camera) → dict#

Expose the video stream of a camera over a TCP connection.

When the streaming is started, the plugin will listen on the specified bind_address and listen_port and stream camera frames to connected clients. If stream_format is a video format (H264, H265, MKV, MP4 etc.) then the camera stream can be viewed using a video player - for example, using vlc:

vlc tcp://<host>:<port>
Parameters:

  • device – Name/path/ID of the device to capture from (default: None, use the default device).

  • duration – Streaming thread duration (default: until stop_streaming() is called).

  • stream_format – Format of the output stream - e.g. h264, mjpeg, mkv etc. If not specified, the stream_format configured on the plugin will be used.

  • camera – Camera object properties - see constructor parameters.

Returns:

The status of the device.

status(device: str | int | None = None)#

Returns the status of the specified camera or all the active cameras if device is None.

stop_capture(device: str | int | None = None)#

Stop any capturing session on the specified device.

Parameters:

device – Name/path/ID of the device to stop (default: all the active devices).

stop_streaming(device: str | int | None = None)#

Stop a camera over TCP session.

Parameters:

device – Name/path/ID of the device to stop (default: all the active devices).

static store_frame(frame, filepath: str, format: str | None = None)#

Capture a frame to the filesystem using the PIL library - it can be overridden by derived classes.

Parameters:

  • frame – Frame object (default: a byte-encoded object or a PIL.Image object).

  • filepath – Destination file.

  • format – Output format.

take_picture(image_file: str, device: str | int | None = None, **camera) → str#

Alias for capture_image().

Parameters:

  • image_file – Path where the output image will be stored.

  • device – Name/path/ID of the device to capture from (default: None, use the default device).

  • camera – Camera parameters override - see constructors parameters.

Returns:

The local path to the saved image.

to_grayscale(frame)#

Convert a frame to grayscale. The default implementation assumes that frame is a PIL.Image object.

Parameters:

frame – Image frame (default: a PIL.Image object).

static transform_frame(frame, color_transform: str | int)[source]#

Frame color space (e.g. RGB24, YUV etc.) transform logic. Does nothing unless implemented by a derived plugin.

wait_capture(camera: Camera) → None#

Wait until a capture session terminates.

Parameters:

camera – Camera object. camera.info.capture_timeout is used as a capture thread termination timeout if set.

Platypush documentation