API Functions

API Functions

The functionality of GenGIS can be extended by written Python scripts which use the following API. This API exposes all data loaded into GenGIS and provides support for creating custom data visualizations and fly-through movies. The API is expanding with each new release of GenGIS. If there is a function you wish to see added please let us know.

A good way to become familiar with the API is to work through the examples in Tutorial 3.

File IO functions

openMap

Open specified map file.

• Example: openMap('X:/myData/worldMap.dem')

openLocations

Open specified location set file.

• Example: openLocations('X:/myData/location-set.csv')

openSequenceData

Open specified sequence data file.

• Example: openSequenceData('X:/myData/sequences.csv')

openTree

Open specified tree file.

• Example: openTree('X:/myData/myTree.gtm')

Console functions

write

Writes text to the GenGIS Console and to the log file.

• Example: write('Hello World!')

warning

Writes text to the GenGIS Console in red and to the log file.

• Example: warning('You have been warned.')

error

Writes text to the GenGIS Console in bright red and to the log file.

• Example: error('Seems something really bad just happened.')

GUI element functions

wxSafeYield

Yields control to pending messages in the windowing system. This must be called whenever you wish GUI elements to be updated.

• Example: wxSafeYield()

console

Show (True) or hide (False) the Console panel. Calling console without any arguments causes the visibility of the console to be toggled.

• Example: console(False)

consoleVisible

Indicates current visibility of the Console panel.

• Example: isVisibile = consoleVisible()

sidePanel

Show (true) or hide (False) the Side panel. Calling sidePanel without any arguments causes the visibility of the side panel to be toggled.

• Example: sidePanel(True)

sidePanelVisible

Indicates current visibility of the Side panel.

• Example: isVisibile = sidePanelVisible()

viewportWidth

Indicates the width of the Viewport

• Example: width = viewportWidth()

viewportHeight

Indicates the height of the Viewport

• Example: height= viewportHeight()

Map functions

viewTop

Sets the 3D terrain to a top-down view.

• Example: viewTop()

viewReset

Set the 3D terrain view to the default perspective view.

• Example: viewReset()

detail

Increase (positive numbers) or decrease (negative numbers) the level-of-detail of the map. Default value = 1.

• Example: detail()

wireframe

Display the map as a wireframe (True) or as a textured terrain (False). Calling wireframe without any arguments causes the display mode of the map to be toggled.

• Example: wireframe(True)

isWireframe

Indicates if map is currently being displayed as a wireframe (True) or textured terrain (False).

• Example: mode = isWireframe()

refresh

Redraws the terrain. It is necessary to call this functions after many Camera functions (see below).

• Example: refresh()

Camera functions

up

Move camera up by the specified number of units. Default value = 1.

• Example: up(5)

down

Move camera down by the specified number of units. Default value = 1.

• Example: down(5)

left

Move camera left by the specified number of units. Default value = 1.

• Example: left(5)

right

Move camera right by the specified number of units. Default value = 1.

• Example: right(5)

rotate

Rotate the camera counterclockwise by the specified number of degrees. Default value = 1.

• Example: rotate(-50)

pitch

Change pitch of camera by the specified number of degrees. Default value = 1.

• Example: pitch(10)

zoom

Change zo0m of camera by specified number of units. Default value = 1.

• Example: zoom(5)

getPosition

Get the current (x,y,z) position of the camera.

• Example: camPos = getPosition()

setPosition

Set (x,y,z) position of the camera.

• Example: setPosition(xPos, yPos, zPos)

getYaw

Get yaw angle of camera (in degrees).

• Example: yaw = getYaw()

setYaw

Set yaw angle of camera (in degrees).

• Example: setYaw(10)

getPitch

Get pitch of camera (in degrees).

• Example: pitch= getPitch()

setPitch

Set pitch of camera (in degrees).

• Example: setPitch(10)

Geometric primitives

Point3D(x, y, z)

Define a point in 3D space.

• Example: pt = Point3D(1.0, 0.0, 0.5)

Line3D(x, y, z)

Define a line in 3D space.

• Example: line = Line3D(Point3D(0.0, 0.0, 0.0), Point3D(1.0, 0.0, 0.5))

convertGeoCoord(northing, easting, point3D

Converts cartesian geographic coordinates (used within GenGIS) to its corresponding point in the Viewport.

• Example: convertGeoCoord(locData[0].northing, locData[1].easting, pt)

convertLatLong(latitude, longitude, point3D)

Converts geographic point specified as a lat/long to its corresponding point in the Viewport.

• Example: convertLatLong(53.22, -23.2, pt)

User-define graphical elements

Colour(red, green, blue)

Define a colour.

• Example: colour = Colour(1,0,0)

VisualLine(colour, width, style, line)

Create a visual line to be rendered in the Viewport.

• Example: line = VisualLine(Colour(1,0,0), 2, LINE_STYLE.SOLID, Line3D(Point3D(0,0,0), Point3D(1,1,1)))

addLine

Add line to Viewport.

• Example: lineId = addLine(line)
• Note: you may need to call refresh() to make the line visible in the Viewport

removeLine

Remove line with the specified id.

• Example: removeLine(lineId)
• Note: you may need to call refresh() to visibily removed the line from the Viewport

VisualMarker(colour, size, shape, position)

Create a visual marker to be rendered in the Viewport.

• Example: marker = VisualMarker(Colour(1,0,1), 6, MARKER_SHAPE.CIRCLE, Point3D(0,0,0))

addMarker

Add marker to Viewport.

• Example: markerId = addMarker(marker)
• Note: you may need to call refresh() to make the marker visible in the Viewport

removeMarker

Remove marker with the specified id.

• Example: removeMarker(markerId)
• Note: you may need to call refresh() to visibily removed the marker from the Viewport

VisualLabel(message, colour, fontSize)

Create a visual label to be rendered in the Viewport.

• Example: label = VisualLabel("Hello World", Colour(1, 0, 0), 12)
• Note: as a minimum you need to call the VisualLabel member function SetGridPosition(Point3D) or SetScreenPosition(Point3D)

addLabel

Add label to Viewport.

• Example: labelId = addLabel(label)
• Note: you may need to call refresh() to make the label visible in the Viewport

removeLabel

Remove labelwith the specified id.

• Example: removeLabel(labelId)
• Note: you may need to call refresh() to visibily removed the label from the Viewport

Misc. functions

quit

Exit GenGIS immediately.

• Example: quit()

saveImage

Save PNG image of the Viewport.

• Example: saveImage('X:/myData/screenshot.png')

dir (built-in Python function)

Return a list of all functions in the current scope.

• Example: dir()