Picamera

:mod:`~picamera.mmalobj` layer:

* 10 second captures should now work with the V2 module as the default
``CAPTURE_TIMEOUT`` has been increased to 60 seconds (`284`_)
* A bug in :meth:`~PiCameraCircularIO.copy_to` caused it to copy nothing when
it encountered "unknown" timestamps in the stream (`302`_, `319`_, `357`_)
* A silly typo in code used by :class:`~picamera.array.PiRGBArray` was fixed
(`321`_)
* A bug in :meth:`~PiCamera.capture_continuous` which caused duplicate frames
in the output was fixed (`311`_)
* Bitrate limits were removed on MJPEG, and full checking of H264 bitrates and
macroblocks/s was implemented (`315`_)
* A bug was fixed in the :attr:`~PiCamera.sensor_mode` attribute which
prevented it from being set after construction (`324`_)
* A bug in the custom encoders example was fixed (`337`_)
* Fixed a rare race condition that occurred when multiple splitter ports were
in use (`344`_)
* Recording overlays is now possible, but currently requires using the lower
level :mod:`~picamera.mmalobj` layer (`196`_)
* Capturing YUV arrays via :class:`~picamera.array.PiYUVArray` is faster,
thanks to GitHub user goosst (`308`_)
* Added the ability to specify a restart interval for JPEG encoding (`369`_)
* Added a property allowing users to manually specify a
:attr:`~PiCamera.framerate_range` for the camera (`374`_)
* Added support for partially transparent overlays in RGBA format (`199`_)
* Improved MJPEG web-streaming recipe, many thanks to GitHub user BigNerd95!
(`375`_)

Substantial work has also gone into improving the documentation. In particular:

* The :doc:`recipes2` chapter has been thoroughly re-worked and I would
encourage anyone using the camera for Computer Vision purposes to re-read
that chapter
* The :doc:`fov` chapter has been extended to include a thorough introduction
to the low level operation of the camera module. This is important for
understanding the limitations and peculiarities of the system
* Anyone interested in using a lower level API to control the camera (which
includes capabilities like manipulating frames before they hit the video
encoder) should read the :doc:`api_mmalobj` chapter
* Finally, some work was done on enhancing the PDF and EPub versions of the
documentation. These should now be much more useable in hard-copy and on
e-readers

.. _196: https://github.com/waveform80/picamera/issues/196
.. _199: https://github.com/waveform80/picamera/issues/199
.. _284: https://github.com/waveform80/picamera/issues/284
.. _302: https://github.com/waveform80/picamera/issues/302
.. _308: https://github.com/waveform80/picamera/issues/308
.. _311: https://github.com/waveform80/picamera/issues/311
.. _315: https://github.com/waveform80/picamera/issues/315
.. _319: https://github.com/waveform80/picamera/issues/319
.. _321: https://github.com/waveform80/picamera/issues/321
.. _324: https://github.com/waveform80/picamera/issues/324
.. _337: https://github.com/waveform80/picamera/issues/337
.. _344: https://github.com/waveform80/picamera/issues/344
.. _357: https://github.com/waveform80/picamera/issues/357
.. _369: https://github.com/waveform80/picamera/issues/369
.. _374: https://github.com/waveform80/picamera/issues/374
.. _375: https://github.com/waveform80/picamera/issues/375

* Fixed issue with unencoded captures in Python 3 (`297`_)
* Fixed several Python 3 bytes/unicode issues that were related to `297`_ (I'd
erroneously run the picamera test suite twice against Python 2 instead of 2
and 3 when releasing 1.11, which is how these snuck in)
* Fixed multi-dimensional arrays for overlays under Python 3
* Finished alternate CIE constructors for the :class:`Color` class

.. _297: https://github.com/waveform80/picamera/issues/297

includes a major re-write of picamera's core:

* Direct capture to buffer-protocol objects, such as numpy arrays
(`241`_)
* Add :meth:`~PiCamera.request_key_frame` method to permit manual request
of an I-frame during H264 recording; this is now used implicitly by
:meth:`~PiCamera.split_recording` (`257`_)
* Added :attr:`~PiCamera.timestamp` attribute to query camera's clock
(`212`_)
* Added :attr:`~PiCamera.framerate_delta` to permit small adjustments to
the camera's framerate to be performed "live" (`279`_)
* Added :meth:`~PiCameraCircularIO.clear` and
:meth:`~PiCameraCircularIO.copy_to` methods to
:class:`PiCameraCircularIO` (`216`_)
* Prevent setting attributes on the main :class:`PiCamera` class to ease
debugging in educational settings (`240`_)
* Due to the core re-writes in this version, you may require cutting edge
firmware (``sudo rpi-update``) if you are performing unencoded captures,
unencoded video recording, motion estimation vector sampling, or manual
sensor mode setting.
* Added property to control preview's :attr:`~PiPreviewRenderer.resolution`
separately from the camera's :attr:`~PiCamera.resolution` (required for
maximum resolution previews on the V2 module - `296`_).

There are also several bug fixes:

* Fixed basic stereoscopic operation on compute module (`218`_)
* Fixed accessing framerate as a tuple (`228`_)
* Fixed hang when invalid file format is specified (`236`_)
* Fixed multiple bayer captures with :meth:`~PiCamera.capture_sequence`
and :meth:`~PiCamera.capture_continuous` (`264`_)
* Fixed usage of "falsy" custom outputs with ``motion_output`` (`281`_)

Many thanks to the community, and especially thanks to 6by9 (one of the
firmware developers) who's fielded seemingly endless questions and
requests from me in the last couple of months!

.. _241: https://github.com/waveform80/picamera/issues/241
.. _257: https://github.com/waveform80/picamera/issues/257
.. _212: https://github.com/waveform80/picamera/issues/212
.. _279: https://github.com/waveform80/picamera/pull/279
.. _216: https://github.com/waveform80/picamera/issues/216
.. _240: https://github.com/waveform80/picamera/issues/240
.. _218: https://github.com/waveform80/picamera/issues/218
.. _228: https://github.com/waveform80/picamera/issues/228
.. _236: https://github.com/waveform80/picamera/issues/236
.. _264: https://github.com/waveform80/picamera/issues/264
.. _281: https://github.com/waveform80/picamera/issues/281
.. _296: https://github.com/waveform80/picamera/issues/296

* The major enhancement is the addition of support for the camera's flash
driver. This is relatively complex to configure, but a full recipe has been
included in the documentation (`184`_)
* A new `intra_refresh` attribute is added to the
:meth:`~PiCamera.start_recording` method permitting control of the
intra-frame refresh method (`193`_)
* The GPIO pins controlling the camera's LED are now configurable. This is
mainly for any compute module users, but also for anyone who wishes to use
the device tree blob to reconfigure the pins used (`198`_)
* The new annotate V3 struct is now supported, providing custom background
colors for annotations, and configurable text size. As part of this work a
new :class:`Color` class was introduced for representation and manipulation
of colors (`203`_)
* Reverse enumeration of frames in :class:`PiCameraCircularIO` is now supported
efficiently (without having to convert frames to a list first) (`204`_)
* Finally, the API documentation has been re-worked as it was getting too
large to comfortably load on all platforms (no ticket)

.. _184: https://github.com/waveform80/picamera/issues/184
.. _193: https://github.com/waveform80/picamera/issues/193
.. _198: https://github.com/waveform80/picamera/issues/198
.. _203: https://github.com/waveform80/picamera/issues/203
.. _204: https://github.com/waveform80/picamera/issues/204

