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
irnetbox: Timeout the TCP connection attempt after 10 seconds.

I'd like to use IRNetBox to determine whether the irnetbox has frozen or
not. Usually attempting to set up a TCP socket to a dead irnetbox will
raise a "Connection refused" socket exception. However, I've also seen
times when the TCP socket connection attempt completely hangs.

This commit adds a 10 second timeout _to the socket connection attempt
only_. I do not want to keep the timeout applied because this would
change how the script behave later on; it seems to rely on blocking
reads from the socket.

[Committer's note: "Connection refused" from the irNetBox doesn't mean
that it's dead; the irNetBox only allows one client connection at a
time, so it means that another client is connected to the irNetBox.
Possibly a misbehaving client that hasn't released its connection, but
it could also be a client legitimately sending messages to the irNetBox.

The correct solution† will be to put a proxy server between the irNetBox
and the clients, that *does* handle multiple client connections.

† The solution for the "one client at a time" problem; I don't know what
is causing the "socket connection attempt hangs" problem seen by the
author.]
Remove README.rst.in (`make doc` keeps README.rst up-to-date)

Ever since 2204c898, `make doc` updates README.rst (in place) so that
the python API documentation is kept in sync with the docstrings in
`stbt.py`.

882f6b76 added additional information to this process; it's no longer
just the python API documentation, it's also the default values of the
`wait_for_match` parameters (which are now not specified in the python
code, but in `stbt.conf`).

However the *process* by which 882f6b76 updates `README.rst` is
different than the existing process for updating the python api docs in
the same file. This current commit uses the same process for updating
both sections of the documentation. The advantage is that it removes the
almost-identical `README.rst.in` added by 882f6b76, thus removing the
following inconsistency:

                         README.rst.in         README.rst

    python api docs      Contained full but    Contains full python
                         obsolete python api   api docs,
                         docs, *not* updated   updated by `make doc`.
                         by `make doc`.

    stbt.conf defaults   Contained             Contains the values,
                         placeholder.          updated by `make doc`.

It was already somewhat non-standard to commit a generated file
(`README.rst`). Having both `README.rst` and `README.rst.in` in the
repository is even more confusing.
Unit tests for api-doc.sh

api-doc.sh is used by `make doc` to keep README.rst up-to-date with the
python API documentation in stbt.py docstrings, and with the
`wait_for_match` parameter default values in stbt.conf.

api-doc.sh doesn't need much test coverage because README.rst is checked
into version control; so each time you run api-doc.sh, your next `git
diff` would alert you if something had gone wrong (and since we all
check our diffs before committing, we'd never commit undesired changes
to README.rst).

However api-doc.sh could go wrong in one way that wouldn't be detected:
Not actually updating README.rst when the API documentation / default
configuration *had* changed. These tests should cover that.

I had to change the implementation of `python_docstrings` (now called
`substitute_python_docstrings`) so that it doesn't do anything to an
input file without the python api section; this is so that I can test
the `templatematch_params` functionality of api-doc.sh.
gsttemplatematch.h: Explicitly use OpenCV's enum values

The `stbt-templatematch` GStreamer element's `matchMethod` property
takes values identical to the OpenCV constants taken by the OpenCV
`cvMatchTemplate` function.

We do need our own enum (`GstTMMatchMethod`) because it is required by
GStreamer's GObject boilerplate. But now we can have the compiler
enforce that the values are kept in sync with the OpenCV equivalents,
instead of listing the OpenCV constants in a comment that the compiler
can't check.

This change is also necessary for the next commit.