New vision

.github/workflows/tests.yaml

@@ -1,78 +1,78 @@
 name: Tests
 on:
-    push:
-        branches:
-            - main
-    pull_request:
-    workflow_dispatch:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
 jobs:
-    ruff:
-        runs-on: ubuntu-latest
-        strategy:
-            matrix:
-                python-version: ["3.10", "3.13"]
-        name: ruff on ${{ matrix.python-version }}
-        steps:
-            - uses: actions/checkout@v3
-            - uses: actions/setup-python@v4
-              with:
-                  python-version: ${{ matrix.python-version }}
-                  cache: "pip"
-            - run: pip install -e '.[dev]'
-            - run: ruff check .
-    mypy:
-        runs-on: ubuntu-latest
-        strategy:
-            matrix:
-                python-version: ["3.10", "3.13"]
-        name: mypy on ${{ matrix.python-version }}
-        steps:
-            - uses: actions/checkout@v3
-            - uses: actions/setup-python@v4
-              with:
-                  python-version: ${{ matrix.python-version }}
-                  cache: "pip"
-            - run: pip install -e '.[dev]'
-            - run: mypy .
-    ruff-format:
-        runs-on: ubuntu-latest
-        strategy:
-            matrix:
-                python-version: ["3.10", "3.13"]
-        name: ruff-format on ${{ matrix.python-version }}
-        steps:
-            - uses: actions/checkout@v3
-            - uses: actions/setup-python@v4
-              with:
-                  python-version: ${{ matrix.python-version }}
-                  cache: "pip"
-            - run: pip install -e '.[dev]'
-            - run: ruff format --check .
-    pytest:
-        runs-on: ubuntu-latest
-        strategy:
-            matrix:
-                python-version: ["3.10", "3.13"]
-        name: pytest on ${{ matrix.python-version }}
-        steps:
-            - uses: actions/checkout@v3
-            - uses: actions/setup-python@v4
-              with:
-                  python-version: ${{ matrix.python-version }}
-                  cache: "pip"
-            - run: pip install -e '.[dev]'
-            - run: pytest --cov=src --cov-report term-missing
-    doctest:
-        runs-on: ubuntu-latest
-        strategy:
-            matrix:
-                python-version: ["3.10", "3.13"]
-        name: doctest on ${{ matrix.python-version }}
-        steps:
-            - uses: actions/checkout@v3
-            - uses: actions/setup-python@v4
-              with:
-                  python-version: ${{ matrix.python-version }}
-                  cache: "pip"
-            - run: pip install -e '.[dev]'
-            - run: make -C docs doctest
+  ruff:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+    name: ruff on ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - run: pip install -e '.[dev]'
+      - run: ruff check .
+  mypy:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+    name: mypy on ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - run: pip install -e '.[dev]'
+      - run: mypy .
+  ruff-format:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+    name: ruff-format on ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - run: pip install -e '.[dev]'
+      - run: ruff format --check .
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+    name: pytest on ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - run: pip install -e '.[dev]'
+      - run: pytest --cov=src --cov-report term-missing
+  doctest:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+    name: doctest on ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - run: pip install -e '.[dev]'
+      - run: make -C docs doctest

docs/source/_static/style.css

@@ -0,0 +1,23 @@
+/*DOCS SIDEBARS AND CENTERING*/
+.sidebar-drawer,
+.sidebar-container,
+.toc-drawer {
+    width: 15em;
+    min-width: 15em;
+}
+@media (min-width: 65em) {
+    .content {
+        margin-left: auto;
+        margin-right: auto;
+    }
+}
+@media (min-width: 82em) {
+    .page {
+        justify-content: center;
+    }
+    .toc-drawer {
+        position: fixed;
+        right: 0;
+        top: 0;
+    }
+}

docs/source/conf.py

@@ -8,6 +8,10 @@
 from __future__ import annotations
 
 import importlib
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
 
 project = "dynsight"
 project_copyright = "2023, Andrew Tarzia"
@@ -37,7 +41,7 @@
 
 autodoc_typehints = "description"
 autodoc_member_order = "groupwise"
