Usage of the mapproj Tool

Introduction

mapproj is a command line tool which lets a user convert BEAM-DIMAP, ENVISAT/MERIS, ENVISAT/AATSR, ERS/ATSR and ENVISAT/ASAR products into map-projected BEAM-DIMAP product format.

ENVI users probably might profit from the fact, that they can directly open a product band's image with ENVI after the product has been converted to the BEAM-DIMAP format. The map-projection information will seemlessly been taken over into ENVI.

Please take a look at the closely related command-line tool pconvert.

Running mapproj

The executable name is mapproj.exe for MS Windows, pconvert.command for Mac OS X and pconvert for UNIX operating systems and is located in the bin directory of your BEAM installation directory.

mapproj is a command-line application and as such it is invoked from a console or shell. UNIX users usually know what a shell is, MS Windows users have to start either command.exe or cmd.exe in order to use mapproj.

NOTE: The BEAM installer does not automatically append the bin directory of the BEAM installation directory to the system's PATH environment variable. If you need to run mapproj from a directory other then bin you have to adjust the PATH variable by your own.

mapproj is implemented as a BEAM processor and therefore has the standard processor command-line interface and also uses processing request files in order to define the input and output product and the processing parameters.

Processing Request Description

The mapproj tool takes a single input product. Map-projection specific parameters are given in a single comma-separated value. Note that BEAM does currently not perform any datum transformations - WGS-84 is assumed in any case. It is possible to define the output map for three different cases:

  1. Given ouput pixel size - ouput easting, northing, product width and height automatically derived from input product. Example processing request file: mapproj-fitted.xml
  2. Given ouput pixel size, easting, northing, product width and height. Example processing request file: mapproj-northing-and-easting.xml
  3. Given ouput pixel size and geographical boundary guaranteed to be within the resulting boundary of the output map. Example processing request file: mapproj-two-points.xml

Note: Since BEAM 3.5 it is possible to use pixel-based geo-codings in the mapproj tool. See the last four parameter descriptions in the following list. To get this working you have to specify in the bands parameter the both bands used by the pixel-based geocoding and also the flags band if used in the geocoding-valid-mask parameter.
Please refer also to the section Tools -> Product Generation Tools -> Pixel-based Geo-Coding.

Processing Parameters

Given in the following is the list of all relevant processing parameters. The definition of the actual map-projection is the same in all three cases:

Parameter Name Description> Type Case
type Request type. Mandatory attribute of the Request element. Value is always "MAP_PROJECTION". String all
bands Comma separated list of names of the input band to be processed. The parameter is optional, if omitted all bands are processed. If used with a pixel-based geo-coding remember to include both bands used by the geo-coding and also the flags band if used in the geocoding-valid-mask parameter List of strings 1, 2 and 3
projection_name The name of a map-projection known by BEAM. For valid map-projection names, please refer to the chapter Available Map Projections. Mandatory parameter, no default value provided. String 1, 2 and 3
projection_parameters Comma-separated list of projection specific parameters. For valid map-projection values, please refer to the chapter Available Map Projections. You can also refer to VISAT's map-projection tool under Projection Parameters. Parameters are entered there in the same units and same order. projection_parameters are optional, if not given, default values are used. List of numbers 1, 2 and 3
orthorectification If set to "true" the output product is orthorectified. If not given the default ("false") is used. Boolean 1, 2 and 3
orthorectification_dem The name of the digital elevation model which is used for orthorectification. If not specified or not available, the elvevation provided by the input product is used. String 1, 2 and 3
resampling_method The name of the resampling method which should be used. Names of supported methods are "NEAREST_NEIGHBOUR", "BILINEAR_INTERPOLATION", "CUBIC_CONVOLUTION". If not given "NEAREST_NEIGHBOUR" is used. String 1, 2 and 3
pixel_size_x The pixel size in map units in X direction of the output map, e.g degree for Geographic Lat/Lon, meters for UTM, Transverse Mercator and Lambert Conformal Conic. Mandatory parameter, no default value. Number 1, 2 and 3
pixel_size_y The pixel size in map units in Y direction of the output map, e.g degree for Geographic Lat/Lon, meters for UTM, Transverse Mercator and Lambert Conformal Conic. Mandatory parameter, no default value. Number 1, 2 and 3
fit_output If set to true, ouput easting, northing, product width and height automatically derived from input product. Default value is false. Boolean 1 only
easting The easting (map-X value) in map units of the center of upper left pixel in the output map. Number 2 only
northing The northing (map-Y value) in map units of the center of upper left pixel in the output map. Number 2 only
output_width The width in pixles of the resulting output product. Number 2 only
output_height The height in pixles of the resulting output product. Number 2 only
west_lon The west longitude in degree which is guaranteed to be within the resulting geographical boundary of the output map. Number 3 only
east_lon The east longitude in degree which is guaranteed to be within the resulting geographical boundary of the output map. Number 3 only
north_lat The north latitude in degree which is guaranteed to be within the resulting geographical boundary of the output map. Number 3 only
south_lat The south latitude in degree which is guaranteed to be within the resulting geographical boundary of the output map. Number 3 only
geocoding_latitudes The band containing latitude values to process a product with a PixelGeoCoding.
This band must be included in the bands parameter. 		String 1, 2 and 3
geocoding_longitudes The band containing longitude values to process a product with a PixelGeoCoding.
This band must be included in the bands parameter. 		String 1, 2 and 3
geocoding_valid_mask The valid mask expression is used to identify valid lat/lon pairs, e.g. "NOT l1_flags.INVALID". Can be null if a valid mask is not used.
Referenced bands must be included in the bands parameter. 		String 1, 2 and 3
geocoding_search_radius The search radius in pixels, shall depend on the actual spatial scene resolution, e.g. for 300 meter pixels a search radius of 5 is a good choice. Number 1, 2 and 3