@chapsummary
 VXL is efficient, simple, and fun to use.
@endchapsummary

This document describes @vxl{x}, a collection of C++ libraries designed for
computer vision research.  Because it's for computer vision it needs to be
@emph{efficient}, handling large quantities of numerical data with little
overhead.  Because it's for research it must be @emph{portable}, so that
one can write and run one's program on any machine available, for example
in order to access a special camera or fast image processing hardware.

The @vxl{x} collection's portability and efficiency are traits which are due
in large part to its parentage.  The package was built by extracting the
core functionalities of two large systems: the ``Image Understanding
Environment'' (IUE) and ``Target junior'' (TargetJr).  Although these
environments contain a wealth of useful code, and have facilitated much
research, they are widely known for their bulk, and the difficulty of
learning to use them.  Common complaints have been
@itemize @bullet
@item
``Too heavy'': To use even one small routine, a large portion of the
environment must be included in the user's program, increasing program
size, compile time, and startup time.  Sometimes the increase is such that
debuggers and other tools fail to work.
@item
``Too slow'': In some cases, the design of the earlier systems restricted
the efficiency of code that could be written when using them.  This was in
some part due to deficiencies of the C++ compilers in use, but also due to
the use of since-superseded programming paradigms.
@item
``Too weird'': Because the IUE is a large system, intended to be used as a
programming environment, it imposes stylistic quirks on programmers who use
it.  The most apparent of these was the use of @LaTeX{} to generate code,
which offered many benefits, but was ultimately rejected by users.
@end itemize
Despite these complaints, the quality of the software available in the
environments, and the promise of a sustained, concerted software
development effort has meant that the IUE/TargetJr has many users
worldwide.  The job of @vxl{x} is to make that many @emph{happy} users, by
creating a set of libraries which have the same useful code, but which are
light, fast, and not weird.

@section Core Libraries

The core of @vxl{x} was defined in February 2000, and comprises six
libraries plus a compatibility layer.

@subsection vcl: The C++ compatibility layer.

The job of vcl is to turn your compiler into a standard C++ compiler.  In
particular, it ensures that your standard library behaves at least
something like that defined in the ANSI/ISO standard.  In an ideal world,
vcl would not be necessary, as all compiler vendors would ship perfectly
compliant systems.  But then, in a perfect world, C++ wouldn't be the only
choice for high efficiency high-level programming.

@subsection vbl: Basic Templates.
The basic templates library contains a small set of generally useful templated
containers and algorithms, e.g. smart pointers, triples, and sparse_arrays. Many of these
things should have been in the STL.

@subsection vul: Utilities.
This contains a number of generally useful C++ classes and functions, notably
file and directory handling,
command-line argument parser, string utilities, a timer, etc.

@subsection vnl: Numerical algorithms.
The main classes in vnl are the matrix and vector classes, which are very
simple c-like objects.  There is no reference counting, objects are
returned by value, or passed into routines.  The use of objects to hold the
output of matrix decompositions also reduces the amount of copying that
needs to be done.  The numerical algorithms are wrappers around
public-domain, high quality Fortran code from the TargetJr @code{netlib}
library but that part of vnl is placed in a separate library: @code{vnl_algo}.

@subsection vil: Imaging.
The imaging library is designed to work well with very large images, but
its primary design objective is to be fast and convenient for the typical
in-core images that are encountered in video and digital image processing.
A panoply of file formats is handled, and it is easy to add support for a
new format.

@subsection vgl: Geometry.
It is in geometry that the spartan aesthetic of the core of @vxl{x} becomes
most apparent.  The library deals with the geometry of points, curves, and
other objects in 2 or more dimensions, but may not call on the numerics
library.  Therefore, it is  restricted to operations which it is reasonable
to express in standard C++, which places a useful limit on what may be
placed there.  For example, surface fitting cannot be in geometry as it
would require the singular value decomposition.  However, there is much
here that is useful, and the library is quite large enough already.  The
@code{vgl_algo} library contains the higher-level code, which is allowed
to depend on @code{vnl} (and if necessary even on @code{vul}).

@subsection vsl: Binary I/O
This section describes how to save and restore objects using a binary stream.
It details how to add the appropriate functions to each class to make use
of this facility.

@section Additional Libraries

@subsection vcsl: Co-ordinate Systems
This library allows you to represent and manipulate transformations, transformation graphs,
and units of measurement.

@subsection vpgl: Cameras and Fundamental Matrix
Representation of various types of cameras and geometric relationships between cameras. Provides algorithms for camera calibration and other photogrammetry procedures.

