== == == == == == == == == == == == == == == == == == == == == =
BRAT - Broadview Radar Altimetry Toolbox README
== == == == == == == == == == == == == == == == == == == == == =



Overview
== == == ==

The Broadview Radar Altimetry Toolbox (BRAT) is a collection of
tools and tutorial documents designed to facilitate the processing
of radar altimetry data. BRAT is able to handle most distributed
radar altimetry data formats, providing support for ingesting,
processing, editing (to a certain extent), generating statistics,
visualising and exporting the results.

A full user manual for BRAT is available in the file
brat_user_manual.pdf in the 'doc' directory of the BRAT
distribution or installation.The user manual contains all the
necessary information about installing and running BRAT.

This README file contains the version history for BRAT, a list of
known issues, and any other last - minute added or updated
information that can not( yet ) be found in the user manual.In
the case of conflicting information, this README file is
authoritative.



Known Issues
============

- Window Buttons in Gnome Desktop

The software recognizes Gnome when when running in a Linux desktop 
and sets the appropriate properties for the minimize, maximize and 
close buttons to be displayed in view windows. However, in Debian 8 
it was verified that additonal configuration steps might be necessary, 
at the system level, for those buttons to be dislayed. 

This issue, which affects not only BRAT but other GUI applications
as well, can be solved by running 

gsettings set org.gnome.desktop.wm.preferences button-layout appmenu:minimize,maximize,close

and by calling gnome-tweak-tool from the command line and then 
selecting "Windows", "Titlebar Buttons", and clicking "ON" for the 
maximize and minimize buttons.


- Spurious error messages about map projections

The first time a view is displayed in a BRAT GUI session, it is 
possible that messages like

"ERROR 6: EPSG PCS/GCS code 54003 not found in EPSG support files."
"Is this a valid EPSG coordinate system?”

are printed to the console. These messages are not issued by BRAT
itself and the reasons why they originate have no consequences on
BRAT functionality. They can be safely disregarded.


- Troubleshooting BRAT startup issues caused by OpenGL check failures

By default, when the BRAT GUI application starts, some tests are executed 
to evaluate the system's OpenGL capabilities. The user can then be alerted 
if some 3D views (3D plots or the globe) have limitations or are not 
displayed at all. In some systems, the Qt framework is not always able to 
recover from these test failures, and the application crashes without 
being able to circumvent the error and/or display any warnings to the user. 
If BRAT cannot start, this is the most common reason, namely in virtual 
machines. To disable these default checks, and allow BRAT to start 
nevertheless, please see the BRAT Software User Manual, section “3.7. 
Troubleshooting OpenGL issues”.




Version History
== == == == == == ==

4.2.1 - May 2018
--------------------
Features added in this version:

- Dimensions consistency check of all operation parameters
- Prevent execution and display full information when dimensions check fails
- Correction of map distance tool for all latitudes and projections
- Improved visualization of X axis, supporting multiple dimensions
- Support user defined variables for filtering parameters
- Support information accessible from about box
- Updated licensing information


4.2.0 - October 2017
--------------------
Features added in this version:

- Upgrade of supported Linux version to Debian 8.x
- Upgrade of supported Python version to 3.4
- Area coordinates can now be manually inserted, besides using the mouse
- View maps base layers can now be changed at runtime
- New application settings: GDAL and WMS raster layer providers
- Support for new variant of Generic Netcdf aliases
- Improved map zoom

Corrections of all bugs and implementation of feature improvements 
reported in version 4.1.0


4.1.0 - April 2017
--------------------
Features added in this version:

- RADS datasets support
- Automatic synchronization with RADS server
- ASCII export gridded view support
- Tutorial videos included in Help
- Support for temporal interpolation when generating grids
- Coastal and Inland Waters Altimetry formulas
- New support for products:
	- Sentinel 3 L1A Products data
	- Sentinel 3 L1BS Products data
	- Envisat Reprocessed data
	- Geosat GDR data
	- ESA River and Lake Hydrology data
	- ESA River and Lake Altimetry data
	- ERS Reaper Products
	- Jason-1 netcdf products
	
