
				Motion Detection

			       by  Corvus V Corax

I   Description		A short descripion of motiontrack
II  License		A refer to GPL v2
III Executables		A listing of all programs that make motiontrack
IV  Install		Some installation instructions
V   Parameters		A description of program commandline parameters
VI  Usage		How you could use the motiontrack programs
VII Developmet,		If anyone is interested in the code
    Forks and Todos


-I   Description:

 Motiontrack is a set of backend tools that can be used for motion detection

   ! Please don't use this software to help monitor places   !
   ! where it impairs the privacy of other people, like      !
   ! monitoring public places and streets, CCTV, voyeurism...!
   ! http://www.stop1984.org -- against total surveillance!  !

 Right now it is able to detect changes between 2 images that resulted
 to motion (in opposition to changes doe to random clutter)
 and tell the areas (i called them sectors) where this motion did happen.
 (This process is very configurable to fit your local needs, like
  optimizing your images in several ways, ignoring colors and areas )
 
 Motiontrack is also able to compare two images and check them for
 differences, even if the images are poorly aligned.
 (for example 2 scanned copies with both angle and shift derivation,
 as well as moderate brightness difference)
 It could even auto-align slightly polygonal distorted images,
 for example taken with a webcam at not exactly the same angle
 however this is currently beta code.

 Path for the future is to make motiontrack able to recognize the objects
 which are actually moving. First thing realized now is simple pattern
 detection. The software should later be able to recognize for example
 ball = object cosisting of several arc segments around nothing
	(in edge enhance view)
 face = object with arcs around. horizontal lines in the lower half,
	upside down 'V' above, topped by 2 circles, ...
 ...
 where those simple geometric structures are the patterns to detect by
 patern matching then, and the object recognizing above being done by
 simple neuralnet AI ;) or some really cool hack, dunno, notthing done yet.

 The pattern detection is thus far able to turn line art into ASCII art,
 and search for distinctive features for auto-alignment :-)



-II  License:

 Gnu Public License (GLP) 2 (or above)
 (see COPYING)



-III Executables:

 mdiffer	[ --color-exclude [<red>,<green>,<blue>:<width>] ... \
		... [<red>,<green>,<blue>:<width>] --color-end ] \
		<source1> <source2> [<destination>] [--help] [-h]

 mnormlz	[ -v <value> | --value=<value> ] <source> [<destination>] \
	        [--help] [-h]

 menlight	< -v <value> | --value=<value> > <source> [<destination>] \
		[--help] [-h]

 mblur		[ -v <value> | --value=<value> ] \
		<source> [<destination>] [--help] [-h]

 mresize	< -v <value> | --value=<value> > <source> [<destination>] \
		[--help] [-h]

 menhance	[ -s <value> | --size=<value> ] \
		[ -a <value> | --amount=<value> ] \
		[ -q <value> | --quality=<value> ] \
		<source> [<destination>] [--help] [-h]

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

 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 [<red>,<green>,<blue>:<width>] ... \
		... [<red>,<green>,<blue>:<width>] --color-end ] \
		[ --exclude [<x>,<y>] [<x>,<y>] ... [<x>,<y>] --end ] \
		[ --sectorsize=<value> ] \
		<source1> <source2> [<destination>] [--help] [-h]

 masciiart	<source> [<destination>] [--help] [-h]

 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>] [--help] [-h]

 malign		<reference> <test> [<destination>]
		[--help] [-h]



