### Install LazySlide

Source: https://github.com/rendeirolab/lazyslide/blob/main/README.md

Install LazySlide using pip or uv. Installation time is typically around 4 seconds on a MacBook Pro with uv.

```bash
pip install lazyslide
```

```bash
uv add lazyslide
```

--------------------------------

### Serve documentation

Source: https://github.com/rendeirolab/lazyslide/blob/main/CONTRIBUTING.md

Start a local server to preview the documentation at http://localhost:8000.

```bash
uv run task doc-serve
```

--------------------------------

### Start a Python session

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/contributing/setup.md

Launch an interactive Python environment using uv.

```bash
uv run --with ipython ipython
```

```bash
uv run --with jupyter jupyter lab
# With extensions
uv run --with jupyter --with dask-labextension jupyter lab
```

--------------------------------

### Install Lazyslide using uv

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/installation.rst

Install lazyslide using the uv package manager.

```bash
uv add lazyslide
```

--------------------------------

### Initialize development environment

Source: https://github.com/rendeirolab/lazyslide/blob/main/CONTRIBUTING.md

Lock dependencies and install pre-commit hooks to ensure code quality.

```bash
uv lock
uv run pre-commit install
```

--------------------------------

### Install pre-commit hooks

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/contributing/setup.md

Initialize pre-commit hooks to enforce code quality standards.

```bash
uv run pre-commit install
```

--------------------------------

### Install Lazyslide from GitHub

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/installation.rst

Install the latest development version of lazyslide directly from its GitHub repository.

```bash
pip install git+https://github.com/rendeirolab/lazyslide.git
```

--------------------------------

### Install OpenSlide reader using pip

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/installation.rst

Install the OpenSlide C library and its Python bindings using pip.

```bash
pip install openslide-python openslide-bin
```

--------------------------------

### Start interactive session

Source: https://github.com/rendeirolab/lazyslide/blob/main/CONTRIBUTING.md

Launch an IPython or Jupyter session using the project's environment.

```bash
uv run --with ipython ipython
# or
uv run --with jupyter jupyter lab
```

--------------------------------

### Install Lazyslide using pip

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/installation.rst

Use this command for the default installation of lazyslide via PyPI.

```bash
pip install lazyslide
```

--------------------------------

### Install Lazyslide using Mamba

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/installation.rst

Install lazyslide using the Mamba package manager.

```bash
mamba install lazyslide
```

--------------------------------

### Install Lazyslide using Conda

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/installation.rst

Install lazyslide from the conda-forge channel using Conda.

```bash
conda install conda-forge::lazyslide
```

--------------------------------

### Install BioFormats reader

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/installation.rst

Install the scyjava package to interact with the BioFormats library for reading various life sciences image formats.

```bash
pip install scyjava
```

--------------------------------

### Install TiffSlide reader

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/installation.rst

Install the TiffSlide reader, which is based on tifffile and provides openslide-python compatibility.

```bash
pip install tiffslide
```

--------------------------------

### Install OpenSlide reader using Conda/Mamba

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/installation.rst

Install the OpenSlide Python bindings from the conda-forge channel, recommended for Linux and OSX users.

```bash
conda install -c conda-forge openslide-python
```

```bash
mamba install -c conda-forge openslide-python
```

--------------------------------

### Download Hugging Face Model Snapshot

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/avail_models.md

Use this Python function to download all files for a specific Hugging Face model repository. Ensure you have the huggingface_hub library installed.

```python
from huggingface_hub import snapshot_download

snapshot_download("model-repo-name")
```

--------------------------------

### Define a Custom Vision Model for LazySlide

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/contributing/new_models.md

This example demonstrates how to create a custom vision model by inheriting from `ImageModel` and implementing the `encode_image` method. It includes model registration with Hugging Face access and transformation handling.

```python
import torch

from lazyslide.models import hf_access, register
from lazyslide.models.base import ImageModel, ModelTask


# A key must be defined to register the model
@register(
    key="the key of the model",
    is_gated=False,  # Optional, by default is False, is the model gated on huggingface?
    task=ModelTask.vision,  # Required, can be a list
    license="MIT",  # Required
    description="The greatest model ever",
    commercial=True,  # Required, can the model be used for commercial purpose?
    hf_url="https://huggingface.co/xxx",  # Optional
    github_url="https://github.com/xxx/xxx",  # Optional
    paper_url="https://doi.org/xxx/xxx",  # Optional
    bib_key="xxx",  # Optional, Add the bib entry to docs/source/references.bib
    param_size="87.8M",  # Optional
    encode_dim=512,  # Optional
)
class MyGreatModel(ImageModel):

    def __init__(self):
        from huggingface_hub import hf_hub_download

        # Use this context manager if your model is gated on huggingface
        with hf_access("my-repo/my-great-model"):
            model_file = hf_hub_download("my-repo/my-great-model", "model.pt")

        self.model = torch.jit.load(model_file, map_location="cpu")
        self.model.eval()

    # Define the transformation here, will automatically be applied
    def get_transform(self):
        return self.model.get_custom_transform()

    @torch.inference_mode()
    def encode_image(self, image):
        """
        Encode the input image using the model.
        The model should expect a tensor of shape [B, C, H, W].
        """
        output = self.model(image)
        return output

```

--------------------------------

### Quick Start: Process Whole Slide Image

Source: https://github.com/rendeirolab/lazyslide/blob/main/README.md

