Vizard 2.3.0 Support

conanfile.py

@@ -195,7 +195,7 @@ def requirements(self):
             self.requires("opencv/4.5.5")
 
         if self.options.get_safe("vizInterface") or self.options.get_safe("opNav"):
-            self.requires("protobuf/3.21.12")
+            self.requires("protobuf/3.21.12") # For compatibility with openCV
             self.requires("cppzmq/4.5.0")
 
     def configure(self):

docs/source/Support/bskReleaseNotes.rst

@@ -84,6 +84,8 @@ Version  |release|
 - The BSK install instructions are updated to ask users to install by first ``pip`` installing build
   required packages through ``requirements_dev.txt``.
 - Update the build process to use ``conan`` version 2.x
+- Support for Vizard release 2.3.0, including rotating frame settings and documentation for support of ``.glb`` shape files
+- ``vizProtobuffer`` upgraded to use latest C++ compiler, ``protobuf`` Python/C++ library upgraded
 
   .. warning::
 

docs/source/Vizard/VizardGUI.rst

@@ -111,12 +111,56 @@ inside a sub-folder ``VizardData`` inside the user's home directory.
 
 ``View`` Menu Item
 ------------------
-The ``View`` menu tab contains a range of Vizard options. A range of coordinate frames can be toggled on or off.
+The ``View`` menu tab contains a range of Vizard options.
+
+Coordinate Frames
+^^^^^^^^^^^^^^^^^
+A range of coordinate frames can be toggled on or off, including ``Camera Target CS``, ``All Spacecraft CS``, ``All Effector CS``, ``All Planet/Moon CS``, ``Hill Frame`` and ``Velocity Frame``.
 
 .. image:: ../_images/static/vizard-imgAxes.jpg
    :align: center
    :width: 90 %
 
+Orbit Lines
+^^^^^^^^^^^
+Both ``Osculating Orbit Lines`` and ``True Trajectory Lines`` can be shown in a variety of frames as described below. Example scenarios highlight different orbit line view settings.
+
+Osculating Orbit Lines
+~~~~~~~~~~~~~~~~~~~~~~
+The osculating orbit is the instantaneous Keplerian orbit disregarding perturbations. These lines can be shown in the following modes:
+
+- ``Celestial Body Relative Inertial`` (default). The relative celestial body is the parent by default, but can be changed through the ``Set Celestial Body (Relative Inertial)`` menu item.
+- ``Spacecraft Relative``. This mode is available in scenarios with multiple spacecraft. The relative orbit chief is selected based on the camera target, but can be changed manually through the ``Set Spacecraft Relative Orbit Chief`` menu item.
+
+True Trajectory Lines
+~~~~~~~~~~~~~~~~~~~~~
+The true trajectory lines can be shown in the following modes:
+
+- Un-corrected Inertial (default). Inertial trajectories shown with respect to the solar system origin.
+- ``Celestial Body Relative Inertial``. The relative celestial body is the parent by default, but can be changed through the ``Set Celestial Body (Relative Inertial)`` menu item. This view mode is highlighted in :ref:`scenarioOrbitManeuver` as shown below.
+
+.. image:: ../_images/static/vizard-bodyInertialFrame.jpg
+   :align: center
+   :width: 50 %
+
+- ``Spacecraft Relative``. This mode is available in scenarios with multiple spacecraft. The relative orbit chief is selected based on the camera target, but can be changed manually through the ``Set Spacecraft Relative Orbit Chief`` menu item. These can be expressed in the Hill frame, velocity frame, or inertial frame of the chief. This view mode is highlighted in :ref:`scenarioDataToViz` as shown below.
+
+.. image:: ../_images/static/vizard-scRelative.jpg
+   :align: center
+   :width: 50 %
+
+- ``Two-Body Rotating Frame``. In scenarios with two celestial bodies, the primary is selected to be the larger of the two, per 3-body problem convention. In scenarios with more than two celestial bodies, the bodies must be manually selected using through the ``Set Rotating Frame Celestial Bodies`` menu item. This view mode is highlighted in :ref:`scenarioHaloOrbit` as shown below.
+
+.. image:: ../_images/static/vizard-rotatingFrame.jpg
+   :align: center
+   :width: 50 %
+
+- ``Body-Fixed Frame``. The primary celestial body is default, but can be changed through the ``Set Body-Fixed Frame Body`` menu item. This view mode is highlighted in :ref:`scenarioAsteroidArrival` as shown below.
+
+.. image:: ../_images/static/vizard-fixedFrame.jpg
+   :align: center
+   :width: 50 %
+
 
 Edit Pointing Vector
 ^^^^^^^^^^^^^^^^^^^^
@@ -259,20 +303,14 @@ as a PNG image within the user's home directory.
 
 Import a Custom Shape Model
 ---------------------------
-When Vizard starts up it represents the spacecraft using a default CAD model called ``bsk-Sat``.  The following section illustrates how this default spacecraft model can be replaced with with a custom CAD model in an ``.obj`` file format, or by using a built-in shape primitive.
-
-.. image:: ../_images/static/vizard-ImgCAD-1.jpg
-   :align: center
-   :width: 90 %
-
-Vizard starts up showing a default spacecraft shape.  To select a different shape, a custom CAD model can be imported using the OBJ file format.  Go to the ``File`` menu and select ``Import OBJ Model``:
+When Vizard starts up it represents the spacecraft using a default CAD model called ``bsk-Sat``.  This default spacecraft model can be replaced with with a custom CAD model in an ``.obj`` or ``.glb`` file format, or by using a built-in shape primitive. Go to the ``File`` menu and select ``Import Model``:
 
 
 .. image:: ../_images/static/vizard-ImgCAD-2.jpg
    :align: center
    :width: 90 %
 
-Next, select the OBJ file that is to be imported into Vizard.
+Next, select the file that is to be imported into Vizard.
 
 
 .. image:: ../_images/static/vizard-ImgCAD-3.jpg
