packaging: Move all "common" into private package _stbt

With the dockerized tools coming up in stb-tester we want to use some of
the stb-tester functionality without incurring a dependency on the rest.
e.g. stbt service needs get/set_config but doesn't need a dependency on
GStreamer or OpenCV.  This has not been possible as all our code was in
a single `stbt.py` file.  The re-organisation 8ae1c0c split `stbt.py` up
into multiple files, but you still couldn't `import stbt.config` without
incurring a dependency on GStreamer.

This commit splits the stbt package into a private package `_stbt` with
no hard dependencies and a public one `stbt` with all of them.  Our
internal tools can now `import _stbt.config` etc. without hacks to
`PYTHONPATH`, etc to get import resolution to work.  It has the secondary
beneficial effect that our users won't think that `import stbt.config` is
a valid thing to do.  We still only officially support `import stbt`.
packaging: Rename `config._set_config` to `config.set_config`

`set_config` is internal to stbt, not internal to config.py.
tests: Fix run-tests.sh's bash-completion on Ubuntu

The default awk implementation on Ubuntu is mawk, which doesn't like
"()" in the pattern part of the awk program. Escaping the parentheses
with backslashes works with both gawk and mawk.

Oddly mawk doesn't complain about the bare parens in the "-F" pattern,
but I can't escape those for consistency because then gawk complains.
.travis.yml: Upgrade pylint to 1.3.1

Now that https://bitbucket.org/logilab/astroid/issue/42 has been fixed.

I had to add a missing W0703 annotation (Catching too general exception)
that wasn't previously caught by pylint.

Pylint now ignores the "include-ids=yes" config setting, so I've removed
it to silence all the associated warnings. stb-tester developers should
upgrade to pylint 1.3.1.
make check-pylint: Silence libdc1394 warning
Merge pull request #223 from drothlis/pylint-1.3

Upgrade Pylint on Travis to 1.3
docs: Document pipeline rationale in the code
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