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