### Install synpivimage with all dependencies

Source: https://github.com/matthiasprobst/synpivimage/blob/main/README.md

Install the package including all available optional dependencies.

```cmd
pip install .[all]
```

--------------------------------

### Install synpivimage with GUI dependencies

Source: https://github.com/matthiasprobst/synpivimage/blob/main/README.md

Install the package with experimental GUI dependencies.

```cmd
pip install .[gui]
```

--------------------------------

### Install synpivimage package

Source: https://github.com/matthiasprobst/synpivimage/blob/main/README.md

Navigate to the cloned repository and install the package using pip.

```cmd
cd synpivimage/
pip install .
```

--------------------------------

### Install synpivimage for development

Source: https://github.com/matthiasprobst/synpivimage/blob/main/README.md

For development purposes, install the package in editable mode.

```cmd
pip install -e .
```

--------------------------------

### Initialize Camera and Laser

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/DoubleImage.ipynb

Setup the camera and laser parameters required for image simulation.

```python
import numpy as np

import synpivimage
```

```python
cam = synpivimage.Camera(
    nx=256,
    ny=256,
    bit_depth=16,
    qe=1,
    sensitivity=1,
    baseline_noise=50,
    dark_noise=10,
    shot_noise=False,
    fill_ratio_x=1.0,
    fill_ratio_y=1.0,
    particle_image_diameter=4  # px
)

laser = synpivimage.Laser(
    width=0.25,
    shape_factor=2
)
```

--------------------------------

### Install synpivimage with test dependencies

Source: https://github.com/matthiasprobst/synpivimage/blob/main/README.md

Install the package along with dependencies required for running tests.

```cmd
pip install .[test]
```

--------------------------------

### Install Documentation Dependencies

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/README.md

Install the required dependencies for building documentation. This command ensures all necessary packages, including Sphinx and themes, are available.

```bash
pip install -e "synpivimage[docs]"
```

--------------------------------

### Import and Initialize Synpivimage

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/out_of_plane.ipynb

Imports necessary libraries and sets the logging level for synpivimage. Ensure synpivimage is installed.

```python
import numpy as np

import synpivimage as spi 
print(f"using synpivimage version {spi.__version__}")

from pivimage import PIVImage, PIVImagePair # for visualization
from pprint import pprint
from mpl_toolkits.axes_grid1 import make_axes_locatable
import matplotlib.pyplot as plt

spi.set_loglevel('INFO')
```

--------------------------------

### Configure Camera and Particle Parameters

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/Camera.ipynb

Setup for particle objects, laser properties, and camera sensor configuration.

```python
one_particle = synpivimage.Particles(
    x=4,
    y=4,
    z=0,
    size=2  # this is NOT the image particle size!
)

laser = synpivimage.Laser(shape_factor=10**3, width=1)


cam = synpivimage.Camera(
    nx=8,
    ny=8,
    bit_depth=16,
    qe=1,
    sensitivity=1,
    baseline_noise=0,
    dark_noise=0,
    shot_noise=False,
    fill_ratio_x=1.0,
    fill_ratio_y=1.0,
    particle_image_diameter=2,
    seed=10
)
```

--------------------------------

### Virtual PIV Setup

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/api.md

Documentation regarding the configuration and setup of the Virtual PIV environment.

```APIDOC
## Virtual PIV Setup

### Description
This section covers the configuration and initialization of the Virtual PIV (Particle Image Velocimetry) environment within the synpivimage project.
```

--------------------------------

### Import synpivimage and check version

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/take_a_single_image.ipynb

Imports the necessary library and displays its version. Ensure you have the library installed.

```python
import numpy as np
from pivimage import PIVImage, PIVImagePair # for visualization

import synpivimage as spi 
spi.__version__
```

--------------------------------

### Install Sphinx Read the Docs Theme

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/README.md

Installs the 'sphinx_rtd_theme' package, which is commonly used for Sphinx documentation. This is a troubleshooting step if the theme is not found.

```python
python3 -m pip install sphinx_rtd_theme
```

--------------------------------

### Minimal synpivimage example

Source: https://github.com/matthiasprobst/synpivimage/blob/main/README.md

This example demonstrates the basic usage of synpivimage for generating synthetic PIV images. It includes setting up camera and laser parameters, defining particles, taking images, displacing particles, and writing output to both TIF and HDF5 files.

```python
import numpy as np

import synpivimage

cam = synpivimage.Camera(
    nx=256,
    ny=256,
    bit_depth=16,
    qe=1,
    sensitivity=1,
    baseline_noise=50,
    dark_noise=10,
    shot_noise=False,
    fill_ratio_x=1.0,
    fill_ratio_y=1.0,
    particle_image_diameter=4  # px
)

laser = synpivimage.Laser(
    width=0.25,
    shape_factor=2
)

n = 100
particles = synpivimage.Particles(
    x=np.random.uniform(-3, cam.nx - 1, n),
    y=np.random.uniform(-4, cam.ny - 1, n),
    z=np.zeros(n),
    size=np.ones(n) * 2,
)

imgA, partA = synpivimage.take_image(laser,
                                     cam,
                                     particles,
                                     particle_peak_count=1000)

displaced_particles = partA.displace(dx=2.1, dy=3.4)

imgB, partB = synpivimage.take_image(laser,
                                     cam,
                                     displaced_particles,
                                     particle_peak_count=1000)

with synpivimage.Imwriter(case_name="test_case",
                          camera=cam,
                          laser=laser) as iw:
    iw.writeA(0, imgA, partA)
    iw.writeB(0, imgB, partB)

with synpivimage.HDF5Writer(filename='data.hdf',
                            n_images=1,
                            camera=cam,
                            laser=laser) as hw:
    hw.writeA(0, imgA, partA)
    hw.writeB(0, imgB, partB)
```

