[](https://pepy.tech/projects/cryoblob)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/py/cryoblob)
[](https://doi.org/10.5281/zenodo.15548975)
[](https://github.com/psf/black)
[](https://github.com/debangshu-mukherjee/cryoblob/actions/workflows/test.yml)
[](https://codecov.io/gh/debangshu-mukherjee/cryoblob)
[](https://github.com/debangshu-mukherjee/cryoblob/actions/workflows/docs.yml)
[](https://cryoblob.readthedocs.io/en/latest/?badge=latest)
# cryoblob
**cryoblob** is a JAX-based, JIT-compiled, scalable package for detection of amorphous blobs in low SNR cryo-EM images. It provides both traditional circular blob detection and advanced multi-method detection for complex morphologies including elongated objects and overlapping structures.
## Features
* **JAX-powered**: Leverages JAX for high-performance computing with automatic differentiation
* **GPU acceleration**: Can utilize both CPUs and GPUs for processing
* **Multi-method detection**: Advanced detection algorithms for diverse blob morphologies:
* **Traditional LoG**: Excellent for circular blobs
* **Ridge detection**: Specialized for elongated (pill-shaped) objects
* **Watershed segmentation**: Separates overlapping circular structures
* **Hessian-based detection**: Superior boundary localization
* **Adaptive filtering**: Includes adaptive Wiener filtering and thresholding
* **Batch processing**: Memory-optimized batch processing for large datasets
* **Validation**: Comprehensive parameter validation using Pydantic models
## Installation
```bash
pip install cryoblob
```
## Quick Start
### Basic Blob Detection
```python
import cryoblob as cb
# Load an MRC file
mrc_image = cb.load_mrc("your_file.mrc")
# Traditional circular blob detection
blobs = cb.blob_list_log(mrc_image)
# Process a folder of images
results = cb.folder_blobs("path/to/folder/")
# Plot results
cb.plot_mrc(mrc_image)
```
### Enhanced Multi-Method Detection
```python
# For complex scenarios with multiple blob types
circular, elongated, overlapping = cb.enhanced_blob_detection(
mrc_image,
use_ridge_detection=True, # Detect elongated objects
use_watershed=True # Separate overlapping blobs
)
print(f"Found {len(circular)} circular, {len(elongated)} elongated, "
f"and {len(overlapping)} overlapping blobs")
```
### Specialized Detection
```python
from cryoblob.valid import (create_elongated_objects_pipeline,
create_overlapping_blobs_pipeline,
create_comprehensive_pipeline)
# For elongated (pill-shaped) objects
config = create_elongated_objects_pipeline()
_, elongated_blobs, _ = cb.enhanced_blob_detection(mrc_image, **config.to_enhanced_kwargs())
# For overlapping circular structures
config = create_overlapping_blobs_pipeline()
circular, _, separated_blobs = cb.enhanced_blob_detection(mrc_image, **config.to_enhanced_kwargs())
# For comprehensive analysis (all methods)
config = create_comprehensive_pipeline()
all_results = cb.enhanced_blob_detection(mrc_image, **config.to_enhanced_kwargs())
```
## Detection Methods
| Blob Type | Method | Best For | Key Function |
|-----------|--------|----------|--------------|
| Circular | LoG | Standard round particles | `blob_list_log()` |
| Elongated | Ridge Detection | Pill-shaped, rod-like objects | `ridge_detection()` |
| Overlapping | Watershed | Touching circular structures | `watershed_segmentation()` |
| Mixed/Complex | Enhanced Detection | Multiple morphologies | `enhanced_blob_detection()` |
## Package Structure
The cryoblob package is organized into the following modules:
* **adapt**: Adaptive image processing with gradient descent optimization
* **blobs**: Core blob detection algorithms and preprocessing
* **files**: File I/O operations and batch processing
* **image**: Basic image processing functions (filtering, resizing, etc.)
* **multi**: Multi-method detection for elongated objects and overlapping blobs
* **plots**: Visualization functions for MRC images and results
* **types**: Type definitions and PyTree structures
* **valid**: Parameter validation using Pydantic models
## Use Cases
**Standard Cryo-EM Particles**
```python
# Traditional circular blob detection
blobs = cb.blob_list_log(mrc_image, min_blob_size=5, max_blob_size=20)
```
**Elongated Biological Structures**
```python
# Detect pill-shaped, rod-like, or filamentous objects
_, elongated, _ = cb.enhanced_blob_detection(
mrc_image, use_ridge_detection=True, use_watershed=False
)
```
**Overlapping or Touching Particles**
```python
# Separate overlapping circular structures
_, _, separated = cb.enhanced_blob_detection(
mrc_image, use_ridge_detection=False, use_watershed=True
)
```
**Complex Heterogeneous Samples**
```python
# Comprehensive analysis for mixed morphologies
circular, elongated, overlapping = cb.enhanced_blob_detection(
mrc_image, use_ridge_detection=True, use_watershed=True
)
```
## Performance
* **Memory Efficient**: Automatic batch size optimization and memory management
* **Scalable**: Multi-device and multi-host processing support
* **Fast**: JIT compilation and GPU acceleration where available
* **Flexible**: Selective method usage to optimize speed vs. comprehensiveness
## Package Organization
* The **codes** are located in `/src/cryoblob/`
* The **notebooks** are located in `/tutorials/`
## Documentation
For detailed API documentation and tutorials, visit: [https://cryoblob.readthedocs.io](https://cryoblob.readthedocs.io)
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Authors
- Debangshu Mukherjee (mukherjeed@ornl.gov)
- Alexis N. Williams (williamsan@ornl.gov)
Raw data
{
"_id": null,
"home_page": null,
"name": "cryoblob",
"maintainer": "Debangshu Mukherjee",
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "Debangshu Mukherjee <mukherjeed@ornl.gov>",
"keywords": "electron microscopy, cryoEM, image processing, JAX, blob detection",
"author": "Debangshu Mukherjee, Alexis N. Williams, Spenser R. Cox, Marshall T. McDonnell, Albina Y. Borisevich",
"author_email": "Debangshu Mukherjee <mukherjeed@ornl.gov>, Alexis N. Williams <williamsan@ornl.gov>, Spenser R. Cox <coxsr@ornl.gov>, Marshall T. McDonnell <mcdonnellmt@ornl.gov>, Albina Y. Borisevich <albinab@ornl.gov>",
"download_url": "https://files.pythonhosted.org/packages/b4/c0/b7f0417be97231f8a4b151db699451be47585b88b70b9348c98dec598516/cryoblob-2025.8.2.tar.gz",
"platform": null,
"description": "[](https://pepy.tech/projects/cryoblob)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://badge.fury.io/py/cryoblob)\n[](https://doi.org/10.5281/zenodo.15548975)\n[](https://github.com/psf/black)\n[](https://github.com/debangshu-mukherjee/cryoblob/actions/workflows/test.yml)\n[](https://codecov.io/gh/debangshu-mukherjee/cryoblob)\n[](https://github.com/debangshu-mukherjee/cryoblob/actions/workflows/docs.yml)\n[](https://cryoblob.readthedocs.io/en/latest/?badge=latest)\n\n# cryoblob\n\n**cryoblob** is a JAX-based, JIT-compiled, scalable package for detection of amorphous blobs in low SNR cryo-EM images. It provides both traditional circular blob detection and advanced multi-method detection for complex morphologies including elongated objects and overlapping structures.\n\n## Features\n\n* **JAX-powered**: Leverages JAX for high-performance computing with automatic differentiation\n* **GPU acceleration**: Can utilize both CPUs and GPUs for processing\n* **Multi-method detection**: Advanced detection algorithms for diverse blob morphologies:\n * **Traditional LoG**: Excellent for circular blobs\n * **Ridge detection**: Specialized for elongated (pill-shaped) objects\n * **Watershed segmentation**: Separates overlapping circular structures\n * **Hessian-based detection**: Superior boundary localization\n* **Adaptive filtering**: Includes adaptive Wiener filtering and thresholding\n* **Batch processing**: Memory-optimized batch processing for large datasets\n* **Validation**: Comprehensive parameter validation using Pydantic models\n\n## Installation\n\n```bash\npip install cryoblob\n```\n\n## Quick Start\n\n### Basic Blob Detection\n\n```python\nimport cryoblob as cb\n\n# Load an MRC file\nmrc_image = cb.load_mrc(\"your_file.mrc\")\n\n# Traditional circular blob detection\nblobs = cb.blob_list_log(mrc_image)\n\n# Process a folder of images\nresults = cb.folder_blobs(\"path/to/folder/\")\n\n# Plot results\ncb.plot_mrc(mrc_image)\n```\n\n### Enhanced Multi-Method Detection\n\n```python\n# For complex scenarios with multiple blob types\ncircular, elongated, overlapping = cb.enhanced_blob_detection(\n mrc_image,\n use_ridge_detection=True, # Detect elongated objects\n use_watershed=True # Separate overlapping blobs\n)\n\nprint(f\"Found {len(circular)} circular, {len(elongated)} elongated, \"\n f\"and {len(overlapping)} overlapping blobs\")\n```\n\n### Specialized Detection\n\n```python\nfrom cryoblob.valid import (create_elongated_objects_pipeline, \n create_overlapping_blobs_pipeline,\n create_comprehensive_pipeline)\n\n# For elongated (pill-shaped) objects\nconfig = create_elongated_objects_pipeline()\n_, elongated_blobs, _ = cb.enhanced_blob_detection(mrc_image, **config.to_enhanced_kwargs())\n\n# For overlapping circular structures \nconfig = create_overlapping_blobs_pipeline()\ncircular, _, separated_blobs = cb.enhanced_blob_detection(mrc_image, **config.to_enhanced_kwargs())\n\n# For comprehensive analysis (all methods)\nconfig = create_comprehensive_pipeline()\nall_results = cb.enhanced_blob_detection(mrc_image, **config.to_enhanced_kwargs())\n```\n\n## Detection Methods\n\n| Blob Type | Method | Best For | Key Function |\n|-----------|--------|----------|--------------|\n| Circular | LoG | Standard round particles | `blob_list_log()` |\n| Elongated | Ridge Detection | Pill-shaped, rod-like objects | `ridge_detection()` |\n| Overlapping | Watershed | Touching circular structures | `watershed_segmentation()` |\n| Mixed/Complex | Enhanced Detection | Multiple morphologies | `enhanced_blob_detection()` |\n\n## Package Structure\n\nThe cryoblob package is organized into the following modules:\n\n* **adapt**: Adaptive image processing with gradient descent optimization\n* **blobs**: Core blob detection algorithms and preprocessing \n* **files**: File I/O operations and batch processing\n* **image**: Basic image processing functions (filtering, resizing, etc.)\n* **multi**: Multi-method detection for elongated objects and overlapping blobs\n* **plots**: Visualization functions for MRC images and results\n* **types**: Type definitions and PyTree structures\n* **valid**: Parameter validation using Pydantic models\n\n## Use Cases\n\n**Standard Cryo-EM Particles**\n```python\n# Traditional circular blob detection\nblobs = cb.blob_list_log(mrc_image, min_blob_size=5, max_blob_size=20)\n```\n\n**Elongated Biological Structures**\n```python\n# Detect pill-shaped, rod-like, or filamentous objects\n_, elongated, _ = cb.enhanced_blob_detection(\n mrc_image, use_ridge_detection=True, use_watershed=False\n)\n```\n\n**Overlapping or Touching Particles**\n```python\n# Separate overlapping circular structures\n_, _, separated = cb.enhanced_blob_detection(\n mrc_image, use_ridge_detection=False, use_watershed=True\n)\n```\n\n**Complex Heterogeneous Samples**\n```python\n# Comprehensive analysis for mixed morphologies\ncircular, elongated, overlapping = cb.enhanced_blob_detection(\n mrc_image, use_ridge_detection=True, use_watershed=True\n)\n```\n\n## Performance\n\n* **Memory Efficient**: Automatic batch size optimization and memory management\n* **Scalable**: Multi-device and multi-host processing support\n* **Fast**: JIT compilation and GPU acceleration where available\n* **Flexible**: Selective method usage to optimize speed vs. comprehensiveness\n\n## Package Organization\n* The **codes** are located in `/src/cryoblob/`\n* The **notebooks** are located in `/tutorials/`\n\n## Documentation\n\nFor detailed API documentation and tutorials, visit: [https://cryoblob.readthedocs.io](https://cryoblob.readthedocs.io)\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Authors\n\n- Debangshu Mukherjee (mukherjeed@ornl.gov)\n- Alexis N. Williams (williamsan@ornl.gov)",
"bugtrack_url": null,
"license": null,
"summary": "Particle Picking of Cryo-EM Datasets",
"version": "2025.8.2",
"project_urls": {
"Documentation": "https://cryoblob.readthedocs.io/",
"Homepage": "https://github.com/debangshu-mukherjee/cryoblob/",
"Issues": "https://github.com/debangshu-mukherjee/cryoblob/issues",
"Repository": "https://github.com/debangshu-mukherjee/cryoblob/"
},
"split_keywords": [
"electron microscopy",
" cryoem",
" image processing",
" jax",
" blob detection"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c567d8cc2d64f16ecef1fc545177a5572f2cfd4f1bb92bfc041d06e1fc7738be",
"md5": "0ac8fc6498975d601fd83788c063b079",
"sha256": "1329365e0e398a19938e311b637d110a3b21f88dc1aa95d97b0e52652e0f50e6"
},
"downloads": -1,
"filename": "cryoblob-2025.8.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0ac8fc6498975d601fd83788c063b079",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 48459,
"upload_time": "2025-08-18T22:36:34",
"upload_time_iso_8601": "2025-08-18T22:36:34.471696Z",
"url": "https://files.pythonhosted.org/packages/c5/67/d8cc2d64f16ecef1fc545177a5572f2cfd4f1bb92bfc041d06e1fc7738be/cryoblob-2025.8.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b4c0b7f0417be97231f8a4b151db699451be47585b88b70b9348c98dec598516",
"md5": "e5adfa4e565c856125d0d3b7d194ad41",
"sha256": "7815e7b1110c3626b4bc071038e0ea1f6588ac828ff5fa5e933f37f0b990fd49"
},
"downloads": -1,
"filename": "cryoblob-2025.8.2.tar.gz",
"has_sig": false,
"md5_digest": "e5adfa4e565c856125d0d3b7d194ad41",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 39314,
"upload_time": "2025-08-18T22:36:36",
"upload_time_iso_8601": "2025-08-18T22:36:36.382369Z",
"url": "https://files.pythonhosted.org/packages/b4/c0/b7f0417be97231f8a4b151db699451be47585b88b70b9348c98dec598516/cryoblob-2025.8.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 22:36:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "debangshu-mukherjee",
"github_project": "cryoblob",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cryoblob"
}
JSON
