API Functions

From The GenGIS wiki
Jump to: navigation, search

Contents

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()