--------------------------------

### Import necessary libraries

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/take_double_image.ipynb

Import the required modules from the pivimage and synpivimage libraries. Ensure synpivimage is installed.

```python
import numpy as np

from pivimage import PIVImage, PIVImagePair # for visualization

import synpivimage as spi 
spi.__version__
```

--------------------------------

### Build HTML Documentation

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/README.md

Generates the HTML documentation output. The `index.html` file will be created in the `_build/` folder. Ensure the `sphinx_rtd_theme` is installed if you encounter theme errors.

```bash
sphinx-build -b html . _build
```

--------------------------------

### Create Camera and Laser Objects

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/IO.ipynb

Instantiate Camera and Laser objects with specified parameters. These objects represent the physical setup for image acquisition.

```python
cam = synpivimage.Camera(
    nx=128,
    ny=128,
    bit_depth=16,
    qe=1,
    sensitivity=1,
    baseline_noise=0,
    dark_noise=0,
    shot_noise=False,
    fill_ratio_x=1.0,
    fill_ratio_y=1.0,
    particle_image_diameter=1.0
)

gauss_laser = synpivimage.Laser(
    width=1.4,
    shape_factor=2
)
```

--------------------------------

### Configure Camera Parameters

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/take_double_image.ipynb

Define the camera's properties, including resolution, bit depth, quantum efficiency, sensitivity, and noise levels. This setup is crucial for realistic image simulation.

```python
cam = Camera(
    nx=16,
    ny=16,
    bit_depth=16,
    qe=1,
    sensitivity=1,
    baseline_noise=50,
    dark_noise=10,
    shot_noise=False,
    fill_ratio_x=1.0,
    fill_ratio_y=1.0,
    particle_image_diameter=2  # px
)
```

--------------------------------

### Import Libraries and Get Version

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/Velocity_Based_Double_Image.ipynb

Imports necessary libraries including numpy and synpivimage. It also retrieves the synpivimage version.

```python
import numpy as np

import synpivimage as spi 
from synpivimage import take_image, Camera, Laser, Particles
spi.__version__
```

--------------------------------

### Saving Data to HDF5

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/SingleImage.ipynb

Writes the generated image and setup parameters to an HDF5 file.

```python
import h5rdmtoolbox as h5tbx
```

```python
with synpivimage.HDF5Writer(filename='single_img.hdf',
                            n_images=1,
                            camera=cam,
                            laser=laser,
                            overwrite=True) as h5:
    h5.writeA(0, img, particles=part)
    h5.writeA(0, img, particles=part)

h5tbx.dump('single_img.hdf')
```

--------------------------------

### Displaying Correlation and Peak Fit Setup

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/out_of_plane.ipynb

Sets up a figure with two subplots to display the correlation plane and prepare for plotting the sub-pixel peak fit. This snippet is incomplete as it lacks the actual plotting calls for the second subplot.

```python
fig, axs = plt.subplots(1, 2)
plot_img(corr, axs[0])
# axs[0].scatter(peak1_i, peak1_j,
#                marker='+', label='max in value')
# axs[1].plot([-1,0,1], [cl, c, cr], 'b--')
```

--------------------------------

### Saving Data to TIFF

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/SingleImage.ipynb

Writes the generated image and setup parameters to a TIFF file.

```python
with synpivimage.Imwriter(case_name='single_img',
                          image_dir='.',
                          suffix='.tif',
                          overwrite=True,
                          camera=cam,
                          laser=laser) as iw:
    iw.write(0, img, particles=part)
```

--------------------------------

### Setup Particles Outside FOV

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/Camera.ipynb

Place particles outside the sensor field of view to capture background noise only.

```python
no_particles = synpivimage.Particles(
    x=-100,
    y=-100,
    z=0,
    size=2
)

laser = synpivimage.Laser(shape_factor=10**3, width=1)
```

--------------------------------

### Initialize Simulation Components

Source: https://context7.com/matthiasprobst/synpivimage/llms.txt

Sets up the camera and laser objects required for generating synthetic PIV images.

```python
import synpivimage

# Setup camera and laser
cam = synpivimage.Camera(
    nx=256, ny=256, bit_depth=16, qe=1, sensitivity=1,
    baseline_noise=50, dark_noise=10, shot_noise=False,
    fill_ratio_x=1.0, fill_ratio_y=1.0, particle_image_diameter=4
)
laser = synpivimage.Laser(width=0.25, shape_factor=2)
```

--------------------------------

### Configure Simulation Parameters

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/out_of_plane.ipynb

Sets up the laser, camera, and particle field parameters for a new simulation.

```python
laser = spi.Laser(shape_factor=10**3, width=10)

cam = spi.Camera(
    nx=128,
    ny=128,
    bit_depth=16,
    qe=1,
    sensitivity=1,
    baseline_noise=0,
    dark_noise=0,
    shot_noise=False,
    fill_ratio_x=1.0,
    fill_ratio_y=1.0,
    particle_image_diameter=2,
    seed=10
)

ppp = 0.1
x_margin = 10, 0
y_margin = 10, 0
z_margin = 2, 0

FOVx = cam.nx + x_margin[0] + x_margin[1]
FOVy = cam.ny + y_margin[0] + y_margin[1]
FOVz = laser.width + z_margin[0] + z_margin[1]

print(FOVx)
print(FOVy)
print(FOVz)
n_particles = int(ppp*FOVx*FOVy*FOVz)
print(n_particles)
N =  int(n_particles/2/2/2)
print(N)
px = np.random.uniform(-x_margin[0], cam.nx+x_margin[1], N)
py = np.random.uniform(-y_margin[0], cam.ny+y_margin[1], N)
pz = np.random.uniform(-laser.width/2-z_margin[0], laser.width/2+z_margin[1], N)

particles = spi.Particles(
    x=px,
    y=py,
    z=np.zeros_like(px),
    size=np.ones_like(px)*2
)
```

