| Environments | PYTHON :: EASI :: MODELER |
| Quick links | Description :: Parameters :: Parameter descriptions :: Details :: Example :: Acknowledgements :: Related |
| Back to top |
| Back to top |
inscaldefo(file, dbic, dboc, tfile, filv, dbvs, fldnme, calwin, adjmethod)
| Name | Type | Caption | Length | Value range |
|---|---|---|---|---|
| FILE * | str | Displacement file name | 1 - | |
| DBIC * | List[int] | Input displacement channel | 1 - 1 | |
| DBOC * | List[int] | Output raster channel containing calibrated displacements | 1 - 1 | |
| TFILE | str | Image coordinates of points | 0 - | |
| FILV | str | Name of input file with vector layer of stable points | 0 - | |
| DBVS | List[int] | Input vector segments | 0 - 16 | |
| FLDNME | str | Field name to use for elevation values | 0 - 64 | ZCOORD | Field Name Default: ZCOORD |
| CALWIN | List[int] | Size of calibration window | 0 - 2 | 1 - Default: 1, 1 |
| ADJMETHOD | str | Displacement adjustment method | 0 - 32 | ALL| UNDER #.#| CLAMP #.#| UNDERSIGMA #.#| CLAMPSIGMA #.#| AVERAGEALL| AVERAGEUNDER #.#| AVERAGECLAMP #.#| AVERAGEUNDERSIGMA #.#| AVERAGECLAMPSIGMA #.# Default: ALL |
| Back to top |
FILE
The name of the file containing ground displacements to calibrate. Typically, the file is an interferogram unwrapped in the deformation mode, with derived ground displacements in a separate 32R channel.
DBIC
The input channel containing the ground displacement to calibrate.
DBOC
The channel of the displacement file to which to write the adjusted displacement data. The channel type must be 32R.
If the output channel is the same as the input channel, the input channel is overwritten with calibrated displacement values.
TFILE
The path and file name of the text file that contains image coordinates (pixel, line) of calibration points. Each point must be specified in a separate line, and the numbers must be separated by spaces, tabs, or commas. Empty lines and lines that begin with the hash symbol (#) are treated as comments and are ignored. Lines that do not contain two valid numbers are skipped and considered "not points".
The numbers in the text file represent pixel and line numbers that are zero-based; that is, the pixel in the upper-left corner of the image has coordinates (0, 0), and the pixel in the lower-right corner has coordinates (number-of-pixels - 1, number-of-lines - 1). You can enter fractional values; however, they will be truncated to integer values.
The points in the text file you specify can be used by themselves or in combination with points in the vector layer specified as input. However, you must specify at least one of these calibration-point sources.
FILV
The name of the file with a vector layer containing stable points. If the file does not have any data, the field to use for elevation values is ignored.
DBVS
The number or numbers of vector segments containing points representing stable targets. Stable targets are locations in the image that are known to have no (zero) displacement in the span of the interferogram. The points must be in ground coordinates that are projectable to the coordinates of the input displacement file. If the displacements are in the raw interferogram geometry (slant range), the points in the input point vector layer must have elevations.
If a vector layer of stable points is specified, this parameter is ignored.
The vector layer of stable points and vector segments you specify can be used by themselves, or combined with points in the text file of point coordinates. If you specify only vector points, you need not specify a text file of point coordinates. However, you must specify at least one source of calibration points.
FLDNME
The field containing the elevation (or z) values, which you can specify as an option. That is, you specify this parameter only when the input displacement file is in the raw SAR image (slant-range) geometry, and has a binary math model. If specified, the field name must exist in the attribute table of the vector layer.
If you specify an input file containing a vector point layer, this parameter is ignored.
CALWIN
The size of the image window, in pixels and lines, centered on each calibration point. In the window, each displacement is are averaged, and the resulting value is used as the correction associated with the given calibration point. The default values are 1, 1, meaning that the exact value at each calibration pixel is used as the correction at this point.
The values you enter must be an odd and positive integer.
To define a square window, enter a single value, To define a rectangular window, enter two values. The window has the same size at all calibration points, based on the value or values you specify.
ADJMETHOD
The adjustment algorithm to use, which you can specify as an option.
You can preface each option with AVERAGE, which raises (or lowers) the entire displacement channel by a single value (the average difference). This is an effective alternative to trying to create a varying surface that goes through the points. Prefacing an option with AVERAGE is also useful in removing a systematic error; for example: AVERAGEALL or AVERAGEUNDERSIGMA 2.0.
| Back to top |
INSCALDEFO adjusts (raises or lowers) a raster of terrain-displacement values to calibration points stored in a text file, a vector layer, or both. The points represent locations (targets) that are known to be stable (not moving) at the interval of time between acquisition of the two SAR images used to derive the interferogram.
INSCALDEFO supports displacement rasters that are either geocoded or still in the raw (slant-range) geometry. The slant-range rasters are identified automatically by the presence of the binary math model in input displacement file.
The specified text file and vector segments (layers) are used for the calibration points. The text file directly provides pixel and line numbers of points to use. The vector point layer segments provide ground coordinates of points that are projected to image positions in the deformation raster. All points are assumed to have a displacement of zero. With vector segments, only points will be used - lines and polygons are skipped and counted as "not points".
The points in the vector segment will be reprojected automatically to match the projection of the raster. If INSCALDEFO cannot project between the vector and raster coordinate systems, processing will stop. If the raster to be adjusted is orthorectified, the projection from the point coordinates is two-dimensional, and does not require elevations (the elevation-values field, if specified, is ignored). If the raster is in the slant-range geometry, the calibration points must have elevations, as specified by the elevation-values field. With such rasters, INSCALDEFO uses three-dimensional transformation between the point and raster coordinate systems. If the ELEVATION_DATUM metadata tag is unavailable in the vector segment or segments, point elevations are assumed to be relative to mean sea level (MSL).
Each point outside the raster area or in a NoData area is skipped and counted as "outside file". Accepted calibration points are assumed to have a displacement of zero. Pixel values at the corresponding raster locations define the corrections to apply at these locations to adjust their displacements to zero.
If you specify a calibration window, and the number of lines and pixels in the window is greater than one, then all valid displacement values in the window are averaged, and the resulting value is used to derive the correction at the pixel. Any NoData values in the calibration window are ignored. If the window extends beyond the image, it is truncated to be fully within the image. The averaging of displacements compensates for possible misregistration of the two images forming the interferogram, and also derives a more stable correction for larger or distributed targets. However, in this case, some calibrated values in the window may not be exactly zero.
For example, specifying CLAMP 0.5 applies no adjustment greater than plus or minus 0.5 over the entire raster. The sigma method examines all the corrections from the points and limits the adjustment based on the sigma value; that is, the standard deviation and the root of their variance.
Specifying UNDERSIGMA 2.0 adjusts only points that are less than plus or minus two sigma, meaning, typically, points with the largest corrections, ranging from 10 to 15 percent, would be counted as "ignored".
You can preface each with AVERAGE, which raises or lowers the entire raster by a single value (the average correction). This is preferable to trying to create a varying surface that goes through the points. Prefacing an options with AVERAGE is also useful for removing a systematic error. For example, AVERAGEUNDERSIGMA 2.0 is generally a safe option to use.
Interferograms unwrapped in topographic mode can be adjusted similarly by running the DEMADJUST algorithm.
| Back to top |
In the following example, a SAR interferogram has been unwrapped. The interferogram has a 32R channel 2 with terrain displacements in centimeters. A new 32R channel 3 has already been added to the raster file. A number of stable (unmoving) points is available in files StablePixels.txt (in image coordinates) and StablePoints.pix (in ground coordinates).
The goal is to adjust the displacement raster by using the calibration points to ensure that all residual errors, such as atmospheric effects, are removed. Based on the premise that random errors in the displacement raster are inevitable, a small calibration window is used, and the adjustment method is specified at UNDERSIGMA 2.0. The raster is in the raw image (slant-range) geometry and has a math model; therefore, the calibration points in the vector layer have elevations in their z-coordinates, and they must be specified.
from pci.inscaldefo import inscaldefo file = "UnwrappedDefo.pix" # displacement raster to adjust dbic = [2] # raster displacement channel dboc = [3] # write the adjusted displacements to new channel tfile = "StablePixels.txt" # input calibration points in image coordinates filv = "StablePoints.shp" # input calibration points in ground coordinates dbvs = [2] fldnme = "ZCOORD" # elevation in actual z-coordinate calwin = [3, 3] # average nine pixels around every point adjmethod = "UNDERSIGMA 2.0" # ignore corrections over 2.0 sigma inscaldefo(file, dbic, dboc, tfile, filv, dbvs, fldnme, calwin, adjmethod)
| Back to top |
© PCI Geomatics Enterprises, Inc.®, 2026. All rights reserved.