Scene Module

class kite.Scene(config=<kite.scene.SceneConfig object>, **kwargs)[source]

Bases: kite.scene.BaseScene

Scene of unwrapped InSAR ground displacements measurements

Parameters

config (SceneConfig, optional) – Configuration object

Optional parameters

Parameters

  • displacement (numpy.ndarray, NxM, optional) – Displacement in [m]

  • theta (numpy.ndarray, NxM, optional) – Theta look angle, see BaseScene.theta

  • phi (numpy.ndarray, NxM, optional) – Phi look angle, see BaseScene.phi

  • llLat (float, optional) – Lower left latitude in [deg]

  • llLon (float, optional) – Lower left longitude in [deg]

  • dLat (float, optional) – Pixel spacing in latitude [deg or m]

  • dLon (float, optional) – Pixel spacing in longitude [deg or m]

cls

alias of kite.scene_io.ARIA

covariance
Getter

(Cached) Instantiates the scene’s covariance attribute.

Type

kite.covariance.Covariance

static import_data(*args, **kwargs)

Import displacement data from foreign file format.

param path

Filename of resource to import

type path

str

param kwargs

keyword arguments passed to import function

type kwargs

dict

returns

Scene from path

rtype

Scene

raises

TypeError

Supported import for unwrapped InSAR data are:

Gamma

Reading geocoded displacement maps (unwrapped igs) originating

from GAMMA software.

Note

Expects:

  • [*] Binary file from Gamma with displacement in radians

  • [*.slc.par] If you want to translate radians to meters using the radar_frequency.

  • [*par] Parameter file, describing corner_lat, corner_lon, nlines, width, post_lat, post_lon or post_north, post_east, corner_east, corner_north, nlines, width.

  • [*theta*, *phi*] Two look vector files, generated by GAMMA command look_vector.

Warning

  • Data has to be georeferenced to latitude/longitude or UTM!

  • Look vector files - expected to have a particular name

Matlab

Variable naming conventions for Matlab .mat container:

Property

Matlab .mat name

type

unit

Scene.displacement

ig_

n x m array

[m]

Scene.phi

phi

float or n x m array

[rad]

Scene.theta

theta

float or n x m array

[rad]

Scene.frame.x

xx

n x 1 vector

[m]

Scene.frame.y

yy

m x 1 vector

[m]

Scene.utm_zone

utm_zone

str (‘33T’)

Displacement is expected to be in meters. Note that the displacement maps could also be pixel offset maps rather than unwrapped SAR interferograms. For SAR azimuth pixel offset maps calculate phi from the heading direction and set theta=0.. For SAR range pixel offsets use the same LOS angles as for InSAR.

ISCE

