Skip to main content

​
Scripting Vizard settings from Basilisk

All scriptable Vizard settings live on the viz.settings object returned by enableUnityVisualization(). These settings are applied once at startup. If a setting is omitted, Vizard uses its own default. For flag-type settings, use 1 to enable, -1 to disable, and 0 to defer to the Vizard default. 
viz = vizSupport.enableUnityVisualization(scSim, simTaskName, scObject,
                                          saveFile=fileName)
viz.settings.ambient = 0.5
viz.settings.spacecraftCSon = 1
viz.settings.orbitLinesOn = 1
viz.settings.showHillFrame = 1

​
Selected startup settings

SettingTypeDescription
ambientfloat 0–1Ambient scene lighting level
spacecraftCSon(-1, 0, 1)Show spacecraft coordinate axes
planetCSon(-1, 0, 1)Show planet coordinate axes
showHillFrame(-1, 0, 1)Show Hill frame of the camera target spacecraft
showVelocityFrame(-1, 0, 1)Show velocity frame of the camera target spacecraft
orbitLinesOn(-1, 0, 1, 2)Show osculating orbit lines (1 = parent-body-relative, 2 = chief-relative)
trueTrajectoryLinesOn(-1, 0, 1–5)Show true trajectory lines in various reference frames
skyBoxstringStar background: "" for NASA SVS starmap, "ESO" for Milky Way, "black", or a file path
atmospheresOff(-1, 0, 1)Disable planet atmosphere shaders
mainCameraTargetstringSpacecraft or celestial body to target at startup
forceStartAtSpacecraftLocalView(-1, 0, 1)Lock the camera in spacecraft-centric view
spacecraftSizeMultiplierfloat > 0Scale spacecraft size in planet-centric view
show24hrClock(-1, 0, 1)Use 24-hour mission clock
showMissionTime(-1, 0, 1)Display mission date/time instead of elapsed time
messageBufferSizeint (bytes)Maximum vizMessages to load into memory; -1 forces loading the entire file
customGUIReferenceHeightfloat (pixels)Override automatic GUI scale (must be > 300)

​
Live settings

Some settings update with every message sent. Access them through viz.liveSettings: 
viz.liveSettings.relativeOrbitChief = "myChiefSC"
viz.liveSettings.terminateVizard = True  # shuts down Vizard cleanly
SettingTypeDescription
targetLineListvector<PointLine>Lines between two scenario objects, redrawn each time step
relativeOrbitChiefstringChief spacecraft for relative orbit calculations
terminateVizardboolShuts Vizard down cleanly when True
playbackPausedboolPauses Vizard playback
playbackInRealTimeint+1 for real-time, -1 for frame-rate
playbackMultiplierintSets playback speed to 2^n

​
Pointing lines

A pointing line draws a colored heading arrow from one object to another. Use createPointLine() to script them: 
viz = vizSupport.enableUnityVisualization(scSim, simTaskName, scObject,
                                          saveFile=fileName)
vizSupport.createPointLine(viz, toBodyName='earth_planet_data',
                           lineColor=[0, 0, 255, 255])
vizSupport.createPointLine(viz, toBodyName='sun_planet_data',
                           lineColor='yellow')
The fromBodyName parameter defaults to the primary spacecraft if omitted. The lineColor accepts a color name string or a four-element RGBA list with values 0–255.

​
Keep-in and keep-out cones

Cones indicate whether a body-fixed axis is within or outside a specified angle to a target body. Use createConeInOut(): 
vizSupport.createConeInOut(viz,
    toBodyName='earth',
    coneColor='teal',
    normalVector_B=[1, 0, 0],
    incidenceAngle=30 * macros.D2R,
    isKeepIn=True,
    coneHeight=5.0,
    coneName='sensorCone')
Set isKeepIn=False for a keep-out cone. The cone turns solid when the constraint is violated.

​
Ground and satellite locations

Use addLocation() to place a location marker on a planet or spacecraft and visualize line-of-sight links: 
vizSupport.addLocation(viz,
    stationName='Boulder Station',
    parentBodyName='earth',
    r_GP_P=groundStation.r_LP_P_Init,
    fieldOfView=np.radians(160.),
    color='pink',
    range=1000.0)
The stationName must be unique. Call changeLocation() with the same arguments to update a location’s properties at runtime.

​
Actuator GUI options

