/**
***************************************************
* \page ug_JEMRIS_txrx Coil array layout tool: JEMRIS_txrx

\n

The GUI for coil array configuration allows to construct receiver and/or transmitter arrays with dedicated spatial
sensitivity patterns. 

\ref ug_JEMRIS_coil_intro
    \li \ref ug_coil_gui_Menu

\ref ug_coil_gui_Panels
    \li \ref ug_coil_gui_xml
    \li \ref ug_coil_gui_sens
    \li \ref ug_coil_gui_array

\ref ug_coil_gui_coil
       \li \ref ug_coil_gui_biot
       \li \ref ug_coil_gui_analytic
       \li \ref ug_coil_gui_external


\n 
\n 
\section ug_JEMRIS_coil_intro Introduction to the coil array layout GUI JEMRIS_txrx

A coil array consists of several coils in a specified order, the channel number. The order is just given
by the order of creation of the coils. In case of a receive coil array, one signal file per coil is generated in
the simulation. In case of a transmit coil array, the RF pulses of the MR sequence have to specify which channel they use. If no
channel is specified, the RF is transmitted via all available channels.

The command "JEMRIS_txrx" opens in Matlab the GUI for coil array configuration.

\subsection ug_coil_gui_Menu GUI Menus

\li File Menu \n
To start, open a new or an existing coil array from the File Menu. The File Menu also contains a submenu "Figure" from which
the complete GUI window can be exported to a jpeg image. Further, a new standard Matlab figure window containing the sensitivity
map can be created.

\li Layout Menu \n
The "Layouts" menu on the top allows easily predefined geometrical arrangement of a number of coils. Currently, only a
distribution on a cylinder is possible. Using this feature will delete all coils of the current coil array and replace
them with a new configuration. A distribution on a sphere will be made available soon (after publication of results).

\section ug_coil_gui_Panels GUI Panels
The GUI is devided in four different panels comprising all functionality: \ref ug_coil_gui_xml, \ref ug_coil_gui_sens, \ref ug_coil_gui_array, \ref ug_coil_gui_coil 

\image html pics/txrx_gui.jpg
\image latex pics/txrx_gui.eps


\subsection ug_coil_gui_xml XML File Panel
On this panel the name of the current XML coil array file is displayed in red. There are two buttons: 

\li <b>"write XML"</b> As with the sequence GUI, this button overwrites the current XML coil file according to the
recent changes made for the indivudual coils. It then invokes the external jemris binary to (re-) calculate the sensitivity maps.
The maps are stored in the current working directory in the HDF5-file "sensmaps.h5".

\li <b>"read XML"</b> Accordingly, this button undoes all recent changes on the coils and reads the current XML coil file.

Additionally, the output of the external jemris call is dumped below.

\n

\subsection ug_coil_gui_sens Sensitivity Map Panel
On this panel the sensitivity map is plotted. Note that the magnitude senstivity for each individual coil is normalized to 
one within the FOV of the coil (see below for a defintion of the coil FOV). Therefore, the superposition of the sensitivity
may has values larger than one.

The display of the sensitivity can be manipulated with four different selection boxes: 

\li <b>"x-y slice" ["x-z-slice","y-z-slice","3-D"]</b> selects the possible views. The 3D view displays a contour of the
sensitivty map.

\li <b>"Magnitude" ["Phase","Real","Imaginary"]</b> For complex coil sensitivity maps.

\li <b>"Show Coils" ["Hide Coils"]</b> Plots the name (label) for each coil at its centre position.  Additionally, an arrow
points in the direction of the coil (see below for definition of the direction). 

\li <b>"Show Sample" ["Hide Sample"]</b> Overlays a transparent view of the sample on the sensitivity map.
The sample is read from the last generated output of the 
<a href="ug_JEMRIS_sim.html">Simulation GUI \c JEMRIS_sim </a> in the current working directory.

\li <b>"All Coils" ["Active Coil"]</b> Either shows the sensitivity superposition of all coils or only the sensitivity map of the
currently selected coil in the \ref ug_coil_gui_array.

\n 


\subsection ug_coil_gui_array Coil Array Panel

On the Coil Array Panel all coils of the array are displayed by green circles with their name. Click a coil to make it active for
manipulation of its attributes on the \ref ug_coil_gui_coil. The active coil is marked with a surrounding red circle.

Additionally, there are three buttons:

\li <b>"Add Coil"</b> Adds another coil to the coil array. The type is chosen from the selection box to the right. Currently,
jemris supports three types of coils: <b>"Biot-Savart" ["Analytic","External"]</b>. Their specific differences is explained below
in the section \ref ug_coil_gui_coil.

\li <b>"Delete Coil"</b> Deletes the currently active coil from the array.

\li <b>"Copy Coil"</b> Adds another coil to the coil array which is an exact copy of the currently active coil.

\n 

\section ug_coil_gui_coil Coil Panel

Finally, on the Coil Panel all properties (attributes) of the currently active coil are specified. Changing the attributes of
a coil will only have effect after pressing the "write XML" button on the \ref ug_coil_gui_xml 

Whenever an attribute value is changed, it is possible to apply this last change to all other coils by pressing the button
<b>"apply change to all"</b>.

There are several attributes which are common for all coil types:

\li <b>"Xpos","Ypos","Zpos"</b> Coordinates of the coil centre.

\li <b>"Azimuth","Polar"</b> Orientation of the coil. In case of the Biot-Savart loop, the azimuth and polar angle determine the
direction of the normal vector on the loop. Similar, for the anaytic coil, the angles specify a rotation of the coordinate system:
first, rotation of the x-y axes about the z-axis (azimuth angle), then rotation of the z-axis about the new x-axis (polar angle, or inclination).
For the external coil these attributes are not used.

\li <b>"Scale"</b> A scale factor for the mangitude sensitivity. 

\li <b>"Phase"</b> A phase shift for the complex sensitivity. 

\li <b>"Conj"</b> Complex conjugation of the complex sensitivity. 

For the next properties, which also apply to all three coil types, it is important to know how jemris internally handles
coil sensitivities during the simulation. Each coil represents its sensitivity on a predefined grid which is calculated once
in the beginning. Then, during simuation, the sensitivities are retrieved by linear interpolation on the grid. This is important
to speed up the simulation since value retrieval has to take place at at every spin position and every time point of the MR
sequence which is related to signal acquisition (in case of a receive coil) or RF pulses (in case of a transmit coil). The grid
(usually the same for all coils in the array) has three attributes:

\li <b>"Dim"</b> The dimension of the coil: has to be either 2 or 3 for 2D or 3D MRI simulations. 2D is allways restricted to
the x-y plane. If 3D simulations are performed with a 2D coil array, the sensitivity is constant along the z-axis. 

\li <b>"Extent"</b> The size of the support region of the sensitivity map, i.e. the FOV of the coil.
Outside the extend the sensitivity is zero. The unit is [mm].

\li <b>"Points"</b> Number of sampling points of the grid along all spatial axes.
If this number is large, sensitivity calculations take longer (espescially in case of a 3D grid).

\n

Finally there are coil attributes specific to the type of the coil:

\subsection ug_coil_gui_biot Biot-Savart Loop

\li <b>"Radius"</b> The radius of the loop. The unit is [mm].

\li <b>"Mask"</b> A radius around the loop wire defining a torus within the field is masked to zero in order to surpress the 
field close to the loop. The unit is [mm]. This is useful for visualization purposes.

\subsection ug_coil_gui_analytic Analytic Coil

\li <b>"Sensitivity"</b> A GiNaC formula to calculate the sensitivity.
Use capital letters "X","Y", and "Z" for the position coordinates. The formula may contain imaginary parts (use "I" as the
imaginary unit) to specify the phase. See section \ref ug_JEMRIS_seq_expressions for a brief description of the symbolic
expression syntax.

\subsection ug_coil_gui_external External Coil

\li <b>"Filename"</b> Specifies the HDF5-file from which jemris reads the externally defined sensitivities. The file
has two datasets, "/maps/magnitude" and "/maps/phase", respecitvely, each of square (2D) or cubic (3D) size to specify the
coil sensitivities.  Note, that such an external HDF5-file is easily constructed by
the GUI: generate a global matlab variable which is a complex data cube of coil sensitivities.
Then write the name of the variable to the attribute "Filename". The GUI will automatically construct the necessary HDF5-file.

*/
