Merge pull request #29 from JuliaSMLM/scmos

Release v0.4.0: sCMOS camera support

Author: kalidke

.gitignore

@@ -7,4 +7,7 @@ Manifest.toml
 examples/Manifest.toml
 *.mp4
 *.png
-*.tif
+*.tif
+
+# Dev outputs folder for examples and demos
+dev/outputs/

Project.toml

@@ -1,7 +1,7 @@
 name = "SMLMSim"
 uuid = "5a0a87e4-02d4-41f5-bf26-b8c94c784a04"
+version = "0.4.0"
 authors = ["klidke@unm.edu"]
-version = "0.3.3"
 
 [deps]
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
@@ -14,7 +14,7 @@ Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 [compat]
 Distributions = "0.25"
 MicroscopePSFs = "0.5"
-SMLMData = "0.2, 0.3"
+SMLMData = "0.4, 0.5"
 julia = "1.6"
 
 [extras]

README.md

@@ -58,12 +58,14 @@ using SMLMSim
 
 # Set diffusion simulation parameters
 params = DiffusionSMLMParams(
-    density = 0.5,        # molecules per μm²
-    box_size = 10.0,      # μm
-    diff_monomer = 0.1,   # μm²/s
-    k_off = 0.2,          # s⁻¹ dimer dissociation rate
-    dt = 0.01,            # s simulation timestep
-    t_max = 10.0          # s total simulation time
+    density = 0.5,           # molecules per μm²
+    box_size = 10.0,         # μm
+    diff_monomer = 0.1,      # μm²/s
+    k_off = 0.2,             # s⁻¹ dimer dissociation rate
+    dt = 0.01,               # s simulation timestep
+    t_max = 10.0,            # s total simulation time
+    camera_framerate = 10.0, # 10 fps (100ms per frame)
+    camera_exposure = 0.1    # 100ms exposure integrates 10 timesteps per frame
 )
 
 # Run diffusion simulation
@@ -106,16 +108,53 @@ Create camera images from simulation results.
 using MicroscopePSFs # Needed for PSF types
 
 # Generate images from diffusion simulation output
+# Note: Frame timing is controlled by DiffusionSMLMParams (camera_framerate, camera_exposure)
+# Multiple simulation timesteps are automatically integrated during simulate()
 psf = GaussianPSF(0.15) # 150nm PSF width
-# Use smld_model to avoid double-counting localization errors
-images = gen_images(smld, psf; 
-    frame_integration=10, # 10 simulation time steps for each camera frame
-    support=1.0 # PSF support range
-    ) 
+images = gen_images(smld, psf;
+    support=1.0,        # PSF support radius in μm (faster than default Inf)
+    poisson_noise=true  # Add shot noise
+)
 
 println("Generated $(size(images,3)) camera images.")
 ```
 
+### sCMOS Camera with Realistic Noise
+
+SMLMSim supports realistic sCMOS camera noise modeling with per-pixel calibration.
+
+```julia
+using SMLMSim
+using MicroscopePSFs
+
+# Create an sCMOS camera (128×128 pixels, 100nm pixels, 1.6 e⁻ read noise)
+camera_scmos = SCMOSCamera(128, 128, 0.1, 1.6)
+
+# Run static simulation with sCMOS camera
+params = StaticSMLMParams(density=1.0, σ_psf=0.13)
+smld_true, smld_model, smld_noisy = simulate(
+    params,
+    pattern=Nmer2D(n=8, d=0.1),
+    camera=camera_scmos
+)
+
+# Generate images with full sCMOS noise model
+# (quantum efficiency, Poisson, read noise, gain, offset)
+psf = GaussianPSF(0.15)
+images_scmos = gen_images(smld_noisy, psf, bg=10.0, camera_noise=true)
+
+# For diffusion simulations
+diff_params = DiffusionSMLMParams(density=0.5, box_size=10.0)
+smld_diff = simulate(diff_params; camera=camera_scmos, override_count=10)
+```
+
+The sCMOS noise model applies:
+1. **Quantum efficiency**: Photon → photoelectron conversion
+2. **Poisson noise**: Shot noise on photoelectrons
+3. **Read noise**: Gaussian noise per pixel
+4. **Gain**: Electron → ADU conversion
+5. **Offset**: Dark level addition
+
 ## Example Workflow: Static Simulation & Visualization
 
 ```julia
