Pixel Extraction |

### Introduction

Basically, the Pixel Extraction Tool allows to extract the pixel values given by a user-specified list of geographic coordinates from a given list of data products. However, a number of additional parameters may be passed to the tool, for example the size of the area around the geographic coordinate which is to be considered.

### The Output Format

The Pixel Extraction Tool generates output in the widely used and very general CSV-format, using tabstops as separators.
It writes a file for each product type it has found within its input products (such as MER_FRS), each starting with a header looking like this:
`# SNAP pixel extraction export table
#
# Window size: 1
# Expression: l1_flags.LAND_OCEAN
# Created on: 2010-09-17 14:53:21
`
The header is followed by the table with the actual data; it might look like the following:

Expression result | ProdID | CoordID | Name | Latitude | Longitude | PixelX | PixelY | Date(yyyy-MM-dd) | Time(HH:mm:ss) | radiance_1 | radiance_2
true | 0 | 1 | pin_1 | 41.31899 | 2.1386652 | 459.0 | 853.0 | 2003-08-09 | 12:14:16 | 157.6424 | 163.6796
true | 1 | 1 | pin_1 | 41.31899 | 2.1386652 | 459.0 | 853.0 | 2005-08-09 | 18:15:26 | 234.534 | 143.423
false | 3 | 2 | pin_2 | 43.3452 | 12.1232 | 539.0 | 533.0 | 2001-07-05 | 12:07:86 | 423.522194 | 156.625496

In the following table, the entries are explained in detail.

Field | Description
--- | ---
Expression result | True if the value matches the expression, false otherwise. Is omitted when expression is used for filtering.
ProdID | An ID for the product with relevance within the extracted data.
CoordID | An ID for the coordinate with relevance within the extracted data.
Name | The coordinate's name, if available.
Latitude | The coordinate's latitude value.
Longitude | The coordinate's longitude value.
PixelX | The data product's pixel value in x direction corresponding to the latitude value.
PixelY | The data product's pixel value in y direction corresponding to the longitude value.
Date(yyyy-MM-dd) | The data product's sensing date.
Time(HH:mm:ss) | The data product's sensing time.
radiance_1 | Exemplary: the first of the bands considered for value extracting.
radiance_2 | Exemplary: the second of the bands considered for value extracting.

### The User Interface

The user interface of the Pixel Extraction Tool consists of two panes. The first is an Input/Output-pane, which allows the user to specify

- the input paths of the products that shall be considered
- an output directory for the extracted values
- a prefix the output files shall share
- a field that allows the user to extract the time from the product filename. This field may come in handy when there are products that don't carry time information readable by the product reader.

The Input/Output-pane is explained in detail within the next section. The second pane is dedicated to specify a number of parameters and is explained thoroughly in the section after the next.

#### The Input/Output Pane

The Input/Output Pane allows to specify the input products and the output mode.

The Input/Output Pane

Input paths: The list contains the data products already chosen for extraction as well as paths to be searched for data products. Using the -Button, data products can be added to the list in multiple ways:

- Add product(s)... by choosing a product already opened in the Sentinel Toolbox. In front of the products name you can see the index of the product e.g. [1].
  See line 1 of "Source paths:" field in the Input/Output Pane above.
- Add product file(s)... by choosing one or more products from the file system.
  See line 2 of "Source paths:" field in the Input/Output Pane above.
- Add directory(s)... by specifying one or more directories and defining a search pattern e.g. "*.nc* for netcdf products.
  See line 3 of "Source paths:" field in the Input/Output Pane above.
- Add directory recursively... or by specifying a directory recursively (indicated by '**' in the list) and defining a search pattern e.g. "*.dim* for DIMAP products.
  See line 4 of "Source paths:" field in the Input/Output Pane above.

Time extraction: If the products carry no time information that is readable by the reader, it is possible to extract the time information from the product filename. In order to do so, the date/time pattern needs to be provided. This date pattern can be composed of the following components:

- year, given as yyyy
- month, given as MM
- days in month, given as dd
- day in year, given as DDD
- hour of day, in 12 hour format, given as hh
- hour of day, in 24 hour format, given as HH
- minute of hour, given as mm
- second of minute, given as ss

