.. _scenarioCustomGravBody:

scenarioCustomGravBody
======================

.. raw:: html

    <iframe width="560" height="315" src="https://www.youtube.com/embed/uUomHSGQW3c" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Overview
--------

Demonstrates how to setup a custom gravity object in Xmera that is not directly supported by
the ``simIncludeGravBody.py`` file.  In this simulation the sun is created using standard values, the Earth
is created using custom values, and the asteroid Itokawa is created with custom values.

.. image:: /_images/static/scenarioCustomGravObject.jpg
   :align: center

Further, the Vizard binary file is setup to load up a custom CAD model for the asteroid. The spacecraft
orbit is defined relative to the asteroid.  Note, this feature requires :ref:`Vizard <vizard>` version 1.8 or higher.

The script is found in the folder ``xmera/examples`` and executed by using::

      python3 scenarioCustomGravBody.py

The simulation layout is shown in the following illustration.  A single simulation process is created
which contains both modules.

.. image:: /_images/static/test_scenarioCustomGravBody.svg
   :align: center

:ref:`planetEphemeris` is used to create the planet ephemeris states. The sun is assumed to be stationary,
while Earth is on a circular orbit and Itokawa is on its elliptical heliocentric orbit.

The method ``createCustomGravObject()`` is used to create the BSK grav bodies for both earth and Itokawa.
The earth body is already supported in :ref:`simIncludeGravBody`, but in this script we show how this could
be customized.  The gravity body ephemeris states are connected to the :ref:`planetEphemeris` planet
state output messages.

Finally, the recorded states will all be relative to the inertial origin at the sun.  :ref:`planetEphemeris` does not
have the ``zeroBase`` capability as :ref:`spiceInterface` has.  This script also records the asteroid
states so that the plot is done of the spacecraft motion relative to the asteroid.

The simulation executes and shows a plot of the spacecraft motion relative to the asteroid.

Illustration of Simulation Results
----------------------------------

::

    show_plots = True

.. image:: /_images/Scenarios/scenarioCustomGravBody1.svg
   :align: center