-IV  Install:

 Motiontrack needs an installed image manipulation library to compile.
 This can be either libgd  or ImageMagick, with support for your favorite
 image formats, installed on your system.

 Note that the GD library is currently the default, since it has been used
 longer and the code is more speed optimized.
 This may change in the future.

 If you got the motiontrack sources from CVS, you first have to create
 the configure scripts by running

   ./autogen.sh <configure options>

 (which will automatically run ./configure with these options afterwards)

 If you are installing from an tarball, you can also run

   ./configure --prefix=<path to install>

 where <path to install> is for example /usr if you want your executables
 in /usr/bin, or /usr/local if you want them in /usr/local/bin.
 standard is /usr/local.

 Note that the pre-created configure script has created invalid makefiles
 on a bsd system i tried it on, if configure misbehaves, regenerate a local
 version via autogen.sh and your autoconf/autoheader/automake installation.

 configure searches for all programs and libraries needed by motiontrack to
 compile in your system standard library and include paths.
 You can give hints where to search additionally, by specifying
 
   ./configure --with-searchdirs=<prefix1>:...:<prefixN>
   
 or setting some environment variables accordingly, like LIBRARY_PATH and
 C_INCLUDE_PATH, or the -L<dir> and -I<dir> options in CFLAGS, CPPFLAGS
 or LDFLAGS.

   ./configure --help

 lists all possible configure options, like library preferences,
 GD versus ImageMagick, debug options, ...

 Note that you can compile in multi-processing support when specifying
 --enable-cluster to configure, since motiontrack 0.1.3.
 This adds the optional flag [ -j <pnum> ] to all cluster enabled
 executables, where you can tell motiontrack how many processes to spawn
 for image processing.
 
 run

    make
    make install

 to create and install the whole package.
 (all executables, sorry, no manpage yet)