Process a whole slide image using LazySlide's pipeline for tissue segmentation, tiling, and feature extraction. Access and visualize extracted features.

```python
import lazyslide as zs

wsi = zs.datasets.sample()

# Pipeline
zs.pp.find_tissues(wsi)
zs.pp.tile_tissues(wsi, tile_px=256, mpp=0.5)
zs.tl.feature_extraction(wsi, model='resnet50')

# Access the features
features = wsi['resnet50_tiles']

# Visualize the 1st and 99th features
zs.pl.tiles(wsi, feature_key="resnet50", color=["1", "99"])
```

--------------------------------

### Build and serve documentation

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/contributing/setup.md

Build the documentation using Sphinx and serve it locally.

```bash
# Build doc with cache
uv run task doc-build
# Fresh build
uv run task doc-clean-build
```

```bash
uv run task doc-serve
```

--------------------------------

### Build documentation

Source: https://github.com/rendeirolab/lazyslide/blob/main/CONTRIBUTING.md

Generate the project documentation with or without cache.

```bash
# Build doc with cache
uv run task doc-build
# Fresh build
uv run task doc-clean-build
```

--------------------------------

### Sync development environment

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/contributing/setup.md

Synchronize the project dependencies using uv.

```bash
uv sync
```

--------------------------------

### Loading Sample Datasets

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Access built-in sample datasets for testing and demonstration purposes.

```python
import lazyslide as zs

# Load a small sample slide (~1.9 MB)
wsi = zs.datasets.sample()

# Load GTEx artery slide
wsi = zs.datasets.gtex_artery()

# Load GTEx small intestine slide
wsi = zs.datasets.gtex_small_intestine()

# Load lung carcinoma slide
wsi = zs.datasets.lung_carcinoma()

# Load without pre-computed data (just the slide)
wsi = zs.datasets.sample(with_data=False)
```

--------------------------------

### Retrieve and initiate a model class

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/avail_models.md

Access a specific model class from the registry and instantiate it.

```python
from lazyslide.models import MODEL_REGISTRY
model_module = MODEL_REGISTRY['instanseg']
model = model_module()  # Initiate the model
```

--------------------------------

### Clone the repository

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/contributing/setup.md

Use git or the GitHub CLI to clone the project.

```bash
git clone https://github.com/rendeirolab/lazyslide.git
# or
gh repo clone rendeirolab/lazyslide
```

--------------------------------

### Format code

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/contributing/setup.md

Run code formatting using task or ruff.

```bash
uv run task fmt
# or
ruff format docs/source src/lazyslide tests
```

--------------------------------

### Run tests

Source: https://github.com/rendeirolab/lazyslide/blob/main/CONTRIBUTING.md

Execute the project test suite using the configured task runner.

```bash
uv run task test
```

--------------------------------

### Download Hugging Face Model via CLI

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/avail_models.md

This command-line interface command downloads a specified Hugging Face model repository. It's a convenient alternative to the Python function for quick downloads.

```bash
hf download model-repo-name
```

--------------------------------

### Checkout a new branch

Source: https://github.com/rendeirolab/lazyslide/blob/main/CONTRIBUTING.md

Create and switch to a new branch for your development work.

```bash
git checkout -b my-new-branch
```

--------------------------------

### Checkout a new branch

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/contributing/setup.md

Create and switch to a new feature branch.

```bash
git checkout -b new-feature
```

--------------------------------

### Opening Whole Slide Images

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Use wsidata to open WSI files and access their metadata properties or persistent Zarr storage.

```python
import lazyslide as zs
from wsidata import open_wsi

# Open a whole slide image from file
wsi = open_wsi("path/to/slide.svs")

# Access slide properties
print(f"Dimensions: {wsi.properties.level_shape}")
print(f"MPP: {wsi.properties.mpp}")
print(f"Number of levels: {wsi.properties.n_level}")

# Open with existing zarr storage (for persistent analysis)
wsi = open_wsi("path/to/slide.svs", store="path/to/slide.zarr")
```

--------------------------------

### Tile Prediction with Contrast Model

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Runs tile-level prediction models, such as the 'contrast' model, for quality control or phenotype classification. Requires preprocessing steps.

```python
import lazyslide as zs

wsi = zs.datasets.sample()
zs.pp.find_tissues(wsi)
zs.pp.tile_tissues(wsi, tile_px=256, mpp=0.5)

# Tile prediction with built-in models
zs.tl.tile_prediction(
    wsi,
    model="contrast",          # Predict contrast scores
    tile_key="tiles",
    batch_size=16,
    device="cuda",
    pbar=True
)

# List available tile prediction models
from lazyslide.models import list_models
print(list_models("tile_prediction"))

# Access predictions (stored in tile shapes)
tiles = wsi.shapes["tiles"]
print(tiles.columns)  # Prediction columns added
```

--------------------------------

### Load Slide File with WSIdata

Source: https://github.com/rendeirolab/lazyslide/blob/main/README.md

Load your slide file using the open_wsi function from the wsidata library.

```python
from wsidata import open_wsi

wsi = open_wsi("path_to_slide")
```

--------------------------------

### Implement Segmentation Model

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/contributing/new_models.md

Create a segmentation model by inheriting from SegmentationModel and implementing segment and supported_output methods. Specify the output types in supported_output.

