Metadata-Version: 2.4
Name: pysnt
Version: 5.0.24
Summary: Python interface for SNT, the ImageJ framework for neuroanatomy
Author: SNT contributors
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/morphonets/pysnt
Project-URL: Repository, https://github.com/morphonets/pysnt
Project-URL: Documentation, https://pysnt.readthedocs.io
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: scyjava>=1.12.3
Requires-Dist: pyimagej>=1.7.0
Requires-Dist: JPype1>=1.5.0
Requires-Dist: numpy>=1.26
Requires-Dist: matplotlib>=3.8
Requires-Dist: xarray>=2023.12
Requires-Dist: pandas>=2.1
Provides-Extra: display
Requires-Dist: networkx>=3.0; extra == "display"
Requires-Dist: cairosvg>=2.7; extra == "display"
Requires-Dist: PyMuPDF>=1.24.3; extra == "display"
Provides-Extra: gui
Requires-Dist: ipykernel>=6.0; extra == "gui"
Requires-Dist: pyobjc-core>=10.0; sys_platform == "darwin" and extra == "gui"
Requires-Dist: pyobjc-framework-cocoa>=10.0; sys_platform == "darwin" and extra == "gui"
Provides-Extra: java
Requires-Dist: install-jdk>=1.0; extra == "java"
Provides-Extra: napari
Requires-Dist: napari[all]; extra == "napari"
Provides-Extra: info
Requires-Dist: psutil>=5.9; extra == "info"
Provides-Extra: all
Requires-Dist: pysnt[display,gui,info,java]; extra == "all"
Provides-Extra: dev
Requires-Dist: pysnt[all,napari]; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: nbclient; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: typing_extensions; extra == "dev"
Requires-Dist: trimesh; extra == "dev"
Requires-Dist: manifold3d; extra == "dev"
Requires-Dist: rtree; extra == "dev"
Requires-Dist: scipy; extra == "dev"
Requires-Dist: scikit-learn; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx<9.0,>=5.0; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Requires-Dist: myst-nb<1.5.0,>=0.15.0; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Dynamic: license-file

<p align="center"><img src="./docs/_static/snt_logo.svg" alt="SNT" width="150"></p>
<h1 align="center">PySNT</h1>
<h2 align="center">Python wrapper for SNT, the framework for quantification of neuronal anatomy</h2>
<div align="center">
  <!-- License -->
  <a href="https://github.com/morphonets/SNT/blob/master/LICENSE.txt">
    <img alt="GitHub license" src="https://img.shields.io/github/license/morphonets/SNT">
  </a>
  <!-- Forum -->
  <a href="https://forum.image.sc/tags/snt">
    <img alt="Forum.sc topics" src="https://img.shields.io/badge/dynamic/json.svg?label=forum&url=https%3A%2F%2Fforum.image.sc%2Ftag%2Fsnt.json&query=%24.topic_list.tags.0.topic_count&suffix=%20topics">
  </a>
  <!-- Issues -->
  <a href="https://github.com/morphonets/pysnt/issues">
    <img alt="Open issues" src="https://img.shields.io/github/issues/morphonets/pysnt">
  </a>
  <a href="https://github.com/morphonets/pysnt/issues">
    <img alt="Closed issues" src="https://img.shields.io/github/issues-closed/morphonets/pysnt">
  </a>
</div>
<div align="center">
  <h3>
    <a href="https://pysnt.readthedocs.io/en/latest/install.html">
      Installation
    </a>
    <span style="margin:.5em">|</span>
    <a href="https://pysnt.readthedocs.io/en/latest/index.html">
       Documentation
    </a>
    <span style="margin:.5em">|</span>
    <a href="https://forum.image.sc/tag/SNT">
      Support
    </a>
  </h3>
</div>


## Technical Features

- **Complete Java Bridge**: Full programmatic access to SNT's neuroanatomy toolkit from Python (via JPype and ScyJava),
  enabling integration of advanced tracing, analysis, and visualization capabilities into Python workflows
  
- **Consistent API**: 1:1 correspondence with SNT's Java API while maintaining Python conventions, allowing developers
  familiar with either language to work efficiently

