geography/fGIS/man/raster.n.html

   1 <!-- manual page source format generated by PolyglotMan v3.0.4, -->
   2 <!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->
   3
   4 <HTML>
   5 <HEAD>
   6 <TITLE>raster(n) manual page</TITLE>
   7 </HEAD>
   8 <BODY>
   9 <A HREF="#toc">Table of Contents</A><P>
  10 <P>
  11
  12 <H2><A NAME="sect0" HREF="#toc0">NAME </A></H2>
  13 raster - Create and manipulate raster object  <P>
  14
  15 <H2><A NAME="sect1" HREF="#toc1">SYNOPSIS </A></H2>
  16 <B> raster
  17 <I>filename </I></B> ?<I>options </I>? <P>
  18
  19 <H2><A NAME="sect2" HREF="#toc2">DESCRIPTION </A></H2>
  20 <P>
  21 This command allows to create raster
  22 objects. Raster objects are more low-level concept than fGIS <B>layers </B>. They
  23 directly correspond to raster files in EPPL7 format. Their values are always
  24 unsigned short integer.  They even make cell size visible to user. This
  25 command returns name of raster object which is used for manipulating this
  26 object. By default it requires existing raster file without reclass table.
  27  <P>
  28  Raster files are objects which holds information of certain integer
  29 spatial variable in given rectangular area. Value is stored with certain
  30 granulariry. Minimal square, which can be addressed as separate unit, is
  31 named cell. Of course, you can specify coordinates with any precision,
  32 but while they are in same cell, same value would be returned. Moreover,
  33 when you edit raster, you can change values only on per cell basis. <P>
  34  Raster
  35 file is always rectangular, but spatial variable can be defined on any
  36 arbitrary area. So, special value is reserved for "undefined" areas of
  37 raster. It is named <B>offsite </B> value. Typically you can read raster it any
  38 coordinates, but if no information is provided for this area, offsite
  39 would be returned.  <P>
  40  There are certain limitation on raster files - file
  41 cannot contain more than 32767 cells per row or per column. Possible values
  42 of raster should be in range 0-65535. Rows and columns of cells can be numbered
  43 starting from any integer, provided that no row or column in file has
  44 number out of range -32767- 32767. fGIS, however never relies on column numbers.
  45 They are supported only for compatibility with EPPL7.  <P>
  46  Raster objects
  47 differs from raster files in the way that they include <B>reclass table </B>.
  48 This allows to store information about several spatial variables in one
  49 file, provided that total count of value combination doesn't exceed raster
  50 file limit. Reclass table defines correspondence between file classes (values)
  51 and values, returned by raster object. It can be defined by two ways - using
  52 special syntax like in EPPL7 RECLASS command (see RECLASS SYNTAX below)
  53 or using Tcl list, each element of which is pair of values, first base,
  54 then reclassed. <P>
  55  When raster objects are accessed or created via GIS operations,
  56 user may not be aware about underlying raster file level. But when objects
  57 are created by interative editing, certain properties of raster (i.e. cell
  58 size) should be specified. <P>
  59  Raster objects behave like other fGIS objects
  60 - layers, legends, palettes etc. Once object is created, new Tcl command
  61 with same name is created. This command is used to access and modify rasters.
  62 <P>
  63
  64 <H2><A NAME="sect3" HREF="#toc3">OPTIONS </A></H2>
  65
  66 <DL>
  67
  68 <DT><B>-reclass <I>statements </I></B>  </DT>
  69 <DD>-specifies reclass table for created raster
  70 object. <I>statements </I> is string, containing set of reclass statements. See
  71 <B>RECLASS SYNTAX </B> below for details </DD>
  72
  73 <DT><B>-table <I>list </I></B>   </DT>
  74 <DD>-specifies reclass table
  75 in form of Tcl list. Each element of this list should be list of two integers,
  76 first of them representing value in raster file, and second - representing
  77 value which would be value of new raster object. </DD>
  78
  79 <DT><B>-new </B>   </DT>
  80 <DD>- specifies that
  81 new raster file should be created instead of opening old. This option should
  82 be specified immediately after file name and followed by several other
  83 options, defining properties of new raster. All subsequent options are
  84 applicable only if <B>-new </B> is specified. </DD>
  85
  86 <DT><B>-like<I> rasterObject </I></B>   </DT>
  87 <DD>- specifies that
  88 all important properties  should be copied from existing raster object.
  89 </DD>
  90
  91 <DT><B>-width<I> integer </I></B>   </DT>
  92 <DD>- specifies how many cells should appear in each row. Cannot
  93 be used together with <B>-like </B> </DD>
  94
  95 <DT><B>-height<I>integer </I></B>   </DT>
  96 <DD>- specifies how many cells
  97 should be in each column. </DD>
  98
  99 <DT><B>-offsite<I>integer </I></B>  </DT>
 100 <DD> - specifies which value would
 101 be used as "no data" value. Default is 65535 for 16-bit files and 255 for
 102 8-bit. Value -1 can be specified for 8-bit files. It means that all classes
 103 are onsite. For 16-bit files it is equivalent to 65535. </DD>
 104
 105 <DT><B>-8bit </B> - specifies
 106 that only one byte should be used for storing  </DT>
 107 <DD>values of raster. This limits
 108 value range to 0-255, slightly decreases file size (usially much less than
 109 two times) and makes file compatible with EPPL7 ver. 2.1. </DD>
 110
 111 <DT><B>-limits<I>{x1 y1 x2
 112 y2} </I></B>   </DT>
 113 <DD>- Allows to specify list of four double values, determinig map coordinates
 114 of file. </DD>
 115
 116 <DT><B>-cell<I> value </I></B> - specifies size of cell. In conjunction with <B>-limits
 117 </B>  </DT>
 118 <DD>it gives more convinient way to create new raster, becouse limits defines
 119  area of interest and cell size - accuracy of map. </DD>
 120 </DL>
 121 <P>
 122
 123 <H2><A NAME="sect4" HREF="#toc4">OBJECT COMMAND </A></H2>
 124 <B>raster
 125 </B> command creates new Tcl command with same name as raster object, which
 126 can be used to manipulate this object.  <P>
 127  <I>rasterName<B> box<I>value x1 y1 x2 y2
 128 </I></B></I> - fills rectangular region with given value. Raster should be opened in
 129 read-write mode (either by <B>-new<I> option of object command or by <B>load </B></I></B> object
 130 command). Returns list of four double values, specifying region actually
 131 affected by command. (Can be less that specified region, if it exceeds
 132 raster boundary). Value is class of base raster file, not reclassed value.
 133 <P>
 134
 135 <DL>
 136
 137 <DT><I>rasterName<B> bpp </B></I> - returns size of data in this raster file  </DT>
 138 <DD>(8 for 8-bit
 139 and 16 for 16 bit rasters). </DD>
 140
 141 <DT><I>rasterName<B> cache  </B></I>?<I>new size </I>?  </DT>
 142 <DD>- controls size
 143 of cache. If raster file is accessed from disk (default read only mode)
 144 setting sufficient cache can improve performance of operations, which
 145 require nonsequentual access, like <B>transect </B>. </DD>
 146
 147 <DT><I>rasterName <B>cell </B></I> ?<B>-area </B>?
 148  </DT>
 149 <DD>- returns parameters of cell. By default, returns cell width in map  coordinates,
 150 which should be meters, and with <B>-area<I> flag returns cell area in current
 151 units (see <B>unit </B></I></B> object command). </DD>
 152
 153 <DT><I>rasterName <B>celllimit </B></I>  </DT>
 154 <DD>- returns list
 155 of four intergers, representig start and end numbers of cells in order
 156 <I>first column </I>, <I>last row </I>, <I>last column<B>, <I>first row </I></B></I>. (Why this order? X direction
 157 of cell numbers is same as of coordinates  (usially), and Y coodinates
 158 usially go from bottom to top, while cells - from top to bottom. So, order
 159 of values is same as order of values in <B>limits<I> object command. </DD>
 160
 161 <DT><I>rasterName
 162 <B>classes <I>value </I></B></I></I></B>  </DT>
 163 <DD>- returns list of base file classes which are mapped to
 164 specified value of this raster object. </DD>
 165
 166 <DT><I>rasterName <B>circle<I> value x y radius
 167  </I></B></I>?<B>-cells </B>?  </DT>
 168 <DD>- fills circulare region in read-write raster with given value.
 169 If <B>-cells </B>,flag is given, radius is assumed to be in raster cells. Otherwise
 170 it is assumed to be in coordinate units. Returns list of coordinates, specifying
 171 actualy affected region. </DD>
 172
 173 <DT><I>rasterName <B>col<I> x </I></B></I>  </DT>
 174 <DD>- returns cell number corresponding
 175 to given X coordinate. Returns error, if coordinate is out of file boundaries.
 176 </DD>
 177
 178 <DT><I>rasterName <B>comment </B></I> ?<I>string </I>?   </DT>
 179 <DD>- returns (or modifies) comment, stored
 180 in file header. Comment length is limited by 32 symbols. </DD>
 181
 182 <DT><I>rasterName <B>count
 183 </B></I> ?<B>options </B>?  </DT>
 184 <DD>- performs various area-calculating operation General formats
 185 folows: </DD>
 186
 187 <DT><I>rasterName <B>count </B></I> ?<B>-- </B>? <I> varname  </I>?<I>region specification </I>?  </DT>
 188 <DD>fills
 189 dynamic array <I>varname </I> indexed by raster classes by areas of these classes
 190 in given region.  </DD>
 191
 192 <DT><I>rasterName <B>count -classes <I>list  </I></B></I>?<I>region specification
 193 </I>?  </DT>
 194 <DD>returns area of given classes within given region. </DD>
 195 </DL>
 196 <P>
 197  Region specification
 198 defaults to whole file. Other possible formats are:
 199 <DL>
 200
 201 <DT><B>-box<I> x1 y1 x2 y2 </I></B>
 202 </DT>
 203 <DD>- within given rectangular area </DD>
 204
 205 <DT><B>-polygon<I> x y x y ... </I></B>  </DT>
 206 <DD>- within polygon, given
 207 by set of coordinate pairs </DD>
 208
 209 <DT><B>-radius<I> distance x y ... </I></B>  </DT>
 210 <DD>within given distance
 211 of any of given points. </DD>
 212
 213 <DT><B>-mask<I> rasterObject list </I></B>  </DT>
 214 <DD>in areas where value of
 215 another rasterObject is in given list. </DD>
 216 </DL>
 217 <P>
 218
 219 <DL>
 220
 221 <DT><I>rasterName <B>delete </B></I>  </DT>
 222 <DD>- destroys raster
 223 object. If raster was in readwrite mode, all unsaved changes are lost. </DD>
 224
 225 <DT><I>rasterName
 226 <B>extents<I> value </I></B></I>  </DT>
 227 <DD>- returns list of four coordinates, within those all values
 228 of given class are contained. </DD>
 229
 230 <DT><I>rasterName <B>filename </B></I>  </DT>
 231 <DD>- returns name of file,
 232 corresponding to this raster object. </DD>
 233
 234 <DT><I>rasterName <B>fill<I> value x y  </I></B></I>?<B>-stop </B>?<I>
 235 value </I>  </DT>
 236 <DD>- fills area, starting with given coordinates with value. By default,
 237 stops on encounter of any value other than in given point. If <B>-stop </B> option
 238 is specified, stops only when encountering given value. Returns list of
 239 coordinates, specifying actually affected region. </DD>
 240
 241 <DT><I>rasterName <B>frame<I> value
 242  x1 y1 x2 y2 </I></B></I> ?<B>-width<I> cells </I></B>?  </DT>
 243 <DD>- a rectangle with given value, not changing
 244 inside area. By default this rectangle is 1 cell wide. </DD>
 245
 246 <DT><I>rasterName <B>get<I> x
 247 y  </I></B></I>?<B>-base </B>?  </DT>
 248 <DD>Returns value of raster in given point. By default returns
 249 reclassed value, but if <B>-base </B> is specified, returns class of raster file.
 250 </DD>
 251
 252 <DT><I>rasterName <B>limits </B></I>  </DT>
 253 <DD>Returns list of four doubles, specifying physical
 254 limits of raster file, in order <I>XLeft </I>, <I>YBottom </I>, <I>XRight </I>, <I>YTop </I>. </DD>
 255
 256 <DT><I>rasterName
 257 <B>line<I> value x y x y ....  </I></B></I>?<B>-width <I>cells </I></B>?  </DT>
 258 <DD>draws a line with given value. By
 259 default one-cell wide. Returns boundaries of region affected. </DD>
 260
 261 <DT><I>rasterName
 262 <B>load </B></I>  </DT>
 263 <DD>Loads raster file into memory, changing it from readonly to readwrite
 264 mode, and enabling all editing operation. (<B>-new </B> option of <B>raster </B> command
 265 performs <B>load </B> implicitely).  </DD>
 266
 267 <DT><I>rasterName <B>max </B></I>  </DT>
 268 <DD>-returns maximal value of
 269 raster object. </DD>
 270
 271 <DT><I>rasterName <B>min </B></I>  </DT>
 272 <DD>- returns minimal value of raster object.
 273 </DD>
 274
 275 <DT><I>rasterName <B>offsite </B></I> ?<I>value </I>?  </DT>
 276 <DD>- returns offsite value for raster object,
 277 or modifies it. </DD>
 278
 279 <DT><I>rasterName <B>polygon<I> value x y x y ... </I></B></I>  </DT>
 280 <DD>- fills given polygon
 281 of given value. Returns boundaries of region affected. </DD>
 282
 283 <DT><I>rasterName <B>put<I> value
 284 x y </I></B></I>  </DT>
 285 <DD>Changes value of individual cell. Returns nothing. </DD>
 286
 287 <DT><I>rasterName <B>reclass
 288 </B></I> ?<I>option </I>? ?<I>arg </I>?  </DT>
 289 <DD>- manipulates reclass table. Without any options, returns
 290 reclass table as Tcl list. </DD>
 291
 292 <DT><I>rasterName <B>reclass -statements </B></I>  </DT>
 293 <DD>option returns
 294 reclass table in form of reclass statements. (see <B> RECLASS SYNTAX </B> below).
 295 </DD>
 296
 297 <DT><I>rasterName <B>reclass -table<I> list </I></B></I>  </DT>
 298 <DD>modifies current reclass using given Tcl
 299 list. Values for classes given in this list would be changed as specified,
 300 all other remains unchanged. </DD>
 301
 302 <DT><I>rasterName <B>reclass <I>statements </I></B></I>  </DT>
 303 <DD>modifies reclass
 304 using specified reclass statements. As <B>-table </B> options, applies statements
 305 to base classes and leaves all nonspecified classes as is. </DD>
 306
 307 <DT><I>rasterName <B>reclass
 308 -clear </B></I>  </DT>
 309 <DD>clears all changes in reclass table and makes reclassed classes
 310 equial to base classes. </DD>
 311
 312 <DT><I>rasterName <B>row<I> y </I></B></I>  </DT>
 313 <DD>return cell number, correspondign
 314 to given Y coordinate. Raises error, if coodinnate is outside file limits.
 315 </DD>
 316
 317 <DT><I>rasterName <B>save </B></I> ?<I>options </I>?  </DT>
 318 <DD>- saves raster file. By default, if raster
 319 is in readwrite mode, saves changes to current filename. </DD>
 320
 321 <DT><I>rasterName <B>save
 322 -as<I> filename </I></B></I>  </DT>
 323 <DD>- saves raster, open for editing into other file, and makes
 324 this file current file of this raster object. </DD>
 325
 326 <DT><B>-backup </B>   </DT>
 327 <DD>option can be specified
 328 for both <B>save </B> and <B>save -as  </B>commands. It makes raster object to keep old
 329 version of file with suffix <I>.bak </I> appended to name. </DD>
 330
 331 <DT><I>rasterName <B>save -to<I> filename
 332 </I></B></I> ?<B>-8bit </B>?  </DT>
 333 <DD>allows to write raster object into raster file. Reclass table
 334 is applied to this operation, so new file would have base classes like
 335 classes of raster object, rather than classes of its base file. </DD>
 336 </DL>
 337 <P>
 338  If <B>-8bit
 339 </B> switch is specified, resulting raster will be forced to 8-bit by discarding
 340 high-order byte, even if max value or offsite are outside 0-255 range. (in
 341 latter case offsite would be set to 65535).
 342 <DL>
 343
 344 <DT><I>rasterName <B>shift <I> dx dy </I></B></I>  </DT>
 345 <DD>changes
 346 origin of cell (row/column) numbers. This is required for certain command
 347 of DOS version of EPPL7, although fGIS always uses map (alternative) coordinates)
 348 </DD>
 349
 350 <DT><I>rasterName <B>transect </B></I> ?<B>-count<I> varname </I></B>? <I>x y x y ... </I>  </DT>
 351 <DD>by default, return list
 352 consisting of pairs {value width} along the given line. If <B>-count </B> is specified,
 353 fills dynamic array <I>varname </I>, indexed by classes, by total widthes of
 354 given value along this line. </DD>
 355
 356 <DT><I>rasterName <B>unused </B></I>  </DT>
 357 <DD>returns value which is
 358 never encountered in this raster. </DD>
 359
 360 <DT><I>rasterName <B>unit </B></I> ?<I>new-unit </I>?  </DT>
 361 <DD>- returns
 362 (or changes) area unit of this raster Unit can be one of following: <B>undefined
 363 </B>,<B>ft </B>.<B>m </B>,<B>km </B>,<B>mile </B>,<B>ha </B>,<B>acre </B>. All subsequent count operations would return
 364 result in given units. <B>Note: </B> map coordinates are always in meters. </DD>
 365
 366 <DT><I>rasterName
 367 <B>xleft </B></I> ?<I>new value </I>?  </DT>
 368 <DD>- returns (or modifies) left boundary coordinate.<B>Note:
 369 </B> it simply modifies value, without appropriate changes in other limits
 370 or cell area value.  </DD>
 371
 372 <DT><I>rasterName <B>xright </B></I> ?<I>new value </I>?  </DT>
 373 <DD>- returns (or modifies)
 374 right boundary coordinate.  </DD>
 375
 376 <DT><I>rasterName <B>ybottom </B></I> ?<I>new value </I>?  </DT>
 377 <DD>- returns
 378 (or modifies) bottom boundary coordinate.  </DD>
 379
 380 <DT><I>rasterName <B>ytop </B></I> ?<I>new value
 381 </I>?  </DT>
 382 <DD>- returns (or modifies) left boundary coordinate.  </DD>
 383 </DL>
 384
 385 <H2><A NAME="sect5" HREF="#toc5">RECLASS SYNTAX </A></H2>
 386 <P>
 387  Syntax
 388 of reclass syntax is inherited from EPPL7. General form of reclass statement
 389 is line, terminated by newline (<B>Note: </B> trailing newline is obligatory),
 390 which consist of new value and list of old (base) values. New value separated
 391 from list by equal sign. List of old values can contain individual values
 392 and ranges, which are two values, separated by colon. <P>
 393
 394 <DL>
 395
 396 <DT>Example  </DT>
 397 <DD>1=1:10
 398 20 </DD>
 399 </DL>
 400 <P>
 401 means, that all values from one to ten and value 20 should be reclassed
 402 into 1. <P>
 403  Set of statements can contain arbitrary number of lines, same
 404 value can occur on left side of several lines. If some value occur on right
 405 side more than once, last occurence have precedence. <P>
 406
 407 <HR><P>
 408 <A NAME="toc"><B>Table of Contents</B></A><P>
 409 <UL>
 410 <LI><A NAME="toc0" HREF="#sect0">NAME</A></LI>
 411 <LI><A NAME="toc1" HREF="#sect1">SYNOPSIS</A></LI>
 412 <LI><A NAME="toc2" HREF="#sect2">DESCRIPTION</A></LI>
 413 <LI><A NAME="toc3" HREF="#sect3">OPTIONS</A></LI>
 414 <LI><A NAME="toc4" HREF="#sect4">OBJECT COMMAND</A></LI>
 415 <LI><A NAME="toc5" HREF="#sect5">RECLASS SYNTAX</A></LI>
 416 </UL>
 417 </BODY></HTML>