gsttemplatematch.c cleanup: capsInitialised not TRUE if cvCreateImageHeader fails

The old code assumed that cvCreateImageHeader worked and set the filter's
`capsInitialised` attribute to TRUE to indicate that the filter had been
initialised.

This modification ensures that capsInitialised is only set to TRUE if
filter->cvImage has a value set to it.

[Committer's note: This wasn't causing us any trouble; it just seemed
a reasonable tidy-up to do.]
stbt-templatematch, wait_for_match, et al. are fully configurable by user

This patch allows users full configurability of the templatematch
algorithm through all aspects of stb-tester package which imply
matching, i.e.
  * stbt-templatematch (gstreamer plugin)
  * stbt.wait_for_match(...)
  * stbt.press_until_match(...)
  * stbt.detect_match(...)

These parameters are:
gstElement param | stbt.py param
_________________|__________________
matchMethod      | match_method
matchThreshold   | match_threshold
confirmMethod    | confirm_method
erodePasses      | erode_passes
confirmThreshold | confirm_threshold*

* Previously known as noiseThreshold/noise_threshold. noiseThreshold is
  marked for deprecation and usage of it will raise a warning. At
  present both noise_threshold and confirm_threshold are valid
  individually when set in wait_for_match (*not* stbt-templatematch
  element though!), and affect the template match in the same way.
  However, using both will result in an error.

For full details on these parameters, please read the documentation,
see stbt's man page, or use gst-inspect stbt-templatematch.

Selftests have been implemented to ensure that setting each of the
parameters to stbt-templatematch are accepted by the element and have
an effect on the template matching process.

Each of the tests that execute a `wait_for_match` are done as 2
consecutive scripts executed with stbt-run. This is to prevent a known
race condition (see commit 243c27e6) where the second in a pair of
consecutive detect_matches reports a match falsely because of a second
bus message from the gstreamer element which reports the positive match
from the first detect_match that stbt.py has already acted on, and which
stbt interprets as a successful match for the second detect_match. There
is a mechanism implemented to make stbt ignore these superfluous
messages, however it only takes effect if the 2 subsequent
detect_matches are using different templates. Because these tests are
designed to demonstrate the effect of changing a single templatematch in
a test, they must use the same template. (They could use identical
copies of each template only with a different name, however this would
make it confusing to understand the tests' purpose and needlessly
increase the number of files in this package.)
Ensure GStreamer tests test the source plugin, not the installed plugin

GStreamer has a "registry" (a cache of element names and the path of the
shared library implementing each element) so if the `stbt-templatematch`
element was already in the registry, `gst-launch` and `gst-inspect`
would use the element from the registry (most likely from an installed
version of stbt) instead of obeying $GST_PLUGIN_PATH, which is set by
`run-tests.sh` to look in the source directory.

Deleting the registry has no harmful effects other than the next
invocation of `gst-launch` or `gst-inspect` will take slightly longer to
start as it recreates the registry.

There's no need to delete the registry again after running the tests,
because when a user runs the installed version of `stbt`, he/she won't
have GST_PLUGIN_PATH pointing at the source directory; even if the
plugin is in the registry, it won't be used if not on GStreamer's search
path.
tests/test-templatematch.sh: Remove unnecessary PYTHONPATH

This "$scratchdir/test.py" doesn't import stbt, so it isn't necessary
to set PYTHONPATH.
New stbt-templatematch confirm method: 'normed-absdiff'

This is a third option for `stbt-templatematch`'s confirmMethod and
`wait_for_match`'s confirm_method parameter in addition to the existing:
'none' and 'absdiff' methods.

'normed-absdiff' is a slight modification and extension of 'absdiff'. The
only difference is a normalise step on both the template and source before
the absolute difference is done. The ethos behind this step came when we
started finding a number of matches that were giving false positives due
to the template image having a low dynamic range, i.e. being low contrast.
By normalizing template and source we exaggerate any differences between
them, meaning it is less likely for a false match to happen.

However, this also means the test is more susceptible to noise, and
therefore the default confirm_threshold (noise_threshold) has been
increased from 0.16 to 0.28. This is preferable over doubling the number
of erode_passes because it is much easier to fine tune the
confirm_threshold than the erode_passes.

The selftest which checked the effect of changing confirm_threshold has
been updated, and a new test to check the effect of switching between
confirm methods is implemented, which is based on a false match we found.

Some of the selftests had to be changed to explicitly use the old
template matching algorithm and settings. i.e. confirm_method=1,
confirm_threshold=0.16, because they *do not* pass with the normalize method,
which is now default.
gsttemplatematch.c: using non-normalized `matchMethod` raises a warning

