SpeckleTracking¶

class pyrost.SpeckleTracking(**kwargs)¶

Wrapper class for the Robust Speckle Tracking algorithm. Performs reference_image and pixel_map updates.

Parameters

**kwargs (dict) – Dictionary of the attributes’ data specified in attr_set and init_set.

Variables

attr_set (set) – Set of attributes in the container which are necessary to initialize in the constructor.
init_set (set) – Set of optional data attributes.

Raises

ValueError – If an attribute specified in attr_set has not been provided.

Notes

Necessary attributes:

data : Measured frames.
dref : Reference to the STData object, from which SpeckleTracking object was derived.
dss_pix : The sample’s translations along the slow axis in pixels.
dfs_pix : The sample’s translations along the fast axis in pixels.
whitefield : Measured frames’ whitefield.
pixel_map : The pixel mapping between the data at the detector’s plane and the reference image at the reference plane.

Optional attributes:

error_frame : MSE (mean-squared-error) of the reference image and pixel mapping fit per pixel.
reference_image : The unabberated reference image of the sample.
m0 : The lower bounds of the fast detector axis of the reference image at the reference frame in pixels.
n0 : The lower bounds of the slow detector axis of the reference image at the reference frame in pixels.

See also

bin.make_reference: Full details of the reference_image update algorithm.
bin.update_pixel_map_gs: Full details of the pixel_map update algorithm based on grid search.

update_errors()¶

Return a new SpeckleTracking object with the updated error_frame.

Parameters: ls_ri (float) – reference_image length scale in pixels.
Returns: A new SpeckleTracking object with the updated error_frame.
Return type: SpeckleTracking
Raises: AttributeError – If reference_image was not generated beforehand.

See also

bin.mse_frame: Full details of the error metric.

update_pixel_map(ls_pm, sw_fs, sw_ss=0, method='search')¶

Return a new SpeckleTracking object with the updated pixel_map.

Parameters

sw_fs (int) – Search window size in pixels along the fast detector axis.
sw_ss (int, optional) – Search window size in pixels along the slow detector axis.
ls_pm (float, optional) – pixel_map length scale in pixels.
method ({'search', 'newton'}, optional) –
pixel_map update algorithm. The following keyword values are allowed:
- ’newton’ : Iterative Newton’s method based on finite difference gradient approximation.
- ’search’ : Grid search along the search window.

Returns

A new SpeckleTracking object with the updated pixel_map.

Return type

SpeckleTracking

Raises

AttributeError – If reference_image was not generated beforehand.
ValueError – If method keyword value is not valid.

update_reference(ls_ri, sw_fs, sw_ss=0)¶

Return a new SpeckleTracking object with the updated reference_image.

Parameters

ls_ri (float, optional) – reference_image length scale in pixels.
sw_ss (int, optional) – Search window size in pixels along the slow detector axis.
sw_fs (int, optional) – Search window size in pixels along the fast detector axis.

Returns

A new SpeckleTracking object with the updated reference_image.

Return type

SpeckleTracking

See also

bin.make_reference: Full details of the reference_image update algorithm.

update_translations(sw_fs, sw_ss=0)¶

Return a new SpeckleTracking object with the updated sample pixel translations (dss_pix, dfs_pix).

Parameters

sw_fs (int) – Search window size in pixels along the fast detector axis.
sw_ss (int, optional) – Search window size in pixels along the slow detector axis.
ls_ri (float, optional) – reference_image length scale in pixels.
method ({'search', 'newton'}, optional) –
pixel_map update algorithm. The following keyword values are allowed:
- ’newton’ : Iterative Newton’s method based on finite difference gradient approximation.
- ’search’ : Grid search along the search window.

Returns

A new SpeckleTracking object with the updated dss_pix, dfs_pix.

Return type

SpeckleTracking

Raises

AttributeError – If reference_image was not generated beforehand.

See also

bin.update_translations_gs: Full details of the sample translations update algorithm.

classmethod import_data(st_data)¶

Return a new SpeckleTracking object with all the necessary data attributes imported from the STData container object st_data.