```python
import torch

from lazyslide.models.base import SegmentationModel, ModelTask
from lazyslide.models import register


@register(
    key="super-segmentation",
    task=ModelTask.segmentation,
    license="Apache 2.0",
    commercial=True,
)
class MySuperSegmentation(SegmentationModel):
    """Apply the InstaSeg model to the input image."""

    def __init__(self):
        from huggingface_hub import hf_hub_download

        model_file = hf_hub_download("my-repo/my-super-segmentation", "model.pt")

        self.model = torch.jit.load(model_file, map_location="cpu")
        self.model.eval()

    @torch.inference_mode()
    def segment(self, image):
        out = self.model(image)
        return {"instance_map": out.long().squeeze(1)}

    def supported_output(self):
        return ("instance_map",)  # Can be multiple outputs

```

--------------------------------

### Run tests

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/contributing/setup.md

Execute the test suite using pytest.

```bash
uv run task test
```

```bash
uv run python -m pytest tests/test_example.py
```

--------------------------------

### Clone the repository

Source: https://github.com/rendeirolab/lazyslide/blob/main/CONTRIBUTING.md

Use these commands to clone the LazySlide repository to your local machine.

```bash
git clone https://github.com/rendeirolab/LazySlide.git
# or
gh repo clone rendeirolab/LazySlide
```

--------------------------------

### Configure OpenSlide binary path on Windows

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/installation.rst

On Windows, ensure the OpenSlide binary directory is added to the DLL search path before importing openslide. Replace 'path/to/openslide/bin' with the actual path to your OpenSlide bin directory.

```python
import os
with os.add_dll_directory("path/to/openslide/bin"):
    import openslide
```

--------------------------------

### Register and create custom models

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Access the model registry or define custom feature extraction models.

```python
import lazyslide as zs
from lazyslide.models import MODEL_REGISTRY, list_models
from lazyslide.models.base import ImageModel
import torch

# List all available models by task
print("Vision models:", list_models("vision"))
print("Multimodal models:", list_models("multimodal"))
print("Segmentation models:", list_models("segmentation"))
print("Tile prediction:", list_models("tile_prediction"))

# Get a specific model class
UNI = MODEL_REGISTRY["uni"]
model = UNI()

# Create a custom model
class MyCustomModel(ImageModel):
    def __init__(self, model_path):
        self.model = torch.jit.load(model_path)
        self.model.eval()

    def get_transform(self):
        from torchvision.transforms.v2 import Compose, ToImage, ToDtype, Normalize, Resize
        return Compose([
            ToImage(),
            ToDtype(dtype=torch.float32, scale=True),
            Resize(size=(224, 224)),
            Normalize(mean=(0.485, 0.456, 0.406), std=(0.229, 0.224, 0.225)),
        ])

    @torch.inference_mode()
    def encode_image(self, image):
        return self.model(image)

# Use custom model
custom_model = MyCustomModel("path/to/model.pt")
zs.tl.feature_extraction(wsi, model=custom_model, model_name="custom")
```

--------------------------------

### Visualize Tiles with Feature Coloring using pl.tiles

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Displays tiles with optional feature coloring for spatial visualization. Supports heatmap or scatter styles and custom colormaps.

```python
import lazyslide as zs
import matplotlib.pyplot as plt

wsi = zs.datasets.sample()
zs.pp.find_tissues(wsi)
zs.pp.tile_tissues(wsi, tile_px=256, mpp=0.5)
zs.tl.feature_extraction(wsi, model="resnet50")

# Basic tile visualization
zs.pl.tiles(wsi, linewidth=0.5)
plt.show()

# Color tiles by extracted features
zs.pl.tiles(
    wsi,
    feature_key="resnet50",
    color=["1", "99"],         # Feature indices to visualize
    style="heatmap",           # "heatmap" or "scatter"
    cmap="viridis",
    alpha=0.9
)
plt.show()
```

--------------------------------

### List available models

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/avail_models.md

Retrieve a list of all available models in the LazySlide registry.

```python
from lazyslide.models import list_models

models = list_models()
```

--------------------------------

### Configure Global Settings in LazySlide

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Access and modify global settings for device, automatic mixed precision (AMP), and progress bars in LazySlide. Settings affect all subsequent operations.

```python
import lazyslide as zs

# Access and modify global settings
print(f"Default device: {zs.settings.device}")
print(f"AMP enabled: {zs.settings.amp}")
print(f"Progress bar: {zs.settings.pbar}")

# Change settings
zs.settings.device = "cuda"
zs.settings.amp = True
zs.settings.autocast_dtype = "float16"
zs.settings.pbar = True

# Settings affect all subsequent operations
wsi = zs.datasets.sample()
zs.pp.find_tissues(wsi)
zs.pp.tile_tissues(wsi, tile_px=256, mpp=0.5)
zs.tl.feature_extraction(wsi, model="resnet50")  # Uses GPU with AMP
```

--------------------------------

### TopK Metric

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/metrics.rst

Utility for calculating Top-K performance metrics.

```APIDOC
## topk

### Description
Calculates the Top-K metric for performance evaluation.

### Module
lazyslide.metrics
```

--------------------------------

### Build Spatial Tile Graph

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Constructs a spatial graph connecting neighboring tiles for graph-based analysis. Requires pre-generated tiles and tissue detection.

