man/raster.n

   1 .TH raster n 1.0 Fgis "developer Tcl commands"
   2
   3 .SH NAME
   4 raster \- Create and manipulate raster object
   5
   6 .SH SYNOPSIS
   7 \fB raster \fIfilename\fR ?\fIoptions\fR?
   8
   9 .SH DESCRIPTION
  10 .PP
  11 This command allows to create raster objects. Raster objects are more low-level
  12 concept than fGIS \fBlayers\fR. They directly correspond to raster files
  13 in EPPL7 format. Their values are always unsigned short integer.
  14 They even make cell size visible to user. This command returns name of
  15 raster object which is used for manipulating this object. By default
  16 it requires existing raster file without reclass table.
  17
  18 Raster files are objects which holds information of certain integer spatial
  19 variable in given rectangular area. Value is stored with certain granulariry.
  20 Minimal square, which can be addressed as separate unit, is named cell.
  21 Of course, you can specify coordinates with any precision, but while they are
  22 in same cell, same value would be returned. Moreover, when you edit raster,
  23 you can change values only on per cell basis.
  24
  25 Raster file is always rectangular, but spatial variable can be defined on
  26 any arbitrary area. So, special value is reserved for "undefined" areas of
  27 raster. It is named \fBoffsite\fR value. Typically you can read raster it
  28 any coordinates, but if no information is provided for this area, offsite
  29 would be returned.
  30
  31 There are certain limitation on raster files - file cannot contain more than
  32 32767 cells per row or per column. Possible values of raster should be in
  33 range 0\-65535. Rows and columns of cells can be numbered starting from
  34 any integer, provided that no row or column in file has number out of range
  35 -32767- 32767. fGIS, however never relies on column numbers. They are supported
  36 only for compatibility with EPPL7.
  37
  38 Raster objects differs from raster files in the way that they include
  39 \fBreclass table\fR. This allows to store information about several
  40 spatial variables in one file, provided that total count of value combination
  41 doesn't exceed raster file limit. Reclass table defines correspondence
  42 between file classes (values) and values, returned by raster object.
  43 It can be defined by two ways - using special syntax like in EPPL7 RECLASS
  44 command (see RECLASS SYNTAX below) or using Tcl list, each element of which
  45 is pair of values, first base, then reclassed.
  46
  47 When raster objects are accessed or created via GIS operations, user may not
  48 be aware about underlying raster file level. But when objects are created
  49 by interative editing, certain properties of raster (i.e. cell size) should
  50 be specified.
  51
  52 Raster objects behave like other fGIS objects - layers, legends, palettes etc.
  53 Once object is created, new Tcl command with same name is created. This
  54 command is used to access and modify rasters.
  55
  56 .SH OPTIONS
  57 .TP 4
  58 \fB-reclass \fIstatements\fR
  59 -specifies reclass table for created raster object. \fIstatements\fR is
  60 string, containing set of reclass statements. See \fBRECLASS SYNTAX\fR below
  61 for details
  62 .TP 4
  63 \fB-table \fIlist\fR
  64 -specifies reclass table in form of Tcl list. Each
  65 element of this list should be list of two integers, first of them representing
  66 value in raster file, and second - representing value which would be value
  67 of new raster object.
  68 .TP 4
  69 \fB-new\fR
  70 - specifies that new raster file should be created instead of
  71 opening old. This option should be specified immediately after file name
  72 and followed by several other options, defining properties of new raster.
  73 All subsequent options are applicable only if \fB-new\fR is specified.
  74 .TP 4
  75 \fB-like\fI rasterObject\fR
  76 - specifies that all important properties
  77 should be copied from existing raster object.
  78 .TP 4
  79 \fB-width\fI integer\fR
  80 - specifies how many cells should appear in each
  81 row. Cannot be used together with \fB-like\fR
  82 .TP 4
  83 \fB-height\fIinteger\fR
  84 - specifies how many cells should be in each column.
  85 .TP 4
  86 \fB-offsite\fIinteger\fR
  87  - specifies which value would be used as "no data"
  88 value. Default is 65535 for 16-bit files and 255 for 8-bit. Value -1 can
  89 be specified for 8-bit files. It means that all classes are onsite. For
  90 16-bit files it is equivalent to 65535.
  91 .TP 4
  92 \fB-8bit\fR - specifies that only one byte should be used for storing
  93 values of raster. This limits value range to 0-255, slightly decreases file
  94 size (usially much less than two times) and makes file compatible with
  95 EPPL7 ver. 2.1.
  96 .TP 4
  97 \fB-limits\fI{x1 y1 x2 y2}\fR
  98 - Allows to specify list of four double values,
  99 determinig map coordinates of file.
 100 .TP 4
 101 \fB-cell\fI value\fR - specifies size of cell. In conjunction with \fB-limits\fR
 102 it gives more convinient way to create new raster, becouse limits defines
 103 area of interest and cell size - accuracy of map.
 104
 105 .SH OBJECT COMMAND
 106 \fBraster\fR command creates new Tcl command with same name as raster object,
 107 which can be used to manipulate this object.
 108
 109 \fIrasterName\fB box\fIvalue x1 y1 x2 y2\fR -
 110 fills rectangular region with given value. Raster should be opened in
 111 read-write mode (either by \fB-new\fI option of object command or by
 112 \fBload\fR object command). Returns list of four double values, specifying
 113 region actually affected by command. (Can be less that specified region,
 114 if it exceeds raster boundary). Value is class of base raster file, not
 115 reclassed value.
 116
 117 .TP 4
 118 \fIrasterName\fB bpp\fR - returns size of data in this raster file
 119 (8 for 8-bit and 16 for 16 bit rasters).
 120 .TP 4
 121 \fIrasterName\fB cache \fR?\fInew size\fR?
 122 - controls size of cache. If raster file is accessed from disk (default
 123 read only mode) setting sufficient cache can improve performance of operations,
 124 which require nonsequentual access, like \fBtransect\fR.
 125 .TP 4
 126 \fIrasterName \fBcell\fR ?\fB-area\fR?
 127 - returns parameters of cell. By default, returns cell width in map
 128 coordinates, which should be meters, and with \fB-area\fI flag returns
 129 cell area in current units (see \fBunit\fR object command).
 130 .TP 4
 131 \fIrasterName \fBcelllimit\fR
 132 - returns list of four intergers, representig start and end numbers of cells
 133 in order \fIfirst column\fR, \fIlast row\fR, \fIlast column\fB, \fIfirst row\fR.
 134 (Why this order? X direction of cell numbers is same as of coordinates
 135  (usially), and Y coodinates usially go from bottom to top, while cells - from
 136 top to bottom. So, order of values is same as order of values in \fBlimits\fI
 137 object command.
 138 .TP 4
 139 \fIrasterName \fBclasses \fIvalue\fR
 140 - returns list of base file classes which are mapped to specified value of
 141 this raster object.
 142 .TP 4
 143 \fIrasterName \fBcircle\fI value x y radius \fR?\fB-cells\fR?
 144 - 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
 145 to be in coordinate units. Returns list of coordinates, specifying actualy
 146 affected region.
 147 .TP 4
 148 \fIrasterName \fBcol\fI x\fR
 149 - returns cell number corresponding to given X coordinate. Returns error, if
 150 coordinate is out of file boundaries.
 151 .TP 4
 152 \fIrasterName \fBcomment\fR ?\fIstring\fR?
 153 - returns (or modifies) comment, stored in file header. Comment length is
 154 limited by 32 symbols.
 155 .TP 4
 156 \fIrasterName \fBcount\fR ?\fBoptions\fR?
 157 - performs various area-calculating operation
 158 General formats folows:
 159 .TP 8
 160 \fIrasterName \fBcount\fR ?\fB--\fR? \fI varname \fR?\fIregion specification\fR?
 161 fills dynamic array \fIvarname\fR indexed by raster classes by areas of these
 162 classes in given region.
 163 .TP 8
 164 \fIrasterName \fBcount -classes \fIlist \fR?\fIregion specification\fR?
 165 returns area of given classes within given region.
 166
 167 Region specification defaults to whole file. Other possible formats are:
 168 .TP 8
 169 \fB-box\fI x1 y1 x2 y2\fR
 170 - within given rectangular area
 171 .TP 8
 172 \fB-polygon\fI x y x y ...\fR
 173 - within polygon, given by set of coordinate pairs
 174 .TP 8
 175 \fB-radius\fI distance x y ...\fR
 176 within given distance of any of given points.
 177 .TP 8
 178 \fB-mask\fI rasterObject list\fR
 179 in areas where value of another rasterObject is in given list.
 180
 181 .TP 4
 182 \fIrasterName \fBdelete\fR
 183 - destroys raster object. If raster was in readwrite mode, all unsaved changes
 184 are lost.
 185 .TP 4
 186 \fIrasterName \fBextents\fI value\fR
 187 - returns list of four coordinates, within those all values of given class
 188 are contained.
 189 .TP 4
 190 \fIrasterName \fBfilename\fR
 191 - returns name of file, corresponding to this raster object.
 192 .TP 4
 193 \fIrasterName \fBfill\fI value x y \fR?\fB-stop\fR?\fI value\fR
 194 - fills area, starting with given coordinates with value. By default,
 195 stops on encounter of any value other than in given point. If \fB-stop\fR
 196 option is specified, stops only when encountering given value. Returns
 197 list of coordinates, specifying actually affected region.
 198 .TP 4
 199 \fIrasterName \fBframe\fI value  x1 y1 x2 y2\fR ?\fB-width\fI cells\fR?
 200 - a rectangle with given value, not changing inside area. By default
 201 this rectangle is 1 cell wide.
 202 .TP 4
 203 \fIrasterName \fBget\fI x y \fR?\fB-base\fR?
 204 Returns value of raster in given point. By default returns reclassed value,
 205 but if \fB-base\fR is specified, returns class of raster file.
 206 .TP 4
 207 \fIrasterName \fBlimits\fR
 208 Returns list of four doubles, specifying physical limits of raster file, in
 209 order \fIXLeft\fR, \fIYBottom\fR, \fIXRight\fR, \fIYTop\fR.
 210 .TP 4
 211 \fIrasterName \fBline\fI value x y x y .... \fR?\fB-width \fIcells\fR?
 212 draws a line with given value. By default one-cell wide. Returns boundaries
 213 of region affected.
 214 .TP 4
 215 \fIrasterName \fBload\fR
 216 Loads raster file into memory, changing it from readonly to readwrite mode,
 217 and enabling all editing operation. (\fB-new\fR option of \fBraster\fR command
 218 performs \fBload\fR implicitely).
 219 .TP 4
 220 \fIrasterName \fBmax\fR
 221 -returns maximal value of raster object.
 222 .TP 4
 223 \fIrasterName \fBmin\fR
 224 - returns minimal value of raster object.
 225 .TP 4
 226 \fIrasterName \fBoffsite\fR ?\fIvalue\fR?
 227 - returns offsite value for raster object, or modifies it.
 228 .TP 4
 229 \fIrasterName \fBpolygon\fI value x y x y ...\fR
 230 - fills given polygon of given value. Returns boundaries of region affected.
 231 .TP 4
 232 \fIrasterName \fBput\fI value x y\fR
 233 Changes value of individual cell. Returns nothing.
 234 .TP 4
 235 \fIrasterName \fBreclass\fR ?\fIoption\fR? ?\fIarg\fR?
 236 - manipulates reclass table. Without any options, returns reclass table as
 237 Tcl list.
 238 .TP 8
 239 \fIrasterName \fBreclass -statements\fR
 240 option returns reclass table in form of reclass statements. (see \fB RECLASS SYNTAX\fR below).
 241 .TP 8
 242 \fIrasterName \fBreclass -table\fI list\fR
 243 modifies current reclass using given Tcl list. Values for classes given
 244 in this list would be changed as specified, all other remains unchanged.
 245 .TP 8
 246 \fIrasterName \fBreclass \fIstatements\fR
 247 modifies reclass using specified reclass statements. As \fB-table\fR options,
 248 applies statements to base classes and leaves all nonspecified classes as is.
 249 .TP 8
 250 \fIrasterName \fBreclass -clear\fR
 251 clears all changes in reclass table and makes reclassed classes equial to
 252 base classes.
 253 .TP 4
 254 \fIrasterName \fBrow\fI y\fR
 255 return cell number, correspondign to given Y coordinate. Raises error, if
 256 coodinnate is outside file limits.
 257 .TP 4
 258 \fIrasterName \fBsave\fR ?\fIoptions\fR?
 259 - saves raster file. By default, if raster is in readwrite mode, saves
 260 changes to current filename.
 261 .TP 8
 262 \fIrasterName \fBsave -as\fI filename\fR
 263 - saves raster, open for editing into other file, and makes this file
 264 current file of this raster object.
 265 .TP 8
 266 \fB-backup\fR
 267 option can be specified
 268 for both \fBsave\fR and \fBsave -as \fRcommands. It makes raster object to
 269 keep old version of file with suffix \fI.bak\fR appended to name.
 270 .TP 8
 271 \fIrasterName \fBsave -to\fI filename\fR ?\fB-8bit\fR?
 272 allows to write raster object into raster file. Reclass table is applied
 273 to this operation, so new file would have base classes like classes of
 274 raster object, rather than classes of its base file.
 275
 276 If \fB-8bit\fR switch is specified, resulting raster will be forced to 8-bit
 277 by discarding high-order byte, even if max value or offsite are outside
 278 0-255 range. (in latter case offsite would be set to 65535).
 279 .TP 4
 280 \fIrasterName \fBshift \fI dx dy\fR
 281 changes origin of cell (row/column) numbers. This is required for certain
 282 command of DOS version of EPPL7, although fGIS always uses map (alternative)
 283 coordinates)
 284 .TP 4
 285 \fIrasterName \fBtransect\fR ?\fB-count\fI varname\fR? \fIx y x y ...\fR
 286 by default, return list consisting of pairs {value width} along the given line.
 287 If \fB-count\fR is specified, fills dynamic array \fIvarname\fR, indexed
 288 by classes, by total widthes of given value along this line.
 289 .TP 4
 290 \fIrasterName \fBunused\fR
 291 returns value which is never encountered in this raster.
 292 .TP 4
 293 \fIrasterName \fBunit\fR ?\fInew-unit\fR?
 294 - returns (or changes) area unit of this raster Unit can be one of
 295 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.
 296 .TP 4
 297 \fIrasterName \fBxleft\fR ?\fInew value\fR?
 298 - returns (or modifies) left boundary coordinate.\fBNote:\fR it simply modifies
 299 value, without appropriate changes in other limits or cell area value.
 300 .TP 4
 301 \fIrasterName \fBxright\fR ?\fInew value\fR?
 302 - returns (or modifies) right boundary coordinate.
 303 .TP 4
 304 \fIrasterName \fBybottom\fR ?\fInew value\fR?
 305 - returns (or modifies) bottom boundary coordinate.
 306 .TP 4
 307 \fIrasterName \fBytop\fR ?\fInew value\fR?
 308 - returns (or modifies) left boundary coordinate.
 309 .SH RECLASS SYNTAX
 310
 311 Syntax of reclass syntax is inherited from EPPL7. General form of reclass
 312 statement is line, terminated by newline (\fBNote:\fR trailing newline is
 313 obligatory), which consist of new value and list of old (base) values. New
 314 value separated from list by equal sign. List of old values can contain
 315 individual values and ranges, which are two values, separated by colon.
 316
 317 .TP 4
 318 Example
 319 1=1:10 20
 320 .PP
 321 means, that all values from one to ten and value 20 should be reclassed into
 322 1.
 323
 324 Set of statements can contain arbitrary number of lines, same value can occur
 325 on left side of several lines. If some value occur on right side more than
 326 once, last occurence have precedence.