.. _rst_file_formats:

File formats
============

AGX Dynamics specific formats
--------------------------------


This chapter explains the various file formats available for AGX Dynamics. All of the below listed file formats can be loaded with the application agxViewer.

.. _table-file-formats:

.. csv-table:: File formats
  :header: "Class", "Description"
  :widths: auto

  "**.agx**", "Binary serialization of an AGX Dynamics simulation"
  "**.aagx**", "XML serialization of an AGX Dynamics simulation"
  "**.agxPy**", "Python script using the AGX Dynamics Python scripting API"
  "**.agxPyz**", "Compressed archive including a .agxPy script file"



.agx, .aagx
^^^^^^^^^^^^^^^^

:numref:`Chapter {number} {name} <serialization_ref>` describe the procedure for storing an existing AGX simulation to disk and how to later restore it. The file formats .agx and .aagx are binary and xml versions of these serializations.


.agxPy
^^^^^^^^^^^^^^

When AGX is installed on Windows, the file format .agxPy (Python script) are associated with agxViewer.exe. In these file a function named buildScene() will be executed to build up the scene. For more information see chapter about Python scripting.


.agxPyz
^^^^^^^^^^^^

The file format .agxPyz are zipped archives containing  a Python script of the same name as the name of the archive. It can also contain textures/models and other data files required for the script to run. They can be loaded with the agxViewer application.

For example, the file ship.agxPyz *must* contain a script named: ship.agxPy in the root directory of the archive. This script will be executed by agxViewer when loaded:

.. code-block:: console

  > agxViewer ship.agxPy

Any data accessed by the script must be available in the archive (ship.agxPyz).

A standard zip command or the application agxArchive (see :numref:`agxarchive_ref`) can be used to create these archives.



.mpy
^^^^^^^^^^
This file format is an `Algoryx Momentum <https://www.algoryx.se/products/algoryx-momentum/>`_ Python scripting file. The API contains a version controlled slightly modified subset of the full AGX Dynamics Python API. .mpy files are supposed to be *attached* to a simulation, as the Momentup scripting API does not allow for creating or modifying the structure of any AGX simulation. With this scripting interface you are limited to only modify constraint state (enabled, force-range, motors, locks etc.), change the sate of rigid bodies (such as moving, changing velocity etc.) and read simulation data such as constraint and contact forces/velocity/position. The API follows the semantics of the Momentum API, so many classes/methods have slightly different names compared to the full AGX Dynamics Python API.

An example of using a .mpy file:

.. code-block:: python

  import v1.Momentum

  sim = v1.getSimulation()
  hinge = sim.getHingeJoint("AHinge")

  def OnStart(time):
      hinge.getMotor().setEnabled(True)
      hinge.getMotor().setTargetSpeed(0.1)

  def OnStep(time):
      print(hinge.getMotor().getCurrentTorque())

  def OnStop(time):
      pass


To use the above script, we save it to a file named ```enableHinge.mpy``` and attach it to an existing stored simulation (which should contain a hinge named 'AHinge'):

.. code-block:: console

  > agxViewer saved_simulation.agx --attachScript enableHinge.mpy



.mpyz
^^^^^^^^^^
Similar to .agxPyz, .mpyz is a compressed (zip) archive containing at least two files: a serialization (.agx) file with the simulation model, and one or more momentum Python scripting file (.mpy). The .agx file should have the same filename as the .mpyz file. This archive can contain more than one .mpy file, and they will all be attached to the simulation as in the example with the .mpy file.

.. code-block:: console

  > agxViewer mySimulation.mpyz

A standard zip command or the application agxArchive (see :numref:`agxarchive_ref`) can be used to create these archives.


3D Mesh formats
------------------

AGX Dynamics is capable of reading a number of 3D mesh file formats. The table :ref:`mesh file formats<table-mesh-formats>` lists the supported file types.