Skip to content

Commit

Permalink
More doc refinements
Browse files Browse the repository at this point in the history
  • Loading branch information
@waveform80
waveform80 committed Mar 18, 2016
1 parent c536767 commit f1dd5d6
Show file tree
Hide file tree
Showing 7 changed files with 158 additions and 145 deletions.
64 changes: 32 additions & 32 deletions picamera/array.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -197,9 +197,9 @@ class PiRGBArray(PiArrayOutput):
output.array.shape[1], output.array.shape[0]))
If you are using the GPU resizer when capturing (with the *resize*
parameter of the various :meth:`~picamera.camera.PiCamera.capture`
methods), specify the resized resolution as the optional *size* parameter
when constructing the array output::
parameter of the various :meth:`~PiCamera.capture` methods), specify the
resized resolution as the optional *size* parameter when constructing the
array output::
import picamera
import picamera.array
Expand Down Expand Up @@ -249,9 +249,9 @@ class PiYUVArray(PiArrayOutput):
print(output.rgb_array.shape)
If you are using the GPU resizer when capturing (with the *resize*
parameter of the various :meth:`~picamera.camera.PiCamera.capture`
methods), specify the resized resolution as the optional *size* parameter
when constructing the array output::
parameter of the various :meth:`~PiCamera.capture` methods), specify the
resized resolution as the optional *size* parameter when constructing the
array output::
import picamera
import picamera.array
Expand Down Expand Up @@ -297,11 +297,11 @@ class PiBayerArray(PiArrayOutput):
Produces a 3-dimensional RGB array from raw Bayer data.
This custom output class is intended to be used with the
:meth:`~picamera.camera.PiCamera.capture` method, with the *bayer*
parameter set to ``True``, to include raw Bayer data in the JPEG output.
The class strips out the raw data, constructing a 3-dimensional numpy array
organized as (rows, columns, colors). The resulting data is accessed via
the :attr:`~PiArrayOutput.array` attribute::
:meth:`~PiCamera.capture` method, with the *bayer* parameter set to
``True``, to include raw Bayer data in the JPEG output. The class strips
out the raw data, constructing a 3-dimensional numpy array organized as
(rows, columns, colors). The resulting data is accessed via the
:attr:`~PiArrayOutput.array` attribute::
import picamera
import picamera.array
Expand Down Expand Up @@ -426,12 +426,12 @@ class PiMotionArray(PiArrayOutput):
Produces a 3-dimensional array of motion vectors from the H.264 encoder.
This custom output class is intended to be used with the *motion_output*
parameter of the :meth:`~picamera.camera.PiCamera.start_recording` method.
Once recording has finished, the class generates a 3-dimensional numpy
array organized as (frames, rows, columns) where ``rows`` and ``columns``
are the number of rows and columns of `macro-blocks`_ (16x16 pixel blocks)
in the original frames. There is always one extra column of macro-blocks
present in motion vector data.
parameter of the :meth:`~PiCamera.start_recording` method. Once recording
has finished, the class generates a 3-dimensional numpy array organized as
(frames, rows, columns) where ``rows`` and ``columns`` are the number of
rows and columns of `macro-blocks`_ (16x16 pixel blocks) in the original
frames. There is always one extra column of macro-blocks present in motion
vector data.
The data-type of the :attr:`~PiArrayOutput.array` is an (x, y, sad)
structure where ``x`` and ``y`` are signed 1-byte values, and ``sad`` is an
Expand Down Expand Up @@ -535,13 +535,13 @@ class PiRGBAnalysis(PiAnalysisOutput):
Provides a basis for per-frame RGB analysis classes.
This custom output class is intended to be used with the
:meth:`~picamera.camera.PiCamera.start_recording` method when it is called
with *format* set to ``'rgb'`` or ``'bgr'``. While recording is in
progress, the :meth:`~PiAnalysisOutput.write` method converts incoming
frame data into a numpy array and calls the stub
:meth:`~PiAnalysisOutput.analyze` method with the resulting array (this
deliberately raises :exc:`NotImplementedError` in this class; you must
override it in your descendent class).
:meth:`~PiCamera.start_recording` method when it is called with *format*
set to ``'rgb'`` or ``'bgr'``. While recording is in progress, the
:meth:`~PiAnalysisOutput.write` method converts incoming frame data into a
numpy array and calls the stub :meth:`~PiAnalysisOutput.analyze` method
with the resulting array (this deliberately raises
:exc:`NotImplementedError` in this class; you must override it in your
descendent class).
.. note::
Expand All @@ -567,8 +567,8 @@ class PiYUVAnalysis(PiAnalysisOutput):
Provides a basis for per-frame YUV analysis classes.
This custom output class is intended to be used with the
:meth:`~picamera.camera.PiCamera.start_recording` method when it is called
with *format* set to ``'yuv'``. While recording is in progress, the
:meth:`~PiCamera.start_recording` method when it is called with *format*
set to ``'yuv'``. While recording is in progress, the
:meth:`~PiAnalysisOutput.write` method converts incoming frame data into a
numpy array and calls the stub :meth:`~PiAnalysisOutput.analyze` method
with the resulting array (this deliberately raises
Expand Down Expand Up @@ -601,11 +601,11 @@ class PiMotionAnalysis(PiAnalysisOutput):
Provides a basis for real-time motion analysis classes.
This custom output class is intended to be used with the *motion_output*
parameter of the :meth:`~picamera.camera.PiCamera.start_recording` method.
While recording is in progress, the write method converts incoming motion
data into numpy arrays and calls the stub :meth:`~PiAnalysisOutput.analyze`
method with the resulting array (which deliberately raises
:exc:`NotImplementedError` in this class).
parameter of the :meth:`~PiCamera.start_recording` method. While recording
is in progress, the write method converts incoming motion data into numpy
arrays and calls the stub :meth:`~PiAnalysisOutput.analyze` method with the
resulting array (which deliberately raises :exc:`NotImplementedError` in
this class).
.. note::
Expand Down Expand Up @@ -652,7 +652,7 @@ def analyze(self, a):
You can use the optional *size* parameter to specify the output resolution
of the GPU resizer, if you are using the *resize* parameter of
:meth:`~picamera.camera.PiCamera.start_recording`.
:meth:`~PiCamera.start_recording`.
"""

def __init__(self, camera, size=None):
Expand Down
74 changes: 50 additions & 24 deletions picamera/camera.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1128,10 +1128,16 @@ def start_recording(
Start recording video from the camera, storing it in *output*.
If *output* is a string, it will be treated as a filename for a new
file which the video will be written to. Otherwise, *output* is assumed
to be a file-like object and the video data is appended to it (the
file which the video will be written to. If *output* is not a string,
but is an object with a ``write`` method, it is assumed to be a
file-like object and the video data is appended to it (the
implementation only assumes the object has a ``write()`` method - no
other methods will be called).
other methods are required but ``flush`` will be called at the end of
recording if it is present). If *output* is not a string, and has no
``write`` method it is assumed to be a writeable object implementing
the buffer protocol. In this case, the video frames will be written
sequentially to the underlying buffer (which must be large enough to
accept all frame data).
If *format* is ``None`` (the default), the method will attempt to guess
the required video format from the extension of *output* (if it's a
Expand Down Expand Up @@ -1197,10 +1203,8 @@ def start_recording(
* *motion_output* - Indicates the output destination for motion vector
estimation data. When ``None`` (the default), motion data is not
output. If set to a string, it is assumed to be a filename which
should be opened for motion data to be written to. Any other value is
assumed to be a file-like object which motion vector is to be written
to (the object must have a ``write`` method).
output. Otherwise, this can be a filename string, a file-like object,
or a writeable buffer object (as with the *output* parameter).
All encoded formats accept the following additional options:
Expand Down Expand Up @@ -1229,6 +1233,9 @@ def start_recording(
.. versionchanged:: 1.5
The *quantization* parameter was deprecated in favor of *quality*,
and the *motion_output* parameter was added.
.. versionchanged:: 1.11
Support for buffer outputs was added.
"""
if 'quantization' in options:
warnings.warn(
Expand Down Expand Up @@ -1259,11 +1266,9 @@ def split_recording(self, output, splitter_port=1, **options):
current output (and close it, if it was specified as a filename), and
continue writing to the newly specified *output*.
If *output* is a string, it will be treated as a filename for a new
file which the video will be written to. Otherwise, *output* is assumed
to be a file-like object and the video data is appended to it (the
implementation only assumes the object has a ``write()`` method - no
other methods will be called).
The *output* parameter is treated as in the :meth:`start_recording`
method (it can be a string, a file-like object, or a writeable
buffer object).
The *motion_output* parameter can be used to redirect the output of the
motion vector data in the same fashion as *output*. If *motion_output*
Expand All @@ -1290,6 +1295,9 @@ def split_recording(self, output, splitter_port=1, **options):
.. versionchanged:: 1.5
The *motion_output* parameter was added
.. versionchanged:: 1.11
Support for buffer outputs was added.
"""
try:
with self._encoders_lock:
Expand Down Expand Up @@ -1464,10 +1472,16 @@ def capture(
Capture an image from the camera, storing it in *output*.
If *output* is a string, it will be treated as a filename for a new
file which the image will be written to. Otherwise, *output* is assumed
to a be a file-like object and the image data is appended to it (the
implementation only assumes the object has a ``write()`` method - no
other methods will be called).
file which the image will be written to. If *output* is not a string,
but is an object with a ``write`` method, it is assumed to be a
file-like object and the image data is appended to it (the
implementation only assumes the object has a ``write`` method - no
other methods are required but ``flush`` will be called at the end of
capture if it is present). If *output* is not a string, and has no
``write`` method it is assumed to be a writeable object implementing
the buffer protocol. In this case, the image data will be written
directly to the underlying buffer (which must be large enough to accept
the image data).
If *format* is ``None`` (the default), the method will attempt to guess
the required image format from the extension of *output* (if it's a
Expand Down Expand Up @@ -1547,6 +1561,9 @@ def capture(
The *splitter_port* parameter was added, and *bayer* was added as
an option for the ``'jpeg'`` format
.. versionchanged:: 1.11
Support for buffer outputs was added.
.. _definitions of quality: http://photo.net/learn/jpeg/#qual
"""
if format == 'raw':
Expand Down Expand Up @@ -1588,9 +1605,9 @@ def capture_sequence(
This method accepts a sequence or iterator of *outputs* each of which
must either be a string specifying a filename for output, or a
file-like object with a ``write`` method. For each item in the sequence
or iterator of outputs, the camera captures a single image as fast as
it can.
file-like object with a ``write`` method, or a writeable buffer object.
For each item in the sequence or iterator of outputs, the camera
captures a single image as fast as it can.
The *format*, *use_video_port*, *splitter_port*, *resize*, and
*options* parameters are the same as in :meth:`capture`, but *format*
Expand Down Expand Up @@ -1645,6 +1662,9 @@ def capture_sequence(
.. versionchanged:: 1.3
The *splitter_port* parameter was added
.. versionchanged:: 1.11
Support for buffer outputs was added.
"""
if use_video_port and burst:
raise PiCameraRuntimeError(
Expand Down Expand Up @@ -1741,11 +1761,14 @@ def capture_continuous(
format string (multiple times too!) although this tends to be
redundant.
If *output* is not a string, it is assumed to be a file-like object
and each image is simply written to this object sequentially. In this
case you will likely either want to write something to the object
between the images to distinguish them, or clear the object between
iterations.
If *output* is not a string, but has a ``write`` method, it is assumed
to be a file-like object and each image is simply written to this
object sequentially. In this case you will likely either want to write
something to the object between the images to distinguish them, or
clear the object between iterations. If *output* is not a string, and
has no ``write`` method, it is assumed to be a writeable object
supporting the buffer protocol; each image is simply written to the
buffer sequentially.
The *format*, *use_video_port*, *splitter_port*, *resize*, and
*options* parameters are the same as in :meth:`capture`.
Expand Down Expand Up @@ -1800,6 +1823,9 @@ def capture_continuous(
.. versionchanged:: 1.3
The *splitter_port* parameter was added
.. versionchanged:: 1.11
Support for buffer outputs was added.
"""
if use_video_port and burst:
raise PiCameraRuntimeError(
Expand Down
52 changes: 24 additions & 28 deletions picamera/encoders.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,14 +84,13 @@ class PiEncoder(object):
"""
Base implementation of an MMAL encoder for use by PiCamera.
The *parent* parameter specifies the :class:`~picamera.camera.PiCamera`
instance that has constructed the encoder. The *camera_port* parameter
provides the MMAL camera port that the encoder should enable for capture
(this will be the still or video port of the camera component). The
*input_port* parameter specifies the MMAL port that the encoder should
connect to its input. Sometimes this will be the same as the camera port,
but if other components are present in the pipeline (e.g. a splitter), it
may be different.
The *parent* parameter specifies the :class:`PiCamera` instance that has
constructed the encoder. The *camera_port* parameter provides the MMAL
camera port that the encoder should enable for capture (this will be the
still or video port of the camera component). The *input_port* parameter
specifies the MMAL port that the encoder should connect to its input.
Sometimes this will be the same as the camera port, but if other components
are present in the pipeline (e.g. a splitter), it may be different.
The *format* parameter specifies the format that the encoder should
produce in its output. This is specified as a string and will be one of
Expand Down Expand Up @@ -185,8 +184,7 @@ class PiEncoder(object):
.. attribute:: parent
The :class:`~picamera.camera.PiCamera` instance that created this
PiEncoder instance.
The :class:`PiCamera` instance that created this PiEncoder instance.
.. attribute:: pool
Expand Down Expand Up @@ -476,7 +474,7 @@ def _open_output(self, output, key=PiVideoFrameType.frame):
file-like object and it is used verbatim. If *output* is neither a
string, nor an object with a ``write`` method it is assumed to be a
writeable object supporting the buffer protocol (this is wrapped in
a :class:`~picamera.streams.BufferIO` stream to simplify writing).
a :class:`BufferIO` stream to simplify writing).
The opened output is added to the :attr:`outputs` dictionary with the
specified *key*.
Expand Down Expand Up @@ -752,12 +750,11 @@ class PiVideoEncoder(PiEncoder):
This derivative of :class:`PiEncoder` configures itself for H.264 or MJPEG
encoding. It also introduces a :meth:`split` method which is used by
:meth:`~picamera.camera.PiCamera.split_recording` and
:meth:`~picamera.camera.PiCamera.record_sequence` to redirect future output
to a new filename or object. Finally, it also extends
:meth:`PiEncoder.start` and :meth:`PiEncoder._callback_write` to track
video frame meta-data, and to permit recording motion data to a separate
output object.
:meth:`~PiCamera.split_recording` and :meth:`~PiCamera.record_sequence` to
redirect future output to a new filename or object. Finally, it also
extends :meth:`PiEncoder.start` and :meth:`PiEncoder._callback_write` to
track video frame meta-data, and to permit recording motion data to a
separate output object.
"""

encoder_type = mmal.MMAL_COMPONENT_DEFAULT_VIDEO_ENCODER
Expand Down Expand Up @@ -967,11 +964,10 @@ def split(self, output, motion_output=None):
"""
Called to switch the encoder's output.
This method is called by
:meth:`~picamera.camera.PiCamera.split_recording` and
:meth:`~picamera.camera.PiCamera.record_sequence` to switch the
encoder's :attr:`output` object to the *output* parameter (which can be
a filename or a file-like object, as with :meth:`start`).
This method is called by :meth:`~PiCamera.split_recording` and
:meth:`~PiCamera.record_sequence` to switch the encoder's
:attr:`output` object to the *output* parameter (which can be a
filename or a file-like object, as with :meth:`start`).
"""
with self.outputs_lock:
outputs = {}
Expand Down Expand Up @@ -1070,8 +1066,8 @@ class PiRawVideoEncoder(PiRawMixin, PiVideoEncoder):
This class is a derivative of :class:`PiVideoEncoder` and the
:class:`PiRawMixin` class intended for use with
:meth:`~picamera.camera.PiCamera.start_recording` when it is called with an
unencoded format.
:meth:`~PiCamera.start_recording` when it is called with an unencoded
format.
.. warning::
Expand Down Expand Up @@ -1314,8 +1310,8 @@ class PiRawOneImageEncoder(PiOneImageEncoder, PiRawImageMixin):
This class is a derivative of :class:`PiOneImageEncoder` and the
:class:`PiRawImageMixin` class intended for use with
:meth:`~picamera.camera.PiCamera.capture` (et al) when it is called with an
unencoded image format.
:meth:`~PiCamera.capture` (et al) when it is called with an unencoded image
format.
.. warning::
Expand All @@ -1331,8 +1327,8 @@ class PiRawMultiImageEncoder(PiMultiImageEncoder, PiRawImageMixin):
This class is a derivative of :class:`PiMultiImageEncoder` and the
:class:`PiRawImageMixin` class intended for use with
:meth:`~picamera.camera.PiCamera.capture_sequence` when it is called with
an unencoded image format.
:meth:`~PiCamera.capture_sequence` when it is called with an unencoded
image format.
.. warning::
Expand Down

0 comments on commit f1dd5d6

Please sign in to comment.