IMPROV - Help File


1. IMPROV - Image Processing for Robot Vision

IMPROV is a simple tool to test image processing functions.  Images
are taken from the Vision VV6300 CMOS colour camera or the QUICKCAM
(using the -q option on the command-line). Operations may be
concatenated, so even a more complex task can also be tested.  The
captured camera image is shown in the image window #1.

2. Selecting and adding image processing operations

The dropchoice on top of each image allows for the selection of an
image processing operation to be performed on the previous image and
displayed in the current image window.  The chosen operation is
displayed in a browser control below the image window. Multiple
operations can be successively applied by concatenating them pushing
the '+' button to the left of the browser.  As long as the operation
is not appended to the existing list of operations it may be replaced
by some other selection from the dropchoice.  Some operations take
arguments like the threshold function. Up to three paramters can be
set using the slider controls labeld p1, p2 and p3.  Paramter values
lie in the range [0.0..1.0]. A 0.5 value for the threshold functions
means an actual greyscale threshold of 8 (4bpp = 16 different grey
values).


3. Modifying and deleting image processing operations

Changes of the parameter slider controls are effective for the most
recent selected image processing operation. Parameters can be changed
afterwards by first selecting them in the corresponding browser and
then adjusting the parameter slider. A selected operation gets
highlighted the '+' push button changes into a '-' push
button. Pressing it will remove the operation from the list.

4. The image processing operations

Here is a brief summary of the image processing operations available
in IMPROV.

