.. _usage.import:

Data import
===========

.. figure:: /images/scene_objects/file_wildcard_pattern.*
   :figwidth: 30%
   :align: right

   File source panel

To load a simulation file or structure, select :menuselection:`File --> Load File` from the menu or use the corresponding toolbar button. OVITO automatically detects the file format (see :ref:`list of supported formats <file_formats.input>`). Compressed files with a :file:`.gz` or :file:`.zst` suffix can be opened directly if the contained format is supported. To import data in a custom format, you can write your own :ref:`file reader in Python <writing_custom_file_readers>` |ovito-pro|.

After import, the dataset appears in the 3D viewport(s) as a visual object and as a `data source` in the :ref:`pipeline editor <usage.modification_pipeline.pipeline_listbox>` (see screenshot).

The :ref:`External file <scene_objects.file_source>` panel below the pipeline editor provides tools for reloading the imported data file or picking a different file as the source of the :ref:`data pipeline <usage.modification_pipeline>`. This is useful if you want to reuse a complex data analysis pipeline with a different simulation.

.. _usage.import.command_line:

Command line usage
------------------

When launching OVITO from the terminal, you can specify the file(s) to load directly. This works for local files and :ref:`files stored in remote locations <usage.import.remote>`:

.. code-block:: shell

  ovito /path/filename
  ovito sftp://hostname/path/filename
  ovito https://www.website.org/path/filename

You can import multiple files at once. If they have the same format, they will be concatenated into an animatable trajectory. If they have different formats, OVITO will detect if they represent a pair of topology/trajectory files (see next section).
Otherwise, they will be inserted as :ref:`separate objects into the scene <usage.import.multiple_datasets>` |ovito-pro|.

You can also specify a directory instead of a file:

.. code-block:: shell

  ovito /path/directory
  ovito .

The path will be set as current working directory and the file import dialog will open in that directory.

.. _usage.import.sequence:

Simulation trajectories
-----------------------

OVITO supports loading simulation trajectories that consist of a series of snapshots:

A series of separate files:
  OVITO detects if the file is part of a numbered sequence of files with similar names in the same directory. For example, if you open :file:`anim1c_5000.dump`, OVITO generates the search pattern :file:`anim1c_*.dump` to find more files (e.g., :file:`anim1c_0.dump`, :file:`anim1c_1000.dump`). The search pattern is generated by replacing the last numeric sequence in the filename you've picked with the wildcard character `*`. You can manually override the generated pattern or turn off the automatic file discovery by toggling the :guilabel:`auto-generate` box.

A file containing a trajectory:
  OVITO detects if the imported file contains more than one simulation frame and loads all of them as an animation sequence. For some file types, e.g., :ref:`XYZ <file_formats.input.xyz>` and :ref:`LAMMPS dump <file_formats.input.lammps_dump>`, this is indicated by the :guilabel:`Contains multiple timesteps` checkbox. Note that OVITO typically keeps only the current trajectory frame in memory at a time to reduce the memory footprint.

A pair of topology and trajectory files:
  Some MD simulation codes use separate files for the topology and the simulation trajectory of a molecular structure. The topology file contains static definitions of atoms and bond connectivity, while the trajectory file contains the computed trajectories and other time-dependent simulation data. You should pick both files in the file selection dialog to import them simultaneously. OVITO recognizes which file is the topology file and which one is the trajectory file based on the following table:

  ============================== ======================
  Topology format                Trajectory format
  ============================== ======================
  LAMMPS data                    LAMMPS dump
  Gromacs GRO                    Gromacs XTC/TRR
  CASTEP cell                    CASTEP md/geom
  *any other supported format*   XYZ
  ============================== ======================

  The topology file is loaded as pipeline data source, and a :ref:`particles.modifiers.load_trajectory` modifier is inserted into the data pipeline to load the time-dependent atomic positions from the trajectory file. This pipeline stage merges the static topology with the dynamic trajectories into a combined animated dataset.

OVITO displays a timeline and a time slider below the viewports if a simulation sequence with more than one frame is loaded. See :ref:`usage.animation` to learn more about OVITO's animation capabilities.

.. _usage.import.multiple_datasets:

Visualizing multiple datasets |ovito-pro|
-----------------------------------------

.. figure:: /images/usage/importexport/datasets_side_by_side.*
   :figwidth: 40%
   :align: right

   Side-by-side visualization example

OVITO Pro allows you to insert multiple objects or datasets into the same 3D scene. You can visualize multiple simulations together in one picture or visualize the same dataset in different ways. The :ref:`branched data pipelines <clone_pipeline>` feature of OVITO Pro lets you duplicate the imported dataset and dynamically process each copy in different ways.

To insert multiple simulations into one scene, use the :menuselection:`File --> Load File` menu function multiple times. When importing the second dataset, select the :guilabel:`Add to scene` option to insert subsequent datasets as additional objects instead of replacing the existing one.

.. figure:: /images/usage/importexport/pipeline_selector.*
   :figwidth: 60%
   :align: right

   The pipeline selector widget in OVITO's toolbar lets you switch between pipelines.

The *pipeline selector* in the top right corner of the OVITO window lists all simulation files and other objects in the current scene. Each imported file has its own data pipeline, allowing you to manipulate the data. The currently selected data pipeline is displayed in the :ref:`pipeline editor <usage.modification_pipeline.pipeline_listbox>` in the right command panel.

.. _usage.import.positioning_objects:

Positioning objects in the scene
--------------------------------

OVITO places all imported simulation files in the same scene coordinate space. You can move individual datasets around if needed. In the :ref:`example picture above <usage.import.multiple_datasets>`, the second dataset was translated along the x-axis to place it side by side with the first dataset. Use the *Translate* tool in the top toolbar to move objects:

.. image:: /images/usage/importexport/translate_tool.*
   :width: 35%

.. image:: /images/usage/importexport/translate_tool_numeric_fields.*
   :width: 35%

While the *Translate* mode is active, drag datasets in the viewports using the mouse or enter the desired XYZ position in the status bar input fields. To move only parts of a dataset, e.g., just a subset of particles, insert the :ref:`particles.modifiers.affine_transformation` modifier in the :ref:`data pipeline <usage.modification_pipeline>`.
