pl: Phase linking (CLI)

Commands of moraine.cli.pl (source); the same functions are called in Python as mc.<name>(...) with import moraine.cli as mc. The help below is generated from the docstrings, like moraine COMMAND --help.

command	summary
emi	Phase linking with EMI estimator.
ds-temp-coh	DS temporal coherence, optionally also weighted by the coherence of the image pairs.
emperical-co-emi-temp-coh-pc	estimating emperical coherence matrix, phase linking and estimating temporal coherence on point cloud data.

emi

Phase linking with EMI estimator.

moraine emi --coh STR --ph STR [--ref VALUE] [--regularize | --no-regularize] [--chunks INT INT] [--cuda | --no-cuda] [--processes VALUE] [--n_workers VALUE] [--threads_per_worker VALUE]

argument	type	default	description
--coh	str	required	input complex coherence of the points (upper triangle of the coherence matrix), shape (n_points, n_image_pairs)
--ph	str	required	output phase history of the points, complex, shape (n_points, nimages)
--ref	int	0	index of the reference image, its phase is set to 0
--regularize	bool	True	regularize the coherence matrix of the points whose coherence magnitude matrix is not positive definite or numerically singular (e.g. when the number of images approaches the number of independent looks of the SHPs; without it their phase history is not reliable); points with a well conditioned positive definite matrix are not changed
--chunks	int	None	point chunk size of the output data, same as coh by default
--cuda	bool	False	if use cuda for processing, false by default
--processes		None	use processes (True) or threads (False) for the workers, only for cpu processing. Default: False
--n_workers		None	number of workers. Default: 1 for cpu, one per GPU for cuda
--threads_per_worker		None	tasks a worker runs at the same time. Default: 2

Global options: --json, --traceback, --log FILE, -q / --quiet (conventions).

In a pipeline (not used by the example pipelines; required arguments only):

[[step]]
name = "emi"
run = "emi"
coh = "..."
ph = "..."

In Python:

import moraine.cli as mc
mc.emi(coh, ph, ref=0, regularize=True, chunks=None, cuda=False, processes=None, n_workers=None, threads_per_worker=None)

The array function mr.emi does the same on numpy / cupy arrays in memory.

ds-temp-coh

DS temporal coherence, optionally also weighted by the coherence of the image pairs.

moraine ds-temp-coh --coh STR --ph STR [--t_coh STR] [--tnet STR] [--n_looks STR] [--t_coh_w STR] [--eff_n_pairs STR] [--n_components STR] [--alpha VALUE] [--chunks INT INT] [--cuda | --no-cuda] [--processes VALUE] [--n_workers VALUE] [--threads_per_worker VALUE]

argument	type	default	description
--coh	str	required	input complex coherence of the points (upper triangle of the coherence matrix), shape (n_points, n_image_pairs)
--ph	str	required	input phase history of the points, complex, shape (n_points, nimages)
--t_coh	str	None	output temporal coherence of the points, every image pair weighted the same, shape (n_points,)
--tnet	str	None	input path of a saved TempNet with the image pairs of coh; all image pairs by default
--n_looks	str	None	input effective number of independent looks of the coherence of the points, float32, shape (n_points,), in the order of coh: the merged n_looks_dir of emperical-co-pc; needed by t_coh_w and eff_n_pairs
--t_coh_w	str	None	output weighted temporal coherence of the points, float32, shape (n_points,), 0..1: the image pairs weighted by their squared coherence without the noise bias, so that incoherent pairs (e.g. long time spans in vegetation) do not lower it; NaN where no image pair is above the noise level
--eff_n_pairs	str	None	output effective number of image pairs the weighted temporal coherence rests on, float32, shape (n_points,), 0..n_image_pairs; a high weighted temporal coherence of few effective pairs is not reliable
--n_components	str	None	output number of connected components of the graph whose nodes are the images and whose edges are the coherent image pairs, int16, shape (n_points,), 1..nimages; 1 means every image is linked to every other by coherent pairs, with more the phase between the groups of images is not constrained by any coherent pair, whatever the weighted temporal coherence is; needs n_looks
--alpha	float	0.001	probability that a point without any coherent image pair (pure noise) has all images connected (n_components 1); it sets the squared coherence above which an image pair counts as coherent, depending on the number of looks and of images; 1e-6 <= alpha <= 0.5; only with n_looks
--chunks	int	None	point cloud chunk size, same as coh by default
--cuda	bool	False	if use cuda for processing, false by default
--processes		None	use processes (True) or threads (False) for the workers, only for cpu processing. Default: False
--n_workers		None	number of workers. Default: 1 for cpu, one per GPU for cuda
--threads_per_worker		None	tasks a worker runs at the same time. Default: 2

Global options: --json, --traceback, --log FILE, -q / --quiet (conventions).

In a pipeline (not used by the example pipelines; required arguments only):

