Usage of the `pconvert` Tool |

### Introduction

`pconvert` is a command line tool which lets a user convert BEAM-DIMAP, ENVISAT/MERIS, ENVISAT/AATSR, ERS/ATSR and ENVISAT/ASAR products into BEAM-DIMAP or HDF-5 product formats. The tool can also generate greyscale and RGB images in TIFF, JPEG, PNG and BMP image formats.

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.

### Running pconvert

For executing the pconvert tool there is an executable script file located in the `bin` directory of your Sentinel Toolbox installation directory. The file name is `pconvert.bat` for MS Windows, `pconvert` for Mac OS X and `pconvert.sh` for UNIX operating systems.

`pconvert` 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 `pconvert`.

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

### Examples

The following examples assume that you

- have opened a shell or console window (on MS Windows either command.exe or cmd.exe)
- have copied a test product to your `$S3TBX-INSTALL-DIR$/bin` directory (in the following examples referred to as `MER_RR__1P_TEST.N1` - a MERIS Level 1B product)
- and that you have changed the current working directory to be the `bin` directory.

`> pconvert -f tif -b 7,5,2 MER_RR__1P_TEST.N1` Creates a TIFF RGB image from the bands R=7, G=5, B=2 with the name `MER_RR__1P_TEST.N1.tif` which will be written into the current working directory.

`> pconvert -f jpg -r 512,512 -b 13 MER_RR__1P_TEST.N1` Creates a JPEG greyscale image from band 13 with the name `MER_RR__1P_TEST.N1.jpg`. The image will have a maximum size of 512 x 512 pixels.

`> pconvert -f h5 MER_RR__1P_TEST.N1` Converts the entire product into a single HDF-5 file with the name `MER_RR__1P_TEST.N1.h5`.

`> pconvert -f tifp MER_RR__1P_TEST.N1` Converts the entire product into a single GeoTIFF file with the name `MER_RR__1P_TEST.N1.tif`.

`> pconvert MER_RR__1P_TEST.N1` Converts the entire product into the MERIS/(A)ATSR Toolbox's standard BEAM-DIMAP product format. The Sentinel Toolbox and the data processors will be able to open the output product directly. The output file will have the name `MER_RR__1P_TEST.N1.dim`. Additionally a directory `MER_RR__1P_TEST.N1.data` will be created. It includes the raw data for the product's geophysical tie-point grids and bands.

### Usage

The following usage text is the output of the `pconvert` tool if you call it without any arguments or if you specify the option `-?`.

    Usage: pconvert [<options>] <file-1> [<file-2> <file-3> ...]

      where the <file-i> are the input data products and <options>
      can be a combination of the following options:

      -f or --format <ext>
         Specifies output format and file extension,
         possible values for <ext> are
           For product conversion:
             dim  - BEAM-DIMAP product format
             h5   - HDF5 product format
             tifp - GeoTIFF product format
           For image conversion:
             png  - Portable Network Graphics image format
             jpg  - JPEG image format
             tif  - GeoTIFF image format
             bmp  - Microsoft Bitmap image format
           Note:
             If image conversion is selected the product must at least
             contain three bands to create an image.
             If this is not the case, you must use one of the options -b or -p
             to define the image content.
         The default value is "-f dim"
      -b or --bands <i> or <iR>,<iG>,<iB> or <i1>,<i2>,<i3>,<i4>...
         Don't use this option in combination with option -p.
         Specifies indices of the bands to be exported as a comma separated
         index list, 1 (one) corresponds to the first band.
         For image output, the number of bands should be 1 (greyscale) or
         3 (RGB), the default value is "-b 8,5,2" (optimized for MERIS).
         For product output, the default value includes all bands.

      -p or --rgb-profile <file-path>
         Valid for greyscale or RGB image output only.
         Don't use this option in combination with option -b.
         Specifies the file path to a text file containing an mathematic
         band expression for each of the RGB channels.
         The syntax of the file is as follows:
             red = <red-expression>
             green = <green-expression>
             blue = <blue-expression>
         It is also possible to use r, g and b instead of red, green and blue.
         Empty lines and lines beginning with the '#' character are ignored.

      -s or --histo-skip <lower>,<upper>
         Valid for greyscale or RGB image output only.
         Specifies the amount of pixels in percent to be skipped from the
         lower resp. upper end of each of the histograms of the R,G and B
         channels. For image output, the default value is "-s 1.0,4.0"
         For product output, the option is ignored.

      -m or --histo-match <algorithm>
         Valid for greyscale or RGB image output only.
         Specifies the histogram matching algorithm to be applied.
         Possible values for <algorithm> are:
             off - no histogram matching
             equalize - force an equalized output histogram
             normalize - force a normalized output histogram
         the default value is "-m off".

      -c or --color-palette <file-path>
         Valid only for image output of a single band.
         Specifies the file path to a text file containing a colour
         palette definition.

      -n or --no-data-color <red>,<green>,<blue>[,<alpha>]
         Valid for greyscale or RGB image output only.
         Specifies the colour that should be used for the no-data layer.
         The alpha value is optional. All component values have to be between
         0 and 255. An alpha value of 255 means fully opaque and 0 means
         fully transparent.

      -r or --max-res <x-res>,<y-res>
         Specifies the maximum image output size in pixels, for example 512,512.
         By default, the full product scene size is taken.
         This option can't be combined with -H or -W

      -W or --width  <width>
         Forces the specified image output width in pixels, for example 512.
         The image aspect ratio will be preserved.
         This option can't be combined with -r or -H

      -H or --height  <height>
         Forces the specified image output height in pixels, for example 512.
         The image aspect ratio will be preserved.
         This option can't be combined with -r or -W

      -o or --outdir <dir-path>
         Specifies the output directory.
         The default value is the current working directory.

      -d or --debug
         Turns the debug mode on.

      -? or -h or --help
         Prints this usage help.