```text
138
138
12.0
22852
2856
```

--------------------------------

### Initialize Particle Simulation

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/Laser.ipynb

Sets up a single particle instance for image generation.

```python
one_particle = synpivimage.Particles(
    x=[8, ],
    y=[8, ],
    z=[0, ],
    size=[2, ]
)
```

--------------------------------

### Initialize PIV Image Generation Workflow

Source: https://context7.com/matthiasprobst/synpivimage/llms.txt

Sets up camera, laser, and particle parameters for a synthetic PIV generation workflow.

```python
import numpy as np
import synpivimage

# Configure logging
synpivimage.set_loglevel(logging.INFO)

# 1. Define camera parameters
cam = synpivimage.Camera(
    nx=512,
    ny=512,
    bit_depth=16,
    qe=0.85,
    sensitivity=1.0,
    baseline_noise=80,
    dark_noise=12,
    shot_noise=True,
    fill_ratio_x=1.0,
    fill_ratio_y=1.0,
    particle_image_diameter=3.5,
    seed=42  # For reproducibility
)

# 2. Define laser parameters
laser = synpivimage.Laser(
    width=0.3,
    shape_factor=2
)

# 3. Generate particles with target seeding density
particles = synpivimage.Particles.generate(
    ppp=0.04,
    dx_max=(-8, 8),
    dy_max=(-8, 8),
    dz_max=(-0.15, 0.15),
    size=2.0,
    camera=cam,
    laser=laser
)

# 4. Define displacement field (uniform flow example)
dx = 4.2  # pixels
dy = 2.8  # pixels
```

--------------------------------

### Initialize Camera and Laser objects

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/OutOfPlane.ipynb

Configure the camera sensor parameters and laser sheet properties for the simulation.

```python
cam = synpivimage.Camera(
    nx=256,
    ny=256,
    bit_depth=16,
    qe=1,
    sensitivity=1,
    baseline_noise=50,
    dark_noise=10,
    shot_noise=False,
    fill_ratio_x=1.0,
    fill_ratio_y=1.0,
    particle_image_diameter=4,  # px
    seed=100
)

laser = synpivimage.Laser(
    width=1,
    shape_factor=2
)
```

--------------------------------

### Instantiate Laser Component with Extracted Parameters

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/SingleImage.ipynb

Instantiate a `synpivimage.Laser` component using the extracted parameters dictionary. The keys of the dictionary should match the component's attribute names.

```python
synpivimage.Laser(**params)
```

--------------------------------

### Initialize Camera Parameters

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/Velocity_Based_Double_Image.ipynb

Sets up the camera parameters such as resolution, bit depth, and noise characteristics. These parameters define the properties of the captured images.

```python
cam = Camera(
    nx=512,
    ny=512,
    bit_depth=16,
    qe=1,
    sensitivity=1,
    baseline_noise=50,
    dark_noise=10,
    shot_noise=False,
    fill_ratio_x=1.0,
    fill_ratio_y=1.0,
    particle_image_diameter=2  # px
)

laser = Laser(
    width=0.25,
    shape_factor=2
)
```

--------------------------------

### Initialize Camera for Noise Simulation

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/Camera.ipynb

Configure the camera object with specific noise parameters.

```python
cam = synpivimage.Camera(
    nx=128,
    ny=128,
    bit_depth=16,
    qe=1,
    sensitivity=1,
    baseline_noise=0,
    dark_noise=0,
    shot_noise=False,
    fill_ratio_x=1.0,
    fill_ratio_y=1.0,
    particle_image_diameter=2,
    seed=10
)
```

--------------------------------

### Get PPP for Particle Set B

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/out_of_plane.ipynb

Retrieves the particles per pixel value for the second particle set.

```python
partB.get_ppp(cam.size)
```

```text
np.float64(0.0106201171875)
```

--------------------------------

### Configure Camera Settings

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/Camera.ipynb

Sets up camera parameters including sensor size, bit depth, quantum efficiency, and noise levels. Initializes a camera object for image simulation.

```python
cam = synpivimage.Camera(
    nx=8,
    ny=8,
    bit_depth=16,
    qe=1,
    sensitivity=1,
    baseline_noise=10,
    dark_noise=0,
    shot_noise=False,
    fill_ratio_x=1.0,
    fill_ratio_y=1.0,
    particle_image_diameter=2,
    seed=50
)

one_particles = synpivimage.Particles(
    x=4,
    y=4,
    z=0,
    size=2
)
```

--------------------------------

### Plot Single Captured Image

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/take_a_single_image.ipynb

Visualizes the captured single particle image using matplotlib. Requires matplotlib to be installed.

```python
import matplotlib.pyplot as plt

plt.figure()
PIVImage.from_array(imgOne).plot()
plt.show()
```

--------------------------------

### Instantiate New Laser with Loaded Parameters

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/IO.ipynb

Create a new `synpivimage.Laser` object using the parameters extracted from the JSON-LD file. This demonstrates the process of loading and reusing configurations.

```python
loaded_gauss_laser = synpivimage.Laser(
    width=lst,
    shape_factor=lsf
)
loaded_gauss_laser
```

--------------------------------

### Configure and Manage Camera Sensors

Source: https://context7.com/matthiasprobst/synpivimage/llms.txt

Initializes a camera sensor with specific noise and resolution parameters, and demonstrates saving/loading configurations via JSON-LD.

