This file describes the object oriented list structures as well as the main
project tree of motiontrack.


---The Main Project Tree---------------------------------------------------------------------------

				----the motiontrack program runs differ(...), enlight(...),
		  motiontrack.c	    resize(...), blur(...), enhance(...)
			^	    and checkmove(...) on command line specified images
	     ._________/|
secmain.c    |		|	----the msectors program runs checkmove(...) on command line
   ^	     |		|	    specified images
   |	     ^		|	header for the checkmove function. checkmove divides
   |---«checkmove.h	|	the given gdlib structure into sectors and checks if some sectors
	   ^		|	are (lighting out of the rest) = are brighter than the average
	checkmove.c	|	gives back a struct sectorlist of these sectors.
			^
enhmain.c    .______.__/|	----the menhance program runs enhance(...) on
   ^	     |	    v	|	    command line specified images
   |	     ^	    |	|	header for the enhance function
   |---«enhance.h   |	|	enhance does an edge search in an gdlib struct
	   ^	    |	|	and saves the found edges in a second
	enhance.c   |	|	gives back only statistical stuff.
		    |	^
blurmain.c   .____._|__/|	----the mblur program runs blur(...) on
   ^	     |	   \|	|	    command line specified images
   |	     ^	    v	|	header for the blur function
   |---«blur.h	    |	|	blur does a smoothing function on a gdlib struct
	   ^	    |	|	and saves the blurred image in a second one
	blur.c	    |	|	the return value is not interesting.
		    |	^
enlmain.c    .______|__/|	----the menlight program runs enlight(...) on
   ^	     |	    |	|	    command line specified images
   |	     ^	    |	|	header for the enlight function
   |---«enlight.h   |	|	enlight increases the grey-scale brightness
	   ^	    |	|	of an image-struct and saves this in another
	enlight.c   |	|	return is quite useless.
		    |	^
normain.c    .______|__/|	----the normlz program runs normalize(...) on
   ^	     |	    |	|	    command line specified images
   |	     ^	    |	|	header for the normalize function
   |---«normalize.h |	|	normalize stretches the brightness range in images
	   ^	    |	|	over the full possible scale from 0 to 255
	normalize.c |	|	feel free to discard the return value.
		    |	^
diffmain.c   .______|__/|	----the mdiffer program runs differ(...) on commandline
   ^	     |	    |	|	    specified images
   |	     ^	    |	|	header for the differ function
   |---«differ.h    |	|	differ compares two given images
	   ^	    |	|	and saves the pixel brightness difference in a third
	differ.c    |	|	it gives back only useless status information.
		    |	|
resize.c    ._______|___/	----the mresize program runs resize(...) on comandline
   ^	    |	    |		    specified images
   |	    ^	    |		header for the resize function
   |---«resize.h    |		resize changs the size of an image, safing
	   ^	    |		it as greyscale
	resize.c    |		return values are waste.
		    |
sclmain.c    ._____ |		----the mscale program rus scale(...) on commandline
   ^	     |	   \|		    specified images
   |	     ^	    v		header for the scale function. scale accepts 4 source (edge)
   |---«scale.h	    |		coordinates and 4 destination coordinates and then shifts,
	   ^	    |		scales and rotates an image to make the source coords placed
	scale.c	    |		on destination coords. uninteresting return value.
		    |	
asciiart.c	    |		----the masciiart program, a demo to demonstrate early stage
   ^		    |		    of pattern detection, later to be used to identify moving
   |		    |		    objects
   |---«pattern.h   |		the header for the pattern function. pattern goes throgh the
	   ^	    |		image and searches for patterns out of a patternlist.
	pattern.c   |		how thats supposed to work later, see README ;)
		    |
align.c		    |		----the malign program, another pattern detection application
   ^_______________/		    aligns 2 images automatically if one is slightly rotated or 
   |				    shifted. Does this by comparing distinctive edge-features
   |---«findpattern.h		the header for the findpattern function. findpattern searches
	   ^			for the most likely position of a known pattern in a specified
	findpattern.c		image area.

---The Object Oriented List Classes:---------------------------------------------------------------


