.. include:: definitions.rstinc .. _importing-model-label: ================= Importing a Model ================= The |AGXUnreal| import feature is accessible from the AGX menu in the top Menu Bar and the File tab of the AGX Mode. .. figure:: images/import/import_top_menu_file.jpg :alt: Using the menu bar to import a model. :target: _images/import_top_menu_file.jpg The import options are accessible from the AGX top menu bar item. .. figure:: images/import/import_agx_mode_file.jpg :alt: Using the AGX Mode to import a model. :target: _images/import_agx_mode_file.jpg The import options are accessible from the File tab of the AGX Mode. When importing an AGX Dynamics archive (.agx) or a URDF (.urdf) file into |AGXUnreal|, the result is a Blueprint containing the imported objects. A key point is that regardless of a model being imported from an AGX Dynamics archive or a URDF file, everything is translated to |AGXUnreal| Components and Assets and can be used in the same way. .. warning:: The resulting Blueprint derives from a base Blueprint named ``BP_Base_``. This base Blueprint should never be manually edited. If edited, the ```Model Synchronization`` feature will not work properly. Any edits should be done directly on the resulting Blueprint or instances of it. See :ref:`synchronize-model-label` for more details. .. _import-settings-label: *************** Import settings *************** When selecting ``AGX > File > Import Model to Blueprint`` and then specifying a model to import, the following dialog appears. .. figure:: images/import/import_settings.jpg :alt: Import settings. :target: _images/import_settings.jpg Import settings used during the import process. By selecting ``Ignore disabled Trimeshes``, any agxCollide::Trimesh that has collision disabled will not be imported. Only its RenderData will be imported, if it exists. This can be an efficient way to reduce the number of components imported for large models. .. _synchronize-model-label: ***************** Synchronize Model ***************** It is possible to synchronize a previously imported Blueprint against the source file it was originally imported from. This is useful for example when changes to the original source file has been made, but a complete, new, Import into |AGXUnreal| is not desired or appropriate. The ``Synchronize Model`` feature will attempt to update the Blueprint according to the selected source file but without removing user changes made in the Blueprint. .. warning:: Data loss may occur during model synchronization. The algorithm will attempt to keep user changes untouched but it cannot be guaranteed. It is recommended to use a version control or backup system for your imported models. There are two main ways to access the ``Synchronize Model`` feature from the Unreal Editor: 1. Right click the Blueprint in the ``Content Browser`` and select ``Scripted Asset Actions > AGX Synchronize Model``. .. figure:: images/import/sync_model_context_menu.jpg :alt: Synchronize Model from context menu. :target: _images/sync_model_context_menu.jpg Accessing model synchronization from the context menu. 2. From within the Blueprint, select the ``AGX Model Source`` Component and klick the ``Syncronize Model`` button. .. figure:: images/import/sync_model_button.jpg :alt: Synchronize Model from Details panel. :target: _images/sync_model_button.jpg Accessing model synchronization from the details panel of the ``AGX Model Source`` Component. .. note:: This feature requires the AGX Dynamics objects to have persistent UUID's between writes to the source file. This works automatically when using models created in e.g. `Algoryx Momentum `_. If the model is created in any other environment, for example a Python or C++ program, consistent UUIDs must be provided by that program. Limitations =========== Currently, the following Components are not supported by the ``Synchronize Model`` featured and are always ignored: * Wire * Track .. _importing-agx-archives-label: ******************************* Importing AGX Dynamics Archives ******************************* The following screenshot shows an example scene with a wheel loader model. .. figure:: images/import/import_wheelloader_agxviewer.jpg :alt: An example scene consisting of a wheel loader model. :target: _images/import_wheelloader_agxviewer.jpg An example scene consisting of a wheel loader model. When importing the example scene to a Blueprint the following is produced: .. figure:: images/import/import_wheelloader_blueprint.jpg :alt: A scene with a wheel loader model imported as a blueprint. :target: _images/import_wheelloader_blueprint.jpg A scene with a wheel loader model imported as a Blueprint. .. _import-wire-track-limitations-label: Wire and Track Import Limitation ================================ For :ref:`wire-label` and :ref:`track-label`, the complete dynamic state of the model is not preserved when imported. For example, the velocities of each lumped node of a Wire will not be preserved during the import process, however the position of the nodes will be. The result of an import of any of these models will replicate the state of the original model as far as possible, but since the information about the dynamic state is not preserved, the resulting imported model can be considered to be at rest. .. _import-unsupported-label: Models With no Import Support ============================= The following models are not supported when importing from an AGX Dynamics archive (.agx): * Terrain * Height Field What is Imported and What Isn't =============================== When importing an .agx file, only objects contained within that .agx file is imported, for example Rigid Bodies, Constraints, Materials, Wires etc. Global settings such as gravity, time step or solver settings are not imported and will be ignored. .. _importing-urdf-models-label: ********************* Importing URDF Models ********************* When selecting ``AGX > File > Import Model to Blueprint`` the following dialog appears. .. figure:: images/import/import_dialog.jpg :alt: Import dialog. :target: _images/import_dialog.jpg Import dialog. If a URDF file is selected and it contains any ``filename`` paths, an additional ``URDF Package`` section is shown. .. figure:: images/import/import_select_urdf_package_path_dir.jpg :alt: Selecting URDF package path directory. :target: _images/select_urdf_package_path_dir.jpg Specifying the URDF package directory. The directory selected here corresponds to the ``package://`` part of any ``filename`` path used in the URDF (.urdf) file and must match. This is common when e.g. having mesh files that are used in the URDF model. The figure below shows an example of this. .. figure:: images/import/import_urdf_package_path_example.jpg :alt: URDF package path example. :target: _images/urdf_package_path_example.jpg An example URDF (.urdf) file having ``package://`` as part of a filename path. Once the import procedure is complete, a Blueprint containing the imported objects will appear and can be used as normal. .. figure:: images/import/import_imported_robot_blueprint.jpg :alt: URDF model imported to Blueprint. :target: _images/imported_robot_blueprint.jpg After importing a URDF file, the result is a Blueprint containing the imported objects. Limitations =========== The URDF import feature in |AGXUnreal| supports the same features, and have the same limitations, as the `Algoryx Dynamics URDF Reader `_ except for a few things: - | URDF's ``mimic`` feature is not supported. - | Textures from mesh files such as e.g. collada (.dae) files are not supported. ************************************** Improving Blueprint Editor Performance ************************************** For very large models with several hundreds or even thousands of components, the Blueprint editor may be slow to react to user input. One way to reduce the number of components of a Blueprint is to use the setting ``Ignore disabled Trimeshes`` during the import process. See :ref:`import-settings-label` for more information about import settings. To improve context menu responstime in the Blueprint ``Event Graph``, it is recommended to de-activate the ``Context Sensitive`` setting shown in the image below. .. figure:: images/import/import_context_sensitive_option.jpg :alt: De-activate context sensitive option. :target: _images/context_sensitive_option.jpg By right-clicking anywhere in the ``Event Graph`` the ``Context Sensitive`` option can be de-activated.