Mailing List Archive

Filter documentation?
Andrew, is there any user documentation for filters? The
filters directory has a README for the filter API but I've
never seen and documentation for what filters are available,
when would the user want to use them, what they do, what
options (if any) do they take, and how to add and remove
filters. That sort of thing. Do you think you might be able
to rough out something that could be added to the HOWTO?

-- bjm
Re: Filter documentation? [ In reply to ]
On Saturday 24 January 2004 21:33, Bruce Markey wrote:
> Andrew, is there any user documentation for filters? The
> filters directory has a README for the filter API but I've
> never seen and documentation for what filters are available,
> when would the user want to use them, what they do, what
> options (if any) do they take, and how to add and remove
> filters. That sort of thing. Do you think you might be able
> to rough out something that could be added to the HOWTO?
>
> -- bjm

There isn't right now, although I did think of adding some the last time that
I worked on the filters README. I have a bug to get rid of in denoise3d,
I'll probably submit some filter documentation with that, or before if it
takes me too much longer to find the problem.

Does anybody have any thoughts on the best place to document this? I think it
should either go into the main MythTV HOWTO, or that I should split the
filters README into separate user and API files.
--
Andrew Mahone
andrewmahone AT eml DOT cc
Re: Filter documentation? [ In reply to ]
Once the filter setup gui interface is up, I think most of these questions
should be eliminated/self explanatory (i.e. the description field for the
filter). Perhaps a one liner added to the Playback/Recording sections of the
HOWTO explaining that you _can_ setup filters. The real problem is right now
that you can't set them up without really knowing what you are doing/editing
the database.

-Debabrata

----- Original Message -----
From: "Andrew Mahone" <andrewmahone@eml.cc>
To: "Development of mythtv" <mythtv-dev@mythtv.org>
Sent: Sunday, January 25, 2004 12:15 AM
Subject: Re: [mythtv] Filter documentation?


> On Saturday 24 January 2004 21:33, Bruce Markey wrote:
> > Andrew, is there any user documentation for filters? The
> > filters directory has a README for the filter API but I've
> > never seen and documentation for what filters are available,
> > when would the user want to use them, what they do, what
> > options (if any) do they take, and how to add and remove
> > filters. That sort of thing. Do you think you might be able
> > to rough out something that could be added to the HOWTO?
> >
> > -- bjm
>
> There isn't right now, although I did think of adding some the last time
that
> I worked on the filters README. I have a bug to get rid of in denoise3d,
> I'll probably submit some filter documentation with that, or before if it
> takes me too much longer to find the problem.
>
> Does anybody have any thoughts on the best place to document this? I
think it
> should either go into the main MythTV HOWTO, or that I should split the
> filters README into separate user and API files.
> --
> Andrew Mahone
> andrewmahone AT eml DOT cc
> _______________________________________________
> mythtv-dev mailing list
> mythtv-dev@mythtv.org
> http://mythtv.org/cgi-bin/mailman/listinfo/mythtv-dev
Re: Filter documentation? [ In reply to ]
On Sunday 25 January 2004 00:46, D Banerjee wrote:
> Once the filter setup gui interface is up, I think most of these questions
> should be eliminated/self explanatory (i.e. the description field for the
> filter). Perhaps a one liner added to the Playback/Recording sections of
> the HOWTO explaining that you _can_ setup filters. The real problem is
> right now that you can't set them up without really knowing what you are
> doing/editing the database.
>
> -Debabrata

I don't know MythTV well enough yet to go messing with the GUI, though, and a
filter selection screen could be very complex (consider that filters may be
used twice in a chain, etc). Until somebody has time to do this messy work,
some docs on how to specify filters would probably be very helpful, and
shouldn't take long to write. Don't forget, mythweb also allows you to edit
channel filters, and you can specify a filter string for playback, so there
are some easy ways to enter filter strings, but no documentation at all on
how to construct a valid fiter string.
--
Andrew Mahone
andrewmahone AT eml DOT cc
Re: Filter documentation? [ In reply to ]
Andrew Mahone wrote:
> ...Until somebody has time to do this messy work,
> some docs on how to specify filters would probably be very helpful, and
> shouldn't take long to write.