[[step]]
name = "ds_temp_coh"
run = "ds-temp-coh"
coh = "..."
ph = "..."

In Python:

import moraine.cli as mc
mc.ds_temp_coh(coh, ph, t_coh=None, tnet=None, n_looks=None, t_coh_w=None, eff_n_pairs=None, n_components=None, alpha=0.001, chunks=None, cuda=False, processes=None, n_workers=None, threads_per_worker=None)

The array function mr.ds_temp_coh does the same on numpy / cupy arrays in memory.

emperical-co-emi-temp-coh-pc

estimating emperical coherence matrix, phase linking and estimating temporal coherence on point cloud data.

moraine emperical-co-emi-temp-coh-pc --rslc STR --is_shp_dir STR --gix STR --ph_dir STR --t_coh_dir STR [--t_coh_w_dir STR] [--eff_n_pairs_dir STR] [--n_components_dir STR] [--alpha VALUE] [--batch_size VALUE] [--regularize | --no-regularize] [--chunks INT INT] [--cuda | --no-cuda] [--processes VALUE] [--n_workers VALUE] [--threads_per_worker VALUE]

argument	type	default	description
--rslc	str	required	input rslc stack, shape (nlines, width, nimages)
--is_shp_dir	str	required	input directory with the SHP bool arrays of the points, one zarr per raster chunk, made by ras2pc_ras_chunk
--gix	str	required	input grid index of the point cloud (azimuth, range), shape (n_points, 2), int
--ph_dir	str	required	output directory with the phase history of the points, complex, shape (n_points, nimages), one zarr per raster chunk; merge with pc_concat and the key of ras2pc_ras_chunk
--t_coh_dir	str	required	output directory with the temporal coherence of the points, shape (n_points,), one zarr per raster chunk
--t_coh_w_dir	str	None	output directory with the weighted temporal coherence of the points (see ds-temp-coh), shape (n_points,), float32, 0..1, NaN where no image pair is above the noise level, one zarr per raster chunk; the effective number of looks of each point comes from the positions of its SHPs and the speckle correlation of rslc
--eff_n_pairs_dir	str	None	output directory with the effective number of image pairs of the weighted temporal coherence, shape (n_points,), float32, one zarr per raster chunk; a high weighted temporal coherence of few effective pairs is not reliable
--n_components_dir	str	None	output directory with the number of connected components of the graph whose nodes are the images and whose edges are the coherent image pairs (see ds-temp-coh), shape (n_points,), int16, 1..nimages, one zarr per raster chunk; 1 means every image is linked to every other by coherent pairs
--alpha	float	0.001	probability that a point without any coherent image pair (pure noise) has all images connected; 1e-6 <= alpha <= 0.5; see ds-temp-coh; only with one of the weighted outputs
--batch_size	int	None	number of points a worker processes at once; the coherence matrices of a batch take 8 bytes per image pair and point, their estimation on the GPU up to 1 GiB more. Default: as many points as 1 GiB of coherence matrices hold (small batches cost time: thousands of small GPU operations per batch)
--regularize	bool	True	regularize the coherence matrix in the phase linking as regularize of emi; the temporal coherence is computed with the coherence matrix as estimated
--chunks	tuple[int, int]	None	parallel processing (azimuth, range) chunk size. Default: rslc.chunks[:2]
--cuda	bool	False	if use cuda for processing, false by default
--processes		None	use processes (True) or threads (False) for the workers, only for cpu processing. Default: False
--n_workers		None	number of workers. Default: 1 for cpu, one per GPU for cuda
--threads_per_worker		None	tasks a worker runs at the same time. Default: 2

Global options: --json, --traceback, --log FILE, -q / --quiet (conventions).

In a pipeline (examples/03_ds.toml, step phase_linking):

[[step]]
name = "phase_linking"
run = "emperical-co-emi-temp-coh-pc"
rslc = "raw/rslc.zarr"
is_shp_dir = "ds/chunks/ds_can_is_shp"
gix = "ds/ds_can_gix_ras_order.zarr"
ph_dir = "ds/chunks/ds_can_ph"
t_coh_dir = "ds/chunks/ds_can_t_coh"
t_coh_w_dir = "ds/chunks/ds_can_t_coh_w"
n_components_dir = "ds/chunks/ds_can_n_components"
alpha = 1e-3                      # a point without any coherent image pair has all images connected with this probability
chunks = [1000, 1000]

# ---- hilbert order

In Python:

import moraine.cli as mc
mc.emperical_co_emi_temp_coh_pc(rslc, is_shp_dir, gix, ph_dir, t_coh_dir, t_coh_w_dir=None, eff_n_pairs_dir=None, n_components_dir=None, alpha=0.001, batch_size=None, regularize=True, chunks=None, cuda=False, processes=None, n_workers=None, threads_per_worker=None)

The array function mr.emperical_co_emi_temp_coh_pc does the same on numpy / cupy arrays in memory.