ts: Deformation products of point clouds: spatial reference, displacement (decision 0040)

moraine.api.ts (source). Every name is also moraine.<name> (import moraine as mr).

pc_reference

pc_reference(data, ref, method: str = 'median')

Values relative to a reference: the reference value of every column is subtracted from the column.

Parameters:

Name	Type	Description	Default
data	ndarray	values of the points, shape (n_points,) or (n_points, n), floating point, numpy or cupy; e.g. the unwrapped phase of every image in radians (ts of unwrap_correct_closure_pc) or displacements	required
ref	ndarray | int	the reference: a bool mask of the reference points, shape (n_points,), True for at least one point; or the index of one reference point, 0 .. n_points - 1	required
method	str	reference value of a column from the points of a mask: 'median' or 'mean' of their values in the column, nan left out; not used with one reference point (its value is the reference value)	'median'

Returns:

Name	Type	Description
out	ndarray	data minus the reference value of its column, same shape and dtype as data; the median (mean, value) of the reference points is 0 in every column
ref_value	ndarray	reference value of every column, shape (n,), or () for data of shape (n_points,), dtype of data

Raises:

Type	Description
ValueError	when the reference points have no value (all nan) in a column

pc_disp

pc_disp(phase, wavelength: float)

Line of sight displacement in millimeters from unwrapped phase.

Parameters:

Name	Type	Description	Default
phase	ndarray	unwrapped phase in radians, any shape, floating point, numpy or cupy; the phase of an image relative to a reference image, growing when the range gets shorter, e.g. the image phases of unwrap_correct_closure_pc relative to a reference area (pc_reference)	required
wavelength	float	radar wavelength in meters, between 0 and 1 (e.g. 0.0554658 for Sentinel-1)	required

Returns:

Name	Type	Description
disp	ndarray	line of sight displacement in millimeters, same shape as phase, float32; positive towards the satellite (a shorter range); nan where phase is nan

Examples

Run when this manual is built; the output follows each snippet.

import numpy as np
import moraine as mr

n_points, nimages = 6, 4
offset = np.array([0.0, 0.5, -0.3, 1.2], dtype=np.float32)     # unknown value of every image, common to all points
motion = np.zeros((n_points, nimages), dtype=np.float32)
motion[4:] = np.arange(nimages) * 0.4                            # the last two points move, the first four are stable
ts = motion + offset                                             # e.g. image phases of the closure correction
ts[3, 2] += 2 * np.pi                                            # one stable point with an unwrapping error

stable = np.zeros(n_points, dtype=bool); stable[:4] = True      # the reference area
out, ref_value = mr.pc_reference(ts, stable)                     # median of the reference points per image
print(ref_value)
print(out.round(2))
out_mean = mr.pc_reference(ts, stable, method='mean')[0]         # the unwrapping error shifts the mean
print(out_mean[:, 2].round(2))
out_point = mr.pc_reference(ts, 0)[0]                            # one reference point
print(out_point[0])

[ 0.   0.5 -0.3  1.2]
[[0.   0.   0.   0.  ]
 [0.   0.   0.   0.  ]
 [0.   0.   0.   0.  ]
 [0.   0.   6.28 0.  ]
 [0.   0.4  0.8  1.2 ]
 [0.   0.4  0.8  1.2 ]]
[-1.57 -1.57 -1.57  4.71 -0.77 -0.77]
[0. 0. 0. 0.]

The median of the reference area removes the value common to all points in every image; one point with an unwrapping error in the area does not change it, while it shifts the mean of image 2.

disp = mr.pc_disp(out, wavelength=0.0554658)                    # Sentinel-1: 1 rad = 4.41 mm
print(disp.dtype)
print(disp.round(2))

float32
[[ 0.    0.    0.    0.  ]
 [ 0.    0.    0.    0.  ]
 [ 0.    0.    0.    0.  ]
 [ 0.    0.   27.73  0.  ]
 [ 0.    1.77  3.53  5.3 ]
 [ 0.    1.77  3.53  5.3 ]]

The referenced phases in millimeters along the line of sight: the moving points come towards the satellite by 1.77 mm per image (0.4 rad); a whole cycle of unwrapping error is half a wavelength, 27.7 mm.