Skip to content

Latest commit

 

History

History
562 lines (369 loc) · 14.9 KB

Commands.md

File metadata and controls

562 lines (369 loc) · 14.9 KB
Raw

Cave Spy Scriping Command Reference

A command reference for the scripting language

(Add <n1 : number> <n2 : number>)

returns n1 + n2

(And <condition 1 : boolean> <condition 2 : boolean>)

returns true if condition 1 and 2 are both true

(Assert <condition : boolean>)

throws an exception if the condition is false

(ChangeExtension <fileName : string> <extension : string>)

changes the extension of the file name passed into to the one that is specified Example

Parameter Type Description
file name string The file name to change the extension on
extension string The new extension. It should include the . on the front
return string The file name with the new extension

Example:

	(ChangeExtension (Get someVariable) ".bmp")

(DrawCaves <image> <caves>)

Draws the found caves into the given image.

Parameter Type Description
image Image The image to draw to
caves List<Cave> The list of caves generated by the find caves algorithm

(DrawClassification <image : Image> <map : Map> <classification: int>)

Colors all of the matching classification items to black.

Parameter Type Description
image Image The image to draw to
map Map The map to take the elevation data from
classification int The classification value to black out

Example:

(DrawClassification (Get map) 2i)

(DrawElevationColor <image : Image> <map : Map> <meters per cycle : double> <opacity : double>)

Draws the elevation in a cycling rainbow like set of colors. A full color cycle is determined by the "meters per cycle" parameter.

Parameter Type Description
image Image The image to draw to
map Map The map to take the elevation data from
meters per cycle double The number of meters of elevation gain between the same color being used over.
opacity double Range form (0-1) How see through the shading will be

Example:

	(DrawElevationColor (Get image) (Get map) 100d 1.0d)

(DrawHillsideShade <image : Image> <map : Map> <heading : double> <step: double> <intensity: double> <opacity : double>)

Draws hill shading on the given image at the given angle and intensity.

Parameter Type Description
image Image The image to draw the shading on to.
map Map The map that contains the elevation data
heading double The angle which the 'light' is coming from.
step double How far from the original pixel the change of elevation will be calculated from.
intensity double The contrast of the shading. The higher the value the more dramatically it'll shade.
opacity double Range form (0-1) How see through the shading will be

Example:

	(DrawHillsideShade (Get image) (Get map) 45d 3d 5d 1.0d)

(DrawIntArray <image: Image> <array : array of int> <color : string> <opacity : double>)

Draws an array of int intensities onto the specified image. It a linear scale from the dimest to the brightest. Is uses for now a green hue.

Parameter Type Description
image Image The image to draw to
array int[] The array of intensities
color string The color in hex for instance ff0000 is red 00ff00 is green 0000ff is blue.
opacity double The opacity of the drawing. 1.0 overwrites --> 0.5 mixes --> 0 draws nothing

Example:

	(DrawIntArray (Get image) (Get array) "00ff00" 0.5d)

(DrawLogIntArray <image: Image> <array : array of int> <color : string> <opacity : double>)

Draws an array of int intensities onto the specified image. It uses a logrithmic scale from the dimest to the brightest. Is uses for now a green hue.

Parameter Type Description
image Image The image to draw to
array int[] The array of intensities
color string The color in hex for instance ff0000 is red 00ff00 is green 0000ff is blue.
opacity double The opacity of the drawing. 1.0 overwrites --> 0.5 mixes --> 0 draws nothing

Example:

	(DrawIntArray (Get image) (Get array) "00ff00" 0.5d)

(DrawRealColor <image : Image> <map : Map> <opacity: double>)

-- not implemented --

(DrawSlopeColor <image : Image> <map: Map> <opacity: double>)

-- not implemented --

(Equals <a : any> <b: any>)

(FileExists <file name>)

Returns true if the file exists.

Parameter Type Description
file name string The path to the file to be tested
return boolean True when the file exists, false otherwise

(FillHoles <map : Map>)

Finds all of the holes in the map data (where no point defined an elevation) and fills them with the averages of the data on the edges.

Parameter Type Description
map Map The map that contains the data

Example:

	(FillHoles (Get map))

(FindCavesByFlood <map : Map> <depth : double>)

Marks the location of a depression as found on the map. This does it by flooding around each point. Any point that makes a flood plain of > 3 and < 1000 pixels is marked red. The method is most effective on barren terrain. In areas of dense trees the spaces between the trees tend to be marked instead of actual ground depressions.

