# Contributing to ndevio

Thank you for your interest in contributing to ndevio! This document provides guidelines for development and contributions.

## Development Setup

### Using pip

For development, clone the repository and install with the dev dependency group:

```bash
git clone https://github.com/ndev-kit/ndevio.git
cd ndevio
pip install -e . --group dev
```

This includes pytest, pytest-cov, pytest-qt, tox-uv, napari, and pyqt6.

Run tests with:

```bash
pytest -v --cov=ndevio --cov-report=html
```

### Using Pixi

You can use [Pixi](https://pixi.sh) for reproducible development environments:

```bash
git clone https://github.com/ndev-kit/ndevio.git
cd ndevio
pixi install -e dev
pixi run -e dev test
```

Or activate the environment and run commands directly:

```bash
pixi shell -e dev
pytest -v
```

## Code Architecture

### Mature Patterns

The following components represent stable, mature patterns that reflect the goals of the ndevio API:

#### `nImage` Class

The `nImage` class ([nimage.py](src/ndevio/nimage.py)) extends bioio's `BioImage` with napari-specific functionality. This is the **core programmatic API** for ndevio and follows these principles:

- **Metadata translation**: Converts bioio metadata (physical pixel sizes, dimension properties, OME metadata) to napari layer metadata (scale, axis_labels, units)
- **Lazy loading support**: Automatically determines whether to load data in-memory or use dask based on file size and available RAM
- **Layer data tuples**: Provides `get_layer_data_tuples()` method that returns napari-ready `LayerDataTuple` objects
- **Channel splitting**: Handles multi-channel images by creating separate layer data tuples per channel
- **Separation of concerns**: No Qt or napari widget dependencies in core functionality

#### `_napari_reader` Module

The napari reader plugin ([_napari_reader.py](src/ndevio/_napari_reader.py)) implements the npe2 reader specification:

- **Plugin discovery**: Registers file extensions and provides reader selection
- **Scene handling**: Integrates with the Scene Widget for multi-scene files
- **Settings integration**: Respects user preferences from ndev-settings
- **Error handling**: Provides helpful suggestions for missing bioio plugins

This module is the **bridge between napari and nImage**, translating drag-and-drop file operations into proper layer creation.

### Key Design Principles

1. **Core logic separate from UI**: Business logic in `nimage.py`, `_layer_utils.py`, etc. should have **no Qt or napari imports** (except type hints)
2. **Lazy imports**: Expensive imports (Qt, napari widgets) should be lazy-loaded to keep startup fast
3. **Settings-driven behavior**: Use [ndev-settings] for user-configurable behavior rather than hardcoding choices
4. **bioio compatibility**: Stay aligned with bioio's data model and avoid reinventing functionality

## Testing

⚠️ **Tests are in poor shape**. Some tests were generated by an LLM without thorough verification and may not reflect actual functionality or edge cases. Sorry!