```python
import synpivimage

# Create a camera with specific sensor parameters
cam = synpivimage.Camera(
    nx=256,                    # Sensor width in pixels
    ny=256,                    # Sensor height in pixels
    bit_depth=16,              # Bit depth (8 or 16)
    qe=0.9,                    # Quantum efficiency (0-1)
    sensitivity=1.0,           # Sensor sensitivity (0-1)
    baseline_noise=50,         # Mean baseline noise level
    dark_noise=10,             # Dark noise standard deviation
    shot_noise=True,           # Enable shot noise (Poisson)
    fill_ratio_x=1.0,          # Pixel fill ratio in x (0-1)
    fill_ratio_y=1.0,          # Pixel fill ratio in y (0-1)
    particle_image_diameter=4, # Particle image diameter in pixels
    seed=42                    # Random seed for reproducibility
)

# Access camera properties
print(f"Sensor size: {cam.size} pixels ({cam.nx}x{cam.ny})")
print(f"Max count value: {cam.max_count}")  # 2^bit_depth - 1

# Save camera configuration as JSON-LD metadata
cam.save_jsonld("camera_config.json")

# Load camera configuration from JSON-LD
cameras = synpivimage.Camera.load_jsonld("camera_config.json")
```

--------------------------------

### Configure camera settings

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/Laser.ipynb

Set up camera parameters for image acquisition.

```python
cam = synpivimage.Camera(
    nx=16,
    ny=16,
    bit_depth=16,
    qe=1,
    sensitivity=1,
    baseline_noise=0,
    dark_noise=0,
    shot_noise=False,
    fill_ratio_x=1.0,
    fill_ratio_y=1.0,
    particle_image_diameter=1.0
)
```

--------------------------------

### Initialize synpivimage environment

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/Camera.ipynb

Standard imports required for using the synpivimage library and plotting results.

```python
import matplotlib.pyplot as plt
import numpy as np

import synpivimage
```

--------------------------------

### Configuring Camera and Laser

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/SingleImage.ipynb

Sets up the camera sensor parameters and laser properties for the synthetic environment.

```python
cam = synpivimage.Camera(
    nx=16,
    ny=16,
    bit_depth=16,
    qe=1,
    sensitivity=1,
    baseline_noise=50,
    dark_noise=10,
    shot_noise=False,
    fill_ratio_x=1.0,
    fill_ratio_y=1.0,
    particle_image_diameter=2,
    seed=100
)

laser = synpivimage.Laser(
    width=0.25,
    shape_factor=2
)
```

--------------------------------

### Build PDF Documentation

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/README.md

Generates the PDF documentation output using the LaTeX builder. After running this command, navigate to the source folder and run the make file to build the actual PDF.

```bash
sphinx-build -b latex . _build
```

--------------------------------

### Initialize HDF5Writer and write image

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/take_a_single_image.ipynb

Configures the HDF5 writer with camera and laser parameters to save image data.

```python
with HDF5Writer('single_img.hdf',
                n_images=2,
                overwrite=True,
                camera=cam,
                laser=laser) as h5:
    h5.writeA(0, img=imgOne)
```

--------------------------------

### Clone the repository

Source: https://github.com/matthiasprobst/synpivimage/blob/main/README.md

Use this command to clone the synpivimage repository from GitHub.

```cmd
git clone https://github.com/matthiasprobst/synpivimage
```

--------------------------------

### Import synpivimage

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/IO.ipynb

Import the synpivimage library to use its functionalities.

```python
import synpivimage
```

--------------------------------

### Generate Initial Particles

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/DoubleImage.ipynb

Create an initial set of particles with random positions.

```python
n = 100
particles = synpivimage.Particles(
    x=np.random.uniform(-3, cam.nx-1, n),
    y=np.random.uniform(-4, cam.ny-1, n),
    z=np.zeros(n),
    size=np.ones(n)*2,
)
```

--------------------------------

### Import Image Writer

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/take_double_image.ipynb

Import the Imwriter class from synpivimage.io for saving image data.

```python
from synpivimage.io import Imwriter
```

--------------------------------

### Clean Documentation Build Directory

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/README.md

Removes the existing build directory to ensure a clean build process. Run this command before generating new documentation files.

```bash
make clean
```

--------------------------------

### Generate and Save PIV Images with Imwriter

Source: https://context7.com/matthiasprobst/synpivimage/llms.txt

Demonstrates generating image pairs and saving them to disk using the Imwriter context manager.

```python
imgA, partA = synpivimage.take_image(laser, cam, particles, particle_peak_count=1000)
displaced = partA.displace(dx=3.0, dy=2.0)
imgB, partB = synpivimage.take_image(laser, cam, displaced, particle_peak_count=1000)

with synpivimage.Imwriter(
    case_name="piv_experiment_001",
    image_dir="./output",           # Optional output directory
    suffix=".tif",                  # Image file format
    overwrite=True,                 # Overwrite existing files
    camera=cam,                     # Save camera metadata
    laser=laser                     # Save laser metadata
) as iw:
    # Write first image pair
    iw.writeA(0, imgA, particles=partA)
    iw.writeB(0, imgB, particles=partB)

    # Write additional image pairs (e.g., time series)
    particles2 = partB.displace(dx=3.0, dy=2.0)
    imgC, partC = synpivimage.take_image(laser, cam, particles2, particle_peak_count=1000)
    iw.writeA(1, imgB, particles=partB)
    iw.writeB(1, imgC, particles=partC)
```

--------------------------------

### Configure Noise Parameters

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/Camera.ipynb

Update baseline and dark noise settings on the camera object.

