Usage
=====

.. _installation:

Installation
------------

Basic Installation
~~~~~~~~~~~~~~~~~~

For local installations, the required packages can be installed with pip:

>>> pip install astropy numpy matplotlib
>>> pip install cripser connected-components-3d jax

To install perch from source:

.. code-block:: bash

   git clone https://github.com/theo-oneill/perch.git
   cd perch
   pip install -e .

This will install the core dependencies:

- numpy
- matplotlib
- tqdm
- jax

Perch requires the following external libraries for the PH computation and structure segmentation:

.. code-block:: bash

   pip install cripser connected-components-3d

- ``cripser``: Fast C++ library (cubical ripser) for PH computation
- ``cc3d`` (connected-components-3d): Connected components for structure segmentation

.. note::

   ``cripser`` is currently pinned to ``>=0.0.16,<=0.0.24``. Newer releases have
   not yet been validated against perch; the upper bound will be relaxed once
   compatibility is confirmed.

Optional Dependencies
~~~~~~~~~~~~~~~~~~~~~

For additional functionality, install these optional packages:

**Astronomical Data Support:**

.. code-block:: bash

   pip install astropy

This enables FITS file I/O and World Coordinate System (WCS) support.

**Data Analysis:**

.. code-block:: bash

   pip install pandas scikit-image

- ``pandas``: Export structures to DataFrame for analysis
- ``scikit-image``: Advanced geometric property calculations

For detailed workflow and examples, see the :doc:`quickstart` guide.