SARINGESTAOI

Description

SARINGESTAOI imports and calibrates SAR datasets into the PCIDSK (*.pix) format. Optionally, SARINGESTAOI can import an image subset by specifying an area of interest (AOI) via a maskfile in geocoded vector format, or a raster window (DBIW) specified in image co-ordinates (columns and lines). In addition to ingesting the raster data, SARINGESTAOI stores metadata and creates auxiliary segments (orbit, math model, GCPs, incidence angle array, etc.) that are necessary for further processing.

Parameters

saringestaoi(fili, filo, calibtyp, dbiw, maskfile, mask, fillop, filedem, dbec, poption, dblayout)

Name	Type	Caption	Length	Value range
FILI *	str	Input file name	1 -
FILO *	str	Output SAR image	1 -
CALIBTYP	str	Data calibration type	0 - 6	Sigma | Beta | Gamma | None
DBIW	List[int]	Raster input window	0 - 4	Xoffset, Yoffset, Xsize, Ysize
MASKFILE	str	Name of input AOI file	0 -
MASK	List[int]	Layer number of AOI	0 - 1
FILLOP	str	Fill option	0 - 6	BOX, NODATA Default: NODATA
FILEDEM	str	File containing the digital elevation model	0 -
DBEC	List[int]	Input elevation channel	0 - 1
POPTION	str	Pyramid options	0 - 4	OFF | NEAR | AVER | MODE Default: AVER
DBLAYOUT	str	Data Layout	0 -	See parameter description Default: TILED256

* Required parameter

Parameter descriptions

FILI

The name of the PCIDSK or GDB-supported file containing the SAR imagery to be ingested. For SAR datasets distributed as multiple files, use the "key file name", as described herein. It is important to use the key file name when opening a SAR dataset to preserve the integrity of the metadata and ensure that the auxiliary segments are correctly created.

For each supported sensor, the general form of the key file name is indicated and the asterisk (*) in the file name indicates a (sensor-dependent) variable number of characters.

• ICEYE: *.h5 or *.xml
• SAOCOM-1 (A and B): *.xemte
• RADARSAT CONSTELLATION MISSION (1, 2 and 3): manifest.safe
• SENTINEL-1 (A and B): manifest.safe
• TerraSAR-X/TanDEM-X: *.xml
• RADARSAT-2: product.xml file
• ALOS-2 PALSAR: LED-* or summary.txt
• COSMO-SKYMED (1,2,3 and 4): *.h5
• KOMPSAT-5: *.h5 or *_Aux.xml
• PAZ: *.xml
• RISAT: BAND_META.txt
• RADARSAT-1: DAT_01.001
• ENVISAT-ASAR: ASA_*.N1
• ALOS-1 PALSAR: IMG-*-ALPSR*-*.* (JAXA format) or DAT_01.001 (ERSDAC format) file
• ERS-1 and ERS-2: DAT_01.001

Airborne and other SAR sensors

• AIRSAR: CM*.dat
• Convair 580: l#p#hhpolgasp.hdr, l#p#hvpolgasp.hdr, l#p#vhpolgasp.hdr, or l#p#vvpolgasp.hdr
• RSIR-C: pr*_ldr_ceos
• UAVSAR: *.ann

For a specific sensor, refer to the appropriate GDB support page in the CATALYST Professional help section to get additional information for all supported processing levels and acquisition modes.

FILO

The name of the PCIDSK file containing the ingested SAR product. The output file must not already exist. If available, GCPs, text, orbit, incidence angle array and binary math model (or rational polynomial coefficients (RPCs)) are retrieved and stored with the image channels in the output file.

CALIBTYP

The type of radiometric calibration to apply. The calibration type defines the physical quantity that the imported pixels will represent, either sigma, (i.e. corrected to ground range) beta (corrected to slant range) or gamma nought (corrected for plane perpendicular to slant range).

Some datasets are supplied by the data provider with a specific calibration. In these cases, not all calibration types are available. The output file's selected calibration cannot be changed after the dataset has been ingested.

SARINGESTAOI may not properly calibrate data acquired by older sensors such as Radarsat-1, ERS-1/2 or ENVISAT. If you require calibration for older sensors, run the CDSAR algorithm followed by the SARSIGM algorithm (to convert to sigma) or the SARBETA algorithm (to convert to beta).

DBIW

The raster window (Xoffset, Yoffset, Xsize, Ysize) defining the area to be extracted from the input image. If no value is specified for this parameter, the entire image is processed by default.

Xoffset, Yoffset define the upper-left image pixel coordinates of the window. Xsize and Ysize define the window width and height respectively.