Corrections of all reported bugs in version 4.0.0


4.0.0 - October 2016
--------------------

Changes for this version:
- Implementation of all incomplete features in 4.0.0 beta version
- Solution of all known problems reported with 4.0.0 beta version


4.0.0 beta - July 2016
-----------------------

Changes for this version:
- Complete redesign and re-implementation of GUI applications and the concept of simpler data handling
- Feature added to allow the usage of Python scripts within the data expressions
- Feature to allow visualization of tracks when selecting the data
- Feature to allow definition of geographical filter via interaction with map
- Add plots export into image files in different formats (GIF, PNG, and PS)
- Improve background in vectorial base and support raster base background
- Improvement of display of vector plots in both visual display and performance of the plotting
- Improve the memory usage for displaying images allowing at least to display 70MB images with 1GB of RAM
- Improve date display to allow human readable format (e.g. yyyy/mm/dd)
- Inclusion of plot legends in saved images
- Addition of histogram plots
- Addition of linear fit to data in 2D plots with show of regression equation

Known problems with the V4.0.0-beta release:
- Contours:
	Contours are only available for spectrograms (by selecting "Contour" options inside "Data Options" tab of
	the generated View). In the full release it will also be available for the Maps and Globe views type.
- Vector Plots:
	Vector plots are currently not supported and will be implemented for the full release.
- Log Scale:
	Logarithmic scale is currently not supported and will be implemented for the full release.
- Colour Table:
	Currently it is not possible to select a custom colour table, and for this reason, for both type of plots,
	spectrogram and map, a default colour table is used. To be implemented for the full release a set of
	predefined colour tables.
- Sampling and Filter:
	Sampling is the equivalent for the old "Set resolution and filter" feature. Currently this is not customizable
	and each time a plot of the type z=f(x,y) is computed, default values are used for the maximum and
	minimum of latitude (90 and -90 degrees respectively), maximum and minimum (180 and -180 degrees
	respectively) of longitude and a step of 1/3 degrees in each axis. Setting of the parameters to be
	implemented for full release.
- Scheduler:
	Scheduler feature allows to postpone one or more operations, however this is not implemented yet, and
	will be available for full release.
- Saving plot results in an image file:
	This feature would allow the user to save the Plot results in an image file (such as JPEG, PNG or TIFF),
	however was not implemented, and will be available for full release.
- Aliases:
	Aliases are short names or unified names for data fields. There are NetCDF files read by Brat that do not
	have pre-defined aliases. This will implemented for the full release.
- Export Operation:
	This option allows the user to export the current operation data to different formats (such as ASCII,
	NetCDF and GeoTIFF). This feature will be for the full release.
- Show Info Button:
	Provides information about the original units (the ones defined in the data products) and the units used
	during computation or selection. This feature is not available yet and will be implemented for full release.
- Faulty Map Projection: Nearest sided perspective:
	This projection is currently not working properly.


3.3.0 - September 2015
--------------------
    - Correction of unhandled exception caused by not updading NetCDF
    file to reflect GUI changes.
    - Ensured build and run compatibility with CentOS 6 64 bits.
    - Enabled by default side-by-side installation of different BRAT
      versions and processor architectures on the same machine, without
      overwriting each other.
    - Updated available formulas (new formulas.ini file).
    - GUI applications display version and architecture, allowing easy
      runtime identification of different instances on the same system.
    - Python API examples can run immediately after installation,
      without further configuration actions like defining BRAT_DATA_DIR.
    - Correction of BRATHL 3.1.0 bug, caused by buffer overruns when
      reading a large list of files.
    - Correction of bugs caused by wxWidgets upgrade:
            - the Log tab in the application BratGui loosed its	graphical
              layout and stability when resized;
            - the context menus of the tree widgets did not execute the
              expected actions and did not present all menu items.
    - Enabled C++11 support in g++ (Linux).
    - Windows XP support enabled by default in 32 bit binaries.
    - Update to NetCDF version 4.3.3.1.
    - Inclusion of new libraries, in integration with NetCDF 4 and CODA 2.13,
    deployed along with BRAT with their respective tools:
    - HDF5 version 1.8.15,
    - curl version 7.43 ( only in Windows ),
    - SZip version 2.1.
    - Extensions of BRATHL code to process NetCDF 4 and HDF 5, including new
    NetCDF data types.
    - Creation of a brathl dynamic module (brathl_module) encapsulating
    all BRATHL functionality to enable (autonomous) load and interface
        with Python.
    - New Python API to the BRATHL library, with examples.
    - Port to 64 bit of BRAT and all its dependencies, including
    - VTK 5.6.0 adjustments to enable 64 bit,
    - port to 64 bit of the BRATHL library,
    - port to 64 bit of the BRAT command line tools,
    - port to 64 bit of the BRAT GUI applications.
    - Updated wxWidgets to version 3.0.2.
    - Replaced Carbon by Cocoa framework in MAC OS X related code and build settings.
    - Updated BRAT GUI applications and libraries, with VTK support, as required
    by new wxWidgets version.

