Objects

Chapter 8 LUSAS
Programmable
Interface
The script file is an ordinary ASCII text file which is processed by LUSAS Modeller
using the FILE OPEN filename.vbs command or the Open Command File dialog
(see LUSAS Modeller help). The format of the script file is as follows:

$ENGINE=scripting engine

{script body}

{procedures and functions}

where scripting engine can be one of the following:

q VBSCRIPT Microsoft Visual Basic Scripting Edition (v3.1)
q JSCRIPT Microsoft Java Scripting Edition (v3.1)
The $ENGINE keyword enables LUSAS Modeller to determine how to interpret the
syntax of the script and must be present on the first line of the script.

Objects
The LUSAS Modeller scripting API is built around a set of core objects with which
an applications programmer can manipulate using specific methods. The current set
of objects implemented to date are as follows.

Level 1 Level 2 Level 3 Level 4

311
Chapter 8 LUSAS Programmable Interface

Level 1 Level 2 Level 3 Level 4

Application
Menus
Text Window
Selection
Database
Database Objects Geometric Points
Lines
Surfaces
Volumes
Mesh Nodes
Elements
Groups

Objects can be accessed using the following methods.

Method Arguments Return Value Comments

getMainMenu none menu object
getDatabase none database object
newDatabase none new Database
object
getSelection none a pre-defined Select objects for use in
selection set a script before the
script is executed
createObject Automation automation To open an Excel
Object$ object spreadsheet, use the
string “Excel.sheet”.
See VBScript online
reference for help
processCommand lcommand$ none To execute any new or
old command
supported by LUSAS
Modeller
createSimpleDialo dialog title$, true if OK To get interactive user
g row label$(), pressed, false input. All input is in
column otherwise character strings
header$()
2d data$(c, r)
getTextWindow none text output
window

312
 User Interface

User Interface
These objects allow the LUSAS Modeller user interface to be customised for a
particular use.

Menus
These allow user commands to be activated from the drop down menus along the top
of the LUSAS Modeller application.
Method Arguments Return Value
getSubMenu menu name$ specified menu object
insertMenu before menu name$, new menu object
new menu name$
appendMenu menu name$ new menu object
removeMenu menu name$

insertItem item name$,

new menu name$,
user Command$
appendItem item name$,
user Command$
removeItem item name$
renameItem old item name$,
new item name$
insertSeparator before menu name$

isMenu menu name$ true or false

isSeparator item name$ true or false
countItems none number of menu entries
existsMenu menu name$ true or false

VBScript Example
Customising the Menu Interface:
$ENGINE=VBSCRIPT
set MainMenu = GetMainMenu()

' Check if we already have a "Test" menu

if (MainMenu.existsMenu("&Test")) then
MainMenu.removeMenu("&Test")
end if

' Add a "Test" menu before the "Window" menu

' Note the "&" character means underline the
' next character as being the keyboard shortcut.

313
Chapter 8 LUSAS Programmable Interface

' These should only appear once for each menu

set testMenu = MainMenu.insertMenu("&Window", "&Test")

' Add background entry

set backMenu = testMenu.AppendMenu("&Background")

' Add 2nd level items

backMenu.AppendItem "&Black Background", "SET VIEW BACKGROUND RED=0
GREEN=0 BLUE=0"
backMenu.AppendItem "&White Background", "SET VIEW BACKGROUND RED=100
GREEN=100 BLUE=100"

' Add Selection Entry

set selectMenu = testMenu.AppendMenu("&Selection")
' Add 2nd level items
selectMenu.AppendItem "&Yellow Selection", "SET VIEW SELECTION COLOUR
COLOUR=100.100.000.000.000"
selectMenu.AppendItem "&Black Selection", "SET VIEW SELECTION COLOUR
COLOUR=0.0.0.0.0"

' Add 1st level axis entries

testMenu.AppendItem "&Axes On", "SET AXES ON VIEWNM=CURRENT"
testMenu.AppendItem "&Axes Off", "SET AXES OFF VIEWNM=CURRENT"

' insert a divider

testMenu.InsertSeparator "&Axes On"

Interactive user input

The current API supports the createSimpleDialog method for getting user input to a
script. The syntax of the function is as follows:
createSimpleDialog (“title”, rowLabels, columnLabels, dataArray)

