head	1.1;
access;
symbols;
locks
	thoth:1.1; strict;
comment	@% @;


1.1
date	95.02.01.19.21.33;	author thoth;	state Exp;
branches;
next	;


desc
@Operations Description file format document
@


1.1
log
@Initial revision
@
text
@%
% Operations Description File Format
%

%
%	Copyright 1993,1994,1995, Center for Computer Vision and Visualization,
%	University of Florida.  All rights reserved.
%

%
% $Log$
%

\documentstyle[fullpage]{article}

\begin{document}

\title {IAC++ Image Operations Descriptions}

\section{Overview}

  The Image Algebra requires that many operations upon images and
scalars be available.  These operations must be quick and convenient
to use.  The use of operator and function overloading makes this
possible.

  A certain class of operations are ``derivative''.  Their operations
are rather straightforwardly derived from operations upon the scalar
values in the image.  Plus between two images constructs a new image
that is the pointwise additions of the values in the two source
images.

  However, there are approximately 400 operations and functions of
this sort available in the 2.2 library.  They comprise about 2M (62
thousand source lines) of code.  Maintaining this much code would be a
nightmare.

  Since the many of the operations are very similar they are good
candidates for code templates.  However C++ does not yet (and may
never) support templates of their sort, so text substitution upon
meta-code has to be used.

  In our current design we use an operations description file that is
parsed by a perl script which performs substitutions on meta-code.
There are 1700 lines of description files, 2300 lines of scripts, and
5300 lines of meta-code (most of which are generated by another
script).  This is much more maintainable than the 62000 lines of
source this system generates.

\section{Image Operations}

  The operations description file for images is line-based.  Tokens
are separated by whitespace.

  Source files for the image operations are generated by the {\tt
c-gen-ops.perl} program.  All arguments to the {\tt c-gen-ops.perl}
program are files to be processed.  If no arguments are supplied, it
reads from stdin.

  Header files for the image operations are generated by the {\tt
h-gen-ops.perl} program.  It recognizes one optional argument that
appears before files to be parsed: {\tt -friends}.  This flag causes
the program to emit declarations suitable for inclusion as friends
inside the body of a class definition.

\subsection{Non-operations}

  A line beginning with {\tt \#} is considered a comment.  If any text
follows the {\tt \#} then it is passed through as a C++ {\tt //}
comment.

  A line beginning with {\tt "} is a source quote.  A number of
single-character flags follow in this specific order.  If the optional
{\tt H} is present then the rest of the line is copied verbatim into
the header file.  If the optional {\tt C} is present then the rest of
the line is copied verbatim into the source file.  If {\tt H} was
present before an {\tt F} or {\tt f} may be the last flag.  If an {\tt
F} is present then the line is only quoted if the {\tt -friends} flag
was supplied.  If instead an {\tt f} is present then the line is only
quoted if no {\tt -friends} flag was supplied.

  Quoting is most useful for including support routines and special
non-exported functions.

  A line beginning with the word {\tt prefix} is a preamble beginning
marker.  All text on later lines is added to the preamble until a line
containing only the word {\tt end} (with no leading or trailing
whitespace) is read.  The end directive is not added to the preamble.
The preamble is loaded but not used by the header generation script.

  A line beginning with the word {\tt filename} is a source output
filename directive.  It has no effect upon the generation of header
files.  The word immediately after it is the name of a file to direct
future source code into.  One of these must preceed any lines that
generate source output.  The specified file is open for write and the
preamble is written as the first few lines.

\subsection{Operations}

  An operation description line has 4 parts.  Modifiers, name, subop,
and arguments.

\begin{description}

  \item {Modifiers} there are 5 different types of operation and 4
adjectives that can be applied to some of these.  These words appear
in any order before the actual name of the operation.

  \item {Name} after the modifiers comes the name of the operation.
If it begins with the word {\tt operator} then it is either an infix
operator or an op=.

  \item {Subop} If the base operation does not have the same name as
the image operation (as is often the case with reductions) then you
can specify the name of the sub-operation with the token {\tt
subop=}{\it name}.

  \item {Arguments} The return type and argument types are specified
here.  The return type is the first token.  The second token is the
first argument type.  If there is a second argument, then its type is
specified by the third token.

  Scalar arguments are specified with just the name of the type.  Image arguments are specified as {\tt I(}{\it type}{\tt )}.

\end{description}

\subsubsection{Operation classes}

 The following keywords are all mutually exclusive.  Only one should
appear on each operation description line.

\begin{description}
  \item {\tt reduction} A binary operation (or function) is applied to
accumulate a result from individual image values taken from a single
argument image.  This binary operation should (theoretically) be
commutative and associative.  The argument signature of a reduction is
{\tt T I(T)}.

  \item {\tt pointwise} The operation is performed upon each source
value (or pair of source values in the binary case) to get the values
for the new image.  Binary operations require that their two source
images have identical domains.  Pointwise operations can have a number
of signatures: {\tt I(T) I(T)}, {\tt I(T) I(T) I(T)}, {\tt I(T) T
I(T)}, or {\tt I(T) I(T) T}.

  \item {\tt strictrel} A binary operation yielding a boolean is
performed upon every pair of values from the source images.  If the
operation yields true for every pair, then the result is true, else
the result is false.  The argument signature of a strictrel is
{\tt bool I(T)}.

  \item {\tt constructor} Obsolete.

  \item {\tt conversion} Obsolete.

\end{description}

  There is no support for $n$-ary operations where $n > 2$.

\subsection{Operation modifiers}

  The following two modifiers may be applied to operations of the {\tt
pointwise} class.

\begin{description}
  \item {\tt unary} The base operation requires only one argument.
Consequently the image operation will only take one image argument.

  \item {\tt binary} The base operation requires two arguments.
Consequently the image operation will take two arguments, and they
must have identical domains (or the operation will generate a run-time
error).

\end{description}

  The following two modifiers may only be applied to {\tt binary
pointwise} operations.

\begin{description}
  \item {\tt commutative} The base operation is commutative (the
result does not depend upon the order of its arguments).  The code
generated for a commutative operation takes advantage of this fact to
generate less code (it swaps arguments when convenient).

  \item {\tt non-commutative} The base operation is not commutative.
The space optimizations possible in the commutative case are not possible.

\end{description}

\end{document}
@