@@ -150,10 +189,63 @@ display(fig)
 # save("smlm_hexamer.png", fig)
 ```
 
+## Example Workflow: Diffusion with Realistic sCMOS Noise
+
+This example demonstrates a complete workflow for single-particle tracking with realistic camera noise:
+
+```julia
+using SMLMSim
+using MicroscopePSFs
+using Statistics
+
+# Create sCMOS camera with realistic noise parameters
+camera_scmos = SCMOSCamera(64, 64, 0.1, 1.6)  # 64×64 pixels, 100nm/px, 1.6 e⁻ read noise
+
+# Run diffusion simulation
+params = DiffusionSMLMParams(
+    density = 1.0,           # 1 molecule/μm²
+    box_size = 6.4,          # 6.4×6.4 μm field
+    diff_monomer = 0.1,      # 0.1 μm²/s diffusion
+    t_max = 0.5,             # 0.5 second total
+    camera_framerate = 100.0 # 100 fps
+)
+smld = simulate(params; camera=camera_scmos, photons=200.0)
+
+# Generate images with full sCMOS noise model
+# (quantum efficiency, Poisson, read noise, gain, offset)
+psf = GaussianPSF(0.13)  # 130nm PSF
+images_scmos = gen_images(smld, psf, bg=10.0, camera_noise=true)
+
+# For comparison: same data with ideal camera (Poisson noise only)
+camera_ideal = IdealCamera(64, 64, 0.1)
+smld_ideal = BasicSMLD(smld.emitters, camera_ideal, smld.n_frames, smld.n_datasets)
+images_ideal = gen_images(smld_ideal, psf, bg=10.0, poisson_noise=true)
+
+# Compare statistics
+println("sCMOS: mean=$(round(mean(images_scmos), digits=1)) ADU, std=$(round(std(images_scmos), digits=1))")
+println("Ideal: mean=$(round(mean(images_ideal), digits=1)) photons, std=$(round(std(images_ideal), digits=1))")
+# sCMOS includes offset (~100 ADU) and spatially-varying gain/readnoise
+```
+
 ## Further Information
 
 For more detailed examples, API documentation, and explanations of the underlying models, please see the [Full Documentation](https://JuliaSMLM.github.io/SMLMSim.jl/dev).
 
+### Demo Scripts
+
+The `dev/` folder contains demonstration scripts showing sCMOS camera functionality:
+
+- **`dev/scmos_quick_demo.jl`** - Fast verification that sCMOS works (~5 seconds)
+- **`dev/scmos_video.jl`** - Generate MP4 showing sCMOS vs Ideal side-by-side
+- **`dev/scmos_demo.jl`** - Full diffusion simulation with extreme sCMOS artifacts
+
+Run from repository root:
+```bash
+julia --project dev/scmos_quick_demo.jl
+```
+
+Outputs are saved to `dev/outputs/` (gitignored).
+
 ## Contributors
 
 -   [JuliaSMLM Team](https://github.com/JuliaSMLM)

api_overview.md

@@ -189,13 +189,27 @@ fluor = GenericFluor(photons=1e5, k_off=50.0, k_on=1e-2)
 ### Creating a Camera
 
 ```julia
-# Create a camera with 100nm pixels (128x128 pixels)
+# IdealCamera: Poisson noise only
 camera = IdealCamera(128, 128, 0.1)  # 128×128 pixels, 100nm pixels
 
 # Specify field of view with an array of pixel edges
 pixel_edges_x = 0.0:0.1:12.8  # 0 to 12.8μm in 0.1μm steps
 pixel_edges_y = 0.0:0.1:12.8
 camera = IdealCamera(pixel_edges_x, pixel_edges_y)