Parameter Type Description
map Map The map that contains the elevation data that will be analyzed
depth double The amount in meters that the flood test will be performed.
return List<Caves> A list of all the locations of the depressions in the map

Example:

	(FindCavesByFlood (Get map) 1.0d)

(Get <variable name : string>)

Retrieves a previously saved object.

Parameter Type Description
name string or symbol The name of the variable to be retrieved
return any The value of the variable

Example:

	(Get image)
	(Get "image")

(GetArg <agument name : string> <default value : any>)

(GetEnvironment <variable name>)

(GetExtension <file name>)

(GreaterThan <n1 : number> <n2 : number>)

(GreaterThanEqual <n1: number> <n2: number>)

(If <condition> <True Clause> <False Clause>)

(LessThan <n1 : number> <n2: number>)

(LessThanEqual <n1 : number> <n2: number>)

(Loop <n: int> <item to execute: any> [<item to execute: any>...])

Repeats the execution of it's parameters n number of times

Parameter Type Description
n int The number of times to execute the parameters after this.
items any The items to be executed n times

Example

	(Loop 5i (MapGeometricMean (Get map) 5i))

(MakeImage <map: Map>)

Creates an Image object from the Map. This allows you call the various methods for drawing to the image.

Parameter Type Description
map Map The image will be templated off of the passed in map
return Image The created image

Example:

	(Set image (MakeImage (Get map)))

(MakeMap <cloud: Cloud> <width: int> [<included classifications>])

Creates a map object from a .las file.

Parameter Type Description
cloud Cloud The cloud object read in via the Read File command
width int The width in pixels of the map. The height will be calculated in proportion to the physical width as defined in the .las file header.
included classifications int Zero or more int fields that include the classifications to include. If no classifications are specified then all points are included.
return Map The map object to be returned

Classifications

Classification Value (bits 0:4) Meaning
0 Created, never classified
1 Unclassified
2 Ground
3 Low Vegetation
4 Medium Vegetation
5 High Vegetation
6 Building
7 Low Point (noise)
8 Model Key-point (mass point)
9 Water
10 Reserved for ASPRS Definition
11 Reserved for ASPRS Definition
12 Overlap Point
13-31 Reserved for ASPRS Definition

