Scripting Functions

<< Previous: Scripting Overview

Next: Scripting Example >>


Cosmographia scripting interface provides functions for:

Functions for Script Execution Timing and Annotations

The Cosmographia scripting interface provides the following functions for script execution timing and annotations:
Function
Description
wait(dur)
delays execution of the next script step by dur seconds.
displayNote(text,dur)
displays text at the top of the screen for dur seconds.

Functions for Time Manipulation

The Cosmographia scripting interface provides the following functions for time manipulation:
Function
Description
setTime(time)
sets time to time given as a numeric Julian Date TDB (e.g. 2457267.500000), a UTC string (e.g. “2029-07-17 23:00:00.001 UTC”), or a TDB string (e.g. “2016-01-01 00:00:00.000 TDB”).
setTimeRate(rate)
sets time rate to the specified numeric rate in seconds.
reverseTime()
reverses time direction.
pause()
pauses time.
unpause()
un-pauses time.
faster2x()
increases time rate 2 times.
slower2x()
decreases time rate 2 times.
faster10x()
increases time rate 10 times.
slower10x()
decreases time rate 10 times.
forwardDay()
jumps time 1 day forward.
backDay()
jumps time 1 day backward.
forwardYear()
jumps time 1 year forward.
backYear()
jumps time 1 year backward.

Functions for Selecting and Going to Objects

The Cosmographia scripting interface provides the following functions for selecting, setting as the center, and going to objects:
Function
Description
selectObject(name)
selects the object with name name.
deselectSelectedObject()
de-selects the currently selected object.
setCentralObject(name)
sets the object with name name as the central object.
gotoObject(name[,dur])
over dur seconds, moves the camera to and points it at the object with the name name, sets this object as the center, and sets the rendering frame to ICRF. If dur is omitted, the default duration is used.
gotoHome(name[,dur])
over dur seconds, moves the camera to the “home” position above the Solar System looking down on it, sets Sun as the center, and sets the rendering frame to inertial. If dur is omitted, the default duration is used.
moveToPov(name,vec1,vec2,vec3,dur)
over dur seconds, sets the body with the name name as the center and its body-fixed frame as the rendering frame, moves the camera to the position vec1, in kilometers, relative to it in its body-fixed frame, and orients the camera to look along the direction vec2 while aligning the camera up direction with the direction vec3 with both vec2 and vec3 specified in the body’s body-fixed frame.
For example cosmo.moveToPov(“Mars”, [0.0,10000.0,0.0], [0.0,-1.0,0.0], [0.0,0.0,-1.0], 5.0) takes 5.0 seconds to place the camera at [0.0,10000.0,0.0] relative to “Mars” in the Mars body-fixed frame while pointing the camera at Mars ([0.0,-1.0,0.0]) and aligning the Mars south pole ([0.0,0.0,-1.0]) with the camera up direction.

Functions for Changing Camera Position and Orientation

The Cosmographia scripting interface provides the following functions for changing the camera position and orientation at the same time:
Function
Description
circleCenterLeft(ang,dur)
over dur seconds, moves camera around the central object by ang degrees going left in the camera’s horizontal plane.
circleCenterRight(ang,dur)
over dur seconds, moves camera around the central object by ang degrees going right in the camera’s horizontal plane.
circleCenterUp(ang,dur)
over dur seconds, moves camera around the central object by ang degrees going up in the camera’s vertical plane.
circleCenterDown(ang,dur)
over dur seconds, moves camera around the central object by ang degrees going down in the camera’s vertical plane.

Functions for Changing Only Camera Orientation

