| colouredit | Edits the colour table associated with a spatial object. Can use either preset or user-defined colour rules. |
| combine | Combines two spatial objects to form a new spatial object. |
| contour | Creates a contour map of a raster surface. |
| datetime | Retrieves the current date or time. |
| density | Creates a density surface from a set of point values. |
| draw | Creates a graphics file representing spatial objects. |
| echo | Displays text on screen or writes it to a file. |
| edit | Adds a metadata item to a spatial object (raster or vector map). |
| fractal | Fills the given raster with a fractal surface. |
| freqdist | Calculates a frequency distribution of a raster. |
| info | Extracts a metadata item from a spatial object (raster or vector map). |
| joinlines | Joins any line objects in the given vector map. |
| new | Creates a new spatial object (raster or vector map). |
| newraster | Creates a new raster map with the given bounds and metadata. |
| newvector | Creates a new vector map with the given bounds and metadata. |
| open | Opens a file representing a spatial object. |
| peakclass | Identifies peaks and summits from a DEM. |
| rcolourat | Extracts a colour component from a raster map using row and column coordinates. |
| rectify | Produces a rectified raster map from a set of control points. |
| removepits | Removes pits from a DEM. Creates a new pitless surface based on the given input surface. |
| removevoids | Removes voids from a raster by interpolating neighbours. |
| reproject | Reprojects a spatial object into a new coordinate system. |
| rvalueat | Extracts or assigns a single attribute associated with a raster map using row and column coordinates. |
| save | Saves a spatial object as a file. |
| simplify | Simplifies any line or area objects in the given vector map. |
| surfnetwork | Calculates the metric surface network from a DEM and surface feature map. |
| surfparam | Calculates a raster map of surface parameter values such as slope or aspect. |
| tocentroids | Finds centroids of any polygons in the given vector map. |
| toraster | Converts a TIN or vector map into a raster map. |
| triangulate | Creates a TIN from a raster surface or a Delaunay triangulation of points in a vector map. |
| valueat | Extracts or sets a single attribute associated with a spatial object (raster or vector map). |
| vectorstyle | Sets the vector appearance when drawn in a graphics file. |
| version | Identifies or queries the LandScript version to be used when interpreting this script. |
Does not return a value.
Usage: colouredit (<spatial_object>spObj, [<string>type], [<string>rules]);
where
All preset colour tables are scaled between the minimum and maximum values of the spatial object with which it is associated unless the rules parameter is provided (see below). If the type is set to 'raw', the object associated with the colour table is assumed to contain raw 32-bit colour values.
If type is set to one of the preset colour tables, rules can optionally provide minimum and maximum values between which the colour table is scaled. This should be provided as a whitespace separated pair of values.
If type is set to 'file', 'rules' or 'addRule', user-defined colour rules should be provided. They should either be stored in a standard '.ctb' (file) colourtable file, or provided as a single string of comma separated rules (rules and addRule). If type is set to 'file' or 'rules' the new rules replace any that might exist in the colour table. If it is set to 'addRule', the given rules are added to any which exist in the colour table. Each rule consists of a value colour sequence, where value represents the attribute with which to associate a colour and colour is either single greyscale number between 0-255, or an rgb triplet or and rgba quad. An optional (D) value can also be provided to indicate discrete colour rule. If (D) not provided colour rules are assumed to be continuous interpolations.
Returns a value of type <spatial_object>.
Usage: combine (<spatial_object>first, <spatial_object>second, [<string>type], [<string>rule], [<boolean>replaceNull]);
where
The type of combination will depend on the types of spatial objects provided and the rule parameter. If two raster maps are provided, the combination rule determines whether the attributes of the first, second or average of the two are used to create the attributes of the combined raster. In the case of raster cells with a null value, this rule can be superceded if replaceNull is true. For two intersecting vector maps rule determines if the intersection is based on the bounding rectangle of each vector ('map'), or the intersection of any area objects within each map ('object)'.
If the two supplied spatial objects are of different types, the type of combination is determined by the order of objects provided to the command. If 'first' is a raster map, it will be 'cookie cut' according to the objects or bounding rectangle of the vector map, again depending on the supplied rule. If 'first' is a vector map containing points, a new attribute will be added to the vector map's attribute table that will be contain the raster at each point location.
Returns a value of type <vector_map>.
Usage: contour (<raster_map>surface, <number>min, <number>interval, [<number>gridWidth]);
where
Returns a value of type <string>.
Usage: datetime ([<string>format]);
where
Allows the current date and/or time to be retrieved. If the format is set to 'full', text representing the current date and time is returned. If 'date' or 'time' is requested, text representing the current date or current time is returned. All of these can be useful for adding metadata descriptions to newly created objects. The default value of 'milliseconds' returns a number representing the number of milliseconds that have elapsed since some arbitrary start time. This can be useful for benchmarking or providing real-time information on how long a script has been running for.
Returns a value of type <raster_map>.
Usage: density (<vector_map>vector, <number>windowSize, <number>xRes, [<number>yRes]);
where
Does not return a value.
Usage: draw (<string>fileName, [<raster_map>raster1], [<raster_map>raster2], [<vector_map>vector1], [<vector_map>vector2], [<string>type], [<number>blendWeight]);
where
This command can be used for more sophisticated graphical output from a script. For simple display of a single raster or vector map, consider using save() instead, selecting 'image' as the output type.
The type options 'hueInt' (hue-intensity image), 'hueSat' (hue-saturation image), 'blend' (blended image) and 'add' (image addition) require both a primary and secondary raster to be supplied. The type 'relief will use the shaded relief of the primary raster and the colours of the secondary raster is it is provided. If 'blend' is requested, the optional parameter blendWeight can be used to determine the weighting given to the primary and secondary rasters.
Does not return a value.
Usage: echo ([<string>text], [<string>fileName]);
where
The text to display can be a combination of literal strings enclosed in "quotes", variables and expressions. Can also include spectial control characters '\n' to indicate a new line and '\t' to indicate a tab stop. Literal text is separated from variables and expressions using the & operator. For examplemapNum = 5;
echo("Map number "&mapNum&" contains "&240*240&" pixels.");
would display the following output:Map number 5 contains 57600 pixels.
If the optional fileName parameter is given, the text is written to the given file instead.
Does not return a value.
Usage: edit (<spatial_object>spObj, <string>item, <string>value);
where
Metadata items can be provided as strings or numeric values. In the case of raster maps, if any of the bounding values or resolution are changed, the change must not affect the number of rows or columns in the raster. Note that changing the bounding values (N, S, E, W) of a map will not cookie-cut it. To subset a map, create a new empty object (e.g. newraster or newvector) then intersect it with the map using combine.
For valid values of 'type', 'projection' and 'ellipsoid', see newRaster() or newVector().
The value associated with the 'attributes' type should be an .atr file containing an attribute table or 'noTable' if an object should not have an attribute table. If an attribute table exists, the active attribute can be set by setting attCol to a number representing the column of the active attribute.
The lighting parameters sunElev, sunAzim determine sun direction when calculating shaded relief and should be expressed in degrees. pShade and aBias should be percentages and represent the proportion of greyscale shading and the aspect bias respectively when calculating shaded relief. vExag determines the vertical exaggeration used when calculating shaded relief. Finally, the light parameters shine, ambient, diffuse, and specular are all expressed as percentages and are used when calculating shaded relief as a surface parameter (e.g. with the command surfparam())
Does not return a value.
Usage: fractal (<raster_map>raster, [<number>dimension]);
where
Does not return a value.
Usage: freqdist (<raster_map>raster, <string>fileName, [<number>min], [<number>binWidth], [<string>ignoreVals], [<boolean>calcHammock]);
where
The raster's frequency distribution is calculated in classes ranging from its minimum value to maximum values in widths defined by the binWidth parameter. The ignoreVals parameter can be used to exclude certain values from contributing to the distribution, for example sea areas with value of 0. If more than one value is to be ignored, a string of space separated values should be provided.
If calcHammock is true, the frequency distribution of the modulus of raster values is found instead. When generating a hammock distribution, the modulus is taken from the binWidth parameter. For example, a binWidth of 10 would find the distribution of raster value remainders after dividing each cell by 10. This allows a comparison of those values ending in 0 with those ending in digits 1-9 and can be useful for detecting contour and rounding artifacts in interpolated DEMs.
In all cases a text file is created with one category per line consisting of a comma-separated lower bin value and frequency.
Returns a value of type <string>.
Usage: info (<spatial_object>spObj, <string>item);
where
The result of calling this command can be either text or a number depending on the type of metadata selected. Statistical information that can be extracted from raster maps includes number of non-null cells (numVals), sum of all cells (sum), measures of average - mean, median, mode, and frequency of modal value (modef); measures of dispersion - stdev, skew and kurtosis, percentileN (where N is any number between 0-100); measures of spatial autocorrelation (moran) and fractal dimension (fracD).
Returns a value of type <vector_map>.
Usage: joinlines (<vector_map>vector);
where
The result of this operation is a new vector map identical to the original except that any linear features will be joined as a single line. If the original lines have different attributes, the new joined line will take the attribute of the first one to be joined. Uses for this operation include the defragmenting a GPS track with patchy signal, the joining of a multi-session line digitization, the rejoining of lines truncated during vector map tiling.
Returns a value of type <spatial_object>.
Usage: new (<spatial_object>spObj, [<boolean>copyContents]);
where
The result of this command, which is always a spatial object of some kind, is normally placed in a variable.
For example,myRaster = new(existingRaster);
will create a new empty raster map called myRaster that contains the same metadata as those in existingRaster. myRaster = new(existingRaster,"true");
will create a duplicate of existingRaster including data and metadata.
Returns a value of type <raster_map>.
Usage: newraster (<number>xOrigin, <number>yOrigin, <number>xRes, <number>yRes, <number>numRows, <number>numCols, [<string>title], [<string>notes], [<string>projection], [<string>ellipsoid], [<string>type]);
where
The result of this command, which is always a raster map, is normally placed in a variable. Each new declaration must include at least enough metadata to define the origin and dimensions of the new raster map to be created. The origin is defined relative to the bottom left corner, and the number of rows/columns along with the resolution in the x and y directions implicitly define the top-right corner. These bounding values should represent the outer edges of the corner cells in the raster map.
For example,myRaster = newraster(100,100, 50, 50, 800,1000);
will create a new empty raster with a bottom left corner at (100,100) and top right corner at (50100,40100). Other metadata can be optionally specified. For example,myRaster = newraster(100,100, 50, 50, 800,1000,"My title", "Raster created by landscript command","OSGB","Airy 1830","Elevation");
Returns a value of type <vector_map>.
Usage: newvector (<number>west, <number>south, <number>east, <number>north, [<string>title], [<string>notes], [<string>projection], [<string>ellipsoid]);
where
The result of this command, which is always a vector map, is normally placed in a variable. Each new declaration must include at least enough metadata to define the bottom-left and top-right of the map.
For example,myVectorMap = newvector(302100,450000, 303100, 451000);
will create a new empty vector map with a bottom left corner at (302100,450000) and top right corner at (303100,451000). Other metadata can be optionally specified. For example,myVectorMap = new(302100,450000, 303100, 451000,"My title", "Vector map created by landscript command","OSGB","Airy 1830");.
Returns a value of type <spatial_object>.
Usage: open (<string>file, [<string>type]);
where
Returns a value of type <raster_map>.
Usage: peakclass (<raster_map>dem, <number>minDrop, [<number>minElev], [<raster_map>fuzzyPeakRaster], [<vector_map>summitNetwork], [<raster_map>hierarchyRaster]);
where
Uses 'relative drop' to identify summits and their catchments from the given DEM. The minDrop parameter sets the minimum vertical drop required for a path from a summit to a higher neighbour. The larger the value the fewer the summits, but the larger in scale. If minElev is also defined, an additional constraint can be applied to summit definition. Only locations with at least this height will be considered as candidate summits. In all cases, a raster containing summit points and their contributing areas is generated. Additionally, a number of optional output maps can also be generated. If a fuzzyPeakRaster is given, this will be filled with values indicating peak membership ranging from 1 at the summit point to 0 at the boundary of its contributing area. If a summitNetwork vector map is given, this will be filled with a set of points representing summits, their passes and connecting topological ridge lines. If a hierarchyRaster is supplied, this will be populated with each peak's nested hierarchy value.
Returns a value of type <number>.
Usage: rcolourat (<raster_map>raster, <number>row, <number>col, <string>component);
where
The raster's row and column origin is assumed to be at the top left. Note also that the order of coordinates is row followed by col. The red, green, blue or alpha component is scaled between 0 and 255. If the query location is outside the raster's bounds, a warning message is reported and 0 is returned.
See also rgb(), red(), green() and blue() that can convert to and from colour integers and red, green and blue values. These functions can be used in local map algebra operations and will be much quicker than rcolourat() for processing entire rasters.
Returns a value of type <raster_map>.
Usage: rectify (<raster_map>raster, <string>ctrlPoints, <string>order, <boolean>interpolate, <number>xRes, [<number>yRes], [<number>north], [<number>south], [<number>east], [<number>west]);
where
Returns a value of type <raster_map>.
Usage: removepits (<raster_map>dem, [<string>type]);
where
The most appropriate type of pit processing will depend on the application and nature of the DEM being processed. Infilling is best suited to the removal of small isolated pits in noisy data. It has the advantage of being quick to compute. Channelling outflow from pits is better suited to hydrological applications that require all non-edge points to flow off the DEM. Channelling is not suited to surfaces with large or deep pits.
The changed elevation values, whether through infilling or channelling, can be found by taking the difference between the original surface and the one returned by this command.
Returns a value of type <raster_map>.
Usage: removevoids (<raster_map>raster);
where
Returns a value of type <spatial_object>.
Usage: reproject (<spatial_object>spObj, <string>type, [<boolean>interpolate], [<number>xRes], [<number>yRes], [<number>north], [<number>south], [<number>east], [<number>west]);
where
Returns a value of type <string>.
Usage: rvalueat (<raster_map>raster, <number>row, <number>col, [<number>att]);
where
The raster's row and column origin is assumed to be at the top left. Note also that the order of coordinates is row followed by col, in contrast to valueat() which requires coordinates in easting,northing order.
The value to be associated with the given location can be assigned if the att parameter is set. If att not set this command will perform a raster query, the result of which can be either text or a number depending on the attribute selected. If the raster map has an attribute table associated with it, the active attribute will determine which column from the table is used to return a value. If the object has no attribute table, the numeric attribute is returned. If the query location is outside the raster's bounds, a warning message is reported and a null value is returned.
Does not return a value.
Usage: save (<spatial_object>spObj, <string>file, [<string>type], [<string>byteOrder], [<number>wordSize]);
where
Returns a value of type <vector_map>.
Usage: simplify (<vector_map>vector, <number>distance);
where
The result of this operation is a new vector map identical to the original except that any linear features or area boundaries will be simplified. Uses the Douglas-Peucker line simplification algorithm.
Returns a value of type <vector_map>.
Usage: surfnetwork (<raster_map>surf, <raster_map>features);
where
A surface feature network consists of points representing pits, passes and peaks joined by lines repsenting channels (from pits to passes) and ridges (from passes to peaks). Input must consist of a Digital Elevation Model and a raster representing the (possibly fragmented) surface features.
Returns a value of type <raster_map>.
Usage: surfparam (<raster_map>surf, <string>type, [<number>wSize], [<number>decay], [<number>slopetol], [<number>curvetol], [<string>scaleSummary]);
where
The type of surface measurement is determined by the type parameter at the scale determined by size. The decay parameter determines the weighting given to neighbouring cells as a function of distance from the centre of the cell to measure. A value of 0 indicates equal weight to all cells, 1 a linear distance decay, 2 a squared distance decay etc. Most parameter types should be self-explanatory. The values 'coeffA', 'coeffB' etc. allow the quadratic coefficients a-f of the best fit surface z = ax2 + by2 +cxy + dx +ey + f to be retrieved.
Parameters can be calculated over a range of window sizes and summarised by including a non-null value for scaleSummary. In which case, wSize, which must be at least 5, represents the largest window size, and the smallest window size is always 3x3.
Returns a value of type <vector_map>.
Usage: tocentroids (<vector_map>vector);
where
The result of this operation is a new vector map containing only points representing the centroids of each polygon in the original vector map. The centroids share the same attributes and colours as the polygons they represent.
Returns a value of type <raster_map>.
Usage: toraster (<vector_map>vector, <number>xRes, [<number>yRes]);
where
Returns a value of type <vector_map>.
Usage: triangulate (<spatial_object>spObj, [<number>numSamples], [<number>rmse], [<number>maxError], [<raster_map>errorSurface]);
where
Returns a value of type <string>.
Usage: valueat (<spatial_object>spObj, <number>easting, <number>northing, [<number>att]);
where
The origin of the spatial object is assumed to be at the bottom left, and the coordinate system used is defined by the spatial object itself. Both raster and vector maps can be queried or set using this command, but to query or assign raster map attributes using row and column coordinates, use rvalueat() instead.
The value to be associated with the given location can be assigned if the att parameter is set. If it is not, the result of calling this command can be either text or a number depending on the attribute selected. If the spatial object has an attribute table associated with it, the active attribute will determine which column from the table is used to return a value. If the object has no attribute table, the numeric attribute is returned. If the query location is outside the spatial object's bounds, a warning message is reported and null is returned.
Does not return a value.
Usage: vectorstyle (<string>action, <string>value);
where
Allows the vector appearance to be changed when creating graphics files with the draw() or save() commands. The options available correspond to those available in LandSerf's 'Vector Appearance' window. Alternatively, settings can be saved or loaded with the save and open options.
The size of point and line rendering can be set with linewidth and pointsize. In both cases, the value parameter should be a number of pixels. This need not be a whole number, for example a linewidth of 0.3 gives faint lines useful for contour rendering or polygon boundaries.
Point and line style can also be controlled with the surroundpoint and surroundline options, which should be set to true or false. If true, points or lines are drawn with a surrounding line. This can be useful for highlighting underlying raster objects without obscuring them.
Polygon appearance can be controlled with the polygonopacity option that should have a value ranging from 0-1. Non-opaque polygons are useful for showing overlapping areal features or for combining with an underlying raster. Polygon boundary appearance is controlled with the boundarycolour option that takes a colour value defined by a series of space-separated colour values scaled between 0-255. Grey levels are specified with a single number; grey levels with transparency by a pair of numbers; red-green-blue values by a triplet and red-green-blue-transparency with a set of four numbers. Polygon boundaries can be turned on and off by setting showboundary to true or false.
Point label colours are set with labelbackground and labelforeground each taking a colour value as described above. Labels can be turned on or off with showLabels that should be set either to true or false. Label size is controlled with the labelsize option requiring a numeric value corresponding to the height in pixels of the label. Its position is controlled with labelposition which should have a value corresponding to one of eight compass directions (north, northeast, east etc.) or centre to centre the label on the point it represents.
The type of rendering can be set with render that can take the value speed for faster, low quality rendering or quality for higher quality anti-aliased rendering.
Returns a value of type <number>.
Usage: version ([<number>versionNum], [<boolean>showDetail]);
where
The LandScript version should be identified at the top of each script to ensure compatibility with future enhancements to the language. If a value of less than 0 is supplied, the current Landscript version is assumed and displayed. If a version more recent (larger) than the current version is supplied, a warning message is displayed.
This command will return the version of LandScript that will be used to interpret the script, which was either set by this command, or is the current version if out of range or not supplied. The result can be stored in a variable and used to perform sections of script conditionally dependent on the version number.
If showDetail is true more detailed information is displayed including the version of Java used to run LandScript.