ENVIRONMENTAL INFORMATICS GEOINFORMATION PRODUCTS		BROCKMANN CONSULT
	BEAM Java Tutorial
	INDEX\| SET-UP\| EX 1\| EX 2\| EX 3a\| EX 3b\| EX 4\| OUTLOOK

Outlook

How to continue after this tutorial

Overview

Check for invalid or missing input pixels

If you are already used to the BEAM API you can try to add some important extensions to your source code from exercise 4. In a real data processing software we would have to check if the input pixel value is defined and valid at a given pixel position x,y. We would also like to specify missing or invalid NDVI output pixels in the output product.

For the NDVI we should only use pixels over land. The MERIS Level-2 product has a classification flag called LAND for this purpose. It is contained in the flags band l2_flags. Given here are two approaches to read the LAND flag:

1. Add a VirtualBand to the input prouduct from which you can then read the flag values:

    String landMaskExpr = "l2_flags.LAND";
    Band landMaskBand = new VirtualBand("land_mask", ProductData.TYPE_INT8, width, height, landMaskExpr);
    inputProduct.addBand(landMaskBand);
    ...
    byte[] landMask = new byte[w];
    ...
    landMaskBand.readPixels(0, y, w, 1, landMask);
    if (landMask[x] != 0) { // valid input pixel for NDVI
    ...

2. A similar way is to use the BEAM band arithmetic directly. You will often find the following code snippet in the source code of the BEAM processors:

    String landMaskExpr = "l2_flags.LAND";
    Term landMaskTerm = inputProduct.createTerm(landMaskExpr);
    ...
    boolean[] landMask = new boolean[w];
    ...
    inputProduct.readBitmask(0, y, w, 1, landMaskTerm, landMask);
    if (landMask[x]) { // valid input pixel for NDVI
    ...

Specify invalid or missing output pixels

The Band class provides two options to specify invalid or missing output pixels:

A. Specify the no-data property of the Band class. In this case you tell the band which no-data value you have used to indicate that the NDVI could not been computed, e.g. -1:

    pubic static final float NDVI_INV = -1;
    ...
    ndviBand.setNoDataValueUsed(true);
    ndviBand.setNoDataValue(NDVI_INV);
    ...
    ndviPixels[x] = NDVI_INV; // if invalid

B. Additionaly we can set the valid-pixel expression property of the Band class. This property is a BEAM band arithmetic expression string:

    pubic static final String NDVI_VALID = "NDVI >= 0 && NDVI <1";
    ...
    ndviBand.setValidPixelExpression(NDVI_VALID);

You can see the effect of the no-data and valid-pixel expression properties directly if you enable the No-Data Overlay for the NDVI image view in VISAT. You can also use the Property Editor to change these properties.

Add more information to the output product

After opening the output of the NDVI exercise in VISAT, we recognise a somehow poor NDVI product. A standard Envisat data product normally contains a lot of additional information such as:

geo-coding,
quality flags,
flag-coding,
bitmask-overlays
and meta-data.

The following table shall give you some hints on where to search in the BEAM-API for support on these issues.

BEAM API Link	Purpose	Example
TiePointGrid	Similar to a band, put pixel values given at a rectangular grid of tie-points only. Pixel value at band coordinates are computed using linear interpolation between tie-points.	`TiePointGrid grid = new TiePointGrid(...); product.addTiePointGrid(grid);`
GeoCoding	Provides the geo-coding for all bands of a product.	`GeoCoding coding = new TiePointGeoCoding(latGrid, lonGrid); product.setGeoCoding(coding);`
FlagCoding	Provides the description of all flags in a flags-band.	`FlagCoding flagCoding = new FlagCoding("output_flags"); flagCoding.addFlag("INVALID", 0x0001, "Pixel is invalid"); flagCoding.addFlag("NN_IOOR", 0x0002, "NN input is out of range"); flagCoding.addFlag("NN_OOOR", 0x0002, "NN output is out of range"); product.addFlagCoding(flagCoding); ... Band flagsBand = new Band("atm_corr_flags", ProductData.TYPE_UINT8, w, h); flagsBand.setFlagCoding(flagCoding); product.addBand(flagsBand);`
MetadataAttribute MetadataElement	Provides meta-data for a product. Meta-data is provided as a hierarchical structure. Every product has automatically a meta-data root element. You can add elements to this root element and to your own elements. Actual data is stored in attributes which you assign to the elements.	`MetadataElement root = product.getMetadataRoot(); root.addMetadataElement(new MetadataElement(...));`
ProductUtils	Copy information from one (input) product to another (output) product and many more utility functions for data products.	`ProductUtils.copyBand, ProductUtils.copyTiePointGrid, ProductUtils.copyBitmaskDefs, ProductUtils.copyFlagCodings`
VirtualBand	Create a band whose pixels are computed from other bands, tie-point grids or flag datasets contained in the product.	`String expre = "0.5 * (radiance_1 + radiance_2)"; Band mean12Band = new VirtualBand("mean12_band", 512, 512, expr); product.addBand(mean12Band);`
To be continued

Extend the BEAM Java API

The following table shows all BEAM extension points that are exported to the public use. It gives you an idea of the large possibilities to increase the functionality of BEAM.

Plug-in Interface	Plug-in Registry	Plug-in Description
VisatPlugIn	VisatPlugInManager	Extension point for VISAT user interface extensions. VISAT automatically loads plug-in classes which implement the `VisatPlugIn` interface from the plug-in search path during startup.
CommandListener, CommandAdapter	CommandManager	Extension point for invoking commands from the VISAT user interface. A VISAT plug-in usually registers one or more commands with the command manager.
ProductReader, AbstractProductReader	ProductIOPlugInManager	Extension point for data product readers for different file formats, e.g. BEAM-DIMAP, Envisat N1, MODIS, AVHRR. Once the `ProductIOPlugInManager` or `ProductIO` classes are used by a client program, it automatically loads all plug-ins implementing the `ProductReader` interface from the plug-in search path.
ProductWriter, AbstractProductWriter,	ProductIOPlugInManager	Extension point for data product writers for different file formats, e.g. BEAM-DIMAP, HDF-5, GeoTIFF. Once the `ProductIOPlugInManager` or `ProductIO` classes are used by a client program, it automatically loads all plug-ins implementing the `ProductWriter` interface from the plug-in search path.
MapProjection, MapTransformDescriptor	MapProjectionRegistry	Extension point for map projections, e.g. UTM, Geographic and map coordinate transformations, e.g. Transverse Mercator, Identity. Once the `MapProjectionRegistry` class is used by a client program, it automatically loads all plug-ins implementing the `MapTransformDescriptor` interface from the plug-in search path.
ElevationModelDescriptor	ElevationModelRegistry	Extension point for digital elevation maps (DEM), e.g. GETASSE30. In BEAM 3.x, `ElevationModelDescriptor` plug-ins are not automatically loaded.
Function Symbol	BandArithmetic	Extension point for mathematical functions such as `sin`, `cos`, `exp`, `log` and symbols such as `PI`, `E`, `X`, `Y` to be used in expressions in the band arithmetic. In BEAM 3.x, `Function` and `Symbol` plug-ins are not automatically loaded.

Find out more about the BEAM Java API

The BEAM installation contains some example sourcecode that shall help you developing your own applications. The code can be found in the examples.zip archive located in the root directory of your BEAM installation. The examples cover the following topics:

codesnippets contains little pieces of code ready to use.
data_export shows several ways to read and write geophysical data, tiepoint data, solar fluxes and ground control points using the BEAM-API.
maptrans implements a very simple example map transformation that should give you a good starting point for implementing your own map transformations and make these available in VISAT.
ndvi_processor here is a complete implementation of a processor using the BEAM Processor framework. It has a graphical user interface and is fully integrated in VISAT. All aspects of the framework are covered, namely
- User interface using the parameter framework
- Visat processor plugin implementation
- A request element factory that validates the processing request parameter values
ndvi_simple a simple implementation of an ndvi processor showing the concepts of line-by-line processing of satellite data.

The BEAM web page contains a lot of useful BEAM plug-ins that are free to download. Some of them are supplied with source code. You will also find the BEAM Java API on this web page. The API docs are also found in api-docs.zip in your BEAM installation folder.

You should also consider to review the BEAM source code found in the src.zip archive located in your BEAM installation folder. You can use the Goto definition function in your Java IDE (Ctrl+B in IDEA) on BEAM API classes and methods used in your code.

If you are new to Java, you should take a look at the overwhelming variety of tutorials on Java programming at Sun's Java pages.