# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**imvis** is a Python package for interactive visualization and processing of 3D medical images. It specializes in medical imaging workflows including DICOM processing, NIFTI conversion, and interactive 3D visualization.

## Development Commands

This project uses **Rye** for dependency management and packaging:

```bash
# Install dependencies and sync environment
rye sync

# Activate virtual environment
.venv/Scripts/activate  # Windows
source .venv/bin/activate  # Linux/Mac

# Build package
rye build

# Run tests
pytest

# Add/remove dependencies
rye add package_name
rye remove package_name
```

Alternative build commands if rye is not available:
```bash
python -m build
pip install --force-reinstall ./dist/imvis-*.whl
```

## Architecture

### Core Modules

- **imagesc3s.py**: Interactive 3D image visualization with scrollable interface using matplotlib
- **nifti_convert.py**: DICOM to NIFTI conversion with SUV calculation for PET images
- **mipz.py**: Maximum Intensity Projection (MIP) with rotation capabilities
- **dicomdir_split.py**: DICOMDIR file organization into Patient/Study/Series hierarchy
- **util.py**: Common utilities for medical image processing

### Key Dependencies

- **SimpleITK**: Core medical image I/O and processing
- **pydicom**: DICOM file handling
- **dicom2nifti**: DICOM to NIFTI conversion
- **matplotlib**: Interactive visualization backend
- **numpy/scipy**: Numerical computing

### Standard Image Orientation

The package assumes a specific 3D image orientation convention (see docs/orientation.png). All functions expect this standard orientation for consistent behavior across medical imaging workflows.

## Testing and Quality

- Tests are located in `tests/` directory
- Test data samples are provided in `samples/` with real medical imaging files (CT, PET, DICOM)
- Run `pytest` to execute the test suite

## Important Notes

- SUV calculation functionality requires proper DICOM tags for PET images
- Interactive visualization works best with matplotlib backends like 'tk' or 'qt'
- The package handles both intensity images and Bq/mL unit images with appropriate scaling