R I Geospatial Scripting - MicroImages, Inc. · 2016-06-20 · Geospatial Scripting page 3...

Geospatial Scripting

page 1

GeospatialScripting

with

TNTgis

Introduction toGEO

SCRIPTING


page 2

Before Getting Started

You can print or read this booklet in color from MicroImages’ web site. Theweb site is also your source for the newest tutorial booklets on other topics.You can download an installation guide, sample data, and the latest versionof TNTmips Free.

http://www.microimages.com

This booklet provides an overview of the ways in which geospatial scripts can beused in TNTgis. You can create and use scripts to query attributes of geospatiallayers, customize DataTips for layers and groups, create interactive tools forexploring and interpreting geospatial data, and implement custom processes.Sample scripts are presented to illustrate typical applications of each type ofgeospatial script.

Prerequisite Skills This booklet assumes that you have completed the exercisesin the tutorial booklets Getting Started with TNTmips, TNTedit, and TNTview,and Introduction to the Display Interface. Those exercises introduce essentialskills and basic techniques that are not covered again here. Please consult thosebooklets for any review you need.

Sample Data The exercises in this booklet use sample data that is distributedwith TNTgis. If you do not have access to a TNTgis DVD, you can download thedata from MicroImages’ web site. In particular, this booklet uses data in the SML

data collection and sample scripts that can be installed by following the instruc-tions on page 6.

More Documentation This booklet is intended only as an introduction togeospatial scripting in TNTgis. Consult the tutorial booklets entitled Buildingand Using Queries, Using CartoScripts, Using Geospatial Formulas, WritingScripts with SML, and Building Dialogs in SML for more information on writingand using geospatial scripts.

TNTmips® Pro and TNTmips Free TNTmips comes in three versions: TNTmipsPro (which requires a software license key), low-cost TNTmips Basic, and TNTmipsFree. TNTmips Basic and TNTmips Free provide nearly all the capabilities ofTNTmips Pro but limit the size of the geospatial objects and attribute tables thatcan be used in your project. TNTmips Basic and TNTmips Free allow you tocreate and use scripts in the Display process (database queries, style scripts,macroscripts, and others) and the Geoformula process, but only TNTmips Proallows you to create and run complex standalone geospatial scripts.

Randall B. Smith, Ph.D., 17 December 2015©MicroImages, Inc., 2008-2015


page 3

Introduction to Geospatial ScriptingTNTgis provides a comprehensive, integrated setof tools and processes that enable you to view, pro-cess, interpret, and publish almost any form ofgeospatial data. Because of the breadth and varietyof available TNTgis processes, many clients are ableto complete their geospatial projects using only thepredefined interactive tools and procedures. Forthose less common occasions that require a custom-ized approach or process, TNTgis also provides ageospatial scripting language called SML.

Geospatial scripts can be used for a variety of tasks.The task may be as simple as using a particular setof database attributes to select vector elements(points, lines, polygons, nodes) for display or pro-cessing. Or you may want to customize and enhancethe DataTips that provide automatic, context-sensi-tive attribute information for geospatial data in aView window. On the other hand, you can also useSML for complex tasks such as implementing a cus-tom process or automating a processing workflowthat takes the place of several separate predefinedTNTgis processes. Standalone processing scriptscan be fairly simple to write in many cases becauseSML includes functions and classes that provideaccess to many predefined TNTgis processes.

This booklet provides an overview of the differenttypes of script that can be used in TNTgis. It dis-cusses the scope of each type of script, the programinterface for script setup, and provides some ex-amples of script applications. Once you havecompleted this scripting overview, you should con-sult the tutorial entitled Writing Scripts with SMLfor an introduction to the syntax and programmingstructure of SML. You can also refer to the tutorialbooklets Building and Using Queries, UsingCartoScripts, and Using Geospatial Formulas formore detailed information about these particularscript types.

Pages 4-6 provide anoverview of the differenttypes of scripts that can beused in TNTgis and thelarge collection of TNTgissample scripts. A briefintroduction to the scripteditor is given on pages 7-8. Simple scripts to createcomputed fields in databasetables are covered onpages 9-11, followed by adiscussion of databasequeries and style scripts onpages 12-13. TheGeoFormula interface forcomputing virtual spatiallayers is discussed onpages 14-16. Pages 17-18introduce the use of DisplayControl scripts for creatingenhanced and complexDataTips. Standalonegeospatial process scriptsare covered on pages 19-24, including their use inTNTmips Job Processingand TNTscript. Use ofMacro and Tool Scripts ingeospatial Views isdiscussed on pages 25-29,followed by SML LayerScripts on page 30.Additional uses of DisplayControl Scripts aredescribed on page 31.


page 4

Geospatial Script OverviewDatabase Computed Field Script: Use simple scripts to create dynamically-updated database fields that can use and combine values in other fields in thesame or related tables. You can use mathematical expressions to create computednumeric fields or combine text in computed string fields.

Database Query: Use a database query to select elements in a geometric object(vector, CAD, shape, or TIN) on the basis of one or more attributes in the associ-ated database. Query selection can control the marking, display, editing, orprocessing of geometric elements.

Style Script: Use a style script to set up custom display styling for elements in ageometric object. A style script can set colors, enable drawing of polygon bordersand fills, and access patterns and styles in a style object.

CartoScript: A CartoScript is a form of style scriptthat uses specialized functions to create cartographicsymbolism for points and lines in geometric objects.

GeoFormula: Use the interactive GeoFormula dialog to cre-ate a virtual display layer or a saved raster object that is amathematical combination of selected spatial objects. AGeoFormula can utilize raw or contrast-enhanced values frominput raster objects and attribute values from elements in geo-metric objects.

Macro Script: Use a macro script to imple-ment custom commands that operate on thegeospatial data in a View window. A macroscript can change the view of the data, oper-ate on data in the View, or start an externalprogram and provide it with data from andabout the layers in the View. You can run amacro script from the View window using anicon button or from the Macros menu.