where:
title is the name of the dialog
rowLabels is a zero based array of strings
columnLabels is a zero based array of strings that are used if two or more
columns are defined.
dataArray is a two dimensional string array that holds initial values/user data.
The dimensions of this array are data(columns, rows)
$ENGINE=VBScript

title = "LUSAS 3D Section Slice"

noParameters = 4
ncol = 0

redim labels(noParameters)
redim headers(ncol)
redim parameters(ncol ,noParameters )

labels(0) = "Axis"
labels(1) = "Start"

314
 User Interface

labels(2) = "Finish"
labels(3) = "Interval"

headers(0) = " "

parameters(0, 0) = "X"
parameters(0, 1) = "0"
parameters(0, 2) = "100"
parameters(0, 3) = "25"

' Get Parameters

okPressed = createSimpleDialog(title, labels, headers, parameters)

'----------------------------------------------------------------------
axis = parameters(0,0)
start = parameters(0,1)
finish= parameters(0,2)
inc = parameters(0,3)
if inc <= 0 then
msgbox "Error increment must be +ve"
else
for val = start to finish step inc
processcommand("SECTION SLICE AXIS=" & axis & "-AXIS VALUE=" & val &
"")
next
end if

To use the user data it should be converted into an appropriate form using the chosen
script language’s conversion functions. In VBScript, the basic ‘convert to’ functions
are CInt, CStr and Cdouble.

Text Output
This allows access to writing user defined messages in LUSAS Modeller.

Method Arguments Return Value

writeLine text$
readLine line number specified text object
countLines none number of lines
VBScript Example
Writing user messages:
$ENGINE=VBSCRIPT
set textWindow = getTextWindow()

' Write line to text window

textWindow.writeLine("Hello World")

' Extract number of lines in text window

m = textWindow.countLines()

315
 Chapter 8 LUSAS Programmable Interface

' retrieve the last 5 text output lines in

' reverse order and show user each line
n = m - 5

' ensure n not -ve

if n < 0 then n = 0
for i = m to n step -1
text = "Line " & i & ": " & textWindow.readLine(i)
msgbox text
next

File handling
As a scripting language host, LUSAS Modeller does not implement any file handling
methods. File handling methods are the responsibility of the chosen scripting
language.

VBScript Example
$ENGINE=VBScript

' set filename

fileName = "File.tmp"

' open file and write text

set outFile = newTextFile (fileName, TRUE)
outFile.write "Date:" & Date & " Time: " & Time & vbNewLine
outFile.close()

' now open file for reading

set inFile = getTextFileForReading (fileName)
text = inFile.readall
inFile.close()

' output text

msgbox text

FUNCTION newTextFile (fileSpec, overwriteExisting)

set fileSys = CreateObject("Scripting.FileSystemObject")
set newTextFile = fileSys.CreateTextFile(fileSpec, overwriteExisting)
END FUNCTION

FUNCTION getTextFileForReading (fileSpec)

const ForReading = 1
set fileSys = CreateObject("Scripting.FileSystemObject")
set getTextFileForReading = fileSys.OpenTextFile(fileSpec, ForReading)
END FUNCTION

Database Object
This object allows access to the LUSAS Modeller database for manipulating
geometric objects using the following methods.

316
 Database Object

Method Arguments Return Value

createPoint x, y, z new point object
countPoints none number of points
getPoint point number specified point object

createLine point or line objects(), new line object

lineType$
createLineByCoordinates x1, y1, z1, new line object
x2, y2, z2
createLineByPoints point object, new line object
point object
createArc points objects() new arc object
countLines none number of lines
getLine line number specified line object

createSurface point or line objects() new surface object

countSurfaces none number of surfaces
getSurface surface number specified surface object

createVolume point, line or surface new volume object

objects()
countVolumes none number of volumes
getVolume volume number specified volume object

createGroup name$ new empty group object

getGroup name$ specified group object

getLargestPointNumber none integer identifier

getLargestLineNumber none integer identifier
getLargestSurfaceNumbe none integer identifier
r
getLargestVolumeNumbe none integer identifier
r

getLargestAttributeNumb attribute type$ number of attributes of

er ‘type$’ in database

Attributes
The database object function ‘getLargestAttributeNumber’ requires a string
parameter describing the attribute type. This can be any one of the following strings:
MESH LOADING LOADING TABLE SUPPORT TRANSFORMATION

