Exercises for the E3D tutorial workshop.
----------------------------------------
(Potsdam, 28-30 April, 2004.)

Exercise 01
-----------

(a) Transform the file "image2d.fits" into an Euro3D formatted file,
    using the position table "PosTable.txt", using any2Euro3D and 
    the E3D GUI.

(b) Replace "PosTable.txt" for another file (e.g., copy and edit), 
    and transform it again to see the differences.

(*) Replace the 2D image and the Position table for your own data
    and try it again (if they are in the RSS).


Exercise 02
-----------

(a) Transform the file "HH_cube.fits" into an Euro3D formatted file,
    using the E3D GUI.

(b) Export it in the RSS format.


Exercise 03
-----------

(a) Go to the "exercise01" directory, load the Euro3D created image
(e.g., image2d.e3d), and export it as a datacube. Load the new cube
and compare with the original data. Compare the size of the files in
the Euro3D and the datacube formats.


Exercise 04
-----------

Go to the "exercise01" directory. Import the 2D spectral image
"spectra2d.fits", as an slit spectra.

Exercise 05
-----------

Go to the "exercise01" directory. Import the 2D map "mapa.fits".

Exercise 06
-----------
Go to the "exercise01" directory, load the Euro3D created image
(e.g., image2d.e3d).

(a) Open the Spectral Inspector. Select the wavelength range selection
(Select). Select a range of wavelengths in the main window (click
left-left) and then send it to the Spaxels Inspector (click
right). Repeat it several times over different regions, until get
used.

(b) Click the central button over the main window and keeping clicked
move through the wavelength. See the movie-like effect on the Spaxels
Inspector.


Exercise 07
-----------
Go to the "exercise01" directory, load the Euro3D created image
(e.g., image2d.e3d).

(a) Open the Spaxels Inspector. Select the spatial range selection
(Select). Select a range of spaxels in the main window (click
left-left) and then send it to the Spectral Inspector (click
right). Repeat it several times over different regions, until get
used.

(b) Click the central button over the main window and keeping clicked
move through the different spaxels. See the movie-like effect on the
Spectral inspector.

Exercise 08
-----------

Go to the "exercise01" directory, load the Euro3D created image
(e.g., image2d.e3d).

(a.1) open the Configuration Menu and change the color map. See the
    effect over RSS image. 

(a.2) Change the Scale. See the effect over the RSS.

      Change the bright and the contrast to emphasize 

(b.1) Open the Spectral Inspector, and mark for spatial selection
    (Select) in the Main Window. Select a certain spatial range and
    send it to the spectral inspector.

(b.2) Open the Configuration Menu and change between different
      Spectral Representations. See the effect in the spectral
      inspector.

(c.1) Open the Spaxels Inspector, and mark for spectral selection
      (Select) in the Main window. Select a certain wavelength range,
      and send it to the Spaxels Inspector.

(c.2) Change the Shape in the Spaxels Inspector to Map (i.e.,
      interpolated). 

(c.3) Open the Configuration Menu and change between different
      interpolation routines. See the difference in the Spaxel
      Inspector.


Exercise 09: The Spaxels Selection
-----------

Go to the "exercise01" directory, load the Euro3D created image
(e.g., image2d.e3d).

(a) Open the spaxels inspector, select a certain wavelength range and
create a spaxels map. Using the "Configuration" menu, select a
"Single"-based spaxel selection. Select a certain number of spaxels
and show the spectra asociated with them. 

(b) Using the "Configuration" menu, select a circular based selection,
of 1.5" diameter. Select one of the two objects seeing in the
image. Storage the selection as an E3D object. Clear it and select the
other object. Storage the selection as another E3D object. Click
alternative to both objects in the "Objects" list while keeping open
the spectral selection.

(c.1) Back to the Single-spaxel selection. Select the "pseudo-slit"
selection by clicking "s". Select different pseudo-slit cuts, showing
the spectra and the intensity cuts ("v"). 