@subsection vpdl: Probability Distributions
Data structures to represent univariate and multivariate probability distributions and algorithms to operate on them, like sampling and estimation.

@subsection vidl: Video
Load and save images from video files and sources.

@section Documentation
@cindex book
@cindex documentation, monolithic
The @vxl{x} documentation comes in two main forms: this book, and structured
comments in the source code, which are automatically extracted.  The book
is intended to be a single reference, where all the high-level
documentation resides.   In TargetJr and the IUE there was always a problem
finding documentation, as it was in too many places.  In @vxl{x}, we are
following the practice of some other successful systems such as vtk, and
providing one monolithic document with, we hope, a good index.

@c The principle is almost the opposite of that in the code itself.

@subsection The VXL Book

The book (in subdirectory @code{vxl/doc/book}) is a human-written collection of VXL
documentation, suitable for printing.  It is intended to be readable as an
introduction to the various facilities provided by the @vxl{x} libraries,
and to be browsable as a first source of examples and tips.

@subsubheading Why texinfo?
@cindex texinfo
It is written in texinfo, a limited form of LaTeX which allows us to make
various forms of output: printed, HTML, windows help files, emacs info, and
plain text files.  Each of these forms has its adherents, and each is
useful.  There are other documentation systems which allow multiple output
formats, but none match texinfo in the three main formats: paper,
hypertext, and ASCII.  This is because it's difficult to target such
disparate formats, and texinfo has evolved over many years to do it well.

On the other hand, texinfo is maybe hard to learn for those who don't know @TeX{}
or @LaTeX{}, so we are keeping an eye on formats such as @emph{DocBook}.

@subsection Automatically generated documentation
@cindex documentation, automatically generated
@cindex Doxygen

Although the human-written @vxl{x} book is the first source, the definitive
authority on what a class or function does must be the source code
comments.  The book will give a high-level description of the most
important and commonly-used features of a class, but the source code
contains the details.  In order to make these details easier to scan, the
@vxl{x} source files contain specially structured comments, which can be
scanned by the @emph{Doxygen} program and converted into an attractive
hyperlinked reference.