3.2.0 - June 2015
------------------
Transitional release, preparing version 3.3.0 and focused on
    - update of build settings and source code to support current versions of
    operating systems, compilers and build systems in all supported platforms
    (Windows, Linux, Mac OS X);
    - update of build settings and source code to prepare the port to 64 bit
    architectures;
    - update to CODA version 2.13;
    - update to BitRock InstallBuilder version 15.1.0;
    - minor bug corrections.

3.1.0 - March 2012
------------------
    - Add an "aliases" capability, that enables users to use the same names for
    the most frequent data fields.
    - Add an index (brat_index_data) for data with a "time" dimension
    (i.e. not available for some data, like grids).
    - Add filters algorithms (four different filters have been implemented),
    working along-track or on grids.
    - The call to the geostrophic velocity algorithms is modified to use the
    aliases for longitude and latitude, to make things simpler for users.
    - Updated CODA to version 2.3.1.
    - Internal (CODA) product type names for ERS product types have been aligned
    with ESA naming convention (OPR_pass_file -> ALT.OPR, WAP -> ALT.WAP)
    - Updated CryoSat product format (codadef) to be in line with upcoming
    L1 PFS v4.9 and L2 PFS v2.8. Main changes impacting BRAT are:
        - The field for the main dataset in the FDM product is now called
          'siral_l2_fdm_mds' instead of 'siral_l2_fdo_mds'
        - usr_corr field now has a scale factor of 1e-15 instead of 1e-7
        - Fixed locating of User Manual document when selected from GUI.

3.0.1 - May 2011
----------------
  - Bugs fixed :
    * The Loess filters computation were not applied if input files were netCDF
      files.
    * Fixed problem where incorrect lines were drawn for worldmap plots on
      Windows due to rounding issues near the projection boundaries.
    * Fixed issue where a 'marque' (box with dotted lines) could appear in a
      worldmap plot.
    * Included MSVC 2010 DLLs to BRAT IDL and MATLAB directories on Windows to
      prevent usage problems of these interfaces.

3.0 - February 2011
-------------------
  - Added algorithms computation module (geostrophic velocity algorithms).
  - Added batch processing : BratScheduler enables to delay the execution of an
    operation.
  - Added support for Topex-Poseidon and ERS RA waveform products.
  - It is now possible to drag & drop files into the Dataset panel.
  - Several improvements to BratDisplay:
    * the center/zoom functionality for worldplots has been greatly improved.
    * the number of latitude/longitude grid lines will now increase/decrease
      depending on the zoom level.
    * latitude/longitude grid lines now come with a text label showing the
      associated latitude/longitude value of the parallel/meridian.
    * the 'animation bar' is now shown by default if the plot can be animated.
    * Added support for new projections: Orthographic, Near-Sided Perspective,
      and Stereographic.
    * The save directory for image export will now be remembered for consecutive
      calls to export.
    * Added support to visualize vector plots.
  - Improve 'ascii export' : 'ascii export' is able to export either the result
    of the operation (default) or only dumps the expression data. In the
    previous version of Brat, 'ascii export' only dumped the expression data.
  - Updated CODA to version 1.5.
  - BRAT now requires VTK 5.6.
  - Bugs fixed :
    * Statistics computation are not converted to wanted unit (set by the user).
    * Display Expression Properties for a field were not updated properly in the
      Views tab of BratGui on Mac OS X.
    * The BRAT installer did now work on KDE SUSE 11 systems.

