Processing Workflows

This guide describes the typical image processing workflows available in KINTSUGI.

Overview

KINTSUGI provides a complete pipeline for multi-cycle immunofluorescence image analysis:

Illumination Correction - Fix uneven lighting across images
Stitching - Combine tiled images into single large images
Deconvolution - Remove optical blur and improve resolution
Extended Depth of Focus (EDoF) - Combine Z-stacks into 2D
Registration - Align images across multiple cycles
Autofluorescence Removal - Subtract background signal
Segmentation - Identify cells and structures
Spatial Analysis - Analyze spatial relationships

Workflow 1: Single Channel Evaluation

Use this workflow to test and tune parameters on a single channel before batch processing.

Notebook: notebooks/1_Single_Channel_Eval.ipynb

Steps:

Load a single channel image
Test illumination correction parameters
Test stitching parameters
Test deconvolution settings
Evaluate results visually

Workflow 2: Cycle Processing

Batch process all channels across multiple cycles.

Notebook: notebooks/2_Cycle_Processing.ipynb

Steps:

Configure input/output directories
Set processing parameters
Run illumination correction
Run stitching
Run deconvolution (optional)
Run EDoF (optional)
Run registration

Workflow 3: Signal Isolation

Remove autofluorescence and isolate true signal.

Note: The notebook-based approach (3_Signal_Isolation.ipynb) is deprecated. Use the Claude-guided workflow or Python API instead.

Option A: Claude-Guided Workflow (Recommended)

Use Claude Code with the KINTSUGI MCP server for interactive, AI-assisted signal isolation.

Setup:

pip install kintsugi[claude]
# If using kintsugi init, Claude config is automatic
# For existing projects: kintsugi mcp config /path/to/project

Usage: Claude Code can:

Load and analyze channels
Suggest optimal parameters based on image characteristics
Apply processing with real-time feedback
Learn from successful parameters for future recommendations

Option B: Python API

from kintsugi.denoise import adaptive_denoise, denoise_nlm
from kintsugi.qc import ImageQC

# Load and assess image quality
qc = ImageQC()
result = qc.assess(image)
print(f"Quality: {result.quality_score}, Issues: {result.issues}")

# Adaptive denoising (auto-selects best method)
denoised = adaptive_denoise(image, strength="auto")

# Or use specific methods
denoised = denoise_nlm(image, patch_size=7, patch_distance=11)

Option C: Legacy Notebook

Notebook: notebooks/3_Signal_Isolation.ipynb (DEPRECATED)

Steps:

Load registered images
Identify autofluorescence channels
Subtract autofluorescence
Apply filtering
Generate final signal images

Workflow 4: Segmentation Analysis

Perform cell segmentation and spatial analysis.

Notebook: notebooks/4_Segmentation_Analysis.ipynb

Steps:

Load processed images
Run InstanSeg segmentation
Extract cell features
Perform clustering
Analyze spatial relationships

Registration Module (Kreg)

The Kreg module provides image registration functionality based on VALIS.

Basic Usage

from kintsugi.kreg import Valis

# Initialize registrar
registrar = Valis(
    src_dir="/path/to/images",
    dst_dir="/path/to/output",
    reference_img_f="cycle1.tif",
    align_to_reference=True,
)

# Run registration
registrar.register()
registrar.register_micro()  # Fine registration
registrar.warp_and_merge_slides()  # Output registered images

Configuration Options

Parameter	Description	Default
`src_dir`	Source image directory	Required
`dst_dir`	Output directory	Required
`reference_img_f`	Reference image filename	Required
`max_image_dim_px`	Max image dimension for processing	2048
`compose_non_rigid`	Enable non-rigid registration	True
`crop_to_overlap`	Crop to overlapping region	True

Visualization Module (Kview2)

The Kview2 module provides interactive visualization tools.

Basic Usage

from kintsugi.kview2 import imshow, curtain, crop

# Display image
imshow(image)

# Compare two images with curtain view
curtain(image1, image2)

# Interactive crop
cropped = crop(image)

Stitching Module (Kstitch)

