Source code for picamera.renderers

# vim: set et sw=4 sts=4 fileencoding=utf-8:
#
# Python camera library for the Rasperry-Pi camera module
# Copyright (c) 2013-2015 Dave Jones <dave@waveform.org.uk>
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
#     * Redistributions of source code must retain the above copyright
#       notice, this list of conditions and the following disclaimer.
#     * Redistributions in binary form must reproduce the above copyright
#       notice, this list of conditions and the following disclaimer in the
#       documentation and/or other materials provided with the distribution.
#     * Neither the name of the copyright holder nor the
#       names of its contributors may be used to endorse or promote products
#       derived from this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.

"""
The renderers module defines the renderer classes used by the camera to provide
preview and overlay output on the Pi's display. Users will rarely need to
construct instances of these classes directly
(:meth:`~picamera.camera.PiCamera.start_preview` and
:meth:`~picamera.camera.PiCamera.add_overlay` are generally used instead) but
may find the attribute references for them useful.

.. note::

    All classes in this module are available from the :mod:`picamera` namespace
    without having to import :mod:`picamera.renderers` directly.

The following classes are defined in the module:


PiRenderer
==========

.. autoclass:: PiRenderer
    :members:


PiOverlayRenderer
=================

.. autoclass:: PiOverlayRenderer
    :members:


PiPreviewRenderer
=================

.. autoclass:: PiPreviewRenderer
    :members:


PiNullSink
==========

.. autoclass:: PiNullSink
    :members:

"""

from __future__ import (
    unicode_literals,
    print_function,
    division,
    absolute_import,
    )

# Make Py2's str and range equivalent to Py3's
str = type('')

import ctypes as ct

import picamera.mmal as mmal
from picamera.exc import (
    PiCameraRuntimeError,
    PiCameraValueError,
    mmal_check,
    )


def _overlay_callback(port, buf):
    mmal.mmal_buffer_header_release(buf)
_overlay_callback = mmal.MMAL_PORT_BH_CB_T(_overlay_callback)


