Metadata-Version: 2.4
Name: linkinpy
Version: 0.0.4
Summary: A python package to bring uv managed workflows to all common image analysis tools
Project-URL: Homepage, https://github.com/your-username/MyPackageFolder
Project-URL: Repository, https://github.com/your-username/MyPackageFolder
Project-URL: Issues, https://github.com/your-username/MyPackageFolder/issues
Project-URL: Changelog, https://github.com/your-username/MyPackageFolder/blob/main/CHANGELOG.md
Author-email: "Bruno M. Saraiva" <bruno.msaraiva2@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.9
Requires-Dist: ipyfilechooser>=0.6.0
Requires-Dist: ipywidgets>=8.0
Requires-Dist: magicgui>=0.10.0
Requires-Dist: numpy>=1.26
Requires-Dist: pyyaml>=6.0
Requires-Dist: stackview>=0.14.0
Requires-Dist: tifffile>=2024.8.10
Provides-Extra: gui
Requires-Dist: pyqt6>=6.7.0; extra == 'gui'
Provides-Extra: napari
Requires-Dist: napari>=0.5.0; extra == 'napari'
Description-Content-Type: text/markdown

# linkinpy

`linkinpy` is the Python core for running YAML-described bioimage-analysis methods in
isolated `uv` environments. It provides:

- a CLI: `linkinpy list`, `linkinpy install`, `linkinpy run`
- spec parsing and validation
- per-spec environment management
- image loading, writing, and shared-memory transport helpers
- result normalization for single-output and multi-output methods
- Colab helper widgets
- a small Python facade API

Run commands in this document from the `LinkinPy/` folder.

## Development Setup

```bash
uv sync
uv run ruff check src tests
uv run pytest
```

Optional developer commands:

```bash
uv run ruff format .
uv run python -m build
uv run pre-commit install
```

The same workflow is available through `make`:

```bash
make sync
make lint
make test
make format
make build
```

## CLI Tutorial

List available methods:

```bash
uv run linkinpy list ../Library/nanopyx.yaml
```

Install a spec for the CLI interface:

```bash
uv run linkinpy install ../Library/nanopyx.yaml --interface cli
```

Each spec gets its own environment under `~/.linkinpy/<spec-name>/`. If the spec contains
`how_to_cite`, the install command prints that citation text after the install summary.

Run a method and save declared outputs to a folder:

```bash
uv run linkinpy run ../Library/nanopyx.yaml eSRRF \
  --output-dir outputs \
  image=input.tif \
  magnification=2
```

Use explicit output destinations when needed:

```bash
uv run linkinpy run ../Library/StarDist.yaml "Predict 2D Pretrained Model" \
  --output labels=outputs/labels.tif \
  image=input.tif \
  model_name=2D_versatile_fluo
```

Arguments are passed as `name=value`. For inputs declared as `np.ndarray`, the CLI accepts
image paths and `.npy` files.

## Python API Tutorial

```python
from linkinpy import LinkinPy

lp = LinkinPy("../Library/nanopyx.yaml")
print(lp.list_callables())
lp.install(interface="cli")
print(
    lp.run(
        "eSRRF",
        {"image": "input.tif", "magnification": 2},
        output_dir="outputs",
    )
)
```

Lower-level APIs are also public:

- `load_spec` / `parse_spec`
- `EnvironmentManager`
- `run_spec_callable`
- `run_spec_callable_in_environment`
- `parse_run_result`
- `read_image` / `write_image`

## Colab Tutorial

Install LinkinPy in a notebook:

```python
!pip install linkinpy
```

Mount Google Drive:

```python
from linkinpy import mount_google_drive

mount_google_drive()
```

Install a selected spec:

```python
from linkinpy import install_colab_spec

install_colab_spec("/content/LinkinPy/Library")
```

Run a method from installed specs:

```python
from linkinpy import run_installed_colab_method

run_installed_colab_method(
    output_dir="/content/drive/MyDrive/LinkinPy/outputs"
)
```

Colab displays image and labels outputs when possible and prints metadata/path outputs in
the notebook output area.

## Spec Contract

Specs are YAML files. Each method declares `inputs`, `outputs`, and `output`.

```yaml
display_name: Example Package
python_version: "3.12"
how_to_cite: "Author A, Author B. Example Package. Journal, year."

install:
  python_packages:
    - name: example-package

segment:
  callable: example_package.segment
  inputs:
    - name: image
      display_name: Input Image
      type: np.ndarray
      role: image
      required: true
  outputs:
    - name: labels
      display_name: Label Image
      type: np.ndarray
      role: labels
      format: tif
      display: true
  output:
    cli: [io]
    colab: [display, io]
    napari: [display, io]
    imagej: [display, io]
    qupath: [display, io]
```

`outputs` is the return-value contract. Tuple/list returns map by output order. Dict
returns map by output name.

## More Documentation

- [GETTING_STARTED.md](GETTING_STARTED.md) for contributor setup
- [METHOD_AUTHORING.md](METHOD_AUTHORING.md) for package authors
- [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow
- [Repository tutorials](../USAGE_TUTORIALS.md) for all interfaces