Display Control Script: Use a Display Control Script toautomatically modify the presentation of geospatial data in aView. For example, you can augment or replace the location-specific DataTip text that automatically pops in at the cursorlocation or replace the text entirely with a graphical presenta-tion of the same location-specific information.


page 5

Geospatial Script Overview (continued)

SML Layer Script: Use an SML Layer script to create a separatelayer in a spatial display view with the Add Script display option.You can use such a script to render a custom cartographic elementsuch as a magnetic declination symbol that can be used in a maplayout.

Tool Script: Use a toolscript to provide aunique interactivegraphic tool to selectdata in a view windowand apply custom pro-cessing. A tool scriptcan provide a point,line, or polyline/poly-gon tool to designatethe portion of the datato be processed. It can also provide a dialog window with controls for theprocess or to show the results of the processing. The tool script template pro-vides prototype functions that you can fill in to define the exact operations youneed. You can activate a tool script from the View window using an icon buttonor from the Tools menu.

Geospatial Process Script: Use the SML Editor in TNTmips Pro orTNTedit to create custom, standalone scripts to uniquely process your geospatialdata. Geospatial process scripts can access and create data in TNTgis ProjectFiles or in external file formats. You can use built-in functions and classes in ageospatial process script to automate a sequence of steps involving a series ofTNTgis processes or even external programs. You can also implement your owncustom geospatial processing algorithms to process raster or geometric dataobjects and their associated database information. Many geospatial functionsare provided for processing raster and geometric objects. A set of image pipelineclasses are provided for fast and efficient processing of images, and pipelinescripts can be constructed using the Script Builder, a graphical design interface(see the Technical Guide entitled Script Builder Overview).

Geospatial scripts can provide custom dialog windows that you design to allowinteractive setting of program options and even views of the input or output data.They can also utilize TNTmips Job Processing to efficiently perform batch pro-cessing and can be run over enterprise networks or using cloud computingresources using TNTscript.


page 6

Sample Geospatial ScriptsA large collection of sample geospatial scripts of all types is distributed withTNTgis. On Windows computers the sample scripts are installed automatically ina subdirectory named smlsamples in your installation directory. The TNTgisinstaller for MacOS X provides a separate option to install the sample scripts in asubdirectory named Geospatial Analysis Scripts. You can also download thelatest version of the sample script library from:

www.microimages.com/sml/index.htm

This Scripting page is also an excellent resource for the latest information aboutgeospatial scripting in the TNT products. It provides links to pages coveringdifferent script categories and topics. The individual category pages provideexamples and descriptions of different scripts in that category.

Many sample scripts are discussed in illustrated color Technical Guides thatprovide detailed information about the sample script along with annotated ex-cerpts. Links to these TechGuides can be found with the script descriptions onthe script category web pages. You can also access them from the TechnicalGuide catalog page:

www.microimages.com/documentation/html/category.htm

TechGuides illustrating sample scripts can be found under the following categorylinks: Scripting, CartoScripts, Display Control & GraphTips, Macro Script, andTool Script, among others.


page 7

Open

Save

Save As

Cut

Copy

Paste

Find andReplace

Go To Line

CheckSyntax

InsertField

ScriptReference

Creating and Editing ScriptsA script can be anything from a single expression to a long structured programwith user-defined functions, nested loops, and branching constructs. Regardlessof how simple or complex your script is, the script editor windows provided inTNTgis make it easy to compose, edit, and check the script. These editor win-dows provide simple tools for inserting operators, SML keywords, and predefinedfunctions into your script. Spaces and tabs are ignored when a script is inter-preted by SML, so you can use spaces and indents freely to make the script morereadable. You can add comments to document script logic and structure. Auto-matic color highlighting for SML keywords, comments, and text strings enhancesreadability as you work. A syntax checker is also provided so you can make surethat your script conforms to the syntax rules of the SML programming language.

The name and layout of the editor window varies depending on the programenvironment in which you are working. For example, when you are composing adatabase selection query to mark elements in a vector object you are displaying,the Select by Query window (small window shown below) includes an InsertField icon button to let you easily insert the references to fields in associateddatabase tables into the script (query). A win-dow with similar layout but different title(“SML”) is provided when youare composing a macro script ortool script.

