USING AND EXTENDING THE RAMPAGE IMAGE PROCESSING ARCHITECTURE
(c) 1997 Mayur Patel


LICENSE

Included in the distribution is a licensing agreement.  Please read and
understand the terms in the file, LICENSE, before using RAMPAGE.

If you or your organization plans to use RAMPAGE for internal or external
projects, then please let me know.  I would like to maintain a list of RAMPAGE
users.



USING RAMPAGE

The header files are the best place to learn about the primitives of the
library. Here, I give a high-level template that most pipelines will follow. 
See the /rampage/examples subdirectory for sample source code.

Coding an image processing pipeline requires three steps:
   (1) Set up the image manager
   (2) Construct image pipeline
   (3) Instantiate an output image
   
The image manager is the portion of the architecture which arbitrates pixel
calculations and limits memory consumption.  Developers should always use the
class RpManReference to access and configure the image manager.

Two concrete image manager classes are currently implemented: "Mini" and
"SoftPull."  The mini-manager does not use auxiliary RAM to cache data, so
run-times are long.  This is a good manager to use when debugging, because it
is easy to follow.  The softpull-manager does use extra memory to cache image
calculations.  It is designed to process extremely large pipelines.

Once an image manager is selected, memory bounds should be set.  Then the image
processing graph can be instantiated.

There are two fundamental kinds of images. First, there are generic input
images.  These have an inherent data type, but may have unlimited domain or
resolution.  Second, there are sampled images. These are images with limited
domain, sampled on a rectangular grid.  All image processing operators are
sub-classed from one of these classes.  All the parameters required to define
the content of an image should be passed through the image's constructor.  

At the end of the pipeline, instantiation of an output driver triggers the
calculation of the pipeline.



EXTENDING RAMPAGE

As mentioned earlier, all images should be derived from the input image class
or the sampled image class.  A good rule of thumb is this: point processing
operations are probably best suited to be derived from the input image class. 
If the image depends explicitly upon the rectangular arrangement of pixels,
then it is best represented through a sampled image.  In image space, the
lower-left corner of the image should be considered to be the origin.

To implement a new image processing operation, implement an appropriate
constructor, destructor and ::fillTile() method.  See the input image header
file for the exact requirements of the ::fillTile() method.

When implementing an output driver, use the ::newTile() method to request image
data.  Image data are returned in tile objects, which are reference-counted.
Therefore, you should use ::deleteTile() to dismiss a tile retrieved using
::newTile().  Because the system is designed to constrain memory consumption,
it is best if you do not request more data at one time than you require.  If
your output driver writes data in 8x8 blocks, then use ::newTile() iteratively
to request 8x8 blocks.

Implementing a new image processing engine is more complicated than
implementing new image processing operators.  Study the image manager base
class to understand the internal interfaces.  Unless you have a very
specialized application, it is unlikely that you will really want to implement
a new image manager.

Simple channel-uniform point-processing operations may be implemented quickly
with templates.  See RpBinaryOp.h and RpUnaryOp.h.  These templates take a
functoid class as a template parameter.  This functoid class is applied to
each value of each channel of each pixel.

Please study the source code for ideas on how to implement new image processing
operators.  There are many topics I haven't discussed, such as the pixel models
and internal interfaces.  In addition to the architecture source, there is an
/examples/ directory.



SUPPORT AND EXTENSIONS

If you have a question or comments, you may contact me.  Contact information is
available in the file /rampage/doc/CONTACT.  I will try to help you, but please
understand that I get paid to do other things.

If you wish to contribute to RAMPAGE, then please send your source code to me. 
Clearly place your name and contact information at the top of each file as a
comment.  Also, explicitly state the licensing terms under which you would like
your code distributed at the top of each file.  I may choose not to include
your code in the regular RAMPAGE distribution if it deviates significantly from
the interface or design criteria of the rest of the architecture.  The design
criteria place image quality first, memory-constrained execution second and
execution speed last.

User-supplied extensions will be aggregated into a /rampage/contrib/ directory
unless the functionality of the entire architecture becomes dependent upon that
code.  Extensions in /rampage/contrib/ will likely have a "Rpx" prefix rather
than the normal RAMPAGE prefix, "Rp."



Thanks.
Mayur Patel