MASKFILE

The name of the file containing the geocoded vector layer defining the areas of interest (AOI). The maskfile parameter has precedence over the DBIW parameter if both are specified. This parameter is optional.

MASK

The number of the geocoded vector layer containing the AOI to process. The vector layer can contain multiple AOIs. Each AOI must be represented as a closed polygon.

If you specify a value for MASKFILE, you must specify a value for this parameter. The geocoded vectors can be in any supported projection (e.g. Long/Lat, UTM etc.)

FILLOP

Fill option specifying how to fill data outside the area of interest when the AOI is not rectangular.

When FILLOP=BOX, a bounding box is drawn encompassing the area of interest. Data inside the bounding box is preserved.

When FILLOP=NODATA, the data outside the AOI but within the bounding box are set to NODATA.

FILEDEM

Specifies the name of a file, directory, or index file containing digital elevation model tiles.

If FILEDEM is the name of a single raster DEM file, the DBEC parameter must be defined.

If FILEDEM is the name of an existing directory, the specified directory is searched for a file named index.txt. The index.txt file must be in the DEM index format, which is described in the Details section.

If FILEDEM is the name of a text file (with a .txt extension), the specified file must be in the DEM index format, which is described in the Details section.

The FILEDEM is used to automatically reproject the AOIs into the SAR geometry, either in slant or ground range using the math model derived from metadata.

If FILEDEM is blank, the AOI position will not be adjusted for elevation. A shift in the location of the AOI will be most noticeable in regions with high variability in elevation and/or SAR images with a large swath width. (e.g. ScanSAR and Sentinel-1 TOPS (IW and EW modes)).

DBEC

Specifies the channel containing the digital elevation model (DEM). This parameter is ignored if FILEDEM is not defined or points to a DEM index text file.

POPTION

The type of resampling to use to compute the overview levels.

Available options are:

• OFF: Does not compute overviews. This option increases the time required to browse an image; but uses the minimum amount of disk space.
• NEAR (NEAREST): Uses nearest-neighbor resampling.
• AVER (AVERAGE): Calculates the average value of all of the pixels that contribute to the overview pixel. Use this option with continuous-tone images. AVERAGE produces a better-looking and more interpretable overview than NEAR. This is the default value.
• MODE: Takes the mode of the pixels contributing to the overview pixel. This option is suitable for use with classified, pseudocolored, or thematic images, but not continuous-tone images.

DBLAYOUT

The layout of the image data in the output PCIDSK file.

Supported values include:

• PIXEL: Pixel interleaved
• BAND: Band interleaved; this is the default value
• FILE: File interleaved
• TILED: Tiled with a default tile size
• TILEDN: Tiled with n x n pixel tiles
• TILEDN RLE: Tiled with RLE compression and n x n pixel tiles

The specified layout can affect processing performance. Band interleaved stores each band contiguously in memory and provides a better performance when bands are processed separately. Pixel interleaved stores the data for all bands for each pixel and may provide improved performance when many bands are used simultaneously. File interleaved is similar to band interleaved, but the image-channel data are stored as separate files (one file for each band).

Tiled files organize the image in several square sub-images; these may be much faster to access when sub-areas are being extracted, as in image display or speckle filtering. Tiling is also the only format that supports data compression. (default is no compression)

JPEG compression is a lossy compression and is suitable for continuous tone images.

Quadtree compression is lossy compression, and provides good compression ratios when images contain large blocks of pixels with the same value.

Run Length Encoding (RLE) compression is lossless, but only provides good compression for images in which long sequences of pixels have the same value, which is typical in pseudocolored or thematic images.

Details

SARINGESTAOI imports and calibrates SAR datasets into the PCIDSK (*.pix) format. Optionally, SARINGESTAOI can import an image subset by specifying an area of interest (AOI) via a maskfile in geocoded vector format, or a raster window (DBIW) specified in image co-ordinates (columns and lines). In addition to ingesting the raster data, SARINGESTAOI stores metadata and creates auxiliary segments (orbit, math model, GCPs, incidence angle array, etc.) that are necessary for further processing.

AOI projection and SAR image geometry

SARINGESTAOI can ingest a subset of a SAR image based upon user specified areas of interest (AOI). The AOI maskfile must contain closed vector polygons stored in the specified mask layer.

No output is written if the polygon(s) contained in the AOI do not overlap with the SAR image.

Various combinations of AOI mask projection, SAR acquisition geometry, availability of a math model and the availability of a DEM have an impact on the geolocation accuracy of the ingested area as described in the following scenarios.

