binningfilter
=============

What it is
----------

This is a filter element for GStreamer 1.0 for binning (adding) pixels together. This increases the sensitivity of the source (camera) at the expense of spatial resolution.

Comments
--------

 - Includes a property to allow resizing of the image. Normally every pixel is replaced by the sum of those around it, but if resize is selected then only every nth pixel is used and these pixels are grouped up in the top left of the frame. Use a videocrop element to extract this smaller image from the frame. This is useful if you have a high resolution camera with a large number of pixels but instead want to use it as a more sensitive camera with larger pixels, and a smaller image.

 - Includes ability to apply binning on the linear intensity scale even if the vidoe feed has gamma applied. See src/gstbinningfilter.h for the GAMMA factor. Set this to 1 (one) to disable this feature.
 
 - Has a 'chroma' algorithm for binning which does this: get r=R-G and b=B-G, average r and b, maybe multiply by some weight (chroma_weight), sum G, calculate new R=G+r, B=G+b. This is usually not as sucessful as straight binning of the RGB components individually.

 - Allows for a black level offset to be applied to each channel in case the black level of the source is not well adjusted.
 
 - Allows for the RGB channels to be balanced with 'contrast' properties.

Building
--------

Building on linux is tested using the autogen script.

First run autogen.sh
	$ chmod a+x autogen.sh
	$ ./autogen.sh
This will use autotools to setup the dev environment, and complete with the line:
"Now type 'make' to compile this module."
You can do that.
	$ make

	$ sudo make install 
will put install the lo file for use with GStreamer, in /usr/local/lib/gstreamer-1.0
To use this in a pipeline you need to tell gstreamer where to find the .lo file.
use:
	$ export GST_PLUGIN_PATH=/usr/local/lib/gstreamer-1.0

See the INSTALL file for advanced setup.

To import into the Eclipse IDE, use "existing code as Makefile project", and the file EclipseSymbolsAndIncludePaths.xml is included here
to import the library locations into the project (Properties -> C/C++ General -> Paths and symbols).

Libraries
---------

Example commands for installing the GStreamer development libraries on Ubuntu 12.04sudo add-apt-repository -y ppa:gstreamer-developers/ppa
	sudo apt-get update
	sudo apt-get install -y dpkg-dev devscripts
	sudo apt-get install -y gstreamer1.0*
	sudo apt-get install -y libgstreamer-plugins-base1.0-dev
	echo "export GST_PLUGIN_PATH=/usr/local/lib/gstreamer-1.0" >> ~/.profile
	sudo apt-get install -y build-essential libgtk-3-dev

pipelines
---------

	gst-launch-1.0 videotestsrc smoothingfilter ! videoconvert ! xvimagesink
	gst-inspect-1.0 smoothingfilter

Locations
---------

Gstreamer plugin locations:
/usr/lib/i386-linux-gnu/gstreamer-1.0
/usr/local/lib/gstreamer-1.0