-V   Parameters:

 To see a short usage description run each file without parameters.


 mdiffer [ --color-exclude [<red>,<green>,<blue>:<width>] ... \
	 ... [<red>,<green>,<blue>:<width>] --color-end ] \
	 <sourcefile1> <sourcefile2> [<destinationfile>] [--help] [-h]

   [--help] and [-h]
   specify on of these to get a short help. specifiying nothing does same

   [ --color-exclude [<red>,<green>,<blue>:<width>] \
   ... [<red>,<green>,<blue>:<width>] --color-end ]
   is an optional set of parameters to specify colors to ignore, when
   checking for image differences.
   A color consists of 3 RGB values, which have to be in range 0..255,
   ( black: 0,0,0 --  red: 255,0,0 -- green: 0,255,0 -- blue: 0,0,255 -- ... )
   and a width value for exclusion accuracy.
   Any positive integer is accepted for width.
   DONT forget the --color-end tag to close the list, or motiontrack wont run

   <sourcefile1> and <sourcefile2>
   are to be images. If their sizes differ, only the overlapping regions
   will be used

   [<destinationfile>]
   is the (optional but recommended) filename of the resulting image to create

   image filetypes are determined by filename extensions

   output to <stdout> is the overall pixel brightness of the resulting image


 mnormlz [ -v <value> | --value=<value> ] <source> [<destination>] \
	 [--help] [-h]

   [--help] and [-h]
   specify on of these to get a short help. specifiying nothing does same

   [ -v <value> || --value=<value> >
   when checking for minima and maxima, average over <value> pixels
   to discard extremas

   <sourcefile>
   is to be a valid image file to enlight

   [<destinationfile>]
   is the (optional but recommended) filename of the resulting image to create

   image filetypes are determined by filename extensions

   output to <stdout> is the overall pixel brightness of the resulting image

 
 menlight < -v <value> | --value=<value> > <sourcefile> [<destinationfile>] \
	  [--help] [-h]

   [--help] and [-h]
   specify on of these to get a short help. specifiying nothing does same

   < -v <value> || --value=<value> >
   the resulting image will have <value>% of the source brightness
   specifying 100 makes a 1 on 1 greyscale copy

   <sourcefile>
   is to be a valid image file to enlight

   [<destinationfile>]
   is the (optional but recommended) filename of the resulting image to create

   image filetypes are determined by filename extensions

   output to <stdout> is the overall pixel brightness of the resulting image


 mblur [ -v <value> | --value=<value> ] \
       <sourcefile> [<destinationfile>] [--help] [-h]

   [--help] and [-h]
   specify on of these to get a short help. specifiying nothing does same

   [ -v <value> | --value=<value> ]
   the brush size for blur calculation in 1/100 pixels
   default is 300
   
   <sourcefile>
   is to be a valid image file to blur

   [<destinationfile>]
   is the (optional but recommended) filename of the resulting image to create

   image filetypes are determined by filename extensions

   output to <stdout> is the overall pixel brightness of the resulting image


 mresize < -v <value> | --value=<value> > <sourcefile> [<destinationfile>] \
	 [--help] [-h]

   [--help] and [-h]
   specify on of these to get a short help. specifiying nothing does same

   < -v <value> | --value=<value> >
   percentage of the original size, 100 would make a greyscale
   1 to 1 copy.
   
   <sourcefile>
   is to be a valid image file to enhance

   [<destinationfile>]
   is the (optional but recommended) filename of the resulting image to create

   image filetypes are determined by filename extensions

   output to <stdout> is the overall pixel brightness of the resulting image


 menhance [ -s <value> | --size=<value> ] \
	  [ -a <value> | --amount=<value> ] \
	  [ -q <value> | --quality=<value> ] \
	  <sourcefile> [<destinationfile>] [--help] [-h]

   [--help] and [-h]
   specify on of these to get a short help. specifiying nothing does same

   [ -s <value> | --size=<value> ]
   the brush size for enhance calculation in 1/100 pixels
   default is 400

   [ -a <value> | --amount=<value> ]
   multiplicator for the resulting edges found, in %
   default is 2000

   [ -q <value> | --quality=<value> ]
   the resolution of the edge search result,
   affects the destination image size and the calculation speed
   with factor 4!
   default is 50, values above 100 are useless

   <sourcefile>
   is to be a valid image file to enhance

   [<destinationfile>]
   is the (optional but recommended) filename of the resulting image to create

   image filetypes are determined by filename extensions

   output to <stdout> is the overall pixel brightness of the resulting image


 msectors [ -s <value> | --sensitivity=<value> ] \
	  [ --absolute ] \
 	  [ --exclude [<x1>,<y1>] [<x2>,<y2>] ... [<xn>,<yn>] --end ] \
	  [ --sectorsize=<value> ] <sourcefile> [<destinationfile>] \
	  [--help] [-h]

   [--help] and [-h]
   specify on of these to get a short help. specifiying nothing does same

   [ --absolute ]
   use an absolute brightness threshold for sector-check instead of one
   relative to the average difference. This might be usefull,
   when auto-comparing several images where some show completely
   different stuff, what could produce false negatives doe to a very high
   "difference average"

   [ -s <value> | --sensitivity=<value> ]
   is an optional parameter to specify the motion detection sensitivity
   value reaches from
	0	greatest sensitivity. motiontrack might detect any slightest
	...	motion, but the risc of false alarm is high.
	...
	5	the standard value, accurate motiondetection with low
	...	false alarm risk.
	...
	9	lowest risk of false alarms doe to flicker. but is unlikely
		to detect small motions.
		use when you want to detect intruding elephants

   [ --exclude [<x1>,<y1>] [<x2>,<y2>] ... [<xn>,<yn>] --end ]
   is an optional set of parameters to specify sectors to ignore, when
   checking for motion. sectors can be of type <x>,<y>
   for the plain coordinates or <x>,<y>:<z> where z is ignored.
   this way one can use the format of the output as input without
   change
   DONT forget the --end tag to close the list, or motiontrack wont run

   [ --sectorsize=<value> ]
   specifys the size of a sector in pixels. For example 20 will
   cause sectors to be 20x20 pixels in size.
   default value is 5.

   <sourcefile>
   is to be a valid image file to analyze

   [<destinationfile>]
   is the filename of an optional resulting image to create

   image filetypes are determined by filename extensions

   output to <stdout> is the amount of sectors with motion in it,
   followed by an ordered list of this sectors (if any) and their
   brightness value in the form:
      x1,y1:brightnes1 x2,y2:brightnes2 ... xn,yn:brightnesn
   this format can be used, too if one wants to specify an exclude list.


 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 [<red>,<green>,<blue>:<width>] ... \
	     ... [<red>,<green>,<blue>:<width>] --color-end ] \
	     [ --exclude [<x>,<y>] [<x>,<y>] ... [<x>,<y>] --end ] \
	     [ --sectorsize=<value> ] \
	     <sourcefile1> <sourcefile2> [<destinationfile>] [--help] [-h]


   [--help] and [-h]
   specify on of these to get a short help. specifiying nothing does same

   [ --absolute ]
   use an absolute brightness threshold for sector-check instead of one
   relative to the average difference. This might be usefull,
   when auto-comparing several images where some show completely
   different stuff, what could produce false negatives doe to a very high
   "difference average"

   [ -s <value> || --sensitivity=<value> ]
   is an optional parameter to specify the motion detection sensitivity
   value reaches from
	0	greatest sensitivity. motiontrack might detect any slightest
	...	motion, but the risc of false alarm is high.
	...
	5	the standard value, accurate motiondetection with low
	...	false alarm risk.
	...
	9	lowest risk of false alarms doe to flicker. but is unlikely
		to detect small motions.
		use when you want to detect intruding elephants

   < -e <value> || --enlight=<value> >
   if given, menlight will be run internally after the mdiffer step
   specify <value> as % of the source brightness, 100 does nothing

   [ --normsize=<value> ]
   when checking for minima and maxima, average over <value> pixels
   to discard extremas, when given motiontrack will normalize source images
   before calculationg difference. Note that will render color-exclusion
   useless, since this step greyscales and changes colors beforehand.
   
   [ --blursize=<value> ]
   the brush size for blur calculation in 1/100 pixels
   if given, mblur will be run internally after the mdiffer (or menlight) step

   [ --resize=<value> ]
   percentage of the original size for mresize.
   if given, mresize will be run internally before the menhance step

   [ --enhsize=<value> ]
   the brush size for enhance calculation in 1/100 pixels
   default is 400

   [ --enhmul=<value> ]
   enhance calculation multiplicator for the resulting edges found, in %
   default is 2000

   [ --enhqual=<value> ]
   the resolution of the edge search result,
   affects the destination image size and the calculation speed
   with factor 4!
   default is 50, values above 100 are useless

   [--norm]
   same as "--normsize=5"

   [--blur]
   same as "--blursize=300"

   [--no-enhance]
   if given no enhancing takes place before sectors is being runned internally.

   [--magnify]
   same as "--resize=200"

   [--shrink]
   same as "--resize=50"

   [--color-exclude [<red>,<green>,<blue>:<width>] \
   ... [<red>,<green>,<blue>:<width>] --color-end ]
   is an optional set of parameters to specify colors to ignore, when
   checking for image differences.
   A color consists of 3 RGB values, which have to be in range 0..255,
   ( black: 0,0,0 --  red: 255,0,0 -- green: 0,255,0 -- blue: 0,0,255 -- ... )
   and a width value for exclusion accuracy.
   Any positive integer is accepted for width.
   DONT forget the --color-end tag to close the list, or motiontrack wont run.

   [--exclude [<x1>,<y1>] [<x2>,<y2>] ... [<xn>,<yn>] --end ]
   is an optional set of parameters to specify sectors to ignore, when
   checking for motion. sectors can be of type <x>,<y>
   for the plain coordinates or <x>,<y>:<z> where z is ignored.
   this way one can use the format of the output as input without
   change
   DONT forget the --end tag to close the list, or motiontrack wont run.

   [--sectorsize=<value>]
   specifys the size of a sector in pixels. For example 20 will
   cause sectors to be 20x20 pixels in size.
   default value is 5

   <sourcefile1> and <sourcefile2>
   are to be images. If their sizes differ, only the overlapping regions
   will be used

   [<destinationfile>]
   is the filename of an optional resulting image to create

   image filetypes are determined by filename extensions

   output to <stdout> is the amount of sectors with motion in it,
   followed by an ordered list of this sectors (if any) and their
   brightness value in the form:
      x1,y1:brightnes1 x2,y2:brightnes2 ... xn,yn:brightnesn
   this format can be used, too if one wants to specify an exclude list


 masciiart <source> [<destination>] [--help] [-h]

   [--help] and [-h]
   specify on of these to get a short help. specifiying nothing does same

   <sourcefile>
   is to be a valid image file to ascii-paint

   [<destinationfile>]
   is the (optional) filename of the resulting image to create

   image filetypes are determined by filename extensions

   output to <stdout> is the ASCII version of the ASCII art (while the output
   image is a bitmap version of this, showing the internal patterns for debug)


 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>] [--help] [-h]

   [--help] and [-h]
   specify on of these to get a short help. specifiying nothing does same

   [ -x <value> | --width=<value> ]
   is to be the width of the destination image in pixels, default is
   the same as the source

   [ -y <value> | --height=<value> ]
   is to be the height of the destination image in pixels, default is
   the same as the source

   [ -- sourcecoords <x1 y1 x2 y2 x3 y3 x4 y4> ]
   these coordinates mark 4 points in the source image, which should be
   near the edges in the order
   <top-left> <top-right> <bottom-left> <bottom-right>
   if not given they default to the edges itself

   [ --destcoords <x1 y1 x2 y2 x3 y3 x4 y4> ]
   these coordinates mark the destination where you want those reference
   points to end at. As long as you dont try rotations of more than 20°
   in any direction this way, this should be quite accurate, however its still
   a simple apreviation algorithm in beta stage.
   So you will create distortions if your specify them too extremely misplaced.
   Default are the coords as the edges of the destination image
   You can speficy coords outside the image bounds for both coordinate sets.

   <sourcefile>
   is to be a valid image file to ascii-paint

   [<destinationfile>]
   is the (optional) filename of the resulting image to create

   image filetypes are determined by filename extensions

   output to <stdout> is the ASCII version of the ASCII art (while the output
   image is a bitmap version of this, showing the internal patterns for debug)


 malign <reference> <test> [<destination>] [--help] [-h]

   [--help] and [-h]
   specify on of these to get a short help. specifiying nothing does same

   <reference>
   is to be a valid image file to use as a reference to align the
   test image to

   <test>
   is to be a valid image file to rescale to be then compared
   to the reference image

   [<destinationfile>]
   is the (optional but recommended) filename of the resulting image to create

   image filetypes are determined by filename extensions

   output to <stdout> is the ASCII version of the ASCII art (while the output
   image is a bitmap version of this, showing the internal patterns for debug)



