camera

class platypush.plugins.camera.Camera(info: platypush.plugins.camera.model.camera.CameraInfo, start_event: threading.Event = <threading.Event object at 0x7fbd96e96be0>, stream_event: threading.Event = <threading.Event object at 0x7fbd96e9d610>, capture_thread: Optional[threading.Thread] = None, stream_thread: Optional[threading.Thread] = None, stream: Optional[platypush.plugins.camera.model.writer.StreamWriter] = None, preview: Optional[platypush.plugins.camera.model.writer.preview.PreviewWriter] = None, file_writer: Optional[platypush.plugins.camera.model.writer.FileVideoWriter] = None)[source]
__init__(info: platypush.plugins.camera.model.camera.CameraInfo, start_event: threading.Event = <threading.Event object>, stream_event: threading.Event = <threading.Event object>, capture_thread: Optional[threading.Thread] = None, stream_thread: Optional[threading.Thread] = None, stream: Optional[platypush.plugins.camera.model.writer.StreamWriter] = None, preview: Optional[platypush.plugins.camera.model.writer.preview.PreviewWriter] = None, file_writer: Optional[platypush.plugins.camera.model.writer.FileVideoWriter] = None)None

Initialize self. See help(type(self)) for accurate signature.

exception platypush.plugins.camera.CameraException[source]
class platypush.plugins.camera.CameraInfo(device: Union[str, int, NoneType], bind_address: Optional[str] = None, capture_timeout: float = 20.0, color_transform: Optional[str] = None, ffmpeg_bin: Optional[str] = None, fps: Optional[float] = None, frames_dir: Optional[str] = None, grayscale: Optional[bool] = None, horizontal_flip: bool = False, input_codec: Optional[str] = None, input_format: Optional[str] = None, listen_port: Optional[int] = None, output_codec: Optional[str] = None, output_format: Optional[str] = None, resolution: Optional[Tuple[int, int]] = None, rotate: Optional[float] = None, scale_x: Optional[float] = None, scale_y: Optional[float] = None, stream_format: Optional[str] = None, vertical_flip: bool = False, warmup_frames: int = 0, warmup_seconds: float = 0.0)[source]
__init__(device: Optional[Union[str, int]], bind_address: Optional[str] = None, capture_timeout: float = 20.0, color_transform: Optional[str] = None, ffmpeg_bin: Optional[str] = None, fps: Optional[float] = None, frames_dir: Optional[str] = None, grayscale: Optional[bool] = None, horizontal_flip: bool = False, input_codec: Optional[str] = None, input_format: Optional[str] = None, listen_port: Optional[int] = None, output_codec: Optional[str] = None, output_format: Optional[str] = None, resolution: Optional[Tuple[int, int]] = None, rotate: Optional[float] = None, scale_x: Optional[float] = None, scale_y: Optional[float] = None, stream_format: Optional[str] = None, vertical_flip: bool = False, warmup_frames: int = 0, warmup_seconds: float = 0.0)None

Initialize self. See help(type(self)) for accurate signature.

class platypush.plugins.camera.CameraPlugin(device: Optional[Union[str, int]] = None, resolution: Tuple[int, int] = (640, 480), frames_dir: Optional[str] = None, warmup_frames: int = 5, warmup_seconds: Optional[float] = 0.0, capture_timeout: Optional[float] = 20.0, scale_x: Optional[float] = None, scale_y: Optional[float] = None, rotate: Optional[float] = None, grayscale: Optional[bool] = None, color_transform: Optional[Union[str, int]] = None, fps: float = 16, horizontal_flip: bool = False, vertical_flip: bool = False, input_format: Optional[str] = None, output_format: Optional[str] = None, stream_format: str = 'mjpeg', listen_port: Optional[int] = 5000, bind_address: str = '0.0.0.0', ffmpeg_bin: str = 'ffmpeg', input_codec: Optional[str] = None, output_codec: Optional[str] = None, **kwargs)[source]

Abstract plugin to control camera devices.

If the platypush.backend.http.HttpBackend is enabled then the plugins that implement this class can expose two endpoints:

  • http://host:8008/camera/<plugin>/photo<.extension> to capture a photo from the camera, where

    .extension can be .jpg, .png or .bmp.

  • http://host:8008/camera/<plugin>/video<.extension> to get a live feed from the camera, where

    .extension can be .mjpeg, .mkv/.webm, .mp4/.h264 or .h265.

Both the endpoints support the same parameters of the constructor of this class (e.g. device, warmup_frames, duration etc.) as GET parameters.

Requires:

  • Pillow (pip install Pillow) [optional] default handler for image transformations.

  • wxPython (pip install wxPython) [optional] default handler for camera previews (ffplay will be

    used as a fallback if wxPython is not installed).

  • ffmpeg (see installation instructions for your OS) for rendering/streaming videos.

Triggers:

__init__(device: Optional[Union[str, int]] = None, resolution: Tuple[int, int] = (640, 480), frames_dir: Optional[str] = None, warmup_frames: int = 5, warmup_seconds: Optional[float] = 0.0, capture_timeout: Optional[float] = 20.0, scale_x: Optional[float] = None, scale_y: Optional[float] = None, rotate: Optional[float] = None, grayscale: Optional[bool] = None, color_transform: Optional[Union[str, int]] = None, fps: float = 16, horizontal_flip: bool = False, vertical_flip: bool = False, input_format: Optional[str] = None, output_format: Optional[str] = None, stream_format: str = 'mjpeg', listen_port: Optional[int] = 5000, bind_address: str = '0.0.0.0', ffmpeg_bin: str = 'ffmpeg', input_codec: Optional[str] = None, output_codec: Optional[str] = None, **kwargs)[source]
Parameters
  • device – Identifier of the default capturing device.

  • resolution – Default resolution, as a tuple of two integers.

  • frames_dir – Directory where the camera frames will be stored (default: ~/.local/share/platypush/<plugin.name>/frames)

  • warmup_frames – 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_seconds – Number of seconds to wait before a picture is taken or the first frame of a video/sequence is captured (default: 0).

  • capture_timeout – Maximum number of seconds to wait between the programmed termination of a capture session and the moment the device is released.

  • scale_x – If set, the images will be scaled along the x axis by the specified factor

  • scale_y – If set, the images will be scaled along the y axis by the specified factor

  • color_transform – Color transformation to apply to the images.

  • grayscale – Whether the output should be converted to grayscale.

  • rotate – If set, the images will be rotated by the specified number of degrees

  • fps – Frames per second (default: 25).

  • horizontal_flip – If set, the images will be flipped on the horizontal axis.

  • vertical_flip – If set, the images will be flipped on the vertical axis.

  • listen_port – Default port to be used for streaming over TCP (default: 5000).

  • bind_address – Default bind address for TCP streaming (default: 0.0.0.0, accept any connections).

  • input_codec – Specify the ffmpeg video codec (-vcodec) used for the input.

  • output_codec – 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.

  • input_format – Plugin-specific format/type for the input stream.

  • output_format – Plugin-specific format/type for the output videos.

  • ffmpeg_bin – Path to the ffmpeg binary (default: ffmpeg).

  • stream_format

    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)

abstract capture_frame(device: platypush.plugins.camera.model.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, preview: bool = False, **camera)str[source]

Capture an image.

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

  • 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(duration: Optional[float] = None, n_frames: Optional[int] = None, **camera)dict[source]

Start a camera preview session.

Parameters
  • 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(duration: Optional[float] = None, n_frames: Optional[int] = None, preview: bool = False, **camera)str[source]

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

Parameters
  • 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(duration: Optional[float] = None, video_file: Optional[str] = None, preview: bool = False, **camera)Union[str, dict][source]

Capture a video.

Parameters
  • 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: platypush.plugins.camera.model.camera.Camera, duration: Optional[float] = None, video_file: Optional[str] = None, image_file: Optional[str] = None, n_frames: Optional[int] = None, preview: bool = False, **kwargs)[source]

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: platypush.plugins.camera.model.camera.Camera, wait_capture: bool = True)None[source]

Close and release a device.

static encode_frame(frame, encoding: str = 'jpeg')bytes[source]

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)[source]

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: Optional[Union[str, int]] = None, stream: bool = None, **info)platypush.plugins.camera.model.camera.Camera[source]

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.

  • info – Camera parameters override - see constructors parameters.

Returns

The initialized platypush.plugins.camera.Camera object.

open_device(device: Optional[Union[str, int]] = None, stream: bool = False, **params)platypush.plugins.camera.model.camera.Camera[source]

Initialize and open a device.

Returns

The initialized camera device.

Raises

platypush.plugins.camera.CaptureSessionAlreadyRunningException

abstract prepare_device(device: platypush.plugins.camera.model.camera.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.

abstract release_device(device: platypush.plugins.camera.model.camera.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: Optional[Union[float, int]] = None)[source]

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: Optional[float] = None, scale_y: Optional[float] = None)[source]

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: platypush.plugins.camera.model.camera.Camera, preview: bool = False, *args, **kwargs)[source]

Start a camera capture session.

Parameters
start_streaming(duration: Optional[float] = None, stream_format: str = 'mkv', **camera)dict[source]

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

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

  • stream_format – Format of the output stream - e.g. h264, mjpeg, mkv etc. (default: mkv).

  • camera – Camera object properties - see constructor parameters.

Returns

The status of the device.

status(device: Optional[Union[str, int]] = None)[source]

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

stop_capture(device: Optional[Union[str, int]] = None)[source]

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: Optional[Union[str, int]] = None)[source]

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: Optional[str] = None)[source]

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, preview: bool = False, **camera)str[source]

Alias for capture_image().

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

  • camera – Camera parameters override - see constructors parameters.

  • preview – Show a preview of the camera frames.

Returns

The local path to the saved image.

to_grayscale(frame)[source]

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)[source]

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

wait_capture(camera: platypush.plugins.camera.model.camera.Camera)None[source]

Wait until a capture session terminates.

Parameters

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

exception platypush.plugins.camera.CaptureAlreadyRunningException(device)[source]
__init__(device)[source]

Initialize self. See help(type(self)) for accurate signature.

class platypush.plugins.camera.StreamWriter(*args, sock: Optional[IO] = None, **kwargs)[source]

Abstract class for camera streaming operations.

__init__(*args, sock: Optional[IO] = None, **kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

close()[source]

Close the channel.

abstract encode(image: PIL.Image.Image)bytes[source]

Encode an image before sending it to the channel.

Parameters

image – PIL Image object.

Returns

The bytes-encoded representation of the frame.

write(image: PIL.Image.Image)[source]

Write an image to the channel.

Parameters

img – PIL Image instance.