Geografic-Information-System/lib/imagery/imagerylib.dox

/*! \page imagerylib GRASS Imagery Library
<!-- doxygenized from "GRASS 5 Programmer's Manual" 
     by M. Neteler 2/2004
  -->

\section imageryintro Introduction to Imagery Library

The <I>Imagery Library</I> was created for version 3.0 of GRASS to
support integrated image processing directly in GRASS. It contains
routines that provide access to the <I>group</I> database structure
which was also introduced in GRASS 3.0 for the same purpose. It is
assumed that the reader has read Database_Structure for a general
description of GRASS databases, \ref Image_Data_Groups for a description of
imagery groups, and \ref Raster_Maps for details about map layers in
GRASS. The routines in the \ref Imagery_Library are presented in functional
groupings, rather than in alphabetical order. The order of
presentation will, it is hoped, provide a better understanding of how
the library is to be used, as well as show the interrelationships
among the various routines. Note that a good way to understand how to
use these routines is to look at the source code for GRASS modules
which use them. Most routines in this library require that the header
file <grass/imagery.h> be included in any code using these
routines. Therefore, programmers should always include this file when
writing code using routines from this library:

\verbatim
#include <grass/imagery.h>
\endverbatim

<P>
<B>Note.</B> All routines and global variables in this library,
documented or undocumented, start with the prefix <B>I_.</B> To avoid
name conflicts, programmers should not create variables or routines in
their own modules which use this prefix.

\subsection Group_Processing Group Processing

The group is the key database structure which permits integration of
image processing in GRASS.

<P>
\subsection Prompting_for_a_Group Prompting for a Group

<P>
The following routines interactively prompt the user for a group name
in the current mapset (This library only works with groups in the
current mapset. Other mapsets, even those in the user's mapset search
path, are ignored.) In each, the <B>prompt</B> string will be printed
as the first line of the full prompt which asks the user to enter a
group name. If <B>prompt</B> is the empty string "", then an
appropriate prompt will be substituted. The name that the user enters
is copied into the <B>group</B> buffer. The size of group should be
large enough to hold any GRASS file name. Most systems allow file
names to be quite long. It is recommended that name be declared
<tt>char group</tt>.  These routines have a built-in 'list' capability
which allows the user to get a list of existing groups.

<P>
The user is required to enter a valid group name, or else hit the
RETURN key to cancel the request. If the user enters an invalid
response, a message is printed, and the user is prompted again. If the
user cancels the request, 0 is returned; otherwise, 1 is returned.

<P>
int I_ask_group_old() prompt for an existing group

Asks the user to enter the name of an existing <B>group</B> in the
current mapset.

<P>
<B>Note.</B> The user is not warned if the <B>group</B> exists. The
programmer should use <I>I_find_group()</I> to determine if the
<B>group</B> exists.

<P>
Here is an example of how to use these routines. Note that the
programmer must handle the 0 return properly:

\verbatim
char group[INAME_LEN];

if ( ! I_ask_group_any ("Enter group to be processed", group))
   exit(0);
\endverbatim

<P>

\subsection Finding_Groups_in_the_Database Finding Groups in the Database

<P>
Sometimes it is necessary to determine if a given group already
exists. The following routine provides this service:

<P>
int I_find_group() does group exist?  

Returns 1 if the specified <B>group</B> exists in the current mapset;
0 otherwise.


\subsection REF_File REF File

<P>
These routines provide access to the information contained in the REF
file for groups and subgroups, as well as routines to update this
information.  They use the <I>Ref</I> structure, which is defined in
the <grass/imagery.h> header file; see \ref Imagery_Library_Data_Structures.

<P>
The contents of the REF file are read or updated by the following
routines:

<P>
int I_get_group_ref() read group REF file

Reads the contents of the REF file for the specified <B>group</B> into
the <B>ref</B> structure.

<P>
Returns 1 if successful; 0 otherwise (but no error messages are printed).

<P>
int I_put_group_ref() write group REF file 

Writes the contents of the <B>ref</B> structure to the REF file for
the specified <B>group.</B>

<P>
Returns 1 if successful; 0 otherwise (and prints a diagnostic error).

<P>
<B>Note.</B> This routine will create the <B>group</B>, if it does not
already exist.

<P>
int I_get_subgroup_ref() read subgroup REF file

Reads the contents of the REF file for the specified <B>subgroup</B>
of the specified <B>group</B> into the <B>ref</B> structure.

<P>
Returns 1 if successful; 0 otherwise (but no error messages are printed).

<P>
int I_put_subgroup_ref() write subgroup REF file

Writes the contents of the <B>ref</B> structure into the REF file for
the specified <B>subgroup</B> of the specified <B>group.</B>

<P>
Returns 1 if successful; 0 otherwise (and prints a diagnostic error).

<P>
<B>Note.</B> This routine will create the <B>subgroup</B>, if it does
not already exist.

<P>
These next routines manipulate the <I>Ref</I> structure:

<P>
int I_init_group_ref() initialize Ref structure

This routine initializes the <B>ref</B> structure for other library
calls which require a <I>Ref</I> structure. This routine must be
called before any use of the structure can be made.

<P>
<B>Note.</B> The routines I_get_group_ref() and I_get_subgroup_ref() call
this routine automatically.

<P>
int I_add_file_to_group_ref() add file name to Ref structure

This routine adds the file <B>name</B> and <B>mapset</B> to the list
contained in the <B>ref</B> structure, if it is not already in the
list.  The <B>ref</B> structure must have been properly
initialized. This routine is used by programs, such as
<I>i.maxlik</I>, to add to the group new raster files created from
files already in the group.

<P>
Returns the index into the <I>file</I> array within the <B>ref</B>
structure for the file after insertion; see \ref
Imagery_Library_Data_Structures.

<P>
int I_transfer_group_ref_file() copy Ref lists

This routine is used to copy file names from one <I>Ref</I> structure
to another. The name and mapset for file <B>n</B> from the <B>src</B>
structure are copied into the <B>dst</B> structure (which must be
properly initialized).

<P>
For example, the following code copies one <I>Ref</I> structure to another:

\verbatim
struct Ref src,dst;
int n;

/* some code to get information into src */