NOP		No Operation
Identity  	Copy source image to target image
Negation	Negate source image (p`=maxcol-p)
Dither(2x2)	Target image contains only black/white pixels
Difference	Difference image of source and previous source
Count		Count pixels of a given (P1) grey value. Result is shown
		in text window.
Threshold	Binarize image. Threshold is given by P1

Minimum	3x3 Minimum Filter
Maximum	3x3 Maximum Filter
Mean   		3x3 Mean Filter
Median	   	3x3 Median Filter
Laplace   	3x3 Laplace Filter
Sobel		3x3 Sobel Filter (absolute gradient value)
Corner		3x3 Corner Filter

Erosion	    	3x3 Erosion
Dilation    	3x3 Dilation
Open	  	3x3 Erosion and then Dilation
Close		3x3 Dilation and the Erosion
Fill
Connected
Boundary
Skeleton

Noise		Generate Noise in target image (P1=degree of noise)
Grey stretch	Make use of all grey values
Grey reduce
Show (x,y)	Print grey value of pixel at (x=P1,y=P2)
Overlay		Copy all pixels of the original where source image pixels
		are black
Region (t)	Segementation (t=P1 as threshold)
Find Circles	Find small circles in source images



5. Links

IMPROV - Image Processing for Robot Vision
http://www.ee.uwa.edu.au/~braunl/improv/
http://www.ee.uwa.edu.au/~braunl/improv/ftp/

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

A note about adding menus and IP functions to the source of IMPROV.

You need to change the source in the following places:

  1. Choose an enumerated type and add it to E_IPLOP in xfqcam.h
  2. Code the function and add it to improc.c and the function prototype to improc.h
  3. Add a "wrapper" call to the function via the switch in the ProcessImage function in xdemo.c
  4. Add the menu information (name, enum and args) to the menParamInfo[] array in xfqcam.c

How the menus are created and the display updated

  Basically menus are constructed from the menParamInfo[] array of
MenuItemDetails structures in xfqcam.c. Each entry in the array
contains the name (as it appears in the menu and browser underneath
the images), the enumerated value (from xfqcam.h) and the number of
arguments.

  Menu popup headings are marked with the number of args
"-1". Underneath each heading in the array are the functions to appear
in that popup. Beware of the order -- the order listed is the
appearance order. Have a look at the source. It is rather self
explanatory.

  A linked list by the enumerated value of each heading is created at
runtime to generate and update the browser info. This allows for
function names such as Show(x,y) to be printed with the actual
parameters being passed, such as Show(0.5,0.38).

Compiling

  You may need to tweak some of the includes to get ximprov to
compile. In particular you may need to check the location of forms.h
on your system. Also, the _QCConfig.quickcam_port variable in qcam.c
will need to be set to the correct parallel port address.

  You will need to have the xforms library 0.88 or later.


************ Added 19 February 1999 ***************

Notes, Bugs and Todo - Jesse Pepper <peppe-jj@ee.uwa.edu.au>

Support for the Vision VV6300 CMOS colour camera has been added to
improv. There have however been a number of bugs created by this which
have not yet been ironed out. Here are a list of the known bugs, add
one if you find it, but make sure you describe it clearly so it can be
reproduced.

* Initialisation takes too long, because the camera doesn't initialise
on the first try, so you have to initialise it again.

* Histogram isn't working??

* Autobrightness causes seg fault

* Program seg faults when you try to change the brightness, white
balance and contrast sliders

* Image is now not being filtered through the others, unless it is a
general filter (NOP, NEGATIVE etc.)

* Image is sligtly corrupted, misses pixels in places
* Processing is too slow, should be able to speed it up
* I have begun a solution to fix the above 2 problems, writing a
  kernel level device driver, so when grabbing a frame my process won't
  get interrupted. It is nearly working.

* Says 4bpp when it's actually 24 (top left)
-------------------------------------------------------------------------
Adding support for more cameras
===============================

The following steps are required to implement support for an
additional camera driver to Improv.

 - Make a new set of files (.cxx and .h) which implements a subclass of
   the Camera virtual class.
 - Edit Camera.cxx, add reference to a class instance to the cameras
   table.  Make sure 'fakecamera' and 'NULL' is in the table.
 - test and debug... :-)

-------------------------------------------------------------------------
peter vanopulos
11 January 2000

Added to the Improv Image Processing Simulator...

The filters sub menu and its options. 
The file filter.c contains all the source code for the filters.
It too is doumented and follows previous struictures and 
definitions from the improc.h file.


FAQ
___

-How do I add a filter?

Simply add a case name in the .c file
Add the filter function in the .c file
Add the filter function prototype in the .h file
Add the call to the function from a menu by adding to the filter
  option in the .c file. Keep with the convention and stick with
  lower case since it looks good and is easy to read after someone 
  else wants to add something aswell.

improc.h improc.c
 - function prototype and implementation
ImprovWrapper.h
 - enum value
ProcImage.cxx
 - menu entry
 - function call


- Then what ?

Compile it by typing make.


- Then what because the linker complains about the *.o files not linking?

There is a problem with the C++ compiler installed in /usr/local/.
Use the one in /usr/ instead.

  make CXX=/usr/bin/g++


************ Added 20 September 2000 ***************
by Uli Mezger

Improv underwent some major reconstructions:

1) New internal image format:

typedef struct {
    int width, height;          /* size of image */
    int xoffset;                /* number of pixels offset in X direction */
    pixel_format format;        /* XYBitmap, XYPixmap, ZPixmap */
    int datasize;               /* Size of the mem block pointed to by data */
    unsigned char *data;        /* pointer to image data */
    int bytes_per_line;         /* accelarator to next line */
    int bytes_per_pixel;        /* bytes per pixel */
    int obformat;               /* format of the obdata */
    void *obdata;               /* hook for the object routines to hang on */
    int flags;                  /* PIC_READONLY */
} Picture;          

typedef enum {
  pix_unknown = 0,

  pix_bitmap,/* 1 bit per pixel, order 76543210 | 76543210 | ... */

  pix_grey4, /* 4 lowest bit in 8 bit byte */
  pix_grey,  /* 8 bit luminosity */

  pix_index, /* 8 bit indexed colors.  Use obdata to store the color table */

  pix_rggb,  /* 32 bit Eyecam native format */

  pix_rgb24, /* RGB 24 bit (8:8:8) */
  pix_rgb32, /* RGB 32 bit (8:8:8:8) Last byte is not used */
  pix_bgr24, /* BGR 24 bit (8:8:8) */
  pix_bgr32, /* BGR 32 bit (8:8:8:8) Last byte is not used */

  pix_hsv32, /* HSV 32 bit (8:8:8:8) LAst byte is not used */

  /* XXX These must be verified and consistently defined against V4L, V4L2 */
  pix_yuyv,  /* YUV 16 bit (4:2:2 packed) */
  pix_yuv12, /* YUV 12 bit (4:2:0 planar) */
  pix_yuv9   /* YUV  9 bit (4:1:0 planar) */
} pixel_format;

So the applications do not have to rely on the global parameters in
'ipl_config', which might be not always correct.  (e.g. the image
format changes during processing).


2) Image format can be changed during processing, e.g. input picture is
grey scale, output picture can be color and/or different image size.

3) User can choose between different input image sequences or the
camera in the Camera menu. But will crash if some of the advanced
image routines do not take care if the input image has been changed or
not during run time. So it is advised to turn off this critical
functions (like the optical flow routines) in order to load a new
image sequence.

4) Graphic library has been added (improv/FWlibrary) to do all the
basic image manipulation (resize image, crop image etc.) and drawing
functions (circles, line, filled polygons etc.)

5) Improv can be started into 6, 4 or 2-processing window mode via
command line (e.g. improv 2)

6)New V4L interface: all cameras supported by the CPiA webcam driver
can be used. For a detailed list of cameras have a look at:
http://webcam.sourceforge.net/

Note: This also includes USB cameras, (if your kernel supports USB!)

7) And of course, some new and very interesting image processing
function (e.g Optical flow routines, Contour finding, Moravec interest
operator, Tracking ...) have been added. Adding your own functions to
'improc.c' has not changed, except the user has more control of the
incoming and outgoing images. (Very handy!)

There are basically two ways to include functions, create a library
(e.g. /contour/libContour.a) or just include your c-functions
(e.g. #include"moravec.c")!

8) The camera image can be included, wherever it is needed (for
comparisons of different operations)