Comments (begin-ning with #) arehighlighted in red.

Key words andnames of pre-defined functionsand classes arehighlighted in blue.

Text strings arehighlighted in cyan.SML Editor window for standalone geospatial process scripts.


page 8

Integrated Script ReferenceSML provides hundreds of predefined elements includingconstants, arithmetic and logical operators, and mathemati-cal and geospatial functions and classes. Documentation onthese elements is provided in the SML Editor’s Script Refer-ence window. The left side of the window is a tree-controlthat lists these and other script element categories; click onthe plus sign icon next to an entry to show a listing of itemsin that category. Functions and classes are further dividedinto subcategories that must also be expanded to show their elements. When youselect an individual script element in the list, the pane in the right side of theScript Reference window documents the syntax and use of the element. For func-tions, the documentation lists the required and optional parameters, the valuereturned, any details and assumptions, and in most cases provides an example ofits use. Class members and methods (class functions) are documented in similarfashion. You can also use the Insert button on the Script Reference window toinsert constants, functions, keywords, and operators into your script.

Depending on which SML Editor you are using, open the Script Reference window fromany of the options on the Insert menu or by pressing the Script Reference icon button.


page 9

Scripts for Database Computed FieldsOne of the simplest yet very useful applications of scripting in TNTgis is creatingcomputed fields in database tables. A computed field does not contain static databut rather the result of an expression that can combine information from otherfields in that table or in other related tables. The expression is evalutaed sepa-rately for each record in the table, so different values can be returned by the sameexpression in different records. There are two types of computed fields: com-puted numeric fields return a numeric result and computed text fields return theresult as a text string. Names for computed fields are shown in blue in tablewindows, so it is easy to distinguish them from standard data fields. You cancreate computed fields and their expressions using the Table Properties windowfor any database table, as described in the Technical Guide entitled Table Proper-ties Window.

Two examples of computed numeric fields are illustrated below. The first one usesdecadal population values for major cities to compute the percent populationchange from 1970 to 1990. This expression uses standard arithmetic operators:subtraction (-), multiplication (*), and division (/), along with parentheses toenforce the proper compu-tation order.

The second example returns an appli-cation rate for herbicide for differentfield management grid polygons. The

rate is determined fromthe previous year‘scorn yield value forthat polygon, using alogical if-else struc-ture to set higherapplication rates forhigher corn yields.


page 10

Scripts for Computed Text FieldsA computed text field script can be as simple as a reference to a string field inanother related table, or it can be a more complex expression that concatenatesother fields or constructs a string from text and numeric data. Raw text stringsmust be enclosed in double quotes in a string expression (and in SML generally).You can concatentate strings by simply using the addition operator (+) or use thesprintf() function to create a formatted string. String expressions can includereferences to numeric fields, but values returned by those fields must be con-verted to a number by the string expression.

The table illustrated below includes two computed text fields (blue) that mergeinformation from other fields in the same table. The Address computed text fieldmerges the information from the StreetNumber and Street fields. The former is aninteger field, so its value is converted to a string using the NumToStr() function.The Street field is a string field, so its field reference can be used directly in theexpression. The resulting strings from these fields are concatenated by simpleaddition, along with a text string consisting only of a space to separate the streetnumber from the street name.

The Name computed textfield illustrates the use of thesprintf() function to concat-enate three string fields(LastName, FirstName, andMiddleName) along withspacing and punctuation. The function usesa format string (enclosed in double quotes)that can include both raw text and referencesto variables that follow the format string inthe same order, separated by commas. In thisexample spaces, a comma, and a period areembedded in the format string. The %s sym-bol is thereferenceto a stringv a l u e ;other symbols are available to refer to integer and floating point fields. Forexample, the symbol %d is used to reference an integer value and convert it to astring. The expression below produces the same result as the string expressionshown above for the Address field:sprintf("%d %s", OwnerValue.StreetNumber, OwnerValue.Street);


page 11

String Expressions for DataTipsDataTips in View windows can automatically reveal important attribute informa-tion for elements when the cursor pauses over them. You can set up DataTips fora displayed layer using its Layer Controls window, as described in the DataTipsTechnical Guide. The DataTip information for each layer is read from a desig-nated field in an attached database table. You can include information frommultiple fields by reading the DataTip from a computed text field that merges andformats information from those fields. The expression can include newline codesto create a multiline DataTip and a text label for each line. The ManagingGeoattributes tutorial includes more information on setting up and using multilineDataTips from computed text fields.

The illustrations above show an example of a multiline DataTip presenting infor-mation from property parcel polygons in a vector object. The string expressionuses newline characters to create four lines of text, each of which begins with atext label for the attribute shown on that line. The assessed value is read from anumeric field and so must be converted to a string for use in the expression.

Text formatting control codes are also available that you can use to set fonts,create bold text, and insert tabs. Each formatting code begins with the tilde char-

acter (~). Codes must be enclosed by a setof curly brackets ( { } )and included withinthe text strings they modify, or withinquotes by themselves. The illustrationsbelow show the same information as in theDataTip above, but with formatting added.

Arial is set as the font,labels are set to bebold, and a tab stop isset for each line and atab character (\t) inserted to left-align the values. A complete list of formattingcodes is presented in the Quick Guide entitled Text Style Formatting Codes.


page 12

Database QueriesA database query is a script that is used to search the records in a database to findthose that match specified criteria. In many cases the database records are at-tached to elements in geospatial objects, so the query in reality is used to identifyone or more elements in that object. A query can reference fields in a single tableor in multiple related tables.

You can use database queries in several ways in TNTgis. When you display oredit geometric objects (vector, CAD, shape, and TIN), you can use a query totemporarily mark (highlight in color) all elements that match your selection crite-ria. You can apply some editing operations (such as deletion) to the entire markedset or just to the current active element in the set. Icon buttons on the Viewwindow allow you to step through the marked set if needed.

Database query used to select polygons tobe displayed (filled in this case). All lineelements are displayed, so boundaries ofunfilled polygons are visible.

Database query used to temporarily mark(in red and magenta colors) displayedpolygons that match the selection criteria.

When you set up display parameters for a geometric object, you can use a query todetermine which elements in a layer are displayed. For vector objects you canseparately query the point, line, and polygon elements, though a single query canreference attributes of different element types if they are topologically related(such as lines and nodes, or lines and polygons). Some geometric object pro-cesses (such as extraction, buffer zone generation, and others) also allow you touse queries to determine the elements to use in the operation. Query proceduresare discussed in detail with many examples in the tutorial booklet entitled Build-ing and Using Queries.


page 13

Style Scripts and CartoScriptsWhen you set up display styling for elements in geometric objects, the Style byAttribute option allows you to set up different styles for elements with differentvalues in a single designated field in an attached database table. If you would liketo set up styles based on a more complex assessment of the element attributes,you can use the By Script style option.

A style script can utilize named styles that have already been created and refer-ence existing line patterns and polygon fill patterns. It can also directly set stylecomponents such as line width and the colors used for point symbols, lines, andpolygon borders and fills. A special set of SML keywords are provided for use instyle queries. The Building and Using Queries tutorial booklet provides an intro-duction to creating style scripts.

DrawBorder = 1;DrawColor$ = "red";if ( POLYSTATS.Area < 200000 ) then

beginFillInside = 1;FillColor$ = "yellow";

endelse

beginFillInside = 1;FillBitmapPatt = 1;FillPatt$ = "BitmapPatt2";

end

A style script that sets up different polygon fill styles based on an area threshold.

Geologic point and line symbolsrendered by CartoScript.

CartoScripts are style scripts that make useof special SML functions to create com-plex symbology for points or lines. TheCartoScript functions allow you to directlydraw symbols, navigate and draw along lineelements, and create text labels as part ofthe symbology. Functions are provided todraw lines, arcs, circles, and 3D cubes andcylinders. You can use CartoScripts to cre-ate specialized symbology for maps inparticular disciplines, such as geology orenvironmental science. The tutorial book-let Using Cartoscripts provides a thoroughintroduction to creating and usingCartoScripts.


page 14

GeoFormula Display LayersA GeoFormula Display Layer is a computed layer that com-bines information from one or more spatial objects (raster orvector). The result is rendered to the View as a “virtual ras-ter” layer; there is no need to create and save an output object.The result can be either grayscale (values ranging from 0 to255) or RGB color (range of 0 to 255 for each of the three color components).GeoFormula layers can be displayed along with any other type of layer in theView. You can add a GeoFormula layer to a View by using the Add / Layer menucascade in the Display Manager.

The GeoFormula Layer Controls window provides a simplified programming in-terface in which selecting input objects automatically creates corresponding scriptvariables and there are predefined variables for the output. The interface alsoprovides push-button creation of numerical variables (“values”). You can thuseasily compose a script that combines values from the various input objects in thedesired way. With their simple interface and virtual output, GeoFormula layersare an ideal means of prototyping data analysis algorithms and testing differentdata fusion methods.

The tutorial booklet entitled Using Geospatial Formulas provides an introduc-tion to GeoFormula display layers and provides many sample GeoFormulas. Theexample shown below computes a color layer in which each of the three colorcomponents is computed from the normalized ratio of two Landsat image bands,but only for areas that have a non-zero potential crop yield value in a correspond-

ing soil map vector object; the color is set togray in the remaining areas.


page 15

GeoFormula ProcessA GeoFormula script that you create for display purposes can also be used in theTNTmips GeoFormula process (Script / GeoFormula from TNTmips menu) tocreate a raster object saved in a Project File. As in the Display process, you cancombine objects to produce a simple numeric result (saved as a grayscale raster)or a color result (saved as an RGB composite raster). In addition, the GeoFormulaprocess implements a specialized analysis procedure called multi-criteria deci-sion analysis that is described on the next page.

The GeoFormula process further simplifies setup by providing a wizard interfacefor creating new GeoFormulas. When you use the wizard, you are prompted toselect the input objects, then for the type of GeoFormula you want to create (nu-meric, color, or multi-criteria). When you choose either of the first two options,the wizard creates a stub script that includes guideline comments on how thattype of script must be structured and what type of values must be returned. Youcan then edit this stub script, removing the comment characters from the func-tional lines and adding the statements needed to perform the desired computation.

The output tabbed panel includes controls for determining the extents, projection,and cell size or line/column dimensions of the output raster.


page 16

Multi-Criteria Decision AnalysisMulti-criteria decision analysis (MCDA) is a quantitative approach to evaluatingdecision problems that involve multiple variables (criteria). The GeoFormulaprocess allows you to apply a spatial form of MCDA using cell values in rasterobjects and the database attributes of polygons in vector objects to represent thespatial variations of individual decision criteria.

When you choose Multi-criteria analysis model from the GeoFormula CreationWizard, the wizard prompts for the required input parameters and automaticallygenerates the corresponding GeoFormula script. The process uses the most com-mon form of MCDA, weighted linear combination. You first assign a “relativeimportance” weighting factor to each of the spatial objects. For each input objectyou are then prompted to select or set up a table of numerical scores that indicatethe relative benefit (or cost) you want to assign to particular values or value rangesin the object. The MCDA script computes an overall score for each output celllocation by multiplying the weighting factor for each object by the score for thatlocation and summing the products from all of the input objects.

92-100

82-91

73-81

64-72

55-63

45-54

36-44

27-35

17-26

8-16

Soil Erodibility(weight = 40%)

Distance from Streams(weight = 35%)

Average Annual Rainfall(weight = 25%)

985

591

MCDA Result: high score indicates greater hazard.

The MCDA example illustrated here evaluates areas where clearcut logging couldhave adverse affects on streams due to sediment runoff. The criteria objects usedare a vector soil map scored by erodibility, a vector map of stream buffer zones,and a raster with local variation in average annual rainfall.


page 17

Display Control Scripts for DataTipsDisplay Control Scripts allow you to add custom effects and procedures to Viewsof saved groups and layouts. A display control script runs automatically when itsgroup or layout is loaded in the Display process, and provides access to eventssuch as the beginning and end of rendering the group or layout; drawing, select-ing, creating, or removing particular layers; showing and hiding a DataTip; andmany others. Each event has a corresponding prototype function in the DisplayControl Script function group, and each such function is automatically called byits associated event. You can insert these prototype functions into your displaycontrol script and add your own code for the function to take the desired actionswhen the associated event occurs in the display. You can create and add a displaycontrol script to a group or layout by choosing Edit Control Script from the Dis-play menu of the Display Manager window.

A simple use of a display control script is to apply custom formatting to text in aDataTip, including font styles, alignment, and background color, as shown by theillustration below. You can format DataTip text using MicroImages formattingcodes or HTML markup and Cascading Style Sheet (CSS) methods. Samplescripts that illustrate these techniques are described in the Technical Guides en-titled Add Styling to DataTips and Design DataTips using HTML.

View of a saved group with DataTip formatted using HTMLmarkup and CSS styles defined in a display control script.


page 18

Display Control Scripts using Graphics

The Label_management sample script repositions andenlarges text (red in the right-hand illustration) foroverlapping label elements in a vector object.

The SlopeAspectGraphTipsample script computesslope and aspect for thecursor location from a hiddenelevation raster and portraysthe results graphically.

The PieChartGraphTip sample scriptcreates a DataTip with transparentbackground and no frame. It shows a piechart and text that are dynamicallyrendered to show census information forcounty polygons drawn from differentfields in an associated database table.

You can program a display control script to do more with DataTip events thansimply format text. Each DataTip is initially composed as a small image in com-puter memory, and a display control script can use SML drawing functions todraw graphics into that image. The DataTip function prototypes also provideaccess to the location of the cursor on screen when the DataTip is requested. Thislocation can then be used to obtain the cell value at that location in a raster layer orone or more attributes for the corresponding element in a geometric layer in theView. The script can use these context-sensitive values, or values computedfrom them, as the basis for creating anddrawing bar graphs, pie charts, andother graphical representations of thedata at that location. The script canalso create a mask for the backgroundarea of the DataTip to make it transpar-ent and suppress the DataTip frame.The illustrations on this page showsome of the graphic applications thatare provided by sample display controlscripts. These scripts are documentedin the TechGuides entitled EnhanceDataTips using Scripts.


page 19

Geospatial Process ScriptsGeospatial process scripts execute standalone processes that run independentlyof other interactive TNTgis components. You can create or run a geospatialprocess script via the SML process in TNTmips Pro or TNTedit. To access theSML process, use the Script menu options from the TNTmips main menu or themenu options provided by the SML icon button on the TNTedit. The Run menuoption allows you to select and run an existing geospatial process script. TheEdit Script option opens the SML Editor window, where you can create, view, edit,and run a geospa-tial process script.

Geospatial processscripts can access,transform, and createvirtually any form ofgeospatial data, includ-ing all of the spatialobject types used inTNTgis as well as anyassociated databaseinformation. A processscript can also importdata from or export datato a host of external fileformats. (Export capa-bility is not availablefrom SML scripts runin TNTmips Free.)

You can set up a script to use interactive dialogs so that those unfamiliar with thescript can easily select input and output objects and supply any necessary process-ing choices and parameters. Popup dialogs created by predefined SML functionsmay suffice for this purpose in simple processing scripts. For more complexscript processes, you can create and manage custom dialog windows to controlthe operation of the script, as described in the tutorial entitled Building Dialogs inSML.


page 20

Create Unique Geospatial ProcessesSTEPS

select Script / Run fromthe TNTmips menuuse the Select Filedialog to navigate to theSTANDALONE directory inthe SML sample scriptcollection and selectRASTERINTERVALS.SML

press [Input Raster...] onthe Raster Intervalswindowselect raster DEM fromthe BUBBSCK Project Filein the SCRIPTING sampledata directoryset the Number ofIntervals field to 12 andpress [Run...]press [Preview result...]on the Distributionwindowpress [Close] on thePreview windowpress [OK] on theDistribution windowuse the Select Objectdialog to name a newProject Fileand outputraster objectpress [Exit] onthe RasterIntervalswindow

You can use a geospatial process script to imple-ment a custom geospatial data operation. TheRASTERINTERVALS script example illustrated here cat-egorizes a grayscale raster into a user-specifiednumber of grayscale-value intervals. The intervalscan be set up using either equal value range or equalcell count per interval, but the resulting ranges canalso be manually edited in the Distribution window.The script output is a categorical raster with a singlevalue for each interval and a color palette for dis-play. This script process can be used to subdividean elevation raster into elevation ranges, a sloperaster into ranges of different slope magnitude, andso on. The dialog and Preview windows are createdand managed by this processing script.

The ThemeMapping optionfor displayingraster layers inthe TNT productsprovides atemporary visualequivalent of thepermanentcategorizationperformed by thisscript.


page 21

Automate a Processing WorkflowMany of the standard geospatial operations you per-form interactively in TNTmips have correspondingpredefined functions or class methods in SML. Theoutput of one such operation can be used as input toanother, allowing a script to tie together a number ofdiscrete geospatial operations into one streamlinedprocess.

The PIPELINEPANSHARP sample script illustrates thisconcept. The inputs to the script are three low-reso-lution raster bands of a multispectral image and ahigher-resolution panchromatic raster. These rastersare processed to create a pan-sharpened color-com-posite with color content from the multispectral bandsand spatial detail from the panchromatic (pan) band.The script uses a number of predefined compiledoperations to handle the major processing steps.These steps include optionally applying contrast-en-hancement to the input rasters, compositing themultispectral bands and resampling to match theextents of the pan band, multiresolution fusion us-ing a choice of colorblending methods tomake the pan-sharp-ened image, andsaving the image asan RVC raster orGeoTIFF, PNG, JP2,or JPEG file. Be-cause each of thesecomplex steps ishandled by a compiled class method, scriptexecution is fast and the script has a rela-tively simple structure.

Image processing operations are particularlyeasy to chain together in geospatial scriptsbecause the same modular pipeline process-ing architecture used in the TNT products isalso integrated into SML.

STEPSselect Script / Run fromthe TNTmips menuselect PIPELINEPANSHARP.SML

from the PIPELINE directoryin the SML sample scriptcollectionin the script’s dialogwindow, press [Red...]select raster BAND_3 fromthe BUBBSCK Project Filepress [Green...] andselect raster BAND_2press [Blue...] and selectraster BAND_1press [Pan...] and selectraster PAN

choose a Color BlendingMode and an OutputFormatpress [OK] to name theoutput object or file andrun the processpress [Close] to exit thescript


page 22

Scripts by JackTM

Dr. Jack F. Paris, a remote-sensing andgeospatial consultant, has developed acollection of advanced geospatial pro-cessing scripts, Scripts by JackTM, thatare in the public domain and can be usedor modified in TNTgis by anyone. Thesescripts are distributed by MicroImagesin the sample script collection noted pre-viously or can be downloaded from theScripting page at microimages.com.

Many of the Scripts by Jack focus onthe calibration and interpretive process-ing of multispectral satellite images. TheSRFI script processes images from a vari-ety of satellite platforms to performvarious radiometric corrections to a stan-dardized reflectance factor index (SRFI).Images processed through SRFI can beused as input to several other scripts. TheTERCOR script applies radiometric terraincorrection to a SRFI image, and the GRUVI

and TASCAP scripts compute measures ofbiophysical surface properties that canbe used to interpret green vegetation bio-mass and soil conditions. Other scriptsin the series provide color enhancementto the water areas of images of coastalareas (WATER) and subdivide grayscaleimages into contiguous areas with simi-lar properties that are then outlined by polygons in a georeferenced vector object(OBJECT).

Each script in this series is documented in detail in the accompanying FAQs byJackTM series (available for download). These PDF documents provide the un-derlying concepts and theory behind the processing implemented in each script,an explanation of how the SML code is used to achieve the desired result, andstep-by-step instructions on running the script.

Top: color-infrared combination ofQuickBird image bands of center-pivotirrigated fields. Bottom: optimizedvegetation index image produced by theGRUVI script in the Scripts by Jackseries. The GRUVI script adjusts forvariations in background soil color andsurface wetness to provide an accurateindex of green vegetation biomass.


page 23

Scripts Using Job Processing

TNT Job Manager running jobs utilizing SML process scripts.

Dialog window opened by an interactivescript that sets up batch conversion ofTIFF files to JPEG2000 via job processing.

Geospatial scripting can be combined with TNTmips Job Processing to efficientlyperform specialized batch processing, allowing several identical script processesto be run simultaneously to take advantage of your computer’s multiple proces-sor cores.

To implement script-based batch job processing, the interactive user-input activi-ties and the processing activities are performed in separate SML scripts. Theinteractive script provides an interface (such as a custom dialog window) tochoose the input geospatial input objects, set global processing parameters, anddesignate the desired output destination. This script also uses the MIJOB classin SML to create a properly-formatted job file for each of the objects to be pro-cessed. This job file specifies the input object(s), provides variable values, andspecifies the process script to be run. (Job files are automatically written to theTNT job directory you have set for your TNTmips installation.) You can specifyin the TNT Job Manager window whether to immediately queue the jobs in theTNTmips Job Processing system or hold them to be queued later. You can alsoschedule jobs to be run at certain times (such as overnight or over the weekend).

When each job file is run, it calls the specified processing script and automati-cally passes the predefined variable values to it for execution. The process scriptmust include variable declarations forall of the values to be passed from thejob file. The process script then pro-cesses the input data specified by thecurrent job file and creates the requiredoutput data. The illustration here showsthe custom dialog window for a scriptthat sets up batch conversion of TIFFimage files to JPEG2000 files via job pro-cessing.


page 24

Automated Processing with TNTscriptTNTscript is a professional product designed to enable automated productionprocessing of geospatial data using SML scripts. TNTscript enables SML scriptsto be executed on computers that do not have any other professional TNTgisproducts installed. If you develop SML processing scripts using TNTmips Pro orTNTedit Pro, TNTscript allows you to execute these scripts on additional com-puters, at remote sites, or using cloud-computing resources. TNTscript can alsobe used separately from the other TNTgis professional products to write, edit,and execute SML programs.

Runtime TNTscript is a Windows or Mac executable program that provides all ofthe noninteractive SML processing functionality found in TNTmips Pro.TNTscript executes SML scripts without user interaction during processing. Itdoes not have a user interface, but instead is launched from the command linemanually or by another program. Processing scripts written for use with TNTscriptare therefore structured in a similar manner as those used in TNTmips job pro-cessing. All data-specific variables must be passed to the SML script by TNTscriptat the start of execution. The script to be used and the required variable valuescan be specified on the command line or in an XML-formatted text file (.smlx).

TNTscript can be used to integrate custom SML processing into a productionworkflow involving other scripts and software products. A custom script control-ling the work–flow can call TNTscript as needed and specify the name of an SMLscript and the required script parameters. The data produced by this processingscript can then be passed along to the next step in the overall work–flow. Net-work licenses for TNTscript are available to allow TNTscript processing to bedistributed over multiple networked computers. Licenses are also available forcloud-computing resources. TNTscript can therefore be used to integrate thecapabilities of SML into geospatial processing workflows in an enterprise net-work to automatically create geospatial products as new data arrive, or in a webapplication that processes data by user request.

A TNTscript license includes the runtime TNTscript executable (with its owninstaller) and a professional license for TNTview (optional installation using theTNTgis installer). TNTview provides access to the SML Script Editor for writing,editing, and testing SML scripts for use with TNTscript. When you set the targetproduct to TNTscript, the built-in Script Reference documentation indicates whichfunctions and classes are available (everything except those related to interactivecomponents such as pop-up dialogs, View windows, etc.). Fully interactive scriptscan also be written and executed from TNTview under the TNTscript license.


page 25

Tool Scripts and Macro ScriptsTool Scripts and Macro Scripts are specialized SML scripts launched from a Viewwindow. These script types are designed to allow easy access to and operationson the objects in the View. You can create tool scripts or macro scripts that enableany user to perform custom procedures on spatial data layers they are viewing.You can set up a general-purpose tool script or macro script to be available fromany type of 2D View window or save a data-specific script with a particular groupor layout. Scripts saved with a layout that becomes part of an atlas are also avail-able for use in TNTatlas. Every View window offers menu selections that let you

easily add and delete Toolscripts and Macro scripts (Op-tions / Scripts).

For the script writer, macroscripts and tool scripts pro-vide a streamlined way toprovide custom processing

capabilities that require visual interaction with the spatial data. Because macroscripts and tool scripts are invoked from a View window, you don’t need toprovide code to create and manage the View window and its contents. Most ofthat management is taken care of automatically, so you can focus on coding thecustom processing itself. Macro scripts and tool scripts:

Tool scripts and macro scriptscan be launched from iconbuttons on a View window'stoolbar or from the Tool andMacros menus.

• are executed from an icon button on a View window toolbar or from a menu;• can access features of the current view such as layers, extents, projection, se-

lected elements, zoom factor, scale, and styles;• can operate on objects in the current view or objects containing the same area;• can add a newly-created layer to the view;• can start an external program and provide it with data derived from the current

view.

A tool script can invoke a drawing tool and/or a dialog window (defined by thescript-writer) that allow the user to interact with the spatial data in the View win-dow. For example, the user could outline an area or select particular elements tobe processed. A macro script does not allow such interaction but can be set upwith a drop-down menu that provides program options.


page 26

Macro Script SetupMacro scripts can be launched from the View window's Macros menu (whichappears once you have installed a macro script) or from an optional icon button onthe toolbar. To add a macro script, choose Options / Scripts / Macro Scripts fromthe View window, which opens the Customize Macro Scripts window. If youwant to add an existing script, click on the Add icon button to open the Select File

window so you can navigate to thescript and select it. To create a newmacro script, click on the New iconbutton. An SML editor windowopens with a default stub script con-taining a list of predefined symbols

that you can use in themacro script. The SMLeditor window includes allthe script-creation and ed-iting features of thestandard SML window.

Once you have created or added the macro script, the Macro Script Propertieswindow opens. You can choose whether the script is accessible from all Views ofthe current type or only from the current saved group or layout. Choose Simplefrom the Type menu to have your tool script execute automatically without furtherinput from the user. Choose Menu if you want drop-down choices presented fromthe Macros menu entry and the icon button; the Menu Choices text field thenbecomes active so you can enter the menu choices needed for the script. Use theIcon toggle button to indicatewhether a script icon button appearson the View window toolbar; clickon the default icon to open a dialogto select an appropriate icon. Thetext you enter in the Name field isused for the menu entry in the Mac-ros menu and for the script iconbutton's ToolTip.

The Test button at the bottom of thewindow lets you run your scriptwithout closing the setup windows.Click OK in the Macro Script Properties and Customize Macro Scripts windowswhen you are done adding, developing, and/or testing your script.

Sample macro scriptscan be found in theMACROSCRIPT subdirectoryin the SCRIPTS directory.

NewAdd

Properties

The Use With menu options vary depend-ing on the type of View: Group, DisplayLayout, or Hardcopy Layout. You caninstall the macro script for all windows ofthat type or only the current one.


page 27

Sample Macro Script: Zoom to ScaleSTEPS

choose Main / Displayfrom the TNTmips menupress the OpenDisplay iconbutton on theDisplay Manager windownavigate to the SML

directory and selectGROUPZOOMTO from theBUBBSCK Project Fileuse the installed Zoom toScale icon button on theView window to vary thezoomchoose Options / MacroScripts from the Viewwindowuse the Properties andEdit icon buttons toexamine the settings andscriptclose the group

set up scale menu choicesthat are most appropriatefor your spatial data.

A macro script canbe launched andoptions selectedusing its iconbutton (left) orfrom the Macrosmenu (right).

The Zoom to Scale macro script (ZOOMTO.SML) is oneof several sample macro scripts that are provided inthe MACRSCR subdirectory of the SCRIPTS directory.This macro script lets the viewer redisplay the Viewwindow at one of several map scales selected fromthe script button's dropdown menu (or the script'ssubmenu in the Macros menu cascade). For properscript function, the objects in the view window mustbe either georeferenced or scale-calibrated.

