Debian Codegraph @

doc/intro/tutorials/blobs.rst

raw
1 .. _tutorial_blobs:
2
3 :octicon:`book;1em;sd-text-info` Detecting blobs on an image
4 ============================================================
5
6 This example shows how to detect blobs on an image with DataLab,
7 and also covers other features such as the plugin system:
8
9 - Add a new plugin to DataLab
10 - Denoise an image
11 - Detect blobs on an image
12 - Save the workspace to a file
13
14 First, we open DataLab, and open the settings dialog (using "File > Settings...",
15 or the |libre-gui-settings| icon in the toolbar).
16
17 .. |libre-gui-settings| image:: ../../../datalab/data/icons/libre-gui-settings.svg
18 :width: 24px
19 :height: 24px
20 :class: dark-light no-scaled-link
21
22 .. figure:: ../../images/tutorials/blobs/01.png
23
24 In the "General" tab, we can see the "Plugins path" field. This is the path where
25 DataLab will look for plugins. We can add a new plugin by copying/pasting the
26 plugin file in this directory.
27
28 .. seealso::
29
30 The plugin system is described in the :ref:`about_plugins` section.
31
32 Let's add the `datalab_example_imageproc.py` plugin to DataLab (this is an example
33 plugin that is shipped with DataLab source package, or may be downloaded from
34 `here <https://github.com/DataLab-Platform/DataLab/tree/main/plugins/examples>`_).
35
36 If we close and reopen DataLab, we can see that the plugin is now available in the
37 "Plugins" menu: there is a new "Extract blobs (example)" entry.
38
39 .. figure:: ../../images/tutorials/blobs/02.png
40
41 The "About DataLab" dialog shows the list of available plugins.
42
43 .. figure:: ../../images/tutorials/blobs/03.png
44
45 Let's click on "Extract blobs (example) > Generate test image"
46
47 .. note:: DataLab menus change between images and signals. To be able to see the
48 "Extract blobs (example)" menu, make sure that the "Images" panel is selected
49 (click on the "Images" tab on the left).
50
51 A pop-up dialog appears, asking for the parameters of the test image to generate
52 (the size of the image and its title).
53 We can just keep the default parameters and click on "OK".
54
55 For information, the image is generated by the plugin using the following code::
56
57 def generate_test_image(self) -> None:
58 """Generate test image"""
59 newparam = self.edit_new_image_parameters(
60 title="Test image", hide_dtype=True, shape=(2048, 2048)
61 )
62 if newparam is not None:
63 # Create a NumPy array:
64 shape = (newparam.height, newparam.width)
65 arr = np.random.normal(10000, 1000, shape)
66 for _ in range(10):
67 row = np.random.randint(0, shape[0])
68 col = np.random.randint(0, shape[1])
69 rr, cc = skimage.draw.disk((row, col), min(shape) // 50, shape=shape)
70 arr[rr, cc] -= np.random.randint(5000, 6000)
71 center = (shape[0] // 2,) * 2
72 rr, cc = skimage.draw.disk(center, min(shape) // 10, shape=shape)
73 arr[rr, cc] -= np.random.randint(5000, 8000)
74 data = np.clip(arr, 0, 65535).astype(np.uint16)
75
76 # Create a new image object and add it to the image panel
77 obj = sigima.objects.create_image(
78 newparam.title, data, units=("mm", "mm", "lsb")
79 )
80 self.proxy.add_object(obj)
81
82 .. figure:: ../../images/tutorials/blobs/04.png
83
84 The plugin has generated a test image, and added it to the "Images" panel. The
85 image shows a few blobs, with a central bigger disk, and a noisy background.
86
87 The plugin has other features, such as denoising the image, and detecting blobs on
88 the image, but we won't cover them here: we will instead use the DataLab native features
89 to achieve, manually, the same operations as the plugin.
90
91 The image is a bit noisy, and also quite large. In addition, the blobs are large
92 with respect to the pixel size.
93
94 To reduce the noise there are several functions available in DataLab. Due to the
95 considerations we just made, we can consider that a binning would reduce the noise
96 without losing the information we look for. Let's apply a binning to the image by a
97 factor of 2 on both axes.
98 This will reduce the image size by a factor of 4, and the noise standard deviation
99 by a factor of 2. Choosing to change the pixel size accordingly
100 will keep the blob size constant in the previous unit (in this case, pixels,
101 but in a real application we can calibrate them to respect a real physical size).
102
103 .. figure:: ../../images/tutorials/blobs/05.png
104
105 Click on "Operations > Pixel binning".
106
107 .. figure:: ../../images/tutorials/blobs/06.png
108
109 The "Binning" dialog opens, with several options. Set the binning factor to 2 for
110 both axes, select the "change pixel size" case and click on "OK".
111
112 .. figure:: ../../images/tutorials/blobs/07.png
113
114 The binned image is added to the "Images" panel.
115 It is now easier to see the blobs (even if they were already quite visible on
116 the original image: this is just an example), and the image will be faster to
117 process.
118
119 A different approach we can take is to apply a moving median filter, to reduce the
120 importance of the spikes. We do it with a window of 5; of course in practice different
121 window sizes can be tested to find a good compromise between noise reduction and
122 resolution. Let's see how to do that.
123
124 .. figure:: ../../images/tutorials/blobs/08.png
125
126 Click on "Processing > Noise reduction > Moving median" entry,
127 and set the window size to ``5``.
128
129 .. figure:: ../../images/tutorials/blobs/09.png
130
131 The filtered image is added to the "Images" panel. Denoising is quite efficient.
132
133 Now, we can be satisfied with our denoising: it is visible that the noise is smaller.
134 We can thus move to the following step: detect the blobs on the image.
135 To do that, we can use the "Blob detection" function available in the
136 "Analysis" menu. Different :ref:`algorithms <ima-blob-detection>` are available,
137 here we will use the OpenCV one.
138
139 .. figure:: ../../images/tutorials/blobs/10.png
140
141 Click on "Analysis > Blob detection > Blob detection (OpenCV)".
142
143 .. figure:: ../../images/tutorials/blobs/11.png
144
145 The "Blob detection (OpenCV)" dialog opens. Set the parameters as shown on the
146 screenshot, and click on "OK".
147
148 .. figure:: ../../images/tutorials/blobs/12.png
149
150 The "Results" dialog opens, showing the detected blobs: one line per blob, with
151 the blob coordinates and radius.
152
153 .. note::
154
155 If you want to show the analysis results again, you can select the "Show results"
156 |show_results| entry in the "Analysis" menu, or the "Results" |show_results|
157 button, in the property panel below the image list:
158
159 .. image:: ../../images/tutorials/fabry_perot/12.png
160
161 .. |show_results| image:: ../../../datalab/data/icons/analysis/show_results.svg
162 :width: 24px
163 :height: 24px
164 :class: dark-light no-scaled-link
165
166 .. figure:: ../../images/tutorials/blobs/13.png
167
168 The detected blobs are also added to the image metadata, and can be seen in the
169 visualization panel on the right.
170
171 Finally, we can save the workspace to a file. The workspace contains all the images
172 that were loaded in DataLab, as well as the processing results. It also contains the
173 visualization settings (colormaps, contrast, etc.), the metadata, and the annotations.
174 To save the workspace, click on "File > Save to HDF5 file...", or the |filesave_h5|
175 button in the toolbar.
176
177 .. |filesave_h5| image:: ../../../datalab/data/icons/io/filesave_h5.svg
178 :width: 24px
179 :height: 24px
180 :class: dark-light no-scaled-link
181
182 If you want to load the workspace again, you can use the "File > Open HDF5 file..."
183 (or the |fileopen_h5| button in the toolbar) to load the whole workspace, or the
184 "File > Browse HDF5 file..." (or the |h5browser| button in the toolbar) to load
185 only a selection of data sets from the workspace.
186
187 .. |fileopen_h5| image:: ../../../datalab/data/icons/io/fileopen_h5.svg
188 :width: 24px
189 :height: 24px
190 :class: dark-light no-scaled-link
191
192 .. |h5browser| image:: ../../../datalab/data/icons/h5/h5browser.svg
193 :width: 24px
194 :height: 24px
195 :class: dark-light no-scaled-link