```python
import lazyslide as zs

wsi = zs.datasets.sample(with_data=False)
zs.pp.find_tissues(wsi)
zs.pp.tile_tissues(wsi, tile_px=256, mpp=0.5)

# Build spatial graph
zs.pp.tile_graph(
    wsi,
    n_neighs=6,                # Number of neighbors
    n_rings=1,                 # Number of neighbor rings
    delaunay=False,            # Use Delaunay triangulation
    transform=None,            # "spectral", "cosine", or None
    tile_key="tiles"
)

# Access the graph (stored as AnnData)
graph = wsi.tables["tiles_graph"]
print(f"Graph has {graph.n_obs} nodes")
print(f"Adjacency matrix shape: {graph.obsp['spatial_connectivities'].shape}")
```

--------------------------------

### Implement Tile Prediction Model

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/contributing/new_models.md

Develop a tile prediction model by inheriting from TilePredictionModel and implementing the predict method. The predict method should return a dictionary parsable as a DataFrame.

```python
import torch

from lazyslide.models.base import TilePredictionModel, ModelTask
from lazyslide.models import register


@register(
    key="super-tile-prediction",
    ...
)
class MySuperTilePrediction(TilePredictionModel, ):
    
    def __init__(self):
        from huggingface_hub import hf_hub_download
        
        model_file = hf_hub_download("my-repo/my-super-tile-prediction", "model.pt")
        
        self.model = torch.jit.load(model_file, map_location="cpu")
        self.model.eval()
    
    @torch.inference_mode()
    def predict(self, image):
        out = self.model(image)
        return {
            "is_tumor": out["is_tumor"],
            "is_normal": out["is_normal"]
        }

```

--------------------------------

### Zero-Shot Scoring with Detailed Classes

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Performs zero-shot scoring on a whole slide image (WSI) using detailed class descriptions. Requires WSI and class prompts as input.

```python
detailed_classes = [
    ["lung adenocarcinoma", "lung cancer cells"],
    ["healthy lung parenchyma", "normal alveoli"],
]
results = zs.tl.zero_shot_score(wsi, prompts=detailed_classes, feature_key="virchow_tiles")
```

--------------------------------

### Authenticate with Hugging Face

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/avail_models.md

Log in to Hugging Face using an access token to gain permission for gated models.

```bash
hf auth login --token YOUR_TOKEN
```

--------------------------------

### IO API

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/index.rst

Handles Input/Output operations for annotations related to Whole Slide Images (WSI).

```APIDOC
## IO for Annotations

### Description
IO for annotations.

### Method
N/A (Module Overview)

### Endpoint
N/A (Module Overview)

### Parameters
N/A (Module Overview)

### Request Example
N/A (Module Overview)

### Response
N/A (Module Overview)
```

--------------------------------

### Pass Model Instance to LazySlide

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/contributing/new_models.md

Alternatively, you can instantiate your model and pass the instance directly to LazySlide functions if it's not registered.

```python
cellpose_instance = Cellpose()

zs.seg.cells(wsi, model=cellpose_instance)
```

--------------------------------

### Evaluate segmentation metrics

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Calculate semantic and instance segmentation metrics like Dice, IoU, and Panoptic Quality.

```python
import lazyslide as zs
from lazyslide.metrics import (
    dice, mean_iou, accuracy, precision, recall,
    f1_score, sensitivity, specificity, pq,
    get_semantic_stats, get_instance_stats
)
import numpy as np

# Semantic segmentation metrics
pred_mask = np.array([[1, 1, 0], [1, 0, 0], [0, 0, 0]])
true_mask = np.array([[1, 1, 1], [1, 0, 0], [0, 0, 0]])

print(f"Dice: {dice(pred_mask, true_mask):.4f}")
print(f"IoU: {mean_iou(pred_mask, true_mask):.4f}")
print(f"Accuracy: {accuracy(pred_mask, true_mask):.4f}")
print(f"Precision: {precision(pred_mask, true_mask):.4f}")
print(f"Recall: {recall(pred_mask, true_mask):.4f}")
print(f"F1: {f1_score(pred_mask, true_mask):.4f}")

# Get comprehensive semantic stats
stats = get_semantic_stats(pred_mask, true_mask)
print(stats)

# Instance segmentation metrics (Panoptic Quality)
pred_instances = np.array([[1, 1, 0], [1, 2, 2], [0, 2, 2]])
true_instances = np.array([[1, 1, 0], [1, 2, 2], [0, 2, 0]])
pq_score = pq(pred_instances, true_instances)
print(f"Panoptic Quality: {pq_score:.4f}")
```

--------------------------------

### Preprocessing API

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/index.rst

Provides functions for preprocessing Whole Slide Images (WSI).

```APIDOC
## Preprocessing Functions

### Description
Functions for preprocessing Whole Slide Images (WSI).

### Method
N/A (Module Overview)

### Endpoint
N/A (Module Overview)

### Parameters
N/A (Module Overview)

### Request Example
N/A (Module Overview)

### Response
N/A (Module Overview)
```

--------------------------------

### Register and Test Lazyslide Model

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/contributing/new_models.md

Verify model availability in the MODEL_REGISTRY and instantiate it. Ensure the model name is correctly registered.

```python
from lazyslide.models import MODEL_REGISTRY, list_models

model_name = "your model name"
assert model_name in list_models()
model_class = MODEL_REGISTRY[model_name]
model_instance = model_class()  # You must call the model to initiate an instance

```

--------------------------------

### Load and export annotations

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Import annotations from GeoJSON files and export processed results to standard formats.