317
Chapter 8 LUSAS Programmable Interface

LOCAL DAMPING VARIATION LOAD CURVE CONSTRAINTS

COORDINATE TABLE

SEARCH AREA RETAINED SLIDELINE SLIDELINE EQUIVALENCE

FREEDOMS PROPERTIES TABLE

THERMAL THERMAL RADIATION ACTIVATE DEACTIVATE

SURFACE GAP SURFACE

DAMPING INFLUENCE THERMAL GAP THERMAL THERMAL RADIATION

PROPERTIES LINE PROPERTIES ENVIRONMENT PROPERTIES
PROPERTIES

THERMAL GEOMETRY MATERIAL COMPOSITE BACKGROUND GRID

CONTACT

These attribute type strings are valid for all attribute inquiry functions in the
scripting API.

VBScript Example
To create a new point object, type:
$ENGINE=VBSCRIPT
set database = getDatabase()
set point1 = database.createPoint(1, 2, 3)
To create a new line object, type:

$ENGINE=VBSCRIPT
set database = getDatabase()
set point1 = database.createPoint(0, 0, 0)
set point2 = database.createPoint(10, 20, 30)

set line = database.createLineByPoints(point1, point2)

or use an array

$ENGINE=VBSCRIPT
set database = getDatabase()
dim points(2)
set points(0) = database.createPoint(0, 0, 0)
set points(1) = database.createPoint(10, 20, 0)
set points(2) = database.createPoint(50, 30, 0)
' straight lines between all points
set straightLine = database.createLine(points, "STRAIGHT")
' spline between all points
set spline = database.createLine(points, "SPLINE")

318
 Database Entities

Database Entities
The following methods are valid for all database objects. It has been left to the user
to check if the database object belongs to a group. If the database object does not
belong to a group, then the database is returned, as a special group of ungrouped
objects.
Database Object Methods Arguments Return Value
hasParentGroup none TRUE or FALSE if the database
object is a member of a group
getParentGroup none the group which the database
object is a member of.
GetHighestParentGroup none the group which ultimately owns
the group that the database object
is a member of.

The basic features of a LUSAS Modeller database are split into three categories.
Geometric Objects - Points, Lines, Surfaces and Volumes
q Mesh Objects - Nodes and Elements
q Collection Objects - Groups
The following methods allow the attributes of the objects which make up the LUSAS
Modeller database to be manipulated.

Geometry Objects
The following methods are valid on geometric objects only.
Geometric Methods Arguments Return Value
countLOF none number of lower order features
defining the entity
getLOF index (1st, 2nd, 3rd specified object
etc.)
countHOF none number of higher order features
defined by the entity
getHOF index (1st, 2nd, 3rd specified object
etc.)
countAttributes attribute type$ number of attributes of ‘type$’
assigned to entity
setPen pen number
getNumber none integer identifier

319
Chapter 8 LUSAS Programmable Interface

Point Methods Arguments Return Value

getX none X co-ordinate
getY none Y co-ordinate
getZ none Z co-ordinate
moveTo x, y, z
moveBy ∆x, ∆y, ∆z
copy ∆x, ∆y, ∆z new copied point object

Line Methods Arguments Return Value

copy ∆x, ∆y, ∆z new copied line object

Surface Methods Arguments Return Value

copy ∆x, ∆y, ∆z new copied surface object

Volume Methods Arguments Return Value

copy ∆x, ∆y, ∆z new copied volume object

VBScript Example
To calculate the centroid of a surface.
$ENGINE=VBSCRIPT
set database = getDatabase()
dim points(3)

' Define point coordinates

set points(0) = database.createPoint(0, 0, 0)
set points(1) = database.createPoint(50, 0, 0)
set points(2) = database.createPoint(75, 50, 0)
set points(3) = database.createPoint(25, 50, 0)

' create surface from points

set surface = database.createSurface(points)

' Initialise coordinates

sumX=0
sumY=0
sumZ=0

' Initialise number of points

nPoints=0

' loop all the lines in this surface

for j = 0 to surface.countLOF() - 1
set line = surface.getLOF(j)
' loop all the points in this line
for k = 0 to line.countLOF() -1
set currentPoint = line.getLOF(k)

320
 Database Entities

' add the position to the sums