- **Full Type Annotation**: Type hints for all methods and classes, enabling static type checking with mypy and improved
  code reliability
  
- **IDE Integration**: Autocomplete, inline documentation, and parameter hints in VS Code, PyCharm, Spyder, and Jupyter
  notebooks through type stubs and docstrings
  
- **Performant**: Lazy class loading minimizes initialization overhead, loading only required SNT components on demand

- **Native Python Converters**: Automatic conversion between SNT objects and Python-native types:
    
    | SNT Java Object | PySNT Python Object              |
    |-----------------|----------------------------------|
    | SNTChart        | matplotlib Figure                |
    | SNTGraph        | NetworkX graph                   |
    | SNTTable        | xarray Dataset; pandas DataFrame |
    | ImagePlus       | xarray; numpy (via ScyJava)      |
    | Collections     | lists/dicts, etc. (via ScyJava)  |



## Limitations
- **Pre-release**: PySNT 5.0 is under active development and targets SNT 5.0.x: Expect bugs and API changes until
  the first stable release

- **Early Stage Software**: Limited community validation. Please [report](https://github.com/morphonets/pysnt/issues)
  anything unexpected

## Getting Started for Users
See [Install instructions](https://pysnt.readthedocs.io/en/latest/install.html).


## Getting Started for Developers

### Environment Setup
```bash
# 1. Clone the repository
git clone https://github.com/morphonets/pysnt.git
cd pysnt

# 2. Create and activate a virtual environment (Python 3.11+, JDK 21 available)
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

# 3. Install PySNT in development mode, with all optional and dev dependencies
pip install -e ".[dev]"

# 4. Verify the setup
python -c "import pysnt; print(pysnt.version())"
python -m pytest tests -q

# 5. Have a look at ./dev/README.md for common workflows
```
Prefer conda/mamba? `mamba env create -f environment-dev.yml && mamba activate pysnt-dev && pip install -e .[dev]`
does the same. Select the resulting interpreter in your IDE (see the
[install docs](https://pysnt.readthedocs.io/en/latest/install.html#choosing-an-interpreter-ides-and-notebooks)).

### Project Structure

```
pysnt/
├── src/pysnt/           # main package source (one subpackage per curated SNT package)
├── tests/               # test suite (JVM-dependent tests skip themselves if SNT cannot be resolved)
├── docs/                # documentation source (Sphinx/MyST) and tutorial notebooks
├── dev/                 # development utilities and templates (see dev/README.md)
├── dev/scripts/         # SNT sync, stub generation, and documentation scripts
├── .github/workflows/   # CI: tests, lowest-dependency tests, docs build
├── pyproject.toml       # packaging metadata, dependency floors, and extras
├── requirements*.txt    # pip equivalents (core, optional features, development)
└── environment*.yml     # conda-compatible equivalents (min, full, development)
```

### Dependencies
`pyproject.toml` contains all details: core dependencies are listed under `dependencies`, and optional
features under extras (`display`, `gui`, `java`, `info`, `all`, `dev`, `docs`). The `requirements*.txt` and
`environment*.yml` files mirror it; The floors are verified by the "lowest declared dependencies" CI job.

### Versioning and SNT
PySNT's `major.minor` version matches the SNT release it targets (PySNT 5.1.x targets SNT 5.1.x); the patch number is
independent, so PySNT can ship fixes without a new SNT release. By default, `pysnt.initialize()` downloads
SNT from Maven at `DEFAULT_SNT_VERSION` (see `src/pysnt/_endpoints.py`). Users can override it with
`initialize(snt_version=...)` or `SNT_VERSION`, or use a local Fiji instead. PySNT warns when the loaded SNT differs in
`major.minor`. See [dev/README.md](dev/README.md#keeping-pysnt-in-sync-with-snt) for the update workflow.

### Need Help?

- 📖 **Documentation**: [pysnt.readthedocs.io](https://pysnt.readthedocs.io)
- 💬 **Forum**: [forum.image.sc/tag/snt](https://forum.image.sc/tag/snt)
- 🐛 **Issues**: [GitHub Issues](https://github.com/morphonets/pysnt/issues)
