-
Notifications
You must be signed in to change notification settings - Fork 3
/
help.html
414 lines (394 loc) · 18.5 KB
/
help.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
<!--
Magic2 (https://github.com/jdranczewski/Magic2)
Copyright (C) 2018 Jakub Dranczewski, based on work by George Swadling
This work was carried out during a UROP with the MAGPIE Group,
Department of Physics, Imperial College London and was supported in part
by the Engineering and Physical Sciences Research Council (EPSRC) Grant
No. EP/N013379/1, by the U.S. Department of Energy (DOE) Awards
No. DE-F03-02NA00057 and No. DE-SC- 0001063
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
-->
<html>
<head>
<title>Magic2 manual</title>
<style>
html, body {
background-color: #5709a4;
background: linear-gradient(140deg, #5709a4, #c84579 35%, #f3cd22);
font-family: Arial;
}
#main {
max-width: 700px;
margin: 0 auto;
background-color: white;
margin-top: 100px;
padding: 25px;
border-radius: 3px;
box-shadow: #00000094 0 0 4px;
}
h1 {
font-size: 3em;
}
h2 {
color: #0D47A1;
}
h3 {
color: #1976D2;
}
</style>
</head>
<body>
<div id="main">
<h1><img src="logo_s.png" style="width: 8em;vertical-align: bottom;"/> - the manual</h1>
<div id="contents">
<h2>Table of contents</h2>
<ul>
<li><a href="#h2_introduction">Introduction</a></li>
<li><a href="#h2_basics">Basics of the interface</a></li>
<li><a href="#h2_fringes">Working with traced interferograms</a></li>
<li><a href="#h2_interpolation">Interpolation</a></li>
<li><a href="#h2_subtract_plasma">Subtraction and plasma density calculation</a></li>
<li><a href="#h2_export">Exporting</a></li>
<li><a href="#h2_lineouts">Taking lineouts</a></li>
<li><a href="#h2_other_operations">Other operations</a></li>
<li><a href="#h2_saving">.m2 - Magic2's very own file format</a></li>
<li><a href="#h2_references">References</a></li>
</ul>
</div>
<h2 id="h2_introduction">Introduction</h2>
<p>
Welcome to Magic2, the successor to Magic. The software has been written by
Jakub Dranczewski during his UROP in 2018. It's main purpose is to create plasma
density maps based on traced out interferograms.
</p>
<h2 id="h2_basics">Basics of the interface</h2>
<h3 id="h3_graphing_area">The graphing area</h3>
<p>
The main element of Magic2 is the graphing area which takes up most of the
screen. The output of all functions will be displayed here, it also allows
interactivity in certain modes.
</p>
<p>
The graphing area has a toolbar at the bottom, which allows you to go back to
the original view, go backwards and forwards in view history, as well as zoom to
rectangle or pan the graph. You can also drag with your right mouse button while
panning in order to zoom in and out.
</p>
<p>
Note that the toolbar's save button differs from Magic2's <a
href="#h3_saving_figures">File -> Save the graph as an image</a> option - it
does not ask for the resolution at which the image should be saved.
</p>
<p>
You can also use most of <a
href="https://matplotlib.org/users/navigation_toolbar.html#navigation-keyboard-shortcuts"
target=_blank>matplotlib's standard keyboard shortcuts</a>, apart from 'c', 's',
and 'backspace', which are either assigned to other things, or too easy to click
while doing other things.
<h3 id="h3_sidebar">The sidebar</h3>
<p>
The sidebar consists of two sections. The top one (Display) can be used to
change what is currently displayed in the <a href="#h3_graphing_area">graphing
area</a>. Clicking any of the options shows the corresponding graph, or
attempts to obtain it (while asking the user for permission). For example, if
no file is open, clicking "Background fringes" will result in a dialog allowing
for choosing a file to open and display. Right-clicking the options allows for
recalculating them (for example right-clicking the "Subtracted map" will
recalculate the subtracted map). There are also two buttons for changing the
thickness of the fringe rendering.
</p>
<p>
The bottom section allows for changing the fringe <a href="#h3_labelling">
labelling mode</a>, so that the phase goes up, down, or stays constant.
The fringes can also be unlabelled.
</p>
<p>
There is a convenient list of keyboard shortcuts at the bottom of the sidebar.
</p>
<h3 id="h3_menu">The menu</h3>
<p>
The menu contains some additional options you may want to use, although <a
href="#h3_sidebar">the sidebar</a> can be used to go through pretty much the
whole fringe loading, labelling, interpolating and subtracting process. The
options that can be found in the menus will be discussed in different section
below.
</p>
<h2 id="h2_fringes">Working with traced interferograms</h2>
<h3 id="h3_interferogram_structure">Structure of the files</h3>
<p>
The files for the background and plasma shot interferograms should be .png files
of the same resolution. The fringes are indicated with black pixels. A mask can
be applied by painting grey pixels on the images.
</p>
<h3 id="h3_opening_fringes">Opening fringe images</h3>
<p>
You can open a fringe image either by using the File menu, or by clicking the
corresponding option in <a href="#h3_sidebar">the sidebar</a>. A dialog will
open, prompting you to choose a .png file. It will then be processed, and the
fringes will be displayed in <a href="#h3_graphing_area">the graphing area</a>.
</p>
<h3 id="h3_project_name">Project name</h3>
<p>
A name for the project will be automatically extracted from the filename of the
.png you opened by cutting off the last word. You can see the result on the left
side of <a href="#h3_sidebar">the sidebar</a>. You can also change the project
name in the File <a href="#h3_menu">menu</a>.
</p>
<p>
The project name is used as a name template when <a href="#h3_data_export">
exporting the data</a> or <a href="#h2_saving">saving .m2 files</a>.
</p>
<h3 id="h3_labelling">Labelling fringes</h3>
<p>
Once a fringe image is open, you can label the fringes to indicate the phase
associated with them. You can do it by clicking anywhere within <a
href="#h3_graphing_area">the graphing area</a> while holding down the
<b>control (Ctrl)</b> key on your keyboard. This will start a line. You can add
points to this line by further control+clicking. To confirm, right click within
<a href="#h3_graphing_area">the graphing area</a> while holding down control.
This will go through all the fringes your line has crossed. It will take the
phase of the first one, and depending on the setting in <a
href="#h3_sidebar">the sidebar</a> assign a higher, lower, or constant phase to
all the subsequent fringes the line has encountered.
</p>
<p>
Unlabelled fringes will be shown as black and ignored while
<a href="#h2_interpolation">interpolating</a>.
</p>
<h2 id="h2_interpolation">Interpolation</h2>
<h3 id="h3_interpolation_idea">The idea of interpolation</h3>
<p>
Once all the fringes are labelled, we need to find phase values in the empty
spaces between them. This is what interpolation is used for. There are two
interpolation methods in Magic2. They can be invoked by choosing an option from
<a href="#h3_menu">the menu</a> or by clicking a map option in <a
href="#h3_sidebar">the sidebar</a>. There is also a debug mode, which displays
the output of all stages of the interpolation. It can be invoked from <a
href="#h3_menu">the menu</a> and has a lengthy warning message that explains its
functionality.
</p>
<h3 id="h3_fast_interpolation">Fast interpolation</h3>
<p>
The fast interpolation method can be used on simple interferograms or to check
whether your fringe labelling is going in the right direction. It is quicker,
but does not account for flat triangles in the triangulation of the
interferogram, meaning that it can produce non-physical artefacts in the output
and should be used mostly for reference.
</p>
<h3 id="h3_exact_interpolation">Exact interpolation</h3>
<p>
The exact interpolation method is a custom one written for this software and
based on the work George Swadling has done with Magic, as well as <a
href="https://doi.org/10.1016/S0098-3004(97)00088-5" target=_blank>this
paper</a>.
</p>
<p>
The method's advantage is that it removes invalid flat triangles from the
triangulation that is used to interpolate the phase. This takes more time,
but is often worth it, as it represents complicated features of the
interferograms much better.
</p>
<h2 id="h2_subtract_plasma">Subtraction and plasma density calculation</h2>
<h3 id="h3_subtraction">Performing the subtraction</h3>
<p>
To perform a subtraction of the plasma and background you can either click the
"Subtracted map" option in <a href="#h3_sidebar">the sidebar</a> (or right-click
it if you want to recompute), or use the <b>Process -> Subtract</b> option in <a
href="#h3_menu">the menu</a>.
</p>
<h3 id="h3_zero_shift">Setting the zero fringe shift point</h3>
<p>
If you would like to adjust the zero fringe shift point, use the <b>Process -> Set
zero shift point</b> option. This will allow you to either automatically select
this point as the one that has the lowest fringe shift value, or to input a
value manually.
</p>
<h3 id="h3_plasma_density">Calculating the plasma density</h3>
<p>
To calculate the plasma density based on the subtracted map, you can either
click the "Plasma density" option in <a href="#h3_sidebar">the sidebar</a> (or
right-click it if you want to recompute), or use the <b>Process -> Calculate
plasma density</b> option in <a href="#h3_menu">the menu</a>.
</p>
<p>
If you have not done so before, Magic2 will ask you to specify the shot
details. Those are the resolution of the interferogram, depth of the object,
wavelength of the laser, and whether the interferograms were traced 'doubly'
(meaning that a distance between two traced lines represents half a fringe
shift). You can always set those options by going to <b>Process -> Set shot
details</b>.
</p>
<h3 id="h3_set_centre">Set the centre of the map</h3>
<p>
By using the <b>Process -> Set centre of the density map</b> option in <a
href="h3_menu">the menu</a> it is possible to set an arbitrary [0, 0] point for
the plasma density map. In the dialog window that pops up, pressing 'Yes' will
allow you to click anywhere on the map (press the escape key to cancel the
operation) and pressing 'No' will reset the centre to the original position.
<h2 id="h2_export">Exporting</a>
<h3 id="h2_data_export">Exporting data</h3>
<p>
You can export the data you are currently viewing in the <a
href="#h3_graphing_area">graphing area</a> at any point by using the <b>"Export
the current view's data"</b> option in the File <a href="#h3_menu">menu</a>.
This will give you an option to choose the desired file location and name. The
default format is .csv. The areas that are masked out (or not interpolated) are
indicated with the string 'nan'.
</p>
<h3 id="h3_saving_figures">Saving figures</h3>
<p>
You can save the graph you are currently viewing by using the "Save the
graph as an image" option in the File <a href="#h3_menu">menu</a>. A prompt will
come up asking you to put in a dpi, effectively setting the images resolution.
You can then choose a location for your file.
</p>
<h2 id="h2_lineouts">Taking lineouts</h2>
<h3 id="h3_drawing_lineout">Drawing a lineout</h3>
<p>
To initialise drawing a lineout you can either use the <b>'Take lineout'</b>
button on the bottom of <a href="#h3_sidebar">the sidebar</a>, or use the
<b>Process -> Take lineout</b> option in <a href="#h3_menu">the menu</a>. This
should work in any display mode. Your cursor will turn into a crosshair. You can
draw the line by clicking the starting and ending points. A new window will
appear, containing the lineout graph and several other options.
</p>
<h3 id="h3_lineout_export">Exporting a lineout</h3>
<p>
This works very similarly to <a href="#h2_data_export">exporting the data
displayed in the graphing area</a> and can be done by pressing a button in the
layout window. The .csv file that is created will contain a
header with the starting and ending points and the display mode specified. The
header also specifies the units that have to be used when analysing the data.
</p>
<h3 id="h3_lineout_width">Width of the lineout</h3>
<p>
By using the input box at the bottom of the layout window, the width of the line
sampled to create the layout can be set. This will be represented by a
semi-transparent rectangle displayed in <a href="#h3_graphing_area">the graphing
area</a>. The rectangle can be turned off with a switch in the layout window.
<h3 id="h3_lineout_colour">The lineout's colour</h3>
<p>
You can set the colour of the lineout at the bottom of the lineout window. This
will change the colour of the lineout line, as well as the lineout graph, making
them easier to colour-code and associate with each other.
</p>
<p>
The colours available are the standard matplotlib colours (the ones it cycles
through when plotting multiple things).
</p>
<h3 id="h3_lineout_lifecycle">The lifecycle of a layout</h3>
<p>
When a layout is created in a particular display mode, it is attached to that
mode. This is indicated by the title of the lineout window (eg. 'plasma map
lineout'). It will show as a solid line only in that mode, turning into a
dashed, semi-transparent line in other modes.
</p>
<p>
The lineout will exist until you close its respective window. It should survive
pretty much any operation you perform on your data.
</p>
<h3 id="#h3_redraw_lineout">Redraw lineout in current mode</h3>
<p>
The <b>'Redraw in current mode'</b> button at the bottom of the lineout window creates
a new lineout of the same width, colour and position as the old one, but changes
the source of data (and the display mode that the lineout is attached to) to the
data currently being displayed.
</p>
<p>
For example, if you create a lineout in the 'Background map' display mode, you
can inspect the plasma map data along the same line by going to switching to the
'Plasma map' mode and clicking the 'Redraw in current mode' button. This will
delete the original layout.
</p>
<h3 id="h3_lineout_pin">Pinning the lineout window</h3>
<p>
The <b>(Un)pin this window</b> button in a layout window allows you to choose
whether you want the window to be attached (<i>modal</i>) to Magic2's main
window or not. When modal, the window doesn't show in your system's taskbar, and
is always displayed on top of the main Magic2 window, minimising itself when you
minimise Magic2 etc.
</p>
<h2 id="h2_other_operations">Other operations</h2>
<h3 id="h3_invert">Invert</h3>
<p>
<b>Process -> Invert</b> inverts the data in the current view. This does not work
with fringes, only the interpolated maps (including subtracted and plasma
density maps).
</p>
<h3 id="h3_cosine">Cosine</h3>
<p>
<b>Process -> Cosine</b> takes the cosine of the current interpolated phase
view. This can be then compared to the initial interferogram used for tracing.
</p>
<p>
The process takes into account the 'double' setting in <a
href="#h3_plasma_density"> the shot options</a>.
</p>
<h2 id="h2_saving">.m2 - Magic2's very own file format</h2>
<p>
.m2 files are envisioned as a simple way to exchange labelled interferograms in
a small file (usually around 200KB). You can send an .m2 file to someone, and
they will be able to open it and get exactly the same data you are working on.
</p>
<h3 id="h3_whats_in_m2">What's in an .m2 file?</h3>
<p>
The file contains two Boolean arrays for both background and plasma
interferograms (one for the fringes and one for the user-defined mask), together
with the fringes' phases. It also
contains the <a href="#h3_project_name">project's name</a>,
<a href="#h3_plasma_density">shot details</a>, <a
href="#h3_zero_shift">zero point setting</a>, and the <a
href="#h3_set_centre">centre of the plasma density map</a>.
</p>
<h3 id="h3_openin_m2">Opening an .m2 file</h3>
<p>
To open an .m2 file, choose a suitable option from the File <a
href="#h3_menu">menu</a>. You can just open an .m2 file, which will give you the
labelled fringe data (note that it will take a few seconds for Magic2 to process
the file, just like with <a href="#h3_opening_fringes">opening .png files</a>),
or choose to interpolate the data too (you have a choice of a fast or exact
interpolation, more on this topic <a href="#h2_interpolation">here</a>).
</p>
<h2 id="h2_references">References</h2>
<p>
Magic2 (<a href="https://github.com/jdranczewski/Magic2"
target="_blank">https://github.com/jdranczewski/Magic2</a>) <br>
Copyright (C) 2018 Jakub Dranczewski, based on work by George Swadling<br><br>
This work was carried out during a UROP with the MAGPIE Group,
Department of Physics, Imperial College London and was supported in part
by the Engineering and Physical Sciences Research Council (EPSRC) Grant
No. EP/N013379/1, by the U.S. Department of Energy (DOE) Awards
No. DE-F03-02NA00057 and No. DE-SC- 0001063<br><br>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.<br><br>
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.<br><br>
You should have received a copy of the GNU General Public License
along with this program. If not, see <a href="https://www.gnu.org/licenses/"
target="_blank">https://www.gnu.org/licenses/</a>.
</p>
<p>
<ul>
<li>Swadling, G. F. et al. (2013) ‘Oblique shock structures formed during the ablation phase of aluminium wire array z-pinches’, <i>Physics of Plasmas. American Institute of Physics</i>, 20(2), p. 022705. doi: 10.1063/1.4790520.</li>
<li>Swadling, G. F. (2012) ‘An experimental investigation of the azimuthal structures formed during the ablation phase of wire array z-pinches’, Ph.D. dissertation. <i>Imperial College London</i>. Available at: <a href="https://spiral.imperial.ac.uk/handle/10044/1/9515" target="_blank">https://spiral.imperial.ac.uk/handle/10044/1/9515</a>.</li>
<li>Ware, J. M. (1998) ‘A procedure for automatically correcting invalid flat triangles occurring in triangulated contour data’, <i>Computers & Geosciences. Pergamon</i>, 24(2), pp. 141–150. doi: 10.1016/S0098-3004(97)00088-5.</li>
<li><a href="https://codeplea.com/triangular-interpolation"
target="_blank">https://codeplea.com/triangular-interpolation</a>
</ul>
</p>
</div>
</body>
</html>