colorlist.h	--------header for the specific exclusion color handling class.
   ^			has all methods to add exclusion colors and check
   |---«colorlist.c	wheather a given color is in range of an exclusion color.
	   ^		colorlist is used by differ.c, difmain.c and motiontrack.c
    _______|
   /		patternlist.h	--------header for the specific pattern compare class
   |		   ^			has all methods to add, remove, and search for the best
   |		   |---«patternlist.c	matching, patterns ;)
   |			   ^		patternlist is used by asciiart.c asciichars.c, pattern.c
   | ______________________|		and findpattern.c
   |/		sectorlist.h	--------header for the specific motion sector handling class
   ^		   ^			has all methods to add, remove and print sectors.
   |		   |---«sectorlist.c	(or sectorlists)
   |			   ^		sectorlist is used by checkmove.c, secmain.c
   | ______________________|		and motiontrack.c
   |/		arglist.h	--------header for the specific command line argument
   ^		   ^			processing class. has all methods for handling
   |		   |---«arglist.c	command lines. really rocks, proud about it. used by
   |			 ^  ^		all executables.
   | ____________________|  |	
   |/			    |--«textlist.h	--------header for the specific text list class
   ^				   ^			has several methods for processing
   |				   |---«textlist.c	numbered text lines in a list
   |					   ^		thus far only used by arglist.c
   |_______________________________________|
   ^
voidlist.h		header for the generic list class, needed by all deduced classes
   ^
   |---«voidlist.c	the code of this class. Methods to add and remove list items, give out
   			generic list information like the amount of members, ...


---The Functional Function Librarys----------------------------------------------------------------


printtext.h		header for the printtext functions.
   ^			this library contains functions for generic text output like
   |---«printtext.c	help and GPL strings, and is used by every executable.
			

imageio.h		header for the imageio functions
   ^			this library contains all functions needed for low level image operations
   |---«imageio.c	like loading, saving and reading / modifiing pixels.
	   ^		it is used by all executables and all image manipulator functions
 imageio_gd.c		as well as imagemath.c
 imageio_imagemagick.c	Note that it splits on different wrapper functions depending on used
			imgage library.

imagemath.h		header for the imagemath functions
   ^			this library contains all functions needed for high level image operations
   |---«imagemath.c	like calculating a regions average light value
			it is used by all image manipulator functions.

asciichars.h		header for the asciichars functions.
   ^			this library contains a single function, which gives back a pattern list
   |---«asciichars.c	preinitialized with several common chars used in ASCII art ;) used by
			asciiart.c

cluster.h		header for the clustering functions.
   ^			this library contains the functions needed for multi-processing.
   |--«cluster.c	it us used by all cluster enabled image manipulator functions.
			image library dependant cluster functions reside in imageio_*.c

---The Useful Image Manipulation Functions---------------------------------------------------------

---checkmove.h :

struct sectorlist* checkmove(ImagePtr *dest, ImagePtr imsource, int deltabright,
			     int sectorsize, int method);
/*Returns a list of overbrighted sectors in source,
  and paints this sectors into a destination image
  a sector is overbrighted when more than 20% over
  the average sector brightness + deltabright if
  method is 0, and when >deltabright if method is 1
  */

---differ.h :

int differ(ImagePtr *dest ,ImagePtr imsource1, ImagePtr imsource2,
	   struct colorlist* excludelist);
/*Creates a Difference map between the 2 source images and
  stores it into the destination image*/

---findpattern.h :

struct patterntarget {
   int x;
   int y;
   int yield;
};


struct patterntarget findpattern(	ImagePtr imsource,
				struct pattern pattern,int x,int y,
				int width, int height );
/*Does a pattern search in imsource, searches for specific pattern around
  a given position*/


---normalize.h :

int normalize(ImagePtr* dest, ImagePtr imsource,int size);
/*Normalizes the brightness of the source image
  to use all values between 0 and 255
  and saves this into dest
  averages over <size> pixels when calculating
  minimum and maximum to disregard errors
  */

---enhance.h :

int enhance(ImagePtr* dest, ImagePtr imsource,
	int value1, int value2, int value3);
/*Greatly enhances the edges (object outlines) of source
  and saves this into dest, uses value/100 pixels for
  edge calculation around position, uses value2/100
  as multiplicator for enhance result
  value3 is a quality index which affects
  destination image size in percent, maximum is 100*/

---pattern.h :

struct patternfield {
   int width;
   int height;
   int *pattern;
};


