Using INTAMAP

INTAMAP Clients

The INTAMAP Java API

Download and installation instructions describe how to obtain the API and install it. This page explains how to use the Java API in your own applications to enable easy access to the INTAMAP interpolation service. Examples of usage are given.

Requests and Responses

A request to the interpolation service is modelled by the InterpolateRequest class, and a response is modelled by the InterpolateResponse class. The InterpolateService class communicates with the interpolation service to send requests and receive responses.

To create a request, simply create an instance of InterpolateRequest. A request, at a minimum, must contain either a collection of observations to interpolate or details of a Sensor Observation Service to gather observations to interpolate from. It is important to note that the service will not interpolate observations with locations specified in the WGS84 coordinate system (latitude/longitude. InterpolateRequest instances and other objects used in requests can also be created using the parsers provided by the API. The InterpolateRequest class provides several methods to allow parameters of the request to be modified before they are sent to the service. The following parameters can be set:

To send the request, an instance of InterpolateService should be created. You can specify the URL to the service you wish to use in the constructor. The sendRequest method can then be used to send the request to the service, and a InterpolateResponse instance is returned. If the interpolation service returns an error, a InterpolateException is thrown containing details of this error.

The InterpolateResponse class returned by the sendRequest method will contain the outputs returned by the service. It is possible to access these outputs, which are parsed as objects by InterpolateService, directly by calling the accessor methods in the class. The following outputs can be accessed:

Generators are also provided to create data in various formats by simply passing an InterpolateResponse instance.

Parsers

The org.intamap.parsers package contains classes able to parse commonly used data formats to create objects used by the interpolation service.

StringParser

Provides methods to create an ObservationCollection instance from a CSV file or a string of x, y, z values. The ObservationCollection can then be used to create a request to send to the interpolation service.

XmlParser

Provides methods to parse various XML formats into objects used by the service. Supported formats are:

Generators

The org.intamap.generators package contains classes able to generate data in various formats from a response returned by the interpolation service.

ImageGenerator

Generates images of predicted statistics (e.g. a map of mean temperature values across a spatial domain) from InterpolateResponse instances. Each pixel in the image represents a location in the prediction domain and is given a colour value related to how high or low that value is. The range used to determine how high or low a value is is calculated automatically from the set of values, or alternatively can be explicitly set. The colour scheme and number of colours to use can also be set using classes from the quickplot.colours package.

GeoTIFFGenerator

Generates GeoTIFF files of statistic predictions from InterpolateResponse instances. GeoTIFFs can only be created if the observations interpolated by the service have a CRS. Uses ImageGenerator to create images, therefore the same parameter modifications are available.

ValuesGenerator

Generates arrays of values for statistic predictions or realisations from an InterpolateResponse instance.

Examples

Generating GeoTIFFs from observations in a CSV file

  1. Import the observations in a CSV file using the StringParser. Each row in the file should represent an observation and have three or four columns: the x coordinate of the feature of interest, the y coordinate of the feature of interest, the result, and optionally the standard deviation. The CSV file should not contain a header. The optional second parameter of the parseCSV method is the SRID of the observations. This parameter is required if you wish to create GeoTIFF files. In this example we are using EPSG:27700 (British National Grid).

    The example CSV file can be downloaded here.

    Example copyright: Annual mean measurements of NO2 for 2007, obtained from diffusion tube monitoring points. Data supplied by the UK National Air Quality Archive at http://www.airquality.co.uk. Data is © Crown copyright 2007, but may be reused if the source and copyright status is acknowledged. File csvFile = new File("example-observations.csv");
    ObservationCollection observations = StringParser.parseCSV(csvFile, 27700);
  2. Create an InterpolateRequest instance using the parsed ObservationCollection. It is possible to modify the request by calling a number of methods on this object. In this example, we will turn on outlier detection and set the method to "automap". InterpolateRequest request = new InterpolateRequest(observations);
    request.setOutlierDetection(true);
    request.setMethodName("automap");
  3. Add the statistics you wish to predict. In this example, we will request the mean, the variance, and the probability of exceeding 0.12. request.addStatisticToPredict("Mean");
    request.addStatisticToPredict("Variance");
    request.addStatisticToPredict("ProbabilityGreaterThan", 0.12);
  4. Create an InterpolateService instance and send the request. InterpolateService service = new InterpolateService("http://intamap.aston.ac.uk:8080/intamap/WebProcessingService");
    InterpolateResponse response = service.sendRequest(request);
  5. Create a GeoTIFFGenerator instance and generate GeoTIFFs. File outputFolder = new File("geotiffs");
    if (!outputFolder.isDirectory()) outputFolder.mkdir();
    GeoTIFFGenerator generator = new GeoTIFFGenerator();
    ArrayList<File> generatedFiles = generator.generateGeoTIFFs(response, outputFolder);
  6. A GeoTIFF will be generated for each statistic in the response. References to the generated files are returned by the generateGeoTIFFs method.

The complete code for this example, including necessary try/catch block:

try {
    // parse csv file
    File csvFile = new File("example-observations.csv");
    ObservationCollection observations = StringParser.parseCSV(csvFile, 27700);

    // create request
    InterpolateRequest request = new InterpolateRequest(observations);
    request.setOutlierDetection(true);
    request.setMethodName("automap");

    // add statistics to predict
    request.addStatisticToPredict("Mean");
    request.addStatisticToPredict("Variance");
    request.addStatisticToPredict("ProbabilityGreaterThan", 0.12);

    // send request
    InterpolateService service = new InterpolateService("http://intamap.aston.ac.uk:8080/intamap/WebProcessingService");
    InterpolateResponse response = service.sendRequest(request);

    // generate geotiffs
    File outputFolder = new File("geotiffs");
    if (!outputFolder.isDirectory()) outputFolder.mkdir();
    GeoTIFFGenerator generator = new GeoTIFFGenerator();
    ArrayList<File> generatedFiles = generator.generateGeoTIFFs(response, outputFolder);
    for (File file : generatedFiles) {
        System.out.println("Generated " + file.getName());
    }
}
catch (ParserException e1) {
    System.err.println("Error parsing CSV file. " + e1.getMessage());
}
catch (IOException e2) {
    System.err.println("Could not open CSV file/write GeoTIFFs. " + e2.getMessage());
}
catch (InterpolateException e3) {
    System.err.println("INTAMAP returned an error during interpolation. " + e3.getMessage());
}
catch (GeneratorException e4) {
    System.err.println("Error generating GeoTIFFs. " + e4.getMessage());
}

Skeleton main method

A skeleton main method to use as a base for implementing the INTAMAP API, org.intamap.main.SkeletonMain, is included in the source code. This method takes two arguments: the path to a CSV file containing observations, and the EPSG code of these observations. The CSV file is parsed and interpolation is performed using the INTAMAP service. GeoTIFFs are generated from the predicted values returned by the service and saved in the current working directory.

Extending the API

If you are using a modified version of the INTAMAP interpolation service, it is possible to extend the API to accomodate these modifications. Understanding of the request and response XML documents defined in the OGC Web Processing Service standard is required.

Additional inputs and outputs can be added to the request and response objects by creating a subclasses of InterpolateRequest and InterpolateResponse respectively. A subclass of InterpolateService must be created so the additional inputs and outputs are dealt with by the service. The subclass must override the generateRequestDocument and parseResponseDocument methods.

The generateRequestDocument should initially call the overridden method in the superclass to get a base XMLBeans ExecuteDocument object. The additional inputs and outputs can then be added to this object. The parseResponseDocument should initially call the overridden method in the superclass to get a base InterpolateResponse object. The additional outputs from the modified service can then be parsed from the XMLBeans ExecuteResponseDocument.