Parameters: st_data (STData) – STData container object.
Returns: A new SpeckleTracking object.
Return type: SpeckleTracking

iter_update(ls_ri, ls_pm, sw_fs, sw_ss=0, n_iter=5, f_tol=0.001, method='search', update_translations=False, verbose=False, return_errors=False)¶

Perform iterative Robust Speckle Tracking update. ls_ri and ls_pm define high frequency cut-off to supress the noise. Iterative update terminates when the difference between total mean-squared-error (MSE) values of the two last iterations is less than f_tol.

Parameters

sw_fs (int) – Search window size in pixels along the fast detector axis.
sw_ss (int, optional) – Search window size in pixels along the slow detector axis.
ls_pm (float, optional) – pixel_map length scale in pixels.
ls_ri (float, optional) – reference_image length scale in pixels.
n_iter (int, optional) – Maximum number of iterations.
f_tol (float, optional) – Tolerance for termination by the change of the total MSE.
method ({'search', 'newton'}, optional) –
pixel_map update algorithm. The following keyword values are allowed:
- ’newton’ : Iterative Newton’s method based on finite difference gradient approximation.
- ’search’ : Grid search along the search window.
update_translations (bool, optional) – Update sample pixel translations if True.
return_errors (bool, optional) – Return errors array if True.

Returns

SpeckleTracking – A new SpeckleTracking object with the updated pixel_map and reference_image. dss_pix and dfs_pix are also updated if update_translations is True.
list – List of total MSE values for each iteration. Only if return_errors is True.

iter_update_gd(ls_ri, ls_pm, sw_fs, sw_ss=0, n_iter=30, f_tol=1e-06, momentum=0.0, learning_rate=1000.0, gstep=0.1, method='search', update_translations=False, verbose=False, return_extra=False)¶

Perform iterative Robust Speckle Tracking update. ls_ri and ls_pm define high frequency cut-off to supress the noise. ls_ri is iteratively updated by dint of Gradient Descent with momentum update procedure. Iterative update terminates when the difference between total mean-squared-error (MSE) values of the two last iterations is less than f_tol.

Parameters

sw_fs (int) – Search window size in pixels along the fast detector axis.
sw_ss (int, optional) – Search window size in pixels along the slow detector axis.
ls_pm (float, optional) – pixel_map length scale in pixels.
ls_ri (float, optional) – Initial reference_image length scale in pixels.
n_iter (int, optional) – Maximum number of iterations.
f_tol (float, optional) – Tolerance for termination by the change of the total MSE.
momentum (float, optional) – hyperparameter in interval (0.0-1.0) that accelerates gradient descent of ls_ri in the relevant direction and dampens oscillations.
learning_rate (float, optional) – Learning rate for ls_ri update procedure.
gstep (float, optional) – ls_ri step used to numerically calculate the MSE gradient.
method ({'search', 'newton'}, optional) –
pixel_map update algorithm. The following keyword values are allowed:
- ’newton’ : Iterative Newton’s method based on finite difference gradient approximation.
- ’search’ : Grid search along the search window.
update_translations (bool, optional) – Update sample pixel translations if True.
return_extra (bool, optional) – Return errors and ls_ri array if True.

Returns

SpeckleTracking – A new SpeckleTracking object with the updated pixel_map and reference_image. dss_pix and dfs_pix are also updated if update_translations is True.
list – List of total MSE values for each iteration. Only if return_errors is True.

mse_curve(lss_ri)¶

Return a mean-squared-error (MSE) survace.

Parameters: lss_ri (numpy.ndarray) – Set of reference_image length scales in pixels.
Returns: A mean-squared-error (MSE) surface.
Return type: numpy.ndarray

See also

bin.mse_total: Full details of the error metric.

mse_total(ls_ri)¶

Generate a reference image with the given ls_ri and return average total mean-squared-error (MSE).

Parameters: ls_ri (float) – reference_image length scale in pixels.
Returns: Average total mean-squared-error (MSE).
Return type: float

See also

bin.mse_total: Full details of the error metric.