NUMWRIT

Description

Writes image data gray-level values from database image channel(s) to a text file or LASF file.

Parameters

Name	Type	Caption	Length	Value range
FILE *	String	Input file name	1 - 192
DBGEO	Integer	Input georeferencing segment	0 - 1	Default: 1
DBIC *	Integer	Input raster channel(s)	1 -
MASK	Integer	Area mask	0 - 4	Xoffset, Yoffset, Xsize, Ysize
NUMFORM *	String	Output data numeric format	4 - 20	COORD | DATA | GEOCOORD | LASFZ | LASFInten Default: COORD
SAMPLING	Integer	Sampling interval	0 - 2	1 - Default: 1,1
TFILE *	String	Output text or LASF file	1 - 192
MONITOR	String	Monitor mode	0 - 3	ON, OFF Default: ON

* Required parameter

Parameter descriptions

FILE

Specifies the name of the image file that contains the image data to process.

DBGEO

Optionally specifies the georeferencing segment. This parameter is required only if the output coordinates (NUMFORM) are specified as georeferenced units (GEOCOORD). Otherwise, pixel and line coordinates are used when writing to the output file.

DBIC

Specifies the image channel(s) for which the gray values are to be written to the output text file or LASF file. Complex channels cannot be processed.

Ranges of channels or segments can be specified with negative values. For example, {1,-4,10} is internally expanded to {1,2,3,4,10}. When you are not specifying a range in this way, only 48 numbers can be specified explicitly.

MASK

Specifies the window or bitmap that defines the area to be processed within the input raster.

If a single value is specified, that value represents the channel number of the bitmap segment in the input file. Only the pixels under the bitmap are processed; the rest of the image remains unchanged.

If four values are specified, they define the x,y offsets and x,y dimensions of a rectangular window identifying the area to process. Xoffset, Yoffset define the upper-left starting pixel coordinates of the window. Xsize is the number of pixels that define the window width. Ysize is the number of lines that define the window height.

If no value is specified, the entire channel is processed.

NUMFORM

Specifies the format in which image data will be stored in the output text file or LASF file.

For the coordinate (COORD) format, the text file contains two values for each pixel: database x-position (pixel) and database y-position (line), and is followed by gray-level value(s) pertaining to each input channel (in pixel-interleave mode). You may specify the number of pixels to be output on each line of text using the "COORDn" form. For example if n=2 (that is, "COORD2"), 2 pixels (6 values) will be output on each line for one input channel. If the number of input channels is four, and n=2 ("COORD2"), four pixels (x,y coordinate and two gray-level values) will be output on each line, for a total 12 columns. If no n value is specified, by default 1 pixel will be output per line.

For the georeferenced coordinate (GEOCOORD) format, the content of the text file is similar to that of the COORD format except that the (x,y) position is expressed in georeferenced units. You may specify the number of pixels to be output on each line of text using the "GEOCOORDn" form. For example, if n=2 (that is, "GEOCOORD2"), 2 pixels (6 values) will be output on each line, if DBIC is equal to one. If no n value is specified, by default 1 pixel will be output per line for 8-bit, 16-bit or 32-bit channels.

For the data ("DATA") format, the text file will contain a gray-level value for each pixel (one gray-level value for each input channel, DBIC). You may specify the number of pixels to be output on each line of text using the "DATAn" form. For example, if n=2 (that is, "DATA2"), 2 pixels (2 values) will be output on each line. If no n value is specified, by default 1 pixel will be output per line.

For the LASF format, the output is not a text file but a LAS Format Lidar point file. For both LASF options, the x and y coordinates of the point come from the x and y of the pixel. The pixel value is written to the z coordinate of the point (for a DEM for example) for the LASFZ option. For the LASFInten option the pixel value is written to the point intensity attribute field. All points are written to the first returns. X and Y offset and scaling are set from the minimum x and y values and the range of values. The Z offset and scaling are set from the raster elevation offset and scaling metadata if they are present. Otherwise the offset is 0 and the scaling is 0.001 for millimeter scaling.

The LAS format has a limit to the number of points that can be in a file. For this reason and in order to keep the number of points in a file manageable, when one billion points have been written to the LAS file, the file is closed and further points are written to an overflow file or files. The first file has the same name as specified in the TFILE parameter with a suffix "_1" and subsequent files have a corresponding suffix. If only one file was needed to contain the points then the output file name is the value of the TFILE parameter.

All options listed above may be followed, without any intervening spaces, by a comma and a keyword SUPPRESS. If this keyword is present, pixels are omitted from output if any of their channels has either a no-data or a failed value. These values are extracted from the metadata tags NO_DATA_VALUE and FAILED_VALUE of individual channels. If a channel has no such tag, the tag from the file is used, if present.

SAMPLING

Specifies the sampling interval in pixel (X) and line (Y) direction to write out the converted data. The default is 1,1.

TFILE

Specifies the path and file name of the text file or LASF file to which the image channel data will be written.

The output file must not already exist before running NUMWRIT.

MONITOR

The program progress can be monitored by printing the percentage of processing completed. A system parameter, MONITOR, controls this activity.

Available options are:

• ON: Turns the monitor ON (default)
• OFF: Turns the monitor OFF (recommended if running in batch or background mode)

Details

NUMWRIT transfers image data from a specified image channel (DBIC) of the input file (FILE) to the specified output text file or LASF file (TFILE). The image gray-level values are transferred in a format that can be read by other third-party programs.

The MASK parameter specifies the area within the input channel(s) from which gray-level values will be written to the text file or LASF file (TFILE).

If a single value is specified, this value points to a bitmap segment which defines the area to be processed. When four values are specified, these values define the x,y offsets and x,y dimensions of a rectangular window within the image to be processed.

If the MASK parameter is not specified, the entire image is processed and written to the output text file or LASF file.

If more than one input channel is specified, NUMWRIT writes the data into the text file in pixel-interleave format (BIP).

By default all selected pixels are written out. However, if the comma-separated SUPPRESS option is added to the NUMFORM parameter, then only pixels with all valid values are written. The per-channel invalid values are extracted from the no-data value or failed value metadata tags of each channel. If a channel has no tags, the values from the file-level tags are used; if they are not set, then all pixels of a given channel are treated as valid.

Examples

Create a text file COORD.TXT with image data in coordinate format with 5 pixels per text line.

EASI>FILE	=	"irvine.pix"
EASI>DBGEO	=
EASI>DBIC	=	1
EASI>MASK	=	0,0,10,7	! defines the upper left 10 x 7 region
EASI>NUMFORM	=	"COORD5"	! 5 values per text line
EASI>SAMPLING	=
EASI>TFILE	=	"COORD.TXT"

EASI>RUN NUMWRIT

Create a text file using the "data" format, with 10 gray values per line.

EASI>FILE	=	"irvine.pix"
EASI>DBGEO	=
EASI>DBIC	=	1
EASI>MASK	=	0,0,10,7
EASI>NUMFORM	=	"DATA10"	! 10 values written per line
EASI>SAMPING	=
EASI>TFILE	=	"DATA.TXT"

EASI>RUN NUMWRIT