The scale menu selections are not predetermined bythe Zoom to Scale script. When you install the script,you are free to set up the menu choices with the rangeof scale selections most appropriate for your data.The script accepts scale input from the menu as ei-ther map scale or ground dimensions. If the menuentry is purely numeric, it is interpreted as the de-nominator of the map scale fraction. For example,12000 is interpreted as a map scale of 1:12000. Ifthe menu entry is in two parts separated by a space(such as "1 mi"), the first part of theentry is interpreted as a ground dimen-sion in miles. (This portion of the scriptcan be easily modified to accept dimen-sions in kilometers or other distanceunits.) The script then performs the nec-essary calculations and sets the newmap scale for the View window.

The predefined macro script variableMenuChoice$ is used to represent theuser's selection from the macro scriptmenu button. If the menu choices arenumeric, thisstring must beconverted to anumeric valueusing theStrToNum()

function.


page 28

Tool Script Templates

A number of class andnumeric variables arepredefined and available forimmediate use in tool scripts.

Tool scripts can be run from an icon button on theView window toolbar or from the Tools menu. Toadd a tool script, choose Options / Tool Scripts fromthe View window in any TNTgis process that has aView window. Making this selection opens the Cus-tomize Tool Scripts window, which is nearly identical

to the Customize Macro Scriptswindow discussed previously.