2.1.1 - June 2010
-----------------
  - Bugs fixed :
    * Regression issue in 2.1.0 that broke support of high resolution and
      waveform data for ENVISAT RA-2 and ERS RA products.
    * Possible loss of field names in expressions that contain aliases
    * Wrong SSH formula for Topex product (SSH_TOPEX) (since BRAT 2.0.0):
      'Topex dual-frequency ionospheric (Iono_Cor) correction' should be used
      instead of 'Ionospheric correction from DORIS (Iono_Dor).
    * When executing an operation within Brat GUI, expression was sometimes
      reset if it contained a syntax error.
    * For Topex products, the date in Brat output was wrong if the Brat
      operation contained "high resolution" fields (data).

2.1.0 - March 2010
------------------
  - Updated RA2 product format specifications (codadef) to bring them in line 
    with the new Vol14 4/C product format specifications document.
  - Improvements to the CRYOSAT product format definitions (codadef) file to
    bring it in line with the latest official specification documents.
  - Updated CODA to version 1.3.3.
  - Bugs fixed :
    * The Matlab API 'brathl_ReadData' could crash depending on how parameters
      were passed to the API.
    * BratDisplay could crash due to an invalid pointer.
    * Incorrect fieldname for Export if 'Only dump expressions' was selected.
    * Fixed column header for 'date as period' values in ascii export.

2.0.3 - November 2009
---------------------
  - Bugs fixed :
    * An uninstall of BRAT would delete the entire installation
      directory (/usr/local by default on Linux when installed as
      root), including non-BRAT files and directories.
    * BratExportAscii : issue with the FIELD_FORMAT parameter
      which is not taken into account from the export parameters' file 
	  (Notice that FIELD_FORMAT parameter is never set by using BratGui 
	  and have to be set manually in the parameters' file).
    * Get rid of 'RPM' error messages after a root install on
      Linux.

2.0.2 - November 2009
--------------------
  - Bugs fixed : 
    * On Windows, BRAT could be looking on the wrong drive for its data files 
    * Fixed a few potential memory leak and memory corruption problems
    * Uninstaller on Windows will now properly remove all files

2.0.1 - June 2009
-----------------
  - Bugs fixed : 
    * Compilation errors under Linux X64
    * BratDisplay sometimes crashes on close.
    * BratGui sometimes crashes when refreshing the display panel
    * Some minor issues.
  
  - Improve 'ascii export' report (from Netcdf products).

2.0.0 - April 2009
------------------
  - This update is a major upgrade of the software, including a Mac OS X
    version, River&Lake data reading capability, full waveform processing and
    plotting, new plotting capabilities, export in GeoTiff, including a Google
    Earth export feature, easier export in ASCII, a rethinking of the Graphical
    User Interface and of the software packaging, to make it easier to use.

1.1.1 - June 2008
----------------------
  - Bug fixed : In Brat Gui, Loess filter is never applied. Bug
    appears in version 1.1.0.

1.1.0 - December 2007
----------------------
  - Bug fixed : sometimes the toolbox (GUI) crashes when you
    delete an operation.
  - Add Jason-2 data processing.
  - Add 'General' NetCdf data processing.
  - Built under linux with GCC 4.2.2 (new warnings)

1.0.2 - March 2007
------------------
  - Bug fixed : In X/Y plot display, sometimes the toolbox
    crashes when moving the graph after having modified the font
    size.
  - Disable 'barn' unit.
  
1.0.1 - December 2006
---------------------
  - Add high-resolution fields processing.
  - Installation process and package creation enhanced.

1.0.0
-----
  - First released version.



Further information
===================

For software upgrades, documentation updates and the on-line
tutorial, including use cases go to:

http://earth.esa.int/brat/ or http://www.altimetry.info/

BRAT has been developed under contract with ESA.