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 -->
6 <TITLE>raster(n) manual page</TITLE>
9 <A HREF="#toc">Table of Contents</A><P>
12 <H2><A NAME="sect0" HREF="#toc0">NAME </A></H2>
13 raster - Create and manipulate raster object <P>
15 <H2><A NAME="sect1" HREF="#toc1">SYNOPSIS </A></H2>
17 <I>filename </I></B> ?<I>options </I>? <P>
19 <H2><A NAME="sect2" HREF="#toc2">DESCRIPTION </A></H2>
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.
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>
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>
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,
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.
64 <H2><A NAME="sect3" HREF="#toc3">OPTIONS </A></H2>
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>
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>
79 <DT><B>-new </B> </DT>
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>
86 <DT><B>-like<I> rasterObject </I></B> </DT>
88 all important properties should be copied from existing raster object.
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>
95 <DT><B>-height<I>integer </I></B> </DT>
96 <DD>- specifies how many cells
97 should be in each column. </DD>
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>
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>
111 <DT><B>-limits<I>{x1 y1 x2
113 <DD>- Allows to specify list of four double values, determinig map coordinates
116 <DT><B>-cell<I> value </I></B> - specifies size of cell. In conjunction with <B>-limits
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>
123 <H2><A NAME="sect4" HREF="#toc4">OBJECT COMMAND </A></H2>
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.
137 <DT><I>rasterName<B> bpp </B></I> - returns size of data in this raster file </DT>
139 and 16 for 16 bit rasters). </DD>
141 <DT><I>rasterName<B> cache </B></I>?<I>new size </I>? </DT>
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>
147 <DT><I>rasterName <B>cell </B></I> ?<B>-area </B>?
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>
153 <DT><I>rasterName <B>celllimit </B></I> </DT>
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>
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>
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>
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.
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>
182 <DT><I>rasterName <B>count
183 </B></I> ?<B>options </B>? </DT>
184 <DD>- performs various area-calculating operation General formats
187 <DT><I>rasterName <B>count </B></I> ?<B>-- </B>? <I> varname </I>?<I>region specification </I>? </DT>
189 dynamic array <I>varname </I> indexed by raster classes by areas of these classes
190 in given region. </DD>
192 <DT><I>rasterName <B>count -classes <I>list </I></B></I>?<I>region specification
194 <DD>returns area of given classes within given region. </DD>
198 defaults to whole file. Other possible formats are:
201 <DT><B>-box<I> x1 y1 x2 y2 </I></B>
203 <DD>- within given rectangular area </DD>
205 <DT><B>-polygon<I> x y x y ... </I></B> </DT>
206 <DD>- within polygon, given
207 by set of coordinate pairs </DD>
209 <DT><B>-radius<I> distance x y ... </I></B> </DT>
210 <DD>within given distance
211 of any of given points. </DD>
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>
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>
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>
230 <DT><I>rasterName <B>filename </B></I> </DT>
231 <DD>- returns name of file,
232 corresponding to this raster object. </DD>
234 <DT><I>rasterName <B>fill<I> value x y </I></B></I>?<B>-stop </B>?<I>
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>
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>
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.
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>
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>
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>
267 <DT><I>rasterName <B>max </B></I> </DT>
268 <DD>-returns maximal value of
271 <DT><I>rasterName <B>min </B></I> </DT>
272 <DD>- returns minimal value of raster object.
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>
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>
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>
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>
292 <DT><I>rasterName <B>reclass -statements </B></I> </DT>
294 reclass table in form of reclass statements. (see <B> RECLASS SYNTAX </B> below).
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>
302 <DT><I>rasterName <B>reclass <I>statements </I></B></I> </DT>
304 using specified reclass statements. As <B>-table </B> options, applies statements
305 to base classes and leaves all nonspecified classes as is. </DD>
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>
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.
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>
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>
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>
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>
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).
344 <DT><I>rasterName <B>shift <I> dx dy </I></B></I> </DT>
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)
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>
356 <DT><I>rasterName <B>unused </B></I> </DT>
357 <DD>returns value which is
358 never encountered in this raster. </DD>
360 <DT><I>rasterName <B>unit </B></I> ?<I>new-unit </I>? </DT>
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>
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>
372 <DT><I>rasterName <B>xright </B></I> ?<I>new value </I>? </DT>
373 <DD>- returns (or modifies)
374 right boundary coordinate. </DD>
376 <DT><I>rasterName <B>ybottom </B></I> ?<I>new value </I>? </DT>
378 (or modifies) bottom boundary coordinate. </DD>
380 <DT><I>rasterName <B>ytop </B></I> ?<I>new value
382 <DD>- returns (or modifies) left boundary coordinate. </DD>
385 <H2><A NAME="sect5" HREF="#toc5">RECLASS SYNTAX </A></H2>
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>
401 means, that all values from one to ten and value 20 should be reclassed
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>
408 <A NAME="toc"><B>Table of Contents</B></A><P>
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>