(c.2) Select a "pseudo-slit" cutting through the bright
object. Storage it as a new object.

(d.1) Select each of the three "Objects", consecutively, and store the
asociated spectrum (average!) using the Spectral inspector.

(d.2) On the Spectral Inspector, select the multiple spectral plot
("Single/Multiple Plot"), and click over the three stored spectra.

(d.3) Subtract and Divide the spectrum 1 and 2 and plot also the
results.



Exercise 10: Sky Subtraction
-----------

Go to the "exercise03" directory, load the Euro3D image "e3d_object.fits".

(a) Open the spaxels inspector, select a certain wavelength range and
create a spaxels map. 

(b) Select a range of spaxels covering the object (N-W). Open the
spectral inspector, send the spectra of this region to it, and storage
it as the "Spec 0". Save this region as an "Object" (Spaxels inspector).

(c) Select a range of spaxels as far as possible from the object
(S-E). Send the corresponding spectra to the spectral inspector and
storage the average as "Spec 1".

(d) Substract the Sky (Spec 1) to all the image by clicking
"Spectra"->"Sky Substraction" on the "Spectral Inspector", and
selecting "Spec 1".

(e) Recover the "Object" with the selection over the object (you
should have stored it in step b). Store the average spectrum of this
object in "Spec 2".

(f) Plot "Spec 0", "Spec 1" and "Spec 2" in a multiplotting, to
compare them. Store the result in a Postscript File.


Exercise 11: DAR correction
-----------

Go to the "exercise01" directory, load the Euro3D created image
(e.g., image2d.e3d).

(a) Open the spaxels inspector, and using the mouse central button
over the Main Window check the displacement of the sources over the
sky plane, due to DAR.

(b) Correct empirically the DAR, but clicking on 
"DAR Tools"->"PM Det. DAR" and 
"DAR Tools"->"Correct DAR"

(c) Repeat the exercise of step (a) to check visualy that the DAR has
been corrected.

(d) Store the result as a new Euro3D file.


Exercise 12: Quick Line fitting
-----------

Go to the "exercise04" directory, load the Euro3D file "e3d_agn.fits".

(a) Select the wavelength range between ~5160 and ~5200 AA and zoom over
it. Create a spaxels map of this region in the Spaxels Inspector.

(b) Select number og spaxels, and see the result on the Spectral
Inspector. 

(c) Fit the observed line, by clicking "Fitting"->"Fit Single Emission
Line".

(d) Perform a "quick-and-dirty" Kinematic analysis, by clicking
"Fitting"->"Full Automatic Kinematic Analysis". The result is sent to
the Spaxels Inspector, including a intensity-peak map, a velocity and
velocity dispersion map, and a continuum map.


Exercise 13: E3D/Tcl scripts
-----------

Go to the "exercise03" directory, there are four E3D/tcl scripts.
Edit them to change the proper directory of the E3D/tcl interpreter,
"tk_e3d". 

(a) Open "save_slice.tcl" (e.g., emacs), and run it. Try to understand
the different steps of the script. Change some parameters from
"create_slice" following the E3D documentation, and check the results.

(b) Open "plot_ps.tcl" (e.g., emacs), and run it. Try to understand
the different steps of the script. Change some parameters from
"plot_spaxels" and check the effects in the result ("file.ps").

(c) Open "plot_movie.tcl" (e.g., emacs), and run it. Try to understand
the different steps of the script. Change some parameters from
"plot_spaxels" and check the effects in the result.

(d) Open "plot_movie_tk.tcl" (e.g., emacs), and run it. Try to understand
the different steps of the script. Change some parameters from
"plot_spaxels" and check the effects in the result.

(e) Create an script that perform the DAR correction. 

Exercise 14: Connecting E3D with external tools.
-----------

Go to the "exercise03" directory. Open the E3D GUI, and open 
the documentation of E3D for the chapter 5.

E3D comunicates with the external using as transmision
two files: /tmp/input.e3d (input) and /tmp/output.e3d (output).

