.TH raster n 1.0 Fgis "developer Tcl commands" .SH NAME raster \- Create and manipulate raster object .SH SYNOPSIS \fB raster \fIfilename\fR ?\fIoptions\fR? .SH DESCRIPTION .PP This command allows to create raster objects. Raster objects are more low-level concept than fGIS \fBlayers\fR. They directly correspond to raster files in EPPL7 format. Their values are always unsigned short integer. They even make cell size visible to user. This command returns name of raster object which is used for manipulating this object. By default it requires existing raster file without reclass table. Raster files are objects which holds information of certain integer spatial variable in given rectangular area. Value is stored with certain granulariry. Minimal square, which can be addressed as separate unit, is named cell. Of course, you can specify coordinates with any precision, but while they are in same cell, same value would be returned. Moreover, when you edit raster, you can change values only on per cell basis. Raster file is always rectangular, but spatial variable can be defined on any arbitrary area. So, special value is reserved for "undefined" areas of raster. It is named \fBoffsite\fR value. Typically you can read raster it any coordinates, but if no information is provided for this area, offsite would be returned. There are certain limitation on raster files - file cannot contain more than 32767 cells per row or per column. Possible values of raster should be in range 0\-65535. Rows and columns of cells can be numbered starting from any integer, provided that no row or column in file has number out of range -32767- 32767. fGIS, however never relies on column numbers. They are supported only for compatibility with EPPL7. Raster objects differs from raster files in the way that they include \fBreclass table\fR. This allows to store information about several spatial variables in one file, provided that total count of value combination doesn't exceed raster file limit. Reclass table defines correspondence between file classes (values) and values, returned by raster object. It can be defined by two ways - using special syntax like in EPPL7 RECLASS command (see RECLASS SYNTAX below) or using Tcl list, each element of which is pair of values, first base, then reclassed. When raster objects are accessed or created via GIS operations, user may not be aware about underlying raster file level. But when objects are created by interative editing, certain properties of raster (i.e. cell size) should be specified. Raster objects behave like other fGIS objects - layers, legends, palettes etc. Once object is created, new Tcl command with same name is created. This command is used to access and modify rasters. .SH OPTIONS .TP 4 \fB-reclass \fIstatements\fR -specifies reclass table for created raster object. \fIstatements\fR is string, containing set of reclass statements. See \fBRECLASS SYNTAX\fR below for details .TP 4 \fB-table \fIlist\fR -specifies reclass table in form of Tcl list. Each element of this list should be list of two integers, first of them representing value in raster file, and second - representing value which would be value of new raster object. .TP 4 \fB-new\fR - specifies that new raster file should be created instead of opening old. This option should be specified immediately after file name and followed by several other options, defining properties of new raster. All subsequent options are applicable only if \fB-new\fR is specified. .TP 4 \fB-like\fI rasterObject\fR - specifies that all important properties should be copied from existing raster object. .TP 4 \fB-width\fI integer\fR - specifies how many cells should appear in each row. Cannot be used together with \fB-like\fR .TP 4 \fB-height\fIinteger\fR - specifies how many cells should be in each column. .TP 4 \fB-offsite\fIinteger\fR - specifies which value would be used as "no data" value. Default is 65535 for 16-bit files and 255 for 8-bit. Value -1 can be specified for 8-bit files. It means that all classes are onsite. For 16-bit files it is equivalent to 65535. .TP 4 \fB-8bit\fR - specifies that only one byte should be used for storing values of raster. This limits value range to 0-255, slightly decreases file size (usially much less than two times) and makes file compatible with EPPL7 ver. 2.1. .TP 4 \fB-limits\fI{x1 y1 x2 y2}\fR - Allows to specify list of four double values, determinig map coordinates of file. .TP 4 \fB-cell\fI value\fR - specifies size of cell. In conjunction with \fB-limits\fR it gives more convinient way to create new raster, becouse limits defines area of interest and cell size - accuracy of map. .SH OBJECT COMMAND \fBraster\fR command creates new Tcl command with same name as raster object, which can be used to manipulate this object. \fIrasterName\fB box\fIvalue x1 y1 x2 y2\fR - fills rectangular region with given value. Raster should be opened in read-write mode (either by \fB-new\fI option of object command or by \fBload\fR object command). Returns list of four double values, specifying region actually affected by command. (Can be less that specified region, if it exceeds raster boundary). Value is class of base raster file, not reclassed value. .TP 4 \fIrasterName\fB bpp\fR - returns size of data in this raster file (8 for 8-bit and 16 for 16 bit rasters). .TP 4 \fIrasterName\fB cache \fR?\fInew size\fR? - controls size of cache. If raster file is accessed from disk (default read only mode) setting sufficient cache can improve performance of operations, which require nonsequentual access, like \fBtransect\fR. .TP 4 \fIrasterName \fBcell\fR ?\fB-area\fR? - returns parameters of cell. By default, returns cell width in map coordinates, which should be meters, and with \fB-area\fI flag returns cell area in current units (see \fBunit\fR object command). .TP 4 \fIrasterName \fBcelllimit\fR - returns list of four intergers, representig start and end numbers of cells in order \fIfirst column\fR, \fIlast row\fR, \fIlast column\fB, \fIfirst row\fR. (Why this order? X direction of cell numbers is same as of coordinates (usially), and Y coodinates usially go from bottom to top, while cells - from top to bottom. So, order of values is same as order of values in \fBlimits\fI object command. .TP 4 \fIrasterName \fBclasses \fIvalue\fR - returns list of base file classes which are mapped to specified value of this raster object. .TP 4 \fIrasterName \fBcircle\fI value x y radius \fR?\fB-cells\fR? - fills circulare region in read-write raster with given value. If \fB-cells\fR,flag is given, radius is assumed to be in raster cells. Otherwise it is assumed to be in coordinate units. Returns list of coordinates, specifying actualy affected region. .TP 4 \fIrasterName \fBcol\fI x\fR - returns cell number corresponding to given X coordinate. Returns error, if coordinate is out of file boundaries. .TP 4 \fIrasterName \fBcomment\fR ?\fIstring\fR? - returns (or modifies) comment, stored in file header. Comment length is limited by 32 symbols. .TP 4 \fIrasterName \fBcount\fR ?\fBoptions\fR? - performs various area-calculating operation General formats folows: .TP 8 \fIrasterName \fBcount\fR ?\fB--\fR? \fI varname \fR?\fIregion specification\fR? fills dynamic array \fIvarname\fR indexed by raster classes by areas of these classes in given region. .TP 8 \fIrasterName \fBcount -classes \fIlist \fR?\fIregion specification\fR? returns area of given classes within given region. Region specification defaults to whole file. Other possible formats are: .TP 8 \fB-box\fI x1 y1 x2 y2\fR - within given rectangular area .TP 8 \fB-polygon\fI x y x y ...\fR - within polygon, given by set of coordinate pairs .TP 8 \fB-radius\fI distance x y ...\fR within given distance of any of given points. .TP 8 \fB-mask\fI rasterObject list\fR in areas where value of another rasterObject is in given list. .TP 4 \fIrasterName \fBdelete\fR - destroys raster object. If raster was in readwrite mode, all unsaved changes are lost. .TP 4 \fIrasterName \fBextents\fI value\fR - returns list of four coordinates, within those all values of given class are contained. .TP 4 \fIrasterName \fBfilename\fR - returns name of file, corresponding to this raster object. .TP 4 \fIrasterName \fBfill\fI value x y \fR?\fB-stop\fR?\fI value\fR - fills area, starting with given coordinates with value. By default, stops on encounter of any value other than in given point. If \fB-stop\fR option is specified, stops only when encountering given value. Returns list of coordinates, specifying actually affected region. .TP 4 \fIrasterName \fBframe\fI value x1 y1 x2 y2\fR ?\fB-width\fI cells\fR? - a rectangle with given value, not changing inside area. By default this rectangle is 1 cell wide. .TP 4 \fIrasterName \fBget\fI x y \fR?\fB-base\fR? Returns value of raster in given point. By default returns reclassed value, but if \fB-base\fR is specified, returns class of raster file. .TP 4 \fIrasterName \fBlimits\fR Returns list of four doubles, specifying physical limits of raster file, in order \fIXLeft\fR, \fIYBottom\fR, \fIXRight\fR, \fIYTop\fR. .TP 4 \fIrasterName \fBline\fI value x y x y .... \fR?\fB-width \fIcells\fR? draws a line with given value. By default one-cell wide. Returns boundaries of region affected. .TP 4 \fIrasterName \fBload\fR Loads raster file into memory, changing it from readonly to readwrite mode, and enabling all editing operation. (\fB-new\fR option of \fBraster\fR command performs \fBload\fR implicitely). .TP 4 \fIrasterName \fBmax\fR -returns maximal value of raster object. .TP 4 \fIrasterName \fBmin\fR - returns minimal value of raster object. .TP 4 \fIrasterName \fBoffsite\fR ?\fIvalue\fR? - returns offsite value for raster object, or modifies it. .TP 4 \fIrasterName \fBpolygon\fI value x y x y ...\fR - fills given polygon of given value. Returns boundaries of region affected. .TP 4 \fIrasterName \fBput\fI value x y\fR Changes value of individual cell. Returns nothing. .TP 4 \fIrasterName \fBreclass\fR ?\fIoption\fR? ?\fIarg\fR? - manipulates reclass table. Without any options, returns reclass table as Tcl list. .TP 8 \fIrasterName \fBreclass -statements\fR option returns reclass table in form of reclass statements. (see \fB RECLASS SYNTAX\fR below). .TP 8 \fIrasterName \fBreclass -table\fI list\fR modifies current reclass using given Tcl list. Values for classes given in this list would be changed as specified, all other remains unchanged. .TP 8 \fIrasterName \fBreclass \fIstatements\fR modifies reclass using specified reclass statements. As \fB-table\fR options, applies statements to base classes and leaves all nonspecified classes as is. .TP 8 \fIrasterName \fBreclass -clear\fR clears all changes in reclass table and makes reclassed classes equial to base classes. .TP 4 \fIrasterName \fBrow\fI y\fR return cell number, correspondign to given Y coordinate. Raises error, if coodinnate is outside file limits. .TP 4 \fIrasterName \fBsave\fR ?\fIoptions\fR? - saves raster file. By default, if raster is in readwrite mode, saves changes to current filename. .TP 8 \fIrasterName \fBsave -as\fI filename\fR - saves raster, open for editing into other file, and makes this file current file of this raster object. .TP 8 \fB-backup\fR option can be specified for both \fBsave\fR and \fBsave -as \fRcommands. It makes raster object to keep old version of file with suffix \fI.bak\fR appended to name. .TP 8 \fIrasterName \fBsave -to\fI filename\fR ?\fB-8bit\fR? allows to write raster object into raster file. Reclass table is applied to this operation, so new file would have base classes like classes of raster object, rather than classes of its base file. If \fB-8bit\fR switch is specified, resulting raster will be forced to 8-bit by discarding high-order byte, even if max value or offsite are outside 0-255 range. (in latter case offsite would be set to 65535). .TP 4 \fIrasterName \fBshift \fI dx dy\fR changes origin of cell (row/column) numbers. This is required for certain command of DOS version of EPPL7, although fGIS always uses map (alternative) coordinates) .TP 4 \fIrasterName \fBtransect\fR ?\fB-count\fI varname\fR? \fIx y x y ...\fR by default, return list consisting of pairs {value width} along the given line. If \fB-count\fR is specified, fills dynamic array \fIvarname\fR, indexed by classes, by total widthes of given value along this line. .TP 4 \fIrasterName \fBunused\fR returns value which is never encountered in this raster. .TP 4 \fIrasterName \fBunit\fR ?\fInew-unit\fR? - returns (or changes) area unit of this raster Unit can be one of following: \fBundefined\fR,\fBft\fR.\fBm\fR,\fBkm\fR,\fBmile\fR,\fBha\fR,\fBacre\fR. All subsequent count operations would return result in given units. \fBNote:\fR map coordinates are always in meters. .TP 4 \fIrasterName \fBxleft\fR ?\fInew value\fR? - returns (or modifies) left boundary coordinate.\fBNote:\fR it simply modifies value, without appropriate changes in other limits or cell area value. .TP 4 \fIrasterName \fBxright\fR ?\fInew value\fR? - returns (or modifies) right boundary coordinate. .TP 4 \fIrasterName \fBybottom\fR ?\fInew value\fR? - returns (or modifies) bottom boundary coordinate. .TP 4 \fIrasterName \fBytop\fR ?\fInew value\fR? - returns (or modifies) left boundary coordinate. .SH RECLASS SYNTAX Syntax of reclass syntax is inherited from EPPL7. General form of reclass statement is line, terminated by newline (\fBNote:\fR trailing newline is obligatory), which consist of new value and list of old (base) values. New value separated from list by equal sign. List of old values can contain individual values and ranges, which are two values, separated by colon. .TP 4 Example 1=1:10 20 .PP means, that all values from one to ten and value 20 should be reclassed into 1. Set of statements can contain arbitrary number of lines, same value can occur on left side of several lines. If some value occur on right side more than once, last occurence have precedence.