```python
cam.baseline_noise = 50
cam.dark_noise = 10

img, _ = synpivimage.take_image(particles=no_particles,
                        camera=cam, laser=laser,
                        particle_peak_count=1000)
plt.imshow(img)
plt.title(f"$\\mu$= {cam.baseline_noise}, $\\sigma$={cam.dark_noise}")
```

```python
cam.baseline_noise = 0
cam.dark_noise = 10
```

```python
img, _ = synpivimage.take_image(particles=no_particles,
                        camera=cam, laser=laser,
                        particle_peak_count=1000)
plt.imshow(img)
plt.title(f"$\\mu$= {cam.baseline_noise}, $\\sigma$={cam.dark_noise}")
```

```python
cam.baseline_noise = 10
cam.dark_noise = 0
```

```python
img, _ = synpivimage.take_image(particles=no_particles,
                        camera=cam, laser=laser,
                        particle_peak_count=1000)

plt.imshow(img)
plt.title(f"$\\mu$= {cam.baseline_noise}, $\\sigma$={cam.dark_noise}")
```

--------------------------------

### Generate and Print Particle Density

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/out_of_plane.ipynb

Initializes particles within a defined camera and laser volume and calculates the active particle density.

```python
partA = generate_particles(0.1, dx_max=[-100, 100], dy_max=[-100, 100], dz_max=[1, 1], camera=cam, laser=laser)
print(partA.active.sum()/cam.nx/cam.ny)
```

```text
0.00994873046875
```

--------------------------------

### Query JSON-LD for Laser Parameters using Ontolutils

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/SingleImage.ipynb

Query a JSON-LD file for laser parameters using `ontolutils.dquery`. This method returns a list of dictionaries, where each dictionary represents a laser model found in the file. The context is used to map prefixes to URIs.

```python
query_dict = ontolutils.dquery(
    'pivmeta:LaserModel',
    'single_img/laser.json',
    context={'pivmeta': 'https://matthiasprobst.github.io/pivmeta#'}
)

for p in query_dict[0]['hasParameter']:
    print(f"{p['label']:14s}: {p['hasNumericalValue']} (std name: {p['hasStandardName']})")
```

--------------------------------

### Load JSON-LD Data with Synpivimage

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/SingleImage.ipynb

Load laser and camera data from JSON-LD files using the `load_jsonld` method. Ensure the file paths are correct.

```python
loaded_laser = synpivimage.Laser.load_jsonld('single_img/laser.json')
loaded_camera = synpivimage.Camera.load_jsonld('single_img/camera.json')
```

--------------------------------

### Create particle distribution

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/Laser.ipynb

Generate a set of particles for illumination testing.

```python
many_particles = synpivimage.Particles(
    x=np.ones_like(z),
    y=np.ones_like(z),
    z=z,
    size=np.ones_like(z)
)
```

--------------------------------

### Import PIV functions

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/take_double_image.ipynb

Import the core functions and classes for image generation from synpivimage.

```python
from synpivimage import take_image, Camera, Laser, Particles
```

--------------------------------

### Import matplotlib

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/Laser.ipynb

Import the plotting library for visualization.

```python
import matplotlib.pyplot as plt
```

--------------------------------

### Manage Seeding Particles

Source: https://context7.com/matthiasprobst/synpivimage/llms.txt

Initializes particle objects with explicit 3D coordinates and sizes, supporting export to JSON-LD format.

```python
import numpy as np
import synpivimage

# Create particles with explicit positions
n_particles = 100
particles = synpivimage.Particles(
    x=np.random.uniform(-3, 253, n_particles),  # x-coordinates (pixels)
    y=np.random.uniform(-4, 252, n_particles),  # y-coordinates (pixels)
    z=np.zeros(n_particles),                     # z-coordinates (laser sheet units)
    size=np.ones(n_particles) * 2                # Particle sizes (arbitrary units)
)

# Access particle properties
print(f"Number of particles: {len(particles)}")
print(f"Active particles: {particles.n_active}")

# Get dictionary representation
particle_data = particles.dict()

# Save particles as JSON-LD
particles.save_jsonld("particles.json")
```

--------------------------------

### take_image

Source: https://context7.com/matthiasprobst/synpivimage/llms.txt

Simulates the complete PIV image acquisition process.

```APIDOC
## take_image

### Description
Simulates the complete PIV image acquisition process including laser illumination, particle imaging, sensor capture, and noise addition.

### Parameters
- **laser** (object) - Required - Laser configuration
- **camera** (object) - Required - Camera configuration
- **particles** (object) - Required - Particle set
- **particle_peak_count** (int) - Required - Target peak intensity for particles
```

--------------------------------

### Visualize Noise Model Output

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/Camera.ipynb

Generate and display an image based on current camera noise settings.

```python
img, _ = synpivimage.take_image(particles=no_particles,
                        camera=cam, laser=laser,
                        particle_peak_count=1000)
plt.imshow(img)
plt.title(f"$\\mu$= {cam.baseline_noise}, $\\sigma$={cam.dark_noise}")
```

--------------------------------

### Define laser profiles

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/Laser.ipynb

Create Gaussian and top-hat laser sheet profiles with a specified width.

```python
z = np.linspace(-2, 2, 10000)
gauss_laser = synpivimage.Laser(
    width=1,
    shape_factor=1
)
tophat_laser = synpivimage.Laser(
    width=1,
    shape_factor=10
)
```

--------------------------------

### Import h5rdmtoolbox

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/take_a_single_image.ipynb

Required import for interacting with HDF5 file structures.

```python
import h5rdmtoolbox as h5tbx
```

--------------------------------

### Import synpivimage dependencies

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/OutOfPlane.ipynb

Initial imports required for numerical operations and plotting.

```python
import numpy as np
import matplotlib.pyplot as plt

import synpivimage
```

--------------------------------

