File: Readme_STMedianFilter.txt

//  STMedianFilter - SpacioTemporal Median Filter for Avisynth
//	Copyright (C) 2002 Tom Barry  - trbarry@trbarry.com
//
//	This program is free software; you can redistribute it and/or modify
//	it under the terms of the GNU General Public License as published by
//	the Free Software Foundation; either version 2 of the License, or
//	(at your option) any later version.
//
//	This program is distributed in the hope that it will be useful,
//	but WITHOUT ANY WARRANTY; without even the implied warranty of
//	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//	GNU General Public License for more details.
//
//	You should have received a copy of the GNU General Public License
//	along with this program; if not, write to the Free Software
//	Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Also, this program is "Philanthropy-Ware".  That is, if you like it and feel
the need to reward or inspire the author then please feel free (but not obligated) 
to consider joining or donating to the Electronic Frontier Foundation. This will 
help keep cyber space free of barbed wire and bullsh*t.  

See their web page at www.eff.org

***************

Okay, on to business. 

NOTE - THIS VERSION IS FOR AVISYNTH 2.5 ALPHA ONLY.  But the old version is 
probably also in another folder in the zip.

STMedianFilter is a (slightly motion compensated) spatial/temporal median filter.

It fairly very fine grained, using only adjacent pixels in space and time, so it
looks at the adjacent 26 locations to filter each location. It now filters both
luma and chroma but chroma filtering is somewhat more limited, as described later.

USAGE - To use it just:

1) Place the STMedianFilter.dll in a directory somewhere. You can get it from 
www.trbarry.com/STMedianFilter.zip

2) In your Avisynth file use commands similar to 

	LoadPlugin("F:\STMedianFilter\STMedianFilter.dll")
	Avisource("D:\wherever\myfile.avi")
	STMedianFilter(S_FilterThreshHold, S_EdgeThreshHold,
	               T_FilterThreshHold, T_MotionThreshHold) 

Of course replace the file and directory names with your own and supply the integer
values for parameters.  Valid values for each are from 0 to 255.

S and T above stand for spatial and temporal, respectively.

A good starting point for parm values might be 

    STMedianFilter(8,15,4,7)

Larger values cause more filtering but more artifacts. Parm descriptions:

  S_FilterThreshHold - don't spatial filter pixel if it would change it more than this
	Larger values may cause loss of fine line detail but it's not extremely sensitive.
  
  S_EdgeThreshHold - don't spatial filter pixel if on an edge where vals change more 
    than this. It seems fairly forgiving, so it can be raised a lot if desired.

  T_FilterThreshHold -don't Temporal filter pixel if it would change it more than this
	Large values will cause ghosting. Don't set over 5-10 to avoid ghosting.
	
  T_MotionThreshHold don't Temporal filter pixel if uncompensated motion vals change more 
    than this. Don't set over about 10 to avoid ghosting.


STMedianFilter should run on all SSEMMX machines or higher. 



METHOD OF OPERATION

But if I understand it right a simple median filter is just a clipping step 
where a value is set to not extend past the high and low of its neighbors. 

For instance, if you had 3 pixels in a row that had the values <5,8,7> you 
could clip the center one to not be outside the low of 5 or the high of 7,
so you would set it to 7. 

Now imagine you had a small 3x3 video screen, like one surface of a Rubiks
cube. Imagine the previous frame was the bottom layer of the cube, the 
current frame was the middle layer, and the next frame was the top. 

Then the current center pixel would be right in the center of the Rubics
cube and there would be 13 ways you could draw a line through it and a pair
of two nearest neighbors. 

What I did was to compare each of those pairs of neighbors to see which
pair was most agreeing on value. I used that pair to clip the value of the 
center pixel.  

I also clipped the pixel value only if both: 

1) It would not change the pixel value by more then the FilterThreshold parm value, and 

2) The amount of 'uncompensated motion' (agreement on value by neighbors) was less than the MotionThreshHold parm value. 



KNOWN ISSUES AND LIMITATIONS

1) 	Assumes YUV (YUY2 or YV12) Frame Based input. Use an AVIsynth function to convert
	first if needed.        

2)  Sorry, currently requires a P-III, Athlon, or higher. Needs SSEMMX support.

3)  This has been changed back to filter Luma only.  


FILE LOCATIONS

For now, both source, this readme, and DLL should be at:
	
	www.trbarry.com/STMedianFilter.zip

A copy of this Readme_STMedianFilter.txt file should be at:
  	
	www.trbarry.com/Readme_STMedianFilter.txt

Latest version 0.1.0.3 by Fizick, also at http://bag.hotmail.ru

***************

Change Log:


2004/08/19  v.0.1.0.3	Released by Fizick 2005/01/30
			Fixed bug with spatial filter radius for YV12
			Thanks to Fizick for this one.  Now also back
			at www.trbarry.com
			
2004/08/10  V 0.1.0.2 	by Fizick  - not public
			Fix one main bug (for both YUY2 and YV12 modes):
			in all previous versions light pixels were not filtered,
			both S_EdgeThreshHold and T_MotionThreshHold did not work also.

2003/06/22  V 0.1.0.1	Fix bug affecting YV12 only

2003/01/22  V 0.1.0.0	Remove chroma filtering again. Add YV12 support. Use Pluginit2
			Also remove Horizontal parms, add them to spatial.
			Hopefully fix purple tint.
						
2002/08/03  V 0.0.3.0   Add some chroma filtering

2002/08/03  V 0.0.2.0   Bugs, Split out spatial, Temporal, Horizontal user parms

2002/08/02  V 0.0.1.0   Initial test release