Getting Started
===============

Prerequisites
-------------

Before installing Phenotypic, ensure you have the following prerequisites:

* Python 3.10 or higher
* pip (Python package installer)
* uv (recommended; see https://docs.astral.sh/uv/)

Installation Methods
------------------

From PyPi
+++++++++

Using uv (recommended)
+++++++++
.. code-block:: bash

   uv add phenotypic

Using pip
+++++++++

.. code-block:: bash

    pip install phenotypic

From Source
-----------

To install from source:


.. code-block:: bash

  git clone https://github.com/exfab/PhenoTypic.git
  cd PhenoTypic && uv sync


Optional Extras
---------------

PhenoTypic provides optional extras for different use cases:

- ``[gui]`` — Browser-based GUI hub: Plotly dashboards, Dash apps, and Jupyter
  integration. Does **not** include napari.
- ``[napari]`` — The interactive napari desktop viewers (pulls napari + PyQt6).
  Required for ``image.rgb.napari()`` and related viewer methods, the point
  picker, and the napari sweep viewer (``python -m phenotypic.gui.sweep``).
- ``[torch]`` — PyTorch + SAM2 for ``Sam2Detector`` (Linux/macOS only).

.. code-block:: bash

   # Browser GUI hub (Plotly, Dash, Jupyter)
   uv add "phenotypic[gui]"

   # napari desktop viewers
   uv add "phenotypic[napari]"

   # SAM2 GPU detector (Linux/macOS)
   uv add "phenotypic[torch]"

``micro_sam`` (used by ``MicroSamDetector``) is only published on
conda-forge and is **not** included in any PhenoTypic extra. See the
:doc:`GPU Detection Setup </how_to/pages/gpu_detection_setup>` guide
for a self-service recipe that combines PhenoTypic and ``micro_sam``
in a single ``pixi`` environment.


Development Installation
========================

For development of new modules, sync with the ``dev`` (and optionally
``docs``) dependency groups:

.. code-block:: bash

    git clone https://github.com/exfab/PhenoTypic.git
    cd PhenoTypic
    uv sync --group dev --group docs


Verification
------------

To verify the installation, run:

.. code-block:: python

   import phenotypic
   print(phenotypic.__version__)


Launching the GUI
-----------------

The unified GUI hub bundles the pipeline builder, results viewer, and
run console under one URL. Two equivalent entry points:

.. code-block:: bash

   # Console script (preferred)
   uv run phenotypic-gui --root ./images --port 8050

   # Module entry (works in environments without the console script on PATH)
   uv run python -m phenotypic.gui --root ./images --port 8050

``--root`` freezes the sandbox the GUI's file browser is allowed to see
(defaults to the current working directory). ``--host 127.0.0.1`` (the
default) keeps the server loopback-only — pair with SSH port forwarding
for remote workstations:

.. code-block:: bash

   ssh -L 8050:localhost:8050 user@cluster

Then open ``http://localhost:8050/`` in your browser. If you launch the
GUI from inside a Slurm allocation (``srun``/``salloc``), the server
binds to the compute node rather than the login node, and the
single-hop tunnel above will return ``connect failed: Connection
refused``. See
:ref:`Running the GUI on a Slurm compute node <gui-hub-slurm-tunnel>`
in the GUI hub guide for the two-hop tunnel pattern. That guide also
covers the file browser, pipeline builder, run console, and results
viewer.

For Open OnDemand-style proxies, pass the browser path as a prefix, not
the full URL:

.. code-block:: bash

   uv run phenotypic-gui --root /rhome/ejaco020 --host 0.0.0.0 --port 30099 --url-prefix /node/hz01/30099/

Then open the full proxy URL, for example
``https://ondemand.hpcc.ucr.edu/node/hz01/30099/``.

.. note::

   ``phenotypic gui`` (no hyphen, as a subcommand) is **not supported**.
   Use ``phenotypic-gui`` or ``python -m phenotypic.gui``. The existing
   ``phenotypic`` CLI is reserved for batch pipeline execution with explicit
   path options, not subcommands.