Script the actuator panel and HUD visibility with setActuatorGuiSetting(): 
vizSupport.setActuatorGuiSetting(viz,
    viewRWPanel=True,
    viewRWHUD=True,
    viewThrusterPanel=True,
    viewThrusterHUD=True)

​
Custom spacecraft appearance

​
OBJ/GLB model import

Script a custom model import so it applies every time the scenario runs: 
vizSupport.createCustomModel(viz,
    modelPath="/path/to/Topex-Posidon-composite.obj",
    scale=[2, 2, 10])
The modelPath can be absolute or relative. Relative paths are resolved against the playback .bin file location for recorded scenarios, or the scenario’s working directory for live streaming. You can also use built-in shape primitives instead of a file: 
vizSupport.createCustomModel(viz, modelPath="SPHERE")
vizSupport.createCustomModel(viz, modelPath="CYLINDER")
vizSupport.createCustomModel(viz, modelPath="CUBE")
vizSupport.createCustomModel(viz, modelPath="CAPSULE")

​
Custom textures

Apply a custom texture and optional normal map alongside the model: 
vizSupport.createCustomModel(viz,
    modelPath="/path/to/model.obj",
    customTexturePath="/path/to/texture.png",
    normalMapPath="/path/to/normalmap.png",
    color=[200, 200, 200, 255])
Supported image formats: .jpg, .bmp, .exr, .gif, .hdr, .iff, .pict, .png, .psd, .tga, .tiff. Maximum image dimensions are 16384 × 16384 pixels.
Models applied to spacecraft are assumed to be in meters. Models applied to celestial bodies are assumed to be in kilometers.

​
Unity Addressable bundles

For complex models, build them into Unity Addressable bundles using the VizardPublicContent Unity project. This approach uses Unity’s internal model pre-processing pipeline, which gives better runtime performance than the OBJ importer.
Addressable bundles must be built with the same Unity Editor version used to compile your version of Vizard. Check File > About Vizard to find the Unity version.
1

Determine the Unity version

Open Vizard, load a scenario, and go to File > About Vizard to see the Unity version.
2

Download and install the matching Unity Editor

Download the correct Unity Editor version from the Unity archive. Include build support for all target platforms (macOS, Linux, Windows).
3

Download the VizardPublicContent project

Download the VizardPublicContent Unity project and open it in Unity. If Unity warns about a version mismatch, select the installed version and continue.
4

Import and prepare your models

Follow the ImportingCustomModels guide to prepare your models for export.
5

Build and export the bundle

Follow the ExportingCustomModelBundles guide. Build a separate bundle for each target platform.
6

Install the bundle

Unzip the bundle and place its contents directly in the platform-specific CustomModels directory. See Download for the correct path on each OS.
7

Reference the model in your scenario

Assign the bundle’s model key to modelDictionaryKey in your Basilisk script:
viz = vizSupport.enableUnityVisualization(scSim, simTaskName, scObject,
                                          saveFile=fileName,
                                          modelDictionaryKeyList='myCustomKey')

​
Multi-spacecraft visualization

Pass a list of spacecraft objects to enableUnityVisualization(). Each spacecraft is identified by its ModelTag. 
viz = vizSupport.enableUnityVisualization(scSim, simTaskName,
                                          [scObject1, scObject2, scObject3],
                                          saveFile=fileName)
When more than one spacecraft is present in a planet-centric or heliocentric view, Vizard automatically switches to 2D sprite rendering to maintain performance. Customize sprites per spacecraft: 
viz = vizSupport.enableUnityVisualization(scSim, simTaskName,
                                          [scObject1, scObject2, scObject3],
                                          spriteList=[
                                              None,
                                              vizSupport.setSprite("STAR", color="red"),
                                              None
                                          ],
                                          saveFile=fileName)
None entries keep the default circle sprite. Passing None as the spriteList argument entirely uses the default for all spacecraft.

​
Live communication modes

Vizard supports three live communication modes.

​
liveStream

Basilisk and Vizard run in lockstep. After each time step, Basilisk waits for Vizard to acknowledge before continuing. This is the best mode for interactive local visualization. 
viz = vizSupport.enableUnityVisualization(scSim, simTaskName, scObject,
                                          liveStream=True)
The default connection address is tcp://0.0.0.0:5556. You can change it: 
viz.reqComProtocol = "tcp"
viz.reqComAddress  = "127.0.0.1"
viz.reqPortNumber  = "5556"
In Vizard, enter the socket address and select DirectComm at the startup panel.

