Learning Targets

Setup an IDE project for BEAM
Get used to the IDE
Write a quicklook generator
1. Open an AATSR TOA product
2. Print out some product information
3. Retrieve the bands of the product
4. Create the quicklook image
5. Write the quicklook image
Become acquainted with BEAM core classes
- ProductIO
- Product
- Band
- ProductUtils

Setup an IDE project for BEAM

IntelliJ IDEA

Create new project

Start IDEA
In the File menu, select New Project
Select Create project from scratch
Click Next
Enter a project Name: Ex1
Choose Project files location
Click Next
Click Finish

Setup the JDK (Java Development Kit)

Right-click project Ex1 in the Project view
Click menu entry Module Settings
Select Project on the left side
If a project JDK is already configured (version 1.6 or higher) you can skip the following steps.
Click on the New button next to the drop-down box with <No JDK>.
Select from the upcoming drop-down box JSDK
Navigate to the home directory of the JDK. On Windows it is by default located at %Program Files%/java
Select the jdk<version>, e.g. jdk1.6.0_18
Click OK.
Close the Project Structure window by clicking on OK.

Define and attach the BEAM Library

Right-click project Ex1 in the Project view
Click menu entry Module Settings
Select Global Libraries on the left side
Click the plus button New Global Library
- Enter Library name: BEAM-4.6, click OK
- Accept following dialog with OK
Click Attach Jar Directories... and select directory %BEAM4_HOME%/lib, click OK
Click Add Classes... and select the JARs ceres-core, ceres-binding, ceres-glayer, ceres-jai, beam-core and beam-envisat-reader contained in %BEAM4_HOME%/modules
- Click Attach Documentation
  - Expand %BEAM4_HOME%/beam-4.6-apidoc.zip, click OK
  - Select path within archive: beam-4.6-apidoc, click OK
- Click Attach Sources
  - Select %BEAM4_HOME%/beam-4.6-sources.zip, click OK
  - Accept following dialog with OK
- Click OK

Create a new Class

Right-click entry Ex1/src in Project view
- Click New/Java Class
- Enter Name: Ex1
- Click OK

Create and run the `main` Method

In the code editor, write psvm into the class, press CTRL+J (Insert Live Template) and approve selection of main() method declaration in order to generate the method. Add a simple line print to the method.

public class Ex1 {
    public static void main(String[] args) {
        System.out.println("Hello BEAM!");
    }
}

Click with the right mouse button in to the code editor and select from the context menu Run Ex1.main() You should see Hello BEAM! in the Run view.

Eclipse

Create new project

Start Eclipse
In the File menu, select New and select Java Project
Enter Project Name: Ex1
Click Finish

Define and attach the BEAM Library

Right-click project Ex1 in the Package Explorer view
Click menu entry Properties
Select group Java Build Path, select tab Libraries
Click Add Library...
- Select User Library
- Click Next >
- Click User Libraries...
- Click New...
  - Enter User library name: BEAM-4.6, click OK
  - Click Add JARs... and select all JARs contained in %BEAM4_HOME%/lib, click OK
  - Click Add JARs... and select the JARs ceres-core, ceres-binding, ceres-glayer, ceres-jai, beam-core and beam-envisat-reader contained in %BEAM4_HOME%/modules
- Expand entry beam-core in JAR list
- Double-click entry Javadoc location
  - Select Javadoc in archive
  - Click (behind Archive path:) Browse...
  - Select %BEAM4_HOME%/beam-4.6-apidoc.zip, click OK
  - Enter into Path within archive:, beam-4.6-apidoc, click OK
- Double-click entry Source attachment
  - Click External File...
  - Select %BEAM4_HOME%/beam-4.6-sources.zip, click OK
- Click OK
Click Finish
Click OK

Create a new Class

Right-click entry Ex1/src in Package Explorer
- Click New/Class
- Enter Name: Ex1
- Click Finish

Create and run the `main` Method

In the code editor, write main into the class, press CTRL+SPACE (Content Assist) and select main - main method in order to generate the method. Add a simple line print to the method.

public class Ex1 {
    public static void main(String[] args) {
        System.out.println("Hello BEAM!");
    }
}

and press the Run icon in the main tool bar. You should see Hello BEAM! in the Console view.

BEAM core classes

We want to start the program by reading an AATSR product. A convenient entry point into the BEAM API is the ProductIO class, which is used to read and write data product files. If you are familiar with a modern IDE you can skip the following sections and immediately enter the source code below.

IntelliJ IDEA

First lines of code

Generate an import statement

