wsi-toolbox 0.2.0__py3-none-any.whl

wsi_toolbox-0.2.0.dist-info/METADATA

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: wsi-toolbox
+Version: 0.2.0
+Summary: A comprehensive toolkit for Whole Slide Image processing, feature extraction, and clustering analysis
+Project-URL: Homepage, https://github.com/technoplasm/wsi-toolbox
+Project-URL: Repository, https://github.com/technoplasm/wsi-toolbox
+Project-URL: Documentation, https://github.com/technoplasm/wsi-toolbox/blob/master/README.md
+Author-email: Ken Enda <ken@endaaman.com>
+License: MIT License
+        
+        Copyright (c) 2025 Ken Enda
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: clustering,deep-learning,histopathology,pathology,wsi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.11
+Requires-Dist: h5py>=3.13.0
+Requires-Dist: hdbscan>=0.8.40
+Requires-Dist: imagecodecs>=2024.12.30
+Requires-Dist: joblib>=1.4.2
+Requires-Dist: leidenalg>=0.10.2
+Requires-Dist: matplotlib>=3.9.4
+Requires-Dist: networkx>=3.3
+Requires-Dist: numpy<2
+Requires-Dist: opencv-python-headless>=4.11.0.86
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: openslide-python>=1.4.1
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pillow>=11.0.0
+Requires-Dist: pydantic-autocli>=0.2.0
+Requires-Dist: pyqt6>=6.8.1
+Requires-Dist: python-igraph>=0.11.8
+Requires-Dist: rich>=14.0.0
+Requires-Dist: scikit-learn>=1.6.1
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: streamlit-aggrid>=0.3.4.post3
+Requires-Dist: streamlit-antd-components>=0.3.2
+Requires-Dist: streamlit>=1.43.2
+Requires-Dist: taskipy>=1.14.1
+Requires-Dist: tifffile>=2025.2.18
+Requires-Dist: timm>=0.9.16
+Requires-Dist: torch>=2.5.1
+Requires-Dist: torchvision>=0.20.1
+Requires-Dist: umap-learn>=0.5.7
+Requires-Dist: zarr>=3
+Provides-Extra: build
+Requires-Dist: packaging; extra == 'build'
+Requires-Dist: setuptools; extra == 'build'
+Requires-Dist: torch; extra == 'build'
+Requires-Dist: wheel; extra == 'build'
+Provides-Extra: compile
+Requires-Dist: flash-attn; extra == 'compile'
+Description-Content-Type: text/markdown
+
+# WSI Toolbox
+
+> **Note**: This package is currently unstable. API may change without notice.
+
+A comprehensive toolkit for Whole Slide Image (WSI) processing, feature extraction, and clustering analysis.
+
+## Installation
+
+```bash
+# From PyPI
+pip install wsi-toolbox
+
+# From GitHub (latest)
+pip install git+https://github.com/technoplasm/wsi-toolbox.git
+```
+
+## Quick Start
+
+### As a Python Library
+
+```python
+import wsi_toolbox as wt
+
+wt.set_default_model_preset('uni')
+cmd = wt.Wsi2HDF5Command(patch_size=256)
+result = cmd('input.ndpi', 'output.h5')
+```
+
+See [README_API.md](README_API.md) for API documentation.
+
+### As a CLI Tool
+
+After `pip install wsi-toolbox`, the CLI is available as `wsi-toolbox` or `wt`.
+For development, use `uv run wt`.
+
+```bash
+# Extract tile patches from WSI into HDF5
+wt wsi2h5 -i input.ndpi -o output.h5
+
+# Extract patch embeddings using foundation model
+wt embed -i output.h5
+
+# Run Leiden clustering on embeddings
+wt cluster -i output.h5
+
+# Compute UMAP projection
+wt umap -i output.h5
+
+# Compute PCA projection
+wt pca -i output.h5
+
+# Generate cluster overlay preview image
+wt preview -i output.h5
+
+# Generate PCA score heatmap preview
+wt preview-pca -i output.h5 -n pca1
+
+# Show HDF5 file structure
+wt show -i output.h5
+
+# Export WSI to Deep Zoom Image format
+wt dzi -i input.ndpi -o ./output
+
+# Generate thumbnail from WSI
+wt thumb -i input.ndpi
+```
+
+Each subcommand has detailed help: `wt <subcommand> --help`
+
+### Streamlit Web Application
+
+```bash
+uv run task app
+```
+
+## HDF5 File Structure
+
+WSI-toolbox stores all data in a single HDF5 file.
+
+### Core Data
+
+```
+patches                    # Patch images: [N, H, W, 3]
+coordinates                # Patch pixel coordinates: [N, 2]
+```
+
+### Metadata
+
+Metadata is stored in **file attrs** (recommended):
+
+```python
+with h5py.File('output.h5', 'r') as f:
+    mpp = f.attrs['mpp']
+    patch_size = f.attrs['patch_size']
+    patch_count = f.attrs['patch_count']
+    # ...
+```
+
+Available attrs: `original_mpp`, `original_width`, `original_height`, `image_level`, `mpp`, `scale`, `patch_size`, `patch_count`, `cols`, `rows`
+
+> Legacy `metadata/*` datasets are kept for backward compatibility but attrs are preferred.
+
+### Model Features
+
+```
+{model}/features           # Patch features: [N, D]
+                           #   uni: [N, 1024]
+                           #   gigapath: [N, 1536]
+                           #   virchow2: [N, 2560]
+{model}/latent_features    # Latent features (optional): [N, L, D]
+```
+
+### Clustering & Analysis (Hierarchical)
+
+Results are stored in a hierarchical namespace structure:
+
+```
+{model}/{namespace}/clusters     # Cluster labels: [N]
+{model}/{namespace}/umap         # UMAP coordinates: [N, 2]
+{model}/{namespace}/pca1         # PCA scores: [N] or [N, k]
+```
+
+**Namespace**:
+- Single file: `default`
+- Multiple files: `file1+file2+...` (auto-generated from filenames)
+
+**Filter hierarchy**: Sub-clustering creates nested paths:
+
+```
+# Base clustering
+uni/default/clusters
+
+# Sub-cluster patches in clusters 1, 2, 3
+uni/default/filter/1+2+3/clusters
+
+# Further sub-cluster within that
+uni/default/filter/1+2+3/filter/0+1/clusters
+```
+
+Each level stores its own clusters, umap, pca results independently.
+
+## Features
+
+- WSI processing (.ndpi, .svs, .tiff → HDF5)
+- Feature extraction (UNI, Gigapath, Virchow2)
+- Leiden clustering with UMAP visualization
+- Preview generation (cluster overlays, PCA heatmaps)
+- Type-safe command pattern with Pydantic results
+- CLI, Python API, and Streamlit GUI
+
+## Documentation
+
+- [API Guide](README_API.md) - Python API documentation
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/technoplasm/wsi-toolbox.git
+cd wsi-toolbox
+uv sync
+
+# Run CLI
+uv run wt --help
+
+# Run Streamlit app
+uv run task app
+```
+
+### Optional: Gigapath support
+
+```bash
+uv sync --group gigapath
+```
+
+## License
+
+MIT

wsi_toolbox-0.2.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+wsi_toolbox/__init__.py,sha256=oAhGxi1bhoWnox-ItOTSLsqAdLxOcAlOmBxq7aWHWQE,2838
+wsi_toolbox/app.py,sha256=QkgaU9D29z_stSAQkCLFxtaICQtCJ3nW6yD4gjhfYM8,32599
+wsi_toolbox/cli.py,sha256=EQUGWFbwEVTp9mz528MKCIGO424bww4VC3jW1athRwc,22632
+wsi_toolbox/common.py,sha256=a9rDFOCuuY8pFRw1WXBKTmA8le-upBQCgk-Vn4qNqFk,4250
+wsi_toolbox/models.py,sha256=HsI-A-R51KVl3MDTxxewGQi68S2G1mSYVGKFQFmd1xA,1095
+wsi_toolbox/watcher.py,sha256=K09zKaarMkIeG3xVW9HgtgrByyYiFiFulsK5lUjoPc4,9990
+wsi_toolbox/wsi_files.py,sha256=hTw3GH1RlHc1DR1Ll6N9BSywuI_f7hD52QIKA2LroYk,20840
+wsi_toolbox/commands/__init__.py,sha256=PpvRzZ47eIpOhZ-M0VP7mFKPvQ32KEgQTc6aHWFx_eA,1511
+wsi_toolbox/commands/clustering.py,sha256=WUqPmEuj-Z5jKN8VmBa4yOUjznAbD4Dc29Glct3uRUM,7134
+wsi_toolbox/commands/data_loader.py,sha256=0vhzmNDBTrVnF3APvk_v0pY5RIM0tKgN-C7LV5YYNLw,7439
+wsi_toolbox/commands/dzi.py,sha256=7QApixPe2WjjlPNykLG9DhF7_YDrsb2r9aELvC3ZUrE,4882
+wsi_toolbox/commands/patch_embedding.py,sha256=KX0jr4UJV0ojNI8v_-5R_xRpCqESN906dse7EevdN_s,7086
+wsi_toolbox/commands/pca.py,sha256=x2WZfjozuaefq32O0B7QOUsT31Tad6LB3Yj5bZT3hmo,7208
+wsi_toolbox/commands/preview.py,sha256=PpMCi7Qq7s7D_Obj2EZJ4_vx0w8DUm1pizBm-LaVoM0,12490
+wsi_toolbox/commands/show.py,sha256=4cTulTIW6KOjxtbTVkqTTmbsFLI1MuKr5-YpJjKN0Og,6354
+wsi_toolbox/commands/umap_embedding.py,sha256=PnNfUCuohOcpcIwlLj1N9MFCKMKVKmUV87vacqoqD6M,6272
+wsi_toolbox/commands/wsi.py,sha256=ctI4iTntYJCNSalqOkgPHgzMp_1uxR0_pRnuy5i0ykM,7873
+wsi_toolbox/utils/__init__.py,sha256=JAih9kAplR8JCZ6I7NGDBJQ3GStUuhrr_f1lQdBvtQA,3465
+wsi_toolbox/utils/analysis.py,sha256=ugLhr_HmF7mT9073qyRCKVWnJEzRmT8mFppdhYHNdb0,5863
+wsi_toolbox/utils/hdf5_paths.py,sha256=xBe3mQ06-QOy3PnnMYEZK5dNdyCrhABZLpDKfo0i-co,6410
+wsi_toolbox/utils/plot.py,sha256=tu15GQrGebjLrCJGL2OTkTqj5IEN26x_imFOSSorhhg,7387
+wsi_toolbox/utils/progress.py,sha256=uHuiCq0T1xkrZQKUVF5NNhu0gAZaoTauF1hfeVk5zOo,6504
+wsi_toolbox/utils/seed.py,sha256=eMCr9BssUG8hqQ6xK6FqFJgdiXU6nnBX5iXO2gIzViE,582
+wsi_toolbox/utils/st.py,sha256=OavRVC9TcnoLo0AwpRIlDI3VWinj83nxGsp_7lJyDZs,2036
+wsi_toolbox/utils/white.py,sha256=XNZz-Wq9rXJym9hC1cqiawG_UxJcUARWuxSKnc2s63g,4006
+wsi_toolbox-0.2.0.dist-info/METADATA,sha256=6-G7OOhaal1jScFgapKyq5hPP0r5-m9f3afsL28nlzc,7175
+wsi_toolbox-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+wsi_toolbox-0.2.0.dist-info/entry_points.txt,sha256=xyCLZAoyQxi2v-Dh8IIUrqxC6Sr_8WDgWbrceNTFiNk,79
+wsi_toolbox-0.2.0.dist-info/licenses/LICENSE,sha256=YEzz8a8Kd5ZhRNItsiPJYFMfgXN1JDVZ9UG7UzTYvNU,1065
+wsi_toolbox-0.2.0.dist-info/RECORD,,

wsi_toolbox-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

wsi_toolbox-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+wsi-toolbox = wsi_toolbox.cli:main
+wt = wsi_toolbox.cli:main

wsi_toolbox-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ken Enda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.