Description
===========

This plugin allows to open particle tracking results from multiple formats into the Napari
Tracks Layer.

Supported formats
=================

The formats currently supported by this plugin are:

CSV
---

The most basic format to store particle tracking tracks is a CSV file containing the tracks table.
In this format each line is a particle and each column a property of the particle. The table
headers must be `TrackID`, `t`, `x`, `y`, `z`. Note that the header order does not matter:

.. list-table:: CSV structure example
   :header-rows: 1

   * - TrackID
     - t
     - x
     - y
     - z
   * - 0
     - 16
     - 41.5828343348868
     - 47.505930020081664
     - 0
   * - 0
     - 17
     - 41.48425270538317
     - 51.6023835597057
     - 0

The raw CSV file is a classical comma-separated values format:

.. code-block::
    :linenos:

    TrackID,t,x,y,z
    0,16, 41.5828343348868, 47.505930020081664, 0
    0,17, 41.48425270538317, 51.6023835597057, 0
    ...

.. warning::
    This CSV format does **not** support split and merge events

TrackMate
---------

The TrackMate format is the XML model file générated by the [TrackMate](https://imagej.net/plugins/trackmate/) Fiji
plugin.
The XML file from TrackMate should not be manually modified and and contains a `Model` element:

.. code-block:: xml
    :linenos:

    <?xml version="1.0" encoding="UTF-8"?>
    <TrackMate version="6.0.2">
    ...
    <Model spatialunits="pixel" timeunits="sec">
        <FeatureDeclarations>
          <SpotFeatures>
            <Feature feature="QUALITY" name="Quality" shortname="Quality" dimension="QUALITY" isint="false" />
            <Feature feature="POSITION_X" name="X" shortname="X" dimension="POSITION" isint="false" />
    ...


All the particles features from the TrackMate model file are loaded in the napari tracks properties.

.. note::
    This format supports split and merge events

Icy
---

The Icy format is a XML file generated by the [Icy](http://icy.bioimageanalysis.org/plugin/spot-tracking/) software.
The XML file from ICY should not be manually modified and starts with the `root` element:

.. code-block:: xml
    :linenos:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
      <trackfile version="1" />
      <trackgroup>
        <track id="265713726">
          <detection t="16" x="41.5828343348868" y="47.505930020081664" z="0" classname="plugins.nchenouard.particleTracking.sequenceGenerator.ProfileSpotTrack" type="1" />
          <detection t="17" x="41.48425270538317" y="51.6023835597057" z="0" classname="plugins.nchenouard.particleTracking.sequenceGenerator.ProfileSpotTrack" type="1" />
          ...


.. note::
    This format supports split and merge events

ISBI
----

The ISBI format is a XML format used for the ISBI tracking challenge. This format must contain
a `root` element and a list of particles in a `TrackContestISBI2012` element:

.. code-block:: xml
    :linenos:

    <?xml version="1.0" encoding="UTF-8"?>
    <root>
      <TrackContestISBI2012 snr="?" density="?" scenario="FakeTracks.tif" generationDateTime="Wed May 12 14:07:09 CEST 2021">
        <particle>
          <detection t="0" x="64.00558680057657" y="3.9587411612103076" z="0.0" />
          <detection t="1" x="63.98171495578894" y="6.04150382894106" z="0.0" />
          <detection t="2" x="63.95406806092088" y="10.06085170348766" z="0.0" />


.. warning::
    This format does **not** support split and merge events


Quickstart
==========

You can open local tracks using `napari` at the terminal and the path to your file:

.. code-block:: shell
    :linenos:

    napari /path/to/your/tracks.xml


OR in python:

.. code-block:: python
    :linenos:

    import napari

    viewer = napari.Viewer()
    viewer.open('/path/to/your/tracks.xml')
    napari.run()

Getting Help
============

If you discover a bug with the plugin, or would like to request a new feature, please
raise an issue on our repository at https://github.com/sylvainprigent/napari-tracks-reader.