Yeah, that's the idea. You've done all this hard work to
get filters working to your liking but they aren't really
accessible to anyone else until there is some introductory
information. I guess I meant to imply that if you could
posts some notes or raw information about the current filters
and how to use them, I'd be willing to help flesh them out to
go into the HOWTO (if Robert doesn't beat me to it =).


> Don't forget, mythweb also allows you to edit
> channel filters, and you can specify a filter string for playback, so there
> are some easy ways to enter filter strings, but no documentation at all on
> how to construct a valid fiter string.

I look forward to seeing the explanation and trying it out
as a newbie filter user.

-- bjm
Re: Filter documentation? [ In reply to ]
On Sunday 25 January 2004 17:32, Bruce Markey wrote:
> I guess I meant to imply that if you could
> posts some notes or raw information about the current filters
> and how to use them, I'd be willing to help flesh them out to
> go into the HOWTO (if Robert doesn't beat me to it =).

Heh, well, if you're volunteering to turn some rough info into decent docs, I
may as well take advantage ;-) I actually looked at the HOWTO docs, but I'm
not sure whether they're all generated from the SGML, or if I'm supposed to
edit each version.

Just a thought, and it'd be a bit of an ugly stopgap measure until there's
"real" filter support in the GUI, but what about listing the filter info from
FilterManager::GetAllFilterInfo in the GUI somewhere (probably in the TV
playback options, the only place in the GUI where you can edit filters right
now).

> I look forward to seeing the explanation and trying it out
> as a newbie filter user.

Ok, here's what I've got so far.

3 ways to enter filter strings:
edit DB yourself
record only, set per-channel filter in mythweb, settings->channels
playback only, set custom playback filter in mythfrontend, setup->tv->playback

A "filter string" is a group of filters separated by commas. Each filter may
have parameters appended, and parameters are prefixed by "=".

Example filter strings:
linearblend,quickdnr
kerneldeint,denoise3d
kerneldeint=10:1,denoise3d=12

currently available filters:

invert
Invert ignores any parameters, and inverts the pixel values of video frames.

linearblend
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.

kerneldeint
Kerneldeint is a more complex deinterlacing filter, which applies a filter
kernel using input from several line. It generally removes combing without a
"ghost" image, sometimes leaving a faint outline of the the image from the
other field. I find it much easier to watch than linearblend or no filter at
all. It accepts up to 2 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.

quickdnr
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
D Banerjee may be able to clarify these parameters, I didn't write this
filter. It appears to try to select reasonable defaults for omitted
parameters.

denoise3d
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: there is a minor bug in denoise3d, which causes some high-valued
(usually bright white) pixels to wrap around to low values. Very
distracting, but fairly rare in things that I've been recording. I'm still
trying to get some good test video for this bug, I will try to have it fixed
ASAP.

crop
Covers edges of video with black bars. This helps to improve video quality
when the edges of the frame are distorted. It takes 4 paremeters which
appear to be mandatory. I need clarification from D Banerjee as to which
side each parameter crops from, and what unit the crop sizes are in (src
looks like pixels to me, description says macroblocks).

forceyv12
forceyuv422p
forcergb24
forceargb32
Forces the filter manager to use the given format. You can use one at the
head of a filter chain to change the capture format. The two RGB formats
should not be used, because there is no conversion filter for them yet. Most
likely use would be forceyuv422p to use YUV422P capture on cards w/ broken
chroma interlacing in YV12.

Filters you can't/shouldn't use:
convert
It exists, 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.

postprocess
I believe this is currently disabled in the build, as it was not functioning
properly. It should be fixed, post-processing can make MPEG-4 video quality
acceptable at much lower bitrates.

I use "kerneldeint,denoise3d" for all channels. I have analog cable that's
mildly noisy, and very noisy on higher channels. For Cartoon Network, w/ bad
noise, I use "kerneldeint,denoise3d=12". These filters plus MPEG-4 encoding
on 480x480 video and 44KHz mp3 encoding, run around 50% CPU on my Athlon XP
2500+.
--
Andrew Mahone
andrewmahone AT eml DOT cc
Re: Filter documentation? [ In reply to ]
> quickdnr
> 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
> D Banerjee may be able to clarify these parameters, I didn't write this
> filter. It appears to try to select reasonable defaults for omitted
> parameters.

It takes inputs in three types. A single argument 0-255 scales everything,
less filtering to more filtering
Four inputs will let you adjust two thresholds, the 1st threshold is the
difference input level before it stops trying to average pixels, and the
second threshold is within how much input level difference to keep the
previous value. This of course applies to both luma and chroma.
Two inputs will give you a single thresholded filter, same description as
the 1st input(s).

> crop
> Covers edges of video with black bars. This helps to improve video
quality
> when the edges of the frame are distorted. It takes 4 paremeters which
> appear to be mandatory. I need clarification from D Banerjee as to which
> side each parameter crops from, and what unit the crop sizes are in (src
> looks like pixels to me, description says macroblocks).
>

They aren't manditory.. It defaults to 16 pixels around all edges without
any arguments. The arguments should be top:left:bottom:right, as the number
of macroblocks (16 pixels). There's currently no point to using any other
unit, since if you don't crop to macroblock boundaries you'll probably end
up worse than when you started ;) However if I ever get frame resizing to
work properly it will be possible to do 8 pixels, if the total is 16 on any
axis. There's no need to include that for now however.

