How to create a new product reader

Warning

This is a very draft version.

New here? See "how to set up an IDE to develop SNAP extensions"

You can put any number of readers in a modules.

Create new module? See "how to create and configure a SNAP extension module"

Engine Integration

Product readers are snap-engine services.

Java code

create package for example org.esa.snap.dataio.<format-name>
add Java classes
- <FormatName>ProductReaderPlugIn implementing org.esa.snap.core.dataio.ProductReaderPlugIn interface
- <FormatName>ProductReader extending org.esa.snap.core.dataio.AbstractProductReader class

Consider following advices:

when implementing AbstractProductReader
- readBandRasterDataImpl(...)
  - must be thread safe
  - be aware that it can be called in any order
- make sure to implement close() and clean up resource acquired. Especially close input streams.
when implementing ProductReaderPlugIn

- getDecodeQualification(Object input)
  - make sure method always succeeds; ensure that no exception is thrown
  - make sure that it is fast (terminates within milliseconds)
  - make sure method is thread safe
  - use the INTENDED qualification with care; generic readers shall return SUITABLE at most

in general ensure to add appropriate metadata (use e.g. EnvisatProductReader as template)
- to the product
  - add also IndexCoding, GeoCoding, FlagCoding, MetadataElement, Masks, VectorDataNode etc.
- to the product reader by implementing ProductIOPlugIn carefully
- to the module manifest (module.xml)
  - Is there a RGB-Profile associated with this product? If yes, see next section how to provide it to SNAP.

Follow advice given in the API doc of interfaces and super classes.

Add unit-level tests in src/test/java.

Add RGB-Profiles

Example:

RGB-Profiles

public class SpotVgtProductReaderPlugIn implements ProductReaderPlugIn {

    public SpotVgtProductReaderPlugIn() {
        RGBImageProfileManager manager = RGBImageProfileManager.getInstance();
        manager.addProfile(new RGBImageProfile("SPOT VGT RGB-1", new String[] {"MIR", "0.5 * (B2 + B3)", "B0 + 0.1 * MIR"}));
        manager.addProfile(new RGBImageProfile("SPOT VGT RGB-2", new String[] {"B3", "0.5 * (B2 + B3)", "B0 + 0.1 * B3"}));
    }
    ...

Service registration

Create resource directory META-INF/services in src/resources

Add file named org.esa.snap.core.dataio.ProductReaderPlugIn

Edit file, for each product reader add its fully qualified class name on a single line (no spaces, no word wrapping):

org.esa.snap.core.dataio.ProductReaderPlugIn

org.esa.snap.dataio.<format-name>.<FormatName>ProductReaderPlugIn

Desktop GUI Integration

If you don't need any special GUI for your reader other than import actions and / or some help pages, then we don't need writing any Java code. Instead we have to add some NetBeans-specific configuration files to the module. Detailed information on NetBeans module development is given here:

NetBeans Modules API

First step is to create a resources package named for example

org.esa.snap.dataio.<format-name> in src/resources

Then add the layer.xml file with following content:

layer.xml

<filesystem>

	<!-- Define action in Actions/Readers/ -->
    <folder name="Actions">
        <folder name="Readers">
            <file name="org-esa-snap-dataio-Import[Format]Product.instance">
                <attr name="instanceCreate" methodvalue="org.openide.awt.Actions.alwaysEnabled"/>
                <attr name="delegate" methodvalue="org.esa.snap.rcp.actions.file.ImportProductAction.create"/>
                <attr name="displayName" stringvalue="[Format-DisplayName]"/>
                <attr name="formatName" stringvalue="[Format-Name]"/>
                <attr name="useAllFileFilter" boolvalue="true"/>
                <attr name="helpId" stringvalue="import[Format]Product"/>
            </file>
        </folder>
    </folder>

	<!-- Place action into menu File/Import/Optical Sensors/[Format] -->
    <folder name="Menu">
        <folder name="File">
            <folder name="Import">
                <folder name="Optical Sensors">
                    <file name="org-esa-snap-dataio-Import[Format]Product.shadow">
                        <attr name="originalFile" 
                              stringvalue="Actions/Readers/org-esa-snap-dataio-Import[Format]Product.instance"/>
                    </file>
                </folder>
            </folder>
        </folder>
    </folder>

</filesystem>

Add extra module metadata

Most of your module's metadata is derived from your project's Maven pom.xml file. However, some so called module "manifest-headers" cannot be derived from it (e.g. the location of the layer.xml file), so we have to provide them in a special configuration file.

Create source directory src/main/nbm

Add file manifest.mf with following content:

manifest.mf

Manifest-Version: 1.0
AutoUpdate-Show-In-Client: true
AutoUpdate-Essential-Module: true
OpenIDE-Module-Layer: org/esa/snap/dataio/<format-name>/layer.xml
OpenIDE-Module-Java-Dependencies: Java > 1.8
OpenIDE-Module-Display-Category: SNAP

Here is a comprehensive list of all allowed NetBeans "manifest headers": http://bits.netbeans.org/8.0/javadoc/org-openide-modules/org/openide/modules/doc-files/api.html#how-manifest

Warning: lines in this file must not exceed 72 characters. If so, introduce an LF and start new line with a single space character.

Code examples in SNAP

snap-geotiff

snap-hdf5

...