cddm.sim

C-DDM video simulator for two-dimensional Brownian motion of spherical particles.

You can use this script to simulate C-DDM experiment. You define number of particles to simulate and the region of interest (simulation box). Particles are randomly placed in the box, simulation is done using periodic boundary conditions - when the particle reaches the edge of the frame it is mirrored on the other side. Then optical microscope image capture is simulated by drawing a point spread function to the image at the calculated particle positions at a predefined time of interest for both cameras.

The frame grabber is done using iterators to reduce memory requirements. You can analyze video frame by frame with minimal memory requirement.

Module Contents

cddm.sim.form_factor(window, sigma=3, intensity=5, navg=10, dtype='uint8', mode='rfft2')

Computes point spread function form factor.

Draws a PSF randomly in the frame and computes FFT, returns average absolute of the FFT.

Parameters

  • window (ndarray) – A 2D window function used in the analysis. Set this to np.ones if you do not use one.

  • sigma (float) – Sigma of the PSF of the image

  • intensity (unsigned int) – Intensity value

  • navg (int) – Specifies mesh size for averaging.

  • dtype (np.dtype) – One of “uint8” or “uint16”. Defines output dtype of the image.

  • mode (str, optional) – Either ‘rfft2’ (default) or ‘fft2’.

Returns

out – Average absolute value of the FFT of the PSF.

Return type

ndarray

cddm.sim.seed(value)

Seed for numba and numpy random generator

cddm.sim.brownian_walk(x0, count=1024, shape=(256, 256), delta=1, dt=1, velocity=(0.0, 0.0))

Returns an brownian walk iterator.

Given the initial coordinates x0, it callculates and yields next count coordinates.

Parameters

  • x0 (array-like) – A list of initial coordinates (i, j) of particles (in pixel units).

  • count (int) – Number of simulation steps.

  • shape ((int,int)) – Shape of the simulation region in pixels.

  • delta (float) – Defines an average step in pixel coordinates (when dt = 1).

  • dt (float, optional) – Simulation time step (1 by default).

  • velocity ((float,float), optional) – Defines an average velocity (vi,vj) in pixel coordinates per unit time step (when dt = 1).

Yields

coordinates (ndarray) – Coordinates 2D array for the particles. The second axis is the x,y coordinate.

cddm.sim.brownian_particles(count=500, shape=(256, 256), num_particles=100, delta=1, dt=1, velocity=0.0, x0=None)

Coordinates generator of multiple brownian particles.

Builds particles randomly distributed in the computation box and performs random walk of coordinates.

Parameters

  • count (int) – Number of steps to calculate

  • shape ((int,int)) – Shape of the box

  • num_particles (int) – Number of particles in the box

  • delta (float) – Step variance in pixel units (when dt = 1)

  • dt (float) – Time resolution

  • velocity (float) – Velocity in pixel units (when dt = 1)

  • x0 (array-like) – A list of initial coordinates

Yields

coordinates (ndarray) – Coordinates 2D array for the particles. The second axis is the x,y coordinate. Length of the array equals number of particles.

cddm.sim.particles_video(particles, t1, shape=(256, 256), t2=None, background=0, intensity=10, sigma=None, dtype='uint8')

Creates brownian particles video

Parameters

  • particles (iterable) – Iterable of particle coordinates

  • t1 (array-like) – Frame time

  • shape ((int,int)) – Frame shape

  • t2 (array-like, optional) – Second camera frame time, in case we are simulating dual camera video.

  • background (int) – Background frame value

  • intensity (int) – Peak Intensity of the particle.

  • sigma (float) – Sigma of the gaussian spread function for the particle

  • dtype (dtype) – Numpy dtype of frames, either uint8 or uint16

Yields

frames (tuple of ndarrays) – A single-frame or dual-frame images (ndarrays).

cddm.sim.data_trigger(data, indices)

A generator that selects data from an iterator at given unique ‘trigger’ indices

Examples

>>> data = range(10)
>>> indices = [1,4,7]
>>> [x for x in data_trigger(data, indices)]
[1, 4, 7]
cddm.sim.plot_random_walk(count=5000, num_particles=2, shape=(256, 256))

Brownian particles usage example. Track 2 particles

cddm.sim.create_random_time(nframes, n=32, dt_min=1)

Create trigger time for single-camera random ddm experiments

cddm.sim.random_time_count(nframes, n=32)

Returns estimated count for single-camera random triggering scheme

cddm.sim.create_random_times1(nframes, n=32)

Create trigger times for c-ddm experiments based on Eq.7 from the paper

cddm.sim.create_random_times2(nframes, n=32)

Create trigger times for c-ddm experiments based on Eq.8 from the paper

cddm.sim.simple_brownian_video(t1, t2=None, shape=(256, 256), background=0, intensity=5, sigma=3, dtype='uint8', **kw)

DDM or c-DDM video generator.

Parameters

  • t1 (array-like) – Frame time

  • t2 (array-like, optional) – Second camera frame time, in case we are simulating dual camera video.

  • shape ((int,int)) – Frame shape

  • background (int) – Background frame value

  • intensity (int) – Peak Intensity of the particle.

  • sigma (float) – Sigma of the gaussian spread function for the particle

  • dtype (dtype) – Numpy dtype of frames, either uint8 or uint16

  • kw (extra arguments) – Extra keyward arguments that are passed to brownian_particles()

Yields

frames (tuple of ndarrays) – A single-frame or dual-frame images (ndarrays).

cddm.sim.adc(frame, saturation=32768, black_level=0, bit_depth='14bit', readout_noise=0.0, noise_model='gaussian', out=None)

Simulated ADC conversion process of ideal signal.

It applies shot noise with the standard deviation of the square of the provided signal and adds a readout_noise of the provided mean value and shot noise characteristics.

Parameters

  • frame (ndarray) – Input noisless signal

  • saturation (int) – Defines the saturation value of the sensor

  • black_level (int) – Defines black level subtraction value.

  • bit_depth (str) – ADC bit depth. Either ‘8bit’, ‘10bit’, ‘12bit’ or ‘14bit’. This defines what kind of scalling is performed when converting results to uint16 (or uint8) image.

  • readout_noise (float) – Value of the additional noise added to the frame.

  • noise_model (str) – Either ‘gaussian’ or ‘poisson’ or ‘none’ to disable noise

  • out (ndarray, optional) – Output array.

Returns

frame – Noissy image

Return type

ndarray