.. _usage.import:

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

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

To load a simulation file from your local computer, select :guilabel:`Load File` from the menu or use the corresponding button in the toolbar.
OVITO detects the format of the file automatically (see :ref:`list of supported formats <file_formats.input>`).
Compressed text-based files with a :file:`.gz` suffix can be read directly by OVITO.

The imported dataset will be visible in the 3d viewports as a visual object
and also appears under the `Data source` section of the :ref:`pipeline editor <usage.modification_pipeline.pipeline_listbox>` (see screenshot on the right).

The :ref:`External file <scene_objects.file_source>` panel is displayed below the pipeline editor.
It contains tool buttons for reloading the imported data file in case it was changed outside of OVITO, or for picking a different file as 
source of the :ref:`data pipeline <usage.modification_pipeline>`. Switching the imported file is useful when you have set up a 
complex data analysis pipeline and would like to reuse it on a different simulation dataset.

.. _usage.import.command_line:

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

If you launch OVITO from the terminal, you can directly specify the file(s) to load. This works both for local and :ref:`remote files <usage.import.remote>`::

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

Importing several files at once by specifying multiple path is possible. 
If they all have the same data format, they will be concatenated into an animatable trajectory.
If they have different formats, OVITO will detect whether 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>`. 

.. _usage.import.sequence:

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

OVITO can load simulation trajectories consisting of a series of snapshots. Various cases are supported by the software:

A series of separate files:
  By default, whenever you import a new simulation file, OVITO tries to detect if the file is part of a numbered sequence of files
  with similar names in the same directory. To this end, the last numeric character sequence (if any) in the filename you picked is replaced with the wildcard
  character ``*`` to generate a search pattern, which will subsequently be used to look up more files in the same directory belonging to the trajectory sequence.
  For instance, if you opened a file named :file:`anim1c_5000.dump`, OVITO will automatically generate the search pattern
  :file:`anim1c_*.dump` to find more snapshots (e.g. :file:`anim1c_0.dump`, :file:`anim1c_1000.dump`, :file:`anim1c_2000.dump`, etc). It is possible to
  manually override the generated file pattern in the input field highlighted in the screenshot or to turn off the 
  automatic discovery of file sequences by unchecking the :guilabel:`auto-generate` box.

One file containing all trajectory frames:
  OVITO automatically detects whether the imported file contains more than one simulation frame and loads all of them as an animation sequence.
  For some file types, e.g. XYZ and LAMMPS dump, this is indicated by the :guilabel:`Contains multiple timesteps`
  checkbox highlighted in the screenshot. Note that OVITO typically keeps only the data of a single frame in memory at a time.
  Subsequent frames are loaded into memory only as needed, for example if you play back the animation or move the time slider.

A pair of topology and trajectory files:
  Some MD simulation codes use separate files for the topology and the trajectory of a molecular structure. The topology file contains the static definition of
  atoms, bonds, etc. while the trajectory file contains the computed trajectories and other time-dependent data generated in the MD simulation.
  In such a case you should pick both files in the file selection dialog and import them simultaneously. OVITO recognizes automatically which 
  of the 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
  CASTEP cell                    CASTEP md/geom
  *any other supported format*   XYZ
  ============================== ======================

  The topology file will be loaded first (e.g. a LAMMPS *data* file) and a :ref:`particles.modifiers.load_trajectory` modifier 
  will be inserted into the data pipeline to load the time-dependent atomic positions
  from the trajectory file (e.g. a LAMMPS *dump* file). This modifier merges both pieces of information -the static topology and the dynamic trajectory data- into a single animated dataset.

OVITO will display a timeline and a time slider below the viewports if a simulation sequence with more than one frame
has been loaded. See the section :ref:`usage.animation` to learn more about OVITO's advanced animation capabilities.

.. _usage.import.multiple_datasets:

Visualizing multiple datasets
-----------------------------

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

   Side-by-side visualization example

OVITO allows you to insert several objects or datasets into the same three-dimensional scene.
You can import and visualize multiple datasets together in one picture as shown in the example on the right.
You can also visualize the same dataset in several different ways, either side by side or superimposing different 
visualization modes. The :ref:`branched data pipelines <clone_pipeline>` feature of OVITO 
lets you dynamically duplicate the imported dataset and process each clone in a different way.

The simplest way to include multiple datasets in one picture is to invoke the
:menuselection:`File --> Load File` menu function several times and import all datasets into the current scene.
When you import the second dataset, OVITO will ask whether to replace the already loaded dataset or not.
Select the :guilabel:`Add to scene` option in order to insert the subsequent datasets as additional objects into the scene.

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

   The pipeline selector widget in OVITO's toolbar

The *pipeline selector* widget, located in the top toolbar (see screenshot), lists all datasets and other objects 
that are part of the current scene. Each imported dataset is associated with its own data pipeline. Thus, you can apply different modifiers
to each of them. The data pipeline of the currently selected dataset is the one being displayed and edited in the
:ref:`pipeline editor <usage.modification_pipeline.pipeline_listbox>` in the command panel on the right.

.. _usage.import.positioning_objects:

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

OVITO places all imported datasets in the same standard position in the scene's global coordinate system. 
Thus, multiple datasets it will at first appear superimposed in the same spatial location, which may not be what you want.

In order to change this, you can move individual objects around and arrange them in the scene as needed. 
In the :ref:`example picture above <usage.import.multiple_datasets>` the second dataset was translated along the x-axis
to place it next to the first dataset. Moving entire datasets is done using the *Translate* tool, which is found in the top 
toolbar of OVITO:

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

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

While the *Translate* input mode is active, you can drag objects around in the viewports
using the mouse. Alternatively, you can enter the desired XYZ position of the active object into the
input fields appearing in the status bar. If you want to move only some parts of a dataset instead of the whole dataset, 
for example a group of selected particles, you can do that by inserting the :ref:`particles.modifiers.affine_transformation` modifier into 
the :ref:`data pipeline <usage.modification_pipeline>`.