### Import Ontolutils Library

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/SingleImage.ipynb

Import the `ontolutils` library, which is used for querying JSON-LD files with SPARQL.

```python
import ontolutils
```

--------------------------------

### Configure Laser Parameters

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/take_double_image.ipynb

Set the laser's illumination width and shape factor. These parameters influence how particles are illuminated in the simulated images.

```python
laser = Laser(
    width=0.25,
    shape_factor=2
)
```

--------------------------------

### Save Camera and Laser to JSON-LD

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/IO.ipynb

Save the configurations of Camera and Laser objects to JSON-LD files using the `save_jsonld` method. This allows for persistent storage and later retrieval of the parameters.

```python
cam_filename = cam.save_jsonld('cam.json')
gauss_laser_filename = gauss_laser.save_jsonld('laser.json')
```

--------------------------------

### Visualize Image Pair

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/take_double_image.ipynb

Create a PIVImagePair object from the generated images and display them using the plot method. This is useful for visually inspecting the simulated particle field.

```python
imgpair = PIVImagePair(A=PIVImage.from_array(imgA), B=PIVImage.from_array(imgB))
imgpair.plot()
```

--------------------------------

### Displaying Simulated Images

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/out_of_plane.ipynb

Shows a specific pair of simulated images (imgA and imgB) from the generated stacks. This helps visualize the effect of particle displacement.

```python
fig, axs = plt.subplots(1, 2)
plot_img(imgsA[3, ...], axs[0], vmax=2**cfg.bit_depth)
plot_img(imgsB[3, ...], axs[1], vmax=2**cfg.bit_depth)
plt.tight_layout()
plt.show()
```

--------------------------------

### Generate Particles with Target PPP

Source: https://context7.com/matthiasprobst/synpivimage/llms.txt

Generates particles with a target particles per pixel (ppp) density. Ensure ppp is between 0 and 1. Max displacement and particle size can be configured.

```python
particles = synpivimage.Particles.generate(
    ppp=0.05,              # Target particles per pixel (0 < ppp < 1)
    dx_max=(-5, 5),        # Max displacement range in x
    dy_max=(-5, 5),        # Max displacement range in y
    dz_max=(-0.1, 0.1),    # Max displacement range in z
    size=2.0,              # Particle size
    camera=cam,
    laser=laser
)

print(f"Generated {len(particles)} particles")
print(f"Achieved ppp: {particles.get_ppp(cam.size):.4f}")
```

--------------------------------

### Create and Plot PIV Image Pair

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/out_of_plane.ipynb

Creates a PIV image pair object and visualizes it.

```python
imgpair = PIVImagePair(A=PIVImage.from_array(imgA), B=PIVImage.from_array(imgB))
imgpair.plot()
```

```text
(<Axes: >, <Axes: >, <Axes: >, <Axes: >)
```

```text
<Figure size 300x300 with 4 Axes>
```

--------------------------------

### Generate Particles by Density

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/DoubleImage.ipynb

Generate particles based on a target ppp value and displacement constraints.

```python
particles01 = synpivimage.Particles.generate(ppp=0.1, dx_max=[0, 2.1], dy_max=[0, 3.4], dz_max=[0, 0], camera=cam, laser=laser)
particles01.get_ppp(cam.size)
```

--------------------------------

### synpivimage.Imwriter

Source: https://context7.com/matthiasprobst/synpivimage/llms.txt

Context manager for saving PIV image sequences to individual files.

```APIDOC
## Imwriter

### Description
Context manager to save PIV image pairs and associated metadata to a directory structure.

### Parameters
- **case_name** (str) - Required - Name of the experiment case.
- **image_dir** (str) - Optional - Output directory path.
- **suffix** (str) - Optional - Image file format (e.g., .tif).
- **overwrite** (bool) - Optional - Whether to overwrite existing files.
- **camera** (object) - Optional - Camera metadata to save.
- **laser** (object) - Optional - Laser metadata to save.
```

--------------------------------

### Visualize Image A

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/Velocity_Based_Double_Image.ipynb

Visualizes the first captured image (imgA) using PIVImage. This helps in inspecting the particle distribution in the initial image.

```python
from pivimage import PIVImage

PIVImage.from_array(imgA).plot()
```

--------------------------------

### Configure Laser and Camera Settings

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/out_of_plane.ipynb

Defines parameters for the laser and camera, including shape factor, dimensions, bit depth, and noise characteristics. These settings influence particle image generation.

```python
laser = spi.Laser(shape_factor=10**3, width=10)

cam = spi.Camera(
    nx=128,
    ny=128,
    bit_depth=16,
    qe=1,
    sensitivity=1,
    baseline_noise=0,
    dark_noise=0,
    shot_noise=False,
    fill_ratio_x=1.0,
    fill_ratio_y=1.0,
    particle_image_diameter=2,
    seed=10
)
```

--------------------------------

### Acquire Image with Custom Particles

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/out_of_plane.ipynb

Captures an image using the custom particle configuration.

```python
imgA, partA = spi.take_image(particles=particles,
                             camera=cam,
                             laser=laser,
                             particle_peak_count=1000)
```

--------------------------------

### Run tests with coverage

Source: https://github.com/matthiasprobst/synpivimage/blob/main/README.md

Execute tests using pytest and generate an HTML coverage report.

```bash
pytest --cov=synpivimage --cov-report html
```

--------------------------------

### Configuring Particle Simulation Parameters

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/out_of_plane.ipynb

Sets specific parameters for particle simulation, including particle number, interrogation window size, particle size, laser width, and density. This is typically done before generating images.

```python
cfg.particle_number = 6
cfg.nx = 16
cfg.ny = 16
cfg.particle_size_mean = 2.5
cfg.particle_size_std = 0
cfg.laser_width = 1
cfg.particle_density()
```