The Cosmographia scripting interface provides the following functions for changing just the camera orientation:
Function
Description
pointAtObject(name)
points the camera at the object with name name.
rollLeft(ang,dur)
over dur seconds, rotates the camera counterclockwise (left) by ang degrees about the view direction.
rollRight(ang,dur)
over dur seconds, rotates the camera clockwise (right) by ang degrees about the view direction.
rollToBodyFixedVector(name,vec,dur)
over dur seconds, rotates the camera about the view direction to align its up direction with the vector vec in the body-fixed frame of the object with name name.
panLeft(ang,dur)
over dur seconds, rotates the camera left by ang degrees about the vertical direction.
panRight(ang,dur)
over dur seconds, rotates the camera right by ang degrees about the vertical direction.
tiltUp(ang,dur)
over dur seconds, rotates the camera up by ang degrees about the horizontal direction.
tiltDown(ang,dur)
over dur seconds, rotates the camera down by ang degrees about the horizontal direction.
rotateAboutVector(vec,ang,dur)
over dur seconds, rotates the camera by ang degrees about the direction given by the vector vec in the rendering frame.
setCameraOrientation(quat)
sets the camera orientation relative to the rendering frame as specified by the SPICE-style quaternion quat.
getCameraOrientation()
returns the camera orientation relative the rendering frame as the SPICE-style quaternion (quat=cosmo.getCameraOrientation()).

Functions for Changing Only Camera Position

The Cosmographia scripting interface provides the following functions for changing just the camera position:
Function
Description
moveTowardsCenter(dist,dur)
over dur seconds, moves the camera dist kilometers closer to the central object.
moveAwayFromCenter(dist,dur)
over dur seconds, moves the camera dist kilometers farther from the central object.
dollyForward(dist,dur)
over dur seconds, moves the camera dist kilometers forward along the view direction.
dollyBackward(dist,dur)
over dur seconds, moves the camera dist kilometers backwards along the view direction.
truckLeft(dist,dur)
over dur seconds, moves the camera dist kilometers left in the horizontal direction.
truckRight(dist,dur)
over dur seconds, moves the camera dist kilometers right in the horizontal direction.
craneUp(dist,dur)
over dur seconds, moves the camera dist kilometers up in the vertical direction.
craneDown(dist,dur)
over dur seconds, moves the camera dist kilometers down in the vertical direction.
translateAlongVector(vec,dist,dur)
over dur seconds, moves the camera dist kilometers along the direction vec in the rendering frame.
moveToDistanceFromCenter(dist,dur)
over dur seconds, moves the camera to the location dist kilometers away from the central object on the camera-center line.
getDistanceFromCenter()
returns the distance from the central object in kilometers (dist=cosmo.getDistanceFromCenter()).
setCameraPosition(vec)
puts the camera at the location vec relative to the central object in the rendering frame.
For example cosmo.setCameraPosition([0.0,10000.0,0.0]) puts the camera at 10,000 kilometers away from the center on the rendering frame’s Y axis.
getCameraPosition()
returns the camera position vector relative to the central object in the rendering frame (vec=cosmo.getCameraPosition())

Functions for Changing Rendering Frame

The Cosmographia scripting interface provides the following functions for selecting various rendering frames:
Function
Description
setCameraToInertialFrame()
set the rendering frame to ICRF.
setCameraToBodyFixedFrame()
sets the rendering frame to the body-fixed frame of the central object.
setCameraToSynodicFrame()
sets the rendering frame to the synodic frame based on for the central object and the object that it orbits.
setCameraToLockedFrame(name)
sets the rendering frame to the locked frame based on the central object and the object with the name name.
trackObject(name)
sets the rendering frame to the locked frame based on the central object and the object with the name name.

Functions for Changing Objects’ Visual Attributes