sumX = sumX + currentPoint.getX()
sumY = sumY + currentPoint.getY()
sumZ = sumZ + currentPoint.getZ()

' Increment number of points

nPoints=nPoints+1
next
next

' compute the coordinates of the centroid

cX = sumX / nPoints
cY = sumY / nPoints
cZ = sumZ / nPoints

' create a point at the centroid

set centroid = database.createPoint(cX, cY, cZ)

' change the colour so we can distinguish this point from others
centroid.setPen(5)

Mesh Objects
The following methods are valid on mesh objects only.

Mesh Object Methods Arguments Return Value

getNumber none integer identifier

Node Methods Arguments Return Value

getX none X co-ordinate
getY none Y co-ordinate
getZ none Z co-ordinate

Element Methods Arguments Return Value

countNodes none number of nodes
getNode index (1st, 2nd, 3rd etc.) specified node object
getComputationalWeight none integer
getFeature none the geometric object that
created this element
VBScript Example
$ENGINE=VBScript

' set text window

set textWindow = getTextWindow()

' get current selection

set s = getSelection()

' extract number of items in selection

nelts = s.countObjects()
textWindow.writeLine("Number of Elements=" & nelts )

321
Chapter 8 LUSAS Programmable Interface

if nelts > 0 then

for i = 0 to nelts-1

' get selected object

set elt = s.getObject(i)

' extract item number

number = elt.getNumber()

' extract number of nodes

lnodz=elt.countNodes()

' Write to text window