...

I_init_group_ref(&dst);

for (n = 0; n < src.nfiles; n++)
   I_transfer_group_ref_file (&src, n, &dst);

\endverbatim

<P>
This routine is used by <I>g.gui.gcp</I> to create the REF file for a
subgroup.

<P>
int I_free_group_ref() free Ref structure

This routine frees memory allocated to the <B>ref</B> structure.

\subsection TARGET_File TARGET File

<P>
The following two routines read and write the TARGET file.

<P>
int I_get_target() read target information

Reads the target <B>location</B> and <B>mapset</B> from the TARGET
file for the specified group. Returns 1 if successful; 0 otherwise
(and prints a diagnostic error). This routine is used by
<I>g.gui.gcp</I> and <I>i.rectify</I> and probably should not be used
by other programs.

<P>
<B>Note.</B> This routine does <B>not</B> validate the target information.

<P>
int I_put_target() write target information

Writes the target <B>location</B> and <B>mapset</B> to the TARGET file
for the specified <B>group.</B> Returns 1 if successful; 0 otherwise
(but no error messages are printed).

<P>
This routine is used by <I>i.target</I> and probably should not be
used by other programs.

<P>
<B>Note.</B> This routine does <B>not</B> validate the target
information.

\subsection POINTS_File POINTS File


<P>
The following routines read and write the POINTS file, which contains
the image registration control points. This file is created and
updated by the module <I>g.gui.gcp</I>,and read by <I>i.rectify.</I>

<P>
These routines use the <I>Control_Points</I> structure, which is
defined in the <grass/imagery.h> <I>header file</I>; see \ref
Imagery_Library_Data_Structures.

<P>
<B>Note.</B> The interface to the <I>Control_Points</I> structure
provided by the routines below is incomplete. A routine to initialize
the structure is needed.

<P>
int I_get_control_points() read group control points

Reads the control points from the POINTS file for the <B>group</B>
into the <B>cp</B> structure. Returns 1 if successful; 0 otherwise
(and prints a diagnostic error).

