'fluoscenepy' project

This project helps to simulate the microscopic images with the basic structures: beads and ellipses, calculated using various concepts. If it sounds too ambitious, please, consider it only as the good intention to have such useful tool ready for various evaluations (e.g. for evaluation of image processing workflows), but not as the solid and proven approach, that has been published somewhere.

Ratio for project development

Even though, there exist number of similar and much more advanced projects, which addresses the task of fluorescence microscopic image simulations, and, moreover, the task of bead simulation seems to be trivial, nevertheless, I haven't seen the appropriate library for the simulation of the precise bead (circle) projection on the pixels grid. The circle ('ball') with 1 pixel radius, not shifted from the center of pixel (exact coordinates like (1, 1) for the circle center) can be projected on the pixel grid in the following ways:

1. "Normal" Circle. The 4 pixels (on 90 degree directions) on the borders are included because the distance between them and the center of the circle is precisely 1 pixel and equal to the radius.

# Python code snippet
from fluoscenepy import FluorObj
flobj = FluorObj(typical_size=2.0, border_type="computed", shape_method="circle")
flobj.get_shape(); flobj.plot_shape()

2. "Oversampled" Circle. All pixels within the circle border are included into the projection with the maximum (though normalized) intensity.

The code snippet is the same as for the "normal" circle above, only the parameter should be set as: shape_method="oversampled circle".

3. "Undersampled" Circle. Only pixels, that lay completely within the border, are included into the projection.

The code snippet is the same as for the "normal" circle above, only the parameter should be set as: shape_method="undersampled circle".

Intuitively, the problem can be solved either by calculation the area of intersection of each pixel with the circle border, or by using some bell-shaped analytic function for the shape description (more information on these functions).
To illustrate this, the following shapes could be plotted:

1. The shape with calculated areas of the intersection of each pixel with the circular border ("Precise" Circle):

The normalized intensity values in the pixels, which intersect with the circular border, is calculated from the ratio of occupied area laying within the circular border, as on the following picture (the left center pixel):

2. To illustrate better the effect of area intersections calculation, the shape of the bead with diameter of 4.8 pixels:

from fluoscenepy import FluorObj
flobj = FluorObj(typical_size=4.8); flobj.get_shape(); flobj.plot_shape()

3. The "continuously" shaped bead can be calculated using implemented in the FluorObj bell-shaped functions, e.g. gaussian, lorentzian, and so on (full list can be printed out by calling the get_shaping_functions() method). Note that the calculation can be performed only for the parameter set as: border_type='computed' or border_type='co'. For the illustration of the calculated shape:

from fluoscenepy import FluorObj
flobj = FluorObj(typical_size=4.8, border_type="co", shape_method="bump3")
flobj.get_shape(); flobj.plot_shape()

The problem of precise shape projection of the circle on the pixel grid becomes even more significant if its center is shifted from the origin of the pixel. To illustrate this, below are a few examples of the shifted by (0.24, 0.0) circles.
Shifted "Normal" Circle:

Shifted "Precise" Circle:

Generation of a microscopic image ("fluorescence scene")

It can be achieved by placing circular of elliptical particles on the "scene". Check the API documentation for all available methods for making it. One of the straightforward way is just to use methods for generation of objects with random shapes, sizes, maximum intensities, and placed randomly on the scene. The code example:

from fluoscenepy import FluorObj, UscopeScene
samples = UscopeScene.get_random_objects(mean_size=(9.11, 6.56), size_std=(1.15, 0.82), 
                                         shapes='mixed', intensity_range=(185, 252), 
                                         n_objects=12, verbose_info=True)
scene = UscopeScene(width=62, height=54)
samples_pl = scene.set_random_places(samples, overlapping=False, touching=False, 
                                     only_within_scene=True, verbose_info=True)
# Placing objects randomly on the scene, without noise
scene.put_objects_on(samples_pl, save_only_objects_inside=True)
scene.add_noise()  # adding standard noise

For comparison, generated scene without standard for CMOS cameras additional noise:

Generated scene with additional noise calculated with default method parameters:

Performance of calculations

Note that even single 'precise' shaped round object (bead) generation can take around 2 seconds for the diameter 12 pixels because of the slow nested for loops for calculating each pixel which is partially within the circle border.
To speed up the calculations, one can install the numba library in the same Python environment and provide the according flags in calculation methods, similar to the following code snippets.
PLEASE NOTE: it has been revealed during tests that the required numba version should be >=0.57.1 (tested and verified for versions: 0.57.1 and 0.60.0).

import numpy as np
from fluoscenepy import FluorObj, force_precompilation
force_precompilation()   # force pre-compilation of computational functions by numba
# Round shape object generation
r_obj_acc = FluorObj(typical_size=12.0)
r_obj_acc.get_shape(accelerated=True)  # takes ~ 0.7 - 1 sec 
r_obj = FluorObj(typical_size=12.0)
r_obj.get_shape()  # takes ~ 2.3 - 2.7 sec 
# Ellipse shape object generation
el_obj_acc = FluorObj(shape_type='ellipse', typical_size=(7.5, 6.0, np.pi/3))
el_obj_acc.get_shape(accelerated=True)  # takes ~ 1.1 - 1.8 sec 
el_obj = FluorObj(shape_type='ellipse', typical_size=(7.5, 6.0, np.pi/3))
el_obj.get_shape()  # takes ~ 3.6 - 5.7 sec 

Acceleration of objects generation and placing

The objects with randomly selected shape type, sizes, center pixel shifts and orientation in the case of ellipse can be generated by using class instance bound method:

import numpy as np
from fluoscenepy import FluorObj, UscopeScene
uscene = UscopeScene(width=320, height=280, image_type=np.uint16)  # creating the scene
# Pixel and intensity ranges for random selection the parameters from
obj_mean_sizes = (16, 12); obj_sizes_std = (5, 3.5); obj_intensities = (28000, 42000)
# Instance bound compiled by numba library generation method with verbose printouts about calculation progress
fl_objs = uscene.get_objects_acc(mean_size=obj_mean_sizes, size_std=obj_sizes_std, shapes='mixed', 
                                  intensity_range=obj_intensities, image_type=uscene.img_type, 
                                  n_objects=25, verbose_info=True)
# Distribute the generated objects according to the provided flags (hopefully, with self-explanatory meaning).
# Note that acceleration by numba compilation will be automatically applied for below method if the library 'numba'
# has been installed. Recommended version for numba is >= 0.57.1
placed_objs = uscene.set_random_places(fl_objs, overlapping=False, touching=False, 
                                       only_within_scene=True, verbose_info=True)
uscene.put_objects_on(placed_objs, save_only_objects_inside=True); uscene.show_scene()

Please note that the performance is limited still by two factors:

1. It's required by the function call to calculate precise distribution of object profile intensity over the pixel grid.
   Especially in the case of object with elliptic shape, it can take up to several dozens of seconds for a single object generation.
2. For the placing algorithms, if the flags 'overlapping' and 'touching' are False, then the algorithm checks during random placing of objects on the scene for event of two objects overlapping and touching. So, it is implemented as the pixelwise checks that in the case of relatively big objects in the sizes, may take long time (up to minutes for a single object placement).