An example of what the syntax for documentation looks like can be found
in @code{vxl/doc/vxl_doc_rules.[h,cxx]}, but briefly a comment line which
begins with @code{//:} is documentation for the type, function, or
variable which follows it.  For example

@smallexample
//: Brief description of my_class
class my_class @{
  //: \brief Brief description, the long one is in the .cxx file
  my_class();
@};
@end smallexample


@anchor{VXL_Philosophy}
@section The Design and Evolution of @vxl{x}
@cindex Philosophy, The VXL

Design goals:

@itemize @bullet
@item Cross platform

@item Loosely coupled

@item light weight --- simple interfaces

@item high-powered --- allow infinitely large images.

@item uniform naming -- of course.
@end itemize

@subsection Motivation
In OpenGL, you guess the name of something, and you're generally
right.  This is what we would like to achieve with @vxl{x}.

@cindex C, similarity to C libraries
Simple and free of programming dogma.  For example, many @vxl{x} routines
exist as C-like functions.  For some tasks, C-like
functions are more appropriate than a forced object-orientation, for others
objects are clearly the more intuitive and compact representation.  This is
clearly seen in the imaging library, where the @code{vil_image} object is
passed to and returned from C-like functions, for example
@example
  vil_image i = vil_load(filename);
  i = vil_smooth_gaussian(i, 0.6);
  vil_save(i, out_filename, "pnm");
@end example
In this case, object orientation ensures that memory is managed
efficiently, without unnecessary copying of data, while using functions
makes the code more readable.

When building a large system, it is crucial to maintain consistent
conventions for file-system structure, and identifier naming.  However, a
crucial philosophy in the design of @vxl{x} is that system conventions must
be pragmatic.  If programmers are ultimately constrained rather than helped
by their environment, they will break the rules, and when they do so, they
will break them in inconsistent ways.  Therefore it is crucial that
consistency within the environment is achieved by conventions that are easy
to live with.  One example, discussed below, is in the rule governing the
relationship between header file names and the objects defined within that
header.  The general principle, then, is "as close to consistent as
comfortable, but no more".

@subsection Names

Names are always the biggest issue in programming environments.  Uniform
naming is one of the most important aspects of a library, and part of the
design effort in @vxl{x} lays in choosing a good, workable scheme for the
naming of classes, functions and files.  On the other hand, few issues
cause as much debate as the choice of naming conventions.  However, we are
lucky for two reasons: first, because we wish to run cross-platform, many
options are restricted; second, as we can never please everybody, we can
just choose a convention and pretend we all hate it.

First things first.  The name @vxl{x} itself refers to a collection of
libraries where the @emph{x} is replaced by a one or two-letter code
describing the contents.

Second, do we use @code{MixedCaseIdentifiers} or
@code{lowercase_with_underscores}?   Well, a certain operating system
#defines 1300 of the @code{MixedCaseIdentifiers} in a header file.
Therefore, programs which use names like @code{LoadImage} may or may not
link.  For this reason, we chose the other ugly solution.

@cindex file extensions
@cindex cxx
@cindex txx
For related reasons, source files in @vxl{x} all end in @code{.cxx}.
Template definitions, which look like source files but are essentially
header files (or actually #include files, as they are not separately
compiled), are suffixed @code{.txx}.

Each class or function in a @vxl{x} library begins with the name of that
library, followed by an underscore, for example @code{vnl_matrix}.
This makes it easy to locate the source code for any class, and easy to
see the list of libraries on which one's program depends.

@cindex namespaces, why not
This scheme was chosen over namespaces because few compilers support
namespaces well, and their implications in large-scale development are as
yet poorly understood.

An obvious extension of this convention would be to insist that every class
or function (in fact, every globally visible symbol exported by a library),
should be defined in its own include file, yielding an easy relationship
between symbols and include statements.  However, such a scheme
imposes great demands on programmers, who must generate long lists of
includes, and on library writers who must create many files with very
little in each.  Pragmatism must rule if we are to avoid programmer
discomfort, thus chaos.  A rule that is still useful, and easier to adhere
to is used:
@quotation
The file @code{vxl/vxl_stuff.h} exports only identifiers which
begin with @code{vxl_stuff_}, and possibly @code{vxl_stuff} itself.
@end quotation
An example of a header file which obeys this rule is shown in Figure 1.1.

@figure
@cartouche
@example
#ifndef vxl_stuff_h_
#define vxl_stuff_h_

enum vxl_stuff_things @{
  vxl_stuff_bare,
  vxl_stuff_spartan
@};

class vxl_stuff @{
@};

bool vxl_stuff_grok(vxl_stuff);
extern int vxl_stuff_val;

#endif
@end example
@end cartouche
@caption{1.1}
Example of a header file @code{vxl_stuff.h} which obeys the naming
convention. Only identifiers that begin with @code{vxl_stuff_} may be
defined.
@endcaption
@endfigure


Of course, this rule is less helpful to clients of the library, who might
remember that there is a class called @code{vtl_thing_doer}, but not know
which header file to include.  However, the disadvantage is not great, as
the likely options are just @code{vtl/vtl_thing.h} and
@code{vtl/vtl_thing_doer.h}.  What is ultimately helpful to clients is a
uniform naming scheme, kept so by pragmatic constraints on the library
developers.

FAQ: What about @code{operator+(vcl_stuff, vcl_stuff)}?  Frequently given
half-answer: Koenig lookup means it's OK.


@subsection Layering
@cindex levels, library layering
@cindex layering
@cindex library interdependencies
Which brings us on to layering: core @vxl{x} libraries may not depend on
each other.  The numerics library cannot use the handy string manipulation
in vul, the imaging library cannot use matrices, or smart pointers.  This
restriction is central to the design of @vxl{x}, because it intrinsically
limits the size of the core libraries.
It appears to contradict traditional software development practice because
it implies that code will be duplicated rather than reused.  However,
the amount of code duplicated is small, and the benefit of lego libraries
is enormous.   The current status is encapsulated in this figure
@example
Level:   0         1         2          3
         vcl       vbl       vnl_algo   v**l
                   vnl       vil_algo
                   vil       vgl_algo
                   vgl       v*l_io
                   vul
                   vsl
@end example
@quotation
Library layers: libraries in one layer may not call their
siblings, even if this means code copying.
@end quotation

However, other alternatives have been considered, and may yet be
considered.  For example, what about putting vul at level 0.5, so that
common utilities can be available to level 1?  The problem of course is
that everything will end up in the level 0.5 library.  We could impose the
rule that nothing goes in vul unless it is used in at least two level 1
libraries.  I don't know whether that would help or not...

There have been two significant propositions to accept
a level 0.5 library - for smart pointers, and binary IO. In both cases
it turned out to be relatively straight forward to provide the required
functionality without the 0.5 library, and indeed the proposers have
found the alternative implementations superior in many ways.