The Kstitch module provides tile stitching functionality.

Basic Usage

from kintsugi.kstitch import stitch_tiles

# Stitch tiled images
stitched = stitch_tiles(
    tile_dir="/path/to/tiles",
    output_path="/path/to/output.tif",
    overlap=0.1,  # 10% overlap
)

Workflow 5: Quality Control

Assess and validate image quality at multiple levels.

Image-Level QC

from kintsugi.qc import ImageQC

qc = ImageQC()
result = qc.assess(image, marker="CD3", tissue="tonsil")

print(f"Passed: {result.passed}")
print(f"Quality Score: {result.quality_score}")
print(f"Issues: {result.issues}")
print(f"Recommendations: {result.recommendations}")

Cell-Level QC

from kintsugi.qc import CellQC

qc = CellQC()
result = qc.assess(
    cell_data,
    marker_columns=["CD3", "CD20", "DAPI"],
    morphology_columns=["area", "eccentricity"]
)

# Filter problematic cells
filtered_data = result.filtered_data
print(f"Removed {len(result.outliers)} outliers")

Marker Validation

from kintsugi.qc import MarkerQC

qc = MarkerQC()
result = qc.assess(intensities, marker_name="CD3", cell_types=cell_types)

if result.crosstalk_detected:
    print(f"Crosstalk with: {result.crosstalk_markers}")

Batch Effects

from kintsugi.qc import BatchQC

qc = BatchQC()
result = qc.assess(
    data=combined_data,
    batch_column="batch_id",
    marker_columns=["CD3", "CD20", "DAPI"]
)

if result.batch_effects_detected:
    normalized = qc.normalize_batches(data, method="quantile")

Denoising Module

KINTSUGI provides multiple denoising algorithms:

Traditional Filters

from kintsugi.denoise import (
    denoise_median,
    denoise_gaussian,
    denoise_bilateral,
    denoise_nlm,
)

# Median filter
result = denoise_median(image, size=3)

# Non-local means
result = denoise_nlm(image, patch_size=7, patch_distance=11)

Deep Learning Denoising

from kintsugi.denoise import denoise_n2v, denoise_care

# Noise2Void (self-supervised, no clean targets needed)
denoiser = N2VDenoiser()
denoiser.train(noisy_images, n_epochs=50)
result = denoiser.predict(image)

# CARE (supervised, requires paired data)
denoiser = CAREDenoiser()
denoiser.train(noisy_images, clean_images)
result = denoiser.predict(image)

Adaptive Denoising

from kintsugi.denoise import adaptive_denoise

# Automatically selects best method and parameters
result = adaptive_denoise(image, strength="auto")

Segmentation Module

Classical Segmentation

from kintsugi.segment import segment_nuclei_watershed, segment_cells_watershed

# Nuclei segmentation
nuclei = segment_nuclei_watershed(
    dapi_image,
    min_distance=10,
    threshold_method="otsu"
)

# Cell segmentation with membrane expansion
cells = segment_cells_watershed(
    membrane_image,
    nuclei_labels=nuclei,
    expansion_distance=5
)

SAM Segmentation

from kintsugi.segment import SAMSegmenter

segmenter = SAMSegmenter(model_type="vit_b")
masks = segmenter.segment(image)

# With box prompts
masks = segmenter.segment_boxes(image, boxes=[[x1, y1, x2, y2]])

Post-Processing

from kintsugi.segment import refine_masks, filter_masks_by_size

# Filter by size
filtered = filter_masks_by_size(labels, min_size=50, max_size=5000)

# Comprehensive refinement
refined = refine_masks(
    labels,
    min_size=50,
    fill_holes=True,
    smooth=True,
    split_touching=True
)

Tips for Large Datasets

Start small: Test parameters on a subset before full batch processing
Monitor memory: Use kintsugi info to check available resources
Use tiled processing: Enable tiled output for very large images
GPU acceleration: Enable CuPy for faster deconvolution
Parameter learning: Use Claude Code to build a database of successful parameters
Batch QC: Run BatchQC to detect and correct batch effects before analysis