Table of Contents
raster - Create and manipulate raster object
raster
filename ?options ?
This command allows to create raster
objects. Raster objects are more low-level concept than fGIS layers . 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 offsite 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 reclass table .
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.
- -reclass statements
- -specifies reclass table for created raster
object. statements is string, containing set of reclass statements. See
RECLASS SYNTAX below for details
- -table list
- -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.
- -new
- - 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 -new is specified.
- -like rasterObject
- - specifies that
all important properties should be copied from existing raster object.
- -width integer
- - specifies how many cells should appear in each row. Cannot
be used together with -like
- -heightinteger
- - specifies how many cells
should be in each column.
- -offsiteinteger
- - 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.
- -8bit - 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.
- -limits{x1 y1 x2
y2}
- - Allows to specify list of four double values, determinig map coordinates
of file.
- -cell value - specifies size of cell. In conjunction with -limits
- it gives more convinient way to create new raster, becouse limits defines
area of interest and cell size - accuracy of map.
raster
command creates new Tcl command with same name as raster object, which
can be used to manipulate this object.
rasterName boxvalue x1 y1 x2 y2
- fills rectangular region with given value. Raster should be opened in
read-write mode (either by -new option of object command or by load 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.
- rasterName bpp - returns size of data in this raster file
- (8 for 8-bit
and 16 for 16 bit rasters).
- rasterName cache ?new size ?
- - 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 transect .
- rasterName cell ?-area ?
- - returns parameters of cell. By default, returns cell width in map coordinates,
which should be meters, and with -area flag returns cell area in current
units (see unit object command).
- rasterName celllimit
- - returns list
of four intergers, representig start and end numbers of cells in order
first column , last row , last column, first row . (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 limits object command.
- rasterName
classes value
- - returns list of base file classes which are mapped to
specified value of this raster object.
- rasterName circle value x y radius
?-cells ?
- - fills circulare region in read-write raster with given value.
If -cells ,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.
- rasterName col x
- - returns cell number corresponding
to given X coordinate. Returns error, if coordinate is out of file boundaries.
- rasterName comment ?string ?
- - returns (or modifies) comment, stored
in file header. Comment length is limited by 32 symbols.
- rasterName count
?options ?
- - performs various area-calculating operation General formats
folows:
- rasterName count ?-- ? varname ?region specification ?
- fills
dynamic array varname indexed by raster classes by areas of these classes
in given region.
- rasterName count -classes list ?region specification
?
- returns area of given classes within given region.
Region specification
defaults to whole file. Other possible formats are:
- -box x1 y1 x2 y2
- - within given rectangular area
- -polygon x y x y ...
- - within polygon, given
by set of coordinate pairs
- -radius distance x y ...
- within given distance
of any of given points.
- -mask rasterObject list
- in areas where value of
another rasterObject is in given list.
- rasterName delete
- - destroys raster
object. If raster was in readwrite mode, all unsaved changes are lost.
- rasterName
extents value
- - returns list of four coordinates, within those all values
of given class are contained.
- rasterName filename
- - returns name of file,
corresponding to this raster object.
- rasterName fill value x y ?-stop ?
value
- - fills area, starting with given coordinates with value. By default,
stops on encounter of any value other than in given point. If -stop option
is specified, stops only when encountering given value. Returns list of
coordinates, specifying actually affected region.
- rasterName frame value
x1 y1 x2 y2 ?-width cells ?
- - a rectangle with given value, not changing
inside area. By default this rectangle is 1 cell wide.
- rasterName get x
y ?-base ?
- Returns value of raster in given point. By default returns
reclassed value, but if -base is specified, returns class of raster file.
- rasterName limits
- Returns list of four doubles, specifying physical
limits of raster file, in order XLeft , YBottom , XRight , YTop .
- rasterName
line value x y x y .... ?-width cells ?
- draws a line with given value. By
default one-cell wide. Returns boundaries of region affected.
- rasterName
load
- Loads raster file into memory, changing it from readonly to readwrite
mode, and enabling all editing operation. (-new option of raster command
performs load implicitely).
- rasterName max
- -returns maximal value of
raster object.
- rasterName min
- - returns minimal value of raster object.
- rasterName offsite ?value ?
- - returns offsite value for raster object,
or modifies it.
- rasterName polygon value x y x y ...
- - fills given polygon
of given value. Returns boundaries of region affected.
- rasterName put value
x y
- Changes value of individual cell. Returns nothing.
- rasterName reclass
?option ? ?arg ?
- - manipulates reclass table. Without any options, returns
reclass table as Tcl list.
- rasterName reclass -statements
- option returns
reclass table in form of reclass statements. (see RECLASS SYNTAX below).
- rasterName reclass -table list
- modifies current reclass using given Tcl
list. Values for classes given in this list would be changed as specified,
all other remains unchanged.
- rasterName reclass statements
- modifies reclass
using specified reclass statements. As -table options, applies statements
to base classes and leaves all nonspecified classes as is.
- rasterName reclass
-clear
- clears all changes in reclass table and makes reclassed classes
equial to base classes.
- rasterName row y
- return cell number, correspondign
to given Y coordinate. Raises error, if coodinnate is outside file limits.
- rasterName save ?options ?
- - saves raster file. By default, if raster
is in readwrite mode, saves changes to current filename.
- rasterName save
-as filename
- - saves raster, open for editing into other file, and makes
this file current file of this raster object.
- -backup
- option can be specified
for both save and save -as commands. It makes raster object to keep old
version of file with suffix .bak appended to name.
- rasterName save -to filename
?-8bit ?
- 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 -8bit
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).
- rasterName shift dx dy
- 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)
- rasterName transect ?-count varname ? x y x y ...
- by default, return list
consisting of pairs {value width} along the given line. If -count is specified,
fills dynamic array varname , indexed by classes, by total widthes of
given value along this line.
- rasterName unused
- returns value which is
never encountered in this raster.
- rasterName unit ?new-unit ?
- - returns
(or changes) area unit of this raster Unit can be one of following: undefined
,ft .m ,km ,mile ,ha ,acre . All subsequent count operations would return
result in given units. Note: map coordinates are always in meters.
- rasterName
xleft ?new value ?
- - returns (or modifies) left boundary coordinate.Note:
it simply modifies value, without appropriate changes in other limits
or cell area value.
- rasterName xright ?new value ?
- - returns (or modifies)
right boundary coordinate.
- rasterName ybottom ?new value ?
- - returns
(or modifies) bottom boundary coordinate.
- rasterName ytop ?new value
?
- - returns (or modifies) left boundary coordinate.
Syntax
of reclass syntax is inherited from EPPL7. General form of reclass statement
is line, terminated by newline (Note: 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.
- Example
- 1=1:10
20
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.
Table of Contents
|