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]
  • dLon (float, optional) – Pixel spacing in longitude [deg]
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 modules are Gamma, Matlab, ISCE, GMTSAR, ROI_PAC, SARscape.

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)

Warning

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

Note

Expects:

  • Displacement grid (NetCDF, *los_ll.grd) in cm (gets transformed to meters)
  • LOS binary data (see instruction, *los.enu)

Calculate the corresponding unit look vectors with GMT5SAR SAT_look:

gmt grd2xyz unwrap_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

Warning

Data has to be georeferenced to latitude/longitude!

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

SARscape

Note

Expects:

  • Header file in *_disp.hdr
  • Displacement data in cm in *_disp
  • LOS data in *disp_ILOS and *disp_ALOS files.
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_mask
Getter:(Cached) Displacement numpy.nan mask
Type:numpy.ndarray, dtype numpy.bool
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 [rad] counter-clockwise from East

Important

Kite 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 look vector elevation angle towards satellite from 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

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.

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)

Warning

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

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

Note

Expects:

  • Displacement grid (NetCDF, *los_ll.grd) in cm (gets transformed to meters)
  • LOS binary data (see instruction, *los.enu)

Calculate the corresponding unit look vectors with GMT5SAR SAT_look:

gmt grd2xyz unwrap_ll.grd | gmt grdtrack -Gdem.grd |
awk {'print $1, $2, $4'} |
SAT_look 20050731.PRM -bos > 20050731.los.enu
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

Warning

Data has to be georeferenced to latitude/longitude!

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

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

Note

Expects:

  • Header file in *_disp.hdr
  • Displacement data in cm in *_disp
  • LOS data in *disp_ILOS and *disp_ALOS files.

SceneConfig

class kite.scene.SceneConfig(**kwargs)[source]
Configuration object, gathering kite.Scene and
sub-objects configuration.
meta

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

Scene metainformation

frame

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

Frame/reference configuration

quadtree

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

Quadtree parameters

covariance

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

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
N
Getter:(Cached) Undocumented
coordinates
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