stb-tester's template match "supports" the non-normalized methods
OpenCV uses for template matching, however the resulting "heat maps" do
not make sense within the context of STBT and the `matchThreshold`
parameter. What is meant by this, is that `matchThreshold` is limited
to the range [0.0..1.0f], but the pixel values for the non-normalized
heat maps do not have a concrete upper limit, and almost definitely fall
outside the [0.0..1.0f] range.

To this end, using a non-normalized method will almost always pass through
to the second pass as the `matchThreshold` would always be exceeded, and
therefore it is *strongly* recommended (but not enforced) that the
equivalent normalized version of the `matchMethod` is used instead.
stbt.py: Load templatematch parameters' default values from stbt.conf

With the introduction of additional templatematch parameters, three
functions in `stbt.py` now have additional keyword arguments:
`detect_match()`, `wait_for_match()`, `press until match()`. In each of
these, the same templatematch parameters appear with the same default
arguments and function docstring entry.

To make the code more readable/maintainable, the templatematch
parameters were removed in these functions and replaced with a catch-all
`**kwargs` argument. The default arguments are now loaded from
`stbt.conf`. Note that the `noise_threshold` argument was left intact
for backwards-compatibility, in case a user calls the function with
positional instead of keyword arguments.

The three templatematch-aware functions now call a new function
`build_templatematch_params(**kwargs)` to obtain the list of
templatematch parameters to use. When called, this new function returns
a dict of complete templatematch parameters. Any keyword arguments
passed into it will override those in `stbt.conf`.

A new test was added to ensure the `stbt.conf` defaults match the
defaults in the gstreamer templatematch element.

[Committer's note: There are 2 main reasons for this change:

1. Avoid hard-coding the same default values for `confirm_threshold`
   etc. in every helper function built by the user on top of
   `wait_for_match` etc.
   Instead, those helper functions can take a `confirm_threshold`
   parameter that defaults to `None`; if they pass it through as `None`
   to `wait_for_match`, the default value from stbt.conf will be used.

2. To allow the user to change the default values for *all* calls to
   `wait_for_match` etc, without having to override the default at every
   call site. When we release the next version of stbt incorporating
   06f34140 (New stbt-templatematch confirm method: 'normed-absdiff'),
   users who wish to continue using the old templatematch algorithm can
   change their `stbt.conf` to specify the old algorithm. This will give
   us (the stbt developers) much greater freedom to evolve the image
   processing algorithm and other aspects of the API, without
   inconveniencing our users.
]
Fix `make check` pylint errors

