⟦726493673⟧

TextFile

.TH IMAGE 5 8/19/86
.CM 1
.SH "NAME"
image \- double_image long_image
.SH "SYNOPSIS"
.nf
// for a long image
#include <long_image.h++>
// for a double image
#include <double_image.h++>
// to create your own image type
#include <image.h++>
.sp
// this is the base data structure for images:
.sp
.sp
/*
    The operations that can be applied when creating the window.
    one can read in an image or create one.
*/
enum create_image_type { CREATE = 7 };
enum read_image_type { READ = 4 };
.sp
.sp
/* protection for images */
enum image_prot 
    { 
    CAN_READ = 1 , 
    CAN_WRITE = 2 , 
    CAN_READ_AND_WRITE = 3 ,
    CAN_NOT_DO_ANYTHING = 4
    };
.sp
/*
    useful for determining the status of data structures
*/
enum status { INITIALIZED = 8 , UNINITIALIZED = 16 };
.sp
/*
    This is the abstract data type for any image
    Actually objects of this type are not useful
    it is meant to have derived types
*/
class image_class
    {
public:
    card number_rows;		// number rows in image
    card number_cols;		// number of collumns in image
    void * header_info ;	// any further header information required by implementation
    image_prot prot;		// the protection of the image 
    card comment_length;	// the length of the comments
    char * comments ;		// comments about the image
    status image_status;	// determines when image data is initialized
.sp
    /* position in image */
    status window_status;	// determines when the window has been initialized
    card collumn;		// the collumn
    card row;			// the row
    card window_width;		// width of possible window in image
    card window_length;		// length of possible window in image
    FILE * file;		// file associated with image
.sp
    /* constructors for images */
    /* constructor when reading an image from a file */
    image_class
	( 
	const read_image_type rit , 	// marker that the image is being read
	const FILE * image_file ,	// file for image
	const card w_width  ,	// window width
	const card w_length 	// window length
	);
.sp
    /* constructor for creating a new image */
    image_class
	( 
	const create_image_type cit,	// maker that the image is being created
	const FILE * image_file , 	// the file for the image
	const card n_rows , 		// the number of rows in the image
	const card n_cols , 		// the number of collumns in the image
	const card w_width , 		// the width of the window
	const card w_length 		// the length of the window
	);
.sp
    /* destructor for images */
    ~image_class () { ; }
.sp
    /* comment manipulation */
.sp
    /* sets the comments */
    void set_comments( char * string , const card length );
.sp
    /* adds a string to the comments */
    void add_comment( char * string , const card length );
.sp
    /* for moving around in an image */
.sp
.sp
    /*
	move in row n steps 
	returns 1 when that motion is legal 0 otherwise
    */
    virtual int move_collumn ( const int n ) ;
.sp
    /*
	move in collumn n steps
	returns 1 when that motion is legal 0 otherwise
    */
    virtual int move_row ( const int n ) ;
.sp
    /*
	move to specified row
    */
    virtual void move_to_row ( const card n ) ;
.sp
    /*
	move to specified collumn
    */
    virtual void move_to_collumn ( const card n ) ;
.sp
    /* routine to write out the image to a file */
    virtual void write ( ) ;
.sp
    /* change the protection from CAN_WRITE to CAN_READ_AND_WRITE */
    virtual void read_and_write ( );
.sp
    };
