.. _tutorial:
A brief tutorial
================
This is a brief tutorial about how to get your first *quick look image* using
BEST and BESTGUI.
Download and install the software
---------------------------------
Download the BEST User Manual
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `BEST User Manual`_ can be downloaded from the ESA_ wev site.
This is not necessary if you already know BEST and how to install it.
.. _`BEST User Manual`: http://earth.esa.int/services/best/documentation
Download and install BEST
~~~~~~~~~~~~~~~~~~~~~~~~~
If BEST_ is not yet installed on your computer than download and install it.
The download page is here__, and you should follow the installation
instructions that you find in the `BEST User Manual`_.
__ BEST_
.. _BEST: http://earth.esa.int/services/best
Download and install BESTGUI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If BESTGUI is not yet installed on your computer than download and install
it following the instructions reported in the :ref:`how-to-get-it` and
:ref:`how-to-install-bestgui` sections.
Get the data
------------
If you don't already have a SAR data from the ERS_ 1/2 or ENVISAT_ missions
you can download a sample data from the ESA_ web site:
http://envisat.esa.int/services/sample_products/asar
In this tutorial we suppose that your data is::
ASA_IMG_1PXPDE20020730_095910_000000162008_00108_02166_0007.N1
(available for the download here__, ~150 MB) and that it is located in your
home folder.
__ http://envisat.esa.int/services/sample_products/asar/DS1/IM/ASA_IMG_1PXPDE20020730_095910_000000162008_00108_02166_0007.N1.gz
.. _ESA: http://earth.esa.int
.. _Envisat: http://envisat.esa.int
.. _ERS: http://earth.esa.int/ers
Run BESTGUI
-----------
Run BESTGUI (see the :ref:`running-bestgui-without-installation` section).
The main application window should be empty with the BESTGUI logo in the
middle, and the massage "Ready" should appear in the status-bar.
Perform the *Header Analysis*
-----------------------------
In order to get the *quick look image* you need to perform the *Header
Analysis* (see the "BEST User Manual").
From the **Tools** menu select the **Data Import & Quick Look** sub-menu
and finally the **Header Analysis** entry:
**Tools-->Data Import & Quick Look-->Header Analysis**
.. .. rubric:: Tools-->Data Import & Quick Look-->Header Analysis
Now the *Header Analysis* form is showed in the main window and on the
status-bar appears the massage: "Untitled parameters file".
You have to set the right parameters for the processing.
If you use the data specified in the point 4 most of the default values
should be already correctly set. You only need to:
- set the *Input Media Path* by typing the data file name::
ASA_IMG_1PXPDE20020730_095910_000000162008_00108_02166_0007.N1
in the corresponding entry. You can also select it from the file dialog
using the *Open* button at the right side of the entry.
- set the *Input Media Type* to "``DISK``". Note that the *Acknowledge
Mount* and *Dismount volume* radio buttons now are grayed.
- set the *Product Type* to "``GEC``"
- set the *Output Dir* mandatory parameter to the folder you want the output
files to be written (e.g type a simple dot "." to indicate you want to
save the output files in the working folder that is the one specified in
the user preferences or, if none is specified, the user home folder).
- set the *Annotation File* mandatory parameter (e.g. type "annotations" in
the corresponding entry). Note that the ``.txt`` extension will be
automatically added by BEST.
- set the *Header Analysis File* mandatory parameter (e.g. type
"annotations" in the corresponding entry). Note that the ``.HAN``
extension will be automatically added by BEST.
.. NOTE: the trick here is to set the size (width=122mm) using the image
tags so that the picture fits the a4paper (PDF manual).
In the HTML manual the image remains at full resolution.
.. figure:: images/tutorial-header_analysis.png
:width: 100%
:alt: header analysis form
:align: center
Header Analysis form.
Here is the ``header_analysis.ini`` file::
[HEADER ANALYSIS]
data format = "MPHSPH"
header analysis file = "annotations"
sensor id = "ASAR"
number of volumes = 1
output dir = "./"
sensor mode = "Image"
acknowledge mount = 'N'
input media type = "DISK"
annotation file = "annotations"
product type = "GEC"
input media path = "ASA_IMG_1PXPDE20020730_095910_000000162008_00108_02166_0007.N1"
source id = "esp"
Now press the *Execute* button on the tool-bar (note that when the mouse is
over it a tool-tip is showed) or use the *Execute* entry in the *Execute*
menu:
**Execute-->Execute**
.. .. rubric:: Execute-->Execute
Since the parameters file has not yet been saved (the "Untitled parameters
file" message is still in the status-bar) the program pops up the file
dialog to ask you the file name to save the parameters file. Replace the
pre-set file name ``patameters.ini`` with ``header_analysis.ini`` and press
the *OK* button.
BEST is launched in a sub-process controlled by BESTGUI.
The status-bar shows the "Running ..." message and the progress-bar displays
the task completion percentage. Further the output-plane pops up (in the
lower part of the main window) showing the colorized output coming from
BEST.
When the processing is complete the progress-bar is hidden and the
status-bar shows the parameters file name (``header_analysis.ini``).
The last line of the output log should report: "HEADER ANALYSIS completed.".
Two new files, ``annotation.txt`` and ``annotations.HAN``, should be in
your working directory.
Run the *Quick Look Generation* tool
------------------------------------
From the **Tools** menu select the **Data Import & Quick Look** sub-menu
and finally the **Quick Look Generation** entry:
**Tools-->Data Import & Quick Look-->Quick Look Generation**
.. .. rubric:: Tools-->Data Import & Quick Look-->Quick Look Generation
Now the *Quick Look Generation* form is showed in the main window and on the
status-bar appears the massage: "Untitled parameters file".
This form has many parameters to set. You can set the default values for
many of them by using the *Default* menu entry in the in the *Execute* menu
**Execute-->Default**
.. .. rubric:: Execute-->Default
or hitting the corresponding button on the tool-bar.
Still assuming that you use the data specified in the point 4, now set the
missing parameters:
- the *Input Media Type* should be set to "``DISK``"
- set the *Input Media Path* to::
ASA_IMG_1PXPDE20020730_095910_000000162008_00108_02166_0007.N1
by selecting it from the file dialog (use the *Open* button at the right
side of the entry).
Note that the full data path is displayed in the *Input Media Type* entry.
- set the *Input Dir* to the folder where the annotation file
(annotations.HAN obtained in the point 6) is located.
Since you are using the working folder you can just type "." (a dot) in
the *Input Dir* entry.
- set the *Header Analysis File* to ``annotations.HAN`` (note: if you use
the *Open* button and select the file from the dialog, the path-name
reported in the entry is the one relative to the *Input Dir*).
- set the *Output Dir* (again you can use "." to refer to the working
folder)
.. NOTE: the trick here is to set the size (width=122mm) using the image
tags so that the picture fits the a4paper (PDF manual).
In the HTML manual the image remains at full resolution.
.. figure:: images/tutorial-quick_look.png
:width: 100%
:alt: header analysis form
:align: center
Quick Look form.
Here is the ``quick_look.ini`` file::
[QUICK LOOK]
number of grid lines = 8, 8
grid type = "LATLON"
output quick look image = "ql"
acknowledge mount = 'N'
quick look presentation = "NORMAL"
output dir = "./"
min percentage = 2.70
output image size = 800, 0
max percentage = 98.50
input dir = "./"
window sizes = 3, 3
output grid image = "qlg"
input media type = "DISK"
grid drawing mode = "TRANSPARENT"
header analysis file = "annotations.HAN"
input media path = "/home/antonio/ASA_IMG_1PXPDE20020730_095910_000000162008_00108_02166_0007.N1"
Now you are ready to run the *Quick Look Generation* tool: press the
*Execute* button on the tool-bar.
Since the parameters file has not yet been saved (the "Untitled parameters
file" message is still in the status-bar) the program pops up the file
dialog to ask you the file name to save the parameters file. Replace the
pre-set file name ``patameters.ini`` with ``quick_look.ini`` and press the
*OK* button.
BEST is launched in a sub-process controlled by BESTGUI.
The status-bar shows the "Running ..." message and the progress-bar displays
the task completion percentage. Further the output-plane pops up (in the
lower part of the main window) showing the colorized output coming from
BEST.
When the processing is complete the progress-bar is hidden and the
status-bar shows the parameters file name (``quick_look.ini``).
The last line of the output log should report: "QUICK LOOK completed.".
Two new files, ``ql.tif`` and ``qlg.tif``, should be in your working
directory. They are the quick look images (``qlg.tif`` is the same image as
``qlg.tif`` with a grid displayed on).
You can see them using your favorite image viewer.