From c37803923bd3c2d9ff3cef1ba9c1e096d4dc732d Mon Sep 17 00:00:00 2001 From: maclariz Date: Wed, 28 Aug 2024 17:29:42 +0100 Subject: [PATCH] Update digital_dark_field.py Updated docstrings --- .../process/diffraction/digital_dark_field.py | 88 ++++++++++++++----- 1 file changed, 68 insertions(+), 20 deletions(-) diff --git a/py4DSTEM/process/diffraction/digital_dark_field.py b/py4DSTEM/process/diffraction/digital_dark_field.py index 64cb75faf..f82e03322 100644 --- a/py4DSTEM/process/diffraction/digital_dark_field.py +++ b/py4DSTEM/process/diffraction/digital_dark_field.py @@ -117,8 +117,6 @@ def aperture_array_generator( (N,2) array containing the aperture positions in a centered coordinate system. fig, ax: Figure and axes handles for plot. - - """ V, H = shape[0], shape[1] @@ -232,6 +230,32 @@ def aperture_array_subtract( """ This function takes in a set of aperture positions, and removes apertures within the user-specified tolerance from aperture_array_delete. + + Parameters + ---------- + aperture_positions: tuple, list, np.array + 2-element vector(s) of the diffraction space shape of positions of apertures + aperture_positions: tuple, list, np.array + 2-element vector(s) of the diffraction space shape of positions of apertures to remove from the list + tol: float + a single number giving the tolerance for a maximum distance between aperture positions in the two lists to still be considered a match + plot_result: bool + Plot the aperture array + plot_marker_size: float + Marker size in points (standard matplotlib) + plot_marker_radius_pixels: float + Marker radius in pixels. + figsize: (float, float) + Figure size. + returnfig: bool + Set to true to return the figure handles. + + Returns + ---------- + aperture_positions: + (N,2) array containing the aperture positions in the image coordinate system. + fig, ax: + Figure and axes handles for plot. """ # Determine which apertures to keep @@ -287,16 +311,23 @@ def pointlist_to_array( This function turns the py4dstem pointslist object to a simple numpy array that is more convenient for rapid array processing in numpy - idim and jdim are the dimensions in the Rx and Ry directions + idim and jdim are the dimensions in the Rx and Ry directions and are determined from the input + + Parameters + ---------- + bplist: pointslist + py4dstem pointslist - returns an array called points_array - This will be an 2D numpy array of n points x 5 columns: + Returns + ---------- + points_array: numpy array + This will be an 2D numpy array of n points x 5 columns: qx qy I Rx Ry - """ + """ for i, j in tqdmnd(bplist.Rshape[0], bplist.Rshape[1]): if i == j == 0: points_array = np.array( @@ -324,10 +355,20 @@ def pointlist_to_array( def pointlist_differences(aperture_position, points_array): """ - calculates differences between a specific aperture position - and a whole list of detected points for a dataset (as an array) + calculates Euclidean distances between a specific aperture position + and a whole list of detected points for a dataset + + Parameters + ---------- + aperture_position: tuple + 2-element vector of the diffraction space shape of a position of an aperture + points_array: numpy array + as produced by pointlist_to_array and defined in docstring for that function - returns the Euclidean distances as a 1D numpy array + Returns + ---------- + diff: numpy array + the Euclidean distances as a 1D numpy array """ subtractor = np.array( [[aperture_position[0], aperture_position[1]] * points_array.shape[0]] @@ -338,19 +379,26 @@ def pointlist_differences(aperture_position, points_array): def DDFimage(points_array, aperture_positions, Rshape=None, tol=1): """ - points_array is an array of points as calculated by pointlist_to_array - - aperture_positions is a numpy.array of aperture centers generated by aperture_array_generator, - with dimensions 2xN for N apertures. - - Rshape is a 2 element vector giving the real space dimensions. If not specified, we - take these value from the max along points_array. - - tol is the tolerance for a displacement between points and centers (in pixels) + Calculates a Digital Dark Field image from a list of detected diffraction peak positions in a points_array and a list of aperture_positions, within a defined matching tolerance + + This does rely on the pointslist_differences function for the calculation - this does rely on the pointslist_differences function + Parameters + ---------- + points_array: numpy array + as produced by pointlist_to_array and defined in docstring for that function + aperture_positions: tuple, list, np.array + 2-element vector(s) of the diffraction space shape of positions of apertures + Rshape: tuple, list, array + a 2 element vector giving the real space dimensions. If not specified, this is determined from the max along points_array + tol: float + the tolerance in pixels or calibrated units for a point in the points_array to be considered to match to an aperture position in the aperture_positions array - returns a the DDF image as a 2D numpy array + Returns + ---------- + image: numpy array + 2D numpy array with dimensions determined by Rshape + """ if Rshape is None: