maicroscopy-sandbox 0.3.0__tar.gz

maicroscopy_sandbox-0.3.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2024] [Ricardo Henriques <ricardo@henriqueslab.org>]
+
+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.

maicroscopy_sandbox-0.3.0/PKG-INFO

@@ -0,0 +1,519 @@
+Metadata-Version: 2.4
+Name: maicroscopy_sandbox
+Version: 0.3.0
+Summary: Fluorescence microscopy simulation toolkit for synthetic microscopy experiments.
+Author-email: Bruno Saraiva <bruno.msaraiva2@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/HenriquesLab/mAIcroscopysandbox
+Project-URL: Repository, https://github.com/HenriquesLab/mAIcroscopysandbox
+Project-URL: Issues, https://github.com/HenriquesLab/mAIcroscopysandbox/issues
+Keywords: microscopy,simulation,fluorescence,bioimaging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: matplotlib>=3.10.9
+Requires-Dist: numba
+Requires-Dist: numpy<2
+Requires-Dist: scikit-image
+Requires-Dist: scipy
+Requires-Dist: stackview>=0.19.1
+Requires-Dist: tifffile
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: ipykernel>=6.29.4; extra == "dev"
+Requires-Dist: pdoc>=12.3.1; extra == "dev"
+Requires-Dist: pre-commit>=3.7.0; extra == "dev"
+Requires-Dist: ruff>=0.4.3; extra == "dev"
+Requires-Dist: twine>=5.1.1; extra == "dev"
+Provides-Extra: test
+Requires-Dist: coverage[toml]>=7.6.1; extra == "test"
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov>=5.0.0; extra == "test"
+Requires-Dist: pytest-xdist>=3.6.1; extra == "test"
+Dynamic: license-file
+
+# mAIcroscopy Sandbox
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+A Python package for simulating realistic fluorescence microscopy experiments with biological samples. Perfect for testing super-resolution algorithms, training AI models, and teaching microscopy concepts.
+
+For installation, usage, and contribution instructions, see:
+
+- [INSTALL.md](INSTALL.md)
+- [USAGE.md](USAGE.md)
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Features
+
+- 🔬 **Realistic Microscopy Simulation**: Accurate modeling of photon noise, bleaching, and detector characteristics
+- 🦠 **Bacterial Cell Dynamics**: Simulate *Staphylococcus*-like cells with growth, septum formation, and division
+- 📸 **Stage Control**: Move and scan across large samples with precise positioning
+- 🔆 **Laser Control**: Adjustable laser power with realistic photobleaching effects
+- 🧪 **Extensible**: Easy to create custom sample types and imaging modalities
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage Examples](#usage-examples)
+  - [Basic Microscopy Simulation](#basic-microscopy-simulation)
+  - [Bacterial Cell Simulation](#bacterial-cell-simulation)
+  - [Time-Lapse Imaging](#time-lapse-imaging)
+- [API Reference](#api-reference)
+- [Advanced Usage](#advanced-usage)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+### Requirements
+
+- Python 3.10 or higher
+- pip package manager
+
+### Install from source
+
+1. Clone the repository:
+```bash
+git clone https://github.com/HenriquesLab/mAIcroscopysandbox.git
+cd mAIcroscopysandbox
+```
+
+2. Install the package:
+```bash
+pip install -e .
+```
+
+3. For development (includes testing and linting tools):
+```bash
+pip install -e ".[dev,test]"
+```
+
+### Local CI
+
+Run the same lint, test, coverage, and build checks used by the automation:
+
+```bash
+./scripts/run_ci_locally.sh
+```
+
+### Dependencies
+
+The package automatically installs the following dependencies:
+- `numpy<2` - Numerical computing
+- `scikit-image` - Image processing
+- `numba` - JIT compilation for performance
+- `scipy` - Morphology and filtering utilities
+- `tifffile` - Binary sample loading and TIFF export
+
+## Quick Start
+
+Here's a minimal example to get you started:
+
+```python
+import numpy as np
+from matplotlib import pyplot as plt
+from maicroscopy_sandbox import mAIcroscopySandbox
+from maicroscopy_sandbox.samples.staph import StaphMembrane
+
+# Create a virtual microscope
+microscope = mAIcroscopySandbox(
+    fov_size=[500, 500],  # Field of view in pixels
+    laser_intensity=1000   # Photons per pixel
+)
+
+# Create a bacterial cell sample
+sample = StaphMembrane(
+    sample_size=microscope.stage_size,
+    n_objects=5,           # Number of cells
+    pixel_size=30          # nm per pixel
+)
+
+# Load sample and acquire image
+microscope.set_laser_power(100)
+frame = microscope.load_sample(sample, acquire=True)
+
+# Display the image
+plt.imshow(frame, cmap="gray")
+plt.title("Simulated Fluorescence Microscopy")
+plt.colorbar(label="Intensity (ADU)")
+plt.show()
+```
+
+## Usage Examples
+
+### Basic Microscopy Simulation
+
+Control the microscope stage and laser settings:
+
+```python
+from maicroscopy_sandbox import mAIcroscopySandbox
+from maicroscopy_sandbox.samples.ellipsoid import Ellipsoid
+
+# Initialize microscope
+microscope = mAIcroscopySandbox(
+    stage_size=[5000, 5000],
+    fov_size=[300, 300],
+    laser_intensity=100000
+)
+
+# Configure detector parameters
+microscope.set_readout_noise(50)      # Camera noise
+microscope.set_ADC_offset(100)        # Baseline offset
+microscope.set_gaussian_sigma(2.0)    # PSF blur
+
+# Create and load a simple ellipsoid sample
+sample = Ellipsoid(
+    sample_size=microscope.stage_size,
+    n_objects=10
+)
+
+# Acquire image
+microscope.set_laser_power(50)  # 50% laser power
+frame = microscope.load_sample(sample, acquire=True)
+
+# Move stage and acquire another image
+new_frame = microscope.move_stage([100, 50], acquire=True)
+```
+
+### Bacterial Cell Simulation
+
+Simulate realistic bacterial cell growth and division:
+
+```python
+from maicroscopy_sandbox import mAIcroscopySandbox
+from maicroscopy_sandbox.samples.staph import StaphMembrane
+import matplotlib.pyplot as plt
+
+# Create microscope
+microscope = mAIcroscopySandbox(fov_size=[500, 500], laser_intensity=1000)
+
+# Create bacterial sample with specific parameters
+sample = StaphMembrane(
+    sample_size=microscope.stage_size,
+    n_objects=3,              # Initial number of cells
+    pixel_size=30,            # 30 nm/pixel
+    bleaching_rate=0.05,      # 5% bleaching per frame
+    progression_rate=10,      # Cell cycle progression speed
+    p1_rate=42,              # Growth phase percentage
+    p2_rate=29               # Septum formation percentage
+)
+
+# Load sample
+microscope.set_laser_power(100)
+frame = microscope.load_sample(sample, acquire=True)
+
+# Visualize
+fig, ax = plt.subplots(1, 1, figsize=(8, 8))
+ax.imshow(frame, cmap="gray")
+ax.set_title("Bacterial Membrane Simulation")
+ax.axis('off')
+plt.tight_layout()
+plt.show()
+
+# Access cell information
+print(f"Number of cells: {len(sample.cells)}")
+for cell_id, cell in sample.cells.items():
+    print(f"Cell {cell_id}: progression={cell.progression}%")
+```
+
+### Time-Lapse Imaging
+
+Capture a time series showing cell dynamics:
+
+```python
+from maicroscopy_sandbox import mAIcroscopySandbox
+from maicroscopy_sandbox.samples.staph import StaphMembrane
+import matplotlib.pyplot as plt
+
+# Setup
+microscope = mAIcroscopySandbox(fov_size=[500, 500], laser_intensity=1000)
+sample = StaphMembrane(
+    sample_size=microscope.stage_size,
+    n_objects=1,
+    pixel_size=30,
+    progression_rate=20  # Faster progression for demo
+)
+
+microscope.set_laser_power(100)
+microscope.load_sample(sample)
+
+# Acquire time series
+n_frames = 10
+frames = []
+
+for i in range(n_frames):
+    frame = microscope.acquire_image()
+    frames.append(frame)
+    print(f"Frame {i+1}/{n_frames}: {len(sample.cells)} cells")
+
+# Display montage
+fig, axes = plt.subplots(2, 5, figsize=(15, 6))
+for i, (ax, frame) in enumerate(zip(axes.flat, frames)):
+    ax.imshow(frame, cmap="gray")
+    ax.set_title(f"t={i}")
+    ax.axis('off')
+plt.tight_layout()
+plt.show()
+```
+
+## API Reference
+
+### mAIcroscopySandbox
+
+Main microscope simulation class.
+
+#### Constructor Parameters
+- `stage_size` (array): Stage size in pixels [height, width]. Default: [5000, 5000]
+- `fov_size` (array): Field of view in pixels [height, width]. Default: [300, 300]
+- `laser_intensity` (float): Maximum laser intensity in photons/pixel. Default: 100000
+- `pixel_size` (float): Physical pixel size in nanometers. Default: 100
+
+#### Key Methods
+- `load_sample(sample, acquire=False)`: Load a sample onto the stage
+- `acquire_image()`: Capture an image at the current position
+- `move_stage(movement, acquire=False)`: Move stage by offset [row, col]
+- `set_laser_power(power)`: Set laser power (0-100%)
+- `set_readout_noise(noise)`: Set camera readout noise
+- `set_gaussian_sigma(sigma)`: Set PSF blur amount
+
+### StaphMembrane
+
+Bacterial cell sample with growth and division.
+
+#### Constructor Parameters
+- `sample_size` (array): Sample area in pixels. Default: [1000, 1000]
+- `n_objects` (int): Initial number of cells. Default: 1
+- `pixel_size` (int): Pixel size in nanometers. Default: 100
+- `bleaching_rate` (float): Bleaching rate per frame. Default: 0.001
+- `progression_rate` (int): Cell cycle progression speed. Default: 2
+- `p1_rate` (int): Growth phase percentage. Default: 42
+- `p2_rate` (int): Septum formation percentage. Default: 29
+
+#### Cell Attributes
+Each cell in `sample.cells` has:
+- `center_row`, `center_col`: Position
+- `major_axis`, `minor_axis`: Size
+- `orientation`: Angle in radians
+- `progression`: Cell cycle progress (0-100%)
+- `p1`, `p2`, `p3`: Phase boundaries
+
+## Advanced Usage
+
+### Creating Custom Samples
+
+Extend the `Sample` base class to create custom samples:
+
+```python
+from maicroscopy_sandbox.samples.sample import Sample
+import numpy as np
+
+class CustomSample(Sample):
+    def __init__(self, sample_size=[1000, 1000], **kwargs):
+        super().__init__(sample_size=sample_size, **kwargs)
+        # Your initialization code
+        
+    def generate_mask(self):
+        # Return 2D array with fluorophore distribution
+        mask = np.zeros(self.sample_size, dtype=np.float32)
+        # ... your custom mask generation ...
+        return mask
+    
+    def calculate_dynamics(self):
+        # Update sample state between frames
+        pass
+```
+
+### Adjusting Optical Parameters
+
+Fine-tune the microscope optics:
+
+```python
+microscope.set_wavelenght(488)      # Excitation wavelength (nm)
+microscope.set_NA(1.4)              # Numerical aperture
+microscope.set_sigma(0.21)          # Fluorophore emission spread
+microscope.set_ADC_per_photon_conversion(1.5)  # Detector gain
+```
+
+### Photobleaching Control
+
+Monitor and control photobleaching:
+
+```python
+# Create sample with high bleaching
+sample = StaphMembrane(
+    sample_size=microscope.stage_size,
+    bleaching_rate=0.1  # 10% per frame
+)
+
+microscope.load_sample(sample)
+
+# Reduce laser power to minimize bleaching
+microscope.set_laser_power(30)  # 30% power
+
+# Acquire multiple frames
+for i in range(10):
+    frame = microscope.acquire_image()
+    # Bleaching is automatically applied
+```
+
+### Saving Time-Lapse Data
+
+Export image sequences:
+
+```python
+import tifffile
+import numpy as np
+
+frames = []
+for i in range(100):
+    frame = microscope.acquire_image()
+    frames.append(frame)
+
+# Save as multi-page TIFF
+stack = np.stack(frames, axis=0)
+tifffile.imwrite("timelapse.tif", stack)
+```
+
+## Project Structure
+
+```
+mAIcroscopysandbox/
+├── .github/
+│   └── workflows/
+│       ├── ci.yml
+│       └── publish.yml
+├── src/
+│   └── maicroscopy_sandbox/
+│       ├── __init__.py
+│       ├── maicroscopy_sandbox.py    # Main microscope class
+│       ├── fluorescence_sim.py       # Image generation
+│       └── samples/
+│           ├── __init__.py
+│           ├── sample.py            # Base sample class
+│           ├── staph.py             # Bacterial cells
+│           ├── ellipsoid.py         # Simple ellipsoids
+│           └── binary.py            # Binary structures
+├── scripts/
+│   ├── run_ci_locally.sh
+│   └── release_to_pypi.sh
+├── notebooks/
+│   ├── example_usage.ipynb          # Usage examples
+│   └── example_from_binary.ipynb    # Binary sample demo
+├── tests/
+│   └── test_maicroscopy_sandbox.py
+├── noxfile.py
+├── Makefile
+├── README.md
+├── pyproject.toml
+└── LICENSE.txt
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes:
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+### Development Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/HenriquesLab/mAIcroscopysandbox.git
+cd mAIcroscopysandbox
+
+# Install in development mode with all extras
+pip install -e ".[dev,test]"
+
+# Run tests
+pytest
+
+# Or run the full local CI flow
+./scripts/run_ci_locally.sh
+
+# Run linter
+ruff check src/
+
+# Format code
+ruff format src/
+```
+
+### Release Automation
+
+- GitHub Actions CI lives in `.github/workflows/ci.yml`
+- PyPI publishing lives in `.github/workflows/publish.yml`
+- Local release validation and optional upload lives in:
+
+```bash
+./scripts/release_to_pypi.sh
+```
+
+If `PYPI_TOKEN` is unset, the script stops after test, build, and distribution validation.
+
+## Citation
+
+If you use this software in your research, please cite:
+
+```bibtex
+@software{maicroscopy_sandbox,
+  author = {Saraiva, Bruno},
+  title = {mAIcroscopy Sandbox: Realistic Fluorescence Microscopy Simulation},
+  year = {2025},
+  publisher = {GitHub},
+  url = {https://github.com/HenriquesLab/mAIcroscopysandbox}
+}
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.
+
+## Acknowledgments
+
+- Developed at the Henriques Lab
+- Built on scikit-image, scipy, and numpy
+- Inspired by real microscopy workflows and challenges
+
+## Contact
+
+- **Author**: Bruno Saraiva
+- **Email**: bruno.msaraiva2@gmail.com
+- **Lab**: [Henriques Lab](https://henriqueslab.github.io/)
+
+## Troubleshooting
+
+### Common Issues
+
+**ImportError: No module named 'maicroscopy_sandbox'**
+- Make sure you installed the package: `pip install -e .`
+- Check you're in the correct virtual environment
+
+**Cells not appearing/disappearing**
+- Restart the Jupyter kernel after code changes
+- The module caches the old version until restart
+
+**Slow performance**
+- Reduce `fov_size` for faster rendering
+- Lower `n_objects` to simulate fewer cells
+- Disable plotting during time-lapse acquisition
+
+**Images too dark/bright**
+- Adjust `laser_intensity` and `laser_power`
+- Check `ADC_per_photon_conversion` and `ADC_offset`
+- Verify sample mask has appropriate fluorophore density
+
+For more help, please [open an issue](https://github.com/HenriquesLab/mAIcroscopysandbox/issues) on GitHub.