.TH "y4mdenoise" "1" "27 Apr 2004" "MJPEG Tools Team" "MJPEG tools manual"

.SH NAME
y4mdenoise \- Motion-compensating YUV4MPEG-frame denoiser

.SH SYNOPSIS
.B y4mdenoise
.RB [ -v
.IR verbosity ]
.RB [ -p
.IR parallelism ]
.RB [ -r
.IR motion-search_radius ]
.RB [ -R
.IR color_motion-search_radius ]
.RB [ -t
.IR error_tolerance ]
.RB [ -T
.IR color_error_tolerance ]
.RB [ -z
.IR zero_motion_error_tolerance ]
.RB [ -Z
.IR color_zero_motion_error_tolerance ]
.RB [ -m
.IR match-count_throttle ]
.RB [ -M
.IR match-size_throttle ]
.RB [ -f
.IR reference_frames ]
.RB [ -B ]
.RB [ -I
.IR interlacing_type ]
.RI "< /dev/stdin > /dev/stdout"

.SH DESCRIPTION
\fBy4mdenoise\fP can be used to remove noise from images
in a YUV4MPEG2 stream. This is useful for cleaning old sources to
increase video quality, and to reduce the bitrate needed to encode
your video (e.g. for VCD and SVCD creation).

.SH HOW IT WORKS
It maintains a list of the last several frames, called reference
frames.  Each reference frame is composed of reference pixels.
Every time a pixel in one frame is proven to be a moved instance
of a pixel in another frame, the reference-pixel incorporates its
value, and produces an average value for all instances of the pixel.
The oldest reference frame, therefore, gets a pretty good idea of
the real value of every pixel, but of course output is delayed by
the number of reference frames.

The search is not actually done one pixel at a time; it's done in
terms of pixel groups.  An entire pixel-group has to match for any
match to be found, but all possible pixel-groups are tested (i.e. all
possible overlapping combinations are checked).  Using pixel-groups
helps to establish a minimum standard for what may be considered a
match, in order to avoid finding lots of really small (and really
useless) matches.  Presently, intensity pixel-groups are 4x2
(i.e. 4 across and 2 down), and color pixel-groups are 2x2.

It compares every pixel-group in the current frame with all
pixel-groups in the previous frame, within a given search-radius,
and sorts them based on how close the match was, keeping the top
contenders.  It then flood-fills each found pixel-group in turn,
to determine the full size of the match.  The first match found to
be big enough is applied to the image.  The number of contenders
to consider, and the minimum size of a match, can be specified on
the command line.

At the end of the frame, any new-frame pixels not resolved yet
are considered to be new information, and a new reference-pixel is
generated for each one.

A "zero-motion pass" happens each frame, before motion-detection, in an
attempt to resolve most of the frame cheaply.  Its error-tolerance can
be set separately.

.SH OPTIONS
\fBy4mdenoise\fP accepts the following options:

.TP 4
.BI \-v " [0..2] verbosity"
0 = none, 1 = normal (per-frame pixel-detection totals), 2=debug.

.TP 4
.BI \-p " num"
Controls the level of parallelism.  Since intensity and color are
denoised separately by design, it's very easy to do each in parallel on
a multiple-processor machine.  The default value is 1; that reads and
writes video frames in parallel with denoising.  A value of 2 causes
intensity and color to be denoised in parallel.  A value of 3 does both
types of concurrency.  A value of 0 turns off all concurrency.

.TP 4
.BI \-r " [4..] search radius"
The search radius, i.e. the maximum distance that a pixel can move and
still be found by motion-detection.  The default is 16.
There are no particular restrictions on the search radius, e.g. it
doesn't have to be an even multiple of 4.

.TP 4
.BI \-R " [4..] color search radius"
The search radius to use for color.  Default is whatever the main
search-radius was set to.  Note that this value ends up getting scaled
by the relative size of intensity & color planes in your YUV4MPEG2
stream.

.TP 4
.BI \-t " [0..255] Error tolerance"
The largest difference between two pixels that's accepted for the two
pixels to be considered equal.  The default is 3, which is good for
medium-noise material like analog cable TV.  (This value will have
to be changed to whatever is appropriate for your YUV4MPEG2 stream
in order to avoid undesirable results.  See the instructions below.)

.TP 4
.BI \-T " [0..255] Error tolerance for color"
The default is whatever the main error-tolerance was set to.

.TP 4
.BI \-z " [0..255] Error tolerance for zero-motion pass"
The error-tolerance used on pixels that haven't moved.  Usually equal
to the main error-tolerance or one less than that.  Default is 2.

.TP 4
.BI \-Z " [0..255] Error tolerance for color's zero-motion pass"
The default is whatever the main zero-motion error-tolerance was set to.

.TP 4
.BI \-m " [num] Match-count throttle"
The maximum number of pixel-group matches (within the search radius)
to consider.  If more are found, only the closest matches are kept.
Default is 15.