> postprocess
> I believe this is currently disabled in the build, as it was not
functioning
> properly. It should be fixed, post-processing can make MPEG-4 video
quality
> acceptable at much lower bitrates.
>

I was toying with it and it appears non-functional. I tried to dump
qscale_table and it seems it's empty/unallocated. I'd segfault on even
reading the first byte. BTW, mpeg-4 spec requires postprocessing, afaik.
It's probably why people need to use really high quality settings to get
acceptable video (but still with blocks). There's supposed to be blocks
without the postprocessing :)

> I use "kerneldeint,denoise3d" for all channels. I have analog cable
that's
> mildly noisy, and very noisy on higher channels. For Cartoon Network, w/
bad
> noise, I use "kerneldeint,denoise3d=12". These filters plus MPEG-4
encoding
> on 480x480 video and 44KHz mp3 encoding, run around 50% CPU on my Athlon
XP
> 2500+.

Is this because denoise3d doesn't like interlacing or other?
Re: Filter documentation? [ In reply to ]
> I'd be willing to help flesh them out to
> go into the HOWTO (if Robert doesn't beat me to it =).

Haven't used any filters yet on my boxes, so have at it.
Re: Filter documentation? [ In reply to ]
On Monday 26 January 2004 09:34, D Banerjee wrote:
> Is this because denoise3d doesn't like interlacing or other?

Denoise3d filters in 3 directions, vertical, horizontal, and temporal (vs
previous frame). The temporal and horizontal filters should still be
effective without deinterlacing, and the vertical will work where there's no
motion, but combing from interlaced video will stop the vertical filter from
working well on that part of the image.

Deinterlacing can also help produce better results at lower bitrates. Combing
is bad for the video codec, because it adds a lot of extra high-frequency
data to encode. Unless I missed something, and MythTV is using interlaced
encoding when it records. The ffmpeg encoder *should* be able to support
this, I don't think rtjpeg can without some reworking.
--
Andrew Mahone
andrewmahone AT eml DOT cc
Re: Filter documentation? [ In reply to ]
Robert Kulagowski wrote:
> > I'd be willing to help flesh them out to
>
>> go into the HOWTO (if Robert doesn't beat me to it =).
>
>
> Haven't used any filters yet on my boxes, so have at it.

Nor have I which is why I want to see some documentation.

Expect my usual M.O. of handing off my best effort to you
for your editorial "filter".

-- bjm