--------------------------------

### Generate Image Pair

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/take_double_image.ipynb

Create the first image (imgA) and its associated particle data (partA). Then, generate the second image (imgB) by displacing the particles from partA. This simulates the particle movement between two consecutive camera exposures.

```python
imgA, partA = take_image(laser, cam, particles, particle_peak_count=1000)

imgB, partB = take_image(laser, cam,
                         partA.displace(dx=4, dz=laser.width/2),
                         particle_peak_count=1000)
```

--------------------------------

### Load Laser from JSON-LD

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/IO.ipynb

Load a Laser object from a JSON-LD file using `LaserModel.from_jsonld`. This method reconstructs the object based on the ontology defined in the file.

```python
from pivmetalib.pivmeta import LaserModel
from ontolutils.namespacelib import PIVMETA

loaded_laser = LaserModel.from_jsonld(gauss_laser_filename)[0]
```

--------------------------------

### Capture image

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/Laser.ipynb

Simulate image acquisition with the defined laser and camera.

```python
imgOne, partOne = synpivimage.take_image(gauss_laser, cam, many_particles, particle_peak_count=1000)
```

--------------------------------

### Importing FFT and Numpy Libraries

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/out_of_plane.ipynb

Imports necessary functions for 2D Fast Fourier Transforms (FFT) and numerical operations from scipy and numpy.

```python
from scipy.fft import rfft2, irfft2, fftshift
import numpy as np
```

--------------------------------

### Importing Curve Fit Library

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/out_of_plane.ipynb

Imports the `curve_fit` function from `scipy.optimize` for performing non-linear least squares fitting.

```python
from scipy.optimize import curve_fit
```

--------------------------------

### Define Laser Sheet Profiles

Source: https://context7.com/matthiasprobst/synpivimage/llms.txt

Creates laser sheet objects with adjustable intensity profiles, ranging from Gaussian to top-hat distributions.

```python
import synpivimage

# Create a Gaussian laser sheet
laser_gaussian = synpivimage.Laser(
    width=0.25,       # Laser sheet width (arbitrary units)
    shape_factor=1    # 1=Gaussian, >100=top-hat profile
)

# Create a top-hat laser sheet
laser_tophat = synpivimage.Laser(
    width=0.5,
    shape_factor=200  # High value creates top-hat profile
)

# Save laser configuration as JSON-LD metadata
laser_gaussian.save_jsonld("laser_config.json")

# Load laser configuration from JSON-LD
lasers = synpivimage.Laser.load_jsonld("laser_config.json")
```

--------------------------------

### Configure Camera Settings

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/take_a_single_image.ipynb

Defines camera parameters such as resolution, bit depth, sensitivity, and noise levels. These settings influence the synthetic image quality.

```python
cam = Camera(
    nx=16,
    ny=16,
    bit_depth=16,
    qe=1,
    sensitivity=1,
    baseline_noise=50,
    dark_noise=10,
    shot_noise=False,
    fill_ratio_x=1.0,
    fill_ratio_y=1.0,
    particle_image_diameter=2
)
```

--------------------------------

### Calculate Particle Density (ppp)

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/DoubleImage.ipynb

Retrieve the current particles per pixel (ppp) value for the generated images.

```python
partA.get_ppp(cam.size), partB.get_ppp(cam.size)
```

--------------------------------

### synpivimage.HDF5Writer

Source: https://context7.com/matthiasprobst/synpivimage/llms.txt

Context manager for saving PIV image sequences to a single HDF5 file.

```APIDOC
## HDF5Writer

### Description
Context manager for saving PIV image sequences to a single HDF5 file with embedded metadata and dimension scales.

### Parameters
- **filename** (str) - Required - Path to the HDF5 file.
- **n_images** (int) - Required - Number of images to pre-allocate.
- **camera** (object) - Required - Camera metadata.
- **laser** (object) - Required - Laser metadata.
- **overwrite** (bool) - Optional - Whether to overwrite existing file.
```

--------------------------------

### Acquire Particle Images

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/out_of_plane.ipynb

Captures images for two particle states using the specified camera and laser configuration.

```python
imgA, partA = spi.take_image(laser=laser, camera=cam, particles=partA, particle_peak_count=1000)
imgB, partB = spi.take_image(laser=laser, camera=cam, particles=partB, particle_peak_count=1000)
```

--------------------------------

### Plot laser profiles

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/Laser.ipynb

Visualize the intensity profiles of the Gaussian and top-hat laser sheets.

```python
plt.plot(z, gauss_iluminated_particles.irrad_photons, label='gauss, s=1')
plt.plot(z, tophat_iluminated_particles.irrad_photons, label='top hat, s=10')
plt.vlines(-gauss_laser.width/2, 0, 1, color='k')
plt.vlines(gauss_laser.width/2, 0, 1, color='k')
plt.ylabel('$I/I_0$')
plt.legend()
```

--------------------------------

### synpivimage.take_image

Source: https://context7.com/matthiasprobst/synpivimage/llms.txt

Generates a synthetic PIV image based on camera, laser, and particle parameters.

```APIDOC
## take_image

### Description
Generates a synthetic PIV image using the provided laser, camera, and particle configuration.

### Parameters
#### Arguments
- **laser** (object) - Required - The laser configuration object.
- **cam** (object) - Required - The camera configuration object.
- **particles** (object) - Required - The particle distribution object.

#### Keyword Arguments
- **particle_peak_count** (int) - Optional - Number of particle peaks to generate.

### Response
- **img** (ndarray) - The generated image array.
- **part** (object) - The particle object used for the image.
```

--------------------------------

### Simulate PIV Image Acquisition with Noise

