Debian Codegraph @

doc/intro/tutorials/fabry_perot.rst

raw
1 .. _tutorial_fabry_perot:
2
3 :octicon:`book;1em;sd-text-info` Measuring Fabry-Perot fringes
4 ==============================================================
5
6 .. meta::
7 :description: Tutorial on how to measure Fabry-Perot fringes using DataLab, the open-source scientific data analysis and visualization platform
8 :keywords: DataLab, fabry-perot, interferometer, fringe, image processing, contour detection, circle fitting, intensity profile, signal processing, metadata, annotations, workspace, hdf5
9
10 This example shows how to measure Fabry-Perot fringes using the image processing
11 features of DataLab:
12
13 - Load an image of a Fabry-Perot interferometer
14 - Define a circular region of interest (ROI) around the central fringe
15 - Detect contours in the ROI and fit them to circles
16 - Show the radius of the circles
17 - Annotate the image
18 - Copy/paste the ROI to another image
19 - Extract the intensity profile along the X axis
20 - Save the workspace
21
22 Load the images
23 ---------------
24
25 .. note::
26
27 The images used in this tutorial "fabry_perot1.jpg" and "fabry_perot2.jpg" are
28 available in the tutorial data folder of DataLab's installation directory
29 (``<DataLab installation directory>/data/tutorials/``).
30
31 .. only:: html
32
33 Alternatively, you can download them from :download:`here </_download/fabry_perot.zip>`
34 and extract to the folder of your choice.
35
36 .. only:: latex
37
38 Alternatively, they can be downloaded from the online documentation at
39 https://datalab-platform.com.
40
41
42 First, we open DataLab and load the images from the menu file "File > Open Image...",
43 with the |fileopen_ima| button in the toolbar or by dragging and dropping the files
44 into DataLab.
45
46 .. figure:: ../../images/tutorials/fabry_perot/01.png
47
48 Open the image files with "File > Open Image...", or with the |fileopen_ima| button in
49 the toolbar, or by dragging and dropping the files into DataLab (on the panel on
50 the right).
51
52 .. |fileopen_ima| image:: ../../../datalab/data/icons/io/fileopen_ima.svg
53 :width: 24px
54 :height: 24px
55 :class: dark-light no-scaled-link
56
57 .. figure:: ../../images/tutorials/fabry_perot/02.png
58
59 Go to the tutorial data folder in DataLab's installation directory (or the folder where you placed the images),
60 select "fabry_perot1.jpg" and "fabry_perot2.jpg" and click "Open".
61
62 The selected image is displayed in the main window. We can zoom in and out by pressing
63 the right mouse button and dragging the mouse up and down. We can also pan the image
64 by pressing the middle mouse button and dragging the mouse.
65
66 .. figure:: ../../images/tutorials/fabry_perot/03.png
67
68 Images loaded in DataLab. Zoom in and out with the right mouse button, pan the
69 image with the middle mouse button.
70
71 .. note::
72
73 When working on application-specific images (e.g. X-ray radiography images,
74 or optical microscopy images), it is often useful to change the colormap to
75 a grayscale colormap.
76 If you see a different image colormap than the one shown in the figure, you can
77 change it by selecting the image in the visualization panel, and the selecting
78 the colormap in the vertical toolbar on the left of the visualization panel.
79
80 Or, even better, you can change the default colormap in the DataLab settings
81 by selecting "Edit > Settings..." in the menu, or the |libre-gui-settings|
82 button in the toolbar.
83
84 .. figure:: ../../images/tutorials/fabry_perot/default_colormap.png
85
86 Select the "Visualization" tab, and select the "gray" colormap.
87
88 .. |libre-gui-settings| image:: ../../../datalab/data/icons/libre-gui-settings.svg
89 :width: 24px
90 :height: 24px
91 :class: dark-light no-scaled-link
92
93 Define circular ROIs and fit contours
94 --------------------------------------
95
96 Let's define a circular region of interest (ROI) around the central fringe.
97 To do that, we firstly select the first image in the "Images" panel
98 (if not already selected), then we select the "Edit graphically" tool in
99 the "ROI" menu.
100
101 .. figure:: ../../images/tutorials/fabry_perot/04.png
102
103 Select the "Edit graphically" tool in the "ROI" menu.
104
105 This opens the "Regions of interest" dialog, that provides all the tools to define and
106 edit ROIs. You can define ROIs graphically or via their coordinates.
107 You can define multiple ROIs on the same image, and even combine them using
108 boolean operations (union, intersection, difference).
109
110 .. figure:: ../../images/tutorials/fabry_perot/05a.png
111
112 The "Regions of interest" dialog opens. Click "Add ROI" and select
113 a circular ROI. Resize the predefined ROI by dragging the handles. Note that you
114 may change the ROI radius while keeping its center fixed by pressing the "Ctrl" key.
115 Click "OK" to close the dialog.
116
117 We choose to define a circular ROI graphically. To do that, we click on the "Graphical ROI"
118 button, and select the circular ROI option. We can now draw the circular ROI on the image
119 by clicking and dragging the mouse: the first click is on one side of the circle, and the
120 second click is on the opposite side of the circle.
121
122 .. figure:: ../../images/tutorials/fabry_perot/05b.png
123
124 The option to graphically define a circular ROI.
125
126 Once created, the ROI can be selected
127 using the "Selection" tool, and moved or resized by dragging the ROI or its handles.
128 In addition, you can change the ROI radius while keeping its center fixed by
129 pressing the "Ctrl" key while dragging a handle.
130
131 .. figure:: ../../images/tutorials/fabry_perot/05c.png
132
133 The circular ROI created appears in the image.
134
135 Once you are satisfied with the ROI position and size, click "OK" to close the dialog.
136 A confirmation dialog opens to ask you to apply the ROI to the image, and confirm
137 its parameters. Here you can also choose to invert the ROI mask (i.e., select the area
138 outside the ROI instead of the area inside the ROI): we do not want to invert the ROI
139 in this case, so we leave the "Invert ROI" checkbox unchecked, and click "OK". If you
140 want to obtain the exact results shown in this tutorial, make sure that the ROI parameters
141 are the same as in the figure.
142
143 .. figure:: ../../images/tutorials/fabry_perot/06.png
144
145 The confirmation dialog.
146
147 Once confirmed, the ROI is applied to the image. The ROI is displayed on the image,
148 and the part outside the ROI is dimmed. Note that, internally, the ROI is defined by a
149 binary mask, i.e., image data is represented as a NumPy masked array.
150
151 .. figure:: ../../images/tutorials/fabry_perot/07.png
152
153 The ROI displayed on the image.
154
155 Now, let's detect the contours in the area inside the ROI and fit them to circles. To
156 do that, we select the "Contour detection" tool in the "Analysis" menu. The contour
157 parameters dialog opens: we select the shape "Circle" and click "OK". Now you will see
158 a "Results" dialog opening, that displays the fitted circle parameters. Click "OK" to
159 close the dialog. The fitted circles are displayed on the image.
160
161 .. figure:: ../../images/tutorials/fabry_perot/08.png
162
163 The "Contour detection" tool in the "Analysis" menu.
164
165 .. figure:: ../../images/tutorials/fabry_perot/09.png
166
167 The "Contour" parameters dialog.
168
169 .. figure:: ../../images/tutorials/fabry_perot/10.png
170
171 The "Results" dialog.
172
173 .. figure:: ../../images/tutorials/fabry_perot/11.png
174
175 The fitted circles are displayed on the image.
176
177 .. note::
178
179 If you want to show the analysis results again, you can select the "Show Results"
180 |show_results| button in the "Analysis" menu, or the "Results" |show_results|
181 button, in the Analysis panel located below the image list:
182
183 .. image:: ../../images/tutorials/fabry_perot/12.png
184
185 .. |show_results| image:: ../../../datalab/data/icons/analysis/show_results.svg
186 :width: 24px
187 :height: 24px
188 :class: dark-light no-scaled-link
189
190 The images (or signals) can also be displayed in a separate window, by clicking on
191 the "View in a new window" entry in the "View" menu (or the |new_window| button in
192 the toolbar). This is useful to compare images or signals side by side, and allows
193 you to add annotations (cursors, labels, shapes, etc.) to the image or signal: the
194 annotations are stored in the metadata of the image or signal, and saved together
195 with the data when the workspace is saved.
196
197 .. |new_window| image:: ../../../datalab/data/icons/view/new_window.svg
198 :width: 24px
199 :height: 24px
200 :class: dark-light no-scaled-link
201
202 .. figure:: ../../images/tutorials/fabry_perot/13.png
203
204 The image displayed in a separate window. The ROI and the fitted circles are
205 also displayed. Annotations can be added to the image by clicking on the buttons
206 at the bottom of the window. The annotations are stored in the metadata of the
207 image, and saved together with the image data when the workspace is saved.
208 Click on "OK" to close the window.
209
210 .. figure:: ../../images/tutorials/fabry_perot/14.png
211
212 The image is displayed in the main window, together with the annotations.
213
214 If you want to take a closer look at the metadata, you can open the "Metadata" dialog.
215
216 .. figure:: ../../images/tutorials/fabry_perot/15.png
217
218 The "Metadata" button is located below the image list.
219
220 .. figure:: ../../images/tutorials/fabry_perot/16.png
221
222 The "Metadata" dialog opens. Among other information, it displays the annotations
223 (in a JSON format), some style information (e.g. the colormap), and the ROI.
224
225 Now, let's delete the image metadata (including the annotations) to clean up the image.
226 Select the "Delete object metadata..." entry in the "Edit" menu, or the |metadata_delete|
227 button in the toolbar, and answer "No" to the confirmation dialog to keep the ROI and
228 delete the rest of the metadata.
229
230 .. figure:: ../../images/tutorials/fabry_perot/17.png
231
232 Select the "Delete object metadata" entry in the "Edit" menu.
233
234 .. |metadata_delete| image:: ../../../datalab/data/icons/edit/metadata_delete.svg
235 :width: 24px
236 :height: 24px
237 :class: dark-light no-scaled-link
238
239 .. figure:: ../../images/tutorials/fabry_perot/18.png
240
241 The "Delete metadata" dialog. Click "No" to keep the ROI and delete the
242 rest of the metadata.
243
244 If we want to define the exact same ROI on the second image, we can copy/paste the
245 ROI from the first image to the second image. The best way to do that is to use
246 the copy/paste option present in the "ROI" menu, or the |roi_copy| and |roi_paste|
247 buttons in the toolbar: select the first image, then click on the "Copy" entry in
248 the "ROI" menu (or the |roi_copy| button in the toolbar), then select the second image,
249 and click on the "Paste ROI" entry in the "ROI" menu (or the |roi_paste| button in the
250 toolbar).
251
252 .. note::
253 Copying/pasting the metadata copies/pastes all the metadata, including the ROIs, but
254 this would have the side effect of also copying/pasting the rest of the metadata.
255
256 .. figure:: ../../images/tutorials/fabry_perot/19.png
257
258 The "Copy" entry in the "ROI" menu.
259
260 .. |roi_copy| image:: ../../../datalab/data/icons/roi/roi_copy.svg
261 :width: 24px
262 :height: 24px
263 :class: dark-light no-scaled-link
264
265 .. figure:: ../../images/tutorials/fabry_perot/20.png
266
267 The "Paste" entry in the "ROI" menu, or the |roi_paste| button in the toolbar.
268
269 .. |roi_paste| image:: ../../../datalab/data/icons/roi/roi_paste.svg
270 :width: 24px
271 :height: 24px
272 :class: dark-light no-scaled-link
273
274 .. figure:: ../../images/tutorials/fabry_perot/21.png
275
276 The ROI is added to the second image.
277
278 Select the "Contour detection" tool in the "Analysis" menu, with the same
279 parameters as before (shape "Circle"). On this image, there are two fringes,
280 so four circles are fitted. The "Results" dialog opens and displays the
281 fitted circle parameters. Click "OK".
282
283 .. figure:: ../../images/tutorials/fabry_perot/22.png
284
285 The "Results" dialog for the second image.
286
287
288 .. figure:: ../../images/tutorials/fabry_perot/23.png
289
290 The fitted circles are displayed on the image.
291
292
293 Extract intensity profiles along the X axis
294 -------------------------------------------
295
296 .. note::
297
298 For the sake of simplicity (and because we want to compare two methods of
299 extraction), we will extract the intensity profile along the X axis
300 at the center of the image. In a real application, you would probably want to
301 extract the **radial intensity profile** instead, which can be done using
302 the "Radial profile" entry in the "Analysis > Intensity profiles" menu: this
303 would be more relevant and straightforward to analyze Fabry-Perot fringes.
304
305 To extract the intensity profile along the X axis, we have two options:
306
307 - Either select the "Line profile..." entry |profile| in the
308 "Analysis > Intensity profiles" menu.
309
310 - Or activate the "Cross section" tool |cross_section| in the vertical toolbar
311 on the left of the visualization panel.
312
313 .. |profile| image:: ../../../datalab/data/icons/operations/profile.svg
314 :width: 24px
315 :height: 24px
316 :class: dark-light no-scaled-link
317
318 .. |cross_section| image:: ../../images/tutorials/csection.png
319
320 Let's try the first option: select the "Line profile..." entry |profile|.
321 This is the most straightforward way to extract a profile from an image, and it
322 corresponds to the ``calc("line_profile")`` computation feature of DataLab's API
323 (so it can be used in a script, a plugin or a macro). Select the "Line profile..."
324 entry |profile| in the "Operations" menu and the "Line profile" dialog will open, letting you
325 select the profile row (for a horizontal profile) or column (for a vertical profile)
326 on the image.
327 You can also enter the row/column number directly by clicking on "parameters..." in the
328 "Line profile" dialog.
329
330 .. figure:: ../../images/tutorials/fabry_perot/24.png
331
332 Select the "Line profile..." entry |profile| in the "Operations" menu.
333
334 .. figure:: ../../images/tutorials/fabry_perot/25.png
335
336 The "Profile" dialog opens. Enter the row of the horizontal profile
337 (or the column of the vertical profile) in the dialog box that opens. Click "OK".
338
339 After clicking "OK", the intensity profile along the X axis is computed and
340 displayed in the "Signals" panel. DataLab automatically switches to the "Signals"
341 panel to display the profile.
342
343 .. figure:: ../../images/tutorials/fabry_perot/26.png
344
345 The intensity profile is added to the "Signals" panel, and DataLab switches to
346 this panel to display the profile.
347
348 If you want to do some measurements on the profile, or add annotations, you can
349 open the signal in a separate window, by clicking on the "View in a new window"
350 entry in the "View" menu (or the |new_window| button in the toolbar).
351
352 .. figure:: ../../images/tutorials/fabry_perot/27.png
353
354 The signal is displayed in a separate window. Here, we added vertical cursors
355 and a text label. As for the images, the annotations are stored
356 in the metadata of the signal and saved together with the signal data when the workspace
357 is saved. Click on "OK" to close the window.
358
359 Now, let's try the second option for extracting the intensity profile along the X axis,
360 using the "Cross section" tool |cross_section| in the vertical toolbar on the
361 left of the visualization panel (this tool is a
362 `PlotPy <https://github.com/PlotPyStack/plotpy>`_ feature). Before being able to use
363 it, we need to select the image again in the visualization panel (otherwise the tool is
364 grayed out). Then, we can click on the image to display the intensity profiles along
365 the X and Y axes. DataLab integrates a modified version of this tool which allows you to
366 transfer the profile to the "Signals" panel for further processing. Select the
367 "Cross section" tool |cross_section| in the vertical toolbar and click on the image to
368 display the intensity profiles along the X and Y axes.
369
370 .. figure:: ../../images/tutorials/fabry_perot/28.png
371
372 The cross section tool in the view panel. In the red circle, the button to
373 activate it. In the blue circle, the button to transfer the profile to the
374 "Signals" panel.
375
376
377 Click on the "Process signal" button |to_signal| in the toolbar near the
378 profile to transfer the profile to the "Signals" panel. The intensity profile is added
379 to the "Signals" panel, and DataLab switches to this panel to display the profile.
380
381 .. |to_signal| image:: ../../../datalab/data/icons/to_signal.svg
382 :width: 24px
383 :height: 24px
384 :class: dark-light no-scaled-link
385
386
387 Save the workspace
388 ------------------
389
390 Finally, we can save the workspace to a file. The workspace contains all the images
391 and signals that were loaded or processed in DataLab. It also contains the analysis
392 results, the visualization settings (colormaps, contrast, etc.), the metadata, and
393 the annotations.
394
395 .. figure:: ../../images/tutorials/fabry_perot/30.png
396
397 Save the workspace to a file with "File > Save to HDF5 file...",
398 or the |filesave_h5| button in the toolbar.
399
400 .. |filesave_h5| image:: ../../../datalab/data/icons/io/filesave_h5.svg
401 :width: 24px
402 :height: 24px
403 :class: dark-light no-scaled-link
404
405 If you want to load the workspace again, you can use the "File > Open HDF5 file..."
406 (or the |fileopen_h5| button in the toolbar) to load the whole workspace, or the
407 "File > Browse HDF5 file..." (or the |h5browser| button in the toolbar) to load
408 only a selection of data sets from the workspace.
409
410 .. |fileopen_h5| image:: ../../../datalab/data/icons/io/fileopen_h5.svg
411 :width: 24px
412 :height: 24px
413 :class: dark-light no-scaled-link
414
415 .. |h5browser| image:: ../../../datalab/data/icons/h5/h5browser.svg
416 :width: 24px
417 :height: 24px
418 :class: dark-light no-scaled-link