Type ProductIO into the main method and press CTRL+Space. IntelliJ IDEA will display a pop-up list with classes matching the word just typed. Select the first entry of the list by typing RETURN in order to generate the import statement for the ProductIO class.

Generate a method call

Then place a dot after the ProductIO word and press CTRL+SPACE again. IntelliJ IDEA displays the list of ProductIO methods. Select the readProduct method with the String argument. The first argument of the readProduct method is the product file path which we want to pass in as a command line parameter, the second method argument shall be set to null. Press CTRL+Q if you want to see the java documentation.
Finalise the call with a semicolon.

Generate exception handler

You will notice that the statement is now underlined by curly read line. This signals a syntax error, in this case caused by the fact that the readProduct method throws a checked exception which is still not caught. Place the cursor on the statement and press ALT+RETURN, select Surround with try/catch:

Generate local variable

The readProduct returns an object of type Product. The Product class is the most important and most frequently used class in the BEAM source code. Place the cursor on the readProduct method and press CTRL+ALT+V (Introduce Variable) in order to generate a local variable for the return value of the method call. Press RETURN to accept the suggested variable name product.

If the call did not throw any exception, we want to print the product's name, otherwise the exception message is printed:

import java.io.IOException;

import org.esa.beam.framework.dataio.ProductIO;
import org.esa.beam.framework.datamodel.Product;

