RECTIFY(1)		    General Commands Manual		    RECTIFY(1)



NAME
       rectify	-  converge  towards  a target image using a Monte Carlo algo‐
       rithm.

SYNOPSIS
       rectify [IMAGE]
       rectify [IMAGE] [options]

DESCRIPTION
       Rectify is a command-line tool that uses a Monte Carlo  (MC)  algorithm
       to converge towards a target image using a random sequence of rectangu‐
       lar brush strokes.  Images produced by rectify have a ghostly,  impres‐
       sionistic quality.

       Rectify works by repeatedly attempting to apply a randomly placed black
       or white brush strokes of rectangular shape to a canvas. The stroke  is
       blended	with  the existing pixel block on the canvas and the change is
       accepted with a Boltzmann weight that accounts for  the	difference  in
       the  absolute value of the pixel block's distance from the target image
       following the trial move. The system is coupled to a thermal bath which
       allows the user to control the probability of accepting moves that take
       the image away from the target, thus allowing the rate  of  convergence
       to be tuned.

       Rectify	avoids	unneccessary  dependency  on  zlib and libpng by using
       LodePNG to decode and encode PNG images.	 MersenneTwister  is  used  to
       provide high quality and efficient random numbers.

       Rectify	must be passed at least one command-line argument, the path of
       a PNG IMAGE file to be used as the target image. The image  will	 auto‐
       matically  be  converted	 to  grayscale if color is detected. When run,
       rectify will output a sequence of images showing the evolution  of  the
       canvas  towards	the  target image. In addition, the current acceptance
       rate is printed to stdout allowing the user to monitor the rate of con‐
       vergence.

       Rectify	is trivially parellelizable, MPI support will follow (allowing
       efficient processing of very large images).

OPTIONS
       rectify	supports  the  following  short-  and  long-form  command-line
       options. Invoking rectify with no options will print a help message.

       -h, --help
	      Print the help message.

       -i INT, --iterations INT
	      Where INT is an integer specifying the number of MC iterations.

       -f INT, --frames INT
	      Where  INT  is  an integer specifying the number of frames to be
	      saved.

       -s DOUBLE, --stroke DOUBLE
	      Set the maximum extent of the trial stroke, where	 DOUBLE	 indi‐
	      cates the stroke extent as a fraction of the target image width,
	      e.g.  a value of 0.5 would set the maximum stroke	 extent	 (both
	      width  and  height)  to  half the width of the target image. The
	      algorithm proceeds more slowly when the maximum stroke width  is
	      large since, on average, more pixels must be processed per trial
	      move.

       -c IMAGE, --canvas IMAGE
	      Start the algorithm using an existing canvas given by PNG	 IMAGE
	      file.  The  IMAGE	 must be the same size as the target otherwise
	      rectify will abort. If the IMAGE is full color it will  be  con‐
	      verted  to  grayscale  before the algorithm starts.  This option
	      can also be used to continue covergence from an existing rectify
	      project, e.g. if too few iterations were chosen.

       -t DOUBLE, --temperature DOUBLE
	      Specify  the  temperature of the thermal bath. A higher tempera‐
	      ture will mean that more trial brush strokes  are	 accepted.  At
	      zero  temperature, only moves that take the canvas closer to the
	      target will be accepted (comparable to  a	 hill  climbing	 algo‐
	      rithm).  Temperature adds noise to the system and can be used to
	      tune the rate of convergence as well as the style of image  pro‐
	      duced.

       -l, --log
	      Use logarithmic spacing for sampling points. This is useful when
	      convergence is very slow.

       -d DIRECTORY, --directory DIRECTORY
	      Specify a directory for the output files.	 DIRECTORY  should  be
	      in  the  working	directory  and	will  be created if it doesn't
	      already exist.

       -m, --monitor
	      Turn on acceptance monitoring. If set, rectify will monitor sta‐
	      tistics  for  the	 acceptance  rate  and	compute histograms for
	      accepted brush strokes. This  is	useful	for  determining  what
	      stroke  sizes  are  dominant as the canvas evolves. Trial stroke
	      sizes can be tuned accordingly.  In monitor mode,	 rectify  will
	      produce three additional output files: log.txt a log file of the
	      acceptance rate at each sampling time  hist.txt  the  acceptance
	      probability   for	  each	 stroke	  size	(width,	 height),  and
	      hist_xy.txt a two-dimensional matrix of the histogram data.

DEFAULTS
       iterations 1000000

       frames 1000

       temperature 0.1

       stroke 0.1

       logarithmic off

       monitor off

SEE ALSO
       flux(1)

CREDITS
       LodePNG, http://lodev.org/lodepng.

       MersenneTwister, www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html.

       Anna, for the name.

BUGS
       Email bugs, comments, and artwork to lester.hedges+rectify@gmail.com.



Lester Hedges			  2013/01/21			    RECTIFY(1)