(a) Test the command:
    
    echo "puts test" > /tmp/input.e3d

    It will write "test" in the Xterm were E3D was opened.

(b) Test the command:

    echo "load_e3d e3d_object.fits" > /tmp/input.e3d

    E3D automatically will load the file "e3d_object.fits" 
    and plot it in the screen.

(c) Create an script in your prefered language to load 
    an e3d-file. Use as examples "e3d_display.pl" and 
    "e3d_command.pl".





SOLUTIONS:

E.01.a:

any2Euro3D -if image2d.fits -of image2d.e3d -pf PosTable.txt -nb_spec 205 -type 1

E.13.e:

correct_dar.tcl at "exercise01" directory.


E3D GUI Tour:
-------------

- E3D comprises three windows: The Main Window (Raw Stacked Spectra),
  The spaxels inspector (Slices, i.e. mono- polychromatic cuts), and 
  The spectral inspector (Spectra).

- All the Inspector comprises an imagearea (black-right) an
  information/prompt panel (left) and a menu (top).

- The information/prompt panel shares for the three inspectors:
  Min, Max, bright and contrast, W1 (starting wavelength) and W2
  (ending wavelength).

- They have for each inspector also particular entries/informations.


- Main Window: RSS Inspector:

   - MENU:

     - File (I/O of data).
       
       Load/Save -> Euro3D format data (native format).
       Import/Export -> RSS/Datacubes (cubes).
		     NOTE: The cubes are created by interpolating the
		     data using the parameters defined for
		     interpolation (Configuration->Interpolation).
       Import slit spectra -> To import a 2D spectral image, without
			      spatial information (assumed to be a
			             slit spectrum).
       Save Slit Spectra -> Save the RSS as it was an slit spectral
       image.
       Save Spectra (Wavelength cut) -> Save the currently selected
       section of the RSS as a 2D spectral image.		     
       
     - Spaxels.
       Open -> Opens the Spaxels Inspector.
       Select -> Change the current selection from wavelength range
		 to spatial range or the other way around.
       Plot -> Plots the currently selection in the Spaxels inspector.

     - Spectra.
       Open -> Opens the Spectral Inspector.
       Select -> Change the current selection from wavelength range
		 to spatial range or the other way around.
       Plot -> Plots the currently selection in the Spectral
       Inspector.

     - Configuration -> Change the configuration of E3D.
       ColorMap -> Change the palette: grey,heat,rainbow,iraf,aips.
       Scale -> Change the Scale: Default, Log, Square, Root-Square
	     & Linear.
       Spectral Representation -> Change the kind of representation
	     in the spectral inspector: Image/Mean, Image, Mean, All,
	     & Image/All.
       Interpolation -> Open the interpolation prompt menu.
	     Select the Interpolation Algorithm to use, the Grid
             Option (read the documentation), and the pixel size of
             the output grid.
	     Once selected it is needed to "Set Parameter" to save the
             selection.
       Spaxel Selection -> Open the Spaxels Selection Menu.
	     Select the two different spaxels selection: single spaxel
	     or circular selection, select the radius (in case of a
	     circular selection) and click on "Set Parameters" to save
	     the selection.

     - DAR Tools: Differential Atmospheric Corrections Tools.
     
       E3D includes different DAR correctors, including the Th.

       If there is a clear bright source, we recomend to use the
       "peak" or the "PM", both empirical corrections.
       
   - Panel: (Particular entries for the Main Window)

       W1 and W2 indicate the currently selected wavelength range.
       With the "Zoom" button we only plot the wavelength range
       between W1 and W2.
       
       In the Main Window, if the number of spaxels is larger than
       256, only the first 256 are plotted by default. A larger number
       can be plotted, by changing the value in the "Range" prompt.
       The "First" entry indicates (and allows to change) the first
       spectrum to be plotted. The scroll bar under both prompts
       allows to navigate through the RSS image, by increasing the
       "First" spectrum to be plot, and letting fix the "Range".