• An AOI derived from an external source with a precise geolocation and in the ortho space, for example ortho or orthomosaics from aerial photography or spaceborne optical or SAR imagery.
• An AOI derived from a raw vendor SAR image displayed using the file georeferencing.
• An AOI derived from a raw vendor SAR image displayed using a math model.

When a RAW vendor SAR image is opened in CATALYST Professional using its key file name, one can display the image using file georeferencing or a math model.

The georeferencing information utilizes the nominal locations of the four corners of the image and assumes equally spaced pixels in the given coordinate system, likely in Latitude and Longitude or UTM. For most recent sensors at processing levels 1A (SLC) and 1B (GRD), CATALYST Professional produces a precise math model (or RPCs) generated from the satellite state vectors provided in the metadata. A math model defines relationship between image co-ordinates (2D) and their geodetic locations (3D).

SARINGESTAOI has been designed to use the SAR file math model (if available) and a DEM to reproject the external AOI (scenario 1) to the image slant range or ground range geometry before ingesting the data. If the math model or the DEM is missing, the ingested area will not correspond to the expected area from the AOI. The shift will be particularly noticeable for areas of rugged terrain or data sets covering large swath widths such as ScanSAR data or Sentinel-1 in IW or EW modes.

Note that displaying a SAR image in FOCUS using its Math Model and a DEM will create an orthoimage "on the fly". Therefore, any vector AOI derived from this model (scenario 3) will be the equivalent of an external AOI (scenario 1).

When a vector AOI is created under scenario 2 but no DEM is provided, SARINGESTAOI will not attempt to reproject the AOI and the ingested area will correspond to the correct AOI location. However, if this AOI file is reused to ingest another SAR image, a shift will occur.

Using a DEM and an AOI derived from an ortho space allows reuse of the AOI to ingest the exact same geographical area for a series of SAR images from different sources, with different dimensions, spatial resolution, orbit direction, etc. Drawing an area of interest using the file georeferencing will only be precise for that image.

SAR image, AOI and DEM spatial extents

Parts of the AOI can be outside the spatial extents of the SAR image. However, if the FILEDEM parameter is specified, the AOI must be completely within the DEM's spatial extents. The DEM must not contain NODATA values for the area covered by the AOI.

Metadata

In addition to image and segment data, the SARINGESTAOI extracts metadata related to SAR processing and writes it to the output file. There are two levels of metadata: file and channel.

At the file level, SAR metadata contains information that relates to the data set as a whole, including:

• Acquisition_DateTime: Date and time of acquisition using the Universal Time (UT) standard (YYYY:MM:DDThh:mm.ss.xxx). (e.g. 2019-11-01T10:01:26.61798727795Z)
• Acquisition_Type: Optional detailed information related to the image observation mode (ScanSAR, Spotlight, StripMap, ...), processing level (SSC, SLC, GRD, ...) and beam mode (Fine, IW, EW...). The content of this metadata varies according to the supplied information and naming conventions uses by the data providers.
• IncidenceFarAngle: Incidence angle, in degrees, at the swath far range
• IncidenceNearAngle: Incidence angle, in degrees, at the swath near range.
• LookDirection: Right or Left. Pointing direction of the sensor relative to the orbit direction (Ascending or Descending).
• Matrix_Type: Matrix stored on file; for example, s4c or c2r
• OrbitDirection: Ascending or Descending
• Polarizations: List of polarizations of the data in the image; for example, HH, HV. Each polarization is represented by two characters. The first character specifies the transmit polarization, the second specifies the receive polarization.
• Product_Type: Imported data product corresponding to the processing level for example, SLC, MLC, GRD, SSC, EEC, L1A, L1B, L1C, L1D, ...
• RadarBand: Radar band corresponding to the wavelength (X, C, L, P, ...)
• RadarCenterFrequency: Radar center frequency given in hertz (hz)
• RadarWavelength: Radar wavelength given in meters (m.)
• SensorModelName: Description of the sensor; for example, RADARSAT-2

For Single Look complex (SLC) data:

• SlantRangeFarEdge: Distance between the sensor and the far edge of the swath, in meters (m), in the slant range geometry.
• SlantRangeNearEdge: Distance between the sensor and the near edge of the swath, in meters (m), in the slant range geometry.
• SlantRangeInterval: For every image pixel in the range direction, the incremental slant range distance in meters (m).

At the channel level, metadata for polarimetric data identifies the matrix element stored in the channel:

• Matrix_Element: Describes the row and column position of the element in the matrix. For example, with a data set stored as an s4c matrix, the first channel is identified as _1_1 and the second channel is identified as _1_2.
• Polarization: Polarization of the channel. Each polarization is represented by two characters. The first character specifies the transmit polarization, the second specifies the receive polarization. For example: HH, HV, VH, VV, RR, LL, RH, RL etc.

