[mythtv] [Draft] Filter documentation.

[Bruce Markey]

Andrew Mahone wrote:
> On Tuesday 27 January 2004 06:44, Bruce Markey wrote:
> 
>>and even
>>the signal quality from the video source.
> 
> 
> This is actually not the case for the selective filters on CPUs w/ MMX.  
> Because multiple values are processed as a vector, you can't have conditional 
> branches on a per-value basis.  The MMX filters calculate filtered pixel 
> values for all pixels, and use bit masks to select filtered/unfiltered pixels 
> based on results from vector comparison.

Signal certainly has an impact on compression algorithms but
are you saying that the same code is run per pixel regardless
of the amount of compensation? I'll chop that out for now since
it is really incidental to the point that CPU usage will vary
do to the users circumstances =).

Are there any other misleading statements, glaring omissions,
clarifications that may avoid frequent questions from users?

The attachment include several corrections and suggestions that
I've received today.

--  bjm

-------------- next part --------------
MythTV provides a facility to include video filters both while recording
and during playback. These filters 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 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. These may be used
when encoding in software but do not apply when using a capture card
with hardware encoding such as those supported by the "ivtv" driver. 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" then enter filter strings in
the "videofilters" column.

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

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

- The "invert" filter

Invert ignores any parameters and inverts the pixel values of the video
frames.  In other words, a negative image. This would rarely be useful
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. This can take 1, 2 or 4 parameters.
These parameters each take a value from 0 for the least filtering
to 255 for the most filtering. With one parameter, the filter
will compute the values it should use for all of its variables.
Two parameter will set the filter strength for luma and chroma
independently. If you are interested in how the algorithm works,
you may examine the source code to see how four parameter are used.

- 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 not
recommended for use.

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 other factors. 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"