Avoid pylint errors for members of namedtuples

Pylint isn't smart enough to know about the members of namedtuples, and
it's annoying to be adding pylint "ignore" annotations everywhere.
tests/run-performance-test.sh: Don't measure `stbt run` startup time

To get more accurate measurements of the time spent in the image
processing algorithm.

This also allows testing the speed of the match algorithm when the
template image is/isn't present in the video; uncomment the "if not
m.match" block if you only want to measure the initial frames of the
video that do match the template.
stbt._match_template: Refactor into first pass and `_confirm_match`

This is in preparation for the next commit.
stbt._match: Performance optimisation by using "pyramid" matching

The most expensive part of the image-matching algorithm is the call
to OpenCV's "matchTemplate" function, which compares the template image
against each possible position within the source image.

The new "pyramid" algorithm downsamples (shrinks) the source & template
images to half their width & height (thus 1/4 of the total pixels)
before passing them to the matchTemplate function. If a likely match is
identified, we then call matchTemplate with the source & template images
at their full size, but restricting matchTemplate's search to the areas
identified as potential matches during the previous level. This process
can be repeated more than once, for example starting from images 1/4 of
the original width & height (1/16 the total pixels).

At the smaller image size, if we identify a match, we always check again
at the larger size. So this algorithm won't introduce false positives
(false matches).

At the smaller image size, if we *don't* identify a match, we return a
"no match" decision immediately. This might introduce false negatives
due to differences between the smaller images that weren't present in
the originals; one of the next commits accounts for this by making the
match threshold more tolerant at the smaller levels of the pyramid.

You can disable this optimisation by setting "match.pyramid_levels" (in
your configuration file) to 1.

Once you add the fixes in the next 3 commits, all stb-tester's unit
tests continue to pass; I have also tested the functionality against a
private collection of 60 template images and 100 source images, and all
6,000 comparisons continue to yield the correct result (checking every
template against every source image; some of the combinations are
expected to match, others are expected to not match because every
template is not present in every image).

The performance improvement, as measured by
tests/run-performance-test.sh against a 720p video:

    before: 3.0fps; after: 35fps

But note that every frame in the video was a "no match", so the image
matching algorithm returned early. Measured using the same script and
video, with a template of the same size that does match:

    before: 2.8fps; after: 19fps

Each measurement was from the best of three runs, on my laptop with
dual-core 1.8GHz Intel Core i7, with the next 3 commits also applied,
and with templates sized 160x57 pixels (large enough for all 3 pyramid
levels to be used).
stbt._match: Don't halve the size of very small template images

This fixes some false negatives with small (~25px) template images.

Note that the source image must always be larger than the template
image, so we don't need to check that `image_pyramid` has as many levels
as `template_pyramid`.
stbt._match_template: Fix for large templates

If the source and template images are exactly the same size, the
`roi_mask` will be exactly 1x1. `cv2.findContours` doesn't return *any*
contours from images that are less than 3 pixels wide or high.

This fixes the following unit tests:
* test_wait_for_match_confirm_threshold_affects_match
* test_wait_for_match_erode_passes_affects_match
stbt._match_template: Lower threshold for downsampled images

Downsampling the images for the pyramid templatematch can cause images
that would match at the original size to not match at the smaller size.

I have only seen this happen in the self-test test_press_visualisation,
which has images with very thin, very high contrast text. At the
original size, the template matched with first pass certainty of 1.0; at
half the size, the certainty was 0.799, just below the default threshold
of 0.8.

To avoid matching images that didn't match before, we still use the same
threshold when checking the images at the full size (i.e. the last step
of the pyramid algorithm); but at the intermediate steps dealing with
downsampled images, we lower the threshold by 0.20. This number is
purely based on the result from the test_press_visualisation self-test,
which is the only failure of its type I have observed with the new
pyramid algorithm, after checking many images in a private collection.

