[mythtv] [Draft] Filter documentation.

[Bruce Markey]

Bruce Markey wrote:
> Here is a first draft.

Let me try this again. It's a plain text file.

--  bjm
-------------- next part --------------
MythTV provides a facility to include video filter both while recording
and during playback. These filter can do additional processing to
improve or modify the video image such as hiding the effects of an
interlaced image or reducing the effects of noise in a poor video
signal. The following is a brief introduction to using the filters
that are available in MythTV version 0.14.

Applying filters
================

One or more filters can be included in a "filter chain". The filters to
be used are identified in a "filter string". A filter string is a group
of filter names and parameters separated by commas.  To include
parameters, the filter name is followed by "=" then then the parameter
information. There should be no spaces in the filter string. Here are
some example filter strings with and without parameters:

kerneldeint=10:1,denoise3d=12
kerneldeint,denoise3d

Recording filters are set for each individual channel. You can run
MythTV's "setup" program and select the "Channel Editor". On the first
page for each channel, you can enter a filter string in the box titled
"Video filters". If you are running "mythweb" on your web server, you
can click on "Settings" then "Channels" and enter filter strings in the
"videofilters" column.

Playback filter are per-host and apply to any recording you watch from
the frontend where filters have been applies. From "mythfrontend" go to
Setup->TV Settings->Playback. Enter your filter string in the box titled
"Custom Filters".

It is also possible to add or manipulate filter strings directly in your
mysql server. The "channel.videofilters" column holds the per-channel
recording filter strings, The playback filters are in the "settings"
table with the value of "CustomFilters" and "hostname" of the
mythfrontend machine. [It may not be a good idea to include this
in the documentation but I fleshed this out for completeness.]

Filters Currently Available:
============================

- The "invert" filter

Invert ignores any parameters, and inverts the pixel values of video
frames.  In other word, a negative image. This would rarely be useful
for most users but may be a good example to verify that your filter
strings take effect.

- The "linearblend" filter

This is the filter that is used when "Deinterlace playback" has been
checked.  It is a simple deinterlacing filter that ignores parameters,
and works by blending adjacent lines.  It replaces combing in interlaced
video with a less distracting "ghost" image.

- The "kerneldeint" filter

Kerneldeint is a more complex deinterlacing filter, which applies a
filter kernel using input from several lines.  It generally removes
combing without a "ghost" image, sometimes leaving a faint outline of
the the image from the other field. It is considered to be less
distracting to watch than linearblend or no filter at all. It accepts
one or two integer parameters separated by a colon.

The first parameter is the filter threshold, and defaults to 12.
Adjacent lines differing by more than the threshold value are filtered.
The second option defaults to 0.  If set to a non-zero value, it will
cause the filter to skip chroma, and filter only the luminance.  It may
be useful on some capture cards which do not capture the chroma fields
of interlaced video correctly.

- The "quickdnr" filter

A fast temporal denoiser.  It uses 2 thresholds to apply 2 different
levels of blending with the previous frame.  It takes 4 integer
parameters:

1: luma threshold 1
2: luma threshold 2
3: chroma threshold 1 
4: chroma threshold 2

These parameters each take a value from 0 for the least filtering
to 255 for the most filtering... 

[ I couldn't begin to parse the rest of the explanation. Please
explain these in layman's terms or pass along a URL for a more
detailed information ;-]

- The "denoise3d" filter

A slower denoiser that applies a spatial and temporal low-pass filter.
The spatial filter can remove some noise that quickdnr can't, but a more
powerful processor is needed.  It accepts 3 float parameters:

1: luma spatial filter strength
2: chroma spatial filter strength
3: luma temporal filter strength

Reasonable defaults will be selected for omitted parameters.  The chroma
temporal filter strength is calculated from the other filter strengths.
NOTE: the current version may cause black spots to appear in bright
white areas.

- The "crop" filter

Covers edges of video with black bars.  This helps to improve video
quality when the edges of the frame are distorted. By default, this
removes 16 pixels from each edge. This can optionally take four
parameters representing top:left:bottom:right. The number times
16 is the number of pixels to remove so, for example, the default
is "=1:1:1:1".

- The "forceyv12" and "forceyuv422p" filters

These force the filter manager to use the given format.  You can use
one of these at the head of a filter chain to change the capture format.
The most likely use would be forceyuv422p to use YUV422P capture on
cards with known chroma interlacing problems with YV12.

There are some filters included in the MythTV source code that should 
not be used:

The "forcergb24" and "forceargb32" filters

The two RGB formats should not be used because there is no conversion
filter for them yet.

- The "convert" filter

It exists but don't use it.  The filter manager uses this filter
automatically when it is unable to match the input/output formats of two
adjacent filters.

- The "postprocess" filter

While this exists in MythTV source code, it is currently disabled.

Usage Considerations
====================

There are trade-offs to consider when deciding if it would be wise
to use a filter. Any processing will modify the original image.
Therefore, you should assess if there is a noticeable improvement
to the picture in order to justify the impact of the processing.
Adding any filter will inherently increase CPU usage. The impact
can vary dramatically depending on your CPU type and speed, the
resolution of the recording, which filters you are using and even
the signal quality from the video source. You can only determine
what is right for you through experimentation. However, as a
starting point, here are some filter strings that many users
may find useful:

For typical broadcast stations:	"kerneldeint,denoise3d"

For stations with poor signal quality: "kerneldeint,denoise3d=12"