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, and the point picker. - ``[torch]`` — PyTorch + SAM2 for ``Sam2`` (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 `Deep Learning Detectors`_ below for a self-service recipe that combines PhenoTypic and ``micro_sam`` in a single ``pixi`` environment. Optional libvips acceleration +++++++++++++++++++++++++++++ On macOS and Windows, the ``[gui]`` extra installs the official `pyvips binary distribution `_, including a self-contained native libvips. No separate system installation or loader-path configuration is needed for the normal GUI installation. Linux and HPC installations use the smaller ``pyvips`` binding. Provide native `libvips `_ through the operating system or a site environment module when the faster DZI path is wanted: .. code-block:: bash # Debian or Ubuntu sudo apt install libvips-dev --no-install-recommends On a cluster, load the site's libvips module before launching the GUI when one is available. Verify that the native library is visible from the same shell that will launch PhenoTypic: .. code-block:: bash uv run python -c "import pyvips; print('pyvips', pyvips.__version__, 'libvips', '.'.join(str(pyvips.version(i)) for i in range(3)))" The bundled build includes common image loaders but omits optional PDF and OpenSlide support. Users who intentionally prefer a fuller Homebrew libvips can install it with ``brew install vips``. If that system install is present but the dynamic loader cannot find ``libvips.42.dylib``, set the fallback library path before running either the verification command or the GUI: .. code-block:: bash export DYLD_FALLBACK_LIBRARY_PATH="$(brew --prefix vips)/lib${DYLD_FALLBACK_LIBRARY_PATH:+:$DYLD_FALLBACK_LIBRARY_PATH}" If ``pyvips`` cannot load its native library, PhenoTypic automatically uses its Pillow implementation. All viewer features remain available, although large DZI pyramids can take longer to prepare and require more memory. Deep Learning Detectors ----------------------- PhenoTypic ships several deep-learning colony detectors — ``Sam2``, ``Sam3``, ``DinoSam2Detector``, ``Insid3Detector``, ``FssDinoDetector``, and the conda-only ``MicroSamDetector``. This section covers **installing** the detector packages and **pre-downloading** their model weights. For detector usage, parameter tuning, device selection, and SLURM staging, see the :doc:`GPU Detection Setup ` how-to guide. Installing the detector packages ++++++++++++++++++++++++++++++++ The PyPI-published detectors are grouped into optional extras: .. list-table:: :header-rows: 1 :widths: 18 32 50 * - Extra - Detectors - Notes * - ``[torch]`` - ``Sam2`` - PyTorch + ``sam2`` from PyPI. Linux/macOS only — no Windows wheels (use WSL2). * - ``[foundation]`` - ``Sam3``, ``DinoSam2Detector``, ``Insid3Detector``, ``FssDinoDetector`` - ``transformers`` (>=5.2.0) + ``huggingface_hub`` (pulls ``torch``). * - ``[gpu]`` - all of the above - Umbrella extra — every GPU detector at once (recommended for a dev env). .. code-block:: bash # SAM2 only uv add "phenotypic[torch]" # SAM3 + DINO-based foundation detectors uv add "phenotypic[foundation]" # Everything, inside a uv-managed checkout uv sync --extra gpu ``MicroSamDetector`` depends on ``micro_sam``, which is published **only on conda-forge** and so is not part of any PhenoTypic extra. Manage the combined stack yourself — for example with `pixi `_, which resolves conda-forge and PyPI in one lockfile, or with conda: .. code-block:: bash pip install phenotypic # or phenotypic[torch] on non-Windows conda install -c conda-forge micro_sam # adds MicroSamDetector Model weights and licenses ++++++++++++++++++++++++++ PhenoTypic **does not redistribute model weights** — each is downloaded from its upstream source under that model's license. Most weights are ungated (SAM2, DINOv2), but **SAM3 and DINOv3 weights are gated** and need a one-time license handshake on the Hugging Face Hub: 1. Create a Hugging Face account. 2. Accept the gate on the model page (this *is* the license acceptance): SAM3 → https://huggingface.co/facebook/sam3, DINOv3 → https://huggingface.co/facebook/dinov3-vitb16-pretrain-lvd1689m. 3. Authenticate locally once: ``uv run hf auth login`` (or export ``HF_TOKEN``). Downloading and caching checkpoints +++++++++++++++++++++++++++++++++++ Every detector downloads its weights automatically on first use, but you can pre-download them with the ``phenotypic.detect.nn`` CLI — essential on SLURM clusters whose compute nodes have no internet access: .. code-block:: bash # SAM2 (default tiny; --all for every size) uv run python -m phenotypic.detect.nn download --model-type sam2 --model-size tiny # micro-sam uv run python -m phenotypic.detect.nn download --model-type microsam --model-name vit_b_lm # Gated foundation weights — --accept-license acknowledges the model license uv run python -m phenotypic.detect.nn download --model-type sam3 --accept-license uv run python -m phenotypic.detect.nn download --model-type dinov3 --dino-size base --accept-license # Ungated DINOv2 (no token needed) uv run python -m phenotypic.detect.nn download --model-type dinov2 --dino-size base # Inspect or clear the cache uv run python -m phenotypic.detect.nn list uv run python -m phenotypic.detect.nn clear --model-type sam2 Cache locations are controlled by environment variables — point them at shared storage so SLURM compute nodes can read pre-staged weights: .. list-table:: :header-rows: 1 :widths: 38 62 * - Variable - Controls * - ``TORCH_HOME`` - SAM2 checkpoint cache (default ``~/.cache/torch/hub/checkpoints/``). * - ``MICROSAM_CACHEDIR`` - micro-sam checkpoint cache. * - ``HF_HOME`` / ``HF_HUB_CACHE`` - Hugging Face cache for SAM3 + DINO weights. * - ``HF_HUB_OFFLINE=1`` / ``TRANSFORMERS_OFFLINE=1`` - Force load-from-cache on offline compute nodes. * - ``HF_TOKEN`` / ``HUGGING_FACE_HUB_TOKEN`` - Auth for gated downloads (alternative to ``hf auth login``). * - ``PHENOTYPIC_ACCEPT_MODEL_LICENSE`` - Non-interactive license acknowledgement for batch/SLURM jobs (e.g. ``sam3,dinov3``). .. note:: On a cluster, accept the gates and pre-stage weights **on the login node** (which has internet), then run the compute job offline with the same ``HF_HOME`` plus ``HF_HUB_OFFLINE=1`` and ``PHENOTYPIC_ACCEPT_MODEL_LICENSE``. Acceptance never happens silently inside a batch job. See the :doc:`GPU Detection Setup ` guide for the full SLURM staging workflow. 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. Start it with the ``phenotypic-gui`` console script: .. code-block:: bash uv run 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 ` 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``. The existing ``phenotypic`` CLI is reserved for batch pipeline execution with explicit path options, not subcommands.