Caused by a combination of factors: the new code from dd44303b (Load
templatematch parameters' default values from stbt.conf) being rebased
after 1276c4e3 (Enable pylint warnings and style checks).

The errors were:

stbt.py:1259: [W0601] Global variable 'load_config' undefined at the module level
stbt.py:1262: [W0613] Unused argument 'tool'
Fix `make check` pep8 1.4.2 errors

Fedora17's pep8 1.0.1 doesn't catch these; this commit is so that `make
check` passes on my OS X system.
stbt.py: Cleanup: Move `warnings` configuration after imports

After *all* the imports; note that importing `gst` requires defining
`ArgvHider` and `StdErrHider` first, so the whole "imports" section
is quite long.
stbt.py: Wording of `noise_threshold` deprecation warning

Removed "stbt-templatematch" from the deprecation message.

"stbt-templatematch" is the name of the GStreamer element used behind
the scenes by `stbt.wait_for_match` et al.

`noise_threshold` doesn't exist at all in the GStreamer element, so the
message is misleading. Furthermore, users of the python API don't need
to know about the GStreamer element --it's an implementation detail-- so
the name of the GStreamer element shouldn't be surfaced in a
user-visible message.

This also changes the `filterwarnings` setup to print all deprecation
warnings originating from the `stbt` module; but this is the only
warning raised by the module.
insert default templatematch arguments into the docs

The `api-doc.sh` helper script (called from `make doc`) was updated to
plug the default templatematch parameters into the docs.

Previously, the docs were effectively updated in-place. README.rst was
read, the api-doc inserted in the right place, and the output written
back to README.rst. To facilitate template subtitution, the docs are now
generated by `api-doc.sh` from a separate README.rst.in input file and
written to the README.rst instead.

The default values are pulled from the top-level `stbt.conf`, and appear
in the doc input file as Python replacement fields (see PEP3101).

api-doc.sh
* Updated to read from README.rst.in and write to README.rst
* Added `templatematch_params()` function to insert defaults
* Formats variables called `**kwargs` correctly in rst format

README.rst.in
* Added templatematch parameter placeholders as Python replacement
  fields

Makefile
* Updated to build README.rst.in instead of README.rst
api-doc.sh: Cleanup: Extract `python_docstrings` into its own function

Since the processing is done in 2 stages (`python_docstrings` and
`templatematch_params`), and `templatematch_params` was its own
function, it makes sense to pull this into its own function too. This
way the high-level pipeline reads like a list of the changes we make
to the README file.
api-doc.sh: Compatibility with BSD / OS X `mktemp`

d7a8012b added a call to mktemp that uses GNU-specific flags.
`match_method`/`confirm_method` params take literal string names not ints

Before, the 2 method parameters accepted integer values which were the
equivalent to the enumerated values in the C code. Now, they take literal
strings of the actual names of the desired method. This is much clearer to
read and interpret than just numbers.

Note: when passed as a parameter via the Python API, the methods must be
string literals (i.e. single or double quoted), however in stbt.conf files,
the quotes must be omitted. When passed as a command line argument to
stbt-templatematch, the quotes must be escaped (i.e. \"...\") as in
test-stbt-templatematch.sh so that the quotes get parsed literally to the
program.

Note that the stbt-templatematch gstreamer element has always accepted the
method names *as well* as the enumerated values, however this modification
means that with the Python API the method names are now accepted *instead
of* the enumerated values.
stbt templatematch: Fix command-line api breakage in 5d6b4761

5d6b4761 (`match_method`/`confirm_method` params take literal string
names not ints) changed the command-line interface of `stbt
templatematch` from

    stbt templatematch frame.png template.png confirm_method=1

to

    stbt templatematch frame.png template.png confirm_method=\"absdiff\"

Using the string name instead of a number is desirable; forcing the user
to provide escaped quotes is not.

With this current commit the interface becomes:

    stbt templatematch frame.png template.png confirm_method=absdiff
stbt-completion: Complete new `stbt templatematch` parameters & values

...introduced in 18a5e70e (stbt-templatematch, wait_for_match, et al.
are fully configurable by user) and 06f34140 (New stbt-templatematch
confirm method: 'normed-absdiff').
Merge branch 'templatematch-normalised-absdiff'

+ A new templatematch algorithm used by `wait_for_match` (06f34140).
+ The algorithm to use, and many parameters of those algorithms, is
  configurable in calls to `wait_for_match` (18a5e70e).
+ Global defaults for the above can be set in stbt.conf (dd44303b).

* templatematch-normalised-absdiff:
  stbt-completion: Complete new `stbt templatematch` parameters & values
  stbt templatematch: Fix command-line api breakage in 5d6b4761
  `match_method`/`confirm_method` params take literal string names not ints
  api-doc.sh: Compatibility with BSD / OS X `mktemp`
  api-doc.sh: Cleanup: Extract `python_docstrings` into its own function
  insert default templatematch arguments into the docs
  stbt.py: `noise_threshold` deprecation warning prints caller of `wait_for_match`
  stbt.py: Wording of `noise_threshold` deprecation warning
  stbt.py: Cleanup: Move `warnings` configuration after imports
  Fix `make check` pep8 1.4.2 errors
  Fix `make check` pylint errors
  stbt.py: Load templatematch parameters' default values from stbt.conf
  gsttemplatematch.c: using non-normalized `matchMethod` raises a warning
  New stbt-templatematch confirm method: 'normed-absdiff'
  tests/test-templatematch.sh: Remove unnecessary PYTHONPATH
  Ensure GStreamer tests test the source plugin, not the installed plugin
  stbt-templatematch, wait_for_match, et al. are fully configurable by user
  gsttemplatematch.c cleanup: capsInitialised not TRUE if cvCreateImageHeader fails
make check-pylint: Disable verbose "locally disabling" messages

Commit 1276c4e3 enabled a lot of extra pylint checks, and selectively
disabled them for specific lines in the python code that were triggering
false positives. However, even when disabled, pylint would print
something like this for each such line:

    stbt.py:26: [I0011] Locally disabling W0232

This commit disables such output, which could be considered debug
messages of pylint itself; actual errors are now much more visible
in the output of `make check-pylint`.
README: minor fixes to templatematch customisation section

Updates the README for clarity and completeness.

Notable changes:
* added list of valid values for `match_method`, which were missing
* update `confirm_method` formatting to emphasise they are strings
* changed to fixed-width font for parameter values
* using double-quotes to indicate strings