napari_track_edit.data_views.dims_utils
=======================================

.. py:module:: napari_track_edit.data_views.dims_utils

.. autoapi-nested-parse::

   Relating the axes of a Tracks object to the axes of the napari viewer.

   The viewer can have more dimensions than the tracks do, e.g. because of multi-channel
   images being present in the same viewer as the tracks layers. Napari aligns every layer
   on its trailing dimensions, so the tracks occupy the last ``ndim_tracks`` world axes of
   the viewer. All additional leading dimensions are for visualization only.

   ``dims.order`` only permutes how axes are *displayed*. ``dims.point``,
   ``dims.current_step`` and ``dims.range`` stay indexed by world axis, and ``roll()`` and
   ``transpose()`` touch nothing but ``order``. So rolling or transposing with the napari
   buttons never moves an axis from one world index to another, and the map between tracks
   axes and world axes does not have to be remembered across a roll. A roll can put an extra
   axis on screen, so any code reading a displayed axis has to ask whether it is a tracks
   axis at all before using it.



Classes
-------

.. autoapisummary::

   napari_track_edit.data_views.dims_utils.TracksDims


Module Contents
---------------

.. py:class:: TracksDims

   Where a Tracks object's axes sit among the viewer's world axes.

   The tracks take the last ``ndim_tracks`` world axes; ``ndim_offset`` counts the
   extra ones in front, which are for visualization only. Meant to be built at the
   point of use rather than stored, because ``ndim_world`` changes when layers are
   added or removed.

   .. attribute:: ndim_world

      Number of dimensions of the viewer.

      :type: int

   .. attribute:: ndim_tracks

      Number of dimensions of the tracks, time included. The
      tracking layers all have exactly this many dimensions, so this doubles as
      the number of axes any of them spans.

      :type: int


   .. py:attribute:: ndim_world
      :type:  int


   .. py:attribute:: ndim_tracks
      :type:  int


   .. py:method:: __post_init__() -> None


   .. py:property:: ndim_offset
      :type: int


      Number of extra world axes in front of the tracks' own axes.

      Also the index of the first tracks axis, so ``values[dims.ndim_offset:]`` is
      the tracks' part of anything indexed by world axis (``dims.point``,
      ``dims.current_step``, ``dims.range``, the axis labels).


   .. py:property:: time_axis
      :type: int


      World axis carrying time, which is the tracks' first axis.


   .. py:method:: to_tracks_axis(world_axis: int) -> int | None

      Map a viewer (world) axis onto a tracks axis, or None if there is none.

      :param world_axis: Axis index in the viewer's world coordinate system.
      :type world_axis: int

      :returns:

                The corresponding tracks axis, or None if the tracks do not
                    span this world axis.
      :rtype: int | None



   .. py:method:: embed_point(location: collections.abc.Sequence[float], point: collections.abc.Sequence[float]) -> list[float]

      Write a tracks-space location into a full-length viewer point.

      The extra leading axes keep whatever the viewer is currently showing, only the
      trailing tracks axes are replaced.

      :param location: Position in tracks space, time included.
      :type location: Sequence[float]
      :param point: The viewer's current ``dims.point``.
      :type point: Sequence[float]

      :returns:

                A point of length ``ndim_world``, ready to assign to
                    ``viewer.dims.point``.
      :rtype: list[float]

      :raises ValueError: If either sequence has the wrong length, which would
          otherwise silently produce a point napari cannot use.