Metadata-Version: 2.4
Name: mbo_utilities
Version: 2.4.2
Summary: Various utilities for the Miller Brain Observatory
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/millerbrainobservatory/mbo_utilities
Project-URL: Documentation, https://millerbrainobservatory.github.io/mbo_utilities/index.html
Project-URL: Repository, https://github.com/millerbrainobservatory/mbo_utilities
Project-URL: Issues, https://github.com/MillerBrainObservatory/mbo_utilities/issues
Keywords: Microscopy,ScanImage,multiROI,Tiff
Requires-Python: <3.13,>=3.12.7
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy<3.0,>=2.2.5
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: tifffile>=2025.3.30
Requires-Dist: scikit-image
Requires-Dist: zarr>=3.1.3
Requires-Dist: dask>=2025.3.0
Requires-Dist: imageio[ffmpeg]
Requires-Dist: ffmpeg-python
Requires-Dist: matplotlib>=3.10.1
Requires-Dist: seaborn>=0.13.2
Requires-Dist: opencv-python-headless
Requires-Dist: h5py
Requires-Dist: tqdm
Requires-Dist: jupyterlab>=4.2.6
Requires-Dist: ipykernel
Requires-Dist: ipywidgets<9,>=8.0.0
Requires-Dist: icecream>=2.1.4
Requires-Dist: glfw; sys_platform != "linux"
Requires-Dist: PySide6; sys_platform == "linux"
Requires-Dist: pygfx>=0.15.2
Requires-Dist: jupyter_rfb>=0.5.1
Requires-Dist: llvmlite>=0.43.0
Requires-Dist: mkl_fft>=2.0.0
Requires-Dist: mbo-fastplotlib>=0.7.2
Requires-Dist: rendercanvas<2.5,>=2.4.2
Requires-Dist: imgui-bundle>=1.92.5
Requires-Dist: pyside6>=6.10.1
Requires-Dist: wgpu<0.29,>=0.28.1
Requires-Dist: napari
Requires-Dist: napari-animation
Provides-Extra: suite2p
Requires-Dist: numba>=0.60.0; extra == "suite2p"
Requires-Dist: lbm_suite2p_python>=2.3.1; extra == "suite2p"
Requires-Dist: suite2p_mbo>=2.0.1; extra == "suite2p"
Provides-Extra: suite3d
Requires-Dist: mbo-suite3d>=0.0.6; extra == "suite3d"
Requires-Dist: cupy-cuda12x; extra == "suite3d"
Provides-Extra: rastermap
Requires-Dist: rastermap; extra == "rastermap"
Provides-Extra: torch
Requires-Dist: torch; extra == "torch"
Requires-Dist: torchvision; extra == "torch"
Provides-Extra: processing
Requires-Dist: mbo_utilities[rastermap,suite2p,suite3d,torch]; extra == "processing"
Provides-Extra: docs
Requires-Dist: sphinx>=6.1.3; extra == "docs"
Requires-Dist: docutils>=0.19; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: numpydoc; extra == "docs"
Requires-Dist: ipykernel; extra == "docs"
Requires-Dist: sphinx-autodoc2; extra == "docs"
Requires-Dist: sphinx_tippy; extra == "docs"
Requires-Dist: sphinx_gallery; extra == "docs"
Requires-Dist: sphinx-togglebutton; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx_book_theme; extra == "docs"
Requires-Dist: sphinx_design; extra == "docs"
Requires-Dist: sphinxcontrib-images; extra == "docs"
Requires-Dist: sphinxcontrib-video; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
Requires-Dist: jupytext; extra == "docs"
Requires-Dist: myst_nb; extra == "docs"
Requires-Dist: pygfx>=0.14.0; extra == "docs"
Provides-Extra: all
Requires-Dist: mbo_utilities[docs,processing]; extra == "all"
Dynamic: license-file

# MBO Utilities