, which may appear in arbitrary order. Following some examples which for date format to parse by pattern:

- `yyyyMMdd` would parse a string like `20111103` and leads to a date `2011-11-03 00:00:00 UTC`
- `yyyyMMdd_hh_mm_ss` would parse a string like `20061126_08_56_12` and leads to a date `2006-11-26 08:56:12 UTC`
- `yyyyMMdd-HH:mm:ss` would parse a string like `20170610-12:36:46` and leads to a date `2017-06-10 12:36:46 UTC`
- `yyyyDDD` would parse a string like `2010159` and leads to a date `2010-06-08 00:00:00 UTC`

The pattern in the filename needs to be provided, in order to tell the software where the pattern occurs within the filename and if it is the start or end date. The pattern must contain at least one of the placeholders `${startDate}` and `${endDate}`. Examples:

- `sst_*_${startDate}.nc`
- `sst_*_${startDate}_${endDate}*.nc`
- `LC8......${startDate}*.nc`

The '`*`' is a placeholder for multiple characters while the '`.`' is a placeholder for a single character.

Output directory: All output is written to the selected directory.

File prefix: The specified file prefix is used to prefix the files which are written.

#### The Parameters Pane

The Parameters Pane allows to specify several parameters used for the extraction.

The Parameters Pane

Coordinates: The coordinates table shows the user-specified geographic coordinates which are used to extract the values. They consist of a name and their latitude/longitude-values. Initially, the table is filled with the pins of the product currently selected in the Sentinel Toolbox. Additional coordinates may be added by

- creating new coordinates
- reading them from a pin file. In addition to the standard format of a pin file, the coordinates file can have a 'DateTime' column. The format of the time value follows the ISO8601 pattern: yyyy-MM-dd'T'HH:mm:ss. UTF-8 encoding is preferred.
  Example:

      Name	Lon	Lat	DateTime
      P1	29.8410	31.1748	2009-06-07T08:27:11
      P2	31.2213	31.5987	2009-06-07T08:27:04
      P3	32.3835	31.1532	2009-06-07T08:27:03

- reading them from a file in the output CSV-format described above. This allows to compare the results from multiple runs of the Pixel Extraction Tool.

Allowed time difference: Specifies how big the difference might be between the time of a pixel and the time of the coordinate.

Export: Specifies if bands, tie-point grids and/or masks should be included in the output.

Window size: The window size specifies the number of pixels surrounding the pixels derived from the given geographic coordinates to be exported. That is, when setting the window size to 3, the values for 3x3=9 pixels will be extracted. The window size must be odd.

Pixel value aggregation method: The user can choose between a number of aggregation methods when a window size bigger than 1x1 is used. Choosing such an aggregation method, the pixel values from the window are all aggregated, so that only a single aggregated value for each coordinate will be exported. If no aggregation is selected, values of all pixels in the window will be exported. The aggregation methods that may be used are:

- min, exports the minimum of the window values
- max, exports the maximum of the window values
- mean, exports mean and standard deviation of the window values
- median, exports the median of the window values

Expression: A band maths expression can be specified to filter the values to output. The "Edit Expression..."-button opens the expression editor, which can be used for easily editing an expression. It is only available if the input product list of the "Input/Output"-pane contains at least one data product; however, in any case an expression may manually be declared.
There are two options of how to use the expression: either the expression is used to filter the values to output, that is, values which do not satisfy the expression are ignored. In the other case, the information of the value met the expression is added to the output. The specified aggregation will be performed if at least one pixel is marked as valid by this expression within the aggregation window.

Sub-scenes: Enables the export of sub-scenes. The scenes contain at least all coordinates (including the specified window) found in one product. Additionally the size of a border can be specified by which the exported scene size extended.

Google Earth output: All output coordinates are collected in one KMZ file, which can be used to display the points in Google Earth.

Match with original input: The pixel extraction allows outputting of correlative data together with the data that is extracted. This checkbox is only enabled if coordinates that carry correlative data have been added.

Copyright © 2010 by Brockmann Consult (beam-issues@brockmann-consult.de). All rights reserved.