Skip to content

Installation Guide#

Prerequisites#

  • Python 3.8 or higher
  • Pixi (recommended, install pixi following the official instructions ) or Conda for dependency management

Using Pixi - automatically handles all dependencies including conda packages:

# macOS/Linux
curl -fsSL https://pixi.sh/install.sh | bash

# Windows (PowerShell)
iwr -useb https://pixi.sh/install.ps1 | iex

# Create a new project
pixi init omero-annotate-ai
cd omero-annotate-ai

# Add dependencies
pixi add python=3.12
pixi add micro-sam                      # AI model
pixi add --pypi omero-annotate-ai      # Main package

# Activate environment
pixi shell

Verify Installation#

Run pixi run python, then: 

import omero_annotate_ai
print(f"✅ Version: {omero_annotate_ai.__version__}")

Alternative: Conda + Pip#

For users who prefer manual conda environment management:

# Create and activate environment
conda create -n omero-ai python=3.11
conda activate omero-ai

# Install conda dependencies
conda install -c conda-forge micro-sam napari zeroc-ice

# Install package from PyPI
pip install omero-annotate-ai

Quick Start#

After installation, try connecting to OMERO:

from omero_annotate_ai import create_omero_connection_widget

# Display connection widget in Jupyter
conn_widget = create_omero_connection_widget()
conn_widget.display()

# Get connection
conn = conn_widget.get_connection()

Development Setup#

For contributors who want to modify the code:

Clone and Install#

git clone https://github.com/Leiden-Cell-Observatory/omero_annotate_ai.git
cd omero_annotate_ai
pixi install              # Installs dev dependencies + package in editable mode

Run Tests#

pixi run pytest           # Run all tests
pixi run test-unit        # Run unit tests only
pixi run test-cov         # Run with coverage report

Development Environments#

Pixi provides multiple environments configured in pyproject.toml:

pixi shell                # Default environment (user)
pixi shell -e dev         # Development tools (pytest, black, isort)
pixi shell -e docs        # Documentation building (mkdocs)

Code Quality#

pixi run format           # Format code with black and isort
pixi run lint             # Check code quality

Troubleshooting#

Pixi not found#

Install pixi following the official instructions:

# macOS/Linux
curl -fsSL https://pixi.sh/install.sh | bash

# Windows (PowerShell)
iwr -useb https://pixi.sh/install.ps1 | iex

Import Errors#

micro-SAM not found:

# With pixi
pixi add micro-sam

# With conda
conda install -c conda-forge micro-sam

OMERO connection issues:

# Ensure OMERO dependencies are installed
pixi add --pypi omero-py ezomero

Widget Display Issues#

Widgets not showing in Jupyter:

# Install and enable widget extension
pip install ipywidgets
jupyter nbextension enable --py widgetsnbextension

Platform-Specific Issues#

zeroc-ice installation:

For pip-only installations (without conda), zeroc-ice requires platform-specific wheels:

Note: Both pixi and conda handle zeroc-ice automatically - no manual wheel installation needed.

Next Steps#