> **Status:** Late-beta stage of active development. There will be bugs that can be addressed quickly, file an [issue](https://github.com/MillerBrainObservatory/mbo_utilities/issues) or reach out on slack.

Image processing utilities for the [Miller Brain Observatory](https://github.com/MillerBrainObservatory) (MBO).

## Features

- **Fast, lazy I/O** with `imread`/`imwrite` for [multiple array types](https://millerbrainobservatory.github.io/mbo_utilities/array_types.html) (ScanImage and generic TIFFs, Suite2p binaries, Zarr and HDF5)
- **Interactive GUI** via `uv run mbo` for data visualization and processing
- **(WIP) Pollen calibration** via `uv run pollen`

[![Documentation](https://img.shields.io/badge/Documentation-black?style=for-the-badge&logo=readthedocs&logoColor=white)](https://millerbrainobservatory.github.io/mbo_utilities/)

## Installation

### Quick Install

The provided installation scripts will install [UV](https://docs.astral.sh/uv/getting-started/features/) and allow you to choose a set of optional dependencies.

**Windows (PowerShell-Only):**

```powershell
irm https://raw.githubusercontent.com/MillerBrainObservatory/mbo_utilities/master/scripts/install.ps1 | iex
```

**Linux/macOS:**

```bash
curl -sSL https://raw.githubusercontent.com/MillerBrainObservatory/mbo_utilities/master/scripts/install.sh | bash
```

### Pip

For help setting up a virtual environment, see the [Virtual Environments guide](https://millerbrainobservatory.github.io/guides/venvs.html).

```bash
uv venv --python 3.12.9
uv pip install mbo_utilities

# install all optional dependencies
uv pip install "mbo_utilities[all]"
```

Using the installation scripts will install an isolated environment.

You can also install mbo_utilities into other environments and they will not conflict.

| Method | Location | Use Case |
|--------|----------|----------|
| `uv pip install` in project | `project/.venv/` | Project-specific, use with `uv run mbo` |
| `uv tool install mbo_utilities` | `~/.local/bin/` | Global `mbo` command |

### Uninstall

**If installed via quick install script:**
 
Powershell:

```powershell
uv tool uninstall mbo_utilities

# Windows - remove venv and shortcut
Remove-Item -Recurse -Force "$env:USERPROFILE\.mbo"
Remove-Item "$env:USERPROFILE\Desktop\MBO Utilities.lnk" -ErrorAction SilentlyContinue
```

Linux/macOS:

```bash

uv tool uninstall mbo_utilities

rm -rf ~/.mbo
```

**If installed in a project venv:**

```bash
uv pip uninstall mbo_utilities
```

The GUI allows registration/segmentation for users to quickly process subsets of their datasets.

These pipelines need to be installed separately.

Currently, the only supported pipeline is LBM-Suite2p-Python.

A few exciting future prospects include [masknmf](https://github.com/apasarkar/masknmf-toolbox).

```bash
uv pip install mbo_utilities[suite2p]
```

**Note:** On Windows, you may need to add `$USERPROFILE/.local/bin` to your PATH via environment variables.

## Usage

We encourage users to start with the [user_guide](https://millerbrainobservatory.github.io/mbo_utilities/user_guide.html).

You can run this code as a jupyter notebook or rendered in the [docs](./demos/user_guide.ipynb) and can be downloaded on the top right of the page.

See [array types](https://millerbrainobservatory.github.io/mbo_utilities/array_types.html) for additional information about each file-type and it's associated lazy array.

### Commands

**Launch GUI:**

`uv run mbo`: Works when in a directory with a `.venv` folder
`mbo`: Calls the global installation, from any terminal.

```bash
# in a project
uv run mbo
```

<p align="center">
  <img src="docs/_images/GUI_Slide1.png" alt="GUI Screenshot" width="45%">
  <img src="docs/_images/GUI_Slide2.png" alt="GUI Screenshot" width="45%">
</p>

**Download User Guide Notebook:**

```bash
uv run mbo --download-notebook
```

**Verify Installation:**

Check that all dependencies are correctly installed, including CUDA/GPU configuration for Suite3D z-registration:

```bash
uv run mbo --check-install
```

**Pollen Calibration:**

```bash
uv run pollen
```

**Download files from GitHub:**

```bash
# download a notebook from github
mbo download https://github.com/user/repo/blob/main/notebook.ipynb

# download to specific location
mbo download https://github.com/user/repo/blob/main/data.npy 
```

**Scan-phase analysis:**

```bash
# open file dialog
uv run mbo scanphase

# analyze specific file
uv run mbo scanphase /path/to/data.tiff

# use first 5 tiffs from a folder
uv run mbo scanphase ./folder/ -n 5

# custom output directory
uv run mbo scanphase data.tiff -o ./results/
```

**File format conversion:**

```bash
# convert tiff to zarr
uv run mbo convert input.tiff output.zarr

# convert to suite2p binary
uv run mbo convert input.tiff output.bin
```

**Show file info:**

```bash
uv run mbo info /path/to/data.tiff
```

**List supported formats:**

```bash
uv run mbo formats
```

## Installation Troubleshooting


### GPU/CUDA Errors

**Error: "Failed to auto-detect CUDA root directory"**

This error occurs when using GPU-accelerated features (like Suite3D registration) and CuPy cannot find your CUDA Toolkit installation.

#### Solution 1: Check if CUDA is installed

**PowerShell (Windows):**
```powershell
# Check for CUDA installations
dir "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA" -ErrorAction SilentlyContinue

# Check if CUDA_PATH is set
$env:CUDA_PATH
```

**Linux/macOS:**
```bash
# Check for CUDA
nvcc --version

# Check CUDA_PATH
echo $CUDA_PATH
```

#### Solution 2: Set CUDA_PATH if CUDA is installed

**PowerShell (Windows):**
```powershell
# Find your CUDA version folder (e.g., v12.1, v11.8, v12.6)
# Replace with your actual version from the directory listing above
$cuda_version = "v12.6"

# Temporary (current session)
$env:CUDA_PATH = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\$cuda_version"

# Permanent (restart terminal after)
[System.Environment]::SetEnvironmentVariable('CUDA_PATH', "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\$cuda_version", 'User')
```

**Linux/macOS:**
```bash
# Find CUDA installation (common locations)
ls /usr/local/cuda* 2>/dev/null

# Set CUDA_PATH (add to ~/.bashrc or ~/.zshrc for persistence)
export CUDA_PATH=/usr/local/cuda-12.6  # Replace with your version
```

#### Solution 3: Install CUDA Toolkit if not present

1. **Check your GPU compatibility**: Ensure you have an NVIDIA GPU
2. **Download CUDA Toolkit**: Visit [NVIDIA CUDA Downloads](https://developer.nvidia.com/cuda-downloads)
3. **Install**: Follow the installer instructions
4. **Restart your terminal** to pick up the new environment variables

**Note:** After installing CUDA Toolkit, `CUDA_PATH` should be set automatically by the installer.

#### Alternative: Use CPU-only processing

If you don't have an NVIDIA GPU or prefer not to install CUDA, you can disable GPU processing in Suite3D by modifying the registration parameters (though this will be significantly slower).

### Git LFS Download Errors (when installing directly from Github)

There is a [bug in fastplotlib](https://github.com/fastplotlib/fastplotlib/issues/861) causing `git lfs` errors when installed from a git branch.

This should be fixed soon.

- In your terminal of choice, set the `GIT_LFS_SKIP_SMUDGE` environment variable to 1
- **restart your terminal**.

**PowerShell (Windows):**
```powershell
# current session only
$env:GIT_LFS_SKIP_SMUDGE="1"

# permanent for the current user)
[System.Environment]::SetEnvironmentVariable('GIT_LFS_SKIP_SMUDGE', '1', 'User')
```

**Command Prompt (Windows):**
```cmd
REM Temporary (current session only)
set GIT_LFS_SKIP_SMUDGE=1
  GIT_LFS_SKIP_SMUDGE=1

REM Permanent (system-wide, requires admin)
setx GIT_LFS_SKIP_SMUDGE 1

  SUCCESS: Specified value was saved.
```

**Linux/macOS (bash/zsh):**
```bash
# current session only
export GIT_LFS_SKIP_SMUDGE=1

# add to .bashrc/.zshrc to be permanent for the current user 
echo 'export GIT_LFS_SKIP_SMUDGE=1' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc  # or ~/.zshrc
```

After setting the variable, restart your terminal and retry the installation.

## Issues & Support

- **Bug reports:** [GitHub Issues](https://github.com/MillerBrainObservatory/mbo_utilities/issues)
- **Questions:** See [documentation](https://millerbrainobservatory.github.io/mbo_utilities/) or open a discussion

## Built With

This package integrates several open-source tools:

- **[Suite2p](https://github.com/MouseLand/suite2p)** - Integration support
- **[Rastermap](https://github.com/MouseLand/rastermap)** - Visualization
- **[Suite3D](https://github.com/alihaydaroglu/suite3d)** - Volumetric processing
