Top Level Readme File for the ipp Package
DESCRIPTION
This directory contains ipp, an image processing package developed
by Randal Nelson at the University of Rochester.
It is not, and was not designed to be a complete collection of
low-level operators, though it contains a number of such operators.
The principle contents are some higher level grouping routines for
finding line segments and curve fragments, groups thereof and derivative
features, which we have used in object recognition programs.
The basic representation for images used in this package is an in-core
format defined in utility.h
This choice works well for robot vision applications where most images
are 1K by 1K or less, given current workstation memories and speeds.
It is not intended for use with very large images, such as those
encountered in some aerial photo-interpretation tasks.
The in-core format is quite basic, and not tied to any particular file format.
To use images from various file formats, and input and output
routines are required to load and store the images.
Routines for loading and storing images in iff (Rochester) and clv (Maryland)
formats are included with the package (input_iff_image, output_iff_image,
input_cvl_image, output_cvl_image).
For other formats, the user must write corresponding routines.
-----------------------------------------------------------------------------
MAKING THE SYSTEM
The system is compiled by typing "make" in this directory.
(Technically, "make install" is used the first time, but at the moment
there is no difference).
Typing "make clean" removes all object and executable modules, all
libraries, (and also cleans up emacs detritus).
Typing "make" or "make clean" in a subdirectory updates the system
to changes in that subdirectory.
One caveat. None of the makefiles checks cross-directory dependecies,
so if you change a library function, you have to explicitly recompile
executables depending on it.
If you change a low-level include file, the best bet is probably to
do a clean make of the whole system.
The system contains hooks for doing graphical and mouse IO.
These routines are in the library libgraphics.a.
The makefile contains a structure for easily substituting different
versions of this library. The default make uses a set of dummy routines.
There is also a set of XWindows routines using the X11 library.
The source code for these is in the directories
src/graphics/lib/dummy_graphics and src/graphics/lib/xgraphics respectively.
If you think the appropriate X context is available on your
system, edit the make include file src/graphics/display.mk and make the
necessary adjustments as directed there - you will need to specify locations
of include files and system libraries for instance.
If you want to hook in another display environment, then you will
need to write routines fleshing out the dummies in
src/graphics/lib/dummy_graphics, and analogously adapt display.mk.
Note that the include file graphics.h is also variant.
The make process loads libraries into the lib directory, .h files
into the include directory, and a few executables, including the
top-level programs find_segments and find_chains into the bin
directory. If you actually make use of the code, you will probably
want to use the library routines, and embed them in your own code,
but the executables serve for demos, and the source code provides
an example of how to use the routines.
To test the system, try running find_segments, an executable that
should show up in the bin directory, on the iff image pics/square.iff,
using the command "find_segments square.iff test.seg"
The segments found should be written to test.seg, and there should
be 8 of them.
A few progress messages should be printed, as the program runs, along with
ones indicating calls to the dummy graphics routines which are
the default graphical interface.
The other test images in pics, group.iff, tinytown.iff, and tree.iff
represent progressively more complex and less polyhedral scenes.
Once you get the local graphical interface up, watching the performance
of the segment finder on these images should give you a pretty
good idea of its behavior.
(Fairly good on the polyhedral objects, messy on the natural scenes.)
******************************************************************************
The directory is organized as follows.
This is an overview. More detailed information is contained in Readme
files in various subdirectories.
------------------------------------------------------------------------------
bin:
Contains executables for selected higher level routines, e.g.
the line segment finding program.
Various other (lower level) executables are generated by the system make
command. By default, the remain with the source code, but the user could
modify the make files to copy these to bin if particular ones were
desired.
Important executables include
*************
NAME
find_curves
SYNOPSIS
find_curves infile [outfile] (interactive mode)\n");
or: find_curves -n infile [outfile] (no display mode)\n");
or: find_curves -f file_of_input_and_output_filenames\n");
DESCRIPTION
Takes and input image (in iff format) finds boundary curves, and
(optionally) writes the set found out to a file.
The first version displays the curves as they are found.
Alternatively, may take a set of input files and process them all,
saving on recomputing the mask set.
*************
NAME
find_ms_curves
SYNOPSIS
find_ms_curves infile [outfile] (interactive mode)\n");
or: find_ms_curves -n infile [outfile] (no display mode)\n");
or: find_ms_curves -f file_of_input_and_output_filenames\n");
DESCRIPTION
Takes and input image (in iff format) finds boundary curves
at multiple resolutions, and
(optionally) writes the set found out to a file.
The first version displays the curves as they are found.
Alternatively, takes a set of input files and process them all,
saving on recomputing the mask set.
Like find_curves, only the processing is run at successively lower
resolution, dropping by a factor of sqrt(2) at each stage until
the image is too small to bother reducing further.
An attempt is made to check curves found at each resolution against
curves already found to avoid duplication.
*************
NAME
find_segments
SYNOPSIS
find_segments [-n] image_file [output_segment_file]
DESCRIPTION
Find line segments in an image. image_file is the input, assumed
to be in iff format in the defualt version. The -n option specifies
no display or user interaction.
It is used when the program is called repeatedly (as in a shell script)
without interaction.
The segments found are (optionally) written to output_segment_file.
In the interactive mode, the user is queried for another
input image. This avoids having to reload certain tables used to drive
the stick-growing process, which is a time-consuming operation.
Source in src/feature/bin
*************
NAME
find_chains
SYNOPSIS
find_chains segment_file [output_chain_file]
DESCRIPTION
Find connected groups of three line segments in the set passed in.
These are written out to output_chain_file.
Linking is based on proximity of endpoints and contrast consistency.
A segment may appear in more than one group.
The algorithm is designed to find perceptual groups that are
likely to form part of a common object boundary.
Source in src/feature/bin
*************
NAME
draw_segments
SYNOPSIS
draw_segments segment_filw [output_image_file]
DESCRIPTION
draws a segment set on display device, optionally generates an image
with the segments appearing black (0) on a white (255) background.
Source in src/feature/bin
*************
NAME
xshow
SYNOPSIS
xshow image_file
DESCRIPTIOM
Uses X11 calls to display iff image on properly configured system
Only handles gray scale images. Attempts to dither if it thinks it has a
binary monitor, but does not use the world's best dithering algorithm.
Source in src/graphics/bin
------------------------------------------------------------------------------
lib:
Contains a set of libraries containing callable routines for
all processes defined. All the executables in bin have corresponding
routines in some library in lib, but many other routines are also there.
Current libraries supplied are listed below.
The functional dependencies in the libraries form a directed,
acyclic graph. The order given below is one valid full ordering, i.e.,
this order would work when passed to the linker.
libfeature.a - Routines for higher-level feature extraction (line segments,
curve fragments, groups of line segments, etc.
libgraphics.a - Routines for doing graphical and mouse IO on an
xwindows system. Needs X11 library. There are real and dummy versions
of this library. The system initially compiles with the dummy
routines. If you think the appropriate X context is available on your
system, edit the make include file src/graphics/display.mk and make the
necessary adjustments as directed there.
libimage.a - Various low-level image processing routines (histograming
convolution, edgel detection etc.)
libutility.a - Low-level routines for loading, storing, and translating
file images into core images.
libiff.a - Low-level io routines for the iff image file format. Probably
nothing here the general user would ever call.
libmisc.a - Grab bag of miscellaneous useful functions, e.g. angular
arithmetic, sorting.
Below is an attempt at showing the full dependency graph
Libraries depend explicitly on all those at a lower level to which
they are connected.
______________
| |
| libfeature.a |
|______________|
|
_____________|________________________
| | | | |
| __|____________ | | __|________
| | | | | | |
| | libgraphics.a | | | | libmisc.a |
| |_______________| | | |___________|
| | | |
| _______|__________|_________|_______
| | | | | | |
| | __|_____|___ | | | (if used)
| | | | | | |============|
| | | libimage.a | | | | libX11 |
| | |____________| | | |============|
| | | | |
| | ____________|______ | |
| | | | | |
| | | __|__|__|_____
|==========| | |
| lm | | libutility.a |
|==========| |______________|
|
|
|
_______|__
| |
| libiff.a |
|__________|
------------------------------------------------------------------------------
include:
Contains copies of include files needed to use the libraries,
generally with corresponding names. Originals are stored in src, to which
versions modifications should be made.
Generally to use the routines in a library, you need utility.h (since most
routines deal with images) the include file corresponding to that library,
and sometimes additional includes, if the particular function utilizes
other parameters. Specifics can be found by looking at the Readme file
with the library source code, or at the source code for the function.
Current include files are
bool.h - Definitions for Boolean types. If you need them.
misc.h - Definitions for angular arithmetic routines, sorting routines,
etc. contained in libmisc.a
cvl.h - Definitions for cvl file format. Generally not needed for any user
callable functions.
iff.h - Definitions for iff file format. Generally. not needed for any user
callable functions.
utility.h - Corresponds to libutility.a. Needed by any function that
uses an image parameter.
image_proc.h - Corresponds to libimage.a. Name is a historical acident.
Needed if you call functions in image library.
xgraphics.h - Corresponds to libxgraphics.a.
image_feature.h - Corresponds to libfeature.a. Basic defs for general
image feature type. Calling specific routines generally needs
include file for specific feature type as well. These are listed below
segment.h - Definitions for line segment routines.
curve.h - Definitions for with curve extraction routines.
chain_of_3.h - Definitions for with segment linking routines.
patch.h - Definitions for patch feature extraction routines
------------------------------------------------------------------------------
src:
Contains all the source code for the package, including both
libraries, executables, and include files.
The general naming sceme is to place all code for a particular library
in a directory called lib, which may contain subdirectories.
Generally there is also a corresponding bin containing code for
executables that use functions in the corresponding library.
All code is written in C, most of it with old-style declarations.
This can cause problems in linking with C++ programs. Can be fixed by
setting appropriate switches in compiler and linker.
------------------------------------------------------------------------------
pics:
Contains a couple of iff format images for checking out the package
prior to local adaptation.
------------------------------------------------------------------------------
Back to
boundaries page
Back to
Randal Nelson's home page