<P>
<B>Note.</B> An error message is printed if the POINTS file is
invalid, or does not exist.

<P>
int I_new_control_point() add new control point

Once the control points have been read into the <B>cp</B> structure,
this routine adds new points to it. The new control point is given by
<B>e1</B> (column) and <B>n1</B> (row) on the image, and the <B>e2</B>
(east) and <B>n2</B> (north) for the target database. The value of
<B>status</B> should be 1 if the point is a valid point; 0
otherwise.Use of this routine implies that the point is probably good,
so status should be set to 1.


<P>
int I_put_control_points() write group control points

Writes the control points from the <B>cp</B> structure to the POINTS
file for the specified group.

<P>
<B>Note.</B> Points in <B>cp</B> with a negative <I>status</I> are not
written to the POINTS file.



\subsection Loading_the_Imagery_Library Loading the Imagery Library


<P>
The library is loaded by specifying $(IMAGERYLIB) in the
Makefile. The following example is a complete Makefile which
compiles code that uses this library:
<P>
<B>Makefile for $(IMAGERYLIB)</B>

\verbatim
#UPDATE THIS EXAMPLE!!
OBJ = main.o sub1.o sub2.o

PGM: $(OBJ) $(IMAGERYLIB) $(GISLIB)

$(CC) $(LDFLAGS) -o $@ $(OBJ) $(IMAGERYLIB) $(GISLIB)

$(IMAGERYLIB): # in case the library changes

$(GISLIB): # in case the library changes
\endverbatim

<B>Note.</B> This library must be loaded with $(GISLIB) since it uses
routines from that library. See \ref GIS_Library or details on that
library. See \ref Compiling_and_Installing_GRASS_Modules for a complete
discussion of Makefiles.

\section Imagery_Library_Data_Structures Imagery Library Data Structures

Some of the data structures in the <grass/imagery.h> header file are
described below.

\subsection struct_Ref struct Ref

<P>
The <I>Ref</I> structure is used to hold the information from the REF
file for groups and subgroups. The structure is:

\verbatim
struct Ref
{
int nfiles; /* number of REF files */
struct Ref_Files
{
  char name[INAME_LEN]; /* REF file name */
  char mapset[INAME_LEN]; /* REF file mapset */
} *file;


struct Ref_Color
{
unsigned char *table; /* color table for min-max values */
unsigned char *index; /* data translation index */
unsigned char *buf; /* data buffer for reading color file */
int fd; /* for image i/o */
CELL min, max; /* min,max CELL values */
int n; /* index into Ref_Files */
} red, grn, blu;

};

\endverbatim

The <I>Ref</I> structure has <I>nfiles</I> (the number of raster
files), <I>file</I> (the name and mapset of each file), and
<I>red,grn,blu</I> (color information for the group or subgroup) Note:
The red,grn,blu elements are expected to change as the imagery code
develops. Do not reference them. Pretend they do not exist.

<P>
There is no function interface to the <I>nfiles</I> and <I>file</I>
elements in the structure. This means that the programmer must
reference the elements of the structure directly (The nfiles and file
elements are not expected to change in the future). The name and
<I>mapset for the i th file are file[i].name, and file[i].mapset.</I>

<P>
For example, to print out the names of the raster files in the structure:

\verbatim
int i;
struct Ref ref;

...

/* some code to get the REF file for a group into <B>ref</B> */

...

for (i = 0; i<ref.nfiles; i++)
  fprintf(stdout, "%s in %s\n", ref.file[i].name, ref.file[i].mapset);
\endverbatim

\subsection struct_Control_Points struct Control_Points 

The <I>Control_Points</I> structure is used to hold the control points
from the group POINTS file. The structure is:

\verbatim
struct 
Control_Points
{
int count; /* number of control points */
double *e1; /* image east (column) */
double *n1; /* image north (row) */
double *e2; /* target east */
double *n2; /* target north */
int *status; /* status of control point */
};
\endverbatim

The number of control points is <I>count.</I>

<P>
Control point <I>i</I> is <I>e1</I> [i], <I>n1</I> [i], <I>e2</I> [i],
<I>n2</I> [i], and its status is <I>status</I> [i].

*/