.sp
/* returns a null terminated string for comments */
const char * comment_string ( image_class& i );
.sp
.sp
// This is the derived type for images of doubles.
// The derived type for longs is the same with long replacing double
.sp
.sp
/*
    the definition of the class to manage image structures
*/
class double_image : image_class
    {
    double *image_buffer;	// buffer to hold image
    double **image_rows;	// pointers to the rows of the image
    double **window_rows;	// pointers to the rows of the window
    /* functions for function pointers */
    ...
.sp
public:
    /* constructors */
    /* the constructor when the image is being read from a file */
    double_image
	( 
	const read_image_type rit , 	// marker that the image is being read
	const FILE * image_file ,	// file for image
	const card w_width = 1 ,	// window width
	const card w_length = 1		// window length
	);
.sp
    /* the constructor when the image is built */
    double_image
	( 
	const create_image_type cit ,	// marker that the image is being created
	const card n_rows , 		// the number of rows in the image
	const card n_cols , 		// the number of collumns in the image
	const FILE * image_file ,	// file for image
	const card w_width = 1 ,	// window width
	const card w_length = 1 	// window length
	);
.sp
    /* destructor (who would want to destroy an image?) */
    ~double_image ( ) { ; }
.sp
    /* access routines for parts of data structure */
    const card n_rows() { return number_rows ; }
    const card n_cols() { return number_cols ; }
    const image_prot the_prot() { return prot; }
    const card c_length() { return comment_length ; }
    const char *the_comments() { return comments ; }
    const card the_collumn() { return collumn ; }
    const card the_row() { return row ; }
    const card the_width() { return window_width ; }
    const card the_length() { return window_length ; }
    const FILE * the_file() { return file ; }
    const status image_init() { return image_status ; }
    const status window_init() { return window_status ; }
.sp
    /* access a pointer to a particular row */
    const double * get_row( card row );
.sp
    /* sets the comments */
    void set_comments( char * string , const card length )
	{
	this->image_class::set_comments ( string , length );
	}
.sp
    /* adds a string to the comments */
    void add_comment( char * string , const card length )
	{
	this->image_class::add_comment ( string , length );
	}
.sp
.sp
    /* real versions of virtual functions */
    /* routine to write out the image to a file */
    void write ( ) ;
.sp
    /*
	move in row n steps 
	returns 1 when that motion is legal 0 otherwise
    */
    int move_collumn ( const int n ) ;
.sp
    /*
	move in collumn n steps
	returns 1 when that motion is legal 0 otherwise
    */
    int move_row ( const int n ) ;
.sp
    /*
	move to specified row
    */
    void move_to_row ( const card n ) ;
.sp
    /*
	move to specified collumn
    */
    void move_to_collumn ( const card n ) ;
.sp
    
    /*
	the function to get the specified element of a window
	it is a function pointer so that unitialized windows
	or protected images don't get read from
	this accesses the function pointer
    */
    double get_w_e ( const card i , const card j )
	{ return (( double (*) (...) )(* get_w_e_pointer)) ( this , i , j ); }
.sp
    /*
	the fast function without checking for initialization
	of a function pointer for getting elements of a window
	Also no bounds checking!
	( Not recommended!)
    */
    double fast_g_w_e ( const card i , const card j )
	{ return window_rows[i][j]; }
    
    /*
	the function to write to the specified element of a window.
	it is a function pointer so that unitialized windows
	or protected images don't get read from
	this accesses the function pointer
    */
    void write_w_e ( const card i , const card j , const double value )
	{ ((void (*) (...) )(* write_w_e_pointer)) ( this , i , j , value ); }
.sp
    /*
	the fast function without checking for initialization
	of a function pointer for writing elements to a window
	Also no bounds checking!
	( Not recommended!)
    */
    void fast_w_w_e ( const card i , const card j , const double value )
	{ window_rows[i][j] = value; }
.sp
    /* 
	the function call on the image gets the upper left hand 
	of the image window and returns a reference so it can be
	used as a lvalue or rvalue
	optimized so does not check that the window is initialized
	if the window is not initialized then odd things may happen
    */
    double& operator() ()
	{ return **window_rows; }
    
    /* 
	move to next legal position in image
	returns 1 when there is a next legal position 0 otherwise
	if the window is not initialized then it initializes it.
	with the window in the position 0,0 (if possible)
    */
    int (* next) (...); /* this will point to member functions! */
.sp
    /* 
	move to previous legal position in image
	returns 1 when there is a previous legal position 0 otherwise
	if the window is not initialized then it initializes it.
	with the window in the farthest position (if possible)
    */
    int (* prev) (...); /* this will point to member functions! */
.sp
    /*
	Access for next and previous elements of images
    */
    int operator++ ( ) 
	{ return (* next) ( this /* because points to member*/ ); }
    int operator-- ( ) 
	{ return (* prev) ( this /* because points to member*/ ); }
.sp
    /*
	Change the size of a window
	causes the window to become uninitialized
    */
    void resize_window ( card width , card length );
.sp
    /*
	Causes the window to cover the entire image.
	Allows one to access any part of the image with window operations
    */
    void window_entire_image ( );
.sp
    };
.sp
.fi
Compile with -lvarc++ -lvar -liff 
.SH "DESCRIPTION"
This is a description of a C++ class to access images.
It handles the concept of a 2d array of longs or doubles
with a window of a specified size.
The routines are designed
to check in so far as possible for illegal values given to them
such as points outside the window to the window routines.
The current implementation is designed to work with the var
image package (
.B "var(3)"
).
.IP "CONSTRUCTORS"
There are two constructors for double or long images.  The first
reads in the image and constructs the correct image data structure
for it.  It should be called as:
.nf
{double,long}_image input(READ,file_pointer)
or
{double,long}_image input(READ,file_pointer,window_width,window_length)
.fi
The last two arguments are optional and control the size of the
window.  If they are omitted then the window is 1 by 1.  
.br
The other constructor is used to create an image for output which is
not read in from a file.  It should be called as:
.nf
{double,long}_image output
    (
    CREATE,
    number_rows,
    number_collumns,
    file_pointer
    )
or
{double,long}_image output
    (
    CREATE,
    number_rows,
    number_collumns,
    file_pointer,
    window_width,
    window_length
    )