```python
import lazyslide as zs

wsi = zs.datasets.sample()
zs.pp.find_tissues(wsi)
zs.pp.tile_tissues(wsi, tile_px=256, mpp=0.5)

# Load annotations from QuPath GeoJSON
zs.io.load_annotations(
    wsi,
    annotations="annotations.geojson",
    explode=True,              # Explode multi-polygons
    in_bounds=False,           # Adjust for slide bounds
    join_with="tissues",       # Join with tissue shapes
    json_flatten="classification",  # Flatten JSON columns
    min_area=100,              # Minimum annotation area
    key_added="annotations"
)

# Export annotations back to GeoJSON
gdf = zs.io.export_annotations(
    wsi,
    key="cells",
    classes="cell_type",       # Column for classification
    colors={"tumor": "#FF0000", "normal": "#00FF00"},
    format="qupath",
    file="exported_cells.geojson"
)
```

--------------------------------

### List timm models

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/avail_models.md

Retrieve a list of all available timm models supported for feature extraction.

```python
from timm import list_models

timm_models = list_models()
```

--------------------------------

### Models API

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/index.rst

Includes various models used for Whole Slide Image (WSI) analysis.

```APIDOC
## Models for WSI Analysis

### Description
Models for WSI analysis.

### Method
N/A (Module Overview)

### Endpoint
N/A (Module Overview)

### Parameters
N/A (Module Overview)

### Request Example
N/A (Module Overview)

### Response
N/A (Module Overview)
```

--------------------------------

### Class Interface Documentation

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/_templates/autosummary/class.rst

Details the structure and callable interface for classes within the LazySlide module.

```APIDOC
## Class Interface

### Description
This documentation covers the autoclass generation for the LazySlide project, specifically highlighting the inclusion of the __call__ special method for class instances.

### Usage
Classes documented under this module are designed to be callable, allowing instances to be executed directly as functions.
```

--------------------------------

### io.load_annotations

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/io.rst

Function to load annotations into the lazyslide environment.

```APIDOC
## io.load_annotations

### Description
Loads annotation data from a specified source into the application.

### Endpoint
lazyslide.io.load_annotations
```

--------------------------------

### Plotting Functions and Classes

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/plotting.rst

Overview of the plotting utilities provided by the lazyslide.pl module.

```APIDOC
## Plotting Module Overview

### Description
This module provides tools for visualizing and interacting with Whole Slide Images (WSIs) and their associated data.

### Available Plotting Utilities

- **`pl.tissue`**: Function for plotting tissue regions.
- **`pl.tiles`**: Function for plotting image tiles.
- **`pl.annotations`**: Function for plotting annotations.
- **`pl.WSIViewer`**: Class for interactive Whole Slide Image viewing.
```

--------------------------------

### Visualize tile predictions

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Generate and visualize tile-level predictions on a whole slide image.

```python
zs.tl.tile_prediction(wsi, model="contrast")
zs.pl.tiles(
    wsi,
    color="contrast",
    tissue_id=0,
    show_image=True,
    show_contours=True,
    vmin=0, vmax=1,
    cmap="RdYlBu_r"
)
plt.show()
```

--------------------------------

### Tools API

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/index.rst

Offers tools for performing various analyses on Whole Slide Images (WSI).

```APIDOC
## Tools for WSI Analysis

### Description
Tools for WSI analysis.

### Method
N/A (Module Overview)

### Endpoint
N/A (Module Overview)

### Parameters
N/A (Module Overview)

### Request Example
N/A (Module Overview)

### Response
N/A (Module Overview)
```

--------------------------------

### Computer Vision API

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/index.rst

Offers Computer Vision utilities specifically for Whole Slide Image (WSI) analysis.

```APIDOC
## Computer Vision Utilities for WSI

### Description
Computer Vision utilities for WSI.

### Method
N/A (Module Overview)

### Endpoint
N/A (Module Overview)

### Parameters
N/A (Module Overview)

### Request Example
N/A (Module Overview)

### Response
N/A (Module Overview)
```

--------------------------------

### Segmentation Module API

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/segmentation.rst

Overview of the available segmentation methods provided by the lazyslide.seg module.

```APIDOC
## Segmentation Module (lazyslide.seg)

### Description
The segmentation module provides tools for identifying and classifying biological structures and artifacts within slide images.

### Available Methods
- **seg.cells**: Performs cell segmentation.
- **seg.cell_types**: Classifies identified cells into specific types.
- **seg.semantic**: Performs semantic segmentation on the image.
- **seg.tissue**: Identifies and segments tissue regions.
- **seg.artifact**: Detects and segments image artifacts.
```

--------------------------------

### Implement Image-Text Multimodal Model

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/contributing/new_models.md

Define a custom image-text multimodal model by inheriting from ImageTextModel and implementing encode_image and encode_text methods. Use hf_access for gated Hugging Face models.

```python
import torch

from lazyslide.models import hf_access, register
from lazyslide.models.base import ImageTextModel, ModelTask


@register(
    key="the key of the model",
    task=ModelTask.vision,  # Required, can be a list
    license="MIT",  # Required
    description="The greatest model ever",
    commercial=True,  # Required, can the model be used for commercial purpose?
)
class MyGreatImageTextModel(ImageTextModel):

    def __init__(self):
        from huggingface_hub import hf_hub_download

        # Use this context manager if your model is gated on huggingface
        with hf_access("my-repo/my-great-image-text-model"):
            model_file = hf_hub_download("my-repo/my-great-image-text-model", "model.pt")

        self.model = torch.jit.load(model_file, map_location="cpu")
        self.model.eval()

    @torch.inference_mode()
    def encode_image(self, image):
        return self.model.encode_image(image)

    @torch.inference_mode()
    def encode_text(self, text):
        return self.model.encode_text(text, normalize=True)

```

--------------------------------

### Register a Model with LazySlide

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/contributing/new_models.md

Use the `register` decorator to make a model available by its string key in LazySlide functions. Ensure all required fields like `key`, `task`, `license`, and `commercial` are provided.

```python
zs.seg.cells(wsi, model='cellpose')  # 'cellpose' must be registered
```

--------------------------------

### Process masks with CV utilities

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Access mask processing utilities for segmentation post-processing.

```python
import lazyslide as zs
from lazyslide.cv import BinaryMask, InstanceMap, merge_connected_polygons, nms
import numpy as np
```

--------------------------------

### Implement Custom Image Model for LazySlide

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/avail_models.md

Inherit from LazySlide's ImageModel to integrate your custom PyTorch vision models. Implement the __init__, get_transform, and encode_image methods. Ensure your model expects a tensor of shape [B, C, H, W] for encoding.

```python
import torch

from lazyslide.models.base import ImageModel

class MyGreatModel(ImageModel):

    def __init__(self):
        from huggingface_hub import hf_hub_download

        model_file = hf_hub_download("my-repo/my-great-model", "model.pt")
        self.model = torch.jit.load(model_file, map_location="cpu")
        self.model.eval()

    # Define the transformation here, will automatically be applied
    def get_transform(self):
        return self.model.get_custom_transform()

    @torch.inference_mode()
    def encode_image(self, image):
        """
        Encode the input image using the model.
        The model should expect a tensor of shape [B, C, H, W].
        """
        output = self.model(image)
        return output
```

--------------------------------

### Perform Zero-Shot Classification

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Performs zero-shot classification on slides using multimodal models like Prism or Titan. Requires pre-extracted features and aggregation.

```python
import lazyslide as zs

wsi = zs.datasets.lung_carcinoma(with_data=False)
zs.pp.find_tissues(wsi)
zs.pp.tile_tissues(wsi, tile_px=512, mpp=0.5, background_fraction=0.95)

# Extract features with Virchow and aggregate with Prism
zs.tl.feature_extraction(wsi, model="virchow", device="cuda")
zs.tl.feature_aggregation(wsi, feature_key="virchow", encoder="prism")

# Zero-shot classification with text prompts
classes = ["lung cancer", "normal lung tissue", "inflammation"]
results = zs.tl.zero_shot_score(
    wsi,
    prompts=classes,
    feature_key="virchow_tiles",
    model="prism",             # Options: "prism", "titan"
    device="cuda"
)
print(results)  # DataFrame with probability scores per class
```

--------------------------------

### Zero-shot Learning Functions

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/tools.rst

Functions for performing zero-shot learning tasks, including scoring and slide captioning.

```APIDOC
## Zero-shot Learning

### Description
Provides capabilities for zero-shot learning, allowing for scoring and generating captions for slides without specific training data.

### Functions
- `tl.zero_shot_score`
- `tl.slide_caption`
```

--------------------------------

### Evaluate Segmentation Performance with LazySlide

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/metrics.rst

Use this snippet to evaluate both instance and semantic segmentation performance. Ensure ground truth and predictions are provided as GeoDataFrames. Adjust `iou_threshold` for instance segmentation as needed.

```python
import geopandas as gpd
from shapely.geometry import Polygon
from lazyslide.metrics.segmentation import (
    get_instance_stats,
    get_semantic_stats,
    accuracy,
    mean_iou,
    pq,
)

# Ground truth in geodataframe
gt_polygons = [
    Polygon([(0, 0), (10, 0), (10, 10), (0, 10)]),  # Square 1
    Polygon([(15, 15), (25, 15), (25, 25), (15, 25)])  # Square 2
]
gdf_true = gpd.GeoDataFrame({'geometry': gt_polygons})

# Prediction in geodataframe
pred_polygons = [
    Polygon([(1, 1), (9, 1), (9, 9), (1, 9)]),      # Slightly smaller square 1
    Polygon([(16, 16), (24, 16), (24, 24), (16, 24)]),  # Slightly smaller square 2
    Polygon([(30, 30), (40, 30), (40, 40), (30, 40)])   # False positive
]
gdf_pred = gpd.GeoDataFrame({'geometry': pred_polygons})

# Instance segmentation evaluation
instance_stats = get_instance_stats(gdf_true, gdf_pred, iou_threshold=0.5)

# Semantic segmentation evaluation
semantic_stats = get_semantic_stats(gdf_true, gdf_pred)

# Calculate various metrics
acc = accuracy(semantic_stats)
miou = mean_iou(instance_stats)
pq = pq(instance_stats)
```

--------------------------------

### Convert Binary Mask to Polygons

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Converts a binary mask to polygons, with options for minimum area and hole detection. Also demonstrates merging connected polygons.

```python
mask = np.zeros((100, 100), dtype=np.uint8)
mask[20:40, 20:40] = 1
mask[60:80, 60:80] = 1

binary_mask = BinaryMask(mask)
polygons = binary_mask.to_polygons(
    min_area=0.001,
    min_hole_area=0.0001,
    detect_holes=True
)
print(f"Found {len(polygons)} polygons")

merged = merge_connected_polygons(polygons)
```

--------------------------------

### Visualize annotations and segmentation

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Display loaded annotations or segmented cell data on a slide.

```python
import lazyslide as zs
import matplotlib.pyplot as plt

wsi = zs.datasets.sample()
zs.pp.find_tissues(wsi)

# Load annotations (e.g., from QuPath GeoJSON)
zs.io.load_annotations(
    wsi,
    annotations="path/to/annotations.geojson",
    key_added="annotations"
)

# Visualize annotations
zs.pl.annotations(
    wsi,
    key="annotations",
    color="classification_name",  # Column for coloring
    fill=True,                    # Fill polygons
    alpha=0.7,
    palette="tab10",
    legend=True,
    scalebar=True
)
plt.show()

# Visualize segmented cells
zs.seg.cells(wsi, model="instanseg", key_added="cells")
zs.pl.annotations(
    wsi,
    key="cells",
    tissue_id=0,
    fill=False,
    linewidth=0.5
)
plt.show()
```

--------------------------------

### Generate Slide Captions with Prism Model

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Generates text captions for histopathology slides using the Prism model. Ensure features are extracted and aggregated before caption generation.

```python
import lazyslide as zs

wsi = zs.datasets.lung_carcinoma(with_data=False)
zs.pp.find_tissues(wsi)
zs.pp.tile_tissues(wsi, tile_px=512, mpp=0.5)
zs.tl.feature_extraction(wsi, model="virchow", device="cuda")
zs.tl.feature_aggregation(wsi, feature_key="virchow", encoder="prism")

# Generate slide caption
captions = zs.tl.slide_caption(
    wsi,
    prompt=["Describe this histopathology slide:"],
    feature_key="virchow_tiles",
    max_length=100,
    model="prism",
    device="cuda"
)
print(captions["caption"].iloc[0])
```

--------------------------------

### Segmentation API

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/index.rst

Provides capabilities for segmentation tasks on Whole Slide Images (WSI).

```APIDOC
## Segmentation Tasks on WSI

### Description
Segmentation tasks on WSI.

### Method
N/A (Module Overview)

### Endpoint
N/A (Module Overview)

### Parameters
N/A (Module Overview)

### Request Example
N/A (Module Overview)

### Response
N/A (Module Overview)
```

--------------------------------

### Preprocessing Functions

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/preprocess.rst

This section covers the core preprocessing functions for tissue analysis.

```APIDOC
## Preprocessing Module

### Description
Provides functions for preprocessing image data, including tissue detection and tiling.

### Functions

#### `pp.find_tissues`

##### Description
Identifies and extracts tissue regions from an image.

##### Method
N/A (Function Call)

##### Endpoint
N/A

#### `pp.tile_tissues`

##### Description
Divides identified tissue regions into smaller tiles for further analysis.

##### Method
N/A (Function Call)

##### Endpoint
N/A

#### `pp.tile_graph`

##### Description
Constructs a graph representation from the tiled tissue data.

##### Method
N/A (Function Call)

##### Endpoint
N/A
```

--------------------------------

### Extract Features with Vision Models

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Extracts deep learning features from tiles using pre-trained vision models. Supports various models including foundation models and allows for advanced configuration.

```python
import lazyslide as zs

wsi = zs.datasets.sample()
zs.pp.find_tissues(wsi)
zs.pp.tile_tissues(wsi, tile_px=256, mpp=0.5)

# Feature extraction with ResNet50
zs.tl.feature_extraction(wsi, model="resnet50")

# Using pathology foundation models (requires access token)
zs.tl.feature_extraction(wsi, model="uni")        # UNI model
zs.tl.feature_extraction(wsi, model="virchow")    # Virchow model
zs.tl.feature_extraction(wsi, model="conch")      # CONCH model
zs.tl.feature_extraction(wsi, model="gigapath")   # GigaPath model

# Advanced feature extraction
zs.tl.feature_extraction(
    wsi,
    model="resnet50",
    device="cuda",             # GPU acceleration
    amp=True,                  # Automatic mixed precision
    batch_size=64,             # Batch size for inference
    num_workers=4,             # Data loading workers
    tile_key="tiles",          # Source tiles
    key_added="resnet50_tiles", # Output key
    pbar=True                  # Show progress bar
)

# Access extracted features as AnnData
features_adata = wsi.fetch.features_anndata("resnet50")
print(f"Feature matrix shape: {features_adata.X.shape}")

# List all available models
from lazyslide.models import list_models
print(list_models("vision"))      # Vision models
print(list_models("multimodal"))  # Multimodal models
```

--------------------------------

### Metrics API

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/index.rst

Provides metrics for scoring or evaluating results in Whole Slide Image (WSI) analysis.

```APIDOC
## Metrics for Scoring or Evaluation

### Description
Metrics for scoring or evaluation.

### Method
N/A (Module Overview)

### Endpoint
N/A (Module Overview)

### Parameters
N/A (Module Overview)

### Request Example
N/A (Module Overview)

### Response
N/A (Module Overview)
```

--------------------------------

### Plotting API

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/index.rst

Contains functions for generating plots related to Whole Slide Image (WSI) analysis.

```APIDOC
## Plotting Functions for WSI

### Description
Plotting functions for WSI.

### Method
N/A (Module Overview)

### Endpoint
N/A (Module Overview)

### Parameters
N/A (Module Overview)

### Request Example
N/A (Module Overview)

### Response
N/A (Module Overview)
```

--------------------------------

### Tissue Segmentation with find_tissues

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Perform threshold-based tissue detection using traditional image processing techniques.