-VI  Usage:

  Using Multi Processing (clustering):
  
 When compiled with "--enable-cluster" you can tell each motiontrack
 executable how many processes to spawn, default is 4 when compiled with
 multi processing support (and of course 1 when compiled without).
 Do this with

   m<name> ...<options>... [ -j <number of processes> ]

 When motiontrack is compiled without cluster support, this option is valid
 but has no effect.


  Motion Detection:

 You need 2 images (from a webcam or video stream),
 with aprox. 1 second time difference.

 You can check for differences in pixel brightness between this images
 with:

   mdiffer <source1> <source2> <destination> \
          [--color-exclude <list> --color-end ]

 These brightness differences indicate possible object motion between
 the image, as well as random flicker and smoke produced by your camera
 and the light sources.

 If you are not interested in motion or changes that happen to be in
 specific colors (for example because sometimes you have random black lines,
 or red dots in your images you are not interested in)
 you can exclude everything which is in this colors in either one of the
 source images from the whole check.
 The width parameter of colors sets the detection accuracy.
 a width of 2 or 3 will exclude only the specified color, while one above
 100 will exclude much that does look somehow alike this color.
 Feel free to experiment around, while running mdiffer between any image and
 a black reference image, to test this values for your case.

 If you get better results, you can change the brightness of these
 differences with

   menlight -e <value> <source> <destination>

 If your input images are very dark, value should be up to 400 to get
 optimal results, if it is too bright, specify 25 to get brightness to
 a quarter.

 If your images are too big so they take too long to process,
 you can use motiontracks

   mresize -v <value> <source> <destination>

 tool, to get into a better magnitude of size.
 try 50  for value to make an image half the resoulution

 Now check for possible objects in the output of mdiffer with the
 edge enhancer:

   menhance -s <size> -q <quality> -a <mult> <source> <destination>

 This edge enhancement brightly amplifies any sharp borders in the
 given image, which are the moved objects.
 But it unfortunately does light up pixel sized inconsitencies, too.
 Increasing the brush size makes it much slower, but enables better
 distinguish between real edges and random inconsistencies or
 compression artefacts.
 If you increase size, you should decrease quality to make less
 checks in the same area, producing a smaller result image,
 otherwise it could get way too slow.
 Also you can change the result multiplicator from the default *20
 (2000%) to different values, which should have a similar effect
 as changing the sensitivity of the sector check.
 
 Now while the random pixel changes are now represented by evenly spread spots
 over the image, the real movements, or moving objects are outlined in
 their old and new position, and their contures can be easily spotted
 as contiguous bright areas.

 By dividing thise image in sectors of equal (default 5x5) pixel size

   msectors [-s <value>] <source> [destination] [-s <value>]\
	    [--sectorsize=<value>] [--exclude <list> --end]

 all sectors are at somehow the same average brightness
 doe to the equaly spread random inconsistencies,
 except the sectors which include real object movement
 which tend to be much brighter.

 If you want the sectors to be 50x50 pixel, since you check in really
 large images, specify "--sectorsize 50" for example.

 Remeber to increase or decrese sectorsize when you fiddle with the enhance
 quality.
 For example since enhance does use quality 50% for default now
 i decreased the original 10x10 default sector size to 5x5 to get
 the same overall behaviour back.

 msectors gives back an optional image with all sectors shown

 depending on the given sensitivity ( -s 0 till -s 9 ) the overbright sectors
 are detected as motion and given back.

 If you are not interested in motion in specific sectors, for example
 cause there is a clock in your picture at sectors 2,2 2,3 3,2 and 3,3
 you can exclude them via "--exclude 2,2 2,3 3,2 3,3 --end"

 If you are not interested in the technical details and dont need the images
 of the steps in between, you can just check for motion between 2 images with

   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 [<red>,<green>,<blue>:<width>] ... \
	       ... [<red>,<green>,<blue>:<width>] --color-end ] \
	       [ --exclude [<x>,<y>] [<x>,<y>] ... [<x>,<y>] --end ] \
	       [ --sectorsize=<value> ] \
	       <sourcefile1> <sourcefile2> [<destinationfile>] [--help] [-h]

 All text output of every executable goes to
   <stderr>
 except for a single number representing the amont of pixel brightness
 or the amount of sectors with motion in it in sectors and motiontrack,
 which goes to
   <stdout>
 Also does the ascii art of "masciiart".

 In addition to that, sectors and motiontrack give out an ordered sectorlist
 of the sectors with motion detected in it to <stdout> in the form

   x1,y1:brightnes1 x2,y2:brightnes2 x3,y3:brightnes3 ... xn,yn:brightnesn

 where the brightness represents the motion detected there.

 You can grep this output and process in your own scripts easily :-)

 Also you can specify a list of this format as an exclude list, this way
 saving the work of removing the useless brightness values :-))


  Comparing generic images:

 Generic image comparison, it much related to motiontracks approach of
 motion detection. However for motion detection the movement-search
 algorithm assumes that most parts of the images are actually the same,
 while in some area, movement happens.

 When comparing generic images, especially images that show completely
 different stuff, this could lead to false negatives, so an absolute
 algorithm might have to be used instead. You can do that by adding the
 [ --absolute ] flag to "motiontrack" or "msectors".

 If you do so, you might also want to disable enhancement and enable blur
 instead,  depending on your image source. Especially when using the
 auto-align functions, small remeaning disalignments could result into
 big detected differences when being edge-enhanced.


  Auto alignment:
 
 The "mscale" program can morph around images in an interesting way
 while being created to fit the needs of the "malign" program,
 it fails badly at greater rotation angles (>45°), however you can
 still use it for basic re-scaling and changing the image width to height
 ratio.

 The "malign" program assumes that while two images show the same, they
 are disaligned, so it searches for some unique features near the edges
 in one image, and then tries to find the same features
 in the reference image.

 While this only works with derivation of some douzend pixel of shift
 or rotation of less than 10° like they happen if you scan an image two
 times without accurately aligning it on your flatbed scanner, its still
 might be a feature to prove itself worthy for several applications.

 You could for example try to compare two webcam taken images of the same
 motive at slightly different angles this way.

 Feel free to contact the developer (me) with feedback and suggestions.


  Pattern Detecton:

 Usage of

   masciiart <source> [<destination>] [--help] [-h]

 Your source image should be white on black line art (for optimal results).
 You can test it with the output of "menhance" used on your webcam images
 maybe you get something useful. mine produces too much 'clutter'.
 Hint: higher resolution images result into better ascii art
       when processing after the enhance step,
       but they might not fit in 80x25 anymore then.



-VII Development, Forks and Todos:

 Actual version is 0.1.3

 The stuff is getting more complex from now on,
 so if anyone would like to contribute  now would be a good time to start,
 since the code is still simple enough to get throgh.
 Read src/TheCode.txt for a file and class overview, and the headers for
 function descriptions.

 TODO is everything that brings motiontrack forward, optimizing code,
 documentation, hacking an AI, whatevery a coder can imagine ;)

   Have fun
			Corvus V Corax
						   corvuscorax@cybertrench.com
