fedora: Add script for testing Fedora packaging
fedora packaging test: Show the manpage for manual inspection

I noticed "ImportError: No module named cv2" when it runs `make doc` as
part of building the RPM, but this easily gets lost in the noise. I'm
not even sure if this will cause a problem in the manpage (seeing as we
commit the changes to README.rst made by `make doc`) so I'm printing the
final manpage to the terminal so you can inspect it.
make check: Don't run integration tests with `PYTHONPATH` set

Since 4ffa6b6 we run our integration tests against an installed version
of stb-tester.  This is great because it is more representative of how
stb-tester will actually be used.  This commit is a further step in this
direction by making PYTHONPATH not point at the source directory, as in
production there is no source directory.

I implemented this while working on Smart TV support as I came across some
problems with imports when using `stbt camera` from the installed
location.  With this change the tests will now catch these issues.
utils: Our `mkdir -p` implementation should raise on error

rather than just returning False.  This makes it closer to Python 3's
`os.makedirs(..., exist_ok=True)`.  Up till now there were just two
users of this function.  One which wanted throwing behaviour and the
other wanted `return False` behaviour.  Future commits will introduce
further users of `mkdir` which want throwing behaviour.
Refactor: Make `xdg_config_dir` package private

rather than module private, so we can make use of it in other places.
Smart TV Support: Add command stbt camera

Entry point for stb-tester support for pointing a camera at a TV.  It is
just a placeholder for now.  Real functionality will be added in later
commits.

Building camera support is optional, as is installing it with rpm/deb as
the packages are split into stb-tester and stb-tester-camera.  This will
allow expressing additional dependencies required for camera support but
not for the rest.

stbt camera is experimental for now.  Until we're happy with it you will
have to call it with:

    stbt --with-experimental camera ...

While I expect that the interface will stay roughly the same there are
many details that may change.  This should avoid our users mistaking it
for something completely stable and supported.
Smart TV Support: Add helper library for generating videos based on stills

Calibrating the camera for Smart TV support requires displaying
reference videos on the TV.  We will generate these videos on the fly
to make it easier to change them and it means we don't need to ship
100s of MB of video files with the stb-tester package.

This commit adds helper functions for generating video files based on
a series of stills.  These stills are provided as a Python sequence so
a generator of stills can be used.  This can be used to great effect
for creating dynamic videos by providing a generator which yields SVGs
modified on the fly.

`frames_to_video` generates MPEG4+AAC videos in either a mpeg-ts
container or MP4.  This is configurable because my Panasonic TV doesn't
like mpeg-ts and my Samsung TV doesn't like MP4.
Smart TV Support: Add tv driver

Calibrating the camera for Smart TV support requires displaying
reference videos on the TV.  This commit introduces an abstraction
"TV Driver", an instance of which will control the TV by some means
to display a given named video.  TV Driver generates videos on the fly
based on configuration passed in on construction (via
`tv_driver.create_from_args`).

The idea is that there might be multiple ways of getting a TV to display
a video, e.g. via DLNA or modulator support.  This commit introduces
a lowest-common-denominator approach "manual" where it's up to the user
to make the video be displayed.  We just provide them with an HTTP URL
from which to download the video.

lighttpd is used to host the videos becuase my Panasonic TV did not get
along with Python's SimpleHTTPServer.  Probably because it was single-
threaded or maybe SimpleHTTPServer doesn't support range requests.
Smart TV Support: Add fake TV driver for testing

A "TV Driver" allows us to display a reference video on the TV.  See
previous commit for more details.

This commit adds a TV Driver for testing so we can fake out the
TV/capture hardware to allow us to test the smart TV calibration/
validation steps which require control over the TV.

The fake-video-src introduced here may be very useful in the future for
testing other parts of stb-tester.  It produces "live" video so is more
like using real hardware than a canned stream and provides more
flexibility than videotestsrc.
Smart TV support: Add command stbt camera validate

stbt camera validate is intended to measure the quality of video capture
that a camera (plus the software corrections to that camera) provides.

It displays a big grid of characters on the TV and then searches for each
one with `wait_for_match`.  It will report whether it found the character
in the right position and whether it matched or not.

To detect issues with brighness compensation the tests are repeated with
text black-on-white, white-on-black, light-grey-on-dark-grey and dark-
grey-on-light-grey.
Smart TV Support: Add stbt camera calibrate