Example:

	(Set map (MakeMap( (Get cloud) 2000i 1i 2i)) # include unclassified and ground

(MapCalculateSlopeAngle <map : Map>)

Calculates the slope of a given space withing the map and returns an array grid of all the angles floored to the nearest integer.

Parameter Type Description
map Map The map to calculate the slope from
return int[] The angles rounded to the nearest degree

Example:

    (MapCalculateSlopes (Get map))

(MapDrainage <map : Map> <look distance: int>)

Maps the drainage into an int array. The Look distance is the number of pixels around a given point that the algorithm will look for the lowest spot. For barren ground this can be low and work well. For heavily tree'd maps a higher value here lets the drainage search betweeen the trees. It takes longer but give a better drainage map.

Parameter Type Description
map Map The map that contains the elevation data.
look distance int The distance in pixels that the algorithm will look for the next lowest spot.

Example:

(DrawArrayInt (Get image) (MapDrainage (Get map) "00FF00" 15i) 1.0d)

(MapGeometricMeanFilter <map: Map> <N: int>)

Performs a geometric mean filter to the map elevation data. It irreversibly changes the elevation data in the map object. The effect is to smooth the image. Particullarly high frequency data. This is nice for getting rid of noise in the data.

Parameter Type Description
map Map The map to apply the filter to
N int The size of the filter. The larger the size the more smoothing will happen, but the slower the algorithm will be. The value must be odd.

Example:

	(MapGeometricMeanFilter (Get map) 5i)

(Not <condition: boolean>)

(NotEquals <item1: any> <item2: any>)

(Or <condition 1: boolean> <condition 2: boolean>)

(ReadFile <file name>)

Reads an object into the system from the given file name.

Parameter Type Description
file name string The file to be read in. Supports .las and .map
returns Cloud or Map object The object being read in.

Example:

	(Set cloud (ReadFile "data.las"))
	(Set map (MakeMap (Get cloud) 3000i))

(SaveToFile <object: image or map> <file name : string>)

Saves the object to the specified file. Supports Image and Map objects. It can save out Images as either bitmaps ".bmp" and google files ".kml"

Parameter Type Description
object Image or Map The object to be saved.
file name string The file to be save. Supports .map, .bmp, .kml

Example:

	(SaveToFile( (Get image) "output.bmp")) # saves a bmp bitmap
	(SaveToFile( (Get image) "output.kml")) # saves a kml directory
	(SaveToFile( (Get map) "output.map")) # saves a Map object to disk

(Set <variable name: string> <value: any>)

Parameter Type Description
variable name symbol or string The name of the variable
value any The value to be saved to the variable

Example

	(Set image (MakeImage (Get cloud) 3000i))
	(Set "stuff" 1234d)

(Sub <n1 : number> <n2: number>)

(While <condition> [<item to execute>...])

Example Scripts

Simple processing script

(	
	
	(Set lasFile "c:\maps\templePeak2.las")
	(Set imageFile (ChangeExtension (Get lasFile) ".kml"))
	# read the las file
	(Set cloud (ReadFile (Get lasFile) "12T"))

	# map the las file to a regtangular grid
	(Set map (MakeMap (Get cloud) 2000i))

	# fix any holes in the map -- right now this isn't a good algorithm
	(FillHoles (Get map))
	#(MapGeometricMeanFilter (Get map) 7i)
	#(MapGeometricMeanFilter (Get map) 5i)

	# run the algorithm to find caves -- this also isn't very good especially in terrain with lots of trees
	#(Set caves (FindCavesByFlood (Get map) 0.3d)) # parameters <map> <minimum depth of the hole in meters>	

	# draw an image based on the map and cave analysis
	(Set image (MakeImage (Get map)))
	(DrawElevationColor (Get image) (Get map) 100d, 1.0d)	# parmaters <image> <map> <meter per color cycle> <opacity>
	(DrawIntArray (Get image) (MapDrainage (Get map) 20i) "00ff00" 1.0d)
	(DrawHillsideShade (Get image) (Get map) 45d 5d 0.7d, 0.3d) #parameters <image> <map> <angle of hillshade> <distance from point of interest> <intensity of shading> <opacity>
	#(DrawCaves (Get image) (Get caves))
	#(DrawClassification (Get image) (Get map) 13i)

	# save the image as defined by the output tag
	(SaveToFile (Get image) (Get imageFile))
)

More complex script

#  This is the default script for the CaveSpy
#  It takes three arguments --input <lasFileName> and --image-size <image width in pixels> --output <output file> [--default-zone <UTM zone of las>]
#  --input   :the name of the file that will be loaded
#  --image-size :width of the produced image size in pixels
#  --output  :the name of the output file.  The extension determines the type of file to be produced.  .bmp and .kml are supported
#  --default-zone  :Some of the .las files don't seem to include UTM zone information.  If not specify the correct zone with this parameter.  The default is value is 12T
#

(	
	# get the input filename
	(Set lasFile (GetArg "--input" "default.las"))	

	# check to make sure the extension is a las file
	(Assert (Equals (GetExtension (Get lasFile)) ".las"))

	# gets the width argument for the image
	(Set mapWidth (GetArg "--image-size" 2000i))	

	# read the las file
	(Set cloud (ReadFile (Get lasFile) (GetArg "--default-zone", "12T")))

	# map the las file to a regtangular grid
	(Set map (MakeMap (Get cloud) (Get mapWidth)))

	# fix any holes in the map -- right now this isn't a good algorithm
	(FillHoles (Get map))
	(MapGeometricMeanFilter (Get map) 5i)

	# run the algorithm to find caves -- this also isn't very good especially in terrain with lots of trees
	(Set caves (FindCavesByFlood (Get map) 2.0d)) # parameters <map> <minimum depth of the hole in meters>

	# draw an image based on the map and cave analysis
	(Set image (MakeImage (Get map)))
	(DrawElevationColor (Get image) (Get map) 450d, 1.0d)	# parmaters <image> <map> <meter per color cycle> <opacity>
	(DrawHillsideShade (Get image) (Get map) 45d 5d 0.7d, 0.5d) #parameters <image> <map> <angle of hillshade> <distance from point of interest> <intensity of shading> <opacity>
	(DrawCaves (Get image) (Get caves))	

	# save the image as defined by the output tag
	(SaveToFile (Get image) (GetArg "--output", "default.bmp"))
)