README

IMSCRIPT
========


1. OVERVIEW

This is a collection of small independent image processing utilities in C.
These tools allow to do image processing from the comfort of the command line.

There is an online tutorial: http://gabarro.org/ccn/itut/i.html


2. PHILOSOPHY

Classic unix philosophy, with some specificities for images:

- each program does one thing and does it well
- programs work together via pipes
- offer mechanism, not policy
- images are arrays of numbers, representable by text files
- image metadata is always ignored (not used, not propagated)

Notice that imscript programs will read any common image format, but
will only write asc, pnm, png, and tiff.

See doc/misc/nipl.txt for a more complete description of the underlying
philosophy.


3. IMPLEMENTATION

The graph of dependencies between files is as disconnected as possible.
Most programs use the functions from "iio.c" for reading and writing images.
The interactive tools use the functions from "ftr.c" for the gui.
Some files may be directly included into others (e.g., "random.c").


4. COMPILATION

make -j        # build only the core tools
make full -j   # build all tools (including miscellaneous and interctive ones)


5. PREREQUISITES

The only real prerequisites are a C compiler and libfftw3f.

It is useful if you have libtiff, libjpeg, and libpng for input/output.

For the interactive tools you will need furthermore libX11.

Some tools on section "misc" require furthermore libgsl and libgslcblas.


6. INSTALLATION

There  is no automatic installation.  After compilation, just copy or link the
desired executables into your PATH (or add imscript/bin into the path).


7. SUMMARY OF PROGRAMS

* Filters: read one image and write one image of the same size

	- blur: convolve an image by a shift-invariant user-specified kernel
	- morsi: apply a morphological operation with a user-specified element
	- qeasy: re-scale the dynamic range of an image
	- qauto: re-scale the dynamic range of an image, automatically
	- palette: colorize a grayscale image using a palette
	- sauto: apply a signed palette
	- dither: binarize an image by error diffusion
	- iion: copy named input to named output (useful to change file format)

* Accumulators: combine several images into one
	- plambda: apply an arbitrary pixel-wise expression
	- veco: generic pixel-wise accumulators for gray images, gray output
	- vecov: generic pixel-wise accumulators for color images, color output
	- vecoh: generic pixel-wise accumulators for gray images, color output
	- tbcat: concatenate images vertically (top-bottom)
	- lrcat: concatenate images horizontally (left-right)

* Queries: extract data from one image
	- imprintf: print a formatted string of image data
	- ghisto: common histogram, in gnuplot format
	- contihist: continuous histogram
	- viewflow:  represent a vector field using a color code
	- flowarrows: represent a vector field using arrows

* Interpolators: fill-in the holes of one image
	- nnint: nearest neighbor interpolation
	- bdint: interpolation from the boundary of each hole
	- simpois: poisson, laplace and biharmonic interpolators
	- amle: absolutely minimizing lipschitz extension

* Rescalers: produce an image of different size or shape
	- downsa: zoom out by combining blocks of pixels
	- upsa: zoom in by interpolation inside cells
	- ntiply: zoom in by pixel replication
	- imflip: rotate or transpose the image domain
	- homwarp: apply an arbitrary homography to the image domain

* Frequecy domains:
	- fft: discrete Fourier transform (direct)
	- ifft: discrete Fourier transform (inverse)
	- dct: discrete cosine transform
	- dht: discrete Hartley transform
	- autocorr: centered autocorrelation (spatial domain, but still)

* Point processing:
	- pview: display points or matches as an image
	- ransac: generic ransac implementation
	- srmatch: multi-scale sift matching for registration
	- plyflatten: project 3D points into a 2.5D representation
	- colormesh: build 3D mesh from calibrated 2.5D representation
	- ijmesh: build 3D mesh from non-calibrated 2.5D representation

* Multi-program suites:
	- siftu: operations for sift keypoints (transform, match, etc)
	- tiffu: operations for tiff files (access tiles, sub-images, etc)
	- fontu: operations for bitmapped fonts

* Miscellaneous:
	- synflow: generate a synthetic optical flow field
	- ccproc: connected component filtering
	- ihough2: generic hough transform (for straight lines)
	- tdip: cylindrical hough transform (for sinusoids)
	- rpc_pm: patch match in the altitude domain
	- distance: distance function to a given set of points
	- sdistance: signed distance to the boundaries of a binary image
	- ppsmooth: periodic + smooth image decomposition
	- pmba2: poor man bundle adjustment
	- tcregistration: register two images by translation

* Interactive programs:
	- cpu: display an image with panning, zooming, contrast changes, and dft
	- rpcflip: flip between several geo-referenced satellite images
	- powerkill: fourier-domain band-pas filter editor
	- epiview: visualize the epipolar geometry between two images
	- viho: interactive homographic visualization
	- dosdo: look at an image and its fourier transform side by side
	- icrop: interactive crop

	NOTE: all interactive programs admit two backends.  By default, they
	open an x-window.  But they can also be compiled as "name_term" and
	then a simpler backend without graphical dependencies is produced.
	This backend us based on ANSI control sequences and utf-8 characters
	and should work on many modern terminals.  This backend is useful for
	interactive image visualization behind ssh.  Note that mouse support
	is still lacking for the ANSI backend, only the keyboard works.