Introduction to Imagery Library

The Imagery Library was created for version 3.0 of GRASS to support integrated image processing directly in GRASS. It contains routines that provide access to the group 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, Image_Data_Groups for a description of imagery groups, and Raster_Maps for details about map layers in GRASS. The routines in the 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:

#include <grass/imagery.h>

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

Group Processing

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

Prompting for a Group

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 prompt string will be printed as the first line of the full prompt which asks the user to enter a group name. If prompt is the empty string "", then an appropriate prompt will be substituted. The name that the user enters is copied into the group 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 char group. These routines have a built-in 'list' capability which allows the user to get a list of existing groups.

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.

int I_ask_group_old() prompt for an existing group

Asks the user to enter the name of an existing group in the current mapset.

Note. The user is not warned if the group exists. The programmer should use I_find_group() to determine if the group exists.

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

char group[INAME_LEN];

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

Finding Groups in the Database

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

int I_find_group() does group exist?

Returns 1 if the specified group exists in the current mapset; 0 otherwise.

REF File

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 Ref structure, which is defined in the <grass/imagery.h> header file; see Imagery Library Data Structures.

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

int I_get_group_ref() read group REF file

Reads the contents of the REF file for the specified group into the ref structure.

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

int I_put_group_ref() write group REF file

Writes the contents of the ref structure to the REF file for the specified group.

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

Note. This routine will create the group, if it does not already exist.

int I_get_subgroup_ref() read subgroup REF file

Reads the contents of the REF file for the specified subgroup of the specified group into the ref structure.

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

int I_put_subgroup_ref() write subgroup REF file

Writes the contents of the ref structure into the REF file for the specified subgroup of the specified group.

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

Note. This routine will create the subgroup, if it does not already exist.

These next routines manipulate the Ref structure:

int I_init_group_ref() initialize Ref structure

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

Note. The routines I_get_group_ref() and I_get_subgroup_ref() call this routine automatically.

int I_add_file_to_group_ref() add file name to Ref structure

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

Returns the index into the file array within the ref structure for the file after insertion; see Imagery Library Data Structures.

int I_transfer_group_ref_file() copy Ref lists

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

For example, the following code copies one Ref structure to another:

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);

This routine is used by i.points to create the REF file for a subgroup.

int I_free_group_ref() free Ref structure

This routine frees memory allocated to the ref structure.

TARGET File

The following two routines read and write the TARGET file.

int I_get_target() read target information

Reads the target location and mapset 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.points and i.rectify and probably should not be used by other programs.

Note. This routine does not validate the target information.

int I_put_target() write target information

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

This routine is used by i.target and probably should not be used by other programs.

Note. This routine does not validate the target information.

POINTS File

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.points,and read by i.rectify.

These routines use the Control_Points structure, which is defined in the <grass/imagery.h> header file; see Imagery Library Data Structures.

Note. The interface to the Control_Points structure provided by the routines below is incomplete. A routine to initialize the structure is needed.

int I_get_control_points() read group control points

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

Note. An error message is printed if the POINTS file is invalid, or does not exist.

int I_new_control_point() add new control point

Once the control points have been read into the cp structure, this routine adds new points to it. The new control point is given by e1 (column) and n1 (row) on the image, and the e2 (east) and n2 (north) for the target database. The value of status 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.

int I_put_control_points() write group control points

Writes the control points from the cp structure to the POINTS file for the specified group.

Note. Points in cp with a negative status are not written to the POINTS file.

Loading the Imagery Library

The library is loaded by specifying in the Makefile. The following example is a complete Makefile which compiles code that uses this library:

Makefile for

#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

Note. This library must be loaded with since it uses routines from that library. See GIS_Library or details on that library. See Compiling and Installing GRASS Modules for a complete discussion of Makefiles.

Imagery Library Data Structures

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

struct Ref

The Ref structure is used to hold the information from the REF file for groups and subgroups. The structure is:

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;

};

The Ref structure has nfiles (the number of raster files), file (the name and mapset of each file), and red,grn,blu (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.

There is no function interface to the nfiles and file 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 mapset for the i th file are file[i].name, and file[i].mapset.

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

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);

struct Control_Points

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

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 */
};

The number of control points is count.

Control point i is e1 [i], n1 [i], e2 [i], n2 [i], and its status is status [i].