struct patternfield pattern(	ImagePtr* dest, ImagePtr imsource,
				int patternwidth, int patternheight,
				int xwidth, int ywidth, struct patternlist* list);
/*Does a pattern search in imsource, saves a pattern in imdest
  and gives back a struct patternfield (uses patternlist list of course*/


---resize.h :

int resize(ImagePtr* dest, ImagePtr imsource,int value);
/*resize imsource by factor value % and saves the result in dest*/

---blur.h :

int blur(ImagePtr* dest, ImagePtr imsource, int value);
/*blurs the pixels of source and saves this into dest,
  uses value/100 pixels for blur calculation around position*/

---enlight.h :

int enlight(ImagePtr* dest, ImagePtr imsource,int value);
/*Modifies the brightness of the source image
  and saves this into dest*/

---scale.h :

int scale(ImagePtr* dest, ImagePtr imsource,int width,int height,
	int x11,int y11, int x12, int y12, int x13,int y13,int x14,int y14,
	int x21,int y21, int x22, int y22, int x23,int y23,int x24,int y24);
/*rescale imsource to size width,height and saves the result in dest
  also the pixels are shifted according to reference shifts in 4 edges*/


---The Executables---------------------------------------------------------------------------------

---malign---------------------------------------------------------------------
This Program will align a test sample image to a reference image
   and safe the result in a destination image.

Usage: malign <reference> <test> [<destination>] \
        [--help] [-h]

---masciiart------------------------------------------------------------------
This program will create an image containing
   some detected ASCII patterns in the source!

Usage: masciiart <source1> [<destination>] \
        [ -j <threads> ] \
        [--help] [-h]

---mblur----------------------------------------------------------------------
This program will create an image containing a blurred version of the source
   with <value> being the brush size for blur calculation,
   given in 1/100 pixels (default 300) 