@@ -293,8 +331,7 @@ configured to script this OBJ import process as illustrated in :ref:`vizardSetti
 
 At this point a panel appears that allows you select the object for which you want to apply a new
 shape, and what shape you want to apply.  When ready, press `Apply Models to Selected Objects` to
-apply the custom space object shape.  Note that instead of an OBJ file a custom shape can also be
-selected such as a sphere, cylinder or cube.
+apply the custom space object shape.  Note that instead of an ``.obj`` or ``.glb`` file a custom shape can also be selected such as a sphere, cylinder or cube.
 
 .. image:: ../_images/static/vizard-ImgCAD-5.jpg
    :align: center

docs/source/Vizard/vizardAdvanced/vizardLiveComm.rst

@@ -331,6 +331,8 @@ The trainer has the option to force certain visual settings to the broadcast:
     * - ``spacecraftCSon``
     * - ``planetCSon``
     * - ``showHillFrame``
+    * - ``showVelocityFrame``
+    * - ``truePathBodySetting``
 
 See :ref:`vizardSettings` for types and descriptions of these variables.
 

docs/source/Vizard/vizardAdvanced/vizardSettings.rst

@@ -228,11 +228,20 @@ default setting for that behavior.
         to use viz default, -1 for false, 1 for true
     * - ``keyboardLiveInput``
       - string
-      - string of alphanumeric key inputs to listen for during 2-way communication    * - ``messageBufferSize``
+      - string of alphanumeric key inputs to listen for during 2-way communication
     * - ``messageBufferSize``
       - int
       - [bytes] Maximum size of vizMessages to be loaded into memory at one time,
         -1 to force loading of entire file into memory, 0 to use viz default
+    * - ``truePathRelativeBody``
+      - string
+      - String of the celestial body name to plot the true path trajectory line[s] against, empty string to use the spacecraft's primary body
+    * - ``truePathRotatingFrame``
+      - string
+      - String must contain the names of two distinct celestial bodies, separated by a space, to define the desired rotating frame for plotting true path trajectories
+    * - ``truePathFixedFrame``
+      - string
+      - String of the spacecraft or celestial body name whose rotation matrix will provide the fixed frame to plot the true path trajectory against
 
 
 While the prior settings are only read once during start up, the following settings are checked

examples/scenarioAsteroidArrival.py

@@ -501,7 +501,12 @@ def run(show_plots):
                                                   # , saveFile=fileName
                                                   )
         viz.epochInMsg.subscribeTo(gravFactory.epochMsg)
+
         viz.settings.showCelestialBodyLabels = 1
+        viz.settings.showSpacecraftLabels = 1
+        viz.settings.truePathFixedFrame = "bennu"
+        viz.settings.trueTrajectoryLinesOn = 5  # relative to celestial body fixed frame
+
         viz.settings.scViewToPlanetViewBoundaryMultiplier = 100
         viz.settings.planetViewToHelioViewBoundaryMultiplier = 100
         viz.settings.orbitLinesOn = -1

examples/scenarioDataToViz.py

@@ -172,6 +172,8 @@ def run(show_plots, attType):
         viz = vizSupport.enableUnityVisualization(scSim, simTaskName, scList
                                                   # , saveFile=fileName
                                                   )
+
+        viz.settings.trueTrajectoryLinesOn = 2  # relative to chief spacecraft
         viz.settings.showSpacecraftLabels = 1
         viz.settings.spacecraftShadowBrightness = 0.2
         # load CAD for target spacecraft

examples/scenarioHaloOrbit.py

@@ -183,6 +183,11 @@ def run(showPlots=True):
     viz = vizSupport.enableUnityVisualization(scSim, simTaskName, scObject,
                                               # saveFile=__file__
                                               )
+    viz.settings.showCelestialBodyLabels = 1
+    viz.settings.mainCameraTarget = "earth"
+    viz.settings.trueTrajectoryLinesOn = 4
+    viz.settings.truePathRotatingFrame = "earth moon"
+
     # Initialize simulation
     scSim.InitializeSimulation()
 
@@ -316,5 +321,3 @@ def run(showPlots=True):
     run(
         True    # Show plots
     )
-
-

examples/scenarioOrbitManeuver.py

@@ -212,7 +212,10 @@ def run(show_plots, maneuverCase):
                                                   # , saveFile=fileName
                                                   )
         viz.settings.mainCameraTarget = "earth"
-        viz.settings.trueTrajectoryLinesOn = 1
+        viz.settings.showCelestialBodyLabels = 1
+        viz.settings.showSpacecraftLabels = 1
+        viz.settings.truePathRelativeBody = "earth"
+        viz.settings.trueTrajectoryLinesOn = 3  # relative to celestial body inertial frame
 
     #
     #   initialize Simulation

requirements.txt

@@ -6,4 +6,4 @@ tqdm
 Pillow
 requests
 bokeh
-protobuf==5.27.0
+protobuf

src/simulation/vizard/_GeneralModuleFiles/vizStructures.h

@@ -403,6 +403,9 @@ VizSettings
     int showMissionTime = 0;                              //!< flag to show the mission time instead of the simulation time. Value of 0 (protobuffer default) to use viz default, -1 for false, 1 for true
     std::string keyboardLiveInput = "";                   //!< string of alphanumeric key inputs to listen for during 2-way communication
     int64_t messageBufferSize = 0;                        //!< [bytes] Maximum size of vizMessages to be loaded into memory at one time, -1 to force loading of entire file into memory, 0 to use viz default
+    std::string truePathRelativeBody = "";                //!< String of the celestial body name to plot the true path trajectory line[s] against, empty string to use the spacecraft's primary body
+    std::string truePathRotatingFrame = "";               //!< String must contain the names of two distinct celestial bodies, separated by a space, to define the desired rotating frame for plotting true path trajectories
+    std::string truePathFixedFrame = "";                  //!< String of the spacecraft or celestial body name whose rotation matrix will provide the fixed frame to plot the true path trajectory against
 }VizSettings;
 
 

src/simulation/vizard/vizInterface/vizInterface.cpp

@@ -505,8 +505,8 @@ void VizInterface::WriteProtobuffer(uint64_t CurrentSimNanos)
 
         // define if true orbit lines should be shown
         vizSettings->set_truetrajectorylineson(this->settings.trueTrajectoryLinesOn);
-        if (abs(this->settings.trueTrajectoryLinesOn)>2) {
-            bskLogger.bskLog(BSK_WARNING, "vizInterface: The Vizard trueTrajectoryLinesOn flag must be either -1, 0, 1 or 2.  A value of %d was received.", this->settings.trueTrajectoryLinesOn);
+        if (abs(this->settings.trueTrajectoryLinesOn)>5) {
+            bskLogger.bskLog(BSK_WARNING, "vizInterface: The Vizard trueTrajectoryLinesOn flag must be either -1, 0, 1 2, 3, 4 or 5.  A value of %d was received.", this->settings.trueTrajectoryLinesOn);
         }
 
         // define if spacecraft axes should be shown
@@ -659,6 +659,9 @@ void VizInterface::WriteProtobuffer(uint64_t CurrentSimNanos)
         vizSettings->set_showmissiontime(this->settings.showMissionTime);
         vizSettings->set_keyboardliveinput(this->settings.keyboardLiveInput);
         vizSettings->set_messagebuffersize(this->settings.messageBufferSize);
+        vizSettings->set_truepathrelativebody(this->settings.truePathRelativeBody);
+        vizSettings->set_truepathrotatingframe(this->settings.truePathRotatingFrame);
+        vizSettings->set_truepathfixedframe(this->settings.truePathFixedFrame);
 
         // define actuator GUI settings
         for (size_t idx = 0; idx < this->settings.actuatorGuiSettingsList.size(); idx++) {

src/simulation/vizard/vizInterface/vizInterface.rst

@@ -59,6 +59,17 @@ The ``VizSpacecraftData`` structure, defined in :ref:`vizStructures`, contains a
       - (optional) Vector of CSS config log messages
 
 
+Handshaking Protocol
+--------------------
+``vizInterface`` facilitates the port configuration and handshaking process between BSK and Vizard. The current implementation of this protocol is defined here for developers, for use if an alternate visualization destination is desired.
+
+BSK instantiates the broadcast socket using ``zmq_bind``, and the 2-way socket using ``zmq_connect``. Vizard joins these sockets using reciprocal ``connect`` and ``bind`` structure where appropriate.
+
+The remaining complexity is with the 2-way socket, which couples BSK and Vizard in lockstep. After instantiation, ``vizInterface`` empties the socket and sends "PING" to start communication. When sending a sim update, ``vizInterface`` first sends the string "SIM_UPDATE", followed by 2 empty messages, followed by the serialized message protobuffer. It then listens for the response "OK". Periodic "PING" messages may be sent to keep the socket alive. To receive user input from Vizard, ``vizInterface`` sends the string "REQUEST_INPUT". It then collects the user input message, followed by a status string. The string "VIZARD_INPUT" signifies a successful send, while "ERROR" signifies an issue during transmission. When using ``opNav``, the string "REQUEST_IMAGE\_" is sent to request for an image from configured onboard cameras.
+
+For more specifics in message packaging and handling, see the source code for this module.
+
+
 User Guide
 ----------
 The ``vizInterface`` module can be directly configured, or setup using the helper methods in :ref:`vizSupport`.

src/utilities/vizProtobuffer/CMakeLists.txt

@@ -41,11 +41,6 @@ if(BUILD_VIZINTERFACE)
                  protobuf::protobuf
          )
 
-         set_target_properties(${PROTO_TARGET} PROPERTIES
-             CXX_STANDARD 11
-             POSITION_INDEPENDENT_CODE ON
-         )
-
          set_target_properties(${PROTO_TARGET} PROPERTIES LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/Basilisk")
          set_target_properties(${PROTO_TARGET} PROPERTIES LIBRARY_OUTPUT_DIRECTORY_DEBUG "${CMAKE_BINARY_DIR}/Basilisk")
          set_target_properties(${PROTO_TARGET} PROPERTIES LIBRARY_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}/Basilisk")