​
broadcastStream

Basilisk broadcasts read-only messages in a publish/subscribe pattern. Multiple Vizard instances can subscribe simultaneously. Basilisk does not wait for any subscriber to connect before executing. 
viz = vizSupport.enableUnityVisualization(scSim, simTaskName, scObject,
                                          broadcastStream=True)
You can run both modes at once for training scenarios where an instructor uses liveStream to interact with the simulation while students subscribe via broadcastStream: 
viz = vizSupport.enableUnityVisualization(scSim, simTaskName, scObject,
                                          liveStream=True,
                                          broadcastStream=True)
The default broadcast address is tcp://0.0.0.0:5570. In Vizard, enter the broadcast address and select Receive Only.

​
noDisplay

Vizard runs headless and only renders the scene when an image is requested from Basilisk. This is a high-performance mode for optical navigation that does not show a graphical window. 
viz = vizSupport.enableUnityVisualization(scSim, simTaskName, scObject,
                                          noDisplay=True)

​
Interactive event panels

In liveStream mode you can display interactive dialog panels in Vizard and read the user’s responses back in Basilisk.

​
Creating a panel

powerPanel = vizInterface.VizEventDialog()
powerPanel.eventHandlerID = "Power Mode Panel"
powerPanel.displayString = "Set system power mode:"
powerPanel.userOptions.append("Nominal")
powerPanel.userOptions.append("Low-Power")
powerPanel.useConfirmationPanel = True

viz.vizEventDialogs.append(powerPanel)

​
Reading responses

for i in range(int(totalDuration / inputTimeStep)):
    currentTime += inputTimeStep
    scSim.ConfigureStopTime(currentTime)
    scSim.ExecuteSimulation()

    userInputs = viz.userInputMsg.read()
    keyInputs   = userInputs.keyboardInput
    eventInputs = userInputs.vizEventReplies

    for response in eventInputs:
        if response.eventHandlerID == "Power Mode Panel":
            if response.reply == "Low-Power":
                pass  # apply low-power mode

​
Keyboard listeners

Register key listeners before starting the simulation: 
viz.settings.keyboardLiveInput = "pz"  # listen for 'p' (pause) and 'z' (quit)
Then check the received keys each step: 
if 'p' in keyInputs:
    # pause logic
if 'z' in keyInputs:
    # quit logic
Vizard pre-assigns several keys as hot-keys for GUI actions. If you register a key that duplicates a hot-key, Vizard displays a warning and both actions will fire.

​
Command-line launching

You can launch Vizard from the terminal and pass arguments to control startup behavior. The examples below use macOS syntax with an application named Vizard.app in /Applications. 
# Open Vizard
open /Applications/Vizard.app

# Automatically load a playback file
open /Applications/Vizard.app --args -loadFile ~/VizFiles/myScenario.bin

# Connect to a live simulation in DirectComm mode
open /Applications/Vizard.app --args -directComm tcp://0.0.0.0:5556

# Run headless (no display) for optical navigation
open /Applications/Vizard.app --args -batchmode -noDisplay tcp://0.0.0.0:5556

# Save all messages received during the run to a file
open /Applications/Vizard.app --args -saveMsgFile myOutputFile

# Record rendering and image transmission times to ~/VizardData/opNavMetrics.txt
open /Applications/Vizard.app --args -saveMetrics -noDisplay tcp://0.0.0.0:5556
Adjust the open command and application name for Linux or Windows.

​
Recording simulation output

To produce a Vizard-compatible binary recording from a Basilisk scenario, provide a saveFile name to enableUnityVisualization(): 
viz = vizSupport.enableUnityVisualization(scSim, simTaskName, scObject,
                                          saveFile="myScenario")
Output is written to _VizFiles/myScenario_UnityViz.bin relative to the scenario directory. Pass a full path ending in .bin to specify the location explicitly. You can also save messages from a running or completed Vizard session via File > Save Messages to File inside the application. This stores data to ~/VizardData/.

​
Simulation epoch

Vizard can show mission date/time in addition to elapsed simulation time. Set the epoch by subscribing the vizInterface module to an EpochMsgPayload message: 
viz.epochInMsg.subscribeTo(epochMsg)
If no epoch is provided, Basilisk defaults to January 1, 2019, 00:00:00.

Build docs developers (and LLMs) love

Get started for freeTalk to us