`stbt camera calibrate` will be used to setup camera support.  It's
currently just a placeholder but real functionality will be introduced
in later commits.
Smart TV Support: Add GStreamer plugin

Smart TV Support will introduce two GStreamer elements.  GStreamer
elements are complied into a GStreamer plugin in the form of a shared
library.

This commit introduces the (empty) plugin.  I seperated it from the
commits that introduce the elements as as can be seen from this commit it
involves a bunch of boilerplate and build changes.  It adds an optional
build-time/test-time dependency on a C compiler, OpenCV development
headers and GStreamer development headers.  If they are not installed the
GStreamer element will not be built.
Smart TV Support: Perform geometric correction to reconstruct TV image

Like set-top boxes, Smart TVs run complex software, including software
not provided by the manufacturer (e.g. apps).  Unlike set-top boxes they
provide no digital video output - the only video output they provide is
to screen.  So to support testing software running on TVs we need to
capture the contents of the TV screen.

We plan to do this with a webcam and some image processing to get the
contents of the screen such that we can feed that into GStreamer.  The
image processing will correct for problems with the positioning of the
camera and issues with the lens (which we will call "flattening") as well
as problems with the colours and brighness of the pixels.

This commit adds a GStreamer element `stbtgeometriccorrection` which
flattens the image by first undoing distortions due to the camera lens
and then extracting the region in the undistorted image that corresponds
to the TV (homography) like:

                  |----------------------------|
    1080p         |  stbtgeometriccorrection   |        720p
  Image from  --> |                            | --> Contents of
    Camera        | Undistort  --> Perspective |         TV
                  |----------------------------|

Undistort is parameterised by the properties:

* `camera-matrix` - A 3x3 matrix of the form:

        f_x   0   c_x
         0   f_y  c_y
         0    0    1

* `distortion-coefficients` - 5 values of the form:

        k_1, k_2, p_1, p_2, k_3

The perspective transformation is parameterised by the property:

* `homography-matrix` - A 3x3 matrix.

See the OpenCV documentation for more information[1].

The combined undistort/perspective transformation is actually done in one
operation.  We create a 1280x720 matrix where each "pixel" contains (x, y)
coordinates of where the real pixel value should be taken from in the
source 1080p image.  The OpenCV function `cvRemap` then justs looks
through this matrix to produce a 720p image from the 1080p input.

We generate this remapping matrix by tracing pixel locations from the 720p
image back through to the location on the 1080p image.  This means doing
the reverse perspective transformation on the coordinates and then
distorting the coordinates.

`stbt camera calibrate` is enhanced to generate the parameters described
above by displaying an image of a chessboard on the TV and then comparing
the measured values to the expected ones.

In test with real life TVs this calibration/correction achieves pixel
perfect positioning according to `stbt camera validate`.

[1]: http://docs.opencv.org/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html
Smart TV Support: Add stbtcontraststretch element

The goal of stbt camera is to reconstruct the image sent to the TV panel
based on video recorded from a camera.  Even after careful calibration of
the camera and TV the brightness of a pixel measured at the camera may
differ from the ideal because:

* The camera suffers from vignetting (darkening at the edges)
* The TV backlight is uneven
* The received brightness of a pixel is angle dependent
* There are reflections on the screen
* Or other reasons

To deal with this location dependent brightness differences we perform
simple contrast stretching.  We take a picture with the TV displaying at
full intensity (white) and at minimum (black).  We then use these images
to scale the brightness of each individual pixel such that black becomes
black and white becomes white.

The stretching is dumb in that it assumes a linear colour-space, and is
not based on some underlying physical model.  It should probably take
Gamma into account, but it seems to work fairly well for the purposes
of image matching.  This can be revisited in the future if it turns out
to be insufficient.

This commit introduces the GStreamer element contraststretch to perform
this stretching on the video and corresponding changes to `stbt camera
calibrate` to capture the white and black images.  The core of the
implementation is written in the SIMD assembly language "orc" as used by
many GStreamer elements.  I measured this to be significantly faster than
the same algorithm implemented in C.
Smart TV Support: Calibration: Add interactive colour adjustment

This calibration step is intended help adjusting the camera/TV settings
so the received pixel values are as close as possible to what we are
expecting.  It is best to do this calibration in the camera itself rather
than in software as all software adjustments are lossy, whereas adjusting
the optics/apature times, etc. in the camera before compression should be
less so.

With this commit the calibration process will show a graph of received vs.
ideal colour values and allow the user to adjust the v4l controls to make
them match as closely as possible.