These metadata, in particular the matrix type, are particularly important for advanced SAR processing such as SAR polarimetry, SAR compact polarimetry, SAR Interferometry and SAR coherent change detection. They determine which process can be applied to a particular dataset. For more information about matrix type, see the PSCONV documentation.

Channel type and image segments

Single look complex (SLC) and multilook complex (MLC) data are stored as complex channels identified by the following codes:

• C16S: Complex 16 bit signed for uncalibrated data
• C32R: Complex 32 bit for calibrated data (sigma, gamma or beta nought).

Complex data are stored as a single channel and are not stored as separate channels (generally known as the Real (I) and Imaginary (Q) channels). Other segments that may be created include the following:

• [GCP] Ground Control Points. GCPs provided by the data vendor, generally a grid of GCPs derived from orbital data.
• [ORB] Orbit segment describing the position of the satellite during the data acquisition.
• [BIN] Binary segment. Rational Functions Model (or rational polynomial coefficient (RPCs)). Math model describing in ground coordinates the location of every pixel in an image. This information is derived from the satellite state-vectors. This segment is generally computed by CATALYST Professional and not directly imported from the data vendor.
• [ARR] Incidence Angle Array. 1D array describing the incidence angle for every column in the range direction.

In general, older sensors (such as ERS-1/2, Radarsat-1, ALOS Palsar-1, ENVISAT-ASAR) rely on a nominal sensor model for positioning and orthorectification while a binary math model is generated for newer sensors

Examples

Example 1. The following Radarsat-2 scene, identified by its key filename (product.xml), is ingested entirely. The DBIW, MASKFILE and MASK are empty.

from pci.saringestaoi import saringestaoi
fili = 'InputData/RS2/product.xml'
filo = 'Output/Radarsat2_fullscene_sigma.pix'
calibtyp = 'sigma'
dbiw = []
maskfile = ''
mask = []
fillop = ''
filedem = ''
dbec = []
poption = 'aver'
dblayout = ''

saringestaoi(fili, filo, calibtyp, dbiw, maskfile, mask, fillop, filedem, dbec, poption, dblayout)
      

Example 2. An AOI is used to subset the following Radarsat-2 scene. Since the AOI is in the ortho space and the input scene in slant range, a DEM must be provided to reproject the AOI into the slant range coordinates. The areas outside the AOI are set to NODATA.

from pci.saringestaoi import saringestaoi
fili = 'InputData/RS2/product.xml'
filo = 'Output/Radarsat2_subset-AOI_sigma.pix'
calibtyp = 'sigma'
dbiw = []
maskfile = 'InputData/AOI_subset_file.pix'
mask = [2]
fillop = 'nodata'
filedem = 'InputData\DEM_file.pix'
dbec = []
poption = 'aver'
dblayout = ''

saringestaoi(fili, filo, calibtyp, dbiw, maskfile, mask, fillop, filedem, dbec, poption, dblayout)
      

Example 3. An AOI is used to subset the following Radarsat-2 scene. Since the AOI is already in the slant range geometry it does not need to be reprojected and FILEDEM and DBEC are left blank. A bounding box is created around the AOI.

from pci.saringestaoi import saringestaoi
fili = 'InputData/RS2/product.xml'
filo = 'Output/Radarsat2_subset-AOI_sigma.pix'
calibtyp = 'sigma'
dbiw = []
maskfile = 'InputData/AOI_subset_file.pix'
mask = [2]
fillop = 'box'
filedem = ''
dbec = []
poption = 'aver'
dblayout = ''

saringestaoi(fili, filo, calibtyp, dbiw, maskfile, mask, fillop, filedem, dbec, poption, dblayout)
      

Example 4. A DBIW window is used to subset the following Radarsat-2. The window upper left coordinate is starting at column 500 and line 750 with a size of 1000 columns and 1500 lines. Note that MASKFILE and MASK have precedence over DBIW when they are specified.

from pci.saringestaoi import saringestaoi
fili = 'InputData/RS2/product.xml'
filo = 'Output/Radarsat2_subset-DBIW_sigma.pix'
calibtyp = 'sigma'
dbiw = [500, 750, 1000, 1500]
maskfile = ''
mask = []
fillop = 'nodata'
filedem = ''
dbec = []
poption = 'aver'
dblayout = ''

saringestaoi(fili, filo, calibtyp, dbiw, maskfile, mask, fillop, filedem, dbec, poption, dblayout)