The Cosmographia scripting interface provides the following functions for changing visual attributes of objects:
Function
Description
showObject(name)
shows the object with the name name.
hideObject(name)
hides the object with the name name.
showIcrfFrame(name)
shows the ICRF frame centered at the object with the name name.
hideIcrfFrame(name)
hides the ICRF frame centered at the object with the name name.
showBodyFixedFrame(name)
shows the body-fixed frame of the object with the name name centered at that object.
hideBodyFixedFrame(name)
hides the body-fixed frame of the object with the name name centered at that object.
showSpiceFrame(name,frame)
shows the SPICE frame with the name frame centered at the object with the name name.
hideSpiceFrame(name,frame)
hides the SPICE frame with the name frame centered at the object with the name name.
showVelocityVector(name)
shows the velocity direction of the object with the name name.
hideVelocityVector(name)
hides the velocity direction of the object with the name name.
showDirectionVector(name,target)
shows the direction from the object with the name name to the object with the name target.
hideDirectionVector(name,target)
hides the direction from the object with the name name to the object with the name target.
showTrajectory(name)
shows the trajectory of the object with the name name.
hideTrajectory(name)
hides the trajectory of the object with the name name.
trajectoryWidth(name,width)
sets the width of the line used to plot the trajectory of the object with the name name to width pixels.
showLatLongGrid(name)
shows the latitude-longitude grid on the object with the name name.
hideLatLongGrid(name)
hides the latitude-longitude grid on the object with the name name.
showTerminator(name)
shows the terminator line on the object with the name name.
hideTerminator(name)
hides the terminator line on the object with the name name.
labelFade(name,dist)
sets the distance dist at which the label of the object with the name name should fade.

Functions for Changing Visualization Settings

The Cosmographia scripting interface provides the following functions for changing visualization setting:
Function
Description
showAllObjects()
shows all objects.
hideAllObjects()
hides all objects.
showPlanetOrbits()
shows orbits of all planets.
hidePlanetOrbits()
hides orbits of all planets.
showEquatorialGrid()
shows the ICRF longitude-latitude grid on the sky.
hideEquatorialGrid()
hides the ICRF longitude-latitude grid from the sky.
showEcliptic()
shows the Ecliptic plane line marker on the sky.
hideEcliptic()
hides the Ecliptic plane line marker from the sky.
showCenterIndicator()
shows the central object indicator.
hideCenterIndicator()
hides the central object indicator.
showInfoText()
shows the info text in the top left and right corners of the window.
hideInfoText()
hides the info text.
showLabels()
shows object labels.
hideLabels()
hides object labels.
showLatLongLabels()
shows latitude-longitude grid labels.
hideLatLongLabels()
hides latitude-longitude grid labels.
showSurfaceFeatureLabels()
shows surface feature labels.
hideSurfaceFeatureLabels()
hides surface feature labels.
showObservationLabels()
shows observation labels.
hideObservationLabels()
hides observation labels.
showConstellationFigures()
shows constellation figures.
hideConstellationFigures()
hides constellation figures.
showConstellationNames()
shows constellation names.
hideConstellationNames()
hides constellation names.
showStarNames()
shows star names.
hideStarNames()
hides star names.
showStatusMessages()
shows default status messages.
hideStatusMessages()
hides default status messages.
showSpiceMessages()
shows missing SPICE data messages.
hideSpiceMessages()
hides missing SPICE data messages.

Functions for Loading/Unloading Catalog Files

The Cosmographia scripting interface provides the following functions for loading and unloading catalog files:
Function
Description
loadCatalogFile(file)
loads the catalog file named file. The file name can be given with an absolute path or with a relative path to directory from which Cosmographia is launched.
unloadLastCatalog()
unloads the last loaded catalog file.

Functions for Capturing Screenshots

The Cosmographia scripting interface provides the following functions for capturing screenshots:
Function
Description
saveScreenShot()
saves a screenshot to a file. The program will prompt the user to enter a file name when this function is invoked.
saveScreenShotToFile(file)
saves a screenshot to a file named file. The file name can be given with an absolute path or with a relative path to directory from which Cosmographia is launched.

Functions for Controlling Application/Window Settings

The Cosmographia scripting interface provides the following functions for controlling application and window settings:
Function
Description
showToolBar()
shows the left toolbar.
hideToolBar()
hides the left toolbar.
minimizeWindow()
minimizes the Cosmographia window.
showFullScreen()
switches the Cosmographia window to the full screen mode.
showNormalWindow()
switches the Cosmographia window to the normal window mode.
quit()
makes the program quit.