- Spaxels Inspector:

     - File (I/O data).

     - Shape: Allows to change the kind of map representation, from
       the original configuration (spaxels-like) to interpolated maps.

     - Select: Handles the Spaxels selection.  
       The Spaxels selection is done in three different ways: 
       (a) Spaxel-to-Spaxel. It the default, just click-and-move over 
        a certain spaxel (using the left-mouse button).
       (b) Circular Selection. Can be selected in the 
        "Configuration"->"Spaxel Selection".
        Click-and-move over a certain spaxel it will select all the
	spaxels at distance lower than the value adopted as radius.
       (c) Pseudo-slit Selection. Can be selected pressing the "s"-key
       when over the Spaxels-inspector ("s" again will deselect it).
       Once clicked is possible to select a pseudo-slit by clicking
       twice the left button.

       Once selected a number of spaxels it is possible to see the 2D
       spectra associated with them in the spectral inspector by
       clicking the right-mouse-button.

       It is possible to see the intensity profile of a certain
       selection (pseudo-slit) by pressing "v".

       To deselect all the selected spaxels it is needed to click 
       "Select"->"Clear"

       It is possible to storage the currently selected spaxels by
       clicking "Select"->"Create Obj". By clicking over the object in
       the "Objects" list in the panel it is possible to recover the
       selection. 
       It is also possible to reverse the selection by clicking
       "Select"->"Reverse Object".

     - Tools:
       
        Blink: To blink between different maps we click over the
        "Tools"->"Blink" button, select a certain number of maps by
        clicking over them, and then click again over the "Blink"
        button.
	To stop the blinking, we click once more time over the "Blink"
        button.

     - Arithmetics:

        Opens the Arithmetics menu, where it is possible perform
        arithmetic operations over the different maps (subtraction,
        division...).

   - Panel: There are several new information entries, where
     information about the actual selected spaxels or the current
     position of the cursor (and the flux of the nearest spaxel) are
     given.

   - Zooming: Clicking "z" over the imagearea the mouse cursor
     transforms to a ractangle. Clicking again "z" we create a zoomed
     version of the map. Clicking "u" we un-zoom.


- Spaxels Inspector:

   - File (I/O data).
       
   - Spectra: This menu handles the storage average spectra, that
     would appear in the list on the left panel. It includes options
     to Save a new average spectrum, plot one or many of them, clear
     the multiple selection, and different arithmetic operations
     between spectra.

   - Fitting: E3D includes a simple line-fitting tool, not thought to
     be an accurate, but a rather "first-look" fitting tool. It fits
     to a single line (gaussian) plus continuum (constant).

     Once selected a certain wavelength range, including a like, it is
     possible to fit it to this simple model by clicking:
     "Fitting"->"Fit Single Emission Line"

     A "quick-and-dirty" kinematic analysis can be performed using
     this fitting capabilities, by clicking:
     "Fitting"->"Full Automatic Kinematic Analysis"


  - Panel: The Spaxels Inspetor Panel includes the wavelength range,
    "Zoom" & "Release" button that have been already explained for the
    Main Window. 

    It also includes a listbox with the storaged spectra.


Examples of E3D/Tcl Routines
-----------------------------
#######
create_env euro3d /null
euro3d load_file e3d_file.fits
euro3d create_slice 0 1 1 0
euro3d save_slice 1 slice.txt Flux 1
exit
########
       
########
create_env euro3d "/null"
euro3d load_file e3d_file.fits
set id_ps [euro3d open_device "file.ps/CPS"]
euro3d plot_spaxels 1.0 100.0 $id_ps 100 300 heat 0.6 0.7 1 1 1 0 2
euro3d close_device $id_ps
exit
########

########
create_env euro3d "/xs"
euro3d load_file e3d_object.fits
for {set i 1} {$i<500} {incr i 1} {
    set j [expr $i+1]
    euro3d plot_spaxels 1.0 180.0 1 $i $j iraf 0.7 0.7 1 1 1 4 2
}
exit
########


      


