ftp://ftp.fct.unl.pt/pub/di/packages/UFF.README
****************************************
UFF
UNL FOURIER FEATURES FROM CURVE PATTERNS
****************************************
An implementation of a general purpose 2-D shape description method
Copyright (C) 1992, 1993, 1994 Thomas W. Rauber
Universidade Nova de Lisboa & UNINOVA - Center for Intelligent
Robotics
Quinta da Torre, 2825 Monte da Caparica, PORTUGAL
E-Mail: tr@uninova.pt
--------------/
/
/
/
/
/
/
/
/
|----------------------------------|
|
|
|
-------|
|
/------\
|
|
|
|
|
|
|
|
|
|
\------/
|
|
|
|
-------|
|
|
|
|
|----------------------------------|
Pattern 1
Pattern 2
INTRODUCTION
-----------UFF is a package which calculates continuous numerical descriptors
from 2-dimensional curve patterns. 2 example patterns are shown above.
The UNL FOURIER FEATURES (UFF) are invariant to TRANSLATIONS,
ROTATIONS
and SCALE CHANGES of the original pattern. This shape descriptor
is a general purpose method. To the best knowledge of the author it is
clearly superior to other general purpose 2-D form descriptors.
This is e.g. true for 1-D Fourier descriptors. A direct comparison
between
the UNL FOURIER FEATURES and 1-D Fourier descriptors is given:
1-D Fourier descriptors
|
UNL FOURIER FEATURES
-------------------------------------------------------Description of 2-D shapes
|
Description of 2-D shapes
Occlusion sensitive
|
Occlusion sensitive
In general closed curves
|
Curve can be open (e.g. Pattern 1)
No nesting allowed (holes)
|
Curves can be nested (e.g. Pattern
2)
No gaps allowed
Insensitive to symmetries
|
|
Gaps may occur
Sensitive to symmetries
The program comes together with a complete documentation and example
patterns. It is implemented in highly portable C code and easy to
install
An optional graphical interface to X-Windows is provided.
The input interface to the program are binary images which are stored
in the popular ".PBM" (pbmplus, netpbm packages) image file format.
INPUT: a binary pattern in a square image
OUTPUT: a multidimensional feature vector, containing a global
description
of the pattern
HOW TO OBTAIN UFF
---------------------The UFF software package can be obtained via anonymous, binary ftp.
Server:
ftp.fct.unl.pt (192.68.178.2)
Directory:
pub/di/packages
Software in C:
UFF<version>.tar.gz
Documentation in Postscript:
UFF.ps.gz
(ca. 40 pages technical report (tutorial like) )
>>>>>>>>>>>>>>>>>>>>
END OF FILE "README"
<<<<<<<<<<<<<<<<<<<<<
REFERENCE
--------The main references for the system are:
1.)
Two-Dimensional Shape Description, Technical report GR UNINOVA-RT-10-94,
UNINOVA, Monte de Caparica, Portugal, 1994.
which is a chapter of
2.)
Inductive Pattern Classification, -Methods-Features-Sensors-,
Thomas Walter Rauber
Ph.D. thesis, Universidade Nova de Lisboa, Faculdade de Cie^ncias e
Tecnologia,
Lisboa, Portugal, 1994.
COPYRIGHT
--------No guarantee, no warranty, for non-commercial use only, except with the
written permission of the author.
INSTALLATION
-----------Unix> gunzip UFF<version>.tar.gz
Unix> tar xf UFF<version>.tar
COMPILATION
----------Go to the "src" directory. If you do not have/want X-Windows, edit
the 'makefile' and put a comment character (#) before all the lines that
start with an 'X'.
Then type 'make' in UNIX.
Some machines need slight adjustments, see file "def.h"
The program compiles also on other operating systems (e.g. MS-Windows),
however without the X-Windows interface.
EXECUTION
--------The program can be called with or without command line options. If it
is
called without options it will automatically ask for the respective data
files.
The following command line options are available:
uff
[-h[elp]] [-v] [-t] [-xoff] [-N <Resolution>]
<Fraction>]
[-dir <data-directory>] [-uff <uff-file>]
[-fnam <feature-names-file>]
-h
prints the usage
-v
Verbosities (more information)
-t
Trace (wait after each image before continuing)
[-q
-xoff Do not use any graphical output
-N
the resolution of the system images;
must be a power of 2. Default value is 128
recommended values are 128, 256, 512
-q
Since only lower frequencies of the calculated Fourier
spectrum are discriminative, only the q-th part of all
frequencies are written to the output file. See the
documentation for more details of this parameter.
-dir
Use the name of the following directory as the data input
directory.
<data-directory> is the name of the directory where the
PBM-files are stored.
-uff
The file to which the output is written. The format of this
file is recognized by the TOOLDIAG program which should be
used together with UFF in order to examine the data.
(see below for more information)
-a
Write the output as text instead of binary data
-fnam
Description file of the features. A text file is
generated
which contains the name of each feature. The size of this
file
depends on -N and -q. For instance N=32 and q=8 produces
22 features. The first is UFF(0,1) and the last is UFF(-1,2).
Example:
uff -N 256 -q 8 -dir ../patterns/scissor -fnam test.nam -uff
../uff/test.uff -v
INTERFACE TO THE 'TOOLDIAG' PROGRAM
----------------------------------The data files and the feature name description file can be read by the
TOOLDIAG program. This additional tool permits you to analyze the
produced
results. For instance the error estimation facility of TOOLDIAG lets you
know
if the produced feature values are suited to be used for classification.
Furthermore the large dimension of the UFF-feature vector can be reduced
to
a reasonable size by means of feature selection techniques.
With the help of tooldiag, a supervised learning of an 2-D shape
recognition
system can be realized.
FILE FORMATS
------------
- FILE FORMAT OF THE BINARY IMAGE FILES
*************************************
UFF accepts the patterns in the PBM format (see additional
documentation).
Generate your binary curve pattern and save it to a PBM-file.
The resolution of the PBM-file can be higher or equal than the system
resolution (-N option), but it is assumed to be square.
Simply put all examples for one pattern class (the same pattern
translated,
rotated or in a different size) into a single directory.
Specify the name of this directory in the -dir option.
- FILE FORMAT OF THE GENERATED UFF FILE
*************************************
A file is generated (-uff option) which contains one line for each image.
Each line has the multidimensional UFF feature vector. The feature values
are binary floating point numbers.
The first line contains the name of the class
directory).
The second line contains the dimension of the
The third line contains the number of samples
of images in the directory.
The the data follows, or as binary data or as
(derived from the
feature vector.
that is equal to the number
text.
You do not have to know this format. TOOLDIAG can handle the data.
The -a option produces text output which is exchangeable among different
machines, but magnifies the size of the feature files considerably.
- FILE FORMAT OF THE FEATURE DESCRIPTION FILE
*******************************************
This file contains the names of the features. In the first line the
number of features must appear. This number must be equal to the number
of
features of the data file(s). Then in each line one feature name appears.
The
name must be a single connected string.
7
u0_v1
u1_v0
u1_v1
u2_v0
u2_v1
u-2_v1
u-1_v1
LIMITATIONS
----------Patterns must be binary, curve oriented. No texture-like patterns can be
processed. No occlusion of parts of the pattern may occur.