[docs]class PiRenderer(object): """ Base implementation of an MMAL video renderer for use by PiCamera. The *parent* parameter specifies the :class:`~picamera.camera.PiCamera` instance that has constructed this renderer. The *layer* parameter specifies the layer that the renderer will inhabit. Higher numbered layers obscure lower numbered layers (unless they are partially transparent). The initial opacity of the renderer is specified by the *alpha* parameter (which defaults to 255, meaning completely opaque). The *fullscreen* parameter which defaults to ``True`` indicates whether the renderer should occupy the entire display. Finally, the *window* parameter (which only has meaning when *fullscreen* is ``False``) is a four-tuple of ``(x, y, width, height)`` which gives the screen coordinates that the renderer should occupy when it isn't full-screen. This base class isn't directly used by :class:`~picamera.camera.PiCamera`, but the two derivatives defined below, :class:`PiOverlayRenderer` and :class:`PiPreviewRenderer`, are used to produce overlays and the camera preview respectively. """ def __init__( self, parent, layer=0, alpha=255, fullscreen=True, window=None, crop=None, rotation=0, vflip=False, hflip=False): # Create and enable the renderer component self._rotation = 0 self._vflip = False self._hflip = False self.parent = parent self.renderer = ct.POINTER(mmal.MMAL_COMPONENT_T)() mmal_check( mmal.mmal_component_create( mmal.MMAL_COMPONENT_DEFAULT_VIDEO_RENDERER, self.renderer), prefix="Failed to create renderer component") try: if not self.renderer[0].input_num: raise PiCameraError("No input ports on renderer component") self.layer = layer self.alpha = alpha self.fullscreen = fullscreen if window is not None: self.window = window if crop is not None: self.crop = crop self.rotation = rotation self.vflip = vflip self.hflip = hflip mmal_check( mmal.mmal_component_enable(self.renderer), prefix="Renderer component couldn't be enabled") except: mmal.mmal_component_destroy(self.renderer) raise
[docs] def close(self): """ Finalizes the renderer and deallocates all structures. This method is called by the camera prior to destroying the renderer (or more precisely, letting it go out of scope to permit the garbage collector to destroy it at some future time). """ if self.renderer: mmal.mmal_component_destroy(self.renderer) self.renderer = None
def __enter__(self): return self def __exit__(self, exc_type, exc_value, exc_tb): self.close() def _get_alpha(self): mp = mmal.MMAL_DISPLAYREGION_T( mmal.MMAL_PARAMETER_HEADER_T( mmal.MMAL_PARAMETER_DISPLAYREGION, ct.sizeof(mmal.MMAL_DISPLAYREGION_T) )) mmal_check( mmal.mmal_port_parameter_get(self.renderer[0].input[0], mp.hdr), prefix="Failed to get alpha") return mp.alpha def _set_alpha(self, value): try: if not (0 <= value <= 255): raise PiCameraValueError( "Invalid alpha value: %d (valid range 0..255)" % value) except TypeError: raise PiCameraValueError("Invalid alpha value: %s" % value) mp = mmal.MMAL_DISPLAYREGION_T( mmal.MMAL_PARAMETER_HEADER_T( mmal.MMAL_PARAMETER_DISPLAYREGION, ct.sizeof(mmal.MMAL_DISPLAYREGION_T) ), set=mmal.MMAL_DISPLAY_SET_ALPHA, alpha=value ) mmal_check( mmal.mmal_port_parameter_set(self.renderer[0].input[0], mp.hdr), prefix="Failed to set alpha") alpha = property(_get_alpha, _set_alpha, doc=""" Retrieves or sets the opacity of the renderer. When queried, the :attr:`alpha` property returns a value between 0 and 255 indicating the opacity of the renderer, where 0 is completely transparent and 255 is completely opaque. The default value is 255. The property can be set while recordings or previews are in progress. """) def _get_layer(self): mp = mmal.MMAL_DISPLAYREGION_T( mmal.MMAL_PARAMETER_HEADER_T( mmal.MMAL_PARAMETER_DISPLAYREGION, ct.sizeof(mmal.MMAL_DISPLAYREGION_T) )) mmal_check( mmal.mmal_port_parameter_get(self.renderer[0].input[0], mp.hdr), prefix="Failed to get layer") return mp.layer def _set_layer(self, value): try: if not (0 <= value <= 255): raise PiCameraValueError( "Invalid layer value: %d (valid range 0..255)" % value) except TypeError: raise PiCameraValueError("Invalid layer value: %s" % value) mp = mmal.MMAL_DISPLAYREGION_T( mmal.MMAL_PARAMETER_HEADER_T( mmal.MMAL_PARAMETER_DISPLAYREGION, ct.sizeof(mmal.MMAL_DISPLAYREGION_T) ), set=mmal.MMAL_DISPLAY_SET_LAYER, layer=value ) mmal_check( mmal.mmal_port_parameter_set(self.renderer[0].input[0], mp.hdr), prefix="Failed to set layer") layer = property( _get_layer, _set_layer, doc=""" Retrieves of sets the layer of the renderer. The :attr:`layer` property is an integer which controls the layer that the renderer occupies. Higher valued layers obscure lower valued layers (with 0 being the "bottom" layer). The default value is 2. The property can be set while recordings or previews are in progress. """) def _get_fullscreen(self): mp = mmal.MMAL_DISPLAYREGION_T( mmal.MMAL_PARAMETER_HEADER_T( mmal.MMAL_PARAMETER_DISPLAYREGION, ct.sizeof(mmal.MMAL_DISPLAYREGION_T) )) mmal_check( mmal.mmal_port_parameter_get(self.renderer[0].input[0], mp.hdr), prefix="Failed to get fullscreen") return mp.fullscreen != mmal.MMAL_FALSE def _set_fullscreen(self, value): mp = mmal.MMAL_DISPLAYREGION_T( mmal.MMAL_PARAMETER_HEADER_T( mmal.MMAL_PARAMETER_DISPLAYREGION, ct.sizeof(mmal.MMAL_DISPLAYREGION_T) ), set=mmal.MMAL_DISPLAY_SET_FULLSCREEN, fullscreen=bool(value) ) mmal_check( mmal.mmal_port_parameter_set(self.renderer[0].input[0], mp.hdr), prefix="Failed to set fullscreen") fullscreen = property( _get_fullscreen, _set_fullscreen, doc=""" Retrieves or sets whether the renderer appears full-screen. The :attr:`fullscreen` property is a bool which controls whether the renderer takes up the entire display or not. When set to ``False``, the :attr:`window` property can be used to control the precise size of the renderer display. The property can be set while recordings or previews are active. """) def _get_window(self): mp = mmal.MMAL_DISPLAYREGION_T( mmal.MMAL_PARAMETER_HEADER_T( mmal.MMAL_PARAMETER_DISPLAYREGION, ct.sizeof(mmal.MMAL_DISPLAYREGION_T) )) mmal_check( mmal.mmal_port_parameter_get(self.renderer[0].input[0], mp.hdr), prefix="Failed to get window") return ( mp.dest_rect.x, mp.dest_rect.y, mp.dest_rect.width, mp.dest_rect.height, ) def _set_window(self, value): try: x, y, w, h = value except (TypeError, ValueError) as e: raise PiCameraValueError( "Invalid window rectangle (x, y, w, h) tuple: %s" % value) mp = mmal.MMAL_DISPLAYREGION_T( mmal.MMAL_PARAMETER_HEADER_T( mmal.MMAL_PARAMETER_DISPLAYREGION, ct.sizeof(mmal.MMAL_DISPLAYREGION_T) ), set=mmal.MMAL_DISPLAY_SET_DEST_RECT, dest_rect=mmal.MMAL_RECT_T(x, y, w, h), ) mmal_check( mmal.mmal_port_parameter_set(self.renderer[0].input[0], mp.hdr), prefix="Failed to set window") window = property(_get_window, _set_window, doc=""" Retrieves or sets the size of the renderer. When the :attr:`fullscreen` property is set to ``False``, the :attr:`window` property specifies the size and position of the renderer on the display. The property is a 4-tuple consisting of ``(x, y, width, height)``. The property can be set while recordings or previews are active. """) def _get_crop(self): mp = mmal.MMAL_DISPLAYREGION_T( mmal.MMAL_PARAMETER_HEADER_T( mmal.MMAL_PARAMETER_DISPLAYREGION, ct.sizeof(mmal.MMAL_DISPLAYREGION_T) )) mmal_check( mmal.mmal_port_parameter_get(self.renderer[0].input[0], mp.hdr), prefix="Failed to get crop") return ( mp.src_rect.x, mp.src_rect.y, mp.src_rect.width, mp.src_rect.height, ) def _set_crop(self, value): try: x, y, w, h = value except (TypeError, ValueError) as e: raise PiCameraValueError( "Invalid crop rectangle (x, y, w, h) tuple: %s" % value) mp = mmal.MMAL_DISPLAYREGION_T( mmal.MMAL_PARAMETER_HEADER_T( mmal.MMAL_PARAMETER_DISPLAYREGION, ct.sizeof(mmal.MMAL_DISPLAYREGION_T) ), set=mmal.MMAL_DISPLAY_SET_SRC_RECT, src_rect=mmal.MMAL_RECT_T(x, y, w, h), ) mmal_check( mmal.mmal_port_parameter_set(self.renderer[0].input[0], mp.hdr), prefix="Failed to set crop") crop = property(_get_crop, _set_crop, doc=""" Retrieves or sets the area to read from the source. The :attr:`crop` property specifies the rectangular area that the renderer will read from the source as a 4-tuple of ``(x, y, width, height)``. The special value ``(0, 0, 0, 0)`` (which is also the default) means to read entire area of the source. The property can be set while recordings or previews are active. For example, if the camera's resolution is currently configured as 1280x720, setting this attribute to ``(160, 160, 640, 400)`` will crop the preview to the center 640x400 pixels of the input. Note that this property does not affect the size of the output rectangle, which is controlled with :attr:`fullscreen` and :attr:`window`. .. note:: This property only affects the renderer; it has no bearing on image captures or recordings (unlike the :attr:`~picamera.camera.PiCamera.zoom` property of the :class:`~picamera.camera.PiCamera` class). """) def _get_rotation(self): return self._rotation def _set_rotation(self, value): try: value = ((int(value) % 360) // 90) * 90 except ValueError: raise PiCameraValueError("Invalid rotation angle: %s" % value) self._set_transform( self._get_transform(value, self._vflip, self._hflip)) self._rotation = value rotation = property(_get_rotation, _set_rotation, doc=""" Retrieves of sets the current rotation of the renderer. When queried, the :attr:`rotation` property returns the rotation applied to the renderer. Valid values are 0, 90, 180, and 270. When set, the property changes the rotation applied to the renderer's output. The property can be set while recordings or previews are active. The default is 0. .. note:: This property only affects the renderer; it has no bearing on image captures or recordings (unlike the :attr:`~picamera.camera.PiCamera.rotation` property of the :class:`~picamera.camera.PiCamera` class). """) def _get_vflip(self): return self._vflip def _set_vflip(self, value): value = bool(value) self._set_transform( self._get_transform(self._rotation, value, self._hflip)) self._vflip = value vflip = property(_get_vflip, _set_vflip, doc=""" Retrieves of sets whether the renderer's output is vertically flipped. When queried, the :attr:`vflip` property returns a boolean indicating whether or not the renderer's output is vertically flipped. The property can be set while recordings or previews are in progress. The default is ``False``. .. note:: This property only affects the renderer; it has no bearing on image captures or recordings (unlike the :attr:`~picamera.camera.PiCamera.vflip` property of the :class:`~picamera.camera.PiCamera` class). """) def _get_hflip(self): return self._hflip def _set_hflip(self, value): value = bool(value) self._set_transform( self._get_transform(self._rotation, self._vflip, value)) self._hflip = value hflip = property(_get_hflip, _set_hflip, doc=""" Retrieves of sets whether the renderer's output is horizontally flipped. When queried, the :attr:`vflip` property returns a boolean indicating whether or not the renderer's output is horizontally flipped. The property can be set while recordings or previews are in progress. The default is ``False``. .. note:: This property only affects the renderer; it has no bearing on image captures or recordings (unlike the :attr:`~picamera.camera.PiCamera.hflip` property of the :class:`~picamera.camera.PiCamera` class). """) def _get_transform(self, rotate, vflip, hflip): # Use a (horizontally) mirrored transform if one of vflip or hflip is # set. If vflip is set, rotate by an extra 180 degrees to make up for # the lack of a "true" vertical flip mirror = vflip ^ hflip if vflip: rotate = (rotate + 180) % 360 return { (0, False): mmal.MMAL_DISPLAY_ROT0, (90, False): mmal.MMAL_DISPLAY_ROT90, (180, False): mmal.MMAL_DISPLAY_ROT180, (270, False): mmal.MMAL_DISPLAY_ROT270, (0, True): mmal.MMAL_DISPLAY_MIRROR_ROT0, (90, True): mmal.MMAL_DISPLAY_MIRROR_ROT90, (180, True): mmal.MMAL_DISPLAY_MIRROR_ROT180, (270, True): mmal.MMAL_DISPLAY_MIRROR_ROT270, }[(rotate, mirror)] def _set_transform(self, value): mp = mmal.MMAL_DISPLAYREGION_T( mmal.MMAL_PARAMETER_HEADER_T( mmal.MMAL_PARAMETER_DISPLAYREGION, ct.sizeof(mmal.MMAL_DISPLAYREGION_T) ), set=mmal.MMAL_DISPLAY_SET_TRANSFORM, transform=value, ) mmal_check( mmal.mmal_port_parameter_set(self.renderer[0].input[0], mp.hdr), prefix="Failed to set transform")
[docs]class PiOverlayRenderer(PiRenderer): """ Represents an MMAL renderer with a static source for overlays. This class descends from :class:`PiRenderer` and adds a static source for the MMAL renderer. The optional *size* parameter specifies the size of the source image as a ``(width, height)`` tuple. If this is omitted or ``None`` then the size is assumed to be the same as the parent camera's current :attr:`~picamera.camera.PiCamera.resolution`. The *source* must be an object that supports the :ref:`buffer protocol <bufferobjects>` which has the same length as an image in `RGB`_ format (colors represented as interleaved unsigned bytes) with the specified *size* after the width has been rounded up to the nearest multiple of 32, and the height has been rounded up to the nearest multiple of 16. For example, if *size* is ``(1280, 720)``, then *source* must be a buffer with length 1280 x 720 x 3 bytes, or 2,764,800 bytes (because 1280 is a multiple of 32, and 720 is a multiple of 16 no extra rounding is required). However, if *size* is ``(97, 57)``, then *source* must be a buffer with length 128 x 64 x 3 bytes, or 24,576 bytes (pixels beyond column 97 and row 57 in the source will be ignored). The *layer*, *alpha*, *fullscreen*, and *window* parameters are the same as in :class:`PiRenderer`. .. _RGB: http://en.wikipedia.org/wiki/RGB """ def __init__( self, parent, source, size=None, layer=0, alpha=255, fullscreen=True, window=None, crop=None, rotation=0, vflip=False, hflip=False): super(PiOverlayRenderer, self).__init__( parent, layer, alpha, fullscreen, window, crop, rotation, vflip, hflip) # Copy format from camera's preview port, then adjust the encoding to # RGB888 and optionally adjust the resolution and size port = self.renderer[0].input[0] fmt = port[0].format mmal.mmal_format_copy( fmt, parent._camera[0].output[parent.CAMERA_PREVIEW_PORT][0].format) fmt[0].encoding = mmal.MMAL_ENCODING_RGB24 fmt[0].encoding_variant = mmal.MMAL_ENCODING_RGB24 if size is not None: w, h = size fmt[0].es[0].video.width = mmal.VCOS_ALIGN_UP(w, 32) fmt[0].es[0].video.height = mmal.VCOS_ALIGN_UP(h, 16) fmt[0].es[0].video.crop.width = w fmt[0].es[0].video.crop.height = h mmal_check( mmal.mmal_port_format_commit(port), prefix="Overlay format couldn't be set") port[0].buffer_num = port[0].buffer_num_min port[0].buffer_size = port[0].buffer_size_recommended mmal_check( mmal.mmal_component_enable(self.renderer), prefix="Overlay couldn't be enabled") mmal_check( mmal.mmal_port_enable(port, _overlay_callback), prefix="Overlay input port couldn't be enabled") self.pool = mmal.mmal_port_pool_create( port, port[0].buffer_num, port[0].buffer_size) if not self.pool: raise PiCameraRuntimeError("Couldn't create pool for overlay") self.update(source) def close(self): super(PiOverlayRenderer, self).close() if self.pool: mmal.mmal_pool_destroy(self.pool) self.pool = None
[docs] def update(self, source): """ Update the overlay with a new source of data. The new *source* buffer must have the same size as the original buffer used to create the overlay. There is currently no method for changing the size of an existing overlay (remove and recreate the overlay if you require this). """ port = self.renderer[0].input[0] fmt = port[0].format bp = ct.c_uint8 * (fmt[0].es[0].video.width * fmt[0].es[0].video.height * 3) try: sp = bp.from_buffer(source) except TypeError: sp = bp.from_buffer_copy(source) buf = mmal.mmal_queue_get(self.pool[0].queue) if not buf: raise PiCameraRuntimeError( "Couldn't get a buffer from the overlay's pool") ct.memmove(buf[0].data, sp, buf[0].alloc_size) buf[0].length = buf[0].alloc_size mmal_check( mmal.mmal_port_send_buffer(port, buf), prefix="Unable to send a buffer to the overlay's port")
[docs]class PiPreviewRenderer(PiRenderer): """ Represents an MMAL renderer which uses the camera's preview as a source. This class descends from :class:`PiRenderer` and adds an MMAL connection to connect the renderer to an MMAL port. The *source* parameter specifies the MMAL port to connect to the renderer. The *layer*, *alpha*, *fullscreen*, and *window* parameters are the same as in :class:`PiRenderer`. """ def __init__( self, parent, source, layer=2, alpha=255, fullscreen=True, window=None, crop=None, rotation=0, vflip=False, hflip=False): super(PiPreviewRenderer, self).__init__( parent, layer, alpha, fullscreen, window, crop, rotation, vflip, hflip) self.connection = self.parent._connect_ports( source, self.renderer[0].input[0]) def close(self): if self.connection: mmal.mmal_connection_destroy(self.connection) self.connection = None super(PiPreviewRenderer, self).close()
[docs]class PiNullSink(object): """ Implements an MMAL null-sink which can be used in place of a renderer. The *parent* parameter specifies the :class:`~picamera.camera.PiCamera` instance which constructed this null-sink. The *source* parameter specifies the MMAL port which the null-sink should connect to its input. The null-sink can act as a drop-in replacement for :class:`PiRenderer` in most cases, but obviously doesn't implement attributes like ``alpha``, ``layer``, etc. as it simply dumps any incoming frames. This is also the reason that this class doesn't derive from :class:`PiRenderer` like all other classes in this module. """ def __init__(self, parent, source): self.parent = parent self.renderer = ct.POINTER(mmal.MMAL_COMPONENT_T)() mmal_check( mmal.mmal_component_create( mmal.MMAL_COMPONENT_DEFAULT_NULL_SINK, self.renderer), prefix="Failed to create null sink component") try: if not self.renderer[0].input_num: raise PiCameraError("No input ports on null sink component") mmal_check( mmal.mmal_component_enable(self.renderer), prefix="Null sink component couldn't be enabled") except: mmal.mmal_component_destroy(self.renderer) raise self.connection = self.parent._connect_ports( source, self.renderer[0].input[0])
[docs] def close(self): """ Finalizes the null-sink and deallocates all structures. This method is called by the camera prior to destroying the null-sink (or more precisely, letting it go out of scope to permit the garbage collector to destroy it at some future time). """ if self.connection: mmal.mmal_connection_destroy(self.connection) self.connection = None if self.renderer: mmal.mmal_component_destroy(self.renderer) self.renderer = None
def __enter__(self): return self def __exit__(self, exc_type, exc_value, exc_tb): self.close()