```python
import lazyslide as zs

wsi = zs.datasets.sample(with_data=False)

# Basic tissue detection
zs.pp.find_tissues(wsi)

# Advanced tissue detection with custom parameters
zs.pp.find_tissues(
    wsi,
    level="auto",              # Automatically choose optimal level
    refine_level=None,         # Optional refinement at higher resolution
    to_hsv=False,              # Use RGB (True for HSV saturation channel)
    blur_ksize=17,             # Median blur kernel size
    threshold=7,               # Binary threshold value
    morph_n_iter=3,            # Morphological operation iterations
    morph_ksize=7,             # Morphological kernel size
    min_tissue_area=1e-3,      # Minimum tissue area (fraction of slide)
    min_hole_area=1e-5,        # Minimum hole area
    detect_holes=True,         # Detect holes in tissue
    filter_artifacts=True,     # Filter non-tissue artifacts
    key_added="tissues"        # Key to store results
)

# Access detected tissues
tissues = wsi.shapes["tissues"]
print(f"Found {len(tissues)} tissue regions")
```

--------------------------------

### Filter models by type

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/avail_models.md

Filter the list of available models based on their specific category.

```python
from lazyslide.models import list_models

vision_models = list_models("vision")  # for vision models only
multimodal_models = list_models("multimodal")  # for multimodal models only
segmentation_models = list_models("segmentation")  # for segmentation models only
tile_prediction_models = list_models("tile_prediction")  # for tile_prediction models only
```

--------------------------------

### Tissue/Tile Properties Functions

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/tools.rst

Functions for analyzing tissue properties and predicting tile characteristics.

```APIDOC
## Tissue/Tile Properties

### Description
Functions to compute tissue properties and perform tile predictions.

### Functions
- `tl.tissue_props`
- `tl.tile_prediction`
```

--------------------------------

### Compute Text-Image Similarity with PLIP

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Computes similarity between text embeddings and tile features using the PLIP model for spatial annotation. Normalizes and applies softmax to scores.

```python
import lazyslide as zs

wsi = zs.datasets.sample()
zs.pp.find_tissues(wsi)
zs.pp.tile_tissues(wsi, tile_px=256, mpp=0.5)

# Extract features with PLIP (multimodal model)
zs.tl.feature_extraction(wsi, model="plip", tile_key="tiles")

# Create text embeddings for tissue types
tissue_terms = ["mucosa", "submucosa", "muscularis", "lymphocyte aggregates"]
text_embeddings = zs.tl.text_embedding(
    tissue_terms,
    model="plip",              # Options: "plip", "conch", "omiclip"
    device="cuda"
)

# Compute text-image similarity
zs.tl.text_image_similarity(
    wsi,
    text_embeddings=text_embeddings,
    model="plip",
    tile_key="tiles",
    normalize=True,            # L2 normalize features
    softmax=True               # Apply softmax to scores
)

# Visualize similarity scores
zs.pl.tiles(wsi, feature_key="plip_tiles_text_similarity", color="mucosa")
```

--------------------------------

### Mask Classes

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/cv.rst

Provides various types of masks for computer vision tasks, including binary, multilabel, multiclass, instance maps, and probability maps.

```APIDOC
## Mask Classes

### Description
These classes represent different types of masks used in computer vision, such as binary masks, masks with multiple labels, and masks for instance segmentation.

### Classes
- **Mask**: Base class for masks.
- **BinaryMask**: Represents a binary mask (e.g., foreground/background).
- **MultilabelMask**: Represents a mask where each pixel can belong to multiple labels.
- **MulticlassMask**: Represents a mask where each pixel belongs to exactly one class.
- **InstanceMap**: Maps pixels to specific object instances.
- **ProbabilityMap**: Represents the probability of a pixel belonging to a certain class.
```

--------------------------------

### Multi-Modal Analysis Functions

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/tools.rst

Functions for integrating and analyzing multi-modal data, including text and images.

```APIDOC
## Multi-Modal Analysis

### Description
Enables the analysis of combined data from different modalities, such as text and images, and links RNA information.

### Functions
- `tl.text_embedding`
- `tl.text_image_similarity`
- `tl.RNALinker`
```

--------------------------------

### io.export_annotations

Source: https://github.com/rendeirolab/lazyslide/blob/main/docs/source/api/io.rst

Function to export current annotations to a file or external format.

```APIDOC
## io.export_annotations

### Description
Exports the current set of annotations to a specified destination.

### Endpoint
lazyslide.io.export_annotations
```

--------------------------------

### Generate Overlapping and Filtered Tiles

Source: https://context7.com/rendeirolab/lazyslide/llms.txt

Generates tiles from a whole slide image with specified overlap and applies background filtering. Use this for preparing image data for downstream analysis.

```python
zs.pp.tile_tissues(
    wsi,
    tile_px=512,
    stride_px=256,             # Stride for overlapping tiles
    mpp=0.5,
    edge=False,                # Exclude edge tiles
    background_filter=True,    # Filter background tiles
    background_fraction=0.3,   # Max background allowed
    background_filter_mode="approx",  # "approx" or "exact"
    tissue_key="tissues",      # Key for tissue shapes
    key_added="tiles"          # Key for tile shapes
)

# Access generated tiles
tiles = wsi.shapes["tiles"]
print(f"Generated {len(tiles)} tiles")

# Get tile specification
tile_spec = wsi.tile_spec("tiles")
print(f"Tile size: {tile_spec.width}x{tile_spec.height}")
print(f"MPP: {tile_spec.mpp}")
```