* The camera's sensor mode can now be forced to a particular setting upon
camera initialization with the new ``sensor_mode`` parameter to
:class:`PiCamera` (`165`_)
* The camera's initial framerate and resolution can also be specified as
keyword arguments to the :class:`PiCamera` initializer. This is primarily
intended to reduce initialization time (`180`_)
* Added the :attr:`~PiCamera.still_stats` attribute which controls
whether an extra statistics pass is made when capturing images from the still
port (`166`_)
* Fixed the :attr:`~PiCamera.led` attribute so it should now work on
the Raspberry Pi model B+ (`170`_)
* Fixed a nasty memory leak in overlay renderers which caused the camera to run
out of memory when overlays were repeatedly created and destroyed (`174`_) *
Fixed a long standing issue with MJPEG recording which caused camera lockups
when resolutions greater than VGA were used (`47`_ and `179`_)
* Fixed a bug with incorrect frame metadata in :class:`PiCameraCircularIO`.
Unfortunately this required breaking backwards compatibility to some extent.
If you use this class and rely on the frame metadata, please familiarize
yourself with the new :attr:`~PiVideoFrame.complete` attribute (`177`_)
* Fixed a bug which caused :class:`PiCameraCircularIO` to ignore the splitter
port it was recording against (`176`_)
* Several documentation issues got fixed too (`167`_, `168`_, `171`_,
`172`_, `182`_)

Many thanks to the community for providing several of these fixes as pull
requests, and thanks for all the great bug reports. Happy new year everyone!

.. _47: https://github.com/waveform80/picamera/issues/47
.. _165: https://github.com/waveform80/picamera/issues/165
.. _166: https://github.com/waveform80/picamera/issues/166
.. _167: https://github.com/waveform80/picamera/issues/167
.. _168: https://github.com/waveform80/picamera/issues/168
.. _170: https://github.com/waveform80/picamera/issues/170
.. _171: https://github.com/waveform80/picamera/issues/171
.. _172: https://github.com/waveform80/picamera/pull/172
.. _174: https://github.com/waveform80/picamera/issues/174
.. _176: https://github.com/waveform80/picamera/pull/176
.. _177: https://github.com/waveform80/picamera/issues/177
.. _179: https://github.com/waveform80/picamera/pull/179
.. _180: https://github.com/waveform80/picamera/issues/180
.. _182: https://github.com/waveform80/picamera/issues/182

* A new chapter on detecting and correcting deprecated functionality was added
to the docs (`149`_)
* Stereoscopic cameras are now tentatively supported on the Pi compute module.
Please note I have no hardware for testing this, so the implementation is
possibly (probably!) wrong; bug reports welcome! (`153`_)
* Text annotation functionality has been extended; up to 255 characters are now
possible, and the new :attr:`~PiCamera.annotate_frame_num` attribute adds
rendering of the current frame number. In addition, the new
:attr:`~PiCamera.annotate_background` flag permits a dark background to be
rendered behind all annotations for contrast (`160`_)
* Arbitrary image overlays can now be drawn on the preview using the new
:meth:`~PiCamera.add_overlay` method. A new recipe has been included
demonstrating overlays from PIL images and numpy arrays. As part of this work
the preview system was substantially changed; all older scripts should
continue to work but please be aware that most preview attributes are now
deprecated; the new :attr:`~PiCamera.preview` attribute replaces them
(`144`_)
* Image effect parameters can now be controlled via the new
:attr:`~PiCamera.image_effect_params` attribute (`143`_)
* A bug in the handling of framerates meant that long exposures (>1s) weren't
operating correctly. This *should* be fixed, but I'd be grateful if users
could test this and let me know for certain (Exif metadata reports the
configured exposure speed so it can't be used to determine if things are
actually working) (`135`_)
* A bug in 1.7 broke compatibility with older firmwares (resulting in an error
message mentioning "mmal_queue_timedwait"). The library should now on older
firmwares (`154`_)
* Finally, the confusingly named :attr:`~PiCamera.crop` attribute was changed
to a deprecated alias for the new :attr:`~PiCamera.zoom` attribute (`146`_)

.. _135: https://github.com/waveform80/picamera/issues/135
.. _143: https://github.com/waveform80/picamera/issues/143
.. _144: https://github.com/waveform80/picamera/issues/144
.. _146: https://github.com/waveform80/picamera/issues/146
.. _149: https://github.com/waveform80/picamera/issues/149
.. _153: https://github.com/waveform80/picamera/issues/153
.. _154: https://github.com/waveform80/picamera/issues/154
.. _160: https://github.com/waveform80/picamera/issues/160