Reading geocoded, unwraped displacement maps processed with ISCE software (https://winsar.unavco.org/isce.html).

Note

Expects:

  • Unwrapped displacement binary (*.unw.geo)

  • Metadata XML (*.unw.geo.xml)

  • LOS binary data (*.rdr.geo)

Note

When using gdal_translate to crop the scene, use the argument -co SCHEME=BIL to make the output

Note

Data are in radians but no transformation to meters yet, as wavelength or at least sensor name is not provided in the XML file.

GMTSAR

Reading GMTSAR grid files.

Note

Expects:

  • Displacement grid (NetCDF, *los_ll.grd) in meter (in case use “gmt grdmath los_cm_ll.grd 0.01 MUL = los_m_ll.grd’)

  • LOS binary data (see instruction, *.los.enu)

Calculate the corresponding unit look vectors with GMT5SAR SAT_look:

gmt grd2xyz los_ll.grd | gmt grdtrack -Gdem.grd | \
awk {'print $1, $2, $4'} | \
SAT_look 20050731.PRM -bos > 20050731.los.enu

ROI_PAC

Note

Expects:

  • Binary file from ROI_PAC (*)

  • Parameter file (<binary_file>.rsc), describing WIDTH, FILE_LENGTH, X_FIRST, Y_FIRST, X_STEP, Y_STEP, WAVELENGTH

  • If the georeferencing is in UTM coordinates, further needed entries in parameter file are ‘X_UNIT’ and ‘Y_UNIT’ that give ‘meters’ and ‘LAT_REF3’ as well as ‘LON_REF3’.

The unwrapped displacement is expected in radians and will be scaled to meters by WAVELENGTH parsed from the *.rsc file.

SARscape

Reading SARscape *_disp files.

Note

Expects:

  • Header file in *_disp.hdr

  • Displacement data in cm in *_disp

  • LOS data in *disp_ILOS and *disp_ALOS files.

LiCSAR

Import unwrapped Geotiffs from the COMET LiCSAR Portal.

Note

Requires the Python package gdal/osgeo! Or through

Expects:

  • Unwrapped geotiff in *.unw.tif

  • LOS data in *.geo.[NEU].tif files

See also the download script in kite.clients.

ARIA

Import unwrapped InSAR scenes from the NASA/JPL ARIA GUNW data products.

Note

Requires the Python package gdal/osgeo! Or through

Expects:

  • Extracted layers: unwrappedPhase, lookAngle, incidenceAngle, connectedComponents

Use ariaExtract.py to extract the layers:

ariaExtract.py -w ascending -f aria-data.nc -d download \
-l unwrappedPhase,incidenceAngle,lookAngle
static load(*args, **kwargs)

Load a kite scene from file filename.[npz,yml] structure.

Parameters

filename (str) – Filenames the scene data is saved under

Returns

Scene object from data resources

Return type

Scene

plot
Getter

(Cached) Shows a simple plot of the scene’s displacement

quadtree
Getter

(Cached) Instantiates the scene’s quadtree.

Type

kite.quadtree.Quadtree

save(filename=None)[source]

Save kite scene to kite file structure

Saves the current scene meta information and UTM frame to a YAML (.yml) file. Numerical data (displacement, theta and phi) are saved as binary files from numpy.ndarray.

Parameters

filename (str, optional) – Filenames to save scene to, defaults to ‘ scene_id _ scene_view

spool()[source]

Start the spool user interface Spool to inspect the scene.

class kite.scene.BaseScene(**kwargs)[source]
displacement

Surface displacement in meter on a regular grid.

Setter

Set the unwrapped InSAR displacement.

Getter

Return the displacement matrix.

Type

numpy.ndarray, NxM

displacement_deramp(demean=True, inplace=True)[source]

Fit a plane onto the displacement data and substract it

Parameters

  • demean (bool) – Demean the displacement

  • inplace (bool) – Replace data of the scene (default: True)

Returns

None if inplace=True else a new Scene

Return type

None or Scene

displacement_mask
Getter

(Cached) Displacement numpy.nan mask

Type

numpy.ndarray, dtype numpy.bool

displacement_px_var

Variance of the surface displacement per pixel. Same dimension as displacement.

Setter

Set standard deviation of of the displacement.

Getter

Return the standard deviation matrix.

Type

numpy.ndarray, NxM

get_ramp_coefficients()[source]

Fit plane through the displacement data.

Returns

Mean of the displacement and slopes in easting coefficients of the fitted plane. The array hold [offset_e, offset_n, slope_e, slope_n].

Return type

numpy.ndarray

los_rotation_factors
Getter

(Cached) Trigonometric factors to rotate displacement matrices towards LOS

Rotation is as follows:

Returns

Factors for rotation

Return type

numpy.ndarray, NxMx3

Raises

AttributeError

phi

Horizontal angle towards satellite line of sight in radians counter-clockwise from East.

Important

Kite’s convention is:

  • \(0\) is East

  • \(\frac{\pi}{2}\) is North!

Setter

Set the phi matrix for scene’s displacement, can be int for static look vector.

Type

numpy.ndarray, size same as displacement or int

phiDeg
Getter

(Cached) LOS horizontal orientation angle in degree, counter-clockwise from East,``NxM`` matrix like kite.Scene.phi

Type

numpy.ndarray

theta

Theta is the look vector elevation angle towards satellite from the horizon in radians. Matrix of theta towards satellite’s line of sight.

Important

Kite convention!

  • \(-\frac{\pi}{2}\) is Down

  • \(\frac{\pi}{2}\) is Up

Setter

Set the theta matrix for scene’s displacement, can be int for static look vector.

Type

numpy.ndarray, size same as displacement or int

thetaDeg
Getter

(Cached) LOS elevation angle in degree, NxM matrix like kite.Scene.theta

Type

numpy.ndarray

Scene I/O Modules

class kite.scene_io.Gamma(scene=None)[source]
Reading geocoded displacement maps (unwrapped igs) originating

from GAMMA software.

Note

Expects:

  • [*] Binary file from Gamma with displacement in radians

  • [*.slc.par] If you want to translate radians to meters using the radar_frequency.

  • [*par] Parameter file, describing corner_lat, corner_lon, nlines, width, post_lat, post_lon or post_north, post_east, corner_east, corner_north, nlines, width.

  • [*theta*, *phi*] Two look vector files, generated by GAMMA command look_vector.

Warning

  • Data has to be georeferenced to latitude/longitude or UTM!

  • Look vector files - expected to have a particular name

read(filename, **kwargs)[source]
Parameters

  • filename (str) – Gamma software parameter file

  • par_file (str) – Corresponding parameter (*par) file. (optional)

Returns

Import dictionary

Return type

dict

Raises

ImportError

validate(filename, **kwargs)[source]

Validate file format

Parameters

filename (string) – file to validate

Returns

Validation

Return type

{bool}

class kite.scene_io.Matlab(scene=None)[source]

Variable naming conventions for Matlab .mat container:

Property

Matlab .mat name

type

unit

Scene.displacement

ig_

n x m array

[m]

Scene.phi

phi

float or n x m array

[rad]

Scene.theta

theta

float or n x m array

[rad]

Scene.frame.x

xx

n x 1 vector

[m]

Scene.frame.y

yy

m x 1 vector

[m]

Scene.utm_zone

utm_zone

str (‘33T’)

Displacement is expected to be in meters. Note that the displacement maps could also be pixel offset maps rather than unwrapped SAR interferograms. For SAR azimuth pixel offset maps calculate phi from the heading direction and set theta=0.. For SAR range pixel offsets use the same LOS angles as for InSAR.

read(filename, **kwargs)[source]

Read function of the file format

Parameters

  • filename (string) – file to read

  • kwargs ({dict}) – Keyword arguments

validate(filename, **kwargs)[source]

Validate file format

Parameters

filename (string) – file to validate

Returns

Validation

Return type

{bool}

class kite.scene_io.ISCE(scene=None)[source]

Reading geocoded, unwraped displacement maps processed with ISCE software (https://winsar.unavco.org/isce.html).

Note

Expects:

  • Unwrapped displacement binary (*.unw.geo)

  • Metadata XML (*.unw.geo.xml)

  • LOS binary data (*.rdr.geo)

Note

When using gdal_translate to crop the scene, use the argument -co SCHEME=BIL to make the output

Note

Data are in radians but no transformation to meters yet, as wavelength or at least sensor name is not provided in the XML file.

read(path, **kwargs)[source]

Read function of the file format

Parameters

  • filename (string) – file to read

  • kwargs ({dict}) – Keyword arguments

validate(filename, **kwargs)[source]

Validate file format

Parameters

filename (string) – file to validate

Returns

Validation

Return type

{bool}

class kite.scene_io.GMTSAR(scene=None)[source]

Reading GMTSAR grid files.

Note

Expects:

  • Displacement grid (NetCDF, *los_ll.grd) in meter (in case use “gmt grdmath los_cm_ll.grd 0.01 MUL = los_m_ll.grd’)

  • LOS binary data (see instruction, *.los.enu)

Calculate the corresponding unit look vectors with GMT5SAR SAT_look:

gmt grd2xyz los_ll.grd | gmt grdtrack -Gdem.grd | \
awk {'print $1, $2, $4'} | \
SAT_look 20050731.PRM -bos > 20050731.los.enu
read(path, **kwargs)[source]

Read function of the file format

Parameters

  • filename (string) – file to read

  • kwargs ({dict}) – Keyword arguments

validate(filename, **kwargs)[source]

Validate file format

Parameters

filename (string) – file to validate

Returns

Validation

Return type

{bool}

class kite.scene_io.ROI_PAC(scene=None)[source]

Note

Expects:

  • Binary file from ROI_PAC (*)

  • Parameter file (<binary_file>.rsc), describing WIDTH, FILE_LENGTH, X_FIRST, Y_FIRST, X_STEP, Y_STEP, WAVELENGTH

  • If the georeferencing is in UTM coordinates, further needed entries in parameter file are ‘X_UNIT’ and ‘Y_UNIT’ that give ‘meters’ and ‘LAT_REF3’ as well as ‘LON_REF3’.

The unwrapped displacement is expected in radians and will be scaled to meters by WAVELENGTH parsed from the *.rsc file.

read(filename, **kwargs)[source]
Parameters

  • filename (str) – ROI_PAC binary file

  • par_file (str) – Corresponding parameter (*rsc) file. (optional)

Returns

Import dictionary

Return type

dict

Raises

ImportError

validate(filename, **kwargs)[source]

Validate file format

Parameters

filename (string) – file to validate

Returns

Validation

Return type

{bool}

class kite.scene_io.SARscape(scene=None)[source]

Reading SARscape *_disp files.

Note

Expects:

  • Header file in *_disp.hdr

  • Displacement data in cm in *_disp

  • LOS data in *disp_ILOS and *disp_ALOS files.

read(filename, **kwargs)[source]

Read function of the file format

Parameters

  • filename (string) – file to read

  • kwargs ({dict}) – Keyword arguments

validate(filename, **kwargs)[source]

Validate file format

Parameters

filename (string) – file to validate

Returns

Validation

Return type

{bool}

class kite.scene_io.LiCSAR(scene=None)[source]

Import unwrapped Geotiffs from the COMET LiCSAR Portal.

Note

Requires the Python package gdal/osgeo! Or through

Expects:

  • Unwrapped geotiff in *.unw.tif

  • LOS data in *.geo.[NEU].tif files

See also the download script in kite.clients.

read(filename, **kwargs)[source]

Read function of the file format

Parameters

  • filename (string) – file to read

  • kwargs ({dict}) – Keyword arguments

validate(filename, **kwargs)[source]

Validate file format

Parameters

filename (string) – file to validate

Returns

Validation

Return type

{bool}

class kite.scene_io.ARIA(scene=None)[source]

Import unwrapped InSAR scenes from the NASA/JPL ARIA GUNW data products.

Note

Requires the Python package gdal/osgeo! Or through

Expects:

  • Extracted layers: unwrappedPhase, lookAngle, incidenceAngle, connectedComponents

Use ariaExtract.py to extract the layers:

ariaExtract.py -w ascending -f aria-data.nc -d download \
-l unwrappedPhase,incidenceAngle,lookAngle
read(folder, **kwargs)[source]

Read function of the file format

Parameters

  • filename (string) – file to read

  • kwargs ({dict}) – Keyword arguments

validate(folder, **kwargs)[source]

Validate file format

Parameters

filename (string) – file to validate

Returns

Validation

Return type

{bool}

SceneConfig

class kite.scene.SceneConfig(**kwargs)[source]

Configuration object, gathering kite.Scene and sub-objects configuration.

♦ meta

Meta, default: <kite.scene.Meta object at 0x7fc8ad406080>

Scene metainformation

♦ frame

FrameConfig, default: <kite.scene.FrameConfig object at 0x7fc8ad4060f0>

Frame/reference configuration

♦ quadtree

kite.quadtree.QuadtreeConfig, default: <kite.quadtree.QuadtreeConfig object at 0x7fc8ad406080>

Quadtree parameters

♦ covariance

kite.covariance.CovarianceConfig, default: <kite.covariance.CovarianceConfig object at 0x7fc8ad4060f0>

Covariance parameters

Meta Information Container

A Scene holds several configuration objects:

class kite.scene.Meta(*args, **kwargs)[source]

Meta configuration for Scene.

♦ scene_title

str, default: 'Unnamed Scene'

Scene title

♦ scene_id

str, default: 'None'

Scene identification

♦ satellite_name

str, default: 'Undefined Mission'

Satellite mission name

♦ wavelength

float, optional

Wavelength in [m]

♦ orbital_node

builtins.str (pyrocko.guts.StringChoice), default: 'Undefined'

Orbital direction, ascending/descending

♦ time_master

builtins.float (pyrocko.guts.Timestamp), default: 1481116161.930574

Timestamp for master acquisition

♦ time_slave

builtins.float (pyrocko.guts.Timestamp), default: 1482239325.482

Timestamp for slave acquisition

♦ extra

dict of pyrocko.guts.Any objects, default: {}

Extra header information

♦ filename

str, optional

Frame

class kite.scene.Frame(scene, config=<kite.scene.FrameConfig object>)[source]

Frame holding geographical references for kite.scene.Scene

The pixel spacing is given by dE and dN which can meters or degree.

E
Getter

(Cached) Undocumented

Emeter
Getter

(Cached) Undocumented

N
Getter

(Cached) Undocumented

Nmeter
Getter

(Cached) Undocumented

coordinates
Getter

(Cached) Local east and north coordinates [m] of all pixels in NxM matrix.

Type

numpy.ndarray, size NxM

coordinatesMeter
Getter

(Cached) Local east and north coordinates [m] of all pixels in NxM matrix.

Type

numpy.ndarray, size NxM

gridE
Getter

(Cached) Grid holding local east coordinates of all pixels in NxM matrix of displacement.

Type

numpy.ndarray, size NxM

gridEmeter
Getter

(Cached) Undocumented

gridN
Getter

(Cached) Grid holding local north coordinates of all pixels in NxM matrix of displacement.

Type

numpy.ndarray, size NxM

gridNmeter
Getter

(Cached) Undocumented

mapENMatrix(E, N)[source]
Local map coordinates in east and north to matrix

row and column

Parameters

  • E (float) – Easting in local coordinates

  • N (float) – Northing in local coordinates

Returns

Row and column

Return type

tuple (int), (row, column)

FrameConfig

class kite.scene.FrameConfig(*args, **kwargs)[source]

Config object holding kite.scene.Scene configuration

♦ llLat

float, default: 0.0

Scene latitude of lower left corner

♦ llLon

float, default: 0.0

Scene longitude of lower left corner

♦ dN

float, default: 25.0

Scene pixel spacing in north, give [m] or [deg]

♦ dE

float, default: 25.0

Scene pixel spacing in east, give [m] or [deg]

♦ spacing

builtins.str (pyrocko.guts.StringChoice), default: 'meter'

Unit of pixel space

LOSUnitVectors

class kite.scene.LOSUnitVectors(scene)[source]

Decompose line-of-sight (LOS) angles derived from displacement to unit vector.

unitE
Getter

(Cached) Unit vector east component, NxM matrix like displacement

Type

numpy.ndarray

unitN
Getter

(Cached) Unit vector north component, NxM matrix like displacement

Type

numpy.ndarray

unitU
Getter

(Cached) Unit vector vertical (up) component, NxM matrix like displacement

Type

numpy.ndarray