public class Ex1 {
    public static void main(String[] args) {
        String filePath = args[0];
        try {
            System.out.println("Loading product: " + filePath);
            Product product = ProductIO.readProduct(filePath, null);
            System.out.println("Product loaded: " + product.getName());
        } catch (IOException e) {
            System.out.println("I/O error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Run

If you run the program, you will notice an ArrayIndexOutOfBoundsException caused by the args[0] since no arguments have been passed to your program and thus the args array is still empty.

In the main tool bar,

open the menu of Ex1 run button
click the EditConfigurations... entry
enter Program parameters: %AATSR-TOA-FILE% (= the location of the AATSR TOA L1B file)
Click OK

When running Ex1 again the program should now produce the expected output in the Run view.

Accessing Bands

Add the following code snippet before the catch statement:

Band[] bands = product.getBands();
for (Band band : bands) {
    System.out.println(band.getName());
}

After running the code you should see the list of band names. These are the names used to access particular bands of a data product, in this case the bands of an AATSR TOA product.

If you are new to IntelliJ IDEA, try typing the above code by frequently using the IDE's Content Assist (CTRL+SPACE):

type p, press CTRL+SPACE,
type ., select getBands() from suggestion list
press CTRL+ALT+V, press *RETURN" to accept name bands
press RETURN to proceed to the next line, type iter, press CTRL+J, select Iterate Iterable and press two times RETURN to accept suggested names.
in the loop body type System.out.println(band.getName()); (use CTRL+SPACE!)

In order to get a quick overview of all the key bindings in IntelliJ IDEA, got to the Help/Productivity Guide in the main menu.

Eclipse

First lines of code

Generate an import statement

Type ProductIO into the main method and press CTRL+SPACE. Eclipse will display a pop-up list with classes matching the word just typed. Select the first entry of the list by typing RETURN in order to generate the import statement for the ProductIO class.

Generate a method call

Then place a dot after the ProductIO word and press CTRL+SPACE again. The IDE displays the list of ProductIO methods. Select the readProduct method with the String argument. The first argument of the readProduct method is the product file path which we want to pass in as a command line parameter, the second method argument shall be set to null. Also note the displayed java documentation. Finalise the call with a semicolon.

Generate exception handler

You will notice that the statement is now underlined by curly read line. This signals a syntax error, in this case caused by the fact that the readProduct method throws a checked exception which is still not caught. Place the cursor on the statement and press CTRL+1 (Quick Fix), select Surround with try/catch:

Generate local variable

The readProduct returns an object of type Product. The Product class is the most important and most frequently used class in the BEAM source code. Select the entire call statement and press SHIFT+ALT+L (Insert Local Variable) in order to generate a local variable for the return value of the method call. Enter Variable name: product and press OK.

If the call did not throw any exception, we want to print the product's name, otherwise the exception message is printed:

import java.io.IOException;

import org.esa.beam.framework.dataio.ProductIO;
import org.esa.beam.framework.datamodel.Product;

public class Ex1 {
    public static void main(String[] args) {
        String filePath = args[0];
        try {
            System.out.println("Loading product: " + filePath);
            Product product = ProductIO.readProduct(filePath, null);
            System.out.println("Product loaded: " + product.getName());
        } catch (IOException e) {
            System.out.println("I/O error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Run

If you run the program, you will notice an ArrayIndexOutOfBoundsException caused by the args[0] since no arguments have been passed to your program and thus the args array is still empty.

In the main tool bar,

open the menu of Run button
click the Run Configurations... entry
select the tab Arguments
enter Program Arguments: %AATSR-TOA-FILE% (= the location of the AATSR TOA L1B file)
Click Run

The program should now produce the expected output in the Console view.

Accessing Bands

Add the following code snippet before the catch statement:

Band[] bands = product.getBands();
for (Band band : bands) {
    System.out.println(band.getName());
}

After running the code you should see the list of band names. These are the names used to access particular bands of a data product, in this case the bands of an AATSR TOA product.

If you are new to the Eclipse IDE, try typing the above code by frequently using the IDE's Content Assist (CTRL+SPACE):

type p, press CTRL+SPACE
select product from suggestion list
type ., select getBands() from suggestion list
mark expression product.getBands() in editor, press SHIFT+ALT+L, enter name bands
press RETURN, type for, press CTRL+SPACE, select foreach
in the loop body type System.out.println(band.getName()); (use CTRL+Space!)

In order to display a quick overview of all the key bindings in the IDE, press CTRL+SHIFT+L.

Writing a 1-band image

We now want to create a greyscale image of band btemp_nadir_1200. Place following code after the for loop:

Band btempNadir1200 = product.getBand("btemp_nadir_1200");
BufferedImage image = btempNadir1200.createRgbImage(ProgressMonitor.NULL);
File imageFile = new File(btempNadir1200.getName() + ".png");
System.out.println("Writing image: " + imageFile);
ImageIO.write(image, "PNG", imageFile);
System.out.println("Image written: " + imageFile);

The createRgbImage method creates an image from a band. The parameter ProgressMonitor.NULL means, we don't need progress monitoring for now. The return value is a BufferedImage defined the standard Java package java.awt. Also ImageIO is a standard Java class which lets you read images from and write images to common formats such as PNG, JPEG, TIFF, BMP.
Run the program. The image file will be written into the Ex1 folder of the workspace. Inspect the image in a viewer.

Writing a 3-band RGB image

We can utilise the BEAM ProductUtils class for creating true RGB images:

Band[] rgbBands = new Band[] {
    product.getBand("reflec_nadir_0870"),
    product.getBand("reflec_nadir_0670"),
    product.getBand("reflec_nadir_0550")
};
ImageInfo imageInfo = ProductUtils.createImageInfo(rgbBands, true, ProgressMonitor.NULL);
image = ProductUtils.createRgbImage(rgbBands, imageInfo, ProgressMonitor.NULL);
imageFile = new File(product.getName() + ".png");
System.out.println("Writing RGB image: " + imageFile);
ImageIO.write(image, "PNG", imageFile);
System.out.println("RGB Image written: " + imageFile);

Class diagram

The following UML class diagram shows the relationships between the BEAM API classes introduced in this exercise:

Previous - Preparation	Up - BEAM 4 Programming Tutorial	Next - Cloud Masking Tool

Exercise 1 - Quicklook Generator

Learning Targets

Setup an IDE project for BEAM

Create new project

Setup the JDK (Java Development Kit)

Define and attach the BEAM Library

Create a new Class

Create and run the `main` Method

Create new project

Define and attach the BEAM Library

Create a new Class

Create and run the `main` Method

BEAM core classes

First lines of code

Generate an import statement

Generate a method call

Generate exception handler

Generate local variable

Run

Accessing Bands

First lines of code

Generate an import statement

Generate a method call

Generate exception handler

Generate local variable

Run

Accessing Bands

Writing a 1-band image

Writing a 3-band RGB image

Class diagram

Labels

Exercise 1 - Quicklook Generator

Learning Targets

Setup an IDE project for BEAM

Create new project

Setup the JDK (Java Development Kit)

Define and attach the BEAM Library

Create a new Class

Create and run the main Method

Create new project

Define and attach the BEAM Library

Create a new Class

Create and run the main Method

BEAM core classes

First lines of code

Generate an import statement

Generate a method call

Generate exception handler

Generate local variable

Run

Accessing Bands

First lines of code

Generate an import statement

Generate a method call

Generate exception handler

Generate local variable

Run

Accessing Bands

Writing a 1-band image

Writing a 3-band RGB image

Class diagram

Labels

Create and run the `main` Method

Create and run the `main` Method