To create a new tool script, clickon the New icon button to openan SML editor window, whichshows the tool script template.The template lists a number ofpredefined symbols and valuesthat you can use in any toolscript. The predefined valuesinclude the X and Y coordinatesof the screen cursor within theview (in pixels) and values thatrecord mouse button actions.

Additionally, the tool script tem-plate includes skeletaldefinitions of procedures likelyto be used in a tool script. Theseinclude procedures used the first

time a tool is activated; when the tool is destroyed;when the tool is activated and deactivated; when thetool is suspended (during redraw) and resumed (af-ter redraw); when the left, right, or middle mousebutton is pressed or released; when the cursor moveswithout a button press; when the cursor moves witha button press; when the cursor enters or leaves theView window; and when the user presses a key. Tocreate your script, remove the comment characters(#) to the left of each procedure definition you needand add code to specify the desired action to be car-ried out by that procedure.

Tool Script icon buttonsappear to the left of anyMacro Script icon buttons onthe View window toolbar.

tool script buttons

macro script buttons


page 29

Sample Tool Script: Flow PathThe Flow Path tool script shows how custom analy-sis procedures can be performed on layers in the cur-rent view using an SML Tool Script. The script usesSML watershed functions that operate on an eleva-tion raster (DEM) that must be the first layer in theView window.

When you launch the script, it first executes water-shed functions to create a depressionless version ofthe DEM and a complete set of vector flow paths.These derived features are required by subsequentscript steps; they are stored as temporary objects andare not displayed in the View. The script then opensa FlowPath and Buffer Zone window and creates agraphic tool that allows the user to place one or morewatershed seed points on the DEM or on an overly-ing image layer. Toggle buttons on the window en-able the user to choose to compute and display:

• the upstream basin (area with flow toward theseed point),

• the flow path downstream, and• a buffer zone around the flow path.

If you prefer seed points to fall along astream course, you can turn on theMove Seed Point to Flow Path togglebutton. Each seed point is then movedto the nearest precomputed flow pathline before the new flow path and ba-sin are computed. You can place newseed points, repeat the analysis as manytimes as desired, and save the com-puted vector objects.

STEPSpress the OpenDisplay iconbutton on theDisplay Manager windownavigate to the SML

directory and selectGROUP FLOWPATH from theBUBBSCK Project Filepress theFlowpath iconbutton on the Viewwindow to launch the toolscriptleft-click at a point alonga stream to create adownstream flowpathline and upstream basinpolygon (the basinpolygon may be smallunless the seed point isexactly on a DEM cellalong a stream channel)close the group

The script also creates and displays (inred) a vector layer outlining the extents ofthe DEM. If an overlying image layer islarger than the DEM, the user can use theextents box to guide placement of the seed points. The extents box is also used toautomatically clip buffer zones computed from flow paths that intersect the DEM boundary.


page 30

Script Layer in DisplayThe standard display process (Display / Spatial Data)supports the use of an SML script as a layer, just asany spatial object can be a layer. An SML scriptlayer can use flexible cartographic drawing functionsto create special map symbols and neatlines. Youcan add a script as a layer by choosing Add/Layer/Script from the Display Manager.

The sample script ARROW.SML is designed to draw anoriented magnetic declination map symbol in a lay-out, as in the example shown here. For this scriptthe SML layer should be alone in a group. The scriptdetermines the angle between grid north and truenorth from the previous map group in the layout; themagnetic declination value in the script must be ed-ited to suit the location of the map data. Thedeclination symbol includes true north, grid north,and magnetic north lines, labels for the angles, andtext describing the coordinate reference system used.

You can also add script layers to groupscontaining other spatial layers. The Co-ordinates panel lets you relate the scriptlayer to the map coordinates of the otherlayers in the group.

The Script tabbed panel in the SML Layer Con-trols window contains the interface for editing andrunning scripts.

STEPSpress the OpenDisplay iconbutton on the DisplayManager windownavigate to the SML

directory and select PAGE

LAYOUT 1 from the BUBBSCK

Project Fileexpand the Group 2entry in the DisplayManagerpress the LayerControls iconbutton for the ARROW

layer in Group 2examine the script in theScript tabbed panel inthe SML Layer Controlswindowpress [OK] on the SMLLayer Controls windowclose the group


page 31

Interactive Display Control ScriptsIn addition to their use to create enhanced DataTips that can include graphics,Display Controls scripts can be used to open a custom dialog window that pro-vides interactive access to data layers in the View. One such control scriptapplication is to provide custom spatial or attribute search capability for a layoutor atlas.

The Nebraska Land Viewer Atlas 2nd Edition created by MicroImages includes aFind Area of Interest dialog that is created and automatically opened by a displaycontrol script, NESEARCHCTRL.SML. The dialog and accompanying code in thecontrol script enables viewers of the atlas to search by name for a township, sec-tion, Natural Resource District, map quadrangle, or city/town. Inexact matchesare allowed by the search code, so multiple results are returned when needed to aresults panel. When a final single result is returned or selected by the viewer, theatlas View automatically zooms to the spatial extent of the selected area. Thesearch dialog also can provide a list of available orthoimages for the USGS quad-rangle at the center of the view, any of which can be selected directly for downloadfrom a Nebraska state government web site.

Since this search utility is provided by a control script, it remains active if theviewer changes interactive tools or uses the tool script created for the atlas, whichprovides scale-variable zoom capabilities. The display control script also installsan icon button on the View to reopen the dialog if the viewer has closed it.

Open Find Area Dialog


page 32

MicroImages, Inc.

www.microimages.com

IndexCartoScript......................................4,13

database computed field script........4, 9-11

database query.....................................4, 12

DataTip......................................11, 17-18

display control script..............4, 17, 18, 31

editing scripts............................................7

GeoFormula...................................4, 14-16

geospatial process script...............4, 19-24

job processing....................................23

macro script..................................4, 25-27multi-criteria decision analysis................16sample scripts...........................................6Scripts by Jack.........................................22Script Reference...................................8SML layer script...............................5,30style script......................................4,13TNTscript..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24tool script................................5,25, 28-29

Advanced Software for Geospatial AnalysisGEO

SCRIPTING

MicroImages, Inc. publishes a complete line of professional software for advanced geospatialdata visualization, analysis, and publishing. Contact us or visit our web site for detailedproduct information.

TNTmips Pro TNTmips Pro is a professional system for fully integrated GIS, imageanalysis, CAD, TIN, desktop cartography, and geospatial database management.

TNTmips Basic TNTmips Basic is a low-cost version of TNTmips for small projects.

TNTmips Free TNTmips Free is a free version of TNTmips for students and profes-sionals with small projects. You can download TNTlite from MicroImages’ web site.

TNTedit TNTedit provides interactive tools to create, georeference, and edit vector, image,CAD, TIN, and relational database project materials in a wide variety of formats.

TNTscript TNTscript lets you execute SML scripts on additional computers, at remotesites, or using cloud-computing resources.

TNTview TNTview has the same powerful display features as TNTmips and is perfect forthose who do not need the technical processing and preparation features of TNTmips.

TNTatlas TNTatlas lets you publish and distribute your spatial project materials on CD orDVD at low cost. TNTatlas CDs/DVDs can be used on any popular computingplatform.

R I Geospatial Scripting - MicroImages, Inc. · 2016-06-20 · Geospatial Scripting page 3...

Documents

Transcript of R I Geospatial Scripting - MicroImages, Inc. · 2016-06-20 · Geospatial Scripting page 3...