! ! Imlib: a small image processing application toolbox for PGM, PPM, and ! BIL images. ! 0. Introduction ____________________ 0.1 Acknowledgements -------------------- This package is an outgrowth of work I did in France at INRIA (PASTIS project), and subsequent work at SSC Satellitbild (www.ssc.se/sb). The following people have helped with the packade: -Daniel Reisfeld (the kernel class) -Robert Davis (the Matrix classes) -Philippe Thévenaz (the spline interpolation) -Snippets from the KUIM image processing system (see below). __________________________________________ 0.2 Yet another package...is this for you? ------------------------------------------ I was never able to find source code that could handle BIL images, so I decided to write a simple image reader that did that. With that work quickly ensued the porting of various programs I have written over the years. Using other peoples programs is never easy, we all have different opinions on how things should be implemented and why, so I have tried to the use of the package as easy as possible. The general philosophy with the present toolkit is to put most of the intelligence in class-libraries, while making it relatively easy to write your own applications, and add you own source. I have included a number of examples in an "Applications" directory, the best way to understand how the toolkit works comes from studying these examples. There's some html documentation included as well, and if you have the source code documentation system "doxygen" installed, additional documentation can be generated (see below). A major limitation is still that you can't resample images using strip-wise I/O. I might look into it if I need it myself... __________________________________ 0.3 Remote sensing specific issues ---------------------------------- One of the unique things with remotely sensed images is their spatial extent (in pixels and in absolute terms) which can be very large. Let it be clear at once: This package does not handle "enormous" images. However, I have tried to deal with the problem in allowing for strip-wise I/O: read an image strip at a time, process the image, and write it to disk. Most of the algorithms can deal with "strip" images as well as "ordinary" images. See e.g. "grad.cpp" or "laystack.cpp" for an example of strip-size image processing. There is a free (=gnu-licensed) package that does handle large images (using tiling) - "Limp" - available at www.remotesensing.org ______________________________________ Is this for you? Read the following.... -------------------------------------- The toolbox has the following features: . Region growing with iterative best neighbour merging of segments using statistical likeness (t-test). It involves a lot of parameters, but they are contained in separate files to make parameter tweaking easy. NOTE: The region growing operation is inherently time consuming, and does not work for "large" images depending on your RAM. The rest of the applications represent more or less standard image processing applications. . SVD decomposition of 2D filters . Parametric Wiener filtering for fast deconvolution . Wavelet regularized Lucy-Richardson/jacobi-iteration deconvolution (with zero-padding) . Fast edge and blur filters through crossed 1-D operators using Gaussian kernels. . High-accuracy B-spline interpolation of scaled images (using Michael Unser's theory, see below) . Simple 4-8 connected morhpology (max,min, TopHat). . Spectral estimation with full complex FFT and choice of window functions (Hamming/Sigmoid) . Generation of Fourier estimated inverse FIR Wiener filters from a-priori FIR blur kernels. . Fourier-based deconvolution directly in the Fourier domain using Fourier-based transfer- functions, or directly from FIR-filters. . FIR filtering with kernels from files with/without an adaptive variance dependent application mode . Automatic histogram stretching to U8 (unsigned 8-bit images), min-max, 0-255, or Gauss(stdv). . Recursive segment renumbering (recursive clump and sieve operation. Works for small images) . Calculation of band-averages over segments, "mosaicing" (average mean, stdv, or area). . False color coding from grayscale images. . Adaptive unsharp masking with threshold based on global histogram variance. . Principal component (PC) analysis. Used e.g. for filtering images (see pc-filtf.cc) . Harris corner detection . Loy/Zelinsky and Reisfeld symmetry operators . Distance Transform and Skeleton . Watershedding segmentation with 2 different strategies for removal of watersheds. . Image enhancement in the PC-domain . Simple optical flow algorithm . Fast local orientation in the spatial domain (see edgori.cc) . Supports processing of large images through striped I/O with user defined overlap and strip size. All pixel wise operations fully compatible for either entire images or strips. . Fast and intuitive pixel-access thorugh special operators (safe or unsafe). . User defined internal representation of images (unsigned 8 bit [U8], unsigned 16 bit [U16], signed 16 bit [S16], and 32 bit float [F32]). . Supports N-band images useful for multispectral applications such as remotely sensed imagery. . Supports the following image formats: PGM (grayscale, U8 bit) , PPM (rgb, U8-bits), BIL/GISIMAGE/ARC-INFO (U8, S16,U16,F32 + hdr file). Programs to convert from bil to PPM/PGM . Many operations such as filters use overloaded operators for intuitive use. ______________________________ Installation: ------------------------------ Modus Operandi: 1. Download and unpack Download imlib-src.tar.gz to a directory, and unpack it using winzip (> 6.0) or tar-gzip. Make sure that the following directories are created: imlib <- Project files for win32 imlib library newmat <- Project files for win32 newmat10 library imlib-src <- Source code for library (baselib.a) imlib-src/Applications <- Application source code imlib-src/applications/win32 <- Project files for win32 applications newmat10-src <- newmat10 source files if you download the documentation files, the following directories should be created: newmat-doc <- Documentation for matrix library imlib-doc <- Documentation imlib-doc/doxygen <- Doxygen files Make sure they are created on the same directory level! _____________________________ 2. Compile and install newmat ----------------------------- --------------- 2.1 Linux/Unix --------------- In order to compile the library, you need to get the source code for the matrix C++ newmat library by Robert Davies. There's a version here, but make sure to check for FAQ:s and changes here: http://webnz.co.nz/robert Edit the make.top file and set directory paths to fit your configuration. Then write make config This simply copies the files "make.common" and "make.top" into the directories imlib-src and imlib-src/Applications. If you have unpacked the newmat library and indicated its path, this will be compiled too. Then make all This will do three things: - compile and install the newmat library - compile and install the imlib-library and applications - make project files for visual C++ If you want to use Microsoft VisualStudio, project files/workspaces are automatically created under imlib-src/Applications/win32. If you don't want this, just comment out the relevant line in the top-level makefile (under make all). make doc If you have doxygen installed (see below), this will install html docs and man pages in imlib-doc/doxygen/html. If you type make clean the baselibs.a and obj-files and the doxygen documentation files are deleted. make distclean will remove the executable files and libraries from their target directory make test will execute some of the appliction scripts in Application directory. ------------ 3.2 win32 ------------ If you have visual studio installed, douvle click on the "makeall.dsw" workspace file. Then set the current configuration to "allfiles/Release" and compile. By default all files land in "c:/bin". Please create this directory if you don't have it. You will have to set the include/library directories under "options" accordingly. Please note that the win32 files may behave strangely, you can expect "fault" pages for some applications. I'm not a windows programmer, so I welcome any help in common problems in "unix->win32" ports. ___________________ 4. General comments ------------------- The makefile (gnu make) is adapted for gcc and egcs under Linux RedHat (5.1,5.2,6.0), you have to adapt it to your local configuration. The makefile has been divided into a configuration part - "make.top" - and a "generic" part - "make.common", "Makefile" and "Application/Makefile". Please modify the paths in "make.top" accordingly. The files make.common and make top are copied into the relevant directories. I have found that using the compilation optimisation flags -O speeds up the applications by a factor of at least 2. However, early gcc compilers have problems with this flag, so I recommend you compile without -O flags first. NOTE 2004-01-7: ______________ Image formats: -------------- I don't guarantee that The BIL format implemented here is compatible with software such as ArcInfo or other GIS packages. If you have problems, please let me know. The BIL image (file.bil) format requires a header (file.hdr) file with the following syntax (an example): NROWS 512 NCOLS 256 NBITS 8 NBANDS 5 SIGNBIT UNSIGNED BIL is Bits Interleaved by Line, meaning that pixels come in the following order: 1111.... (line 1, band 1) 2222.... (line 1, band 2) 3333.... (line 1, band 3) 4444.... (line 1, band 4) 1111.... (line 2, band 1) 2222.... (line 2, band 2) . . . etc A format of mainly historical interest is BSQ, where an entire image is stored separately. A pixel storage order commonly used is BIP, Bits Interleaved by Pixel: 123412341234 (pixel 1 band 1, pixel 1 band 2, pixel 1 band3, ...pixel 2 band 1, pixel 2 band 2..) This is used in the BMP image format, common on PC:s (This format has a header with information on look up tables). Imlib actually uses BIP storage internally, see mage.h . ____________________________ Example scripts ---------------------------- There is an example unix (csh) script and data on the use of the region growing algorithm. - seg (top level script that performs region growing in three steps) - parvec# (#=0,1,2 are parameter settings that you will want to play with) used by the program segmerge (see Applications/segmerge.cpp) - spotim.ppm (a small spot-4 image using the bands R-G-B= 4-3-1). There are other applications expressed scripts such as: - deblur (extract the text on a blurred image. A real example!) - auto_destripe (Use pattern recognition based on radial symmetry to auto-detect and remove stripes). - sharpen (Fourier-based Wiener filtering of the spotim.ppm image) These scripts are also available as windows bat files (no warranty that they will work for all versions of dos). ______________________ Compilation issues: ---------------------- The libraries have been compiled under linux with gnu/g++ (Sun/Solaris) and Linux (RedHat 7.3 ) with gcc 2.96, gcc3 3.1 and with Microsoft Visual C++. Makefiles for gcc and and project files for visual studio are included. There is a script "makewin32" that automagically generates project files in the output directory ./win32. Please note that they assume that the directory "c:\bin" exists; if it doesn't, create it! Beware of the gcc 3.3.x compiler series: The machine code generated from conditional expressions (such as a = (a < 0 ? 1 : -1)) may not work at all! I problems with the 3.3.1 under SUSE 9.0 and had to download 3.3.2 to make it work. ______________________ Running the programs: ---------------------- All executables programs are found under the Application directory and are intended to be used as a command line tool box. Generally most programs seem to work under windows NT (4) and windows2000, and win98. Please don't forget to compile the programs using a large enough stack frame. Most programs run well under Linux and Sun environment. There may still be problems with the strip-wise I/O, if you get problems with core dumps, try and change the windowsize or the stripheight, this usually helps. ______________________ Where to find it ---------------------- Comments/compliments/insults should be adressed to: soren.molander@bredband.net URL with the latest relase: http://hem.bredband.net/sormol/imlib _______________________________ Other packages and related code ------------------------------- As of 2003 there are a number of image processing/analysis frameworks available for a number of platforms. Several of these are based on "generic programming" techniques, using the Standard Template Library (STL) and/or various techniques for generic programming such expression templates. These have much more ambitious goals than my little packages, and you might want to look at these first. One of these is the VIGRA framework mainly implemented by Ullrich Köthe and is available at http://kogs-www.informatik.uni-hamburg.de/~koethe/vigra/ Todd Verhuizen has written a series of papers on the generic programming paradigm well worth reading, and he is also the main contributor to the matrix package "Blitz++". http://osl.iu.edu/~tveldhui/ Although these frameworks are very nice, some compilers (such as VC++ from Microsoft) do not handle templates sufficently well to handle some of the generic programming frameworks, so check it out first. The openCV was written by a group of russian computer scientists and contain a wealth of algorithms such as a face detection, etc. Some of these require the IPP processing libraries to be compiled, but the source code is freely available. http://sourceforge.net/projects/opencvucl/ The open source remote sensing effort at http://www.remotesensing.org tries to promote the spread of software for developers and users. Here you will find a wealth of code, from mapping/GIS to image processing software. For a collection of useful raster based algorithms, the KUIM system has source code at: http://www.cim.mcgill.ca/~sbouix/kuim/ An excellcent source documentation system, doxygen, by Dimitri van Heesch: http://www.stack.nl/~dimitri/doxygen/index.html For nice depenency graph generation, gviz from AT&T (for optional use by doxygen) http://www.research.att.com/sw/tools/graphviz/ On Philippe Thévenaz home page there is a lot of useful information on interpolation http://bigwww.epfl.ch/thevenaz/index.html A simple but efficient mpeg1 encoder can be found on www.rpmfind.net (mpeg_encode) ------------------------ New relases: 8-May-1999. Bug fixes and an improved algorithm for removal of watersheds. 22-May-1999. Fixed (obvious) bug in bil2ppm, now works in strip-mode. 12-June-1999. Cleaned up the html-documentation. 17-June-1999. Should now be ansi compliant. 24-June-1999. Changed char* to string, more stable and C++ like. 18-July-1999. Fixed the "dirty unix" trick in the HeaderOffsetFromFIle method, now uses ftell(FILE* fp) to calculate file size. 26-July-1999. Fixed bug in BIL format file access which, which gave wrong result or core dumps when reading image band-wise. Added new applications iminfo, bandext, and ppm2bil. 02-Aug-1999. Slightly different implementation of grad, should now work for larger images. 7-Sept-1999. New matrix library version newmat10, now compatible with egcs. Various bugfixes in imlib-src. 21-sept-1999. The blob renumber (GIS clump) procedure should now work properly. 24-sept-1999. Fixed dem2vrml application, it now outputs data in acceptable viewpoints. 13-Oct-1999. Renamed define statements in h files, and added conditional includes to reduce compilation times. 3-Nov-1999. Found bug in basic.h that caused MeterProgress to crash. 3-Mar-2000. Cleaned up class libraries, put implementations in .cc files where they should be. 6-May-2000. Fixed bug in wiener_spot application 14-June-2000. Compensated for complex exponential shift for real FIR filters, which caused a shift in the output result. Also added a Hammin window option for wiener filtering, to get away from ringing effects. 27-June-2000: Added new applications: gaussian histogram equalization ("histo"), local orientation superposed on edge images (after non-maximal surpression) "edgori", zero-crossings "zeroc", simple line-based deinterlacing "deinterlace". Added new class "histogram" for more general histogram operations. Added the possibility to skip ranges in calculating the histogram. 12-July-2000: Cleaned up the comments, now should be compatible with document generating tools such as doxygen. 7-Aug-2000 : Added new applications: gabor.cc - Gabor filtering in the spatial domain contrast.cc - exponential band pass filter that simulates ganglion c ell response in the eye. corr.cc - Crosscorrelation of images tophat - morphgological 8-neighbour Tophat edge detection = Min(Im) - Im thresh - iterative (optimal) thresholding 30-Sept-2000: Martin Weber helped me to port and test the code so now it should at least be compilable under win32 Os:es. However, expect I/O and memory allocations problems... 17-Nov-2000: Found and fixed a serious memory leak due to a faulty copy-constructor. 19-Nov-2000: Removed the segment script, the segmentation parameters in "segmerge" are now parsed directly. 3-Dec-2000: Cleaned up the source code, replaced Point2D and Point3D classes with PixCoord and a template class Pixel. 15-Dec-2000: Minor clean-ups. 19-Dec-2000: Put mathematical functions and constants in a separate namespace. Bessel functions (courtesy C.A. Bertulani) and other mathematical functions defined in mathutils.h. Discrete Gaussian kernel defined, used in Grad for improved edge detection. 28-Dec-2000: Fixed bug that caused wrap-around errors in histo and histeq. Added option to use real spectrum-based wiener filter estimates. 3-Jan-2001: Generated a doxygen parameter file. If processed with doxygen, the output documentation is put in imlib-doc/doxygen. The "grad" program now accepts a threshold parameter. 16-Jan-2001: Added logos to doxygen documentation and patched make file. The html/man documentation is now generated with "make doc", and removed with "make clean". 20-Feb-2001: Added project files for win32 applications, and a top-level make file. 6-Mar-2001: Added Canny edge detection. 16-Mar-2001: Fixed bug in bilinear interpolation. 21-Mar-2001: Added Fourier-based cross correlation (matched filtering). See "corrx.cpp". 22-Mar-2001: Added Fourier-based filtering, "fftfilter.cpp". See also "firfilter.cpp". 02-Apr-2001: Fixed bug in iminfo, now strip-wise averages give correct results. 04-Apr-2001: Added "scale" application to up-down sample images. Modified Pyramid class accordingly. 09-Apr-2001: Added "extrema.cpp" that finds the extremvalues of an image, using watershedding. Fixed bug in histo.cpp. 10-May-2001: Added an experimental point-based fourier filtering function "fouriermask.cpp". This allows for removal of discrete frequencies (e.g. striping) in the Fourier plane. 12-June-2001: Fixed bug in crop-function in image.cpp 7-July-2001 : Added "morfmask.h/cpp" for iterative morphological operations such as thinning and 8->4 connectivity conversion. 17-Aug-2001 : Fixed bug in Max/Min operators, added bounding box operator in segmentation.cpp. 25-Sep-2001 : On some win32 platforms the stripwise I/O crashes, so I've added options for some applications that enables either stripwise or normal mode. 02-Oct-2001: Now conbined newmat and imlib in same project for both win32 and unix distributions. 16-Oct-2001: Fixed a silly error in method CalcStat() in image class. Now SetSkipValues should work. 19-Oct-2001: Added extra options to histo. Added bandpass filtering option to corrx. 7-Nov-2001: Added random number generation and made time functions inline to avoid link errors. 27-Nov-2001: Programs sucessfully tested with the Intel icc 5.0 compiler. Fixed a few lexical bugs. 7-Dec-2001: Fixed bug in iminfo that reported different image statistics for strip-wise and ordinary I/O. 18-Dec-2001: Speeded up the min/max operations in segmentation. 19-Dec-2001: Added im2txt which writes an entire image into an ascii file, and pixinspect an interactive application to inspect pixel values. Tried to fix bug in filestrip, not sure if successful. 29-Jan-2002: tweaked filestrip again, should work better now... 02-Feb-2002: Added Philippe Thévenaz implementation of B-spline interpolation (spline.cpp/h), and integrated it in the pyramid class (splineInterpolation). This is available through scale.cpp (replace binomial interpolation with splines). The implementation is based a series of papers by Michael Unser et al (recommened reading!). Also added new application resmerge.cpp, that sharpens a low resolution image with a high resolution one. It is assumed that the images cover the same extent. 20-Mar-2002: Fixed "unix2dos" conversion when creating project files for win32. Added N-order Fourier-based Butterworth filter and spatial Laplace filter. 25-Mar-2002: Added example of real linear movement deblurring (sony camera). Fixed a bug in filestrip.cpp for pnm-read. 8-Apr-2002: Added Fourier-based bandpass/lowpass/bandstop filtering (gaussbp.cpp) and adaptive median filtering (morf.cpp). 9-Aug-2002: Added radial symmetry operator "radialsym.cpp". Also added conditional convolution parameter, to avoid excessive filtering on zero values. See "radialsym.cpp" for example. 17-Sept-2002: Added "graceful" reporting when opening non-existent files. Now you can check if file exists in mail applications. 22-Sept-2002: Added color class for RGB <-> HSV conversion and false color coding. "opticalflow" and "locori" now produce color coded outputs. 03-Oct-2002: "edgori.cpp" now produces correct edge-orientation [0..Pi] as a bw or false-color image (red = 255, blue = 0) 29-Oct-2002: Normalized correlation introduced in "corrxspat.cpp" and "kernel.cpp". Compare results with that of "corrx" which does normal (stationary) correlation in the Fourier domain. 16-Nov-2002: Added Euclidian Distance Transform and Skeletonisation (adapted from KUIM). 27-Nov-2002: Added Gaussian blur (blur.cpp) 02-Dec-2002: Changed interface to extrema.txt: now produce a list maximum minima/maxima. Also allow the point location to be expressed in local fourier coordinates. Added an example script "auto_destripe" for automatic fourier-based removal of stripes. 09-Dec-2002: Added application "setsize", which resamples image to a desired size (cf. scale.cpp). 29-Jan-2003: Added new options to some applications :-). For example, now you can use direction in grad.cpp 3-Feb-2003 : Fixed crash-bug due to def. of sqrt in Mathutil. Now use standard def. Upgraded to newmat11 and removed -no-deprecated flag. 25-Feb-2003: Fixed bug in relaxation labeling. Added test program "relaxtest" in applications. 27-Feb-2003: Added energy.cpp, which uses a quadrature filter pair to derive local energy and phase. Added N:th order derivatives in kernel.h, which uses recursive procedure in mathutil.cpp. Removed canny edge detector (inferior quality). 29-Apr-2003: Added Harris corner detector 27-May-2003: Added test pattern generator (testpat.cpp), and generalized symmetry (Reisfeld). Minor bugfixes in allplications. 19-June-2003: Now the entire code resides under the namespace "Imlib", so if you have code that uses the source you have to use "Imlib::". 19-Aug-2003: Fixed bug in minmax normalization in histogram.cpp. Now "histo.cpp" does both Gaussian and min-max normalisation. 22-Aug-2003: Added "imhist.cpp" application that write an image histogram to a file. 9-Sept-2003: Added a new criterion for merging regions based on making areas as round as possible 7-Feb-2004 : Added cepstrum application that generates Ifft(Log(Abs(fft(f(x,y))) + 1)); 5-March-2004: Added Lucy-Richardson and successive iteration deconvolution (deconv.cpp); 16-March-2004: Added choice of local/global variance estimate and soft/hard threshold in wavelet coeffs. 17-March-2004: Added choice of actual regularization of solution, works for noise-free images. 21-March-2004: Added decomposition of 2D kernels to 1D kernels using SVD (still experimental) 22-March-2004: Now works, see firfilter.cpp :-). Also changed Kernel representation from heap to STL vector allocation 27-March-2004: Fixed wrap-arund errors in a trous wavelet reconstruction 15-April-2004: Both up and down sampling is done by genereralized spline interpolation. See spline.cpp, pyramid.cpp, and scale.cpp 21-April-2004: Added greyscale dependent wavelet pruning in deconv/pyramid.cpp (to retain fine details). 28-April-2004: Reverted to standard splines for downsampling. New version of Harris operator 12-May-2004: Added an extra parameter in deconv.cpp to control the number of pyramid levels in the wavelet reconstruction. Now produces really nice results in noise images, especially astronomical images. 19-Jan-2005: Fixed mysterious hangup bug in segmerge due (probably) to definition of log in mathutil. Added function approximation of cumulative gaussian approx in mathutil. 10-Feb-2005: Added im2ker function that converts an image to a kernel (text file). Also added new writemask kernel functions: exponentials and Airy function. The Airy function = ( 2*J(1,r/r0)/(r/r0) )^2 is the theoretical point spread function for a perfect thin lens in the Fraunhofer limit (far field). 12-Feb-2005: Added Gamma-Map specklefilter 26-Apr-2005: Added Student-T test specklefilter, better preservation of edges and texture. 07-May-2005: Added random number generator with period 2^14 (see mathutil.cpp). Credits in file. 28-Dec-2005: Changed member variables "variable" to "this->variable" to conform to new C++ standards. Makes the code ugly, yuc. Also have problems with the new gcc versions, you will probably get link errors in "segmerge" and "delin". Looking into that.... 1-Jan-2014: Added adaptive histogram equalization, adapthisto.cpp. It features: - Enchancement of low and highpass components respectively. - Standard global dynamics range adjustment using mean and stdv (see histo.cpp) - Local block-based linear mean + stdv adjustment, with bilinear interpolation to reduce blockiness. - Global gamma adjustment Last changed: 1-Jan-2014