# '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
# 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](https://en.wikipedia.org/wiki/Bell-shaped_function) 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:
```python
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:
```python
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:
.png "Shifted Normal Circle 1px R")
Shifted "Precise" Circle:
.png "Shifted Precise Circle 1px R")
### 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:
```python
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](https://numba.pydata.org/) 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).
````python
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
````
Raw data
{
"_id": null,
"home_page": null,
"name": "fluoscenepy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "fluorescent microscopic image simulaiton",
"author": "Sergei Klykov",
"author_email": "sergej.klykow@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1d/6c/0191a1980f3a756fd22fb7103effa4879c979e64b5df456cb1fd7f4cf701/fluoscenepy-0.0.1.tar.gz",
"platform": null,
"description": "# 'fluoscenepy' project\r\nThis project helps to simulate the microscopic images with the basic structures: beads and ellipses, calculated using various concepts. \r\nIf it sounds too ambitious, please, consider it only as the good intention to have such useful tool ready for various evaluations \r\n(e.g. for evaluation of image processing workflows), but not as the solid and proven approach, that has been published somewhere.\r\n\r\n### Ratio for project development\r\nEven though, there exist number of similar and much more advanced projects, which addresses the task of fluorescence microscopic image\r\nsimulations, and, moreover, the task of bead simulation seems to be trivial, nevertheless, I haven't seen the appropriate library\r\nfor the simulation of the precise bead (circle) projection on the pixels grid. The circle ('ball') with 1 pixel radius, not shifted\r\nfrom the center of pixel (exact coordinates like (1, 1) for the circle center) can be projected on the pixel grid \r\nin the following ways:\r\n\r\n1) \"Normal\" Circle. The 4 pixels (on 90 degree directions) on the borders are included because \r\nthe distance between them and the center of the circle is precisely 1 pixel and equal to the radius. \r\n \r\n![Normal Circle](./src/fluoscenepy/readme_images/Circle_rad_1px.png \"Normal Circle 1px R\") \r\n\r\n```python\r\n# Python code snippet\r\nfrom fluoscenepy import FluorObj\r\nflobj = FluorObj(typical_size=2.0, border_type=\"computed\", shape_method=\"circle\")\r\nflobj.get_shape(); flobj.plot_shape()\r\n```\r\n \r\n2) \"Oversampled\" Circle. All pixels within the circle border are included into the projection with the maximum \r\n(though normalized) intensity.\r\n\r\n![Oversampled Circle](./src/fluoscenepy/readme_images/Oversampled_Circle_rad_1px.png \"Oversampled Circle 1px R\") \r\n\r\nThe code snippet is the same as for the \"normal\" circle above, only the parameter should be set as: \r\n***shape_method=\"oversampled circle\"***.\r\n\r\n3) \"Undersampled\" Circle. Only pixels, that lay completely within the border, are included into the projection.\r\n\r\n![Undersampled Circle](./src/fluoscenepy/readme_images/Undersampled_Circle_rad_1px.png \"Undersampled Circle 1px R\") \r\n\r\nThe code snippet is the same as for the \"normal\" circle above, only the parameter should be set as: \r\n***shape_method=\"undersampled circle\"***. \r\n\r\nIntuitively, the problem can be solved either by calculation the area of intersection of each pixel with the circle\r\nborder, or by using some bell-shaped analytic function for the shape description \r\n([more information](https://en.wikipedia.org/wiki/Bell-shaped_function) on these functions). \r\nTo illustrate this, the following shapes could be plotted: \r\n1) The shape with calculated areas of the intersection of each pixel with the circular border (\"Precise\" Circle): \r\n\r\n![Precise Circle 2](./src/fluoscenepy/readme_images/Precise_bordered_circle_rad_1px.png \"Precise Circle 1px R\") \r\n\r\nThe normalized intensity values in the pixels, which intersect with the circular border, is calculated from the ratio\r\nof occupied area laying within the circular border, as on the following picture (the left center pixel): \r\n\r\n![Intersection](./src/fluoscenepy/readme_images/Intersection_Circle_rad_1px.png \"Precise Circle 1px R\") \r\n\r\n2) To illustrate better the effect of area intersections calculation, the shape of the bead with diameter of 4.8 pixels: \r\n\r\n![Precise Circle 4.8](./src/fluoscenepy/readme_images/Precise_bordered_circle_rad_4.8px.png \"Precise Circle 4.8px R\")\r\n```python\r\nfrom fluoscenepy import FluorObj\r\nflobj = FluorObj(typical_size=4.8); flobj.get_shape(); flobj.plot_shape()\r\n```\r\n\r\n3) The \"continuously\" shaped bead can be calculated using implemented in the ***FluorObj*** bell-shaped \r\nfunctions, e.g. gaussian, lorentzian, and so on (full list can be printed out by calling the\r\n***get_shaping_functions()*** method). Note that the calculation can be performed only for the parameter \r\nset as: ***border_type='computed'*** or ***border_type='co'***. For the illustration of the calculated\r\nshape: \r\n\r\n![Bump3 Circle 4.8](./src/fluoscenepy/readme_images/Bump3_computed_circle_rad_4.8px.png \"Bump3 Circle 4.8px R\")\r\n```python\r\nfrom fluoscenepy import FluorObj\r\nflobj = FluorObj(typical_size=4.8, border_type=\"co\", shape_method=\"bump3\")\r\nflobj.get_shape(); flobj.plot_shape()\r\n```\r\n\r\nThe problem of precise shape projection of the circle on the pixel grid becomes even more significant \r\nif 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)\r\ncircles. \r\nShifted \"Normal\" Circle: \r\n\r\n.png \"Shifted Normal Circle 1px R\")\r\n\r\nShifted \"Precise\" Circle: \r\n\r\n.png \"Shifted Precise Circle 1px R\") \r\n\r\n### Generation of a microscopic image (\"fluorescence scene\")\r\nIt can be achieved by placing circular of elliptical particles on the \"scene\". Check the API documentation for all \r\navailable methods for making it. \r\nOne of the straightforward way is just to use methods for generation of objects with random shapes, sizes, maximum intensities, and \r\nplaced randomly on the scene. The code example: \r\n```python\r\nfrom fluoscenepy import FluorObj, UscopeScene\r\nsamples = UscopeScene.get_random_objects(mean_size=(9.11, 6.56), size_std=(1.15, 0.82), \r\n shapes='mixed', intensity_range=(185, 252), \r\n n_objects=12, verbose_info=True)\r\nscene = UscopeScene(width=62, height=54)\r\nsamples_pl = scene.set_random_places(samples, overlapping=False, touching=False, \r\n only_within_scene=True, verbose_info=True)\r\n# Placing objects randomly on the scene, without noise\r\nscene.put_objects_on(samples_pl, save_only_objects_inside=True)\r\nscene.add_noise() # adding standard noise\r\n```\r\nFor comparison, generated scene without standard for CMOS cameras additional noise: \r\n\r\n![Scene w/t noise](./src/fluoscenepy/readme_images/Scene_without_noise_1.png \"Scene without Noise\")\r\n\r\nGenerated scene with additional noise calculated with default method parameters: \r\n\r\n![Scene w/t noise](./src/fluoscenepy/readme_images/Scene_with_noise_1.png \"Scene without Noise\")\r\n\r\n### Performance of calculations\r\nNote that even single 'precise' shaped round object (bead) generation can take around 2 seconds for the diameter 12 pixels\r\nbecause of the slow nested for loops for calculating each pixel which is partially within the circle border. \r\nTo speed up the calculations, one can install the [numba](https://numba.pydata.org/) library in the same Python environment\r\nand provide the according flags in calculation methods, similar to the following code snippets. \r\n**PLEASE NOTE:** it has been revealed during tests that the required ***numba*** version should be **>=0.57.1** \r\n(tested and verified for versions: 0.57.1 and 0.60.0).\r\n````python\r\nimport numpy as np\r\nfrom fluoscenepy import FluorObj, force_precompilation\r\nforce_precompilation() # force pre-compilation of computational functions by numba\r\n# Round shape object generation\r\nr_obj_acc = FluorObj(typical_size=12.0)\r\nr_obj_acc.get_shape(accelerated=True) # takes ~ 0.7 - 1 sec \r\nr_obj = FluorObj(typical_size=12.0)\r\nr_obj.get_shape() # takes ~ 2.3 - 2.7 sec \r\n# Ellipse shape object generation\r\nel_obj_acc = FluorObj(shape_type='ellipse', typical_size=(7.5, 6.0, np.pi/3))\r\nel_obj_acc.get_shape(accelerated=True) # takes ~ 1.1 - 1.8 sec \r\nel_obj = FluorObj(shape_type='ellipse', typical_size=(7.5, 6.0, np.pi/3))\r\nel_obj.get_shape() # takes ~ 3.6 - 5.7 sec \r\n````\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simulation of a microscopic image with round (beads) and elongated fluorescent objects",
"version": "0.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/sklykov/fluoscenepy/issues/",
"Changelog": "https://github.com/sklykov/fluoscenepy/blob/main/CHANGELOG.md",
"Documentation": "https://sklykov.github.io/fluoscenepy/api_doc/fluoscenepy/fluoscene.html",
"Homepage": "https://sklykov.github.io/fluoscenepy/",
"Repository": "https://github.com/sklykov/fluoscenepy/"
},
"split_keywords": [
"fluorescent",
"microscopic",
"image",
"simulaiton"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a6a070b30aab3ada911534b50f25bde85e256d7e1d629608516760b0a23e02a1",
"md5": "1452cda28fc6a249cc310cceb51536ef",
"sha256": "a2aacd48bd4acadadbdebaee08371db5cfd153986728dd4dd3cf5ca7992027e8"
},
"downloads": -1,
"filename": "fluoscenepy-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1452cda28fc6a249cc310cceb51536ef",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 190743,
"upload_time": "2024-09-20T19:56:02",
"upload_time_iso_8601": "2024-09-20T19:56:02.531493Z",
"url": "https://files.pythonhosted.org/packages/a6/a0/70b30aab3ada911534b50f25bde85e256d7e1d629608516760b0a23e02a1/fluoscenepy-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1d6c0191a1980f3a756fd22fb7103effa4879c979e64b5df456cb1fd7f4cf701",
"md5": "5c5724e25b0dc1a0430a55871aefa165",
"sha256": "a1f9f92788d126954b3658dc3a9837b47d1ffa92b53289e97f23219d0ab5e86b"
},
"downloads": -1,
"filename": "fluoscenepy-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "5c5724e25b0dc1a0430a55871aefa165",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 189700,
"upload_time": "2024-09-20T19:56:04",
"upload_time_iso_8601": "2024-09-20T19:56:04.316119Z",
"url": "https://files.pythonhosted.org/packages/1d/6c/0191a1980f3a756fd22fb7103effa4879c979e64b5df456cb1fd7f4cf701/fluoscenepy-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-20 19:56:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sklykov",
"github_project": "fluoscenepy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "fluoscenepy"
}
JSON