.fi
As before the last two arguments are optional and when left out are
initialized to 1.  
.PP
The destructor for images is currently null.
.IP "Access Routines"
These routines retrieve interesting private parts of the data
structure that can be useful.  This allows parts of an image to be
read only.  This also one to pass parts of the data structure to C
routines.  The first few retrieve information about the image as a
whole.
.br
.B "n_rows:"
 retrieves the number of rows in the image.
.br
.B "n_cols:"
 retrieves the number of collumns in the image.
.br
.B "the_prot:"
 retrieves the protection status of the image.  This way one can tell
whether the image is read or write protected.
.br
.B "c_length:"
 returns the number of chars in the comments
.br
.B "the_comments:"
 returns a 
.I "not necessarily"
null terminated string containing the comments.
.br
.B "the_file:"
 returns the file pointer which is the file for the image.
.br
.B "image_init:"
 returns whether the image has been initialized.
.br
.br
The next few access functions control the window to the image.
.br
.B "window_init:"
 returns whether the image window has been initialized.
.br
.B "the_collumn:"
 the collumn of the upper left hand corner of the window.
.br
.B "the_row:"
 the row of the upper left hand corner of the window.
.br
.B "the_width:"
 the width of the window.
.br
.B "the_length:"
 the length of the window.
.br
.br
Another access function mostly for C routines is 
.B get_row
that retrieves a pointer to a specified row in an image.
.br
.br
A command that is not part of the access routines but functions in
much the same way is 
.B "comment_string"
that takes an image and returns a null terminated string for the
comment.
.IP "Comment Management"
There are two routines that are used to construct comments for an
image.  
.B "set_comments"
sets the comments to a specified string of a specified length.  
.B "add_comments"
adds to the already existing comments a specified string of a
specified length.
.IP "Output"
.B "write"
writes the image out to its specified file.
.IP "Moving the Window"
.B "move_collumn" 
and
.B "move_row"
incrementally move the window to a specified number of rows or
collumns.  They both return a boolean to indicate whether the
move is possible.  
.B "move_to_row"
and
.B "move_to_collumn"
are used to move the window on the image to a specified position in
the image.  They will print an error message and dump core if an
illegal position is specified.  
.IP "Iterating through an Image"
For iterating through an entire image there are two function
.I "pointers"
.B "*next" and 
.B "*prev."
When 
.B "*next" 
is called on an initialized image it initializes the window and 
sends it to the upper left hand corner of the image.  Successive calls
move the window along the row until it doesn't fit any more and then
to the beginning of the next collumn.  
.B "*prev" 
starts on the bottom right of the the image and moves backwards.  
.B "++"
is overloaded to be 
.B "*next" 
on images and
.B "--"
is overloaded to be
.B "*prev"
on images.
Both functions return true when they are legal and false when
they fall off the image.  If they fall off the image they do nothing.
One can iterate through an image using these this way:
.nf
while(++image)
or
while(++input,++output)
.fi
When the second technique is used one must be careful to make sure
that the size of output is (input.n_rows() - input.the_length() + 1 ,
input.n_cols() - input.the_width() + 1).
.IP "Accessing Window Elements"
There are several functions for reading or writing to elements of a
window.  For reading
.B "get_w_e"
returns a window element.  A version of this exists without any
checking that the numbers given make sense.  It is called 
.B "fast_get_w_e."
Use of this code is not recomended.
Similarly 
.B "write_w_e"
and
.B "fast_write_w_e"
write a value to a particular point in a window.  Once again I do not
recomend using 
.B "fast_write_w_e."
If you only want to access the (0,0) element of a window (especially
useful if your window is default size).  You can use the overloaded
function call operator
.B "()"
to access or write to this element.
as an example:
.nf
output() = 7;
writes 7 to the upper left hand corner of the window on the image
output.
cout << input();
writes the upper left hand corner of the window to the stdout.
.fi
.IP "Changing the Size of the Window"
Two member functions are supplied to retrieve the size of an existing
window:
.B "resize_window"
and
.B "window_entire_image."
.B "resize_window" 
changes the size of a window to a specified size.
.b "window_entire_image" 
makes the window size the same as the image size and makes the entire
image inside the window.  This allows one to access any part of the
image array as a point in the window.
.SH "FILES"
/usr/local/include/image.h++
/usr/local/include/double_image.h++
/usr/local/include/long_image.h++
.SH "SEE ALSO"
var(3)
.SH "DIAGNOSTICS"
Usually crashes out with an error message and a core dump
if something suspicious is tried.
.SH "BUGS"
Either my code has absolutely and completely no bugs or I am
a bare faced liar.
.SH HISTORY
.TP
19-Aug-86  David Sher (sher) at University of Rochester
Created.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦726493673⟧ TextFile

Derivation

TextFile