Usage: mblur [ -v <value> | --value=<value> ] \
        [ -j <threads> ] \
        <source1> [<destination>] [[--help] [-h]

---mdiffer--------------------------------------------------------------------
This program will create an image containing the
   brightness difference of source1 and source2!

Usage: mdiffer \
        [ --color-exclude [<r>,<g>,<b>:<width>] ... --color-end ] \
        [ -j <threads> ] \
        <source1> <source2> [<destination>] [--help] [-h]

ColorExclude: A list of colors to ignore.
              Colors within <width> to this colors in any source
              will cause that pixel to be ignored
              End the list with --color-end.
              default is none

---menhance-------------------------------------------------------------------
This program will create an image containing
   the highlights of the detected edges in the specified source image!

Usage: menhance [ -s <value> | --size=<value> ] \
        [ -a <value> | --amount=<value> ] \
        [ -q <value> | --quality=<value> ] \
        [ -j <threads> ] \
        <source1> [<destination>] [[--help] [-h]

    size: The brush size for edge enhancing in 1/100 pixels.
          default is "--size=400"
  amount: Enlightenment factor in % for edges found.
          default is "--amount=2000"
 quality: Size of the destination image in %
          default is "--quality=50"
          (maximum is 100)

---menlight-------------------------------------------------------------------
This program will create an image containing
   a greyscale version of the source image,
   with its brightness changed to <value> %! 

Usage: menlight < -v <value> | --value=<value> > <source> [<destination>] \
        [ -j <threads> ] \
        [--help] [-h]

---mnormlz--------------------------------------------------------------------
This program will create an image containing
   a greyscale version of the source image,
   with its brightness normalized between 0 and 255!
   <value> specifies the averaging brushsize in pixels
   when searching for minimum and maximum, default 5.

Usage: mnormlz [ -v <value> | --value=<value> ] <source> [<destination>] \
        [ -j <threads> ] \
        [--help] [-h]

---motiontrack----------------------------------------------------------------
This program will create an image containing
   the movement sectors between source1 and source2!
The Sectorlist will go to stdout, the text to stderr.
For machine parsing try "motiontrack <arguments> 2>/dev/null | <parseprog>"

Usage: motiontrack [ -s <value> | --sensitivity=<value> ] \
        [ --absolute ] \
        [ -e <value> | --enlight=<value> ] \
        [ --blursize=<value> ] \
        [ --resize=<value> ] \
        [ --enhsize=<value> ] \
        [ --enhmul=<value> ] \
        [ --enhqual=<value> ] \
        [ --blur ] [ --no-enhance ] \
        [ --norm ] [ --normsize=<value> ] \
        [ --magnify ] [ --shrink ] \
        [ --color-exclude [<r>,<g>,<b>:<width>] ... --color-end ] \
        [ --exclude [<x>,<y>] [<x>,<y>] ... [<x>,<y>] --end ] \
        [ --sectorsize <value> ] \
        [ -j <threads> ] \
        <source1> <source2> [<destination>] [--help] [-h]

    absolute: Use this flag if you want motiontrack just to
              test if two images show the same motive
              instead of detecting moving objects.
 sensitivity: 0 detect smallest motions, much false alarms.
              1 some lesser sensitivity, less flase alarms.
              ...
              9 detect almost no motion, no false alarms.
              default is "-s 5"
     enlight: Enlightenment factor in %.
              Some camera input must be lighted / darkened.
              0 means black, 50 means half the light 200 means doubled.
              default is unchanged light which is "-e 100"
    normsize: averaging size in pixels for normalizing scan.
              default is not to normalize.
              note that normalizing and color-exclusion lists are
              mutually exclusive.
    blursize: The brush size for blurring in 1/100 pixels.
              default is not to blur at all.
      resize: Resize factor in %. 
     enhsize: The brush size for edge enhancing in 1/100 pixels.
              default is "--enhsize=400"
      enhmul: Enlightenment factor in % for edges found in enhance step.
              default is "--enhmul=2000"
     enhqual: Size of the enhance-destination image in %
              default is "--quality=50"
              (maximum is 100)

        norm: force normalizing of source images, same as "--normsize=5"
        blur: force blur step. same as "--blursize=300"
  no-enhance: force skipping of enhancing step.
     magnify: same as "--resize=200"
      shrink: same as "--resize=50"
ColorExclude: A list of colors to ignore.
              Colors within <width> to this colors in any source
              will cause that pixel to be ignored
              End the list with --color-end.
              default is none
     exclude: A list of sectors to ignore.
              can be given as [<x>,<y>:<b>] like in the output
              End the list with --end.
              default is none
  sectorsize: The size of a sector, default is 5 (pixel)

---mresize--------------------------------------------------------------------
This program will create a greyscale image being
   <value> % the size of the source!

Usage: mresize < -v <value> | --value=<value> > \
        <source1> [<destination>] \
        [ -j <threads> ] \
        [--help] [-h]

---mscale---------------------------------------------------------------------
This program will create a greyscale image being
   a rescaled version of the source!
   Destination size will default to the source size,
   but can be altered with --width and --height.
   Also you can specify old and new coordinates of
   4 reference points within the image,
   (top-left, top-right, bottom-left, bottom-right )
   which default to the edges if not given.

Usage: mscale [ -x <value> | --width=<value> ] \
        [-y <value> | --height=<value> ] \
        [ --sourcecoords <x1 y1 x2 y2 x3 y3 x4 y4> ] \
        [ --destcoords <x1 y1 x2 y2 x3 y3 x4 y4> ] \
        <source1> [<destination>] \
        [ -j <threads> ] \
        [--help] [-h]

---msectors-------------------------------------------------------------------
This Program will create an image containing
   the average brightness values in all 10x10 Pixel sectors
The Sectorlist will go to stdout, the text to stderr.
For machine parsing try "msectors <arguments> 2>/dev/null | <parseprog>"

Usage: msectors [ -s <value> | --sensitivity=<value> ] \
        [ --absolute ] \
        [ --exclude [<x>,<y>] [<x>,<y>] ... [<x>,<y>] --end ] \
        [ -j <threads> ] \
        [ --sectorsize <value> ] <source> [<destination>] [--help] [-h]

    Absolute: Use this flag if you want motiontrack just to
              test if two images show the same motive
              instead of detecting moving objects.
 Sensitivity: 0 detect smallest motions, much false alarms.
              1 some lesser sensitivity, less flase alarms.
              ...
              9 detect almost no motion, no false alarms.
              default is "-s 5"
     Exclude: A list of sectors to ignore.
              can be given as [<x>,<y>:<b>] like in the output
              End the list with --end.
              default is none
  Sectorsize: The size of a sector, default is 5 (pixel)

---------------------------------------------------------------------------------------------------
