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

Commands of moraine.cli.ts (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
pc-reference	Point cloud data relative to a reference: the reference value of every image is subtracted from it
pc-disp	Line of sight displacement in millimeters from unwrapped phase of point clouds.

pc-reference

Point cloud data relative to a reference: the reference value of every image is subtracted from it. The reference value of an image is the median of the values of the reference points of ref_mask (by default), their mean, or the value of the point ref_point; give either ref_mask or ref_point. Afterwards the reference points have the median (mean, value) 0 in every image, e.g. displacements relative to a stable area. The reference points should be stable, coherent and in one region of the closure correction. The mask of the reference points stays in memory (1 byte per point).

moraine pc-reference --pc STR --out STR [--ref_mask STR] [--ref_point VALUE] [--method STR] [--ref_value STR] [--out_chunks VALUE] [--processes | --no-processes] [--n_workers VALUE] [--threads_per_worker VALUE]

argument	type	default	description
--pc	str	required	input point cloud data, shape (n_points,) or (n_points, n), floating point, chunks (points_block, 1); e.g. the unwrapped phase of every image (ts of unwrap-correct-closure-pc, radians) or displacements
--out	str	required	output pc minus the reference value of every image, same shape, dtype and unit as pc, chunks (out_chunks, 1)
--ref_mask	str	None	input the reference points, bool, shape (n_points,), True for at least one point; e.g. from polygon-mask
--ref_point	int	None	index of the one reference point, 0 .. n_points - 1, e.g. the point of a double click on a map of moraine.cli.view
--method	str	'median'	reference value from the points of ref_mask: 'median' or 'mean' of their values in the image, nan left out; not used with ref_point
--ref_value	str	None	output the reference value of every image, shape (n,) (shape (1,) for pc of shape (n_points,)), dtype and unit of pc
--out_chunks	int	None	point chunk size of out, that of pc by default
--processes		False	use processes for the workers instead of threads
--n_workers		1	number of workers
--threads_per_worker		4	tasks (images) a worker processes at the same time; a task holds two images of all points

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

In a pipeline (examples/06_products.toml, step reference):

[[step]]
name = "reference"                # median of the reference points subtracted from every image
run = "pc-reference"
pc = "unw/pc_ts.zarr"
ref_mask = "disp/pc_ref_mask.zarr"
out = "disp/pc_ts_ref.zarr"
ref_value = "disp/ref_value.zarr"

In Python:

import moraine.cli as mc
mc.pc_reference(pc, out, ref_mask=None, ref_point=None, method='median', ref_value=None, out_chunks=None, processes=False, n_workers=1, threads_per_worker=4)

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

pc-disp

Line of sight displacement in millimeters from unwrapped phase of point clouds.

moraine pc-disp --pc STR --out STR --wavelength VALUE [--out_chunks VALUE] [--processes | --no-processes] [--n_workers VALUE] [--threads_per_worker VALUE]

argument	type	default	description
--pc	str	required	input unwrapped phase in radians, shape (n_points,) or (n_points, n), floating point, chunks (points_block, 1); the phase of every image relative to a reference image, growing when the range gets shorter, e.g. ts of unwrap-correct-closure-pc or its output of pc-reference
--out	str	required	output line of sight displacement in millimeters, same shape as pc, float32, chunks (out_chunks, 1); positive towards the satellite (a shorter range); nan where pc is nan
--wavelength	float	required	radar wavelength in meters, between 0 and 1 (radar_wavelength of the metadata of load-gamma-metadata, e.g. 0.0554658 for Sentinel-1)
--out_chunks	int	None	point chunk size of out, that of pc by default
--processes		False	use processes for the workers instead of threads
--n_workers		1	number of workers
--threads_per_worker		4	tasks (images) a worker processes at the same time; a task holds two images of all points

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

In a pipeline (examples/06_products.toml, step disp):

[[step]]
name = "disp"
run = "pc-disp"
pc = "disp/pc_ts_ref.zarr"
out = "disp/pc_disp.zarr"
wavelength = "${wavelength}"

In Python:

import moraine.cli as mc
mc.pc_disp(pc, out, wavelength, out_chunks=None, processes=False, n_workers=1, threads_per_worker=4)

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