lattice-sub 1.0.10__tar.gz → 1.1.1__tar.gz

{lattice_sub-1.0.10 → lattice_sub-1.1.1}/MANIFEST.in

@@ -10,10 +10,22 @@ recursive-include src *.py
 recursive-include examples *.yaml *.yml
 recursive-include docs *.md *.png
 
+# Exclude tests (dev only - available on GitHub)
+prune tests
+
 # Exclude internal/development files
 exclude NOTES_*.md
 exclude *.log
+exclude benchmark_*.py
+exclude analyze_thresholds.py
+exclude test_search_strategies.py
+prune benchmark_visualizations
+prune kornia_benchmark_visualizations
+prune dist
+prune tests/test_output
+prune tests/test_output_gpu
 global-exclude *.pyc
 global-exclude __pycache__
 global-exclude *.egg-info
 global-exclude .git*
+global-exclude .pytest_cache

{lattice_sub-1.0.10/src/lattice_sub.egg-info → lattice_sub-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lattice-sub
-Version: 1.0.10
+Version: 1.1.1
 Summary: Lattice subtraction for cryo-EM micrographs - removes periodic crystal signals to reveal non-periodic features
 Author-email: George Stephenson <george.stephenson@colorado.edu>, Vignesh Kasinath <vignesh.kasinath@colorado.edu>
 License: MIT
@@ -28,6 +28,7 @@ Requires-Dist: click>=8.1
 Requires-Dist: scikit-image>=0.21
 Requires-Dist: torch>=2.0
 Requires-Dist: matplotlib>=3.7
+Requires-Dist: kornia>=0.7
 Provides-Extra: dev
 Requires-Dist: pytest>=7.4; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -55,7 +56,7 @@ Dynamic: license-file
 
 **Remove periodic lattice patterns from cryo-EM micrographs to reveal non-periodic features.**
 
-![Example Result](docs/images/example_comparison.png)
+![Example Result](https://raw.githubusercontent.com/gsstephenson/cryoem-lattice-subtraction/main/docs/images/example_comparison.png)
 
 ---
 
@@ -67,6 +68,8 @@ pip install lattice-sub
 
 That's it! GPU acceleration works automatically if you have an NVIDIA GPU.
 
+> **Note:** Requires Python 3.11+ and an NVIDIA GPU (RTX 20/30/40 series, A100, etc.) for best performance. CPU fallback is available but slower.
+
 ---
 
 ## Quick Start
@@ -77,6 +80,8 @@ That's it! GPU acceleration works automatically if you have an NVIDIA GPU.
 lattice-sub process your_image.mrc -o output.mrc --pixel-size 0.56
 ```
 
+> **Pixel size:** Use your detector's actual pixel size (e.g., K3=0.56Å, Falcon=1.14Å, K2=1.32Å)
+
 ### Process a Folder of Images
 
 ```bash
@@ -99,7 +104,7 @@ This creates side-by-side PNG images showing before/after/difference for each mi
 |--------|-------------|
 | `-p, --pixel-size` | **Required.** Pixel size in Ångstroms |
 | `-o, --output` | Output file path (default: `sub_<input>`) |
-| `-t, --threshold` | Peak detection sensitivity (default: 1.42) |
+| `-t, --threshold` | Peak detection sensitivity (default: **auto** - optimized per image) |
 | `--cpu` | Force CPU processing (GPU is used by default) |
 | `-q, --quiet` | Hide the banner and progress messages |
 | `-v, --verbose` | Show detailed processing information |
@@ -107,7 +112,10 @@ This creates side-by-side PNG images showing before/after/difference for each mi
 ### Example with Options
 
 ```bash
-# Process with custom threshold, verbose output
+# Process with auto-optimized threshold (default - recommended)
+lattice-sub process image.mrc -o cleaned.mrc -p 0.56 -v
+
+# Override with a specific threshold if needed
 lattice-sub process image.mrc -o cleaned.mrc -p 0.56 -t 1.5 -v
 
 # Batch process, force CPU with 8 parallel workers
@@ -116,16 +124,22 @@ lattice-sub batch raw/ processed/ -p 0.56 --cpu -j 8
 
 ---
 
-## Using a Config File
+## Using a Config File (Optional)
+
+For most users, the defaults work great — just use `-p` for pixel size:
+
+```bash
+lattice-sub batch input/ output/ -p 0.56
+```
 
-For reproducible processing, save your parameters in a YAML file:
+Config files are useful for **reproducibility** or **non-standard samples**:
 
 ```yaml
-# params.yaml
+# params.yaml - only include what you want to override
 pixel_ang: 0.56
-threshold: 1.42
-inside_radius_ang: 90
-unit_cell_ang: 116
+unit_cell_ang: 120      # Default: 116 (nucleosome). Change for other crystals.
+inside_radius_ang: 80   # Default: 90. Protect different resolution range.
+# threshold: 1.45       # Uncomment to override auto-optimization
 ```
 
 Then use it:
@@ -244,6 +258,60 @@ MIT License - see [LICENSE](LICENSE) for details.
 <details>
 <summary><strong>📚 Advanced Topics</strong> (click to expand)</summary>
 
+### v1.1.0 Optimizations
+
+Version 1.1.0 introduces two major optimizations that make the tool both **faster** and **smarter**:
+
+#### 1. Adaptive Per-Image Threshold Optimization
+
+**Problem (v1.0.x):** A fixed threshold (1.42) was used for all images, but optimal thresholds vary by image quality, ice thickness, and lattice order.
+
+**Solution (v1.1.0):** Automatic per-image optimization using grid search:
+- Tests 21 threshold values in range [1.40, 1.60] with 0.01 step
+- Scores each using a quality function that balances:
+  - **Peak count** (target: ~600 peaks for good lattice coverage)
+  - **Peak SNR** (signal-to-noise of detected peaks)
+  - **Peak distribution** (uniform hexagonal spacing preferred)
+  - **Coverage** (adequate sampling across frequency space)
+- Returns the threshold with highest quality score
+
+**Result:** Each image gets its optimal threshold automatically.
+
+![Threshold Distribution Analysis](https://raw.githubusercontent.com/gsstephenson/cryoem-lattice-subtraction/main/docs/images/threshold_analysis.png)
+
+#### 2. GPU-Accelerated Background Subtraction (Kornia)
+
+**Problem (v1.0.x):** Profiling revealed background subtraction (scipy median filter) consumed **94% of processing time** — not FFT as expected.
+
+**Solution (v1.1.0):** Replaced scipy's CPU median filter with Kornia's GPU implementation:
+```python
+# Before (v1.0.x) - CPU, ~2.5s per image
+from scipy.ndimage import median_filter
+background = median_filter(log_power, size=51)
+
+# After (v1.1.0) - GPU, ~0.05s per image  
+from kornia.filters import median_blur
+background = median_blur(log_power_tensor, (51, 51))
+```
+
+**Result:** 48x speedup on background subtraction alone.
+
+#### Performance Comparison
+
+| Version | Threshold | Background Sub | Time/Image | Quality |
+|---------|-----------|----------------|------------|---------|
+| v1.0.10 | Fixed (1.42) | scipy CPU | ~12s | Good |
+| v1.1.0 | Fixed | Kornia GPU | ~1.0s | Good |
+| v1.1.0 | **Auto** | **Kornia GPU** | **~2.6s** | **Optimal** |
+
+**Net result:** 5x faster with better results per image.
+
+#### Correlation Validation
+
+Kornia GPU vs scipy CPU background subtraction correlation: **0.9976** (nearly identical output).
+
+---
+
 ### Algorithm Details
 
 ```
@@ -264,12 +332,13 @@ The algorithm:
 | Parameter | Default | Description |
 |-----------|---------|-------------|
 | `pixel_ang` | *required* | Pixel size in Ångstroms |
-| `threshold` | 1.42 | Peak detection threshold on log-amplitude |
+| `threshold` | **auto** | Peak detection threshold - auto-optimized per image (range 1.40-1.60) |
 | `inside_radius_ang` | 90 | Inner resolution limit (Å) - protects structural info |
 | `outside_radius_ang` | auto | Outer resolution limit (Å) - protects near Nyquist |
 | `expand_pixel` | 10 | Morphological expansion of peak mask (pixels) |
 | `unit_cell_ang` | 116 | Crystal unit cell for inpaint shift calculation (Å) |
 | `backend` | auto | `"auto"`, `"numpy"` (CPU), or `"pytorch"` (GPU) |
+| `use_kornia` | **true** | Use Kornia for GPU-accelerated background subtraction (48x faster) |
 
 ### Supported Hardware
 
@@ -294,16 +363,17 @@ pytest tests/ -v  # Run tests
 
 ```
 src/lattice_subtraction/
-├── __init__.py        # Package exports
-├── cli.py             # Command-line interface
-├── core.py            # LatticeSubtractor main class
-├── batch.py           # Parallel batch processing
-├── config.py          # Configuration dataclass
-├── io.py              # MRC file I/O
-├── masks.py           # FFT mask generation
-├── processing.py      # FFT helpers
-├── ui.py              # Terminal UI
-└── visualization.py   # Comparison figures
+├── __init__.py           # Package exports
+├── cli.py                # Command-line interface
+├── core.py               # LatticeSubtractor main class
+├── batch.py              # Parallel batch processing
+├── config.py             # Configuration dataclass
+├── io.py                 # MRC file I/O
+├── masks.py              # FFT mask generation
+├── processing.py         # FFT helpers + GPU background subtraction
+├── threshold_optimizer.py # Auto-threshold optimization (NEW in v1.1)
+├── ui.py                 # Terminal UI
+└── visualization.py      # Comparison figures
 ```
 
 ### Migration from MATLAB

{lattice_sub-1.0.10 → lattice_sub-1.1.1}/README.md

@@ -15,7 +15,7 @@
 
 **Remove periodic lattice patterns from cryo-EM micrographs to reveal non-periodic features.**
 
-![Example Result](docs/images/example_comparison.png)
+![Example Result](https://raw.githubusercontent.com/gsstephenson/cryoem-lattice-subtraction/main/docs/images/example_comparison.png)
 
 ---
 
@@ -27,6 +27,8 @@ pip install lattice-sub
 
 That's it! GPU acceleration works automatically if you have an NVIDIA GPU.
 
+> **Note:** Requires Python 3.11+ and an NVIDIA GPU (RTX 20/30/40 series, A100, etc.) for best performance. CPU fallback is available but slower.
+
 ---
 
 ## Quick Start
@@ -37,6 +39,8 @@ That's it! GPU acceleration works automatically if you have an NVIDIA GPU.
 lattice-sub process your_image.mrc -o output.mrc --pixel-size 0.56
 ```
 
+> **Pixel size:** Use your detector's actual pixel size (e.g., K3=0.56Å, Falcon=1.14Å, K2=1.32Å)
+
 ### Process a Folder of Images
 
 ```bash
@@ -59,7 +63,7 @@ This creates side-by-side PNG images showing before/after/difference for each mi
 |--------|-------------|
 | `-p, --pixel-size` | **Required.** Pixel size in Ångstroms |
 | `-o, --output` | Output file path (default: `sub_<input>`) |
-| `-t, --threshold` | Peak detection sensitivity (default: 1.42) |
+| `-t, --threshold` | Peak detection sensitivity (default: **auto** - optimized per image) |
 | `--cpu` | Force CPU processing (GPU is used by default) |
 | `-q, --quiet` | Hide the banner and progress messages |
 | `-v, --verbose` | Show detailed processing information |
@@ -67,7 +71,10 @@ This creates side-by-side PNG images showing before/after/difference for each mi
 ### Example with Options
 
 ```bash
-# Process with custom threshold, verbose output
+# Process with auto-optimized threshold (default - recommended)
+lattice-sub process image.mrc -o cleaned.mrc -p 0.56 -v
+
+# Override with a specific threshold if needed
 lattice-sub process image.mrc -o cleaned.mrc -p 0.56 -t 1.5 -v
 
 # Batch process, force CPU with 8 parallel workers
@@ -76,16 +83,22 @@ lattice-sub batch raw/ processed/ -p 0.56 --cpu -j 8
 
 ---
 
-## Using a Config File
+## Using a Config File (Optional)
+
+For most users, the defaults work great — just use `-p` for pixel size:
+
+```bash
+lattice-sub batch input/ output/ -p 0.56
+```
 
-For reproducible processing, save your parameters in a YAML file:
+Config files are useful for **reproducibility** or **non-standard samples**:
 
 ```yaml
-# params.yaml
+# params.yaml - only include what you want to override
 pixel_ang: 0.56
-threshold: 1.42
-inside_radius_ang: 90
-unit_cell_ang: 116
+unit_cell_ang: 120      # Default: 116 (nucleosome). Change for other crystals.
+inside_radius_ang: 80   # Default: 90. Protect different resolution range.
+# threshold: 1.45       # Uncomment to override auto-optimization
 ```
 
 Then use it:
@@ -204,6 +217,60 @@ MIT License - see [LICENSE](LICENSE) for details.
 <details>
 <summary><strong>📚 Advanced Topics</strong> (click to expand)</summary>
 
+### v1.1.0 Optimizations
+
+Version 1.1.0 introduces two major optimizations that make the tool both **faster** and **smarter**:
+
+#### 1. Adaptive Per-Image Threshold Optimization
+
+**Problem (v1.0.x):** A fixed threshold (1.42) was used for all images, but optimal thresholds vary by image quality, ice thickness, and lattice order.
+
+**Solution (v1.1.0):** Automatic per-image optimization using grid search:
+- Tests 21 threshold values in range [1.40, 1.60] with 0.01 step
+- Scores each using a quality function that balances:
+  - **Peak count** (target: ~600 peaks for good lattice coverage)
+  - **Peak SNR** (signal-to-noise of detected peaks)
+  - **Peak distribution** (uniform hexagonal spacing preferred)
+  - **Coverage** (adequate sampling across frequency space)
+- Returns the threshold with highest quality score
+
+**Result:** Each image gets its optimal threshold automatically.
+
+![Threshold Distribution Analysis](https://raw.githubusercontent.com/gsstephenson/cryoem-lattice-subtraction/main/docs/images/threshold_analysis.png)
+
+#### 2. GPU-Accelerated Background Subtraction (Kornia)
+
+**Problem (v1.0.x):** Profiling revealed background subtraction (scipy median filter) consumed **94% of processing time** — not FFT as expected.
+
+**Solution (v1.1.0):** Replaced scipy's CPU median filter with Kornia's GPU implementation:
+```python
+# Before (v1.0.x) - CPU, ~2.5s per image
+from scipy.ndimage import median_filter
+background = median_filter(log_power, size=51)
+
+# After (v1.1.0) - GPU, ~0.05s per image  
+from kornia.filters import median_blur
+background = median_blur(log_power_tensor, (51, 51))
+```
+
+**Result:** 48x speedup on background subtraction alone.
+
+#### Performance Comparison
+
+| Version | Threshold | Background Sub | Time/Image | Quality |
+|---------|-----------|----------------|------------|---------|
+| v1.0.10 | Fixed (1.42) | scipy CPU | ~12s | Good |
+| v1.1.0 | Fixed | Kornia GPU | ~1.0s | Good |
+| v1.1.0 | **Auto** | **Kornia GPU** | **~2.6s** | **Optimal** |
+
+**Net result:** 5x faster with better results per image.
+
+#### Correlation Validation
+
+Kornia GPU vs scipy CPU background subtraction correlation: **0.9976** (nearly identical output).
+
+---
+
 ### Algorithm Details
 
 ```
@@ -224,12 +291,13 @@ The algorithm:
 | Parameter | Default | Description |
 |-----------|---------|-------------|
 | `pixel_ang` | *required* | Pixel size in Ångstroms |
-| `threshold` | 1.42 | Peak detection threshold on log-amplitude |
+| `threshold` | **auto** | Peak detection threshold - auto-optimized per image (range 1.40-1.60) |
 | `inside_radius_ang` | 90 | Inner resolution limit (Å) - protects structural info |
 | `outside_radius_ang` | auto | Outer resolution limit (Å) - protects near Nyquist |
 | `expand_pixel` | 10 | Morphological expansion of peak mask (pixels) |
 | `unit_cell_ang` | 116 | Crystal unit cell for inpaint shift calculation (Å) |
 | `backend` | auto | `"auto"`, `"numpy"` (CPU), or `"pytorch"` (GPU) |
+| `use_kornia` | **true** | Use Kornia for GPU-accelerated background subtraction (48x faster) |
 
 ### Supported Hardware
 
@@ -254,16 +322,17 @@ pytest tests/ -v  # Run tests
 
 ```
 src/lattice_subtraction/
-├── __init__.py        # Package exports
-├── cli.py             # Command-line interface
-├── core.py            # LatticeSubtractor main class
-├── batch.py           # Parallel batch processing
-├── config.py          # Configuration dataclass
-├── io.py              # MRC file I/O
-├── masks.py           # FFT mask generation
-├── processing.py      # FFT helpers
-├── ui.py              # Terminal UI
-└── visualization.py   # Comparison figures
+├── __init__.py           # Package exports
+├── cli.py                # Command-line interface
+├── core.py               # LatticeSubtractor main class
+├── batch.py              # Parallel batch processing
+├── config.py             # Configuration dataclass
+├── io.py                 # MRC file I/O
+├── masks.py              # FFT mask generation
+├── processing.py         # FFT helpers + GPU background subtraction
+├── threshold_optimizer.py # Auto-threshold optimization (NEW in v1.1)
+├── ui.py                 # Terminal UI
+└── visualization.py      # Comparison figures
 ```
 
 ### Migration from MATLAB

{lattice_sub-1.0.10 → lattice_sub-1.1.1}/examples/config.yaml

@@ -1,7 +1,10 @@
-# Lattice Subtraction - Example Configuration
+# Lattice Subtraction - Example Configuration (v1.1.0)
 # 
 # This file contains all available configuration options.
 # Copy and modify for your specific dataset.
+#
+# NEW in v1.1.0: Auto-threshold and Kornia GPU acceleration are now defaults!
+# Just run `lattice-sub process image.mrc -p 0.56` for optimal results.
 
 # ============================================
 # REQUIRED: Detector/Pixel Size
@@ -16,9 +19,11 @@ pixel_ang: 0.56
 # ============================================
 
 # Threshold for peak detection on log-amplitude FFT
+# Options:
+#   - "auto" (default): Optimizes threshold per image in range [1.40, 1.60]
+#   - A fixed value (e.g., 1.42): Uses same threshold for all images
 # Higher values = more conservative (fewer peaks detected)
-# Typical range: 1.2 - 1.8
-threshold: 1.42
+threshold: auto
 
 # ============================================
 # Resolution Limits (in Angstroms)
@@ -69,3 +74,12 @@ pad_output: false
 # Backend for FFT computation
 # Options: "auto" (default, GPU if available), "numpy" (CPU), or "pytorch" (GPU)
 backend: auto
+
+# ============================================
+# GPU Acceleration (NEW in v1.1.0)
+# ============================================
+
+# Use Kornia for GPU-accelerated background subtraction
+# This provides ~48x speedup over scipy's CPU median filter
+# Set to false to use CPU scipy (for debugging or CPU-only systems)
+use_kornia: true

{lattice_sub-1.0.10 → lattice_sub-1.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lattice-sub"
-version = "1.0.10"
+version = "1.1.1"
 description = "Lattice subtraction for cryo-EM micrographs - removes periodic crystal signals to reveal non-periodic features"
 readme = "README.md"
 license = {text = "MIT"}
@@ -34,6 +34,7 @@ dependencies = [
     "scikit-image>=0.21",
     "torch>=2.0",
     "matplotlib>=3.7",
+    "kornia>=0.7",
 ]
 
 [project.optional-dependencies]

{lattice_sub-1.0.10 → lattice_sub-1.1.1/src/lattice_sub.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lattice-sub
-Version: 1.0.10
+Version: 1.1.1
 Summary: Lattice subtraction for cryo-EM micrographs - removes periodic crystal signals to reveal non-periodic features
 Author-email: George Stephenson <george.stephenson@colorado.edu>, Vignesh Kasinath <vignesh.kasinath@colorado.edu>
 License: MIT
@@ -28,6 +28,7 @@ Requires-Dist: click>=8.1
 Requires-Dist: scikit-image>=0.21
 Requires-Dist: torch>=2.0
 Requires-Dist: matplotlib>=3.7
+Requires-Dist: kornia>=0.7
 Provides-Extra: dev
 Requires-Dist: pytest>=7.4; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -55,7 +56,7 @@ Dynamic: license-file
 
 **Remove periodic lattice patterns from cryo-EM micrographs to reveal non-periodic features.**
 
-![Example Result](docs/images/example_comparison.png)
+![Example Result](https://raw.githubusercontent.com/gsstephenson/cryoem-lattice-subtraction/main/docs/images/example_comparison.png)
 
 ---
 
@@ -67,6 +68,8 @@ pip install lattice-sub
 
 That's it! GPU acceleration works automatically if you have an NVIDIA GPU.
 
+> **Note:** Requires Python 3.11+ and an NVIDIA GPU (RTX 20/30/40 series, A100, etc.) for best performance. CPU fallback is available but slower.
+
 ---
 
 ## Quick Start
@@ -77,6 +80,8 @@ That's it! GPU acceleration works automatically if you have an NVIDIA GPU.
 lattice-sub process your_image.mrc -o output.mrc --pixel-size 0.56
 ```
 
+> **Pixel size:** Use your detector's actual pixel size (e.g., K3=0.56Å, Falcon=1.14Å, K2=1.32Å)
+
 ### Process a Folder of Images
 
 ```bash
@@ -99,7 +104,7 @@ This creates side-by-side PNG images showing before/after/difference for each mi
 |--------|-------------|
 | `-p, --pixel-size` | **Required.** Pixel size in Ångstroms |
 | `-o, --output` | Output file path (default: `sub_<input>`) |
-| `-t, --threshold` | Peak detection sensitivity (default: 1.42) |
+| `-t, --threshold` | Peak detection sensitivity (default: **auto** - optimized per image) |
 | `--cpu` | Force CPU processing (GPU is used by default) |
 | `-q, --quiet` | Hide the banner and progress messages |
 | `-v, --verbose` | Show detailed processing information |
@@ -107,7 +112,10 @@ This creates side-by-side PNG images showing before/after/difference for each mi
 ### Example with Options
 
 ```bash
-# Process with custom threshold, verbose output
+# Process with auto-optimized threshold (default - recommended)
+lattice-sub process image.mrc -o cleaned.mrc -p 0.56 -v
+
+# Override with a specific threshold if needed
 lattice-sub process image.mrc -o cleaned.mrc -p 0.56 -t 1.5 -v
 
 # Batch process, force CPU with 8 parallel workers
@@ -116,16 +124,22 @@ lattice-sub batch raw/ processed/ -p 0.56 --cpu -j 8
 
 ---
 
-## Using a Config File
+## Using a Config File (Optional)
+
+For most users, the defaults work great — just use `-p` for pixel size:
+
+```bash
+lattice-sub batch input/ output/ -p 0.56
+```
 
-For reproducible processing, save your parameters in a YAML file:
+Config files are useful for **reproducibility** or **non-standard samples**:
 
 ```yaml
-# params.yaml
+# params.yaml - only include what you want to override
 pixel_ang: 0.56
-threshold: 1.42
-inside_radius_ang: 90
-unit_cell_ang: 116
+unit_cell_ang: 120      # Default: 116 (nucleosome). Change for other crystals.
+inside_radius_ang: 80   # Default: 90. Protect different resolution range.
+# threshold: 1.45       # Uncomment to override auto-optimization
 ```
 
 Then use it:
@@ -244,6 +258,60 @@ MIT License - see [LICENSE](LICENSE) for details.
 <details>
 <summary><strong>📚 Advanced Topics</strong> (click to expand)</summary>
 
+### v1.1.0 Optimizations
+
+Version 1.1.0 introduces two major optimizations that make the tool both **faster** and **smarter**:
+
+#### 1. Adaptive Per-Image Threshold Optimization
+
+**Problem (v1.0.x):** A fixed threshold (1.42) was used for all images, but optimal thresholds vary by image quality, ice thickness, and lattice order.
+
+**Solution (v1.1.0):** Automatic per-image optimization using grid search:
+- Tests 21 threshold values in range [1.40, 1.60] with 0.01 step
+- Scores each using a quality function that balances:
+  - **Peak count** (target: ~600 peaks for good lattice coverage)
+  - **Peak SNR** (signal-to-noise of detected peaks)
+  - **Peak distribution** (uniform hexagonal spacing preferred)
+  - **Coverage** (adequate sampling across frequency space)
+- Returns the threshold with highest quality score
+
+**Result:** Each image gets its optimal threshold automatically.
+
+![Threshold Distribution Analysis](https://raw.githubusercontent.com/gsstephenson/cryoem-lattice-subtraction/main/docs/images/threshold_analysis.png)
+
+#### 2. GPU-Accelerated Background Subtraction (Kornia)
+
+**Problem (v1.0.x):** Profiling revealed background subtraction (scipy median filter) consumed **94% of processing time** — not FFT as expected.
+
+**Solution (v1.1.0):** Replaced scipy's CPU median filter with Kornia's GPU implementation:
+```python
+# Before (v1.0.x) - CPU, ~2.5s per image
+from scipy.ndimage import median_filter
+background = median_filter(log_power, size=51)
+
+# After (v1.1.0) - GPU, ~0.05s per image  
+from kornia.filters import median_blur
+background = median_blur(log_power_tensor, (51, 51))
+```
+
+**Result:** 48x speedup on background subtraction alone.
+
+#### Performance Comparison
+
+| Version | Threshold | Background Sub | Time/Image | Quality |
+|---------|-----------|----------------|------------|---------|
+| v1.0.10 | Fixed (1.42) | scipy CPU | ~12s | Good |
+| v1.1.0 | Fixed | Kornia GPU | ~1.0s | Good |
+| v1.1.0 | **Auto** | **Kornia GPU** | **~2.6s** | **Optimal** |
+
+**Net result:** 5x faster with better results per image.
+
+#### Correlation Validation
+
+Kornia GPU vs scipy CPU background subtraction correlation: **0.9976** (nearly identical output).
+
+---
+
 ### Algorithm Details
 
 ```
@@ -264,12 +332,13 @@ The algorithm:
 | Parameter | Default | Description |
 |-----------|---------|-------------|
 | `pixel_ang` | *required* | Pixel size in Ångstroms |
-| `threshold` | 1.42 | Peak detection threshold on log-amplitude |
+| `threshold` | **auto** | Peak detection threshold - auto-optimized per image (range 1.40-1.60) |
 | `inside_radius_ang` | 90 | Inner resolution limit (Å) - protects structural info |
 | `outside_radius_ang` | auto | Outer resolution limit (Å) - protects near Nyquist |
 | `expand_pixel` | 10 | Morphological expansion of peak mask (pixels) |
 | `unit_cell_ang` | 116 | Crystal unit cell for inpaint shift calculation (Å) |
 | `backend` | auto | `"auto"`, `"numpy"` (CPU), or `"pytorch"` (GPU) |
+| `use_kornia` | **true** | Use Kornia for GPU-accelerated background subtraction (48x faster) |
 
 ### Supported Hardware
 
@@ -294,16 +363,17 @@ pytest tests/ -v  # Run tests
 
 ```
 src/lattice_subtraction/
-├── __init__.py        # Package exports
-├── cli.py             # Command-line interface
-├── core.py            # LatticeSubtractor main class
-├── batch.py           # Parallel batch processing
-├── config.py          # Configuration dataclass
-├── io.py              # MRC file I/O
-├── masks.py           # FFT mask generation
-├── processing.py      # FFT helpers
-├── ui.py              # Terminal UI
-└── visualization.py   # Comparison figures
+├── __init__.py           # Package exports
+├── cli.py                # Command-line interface
+├── core.py               # LatticeSubtractor main class
+├── batch.py              # Parallel batch processing
+├── config.py             # Configuration dataclass
+├── io.py                 # MRC file I/O
+├── masks.py              # FFT mask generation
+├── processing.py         # FFT helpers + GPU background subtraction
+├── threshold_optimizer.py # Auto-threshold optimization (NEW in v1.1)
+├── ui.py                 # Terminal UI
+└── visualization.py      # Comparison figures
 ```
 
 ### Migration from MATLAB

{lattice_sub-1.0.10 → lattice_sub-1.1.1}/src/lattice_sub.egg-info/SOURCES.txt

@@ -2,8 +2,8 @@ LICENSE
 MANIFEST.in
 README.md
 pyproject.toml
-docs/architecture.md
 docs/images/example_comparison.png
+docs/images/threshold_analysis.png
 examples/config.yaml
 examples/converted_params.yaml
 src/lattice_sub.egg-info/PKG-INFO
@@ -20,6 +20,6 @@ src/lattice_subtraction/core.py
 src/lattice_subtraction/io.py
 src/lattice_subtraction/masks.py
 src/lattice_subtraction/processing.py
+src/lattice_subtraction/threshold_optimizer.py
 src/lattice_subtraction/ui.py
-src/lattice_subtraction/visualization.py
-tests/test_lattice_subtraction.py
+src/lattice_subtraction/visualization.py

{lattice_sub-1.0.10 → lattice_sub-1.1.1}/src/lattice_sub.egg-info/requires.txt

@@ -7,6 +7,7 @@ click>=8.1
 scikit-image>=0.21
 torch>=2.0
 matplotlib>=3.7
+kornia>=0.7
 
 [dev]
 pytest>=7.4