In theory this has a performance impact, because the region of interest
processed at subsequent levels in the pyramid algorithm will be larger.
But I couldn't measure any difference with tests/run-performance-test.sh
(perhaps because the particular source video & template image I was
using don't present many matches between the thresholds of 0.6 and 0.8).
stbt._find_match: Nicer error if `match.pyramid_levels` misconfigured
"stbt run -vv" output includes html guide to understanding the debug images

"stbt run -vv" generates debug images to
"./stbt-debug/detect_match/<frame_number>/".

These images are numerous, and difficult to understand. Now we also
generate "./stbt-debug/detect_match/<frame_number>/index.html" which
presents the images in the correct order, notes the decision taken at
each point of the algorithm, and explains the images somewhat.

This uses Jinja2, a template engine implemented in python. The
"python-jinja2" package is available in the main Fedora repositories.
Note that the VM in `extra/vm` already installs Jinja2 (for the runner).
Merge branch 'match-performance'

An implementation of "pyramid" template matching -- a performance
optimisation for `stbt.wait_for_match` and `stbt.detect_match`.

The main change is ac97d6dd; see that commit message for details.

Also of interest is b4b59f5c, which extends the `stbt run -vv` debug
(which dumps to disk intermediate images from the image processing
algorithm) to also generate an `index.html` file that presents the
images in the correct order, notes the decision taken at each point of
the algorithm, and explains the images somewhat. See an example at
http://stb-tester.com/stbt-debug-example/detect_match/00001/index.html

* match-performance:
  "stbt run -vv" output includes html guide to understanding the debug images
  stbt._find_match: Nicer error if `match.pyramid_levels` misconfigured
  stbt._match_template: Lower threshold for downsampled images
  stbt._match_template: Fix for large templates
  stbt._match: Don't halve the size of very small template images
  stbt._match: Performance optimisation by using "pyramid" matching
  stbt._match_template: Refactor into first pass and `_confirm_match`
  tests/run-performance-test.sh: Don't measure `stbt run` startup time
  Avoid pylint errors for members of namedtuples
stbt.argparser: Document seemingly-unnecessary line of code

This line isn't strictly necessary because:

* When no `-v` command-line argument is specified, we set the
  default `_debug_level` 3 lines above (see 9aa90c16).
* When the `-v` command-line argument *is* specified, we increment
  `_debug_level` regardless of any default value retrieved by this line.

However, `stbt-run` prints out all the configuration options at startup:

    stbt.debug("Arguments:\n" + "\n".join([
        "%s: %s" % (k, v) for k, v in args.__dict__.items()]))

which includes a line of output like this:

    verbose: 2

Without this line of code, the output would look like this:

    verbose: None

even though verbose was set to 2 in the config file.

Hopefully adding this comment will stop people from trying to remove
that line, finding out that the unit test
`test_that_verbosity_level_is_read_from_config_file` fails, and
generally wasting time.
stbt.get_config: Take `type_` parameter, for better error messages

Instead of:

    >>> int(get_config(section, key))
    ValueError: invalid literal for int() with base 10: 'xyz'

we now get:

    >>> get_config(section, key, type_=int)
    ConfigurationError: 'section.key' invalid type (must be int)
stbt.wait_for_match etc: Nicer error message if template larger than source

This used to raise a very obscure exception somewhere deep in the
implementation details. It's a common error when you use the `stbt
templatematch` command-line tool and you give the arguments in the
wrong order.
tests: Two new tests have been added for the new feature
`process_all_frames`.

When using this context, all the frames must be processed and there must
not be any frame loss. In order to test this, the framerate is forced to be
50fps, and afterwards the timestamp of the frames is overlapped. That way,
the expected overlapped strings are: "00:00:00.000", "00:00:00.020",
"00:00:00.040" and so on.

Due to a dependency on the speed of the computer where this is run, the
first match must not be at any specific time. Otherwise, it can be
missed and therefore, fail. Instead, the milliseconds are checked, and
afterwards, the timestamps will report whether the matches were
consecutive.
stbt: new public method `process_all_frames` implemented.

The `queue` element in the pipeline operates in "leaky" mode, which means
that, in order to keep up with live TV, the pipeline will drop out frames
when its buffer is filled.

The new method `process_all_frames` will force the pipeline to process all
the frames. Warning: code to be run while this is active shouldn't be too
long because an awful lot of memory will be consumed in order to keep all
the incoming frames.

In order to get this done, both the `appsink` and `queue` elements in the
pipeline need to be non-leaky:

1) queue.leaky = 0 ("Not Leaky")
2) queue.max_size_buffers = 0 ("disable")
3) queue.max_size_time = 0 ("disable")
4) queue.max_size_bytes = 0 ("disable")

Besides, the Queue object used to store the last frame is reused, created
with unlimited number of elements (max_size = 0)

When entering this context, no frame must be droppedd, so the bit of code
that drops an old frame must no be run. In order to achieve this in a
readable way, a new `operation_mode` attribute is used.

When leaving the context `process_all_frames`, restart_bin_source() is used
for catching up with the live stream. However, restart_source_bin()
detects many underruns and, therefore, raises the next error:
    "Video loss. Too many underruns."

In order to avoid this, process_all_frames() now deactivates the
underrun_timeout during the process, and it is necessary to make sure that
underrun_timeout exists before trying to start it.

Example usage code:

with stbt.process_all_frames():
    # do your measurements here.
# here, live stream is caught up with
# and frame-dropping (leaky) mode is back to normal
stbt-run: New public method `get_live_stream_timestamp`

This method enables to get the timestamp of the last frame queued for
processing.

This can be used to get an approximation of the current time expressed
in terms of the stream timestamp.

When the pipeline has just ben restarted, it may happen that gstreamer
can't get the last frame because it doesn't exist, so the optional
parameter `retry` can be used to force this method to continue checking
until it successfully retrieves a valid frame.
stbt.py: Fixed error launched by get_live_stream_timestamp()

The element that was being assigned the name `upstream_screenshot` was
instroduced erronously because a `queue` gstreamer element does not have
a "last-buffer" property. This is fixed by introducing an "appsink"
element.
stbt.py: make sure the upstream_screenshot drops old frames.
stbt.py: new function get_frame_timestamp() added

`stbt.get_frame()` returns the last processed frame, but not its timestamp.
Now that `process_all_frames()` has been added so as to take precise
measurements, there needs to be a way of retrieving this timestamp, as well
as the timestamp from the live stream (already implemented).

This way, a usage exmaple would be:

with stbt.process_all_frames():
    t0 = stbt.get_live_stream_timestamp(retry=True)
    stbt.press('MENU')
    stbt.wait_for_match('menu.png')
    t1 = stbt.get_frame_timestamp()
print 'Time spent in launching the menu:', float(t1 - t2) / (10 ** 9)
stbt.py: reduce memory used when queue is non-leaky

By allocating the queue after the ffmpgecolorspace element, we reduce the
memory consumed when it is non-leaky, that is in a `process_all_frames`
context.

To reduce this even more, I've tried to substitute this queue with a queue2
element. However, what queue2 does is store the buffers in disk AS WELL AS
keep them in memory. Therefore, that doesn't help.

The amount of memory used also depends on the processing speed of the
computer. Currently, on a machine with an Intel Core i5, Fedora 18, and
hardly any process running besides the default services of Fedora, this
consumes an extra ~200MB every second.