


grass.to.ipw            GRASS Reference Manual             grass.to.ipw



NAME
	grass.to.ipw -- Converts GRASS raster map layer to IPW image file

SYNOPSIS
	grass.to.ipw
	grass.to.ipw help
	grass.to.ipw [-r] [-o] map=name [header=name] [units=name] \
	                 [divisor=value] [offset=value]	

DESCRIPTION
	grass.to.ipw converts a GRASS raster file to an IPW image file.
	The current GRASS mask is taken into account.  The IPW image is
	written to standard output.

	An IPW linear quantization header may be provided with the header=
	option or as stdin; otherwise the number of bits per pixel and
	floating point map are derived from the min and max cell values
	(the floating point map maximum may be increased to preserve the
	precision of the data).  Contrary to previous versions of this
	utility, the number of lines and samples in the given header do
	not need to conform with the currently defined GRASS region.

	If no IPW header file is specified, the number of bits per
	pixel will be set large enough to hold the maximum data
	value in the GRASS map layer, i.e. N bits where N is the
	lowest integer such that 2**N - 1 is greater than the
	maximum data value in the GRASS map layer.  The linear
	quantization mapping will be defined so that there is a
	1:1 mapping of the integer data values. 

	If the -r (raw data) flag is specified, the GRASS data values will
	be copied as raw pixel values to the IPW image without inclusion of
	a linear quantization header.  If both the -r flag and an IPW header
	file are specified, the given linear quantization header will be
	written to the output image, but the data values will nevertheless
	be copied as raw pixel values, bypassing the floating point mapping
	(see examples below).

        In GRASS, the raster header specifies the north, south, east
        and west boundaries as the outer cell edges of the raster map.
        The data values are assumed to be located at the cell centers.
        Therefore, the data value for the northwestern-most cell (row 0,
        col 0) is georeferenced at northing NORTH-NSRES/2 and easting
        WEST+EWRES/2 (where NORTH is the northern edge of the raster,
        WEST is the western edge of the raster and NSRES and EWRES are
        the resolutions in the N/S and E/W directions, respectively).
        In IPW the GEO header parameters bline and bsamp, analogous
        to NORTH and WEST, do not define the outer edge of the boundary
        cells (i.e. IPW pixels).  Instead they georeference the centers
        of the boundary cells.

        To translate the IPW image to a GRASS format, this half-cell
        difference of the georeferencing parameters is accounted for. 
        The geographic region stored in the header of the new GRASS
        raster will be set so that:

		bline = NORTH-NSRES/2
		bsamp = WEST+EWRES/2.
		dline = -NSRES
		dsamp = EWRES

	where bline and bsamp are the beginning line and sample coordinates,
        and dline and dsamp are the line and sample increments of the
        IPW geodetic header. Thus unlike most GRASS commands, the current
	geographic region of your GRASS session is not used to set the
	boundaries or resolution of the IPW image which is generated. 

        The -o flag can be used to override reckoning of the
        half-resolution difference in the georeferencing parameters.  If the
        -o option is specified, bline will be set to NORTH and bsamp will
        be set to WEST without adjustment for the difference.  This option
        should be invoked only when evidence of spatial misregistration is
        apparent and understood (use only with extreme caution).

	A divisor and/or offset may be specified for conversion of
	the integer GRASS data values to IPW floating point values.
	If both are specified, the offset will be added to the data
	first, and then the result will be divided by the given
	divisor before storing in the IPW output image.

	If a units parameter is specified, the given units name will
	be stored in the "units =" line of the lq (linear quantization)
	header of the output IPW image file.

OPTIONS

	Flags:
	-r                  raw values (don't convert to linear quantization)
        -o                  set IPW GEO header parameters bline and bsamp
			    equal to GRASS cell header parameters
                            NORTH and WEST, respectively:
                            causes one-half cell resolution misregistration in
                            each direction (see discussion above)


	Parameters:
	map=name            input GRASS raster file


GRASS 4.0                U.S. Army CERL                         1






grass.to.ipw            GRASS Reference Manual             grass.to.ipw



	header=name         input linear quantization header file
	units=name          data units for annotation
	divisor=value       divide each map data by this value
			    default: 1.0
	offset=value	    add to each map data (prior to division)
			    default: 0.0
	

EXAMPLES

	The following command,

		grass.to.ipw map=grasslayer divisor=10.0 offset=-100.0 \
		       > ipwfile

	will convert a GRASS map layer called  grasslayer to an IPW
	image file called ipwfile, subtracting 100.0 from all input
	values then dividing the result by 10.0 before storing in the
	IPW output file.

	The following pipeline of commands,

		mkbih -l 200 -s 500 -f | mklqh -m 0,0,255,1.275 -f \
		  | grass.to.ipw -r map=rawlayer > image

	creates an IPW image with 200 lines and 500 samples with linear
	floating point mapping defined by the pairs (0,0) and (255,1.275).
	The data values in GRASS raster file "rawlayer" are copied as raw
	pixel values, so that a value of 200 in input map layer grasslayer
	is copied as raw value 200 in the IPW image, and will be mapped to
	floating point value of 1.0.

	To convert several GRASS raster files into a multi-band IPW image:
		grass.to.ipw map=raster.1 > ipw.1
		    ...
		grass.to.ipw map=raster.N > ipw.N
		mux ipw.1 ... ipw.N > image

WARNINGS

	IPW suffers from a forked path of software development, with 
	libraries having been released by both UCSB and the EPA
	Environmental Research Laboratory -- Corvallis.  There is a
	kludge in headers.c, for example, designed to handle one of the
	differences in the library code for bihmake.c.  There is at this
	time, however, no suitable solution for the use of ftoa (float
	to ASCII string) in the UCSB code, as opposed to dtoa (double).
	As a result of the latter, only SIX significant digits will be
	found in the georegistration descriptions in the geo header created
	by this utility if it has been compiled with UCSB library calls.
	Significant misregistration of data may ensue, so user beware!
	Manual editing of the resulting IPW data headers may be required.

SEE ALSO
     James Edward Frew, Jr., The Image Processing Workbench

     Also read GRASS User's Reference Manual entries for:
     ipw.to.grass, g.region

AUTHOR
     Kelly Longley, Oregon State University, EPA Environmental
     Research Lab - Corvallis, OR








GRASS 4.0                U.S. Army CERL                         2