+
+# SCMOSCamera: Realistic noise model with per-pixel calibration (SMLMData 0.4+)
+# Parameters: width, height, pixel_size, readnoise
+camera_scmos = SCMOSCamera(128, 128, 0.1, 1.6)  # 1.6 e⁻ RMS read noise
+
+# Advanced: Specify all calibration parameters
+# offset (ADU), gain (e⁻/ADU), readnoise (e⁻ RMS), quantum efficiency (0-1)
+camera_scmos = SCMOSCamera(
+    128, 128, 0.1;
+    offset=100.0,      # 100 ADU dark level
+    gain=0.5,          # 0.5 e⁻/ADU
+    readnoise=1.6,     # 1.6 e⁻ RMS
+    qe=0.95            # 95% quantum efficiency
+)
 ```
 
 ## Core Functions
@@ -287,8 +301,10 @@ images = gen_images(
     sampling=2,                    # Supersampling factor for PSF integration
     threaded=true,                 # Enable multithreading
     bg=0.0,                        # Background signal level (photons per pixel)
-    poisson_noise=false,           # Apply Poisson noise
-    camera_noise=false             # Apply camera read noise
+    poisson_noise=false,           # Apply Poisson noise only (simple shot noise)
+    camera_noise=false             # Apply full camera noise model (requires SCMOSCamera)
+                                   # - For SCMOSCamera: QE, Poisson, read noise, gain, offset
+                                   # - For IdealCamera: ignored (use poisson_noise instead)
 )
 
 # The support parameter controls PSF computation region:
@@ -301,6 +317,17 @@ support=1.0  # 1.0 µm radius around each emitter
 
 # 3. Tuple (xmin, xmax, ymin, ymax): Explicit region in microns
 support=(4.0, 6.0, 4.0, 6.0)  # Only compute PSF within this region
+
+# Example: sCMOS camera with realistic noise
+camera_scmos = SCMOSCamera(128, 128, 0.1, 1.6)
+smld = BasicSMLD(emitters, camera_scmos, n_frames, n_datasets)
+images_scmos = gen_images(smld, psf, bg=10.0, camera_noise=true)
+# Applies: QE → Poisson → read noise → gain → offset
+
+# Example: IdealCamera with Poisson noise only
+camera_ideal = IdealCamera(128, 128, 0.1)
+smld = BasicSMLD(emitters, camera_ideal, n_frames, n_datasets)
+images_poisson = gen_images(smld, psf, bg=10.0, poisson_noise=true)
 ```
 
 #### gen_image
@@ -471,12 +498,17 @@ smld = simulate(params)
 dimer_smld = get_dimers(smld)
 frames, fractions = analyze_dimer_fraction(smld)
 
-# 4. Generate microscope images with finite PSF support
+# 4. Generate microscope images with realistic sCMOS noise
+# Create sCMOS camera matching simulation box
+n_pixels = Int(ceil(params.box_size / 0.1))  # 0.1 μm pixels
+camera_scmos = SCMOSCamera(n_pixels, n_pixels, 0.1, 1.6)
+smld_cam = BasicSMLD(smld.emitters, camera_scmos, smld.n_frames, 1)
+
 psf = GaussianPSF(0.15)  # 150nm PSF width
-images = gen_images(smld, psf; 
+images = gen_images(smld_cam, psf;
     support=1.0,         # 1.0 μm PSF support radius (faster)
     bg=5.0,              # Background photons per pixel
-    poisson_noise=true   # Add realistic photon counting noise
+    camera_noise=true    # Full sCMOS noise model (QE, Poisson, read noise, gain, offset)
 )
 ```
 

dev/Project.toml

@@ -1,6 +1,9 @@
 [deps]
+ColorTypes = "3da002f7-5984-5a60-b8a6-cbb66c0b333f"
+FixedPointNumbers = "53c48c17-4a7d-5ca2-90c5-79b7896eea93"
 GLMakie = "e9467ef8-e4e7-5192-8a1a-b1aee30e663a"
 MicroscopePSFs = "de9ac726-48a4-48ab-84b0-1c03c7c18929"
 Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
 SMLMSim = "5a0a87e4-02d4-41f5-bf26-b8c94c784a04"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+VideoIO = "d6d074c3-1acf-5d4c-9a43-ef38773959a2"

dev/outputs/.gitkeep

@@ -0,0 +1 @@
+# Outputs from dev demos are saved here (gitignored)