.TP 4
.BI \-M " [num] Match-size throttle"
The minimum size of the flood-filled region generated from a match.
Matches smaller than this are thrown away.  Specified in terms of
pixel-groups.  Default is 3.

.TP 4
.BI \-f " num"
The number of reference frames to keep.  Pixel values are averaged over
this many frames before they're written to standard output; this also
implies that output is delayed by this many frames.  Default is 10.

.TP 4
.BI \-B
Black-and-white mode.  Denoise only the intensity plane, and set the
color plane to all white.

.TP 4
.BI \-I " num"
Set interlacing type.  Default is taken from the YUV4MPEG2 stream.
0 means not interlaced, 1 means top-field interlaced, 2 means
bottom-field interlaced.  This is useful when the signal is more
naturally of some other interlacing type than its current representation
(e.g. if the original was shot on film and then later it was transferred
to interlaced video, it will denoise better if treated as film, i.e.
non-interlaced).

.SH TYPICAL USAGE AND TIPS
Keep in mind that all of this advice was gained through experience.
(Just because one writes a tool doesn't mean one understands how it
should be used, for the same reason that car designers aren't
necessarily professional drivers.)

The error-threshold must be determined for every individual YUV4MPEG2
stream.  If the threshold is set too low, it'll leave noise in
the video, and the denoiser will run a lot slower than it has to.
If it's set too high, the denoiser will start to remove detail:
the video will get blurrier, you may see topographical-like bands
in the relatively flat areas of the video, and small parts of the
video that should be moving will be stuck in place.  It may also
run a little slower.  Additionally, just because the video came to
you from a clean source (digital cable TV, LaserDisc, etc.) doesn't
mean the video itself is clean; \fBy4mdenoise\fP is capable of
picking up on noise in the original recording as well as sampling error
from the video-capture device.  You will have to generate small
clips of representative parts of your video, denoise them with
various error thresholds, and see what looks the best.  As you
gain experience with the tool, you may know what error threshold
generally works with various types of sources, but you'll still
want to double-check your assumptions.

Flat, shiny surfaces, like gloss-painted walls, or the polished wood
floor of an indoor gymnasium, seem to require a lower error threshold
than other types of video.

Here is the author's experience:

 -t 1 : Digital cable TV, most LaserDiscs, DV camcorder video
 -t 2 : VHS camcorder video, commercially-produced videotapes
 -t 3 : Analog cable TV, VHS videotape (at the 2-hour speed)
 -t 4 : VHS videotape (at the 6-hour speed)

Interlaced video that was made from non-interlaced video (e.g. a
videotape or LaserDisc of a film) must be denoised as non-interlaced.
Otherwise the result tends to be grainy.

\fBy4mdenoise\fP only removes temporal noise, i.e. noise that occurs
over time.  And it tends to do such a good job of this, that the
spatial noise (i.e. noise that occurs in nearby areas of the same frame)
tends to become very distinct.  Therefore, always pipe the output of
\fBy4mdenoise\fP through a spatial filter such as \fBy4mspatialfilter\fP
or \fByuvmedianfilter\fP.

When producing very low bitrate video (e.g. VCD-compatible video
less than 900 kbps), denoise at the output frame size, e.g. don't
denoise at DVD frame size then downscale to VCD size.  That will
denoise as well as condition the video for the motion-detection part of
\fBmpeg2enc\fP.  Not doing this will produce video where the less
complex scenes will look really good, but high-motion scenes will blur
significantly.

JPEG compression of your video frames, even 100% compression, seems to
be inaccurate enough to affect MPEG encoding.  Therefore, if you're
using motion-JPEG files as your intermediary video format, you may
want to use the denoiser in your MPEG-encoding pipeline, i.e. after
\fBlav2yuv\fP and before \fBmpeg2enc\fP.  If you're generating multiple
resolutions of the same video, e.g. DVD and VCD, experience shows
that it's acceptable to run \fBy4mdenoise\fP before \fByuv2lav\fP, but
you should still use the spatial-filter (e.g. \fBy4mspatialfilter\fP,
\fByuvmedianfilter\fP) in the MPEG-encoding pipeline, to try to smooth
away JPEG encoding artifacts.

.SH AUTHOR
The bulk of the \fBy4mdenoise\fP code, and this manual page, was
written by Steven Boswell <ulatec@users.sourceforge.net>.

.SH FURTHER INFO
If you have questions, remarks, problems or you just want to contact
the developers, the main mailing list for the MJPEG\-tools is:

.BR \fImjpeg\-users@lists.sourceforge.net\fP

For more info, see our website at

.BR \fIhttp://mjpeg.sourceforge.net/\fP

.SH SEE ALSO
.BR mjpegtools (1),
.BR mpeg2enc (1),
.BR yuvdenoise (1),
.BR yuvmedianfilter (1)