co: Covariance and coherence matrix estimation

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

multi_look

multi_look(rslc1, rslc2, looks=(1, 1))

multi looked interferogram for raster data.

Parameters:

Name	Type	Description	Default
rslc1		reference rslc	required
rslc2		secondary rslc	required
looks	default: (1, 1)	range and azimuth looks	(1, 1)

intf

intf(rslc1, rslc2)

1 by 1 look interferogram for both raster and point cloud.

Parameters:

Name	Type	Description	Default
rslc1		reference rslc, arbitrary dims, e.g., 3D(raster stack), 2D(raster or point cloud stack) or 1D(point cloud)	required
rslc2		secondary rslc	required

emperical_co

emperical_co(rslc: ndarray, is_shp: ndarray, block_size: int = 128) -> tuple[ndarray, ndarray]

Maximum likelihood covariance estimator.

Parameters:

Name	Type	Description	Default
rslc	ndarray	rslc stack, dtype: cupy.complexfloating	required
is_shp	ndarray	shp bool, dtype: cupy.bool	required
block_size	int	no effect, kept for compatibility	128

Returns:

Type	Description
tuple[ndarray, ndarray]	the covariance and coherence matrix cov and coh

emperical_co_pc

emperical_co_pc(rslc: ndarray, idx: ndarray, pc_is_shp: ndarray, block_size: int = 128, image_pairs: ndarray = None, return_n_looks: bool = False)

Maximum likelihood covariance estimator for point cloud data.

Parameters:

Name	Type	Description	Default
rslc	ndarray	rslc stack, dtype: np.complex64	required
idx	ndarray	index of point target (azimuth_index, range_index), dtype: np.int32, shape: (n_pc, 2)	required
pc_is_shp	ndarray	shp bool, dtype: bool	required
block_size	int	no effect, kept for compatibility	128
image_pairs	ndarray	only coherence of those image pairs will estimated, dtype: np.int32, shape: (n_image_pair, 2)	None
return_n_looks	bool	also return the effective number of independent looks of the SHP set of each point	False

Returns:

Type

Description

ndarray or tuple[ndarray, ndarray]

coh, dtype:np.complex64, shape(n_pc, n_image_pair); with return_n_looks also n_looks, dtype float32, shape (n_pc,): the number of independent looks with the same variance of the coherence estimate as the correlated SHPs of the point (between 1 and the number of SHPs; smaller for compact SHP sets than for scattered ones of the same size), from the positions of the SHPs and the speckle correlation of rslc; the number of SHPs where rslc is too small to estimate the correlation

uncompress_single_coh_numba

uncompress_single_coh_numba(coh, nimages, image_pairs)

uncompress_coh

uncompress_coh(coh: ndarray, image_pairs: ndarray = None) -> ndarray

uncompress coh matrix to a hermitian matrix

Parameters:

Name	Type	Description	Default
coh	ndarray	compressed coherence stack, dtype: np.complex64, shape(...,n_image_pair)	required
image_pairs	ndarray	image pairs, dtype: np.int32, shape: (n_image_pair, 2), all pairs by default	None

Returns:

Type	Description
ndarray	uncompressed, dtype:np.complex64, shape(..., n_image_pair)

ad_intf_pc

ad_intf_pc(ref_rslc: ndarray, sec_rslc: ndarray, idx: ndarray, pc_is_shp: ndarray, block_size: int = 128) -> ndarray

Adaptive multilooking interferogram generation for point cloud data.

Parameters:

Name	Type	Description	Default
ref_rslc	ndarray	reference rslc, dtype: np.complex64	required
sec_rslc	ndarray	secondary rslc, dtype: np.complex64	required
idx	ndarray	index of point target (azimuth_index, range_index), dtype: np.int32, shape: (n_pc, 2)	required
pc_is_shp	ndarray	shp bool, dtype: bool	required
block_size	int	the CUDA block size, it only affects the calculation speed	128

Returns:

Type	Description
ndarray	coh, dtype:np.complex64, shape(n_pc, n_image_pair)

isPD

isPD(co: ndarray) -> ndarray

Parameters:

Name	Type	Description	Default
co	ndarray	absolute value of complex coherence/covariance stack	required

Returns:

Type	Description
ndarray	bool array indicating wheather coherence/covariance is positive define

nearestPD

nearestPD(co: ndarray) -> ndarray

Find the nearest positive-definite matrix to input matrix.

Parameters:

Name	Type	Description	Default
co	ndarray	stack of matrix with shape [...,N,N]	required

Returns:

Type	Description
ndarray	nearest positive definite matrix of input, shape [...,N,N]

regularize_spectral

regularize_spectral(coh: ndarray, beta: Union[float, ndarray]) -> ndarray

Spectral regularizer for coherence matrix.

Parameters:

Name	Type	Description	Default
coh	ndarray	stack of matrix with shape [...,N,N]	required
beta	Union[float, ndarray]	the regularization parameter, a float number or cupy ndarray with shape [...]	required

Returns:

Type	Description
ndarray	regularized matrix, shape [...,N,N]

Examples

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

import numpy as np
import moraine as mr

rng = np.random.default_rng(0)
nlines, width, nimages = 20, 30, 10
rslc = (rng.standard_normal((nlines, width, nimages)) + 1j * rng.standard_normal((nlines, width, nimages))).astype(np.complex64)
idx = np.array([[5, 5], [10, 15]], dtype=np.int32)              # (azimuth, range) of two points
pc_is_shp = np.ones((2, 5, 5), dtype=bool)                      # their SHPs in a 5 x 5 window (all here)

coh = mr.emperical_co_pc(rslc, idx, pc_is_shp)                   # compressed coherence, (n_points, n_pairs)
print(coh.shape, coh.dtype)
C = mr.uncompress_coh(coh)                                       # full hermitian matrices, (n_points, nimages, nimages)
print(C.shape, np.allclose(np.diagonal(C, axis1=1, axis2=2).real, 1, atol=1e-5))
print(mr.isPD(np.abs(C)))                                        # is the coherence magnitude matrix positive definite?

(2, 45) complex64
(2, 10, 10) True
[ True  True]

bad = np.abs(C[0]).copy()
bad[0, 1] = bad[1, 0] = 1.5                                      # not a valid coherence matrix any more
print(mr.isPD(bad[None])[0], mr.isPD(mr.nearestPD(bad[None]))[0])
intf = mr.intf(np.ascontiguousarray(rslc[..., 0]), np.ascontiguousarray(rslc[..., 1]))   # 1 x 1 look interferogram of two images
print(intf.shape, intf.dtype)

False True
(20, 30) complex64

The compressed layout is the upper triangle in the order of numpy.triu_indices(nimages, 1) (data contract); emperical_co_pc(..., return_n_looks=True) also gives the effective number of independent looks of each SHP set, the input of the weighted DS temporal coherence.