textWindow.writeLine("Element Number=" & number & " Number of
Nodes=" & lnodz )

' loop nodes

for n = 1 to lnodz

' extract nodes object

set node=elt.getNode(n)

' extract node number

nnum=node.getNumber()

' extract x,y,z coords

x=node.getX()
y=node.getY()
z=node.getZ()
textWindow.writeLine("Node=" & nnum & " X=" & x & " Y=" & y & "
Z=" & z)
next
next
end if

Collection Objects
Group Methods Arguments Return Value
countPoints none number of points
countLines none number of lines
countSurfaces none number of surfaces
countVolumes none number of volumes
countGroups none number of groups
countNodes none number of nodes
countElements none number of elements
getPoint index (1st, 2nd, 3rd etc.) specified point object
getLine index (1st, 2nd, 3rd etc.) specified line object
getSurface index (1st, 2nd, 3rd etc.) specified surface object
getVolume index (1st, 2nd, 3rd etc.) specified volume object
getGroup index (1st, 2nd, 3rd etc.) specified group object
getNode index (1st, 2nd, 3rd etc.) specified node object
getElement index (1st, 2nd, 3rd etc.) specified element object
add object array()

322
 Database Entities

Group Methods Arguments Return Value

remove object array()
getName name$ name of group
setName name$
optimiseElements method$,
element solution order array()
createSuperelement title$,
include loading,
include stiffness,
include mass,
include damping,
generalised coordinates,
anchorX,
anchorY,
anchorZ

VBScript Example
Adding objects to a group:
To create a group and add a line to the group
$ENGINE=VBSCRIPT
set database = getDatabase()
' create a group
set myGroup = database.createGroup(“My Group”)
' create a line
set line = database.createLineByCoordinates(0,0,0,
10,20,30)
' add the line to the group
myGroup.Add(line)

Selection Object
This allows access to a pre-defined user defined selection in LUSAS Modeller. The
current selection mechanism is implemented. There is no method of
checking object type at present.
Method Arguments Return Value
countObjects none
getObject index (1st, 2nd, 3rd etc.) specified selected object
VBScript Example
Extracting objects from a pre-defined user selection:
‘ Prior to this script’s execution, the user should have
selected a number of lines
$ENGINE=VBScript

323
 Chapter 8 LUSAS Programmable Interface

set db=getDatabase()

' set textwindow object

set textWindow = getTextWindow()

' get current selection object

set s = getSelection()

' extract number of selected items

nlines = s.countObjects()

' loop selected lines

for i = 0 to nlines-1

' set line object

set line = s.getObject(i)

' extract number of lower order features (points)

npts = line.countLOF()

' loop points

for k = 0 to npts-1

' set point object

set currentPoint = line.getLOF(k)

' extract point data

Number = currentPoint.getNumber()
X = currentPoint.getX()
Y = currentPoint.getY()
Z = currentPoint.getZ()

' Write line to text window

text = "Point No " & Number & " X=" & X & " Y=" & Y & " Z=" & Z
textWindow.writeLine(text)
next

Error Messages
The API functions now return descriptive error messages to the script and halt
execution so that errors can be corrected. The format of the error messages is as
follows.

LUSAS Modeller ActiveX Object : error description at line number

Connecting to other applications

The current API supports the CreateObject mechanism which allows multiple
instances of other applications to be accessed from LUSAS Modeller. An example of
this would be to read in model material data from an Microsoft Excel spreadsheet.
The LUSAS Modeller implementation of the ‘createObject’ method will only be
called if the application object is specified explicitly. i.e.
Application.CreateObject(args). VBScript supports the ‘CreateObject’ method as
part of the language and so it this should be used.

324
 Connecting to other applications

The argument to the createObject function is a string identifier which is in the form
‘Application.class’ where class is the automation object exposed by the Application.
A list of automation objects can be found by looking in the
HKEY_CLASSES_ROOT section of your registry. Examples of automation objects
are.
Excel.Chart, Excel.Sheet, Excel.WorkSheet, Word.Basic

VBScript Example
Writing data to an Excel spreadsheet
$ENGINE=VBSCRIPT

' Export point coordinates from existing model to MicroSoft Excel

set db=getdatabase()

' Extract number of points in database

noPoints=db.countPoints()

' Extract max point number

mxPoint=db.getLargestPointNumber()

' Ensure model loaded

if noPoints = 0 then
msgbox "Error existing model must be loaded before running this
script"
else

' Open Excel application

set ExcelApp = application.createObject("Excel.Application")

' Set Names of workbook and worksheet

call initialiseExcelApp(ExcelApp, "Lusas WorkBook", "Lusas Output")

' Set Objects

set WorkBook = ExcelApp.WorkBooks(1)
set WorkSheet= WorkBook.WorkSheets(1)

' Number of points

WorkSheet.Cells(1,1).Value = noPoints

' Row headers

WorkSheet.Cells(2,1).Value = "No."
WorkSheet.Cells(2,2).Value = "X"
WorkSheet.Cells(2,3).Value = "Y"
WorkSheet.Cells(2,4).Value = "Z"

' Output Point data to the range of cells

for i = 1 to mxPoint

' retrieve point object from Modeller Database

set point = db.getPoint(i)

' Check if point exists

if not IsNull(point) then

' point number

WorkSheet.Cells(i+2,1).Value = i

325
Chapter 8 LUSAS Programmable Interface

' retrieve values from each point object

WorkSheet.Cells(i+2,2).Value = point.getX()
WorkSheet.Cells(i+2,3).Value = point.getY()
WorkSheet.Cells(i+2,4).Value = point.getZ()
end if
next
end if

' Save Excel work book in default file directory

Fname=WorkBook.Title + ".xls"
WorkBook.SaveAs(Fname)

' Quit Excel

ExcelApp.Quit

Sub initialiseExcelApp(ExcelObj, workBookName, sheetName)

' set file directory

FilePath = "C:\TEMP\"
ExcelObj.DefaultFilePath = FilePath

' set workbook

set WB = ExcelObj.WorkBooks.Add
WB.Title = workBookName

' Set worksheet

set WS = WB.Worksheets(1)
WS.Name = sheetName
End Sub

Reading data from an Excel spreadsheet

$ENGINE=VBSCRIPT

' Create points from a MicroSoft Excel spreadsheet

' Set spreadsheet name

FileName = "C:\Temp\Lusas WorkBook.xls"

' Open spreadsheet

Set ExcelApp =application.createObject("Excel.Application")
set WorkBook = ExcelApp.Workbooks.Open(FileName)
set WorkSheet = WorkBook.WorkSheets(1)

' Recover number of points

mxPoint = WorkSheet.Cells(1,1)

' Recover point data

for i = 1 to mxPoint

' Recover point number

n = WorkSheet.Cells(i+2,1)

' Recover point coordinates

X = WorkSheet.Cells(i+2,2)
Y = WorkSheet.Cells(i+2,3)
Z = WorkSheet.Cells(i+2,4)

326
 Connecting to other applications

' Create point

set p1 = getDatabase.createPoint(X, Y, Z)
next

' Quit Excel

application.createObject("Excel.Application").Quit

327