Major re-work of docs

Moved all examples into separate files for ease of testing; added
unconvetional files output section (fixes some ticket ... can't find it
at the moment!)

docs/Makefile

@@ -6,10 +6,17 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
-DOT_DIAGRAMS  = $(wildcard *.dot)
-MSC_DIAGRAMS  = $(wildcard *.mscgen)
-SVG_IMAGES    = $(wildcard *.svg) $(DOT_DIAGRAMS:%.dot=%.svg) $(MSC_DIAGRAMS:%.mscgen=%.svg)
-PDF_IMAGES    = $(SVG_IMAGES:%.svg=%.pdf)
+DOT_DIAGRAMS  := $(wildcard images/*.dot)
+MSC_DIAGRAMS  := $(wildcard images/*.mscgen)
+GPI_DIAGRAMS  := $(wildcard images/*.gpi)
+SVG_IMAGES    := $(wildcard images/*.svg) $(DOT_DIAGRAMS:%.dot=%.svg) $(MSC_DIAGRAMS:%.mscgen=%.svg)
+PNG_IMAGES    := $(wildcard images/*.png) $(GPI_DIAGRAMS:%.gpi=%.png) $(SVG_IMAGES:%.svg=%.png)
+PDF_IMAGES    := $(SVG_IMAGES:%.svg=%.pdf) $(GPI_DIAGRAMS:%.gpi=%.pdf) $(DOT_DIAGRAMS:%.dot=%.pdf) $(MSC_DIAGRAMS:%.mscgen=%.pdf)
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -46,17 +53,17 @@ help:
 clean:
 	rm -rf $(BUILDDIR)/*
 
-html: $(SVG_IMAGES)
+html: $(SVG_IMAGES) $(PNG_IMAGES)
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-dirhtml: $(SVG_IMAGES)
+dirhtml: $(SVG_IMAGES) $(PNG_IMAGES)
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
-singlehtml: $(SVG_IMAGES)
+singlehtml: $(SVG_IMAGES) $(PNG_IMAGES)
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
@@ -173,13 +180,25 @@ pseudoxml:
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
 
-%.svg: %.msc
+%.svg: %.mscgen
 	mscgen -T svg -o $@ $<
 
 %.svg: %.dot
 	dot -T svg -o $@ $<
 
+%.png: %.gpi common.gp
+	gnuplot -e "set term pngcairo size 640,480" $< > $@
+
+%.png: %.svg
+	inkscape -e $@ $<
+
 %.pdf: %.svg
 	inkscape -A $@ $<
 
+%.pdf: %.gpi common.gp
+	gnuplot -e "set term pdfcairo size 10cm,7.5cm" $< > $@
+
+%.pdf: %.mscgen
+	mscgen -T eps -o - $< | ps2pdf -dEPSCrop - $@
+
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext

docs/api_encoders.rst

@@ -14,7 +14,7 @@ for :ref:`custom_encoders`.
 
 The inheritance diagram for the following classes is displayed below:
 
-.. image:: encoder_classes.*
+.. image:: images/encoder_classes.*
     :align: center
 
 

docs/conf.py

@@ -69,7 +69,7 @@ def __getattr__(cls, name):
 
 # -- General configuration ------------------------------------------------
 
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx', 'sphinx.ext.imgmath']
 templates_path = ['_templates']
 source_suffix = '.rst'
 #source_encoding = 'utf-8-sig'
@@ -88,6 +88,7 @@ def __getattr__(cls, name):
 pygments_style = 'sphinx'
 #modindex_common_prefix = []
 #keep_warnings = False
+imgmath_image_format = 'svg'
 
 # -- Autodoc configuration ------------------------------------------------
 

docs/development.rst

@@ -57,9 +57,7 @@ within a virtual Python environment:
     (picamera) $ cd picamera
     (picamera) $ make develop
 
-The additional dependencies (like texlive, graphviz, inkscape, libjpeg, and
-libav-tools) are required for building the documentation and running the test
-suite. To pull the latest changes from git into your clone and update your
+To pull the latest changes from git into your clone and update your
 installation:
 
 .. code-block:: console

docs/examples/array_capture_py2.py

@@ -0,0 +1,12 @@
+import time
+import picamera
+import numpy as np
+
+with picamera.PiCamera() as camera:
+    camera.resolution = (100, 100)
+    camera.framerate = 24
+    time.sleep(2)
+    output = np.empty((112 * 128 * 3,), dtype=np.uint8)
+    camera.capture(output, 'rgb')
+    output = output.reshape((112, 128, 3))
+    output = output[:100, :100, :]

docs/examples/array_capture_py3.py

@@ -0,0 +1,10 @@
+import time
+import picamera
+import numpy as np
+
+with picamera.PiCamera() as camera:
+    camera.resolution = (320, 240)
+    camera.framerate = 24
+    time.sleep(2)
+    output = np.empty((240, 320, 3), dtype=np.uint8)
+    camera.capture(output, 'rgb')

docs/examples/bayer_array.py

@@ -0,0 +1,13 @@
+import time
+import picamera
+import picamera.array
+import numpy as np
+
+with picamera.PiCamera() as camera:
+    with picamera.array.PiBayerArray(camera) as stream:
+        camera.capture(stream, 'jpeg', bayer=True)
+        # Demosaic data and write to output (just use stream.array if you
+        # want to skip the demosaic step)
+        output = (stream.demosaic() >> 2).astype(np.uint8)
+        with open('image.data', 'wb') as f:
+            output.tofile(f)

docs/examples/bayer_data.py

@@ -0,0 +1,159 @@
+from __future__ import (
+    unicode_literals,
+    absolute_import,
+    print_function,
+    division,
+    )
+
+
+import io
+import time
+import picamera
+import numpy as np
+from numpy.lib.stride_tricks import as_strided
+
+stream = io.BytesIO()
+with picamera.PiCamera() as camera:
+    # Let the camera warm up for a couple of seconds
+    time.sleep(2)
+    # Capture the image, including the Bayer data
+    camera.capture(stream, format='jpeg', bayer=True)
+    ver = {
+        'RP_ov5647': 1,
+        'RP_imx219': 2,
+        }[camera.exif_tags['IFD0.Model']]
+
+# Extract the raw Bayer data from the end of the stream, check the
+# header and strip if off before converting the data into a numpy array
+
+offset = {
+    1: 6404096,
+    2: 10270208,
+    }[ver]
+data = stream.getvalue()[-offset:]
+assert data[:4] == 'BRCM'
+data = data[32768:]
+data = np.fromstring(data, dtype=np.uint8)
+
+# For the V1 module, the data consists of 1952 rows of 3264 bytes of data.
+# The last 8 rows of data are unused (they only exist because the maximum
+# resolution of 1944 rows is rounded up to the nearest 16).
+#
+# For the V2 module, the data consists of 2480 rows of 4128 bytes of data.
+# There's actually 2464 rows of data, but the sensor's raw size is 2466
+# rows, rounded up to the nearest multiple of 16: 2480.
+#
+# Likewise, the last few bytes of each row are unused (why?). Here we
+# reshape the data and strip off the unused bytes.
+
+reshape, crop = {
+    1: ((1952, 3264), (1944, 3240)),
+    2: ((2480, 4128), (2464, 4100)),
+    }[ver]
+data = data.reshape(reshape)[:crop[0], :crop[1]]
+
+# Horizontally, each row consists of 10-bit values. Every four bytes are
+# the high 8-bits of four values, and the 5th byte contains the packed low
+# 2-bits of the preceding four values. In other words, the bits of the
+# values A, B, C, D and arranged like so:
+#
+#  byte 1   byte 2   byte 3   byte 4   byte 5
+# AAAAAAAA BBBBBBBB CCCCCCCC DDDDDDDD AABBCCDD
+#
+# Here, we convert our data into a 16-bit array, shift all values left by
+# 2-bits and unpack the low-order bits from every 5th byte in each row,
+# then remove the columns containing the packed bits
+
+data = data.astype(np.uint16) << 2
+for byte in range(4):
+    data[:, byte::5] |= ((data[:, 4::5] >> ((4 - byte) * 2)) & 0b11)
+data = np.delete(data, np.s_[4::5], 1)
+
+# Now to split the data up into its red, green, and blue components. The
+# Bayer pattern of the OV5647 sensor is BGGR. In other words the first
+# row contains alternating green/blue elements, the second row contains
+# alternating red/green elements, and so on as illustrated below:
+#
+# GBGBGBGBGBGBGB
+# RGRGRGRGRGRGRG
+# GBGBGBGBGBGBGB
+# RGRGRGRGRGRGRG
+#
+# Please note that if you use vflip or hflip to change the orientation
+# of the capture, you must flip the Bayer pattern accordingly
+
+rgb = np.zeros(data.shape + (3,), dtype=data.dtype)
+rgb[1::2, 0::2, 0] = data[1::2, 0::2] # Red
+rgb[0::2, 0::2, 1] = data[0::2, 0::2] # Green
+rgb[1::2, 1::2, 1] = data[1::2, 1::2] # Green
+rgb[0::2, 1::2, 2] = data[0::2, 1::2] # Blue
+
+# At this point we now have the raw Bayer data with the correct values
+# and colors but the data still requires de-mosaicing and
+# post-processing. If you wish to do this yourself, end the script here!
+#
+# Below we present a fairly naive de-mosaic method that simply
+# calculates the weighted average of a pixel based on the pixels
+# surrounding it. The weighting is provided by a byte representation of
+# the Bayer filter which we construct first:
+
+bayer = np.zeros(rgb.shape, dtype=np.uint8)
+bayer[1::2, 0::2, 0] = 1 # Red
+bayer[0::2, 0::2, 1] = 1 # Green
+bayer[1::2, 1::2, 1] = 1 # Green
+bayer[0::2, 1::2, 2] = 1 # Blue
+
+# Allocate an array to hold our output with the same shape as the input
+# data. After this we define the size of window that will be used to
+# calculate each weighted average (3x3). Then we pad out the rgb and
+# bayer arrays, adding blank pixels at their edges to compensate for the
+# size of the window when calculating averages for edge pixels.
+
+output = np.empty(rgb.shape, dtype=rgb.dtype)
+window = (3, 3)
+borders = (window[0] - 1, window[1] - 1)
+border = (borders[0] // 2, borders[1] // 2)
+
+rgb = np.pad(rgb, [
+    (border[0], border[0]),
+    (border[1], border[1]),
+    (0, 0),
+    ], 'constant')
+bayer = np.pad(bayer, [
+    (border[0], border[0]),
+    (border[1], border[1]),
+    (0, 0),
+    ], 'constant')
+
+# For each plane in the RGB data, we use a nifty numpy trick
+# (as_strided) to construct a view over the plane of 3x3 matrices. We do
+# the same for the bayer array, then use Einstein summation on each
+# (np.sum is simpler, but copies the data so it's slower), and divide
+# the results to get our weighted average:
+
+for plane in range(3):
+    p = rgb[..., plane]
+    b = bayer[..., plane]
+    pview = as_strided(p, shape=(
+        p.shape[0] - borders[0],
+        p.shape[1] - borders[1]) + window, strides=p.strides * 2)
+    bview = as_strided(b, shape=(
+        b.shape[0] - borders[0],
+        b.shape[1] - borders[1]) + window, strides=b.strides * 2)
+    psum = np.einsum('ijkl->ij', pview)
+    bsum = np.einsum('ijkl->ij', bview)
+    output[..., plane] = psum // bsum
+
+# At this point output should contain a reasonably "normal" looking
+# image, although it still won't look as good as the camera's normal
+# output (as it lacks vignette compensation, AWB, etc).
+#
+# If you want to view this in most packages (like GIMP) you'll need to
+# convert it to 8-bit RGB data. The simplest way to do this is by
+# right-shifting everything by 2-bits (yes, this makes all that
+# unpacking work at the start rather redundant...)
+
+output = (output >> 2).astype(np.uint8)
+with open('image.data', 'wb') as f:
+    output.tofile(f)
+

docs/examples/capture_client.py

@@ -0,0 +1,45 @@
+import io
+import socket
+import struct
+import time
+import picamera
+
+# Connect a client socket to my_server:8000 (change my_server to the
+# hostname of your server)
+client_socket = socket.socket()
+client_socket.connect(('my_server', 8000))
+
+# Make a file-like object out of the connection
+connection = client_socket.makefile('wb')
+try:
+    camera = picamera.PiCamera()
+    camera.resolution = (640, 480)
+    # Start a preview and let the camera warm up for 2 seconds
+    camera.start_preview()
+    time.sleep(2)
+
+    # Note the start time and construct a stream to hold image data
+    # temporarily (we could write it directly to connection but in this
+    # case we want to find out the size of each capture first to keep
+    # our protocol simple)
+    start = time.time()
+    stream = io.BytesIO()
+    for foo in camera.capture_continuous(stream, 'jpeg'):
+        # Write the length of the capture to the stream and flush to
+        # ensure it actually gets sent
+        connection.write(struct.pack('<L', stream.tell()))
+        connection.flush()
+        # Rewind the stream and send the image data over the wire
+        stream.seek(0)
+        connection.write(stream.read())
+        # If we've been capturing for more than 30 seconds, quit
+        if time.time() - start > 30:
+            break
+        # Reset the stream for the next capture
+        stream.seek(0)
+        stream.truncate()
+    # Write a length of zero to the stream to signal we're done
+    connection.write(struct.pack('<L', 0))
+finally:
+    connection.close()
+    client_socket.close()

docs/examples/capture_server.py

@@ -0,0 +1,34 @@
+import io
+import socket
+import struct
+from PIL import Image
+
+# Start a socket listening for connections on 0.0.0.0:8000 (0.0.0.0 means
+# all interfaces)
+server_socket = socket.socket()
+server_socket.bind(('0.0.0.0', 8000))
+server_socket.listen(0)
+
+# Accept a single connection and make a file-like object out of it
+connection = server_socket.accept()[0].makefile('rb')
+try:
+    while True:
+        # Read the length of the image as a 32-bit unsigned int. If the
+        # length is zero, quit the loop
+        image_len = struct.unpack('<L', connection.read(struct.calcsize('<L')))[0]
+        if not image_len:
+            break
+        # Construct a stream to hold the image data and read the image
+        # data from the connection
+        image_stream = io.BytesIO()
+        image_stream.write(connection.read(image_len))
+        # Rewind the stream, open it as an image with PIL and do some
+        # processing on it
+        image_stream.seek(0)
+        image = Image.open(image_stream)
+        print('Image is %dx%d' % image.size)
+        image.verify()
+        print('Image is verified')
+finally:
+    connection.close()
+    server_socket.close()