-autoclass_content = "class"
+autoclass_content = "both"
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
@@ -53,3 +57,8 @@
 
 html_theme = "furo"
 html_static_path = ["_static"]
+
+
+def setup(app: Sphinx) -> None:
+    """Configure the Sphinx app by adding a custom CSS file."""
+    app.add_css_file("style.css")

docs/source/index.rst

@@ -10,6 +10,7 @@
    :maxdepth: 2
 
    vision <vision>
+   track <track>
    descriptors <descriptors>
    onion clustering <onion>
    analysis <analysis>
@@ -75,10 +76,6 @@ you are using Python 3.10 and below, you can use :mod:`cpctools` to access
 
   $ pip install cpctools
 
-If you want to use the :mod:`dynsight.vision` and :mod:`dynsight.track` modules
-you will need to install a series of packages. This can be done with with pip::
-
-  $ pip install ultralytics PyYAML
 
 How to get started
 ------------------

docs/source/label_tool/label_tool.rst

@@ -0,0 +1,70 @@
+The Label Tool
+==============
+
+The ``dynsight label_tool`` is a simple web application that allows users to
+label images. Picture labelling is a crucial step in many computer vision tasks,
+such as the creation of initial training dataset to train Convolutional Neural
+Networks (CNNs) model. The current version of `dynsight vision <../_autosummary/dynsight.vision.VisionInstance.html>`_
+exploits the power of the `YOLO models <https://docs.ultralytics.com/models/yolo12/>`_
+for computer vision tasks. Thus, the ``label_tool`` has been specifically
+designed to work with the YOLO dataset format.
+
+.. image:: ../_static/label_tool.png
+
+----------
+How to Use
+----------
+
+The ``label_tool`` application can be executed in 2 main ways:
+
+* As a standalone application, run the following command in the environment
+  where dynsight is installed:
+
+.. code-block:: bash
+
+    $ label_tool
+
+* From python code:
+
+.. code-block:: python
+
+    import dynsight
+
+    dynsight.vision.label_tool(port=8888) #port selection is optional
+
+In both cases a localhost server should start and the application should
+automatically appear in your default web browser.
+
+.. tip::
+
+    In case the application does
+    not open automatically, you can manually open it by copying and pasting
+    the URL provided in the terminal output.
+
+-------
+The GUI
+-------
+
+The ``label_tool`` Graphical User Interface is divided in three main panels:
+
+* **The image panel**: where loaded images appear and labels can be drawn.
+
+* **The label menu panel**: where labels can be created and edited.
+
+.. image:: ../_static/label_menu.png
+    :align: center
+
+* **The commands panel**: where all the available commands can be executed.
+
+.. image:: ../_static/label_bar.png
+
+Using the ``Choose File`` button, users can select the image(s) they want to
+label. Once the image is loaded, users can start drawing labels by clicking and
+dragging on the image panel. The label menu panel allows users to create and
+edit labels. Finally, the commands panel provides a set of exporting options:
+
+* **Export label**: Download a single ``.txt`` file in YOLO format containing the labels for the current image.
+
+* **Export dataset**: Download a YOLO dataset from the loaded images with the labels and create the initial yaml configuration file to be used in the YOLO training process.
+
+* **Synthesize dataset**: Create a synthetic dataset from the drawn labels randomizing the object position in different images (useful when a low number of images is available).

docs/source/track.rst

@@ -0,0 +1,14 @@
+track
+=====
+
+This module tracks particle trajectories in `.xyz` files that lack explicit
+particle IDs, assigning consistent identities across frames.
+It is especially useful for outputs generated by the :doc:`vision` module.
+
+Functions
+---------
+
+.. toctree::
+  :maxdepth: 1
+
+  track_xyz <_autosummary/dynsight.track.track_xyz>

docs/source/vision.rst

@@ -10,5 +10,5 @@ Usage
 .. toctree::
   :maxdepth: 1
 
-  Video <_autosummary/dynsight.vision.Video.rst>
-  Detect <_autosummary/dynsight.vision.Detect.rst>
+  label_tool <label_tool/label_tool.rst>
+  VisionInstance <_autosummary/dynsight.vision.VisionInstance.rst>