NAME

SYNOPSIS

DESCRIPTION

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.

OPTIONS

-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.

OBJECT COMMAND

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.

RECLASS SYNTAX

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

• NAME
• SYNOPSIS
• DESCRIPTION
• OPTIONS
• OBJECT COMMAND
• RECLASS SYNTAX