histoseg 0.1.9.3

Python toolkit for H&E image analysis, spatial contour analysis, and 3D contour reconstruction.

HistoSeg

Python toolkit for H&E image analysis, spatial contour analysis, and 3D contour reconstruction.

HistoSeg has three public feature groups:

• HE Analysis (histoseg.he) for image-based H&E tissue segmentation, neutral tissue partitioning, and aligned-image change detection.
• Contour Analysis (histoseg.contour) for contour extraction from spatial/cell-coordinate data, including Pattern1 isolines and multi-structure Xenium exports.
• 3D Analysis (histoseg.threed) for same-sample, multi-slice Xenium contour alignment and reconstruction workflows.

Full documentation: histoseg.readthedocs.io

When To Use Each Feature Group

Use HE Analysis when your input is an H&E image such as PNG, JPG, TIFF, or GeoTIFF and you want masks, overlays, heatmaps, GeoJSON polygons, or region tables.

Use Contour Analysis when your input is spatial cell-coordinate data such as Xenium cells.parquet plus cluster assignments, and you want geometry extracted from cell neighborhoods or selected cluster groups.

Use 3D Analysis when you are preparing for multi-slice Xenium contour reconstruction from the same sample. The first released workflow soft-aligns a hard-aligned moving contour GeoJSON to a fixed reference slice with a conservative TPS displacement field.

Installation

pip install -U histoseg

For local Hugging Face MedSAM-backed HE segmentation:

pip install -U "histoseg[he]"

For development:

git clone https://github.com/hutaobo/HistoSeg.git
cd HistoSeg
pip install -U pip
pip install -e ".[he]"

HE Analysis Quickstart

from histoseg.he import HESegmentationConfig, run_he_segmentation

result = run_he_segmentation(
    HESegmentationConfig(
        image="/path/to/he.png",
        out_dir="outputs/he_all_elements",
        task="all_elements",
        backend="heuristic",
        n_components=6,
    )
)

print(result.overlay_png)
print(result.geojson)

histoseg-he all-elements \
  --image /path/to/he.png \
  --out-dir outputs/he_all_elements \
  --backend heuristic

HE Analysis currently supports:

• single: tissue foreground extraction, or user-prompted region extraction from boxes/points
• all_elements: neutral tissue component partitioning (component_1, component_2, ...)
• change: aligned before/after H&E change detection

Contour Analysis Quickstart

from histoseg.contour import Pattern1IsolineConfig, run_pattern1_isoline

cfg = Pattern1IsolineConfig(
    clusters_csv="/path/to/clusters.csv",
    cells_parquet="/path/to/cells.parquet",
    tissue_boundary_csv="/path/to/tissue_boundary.csv",
    out_dir="outputs/pattern1_isoline0p5",
    pattern1_clusters=(10, 23, 19, 27, 14, 20, 25, 26),
)

result = run_pattern1_isoline(cfg)
print(result.preview_png)
print(len(result.contours))

histoseg-contour pattern1 \
  --clusters-csv clusters.csv \
  --cells-parquet cells.parquet \
  --out-dir outputs/pattern1 \
  --pattern1-clusters 10,23,19

Contour Analysis currently supports:

• Pattern1 isoline contour generation from clustered cell coordinates
• multi-structure contour partitioning
• Xenium Explorer annotation exports
• Hugging Face dataset helper workflows for Xenium-style inputs

3D Analysis Quickstart

from histoseg.threed import (
    ThreeDContourReconstructionConfig,
    run_3d_contour_reconstruction,
)

cfg = ThreeDContourReconstructionConfig(
    fixed_geojson="slice_01.geojson",
    moving_hard_aligned_geojson="slice_02_hard_aligned_to_01.geojson",
    out_dir="outputs/3d_soft_alignment",
    group_property="structure",
    diagnostic_structure="Structure 5",
)

result = run_3d_contour_reconstruction(cfg)
print(result.soft_aligned_geojson)
print(result.diagnostic_report_png)

histoseg-3d reconstruct \
  --fixed-geojson slice_01.geojson \
  --moving-hard-aligned-geojson slice_02_hard_aligned_to_01.geojson \
  --out-dir outputs/3d_soft_alignment \
  --group-property structure \
  --diagnostic-structure "Structure 5"

3D Analysis currently performs the soft TPS registration/pre-reconstruction step. It does not yet generate a 3D mesh or volume.

Outputs

HistoSeg workflows write reviewable artifacts such as:

• PNG previews and overlays
• label maps and heatmaps
• GeoJSON polygons
• CSV/Parquet region or contour tables
• params.json and metrics.json provenance files

Documentation

• HE Analysis
• Contour Analysis
• 3D Analysis
• 3D contour soft alignment tutorial
• API Reference

License

This project is distributed under the PolyForm Noncommercial 1.0.0 license. Academic and other noncommercial use is permitted. Any commercial use requires a separate commercial license from SPATHO AB. See LICENSE for details.