flct#
- pyflct.flct.flct(image1, image2, deltat, deltas, sigma, order='row', quiet=False, biascor=False, thresh=0.0, absflag=False, skip=None, xoff=0, yoff=0, interp=False, kr=None, pc=False, latmin=0, latmax=0.2)[source]#
Performs Fourier Local Correlation Tracking by calling the FLCT C library.
Note
In the references there are some dat files which can be used to test the FLCT code. The best method to read those dat files is the
pyflct.read_2_images
andpyflct.read_3_images
as the arrays would automatically be read in row major format.If you use the IDL IO routines to get the input arrays from
dat
files, the IDL routines always read the binary files in the column major, but both Python and C, on which these functions are written are row major so the order of the arrays have to be changed which can be done with theorder
keyword. This may lead to different values in both the cases.If your input arrays are column major then pass the
order
parameter ascolumn
and it will automatically take care of the order change. But this can produce some changes in the values of the arrays.
Warning
All the below limitations have been directly taken from the C source user manual without any modifications. The original user manual can be found here.
FLCT is unable to find flows that are normal to image gradients. This is a defect of the LCT concept.
FLCT cannot determine velocities on scales below the scale size of structures in the images. This is a defect of the LCT concept.
Images that have minimal structure can give nonsensical velocity results.
Results can depend on value of
sigma
, so you must experiment to determine the best choice ofsigma
.Velocities corresponding to shifts less than 0.1 - 0.2 pixels are not always detected. It may be necessary to increase the amount of time between images, depending on the noise level in the images. Sometimes using the filtering option helps.
Velocities computed within
sigma
pixels of the image edges can be unreliable.Noisy images can result in spurious velocity results unless a suitable threshold value
thresh
is chosen.
- Parameters:
image1 (
numpy.ndarray
) – The first image.image2 (
numpy.ndarray
) – The second image taken afterdeltat
time of the first one.deltat (
float
) – The time interval between the two images in seconds.deltas (
float
) – Units of length of the side of a single pixel. Velocity is computed in units ofdeltas
/deltat
.sigma (
float
) – Sub-images are weighted by Gaussian of widthsigma
. Results can depend on value ofsigma
. The user must experiment to determine best choice ofsigma
. Ifsigma
is set to 0, only single values of shifts are returned. These values correspond to the overall shifts between the two images.order ({"row" | "column"}, optional) – The order in which the array elements are stored that is whether they are stored as row major or column major. Defaults to
row
.quiet (
bool
, optional) – If set toTrue
all the error messages of FLCT C code will be suppressed. Defaults toFalse
.biascor (
bool
, optional) – If set toTrue
bias correction will be applied while computing the velocities. This bias is intrinsic to the FLCT algorithm and can underestimate the velocities during calculations. For more details visit here.thresh (
float
, optional) – A calculation will not be done for a pixel if the average absolute value between the two images is less thanthresh
. Ifthresh
is between 0 and 1,thresh
is assumed given in in relative units of the maximum absolute pixel value in the average of the two images. Defaults to 0.absflag (
bool
, optional) – This is set toTrue
to force thethresh
values between 0 and 1 to be considered in absolute terms. Defaults to False.skip (
int
, optional) – The number of pixels to be skipped in thex
andy
direction after each calculation of a velocity for a pixel. Defaults toNone
.xoff (
int
, optional) – The offset in “x” direction afterskip
is enabled. Defaults to 0.yoff (
int
, optional) – The offset in “y” direction afterskip
is enabled. Defaults to 0.interp (
bool
, optional) – If set toTrue
interpolation will be performed at the skipped pixels. Defaults toFalse
.kr (
float
, optional) – Apply a low-pass filter to the sub-images, with a Gaussian of a characteristic wavenumber that is a factor ofkr
times the largest possible wave numbers in “x”, “y” directions.kr
should be positive. Defaults toNone
pc (
bool
, optional) – Set toTrue
if the images are Plate Carrée projected. Defaults toFalse
.latmin (
float
, optional) – Lower latitude limit in radians, used withpc
. Defaults to 0.latmax (
float
, optional) – Upper latitude limit in radians, used withpc
. Defaults to 0.2.
- Returns:
tuple
– A tuple containing the velocityndarray
in the following ordervx
,vy
, andvm
.vx
is the velocity at every pixel location in thex
direction.vy
is the velocity at every pixel location in they
direction.vm
is the mask array which is set to 1 at pixel locations where the FLCT calculations were performed, 0 where the calculations were not performed and 0.5 where the results were interpolated.
References
Welsch et al, ApJ 610, 1148, (2004)
Fisher & Welsch, PASP 383, 373, (2008)
Fisher et al., ApJS, accepted (2020)