Source: https://context7.com/matthiasprobst/synpivimage/llms.txt

Simulates the complete PIV image acquisition process, including laser illumination, particle imaging, sensor capture, and noise addition. Configure camera noise characteristics and particle properties for realistic simulation.

```python
import numpy as np
import synpivimage

# Setup camera with noise characteristics
cam = synpivimage.Camera(
    nx=512, ny=512, bit_depth=16, qe=0.9, sensitivity=1.0,
    baseline_noise=100, dark_noise=15, shot_noise=True,
    fill_ratio_x=1.0, fill_ratio_y=1.0, particle_image_diameter=3
)

laser = synpivimage.Laser(width=0.3, shape_factor=2)

particles = synpivimage.Particles(
    x=np.random.uniform(-5, 517, 500),
    y=np.random.uniform(-5, 517, 500),
    z=np.random.uniform(-0.2, 0.2, 500),
    size=np.ones(500) * 2.5
)

# Take the image
img, updated_particles = synpivimage.take_image(
    laser=laser,
    camera=cam,
    particles=particles,
    particle_peak_count=2000  # Target peak intensity for particles
)

# Analyze results
print(f"Image shape: {img.shape}")
print(f"Image dtype: {img.dtype}")
print(f"Intensity range: {img.min()} - {img.max()}")
print(f"Active particles: {updated_particles.n_active}")
print(f"Out-of-plane particles: {updated_particles.n_out_of_plane_loss}")

# Get particle information
updated_particles.info()
```

--------------------------------

### Generate and Save Double Images

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/DoubleImage.ipynb

Use this snippet to generate a set of double images by simulating particle movement and capturing images before and after displacement. Ensure 'synpivimage', 'cam', and 'laser' are properly initialized.

```python
particles01 = synpivimage.Particles.generate(ppp=0.1, dx_max=[0, 2.1], dy_max=[0, 3.4], dz_max=[0, 0], size=2, camera=cam, laser=laser)


with synpivimage.Imwriter(case_name='double_images',
                          camera=cam,
                          laser=laser,
                          overwrite=True) as iw:
    for i in range(10):
        
        imgA, partA = synpivimage.take_image(
            laser,
            cam,
            particles01,  # we passed out new object here!
            particle_peak_count=1000)
    
        displaced_particles = partA.displace(dx=2.1, dy=3.4)
        
        imgB, partB = synpivimage.take_image(
            laser,                                 
            cam,
            displaced_particles,
            particle_peak_count=1000)

        iw.writeA(index=i, img=imgA, particles=partA)
        iw.writeB(index=i, img=imgB, particles=partB)

        particles01.regenerate()
```

--------------------------------

### Import Libraries for Image Processing

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/DoubleImage.ipynb

Import necessary libraries for file path manipulation and image reading.

```python
import pathlib
import cv2
```

--------------------------------

### Illuminate particles

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/Laser.ipynb

Apply laser illumination to the particle set.

```python
gauss_iluminated_particles = gauss_laser.illuminate(many_particles)
tophat_iluminated_particles = tophat_laser.illuminate(many_particles)
```

--------------------------------

### Generate Uniformly Distributed Particles

Source: https://context7.com/matthiasprobst/synpivimage/llms.txt

Creates particles with a uniform random distribution within specified bounds. Particle sizes can be fixed or follow a normal distribution.

```python
import synpivimage

# Generate uniformly distributed particles
particles = synpivimage.Particles.generate_uniform(
    n_particles=500,
    size=2.0,                          # Fixed particle size
    x_bounds=(-10, 266),               # x-coordinate bounds
    y_bounds=(-10, 266),               # y-coordinate bounds
    z_bounds=(-0.2, 0.2)               # z-coordinate bounds (laser sheet)
)

# With variable particle sizes (mean, std)
particles_variable = synpivimage.Particles.generate_uniform(
    n_particles=500,
    size=(2.0, 0.5),                   # Normal distribution (mean=2.0, std=0.5)
    x_bounds=(-10, 266),
    y_bounds=(-10, 266),
    z_bounds=(-0.2, 0.2)
)

print(f"Particle size range: {particles_variable.size.min():.2f} - {particles_variable.size.max():.2f}")
```

--------------------------------

### Defining Particle Positions

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/SingleImage.ipynb

Initializes particle coordinates and sizes, including particles outside the camera field of view.

```python
n = 100
particles = synpivimage.Particles(
    x=np.random.uniform(-5, cam.nx+4, n),
    y=np.random.uniform(-5, cam.ny+4, n),
    z=np.zeros(n),
    size=np.ones(n)*2.5
)
```

--------------------------------

### synpivimage.set_loglevel

Source: https://context7.com/matthiasprobst/synpivimage/llms.txt

Configures the library's logging verbosity.

```APIDOC
## set_loglevel

### Description
Sets the logging level for the synpivimage library.

### Parameters
- **level** (int) - Required - The logging level (e.g., logging.DEBUG, logging.INFO, logging.WARNING).
```

--------------------------------

### Extract Laser Parameters into a Dictionary

Source: https://github.com/matthiasprobst/synpivimage/blob/main/docs/getting_started/SingleImage.ipynb

Extract laser parameters from the queried dictionary into a new dictionary where labels are keys and numerical or string values are values. This simplifies passing parameters to component constructors.

```python
params = {p['label']: p.get('hasNumericalValue', p.get('hasStringValue', None)) for p in query_dict[0]['hasParameter']}
params
```

--------------------------------

### Display Particle Information for Image B

Source: https://github.com/matthiasprobst/synpivimage/blob/main/examples/take_double_image.ipynb

Display the particle information for image B, similar to image A, to compare particle counts and identify any changes.

```python
partB.info()
```