2.1.1. fakecbed.discretized.CBEDPattern

class CBEDPattern(undistorted_tds_model=None, undistorted_disks=(), undistorted_misc_shapes=(), undistorted_outer_illumination_shape=None, gaussian_filter_std_dev=0, num_pixels_across_pattern=512, distortion_model=None, apply_shot_noise=False, detector_partition_width_in_pixels=0, cold_pixels=(), mask_frame=(0, 0, 0, 0), skip_validation_and_conversion=False)

Bases: PreSerializableAndUpdatable

The parameters of a discretized fake convergent beam electron diffraction (CBED) pattern.

A series of parameters need to be specified in order to create an image of a fake CBED pattern, with the most important parameters being: the set of intensity patterns of undistorted shapes that determine the undistorted noiseless non-blurred uncorrupted (UNNBU) fake CBED pattern; and a distortion model which transforms the UNNBU fake CBED pattern into a distorted noiseless non-blurred uncorrupted (DNNBU) fake CBED pattern. The remaining parameters determine whether additional images effects are applied, like e.g. shot noise or blur effects. Note that in the case of the aforementioned shapes, we expand the notion of intensity patterns to mean a 2D real-valued function, i.e. it can be negative. To be clear, we do not apply this generalized notion of intensity patterns to the fake CBED patterns: in such cases intensity patterns mean 2D real-valued functions that are strictly nonnegative.

Let \(u_{x}\) and \(u_{y}\) be the fractional horizontal and vertical coordinates, respectively, of a point in an undistorted image, where \(\left(u_{x},u_{y}\right)=\left(0,0\right)\) is the bottom left corner of the image. Secondly, let \(q_{x}\) and \(q_{y}\) be the fractional horizontal and vertical coordinates, respectively, of a point in a distorted image, where \(\left(q_{x},q_{y}\right)=\left(0,0\right)\) is the bottom left corner of the image. When users specify the distortion model, represented by an instance of the class distoptica.DistortionModel, they also specify a coordinate transformation, \(\left(T_{⌑;x}\left(u_{x},u_{y}\right), T_{⌑;x}\left(u_{x},u_{y}\right)\right)\), which maps a given coordinate pair \(\left(u_{x},u_{y}\right)\) to a corresponding coordinate pair \(\left(q_{x},q_{y}\right)\), and implicitly a right-inverse to said coordinate transformation, \(\left(T_{\square;x}\left(q_{x},q_{y}\right), T_{\square;y}\left(q_{x},q_{y}\right)\right)\), that maps a coordinate pair \(\left(q_{x},q_{y}\right)\) to a corresponding coordinate pair \(\left(u_{x},u_{y}\right)\), when such a relationship exists for \(\left(q_{x},q_{y}\right)\).

The calculation of the image of the target fake CBED pattern involves calculating various intermediate images which are subsequently combined to yield the target image. These intermediate images share the same horizontal and vertical dimensions in units of pixels, which may differ from those of the image of the target fake CBED pattern. Let \(N_{\mathcal{I};x}\) and \(N_{\mathcal{I};y}\) be the number of pixels in the image of the target fake CBED pattern from left to right and top to bottom respectively, and let \(N_{\mathring{\mathcal{I}};x}\) and \(N_{\mathring{\mathcal{I}};y}\) be the number of pixels in each of the aforementioned intermediate images from left to right and top to bottom respectively. In fakecbed, we assume that

(2.1.1.1)\[N_{\mathcal{I};x}=N_{\mathcal{I};y},\]

(2.1.1.2)\[N_{\mathring{\mathcal{I}};x}\ge N_{\mathcal{I};x},\]

and

(2.1.1.3)\[N_{\mathring{\mathcal{I}};y}\ge N_{\mathcal{I};y}.\]

The integer \(N_{\mathcal{I};x}\) is specified by the parameter num_pixels_across_pattern. The integers \(N_{\mathring{\mathcal{I}};x}\) and \(N_{\mathring{\mathcal{I}};y}\) are specified indirectly by the parameter distortion_model. The parameter distortion_model specifies the distortion model, which as mentioned above is represented by an instance of the class distoptica.DistortionModel. One of the parameters of said distortion model is the integer pair sampling_grid_dims_in_pixels. In the current context, sampling_grid_dims_in_pixels[0] and sampling_grid_dims_in_pixels[1] are equal to \(N_{\mathring{\mathcal{I}};x}\) and \(N_{\mathring{\mathcal{I}};y}\) respectively.

As mentioned above, a set of intensity patterns need to be specified in order to create the target fake CBED pattern. The first of these is the intensity pattern of an undistorted thermal diffuse scattering (TDS) model, \(\mathcal{I}_{\text{TDS}}\left(u_{x},u_{y}\right)\), which is specified by the parameter undistorted_tds_model. The second of these intensity patterns is that of the undistorted outer illumination shape, \(\mathcal{I}_{\text{OI}}\left(u_{x},u_{y}\right)\), which is specified by the parameter undistorted_outer_illumination_shape. \(\mathcal{I}_{\text{OI}}\left(u_{x},u_{y}\right)\) is defined such that for every coordinate pair \(\left(u_{x},u_{y}\right)\), if \(\mathcal{I}_{\text{OI}}\left(u_{x},u_{y}\right)=0\) then the value of the UNNBU fake CBED pattern is also equal to 0. A separate subset of the intensity patterns that need to be specified are \(N_{\text{D}}\) intensity patterns of undistorted nonuniform circles and/or ellipses, \(\left\{ \mathcal{I}_{k;\text{D}}\left(u_{x},u_{y}\right)\right\} _{k=0}^{N_{\text{D}}-1}\), which is specified by the parameter undistorted_disks. Each intensity pattern \(\mathcal{I}_{k;\text{D}}\left(u_{x},u_{y}\right)\) is suppose to depict one of the CBED disks in the fake CBED pattern in the absence of the intensity background. Moreover, each intensity pattern \(\mathcal{I}_{k;\text{D}}\left(u_{x},u_{y}\right)\) has a corresponding supporting intensity pattern \(\mathcal{I}_{k;\text{DS}}\left(u_{x},u_{y}\right)\), which is defined such that for every coordinate pair \(\left(u_{x},u_{y}\right)\), if \(\mathcal{I}_{k;\text{DS}}\left(u_{x},u_{y}\right)=0\) then \(\mathcal{I}_{k;\text{D}}\left(u_{x},u_{y}\right)=0\). The remaining intensity patterns that need to be specified, of which there are \(N_{\text{M}}\), are intensity patterns of undistorted miscellaneous shapes, \(\left\{ \mathcal{I}_{k;\text{M}}\left(u_{x},u_{y}\right)\right\} _{k=0}^{N_{\text{M}}-1}\), which is specified by the parameter undistorted_misc_shapes. These patterns, along with that of the TDS model, contribute to the intensity background.

To add blur effects, users can specify a nonzero standard deviation \(\sigma_{\text{blur}}\) of the Gaussian filter used to yield such blur effects on the target fake CBED pattern. The value of \(\sigma_{\text{blur}}\) is specified by the parameter gaussian_filter_std_dev.

To add shot noise effects to the image of the target fake CBED pattern, the parameter apply_shot_noise needs to be set to True.

For some pixelated electron detectors, the pixels of a number \(N_{\text{DPW}}\) of contiguous rows and an equal number of contiguous columns will not measure or readout incident electron counts. Instead, the final intensity values measured are inpainted according to the final intensity values of the other pixels in the detector. The intersection of the aforementioned contiguous block of rows and the aforementioned contiguous block of columns is located within one pixel of the center of the detector. The integer \(N_{\text{DPW}}\), which we call the detector partition width in units of pixels, is specified by the parameter detector_partition_width_in_pixels.

Cold pixels, which are individual zero-valued pixels in the image of the target fake CBED pattern, are specified by the parameter cold_pixels. Let \(N_{\text{CP}}\) be the number of cold pixels in the image of the target fake CBED pattern. Furthermore, let \(\left\{ n_{k;\text{CP}}\right\} _{k=0}^{N_{\text{CP}}-1}\) and \(\left\{ m_{k;\text{CP}}\right\} _{k=0}^{N_{\text{CP}}-1}\) be integer sequences respectively, where \(n_{k;\text{CP}}\) and \(m_{k;\text{CP}}\) are the row and column indices respectively of the \(k^{\text{th}}\) cold pixel. For every nonnegative integer k less than \(N_{\text{CP}}\), cold_pixels[k][0] and ``cold_pixels[k][1] are \(n_{k;\text{CP}}\) and \(m_{k;\text{CP}}\) respectively, with the integer \(k\) being equal to the value of k.

The mask frame of the image of the target fake CBED pattern is specified by the parameter mask_frame, which is expected to be a 4-element tuple, \(\left(L, R, B, T\right)\), of nonnegative integers. mask_frame[0], mask_frame[1], mask_frame[2], and mask_frame[3] are the widths, in units of pixels, of the left, right, bottom, and top sides of the mask frame respectively. If all elements of mask_frame are zero, then no pixels in the image of the target fake CBED pattern are masked by the mask frame.

Below we describe in more detail how various attributes of the current class are effectively calculated. Before doing so, we need to introduce a few more quantities:

(2.1.1.4)\[j\in\left\{ j^{\prime}\right\}_{j^{\prime}=0}^{ N_{\mathcal{\mathring{I}};x}-1},\]

(2.1.1.5)\[i\in\left\{ i^{\prime}\right\} _{i^{\prime}=0}^{ N_{\mathcal{\mathring{I}};y}-1}\]

(2.1.1.6)\[q_{\mathcal{\mathring{I}};x;j}=\left(j+\frac{1}{2}\right) \Delta q_{\mathcal{\mathring{I}};x},\]

(2.1.1.7)\[q_{\mathcal{\mathring{I}};y;i}=1-\left(i+\frac{1}{2}\right) \Delta q_{\mathcal{\mathring{I}};y},\]

(2.1.1.8)\[\Delta q_{\mathcal{\mathring{I}};x}= \frac{1}{N_{\mathcal{\mathring{I}};x}},\]

(2.1.1.9)\[\Delta q_{\mathcal{\mathring{I}};y}= \frac{1}{N_{\mathcal{\mathring{I}};y}}.\]

(2.1.1.10)\[m\in\left\{ m^{\prime}\right\} _{m^{\prime}=0}^{N_{\mathcal{I};x}-1},\]

(2.1.1.11)\[n\in\left\{ n^{\prime}\right\} _{n^{\prime}=0}^{N_{\mathcal{I};y}-1},\]

and

(2.1.1.12)\[\begin{split}\mathbf{J}_{\square}\left(q_{x},q_{y}\right)= \begin{pmatrix}\frac{\partial T_{\square;x}}{\partial q_{x}} & \frac{\partial T_{\square;x}}{\partial q_{y}}\\ \frac{\partial T_{\square;y}}{\partial q_{x}} & \frac{\partial T_{\square;y}}{\partial q_{y}} \end{pmatrix},\end{split}\]

where the derivatives in Eq. (2.1.1.12) are calculated numerically using the second-order accurate central differences method. The aforementioned attributes of the current class are effectively calculated by executing the following steps:

1. Calculate

(2.1.1.13)\[\mathring{\mathcal{I}}_{\text{OI};⌑;i,j}\leftarrow \mathcal{I}_{\text{OI}}\left( T_{\square;x}\left(q_{\mathring{\mathcal{I}};x;j}, q_{\mathring{\mathcal{I}};y;i}\right), T_{\square;y}\left(q_{\mathring{\mathcal{I}};x;j}, q_{\mathring{\mathcal{I}};y;i}\right)\right),\]

(2.1.1.14)\[\begin{split}\mathring{\mathcal{I}}_{\text{OI};⌑;i,j}\leftarrow\begin{cases} \text{True}, & \text{if }\mathring{\mathcal{I}}_{\text{OI};⌑;i,j} \neq0,\\ \text{False}, & \text{otherwise}, \end{cases}\end{split}\]

and then apply max pooling to \(\mathring{\mathcal{I}}_{\text{OI};⌑;i,j}\) with a kernel of dimensions \(\left(N_{\mathring{\mathcal{I}};y}/N_{\mathcal{I};y}, N_{\mathring{\mathcal{I}};x}/N_{\mathcal{I};x}\right)\) and store the result in \(\mathcal{I}_{\text{OI};⌑;n,m}\).

2. Calculate

(2.1.1.15)\[\mathcal{I}_{\text{DOM};⌑;n,m}\leftarrow0.\]

3. Calculate

(2.1.1.16)\[\begin{split}\mathcal{I}_{\text{MF};⌑;n,m}\leftarrow\begin{cases} \text{True}, & \text{if }L\le m<N_{\mathcal{I};x}-R \text{ and }T\le n<N_{\mathcal{I};y}-B,\\ \text{False}, & \text{otherwise}. \end{cases}\end{split}\]

4. For \(0\le k<N_{\text{D}}\), calculate

(2.1.1.17)\[\begin{split}\mathring{\mathcal{I}}_{\text{CBED};⌑;i,j}& \leftarrow\mathring{\mathcal{I}}_{\text{CBED};⌑;i,j}\\& \quad\quad\mathop{+}\mathcal{I}_{k;\text{D}}\left(T_{\square;x}\left( q_{\mathring{\mathcal{I}};x;j},q_{\mathring{\mathcal{I}};y;i}\right), T_{\square;y}\left(q_{\mathring{\mathcal{I}};x;j}, q_{\mathring{\mathcal{I}};y;i}\right)\right),\end{split}\]

(2.1.1.18)\[\mathring{\mathcal{I}}_{k;\text{DS};⌑;i,j}\leftarrow \mathcal{I}_{k;\text{DS}}\left(T_{\square;x}\left( q_{\mathring{\mathcal{I}};x;j},q_{\mathring{\mathcal{I}};y;i}\right), T_{\square;y}\left(q_{\mathring{\mathcal{I}};x;j}, q_{\mathring{\mathcal{I}};y;i}\right)\right),\]

(2.1.1.19)\[\begin{split}\mathring{\mathcal{I}}_{k;\text{DS};⌑;i,j}\leftarrow\begin{cases} \text{True}, & \text{if }\mathring{\mathcal{I}}_{k;\text{DS};⌑;i,j} \neq0,\\ \text{False}, & \text{otherwise}, \end{cases}\end{split}\]

then apply max pooling to \(\mathring{\mathcal{I}}_{k;\text{DS};⌑;i,j}\) with a kernel of dimensions \(\left(N_{\mathring{\mathcal{I}};y}/N_{\mathcal{I};y}, N_{\mathring{\mathcal{I}};x}/N_{\mathcal{I};x}\right)\) and store the result in \(\mathcal{I}_{k;\text{DS};⌑;n,m}\), and calculate

(2.1.1.20)\[\mathcal{I}_{\text{DOM};⌑;n,m}\leftarrow \mathcal{I}_{\text{DOM};⌑;n,m}+\mathcal{I}_{k;\text{DS};⌑;n,m}.\]

5. Calculate

(2.1.1.21)\[\mathcal{I}_{\text{DOM};⌑;n,m}\leftarrow \mathcal{I}_{\text{MF};⌑;n,m} \mathcal{I}_{\text{OI};⌑;n,m} \mathcal{I}_{\text{DOM};⌑;n,m}.\]

6. For \(0\le k<N_{\text{M}}\), calculate

(2.1.1.22)\[\begin{split}\mathring{\mathcal{I}}_{\text{CBED};⌑;i,j}& \leftarrow\mathring{\mathcal{I}}_{\text{CBED};⌑;i,j}\\& \quad\quad\mathop{+}\mathcal{I}_{k;\text{M}}\left(T_{\square;x}\left( q_{\mathring{\mathcal{I}};x;j},q_{\mathring{\mathcal{I}};y;i}\right), T_{\square;y}\left(q_{\mathring{\mathcal{I}};x;j}, q_{\mathring{\mathcal{I}};y;i}\right)\right).\end{split}\]

7. Calculate

(2.1.1.23)\[\mathring{\mathcal{I}}_{\text{CBED};⌑;i,j}\leftarrow \text{det}\left(\mathbf{J}_{\square}\left( q_{\mathring{\mathcal{I}};x;j}, q_{\mathring{\mathcal{I}};y;i}\right)\right) \left|\mathring{\mathcal{I}}_{\text{CBED};⌑;i,j}\right|.\]

8. Apply average pooling to \(\mathring{\mathcal{I}}_{\text{CBED};⌑;i,j}\) with a kernel of dimensions \(\left(N_{\mathring{\mathcal{I}};y}/N_{\mathcal{I};y}, N_{\mathring{\mathcal{I}};x}/N_{\mathcal{I};x}\right)\), and store the result in \(\mathcal{I}_{\text{CBED};⌑;n,m}\).

9. Apply a Gaussian filter to \(\mathcal{I}_{\text{CBED};⌑;n,m}\) that is identical in outcome to that implemented by the function scipy.ndimage.gaussian_filter(), with sigma set to gaussian_filter_std_dev and truncate set to 4, and store the result in \(\mathcal{I}_{\text{CBED};⌑;n,m}\).

10. Calculate

(2.1.1.24)\[k_{\text{I};1}\leftarrow \left\lfloor \frac{N_{\mathcal{I};x}-1}{2}\right\rfloor -\left\lfloor \frac{N_{\text{DPW}}}{2}\right\rfloor ,\]

and

(2.1.1.25)\[k_{\text{I};2}\leftarrow k_{\text{I};1}+N_{\text{DPW}}-1.\]

11. If apply_shot_noise is set to True, then apply shot/Poisson noise to \(\mathcal{I}_{\text{CBED};⌑;n,m}\), and store the result in \(\mathcal{I}_{\text{CBED};⌑;n,m}\).

12. If \(N_{\text{DPW}}>0\), then inpaint the pixels in the rows indexed from \(k_{\text{I};1}\) to \(k_{\text{I};2}\) and the columns indexed from \(k_{\text{I};1}\) to \(k_{\text{I};2}\) of the image \(\mathcal{I}_{\text{CBED};⌑;n,m}\) using the function skimage.restoration.inpaint_biharmonic(), and store the result in \(\mathcal{I}_{\text{CBED};⌑;n,m}\).

13. Calculate

(2.1.1.26)\[\mathcal{I}_{\text{CBED};⌑;n,m}\leftarrow \mathcal{I}_{\text{MF};⌑;n,m} \mathcal{I}_{\text{OI};⌑;n,m} \mathcal{I}_{\text{CBED};⌑;n,m}.\]

14. Update pixels of \(\mathcal{I}_{\text{CBED};⌑;n,m}\) at pixel locations specified by cold_pixels to the value of zero.

15. Apply min-max normalization of \(\mathcal{I}_{\text{CBED};⌑;n,m}\), and store result in \(\mathcal{I}_{\text{CBED};⌑;n,m}\).

16. Calculate

(2.1.1.27)\[\mathcal{I}_{\text{CS};⌑;n,m}\leftarrow1 -\mathcal{I}_{\text{MF};⌑;n,m}\mathcal{I}_{\text{OI};⌑;n,m}.\]

17. Convolve a \(3 \times 3\) filter of ones over a symmetrically unity-padded \(\mathcal{I}_{\text{CS};⌑;n,m}\) to yield an output matrix with the same dimensions of \(\mathcal{I}_{\text{CBED};⌑;n,m}\), and store said output matrix in \(\mathcal{I}_{\text{CS};⌑;n,m}\).

18. For \(0\le k<N_{\text{D}}\), calculate

(2.1.1.28)\[\mathcal{I}_{k;\text{DCM};⌑;n,m}\leftarrow \mathcal{I}_{\text{CS};⌑;n,m}\mathcal{I}_{k;\text{DS};⌑;n,m},\]

(2.1.1.29)\[\begin{split}\Omega_{k;\text{DCR};⌑}\leftarrow\begin{cases} \text{True}, & \text{if }\sum_{n,m}\mathcal{I}_{k;\text{DCM};⌑;n,m} \neq0,\\ \text{False}, & \text{otherwise}, \end{cases}\end{split}\]

and

(2.1.1.30)\[\begin{split}\Omega_{k;\text{DAR};⌑}\leftarrow\begin{cases} \text{True}, & \text{if }\sum_{n,m}\mathcal{I}_{k;\text{DS};⌑;n,m}=0,\\ \text{False}, & \text{otherwise}. \end{cases}\end{split}\]

We refer to \(\mathcal{I}_{\text{CBED};⌑;n,m}\) as the image of the target fake CBED pattern, \(\mathcal{I}_{\text{OI};⌑;n,m}\) as the image of the illumination support, \(\mathcal{I}_{\text{DOM};⌑;n,m}\) as the image of the disk overlap map, \(\mathcal{I}_{k;\text{DS};⌑;n,m}\) as the image of the support of the \(k^{\text{th}}\) CBED disk, \(\left\{ \Omega_{k;\text{DCR};⌑}\right\}_{k=0}^{N_{\text{D}}-1}\) as the disk clipping registry, and \(\left\{ \Omega_{k;\text{DAR};⌑}\right\}_{k=0}^{N_{\text{D}}-1}\) as the disk absence registry.

Parameters:

undistorted_tds_modelfakecbed.tds.Model | None, optional

The intensity pattern of the undistorted TDS model, \(\mathcal{I}_{\text{TDS}}\left(u_{x},u_{y}\right)\). If undistorted_tds_model is set to None, then the parameter will be reassigned to the value fakecbed.tds.Model().

undistorted_disksarray_like (fakecbed.shapes.NonuniformBoundedShape, ndim=1), optional

The intensity patterns of the undistorted fake CBED disks, \(\left\{ \mathcal{I}_{k;\text{D}}\left(u_{x},u_{y}\right)\right\} _{k=0}^{N_{\text{D}}-1}\). For every nonnegative integer k less than \(N_{\text{D}}\), undistorted_disks[k] is \(\mathcal{I}_{k;\text{D}}\left(u_{x},u_{y}\right)\), with the integer \(k\) being equal to the value of k

undistorted_misc_shapesarray_like (any_shape, ndim=1), optional

The intensity patterns of the undistorted miscellaneous shapes, \(\left\{ \mathcal{I}_{k;\text{M}}\left(u_{x},u_{y}\right)\right\} _{k=0}^{N_{\text{M}}-1}\). Note that any_shape means any public class defined in the module fakecbed.shapes that is a subclass of fakecbed.shapes.BaseShape.

undistorted_outer_illumination_shapefakecbed.shapes.Circle | fakecbed.shapes.Ellipse | fakecbed.shapes.GenericBlob | None, optional

The intensity pattern of the undistorted outer illumination shape, \(\mathcal{I}_{\text{OI}}\left(u_{x},u_{y}\right)\). If undistorted_outer_illumination_shape is set to None, then \(\mathcal{I}_{\text{OI}}\left(u_{x},u_{y}\right)\) will equal unity for all \(u_{x}\) and \(u_{y}\).

gaussian_filter_std_devfloat, optional

The standard deviation \(\sigma_{\text{blur}}\) of the Gaussian filter used to yield such blur effects on the target fake CBED pattern. Must be nonnegative.

num_pixels_across_patternint, optional

The number of pixels across the image of the fake CBED pattern, \(N_{\mathcal{I};x}\). Must be positive.

distortion_modeldistoptica.DistortionModel | None, optional

The distortion model. If distortion_model is set to None, then the parameter will be reassigned to the value distoptica.DistortionModel(sampling_grid_dims_in_pixels=(N_x, N_x)), Where N_x is equal to num_pixels_across_pattern.

apply_shot_noisebool, optional

If apply_shot_noise is set to True, then shot noise is applied to the image of the fake CBED pattern. Otherwise, no shot noise is applied.

detector_partition_width_in_pixelsint, optional

The detector partition width in units of pixels, \(N_{\text{DPW}}\). Must be nonnegative.

cold_pixelsarray_like (int, ndim=2), optional

The pixel coordinates of the cold pixels.

mask_framearray_like (int, shape=(4,)), optional

mask_frame specifies the mask frame of the image of the target fake CBED pattern. mask_frame[0], mask_frame[1], mask_frame[2], and mask_frame[3] are the widths, in units of pixels, of the left, right, bottom, and top sides of the mask frame respectively. If all elements of mask_frame are zero, then no pixels in the image of the target fake CBED pattern are masked by the mask frame.

Attributes:

core_attrs

dict: The “core attributes”.

de_pre_serialization_funcs

dict: The de-pre-serialization functions.

device

torch.device: The device on which computationally intensive

disk_absence_registry

torch.Tensor: The disk clipping registry,

disk_clipping_registry

torch.Tensor: The disk clipping registry,

disk_overlap_map

torch.Tensor: The image of the disk overlap map,

disk_supports

torch.Tensor: The image stack of the disk supports,

illumination_support

torch.Tensor: The image of the illumination support,

image

torch.Tensor: The image of the target fake CBED pattern,

image_has_been_overridden

bool: Equals True if the image of the target fake CBED pattern

num_disks

int: The total number of CBED disks defined, \(N_{\text{D}}\).

pre_serialization_funcs

dict: The pre-serialization functions.

signal

hyperspy._signals.signal2d.Signal2D: The hyperspy signal

validation_and_conversion_funcs

dict: The validation and conversion functions.

Methods

de_pre_serialize([serializable_rep, ...])	Construct an instance from a serializable representation.
dump([filename, overwrite])	Serialize instance and save the result in a JSON file.
dumps()	Serialize instance.
get_core_attrs([deep_copy])	Return the core attributes.
get_de_pre_serialization_funcs()	Return the de-pre-serialization functions.
get_disk_absence_registry([deep_copy])	Return the disk clipping registry, \(\left\{\Omega_{k;\text{DAR};⌑}\right\}_{k=0}^{N_{\text{D}}-1}\).
get_disk_clipping_registry([deep_copy])	Return the disk clipping registry, \(\left\{\Omega_{k;\text{DCR};⌑}\right\}_{k=0}^{N_{\text{D}}-1}\).
get_disk_overlap_map([deep_copy])	Return the image of the disk overlap map, \(\mathcal{I}_{\text{DOM};⌑;n,m}\).
get_disk_supports([deep_copy])	Return the image stack of the disk supports, \(\left\{\mathcal{I}_{k; \text{DS};⌑;n,m}\right\}_{k=0}^{N_{\text{D}}-1}\).
get_illumination_support([deep_copy])	Return the image of the illumination support, \(\mathcal{I}_{\text{OI};⌑;n,m}\).
get_image([deep_copy])	Return the image of the target fake CBED pattern, \(\mathcal{I}_{\text{CBED};⌑;n,m}\).
get_pre_serialization_funcs()	Return the pre-serialization functions.
get_signal([deep_copy])	Return the hyperspy signal representation of the fake CBED pattern.
get_validation_and_conversion_funcs()	Return the validation and conversion functions.
load([filename, skip_validation_and_conversion])	Construct an instance from a serialized representation that is stored in a JSON file.
loads([serialized_rep, ...])	Construct an instance from a serialized representation.
override_image_then_reapply_mask(...[, ...])	Override the target fake CBED pattern image and reapply masking.
pre_serialize()	Pre-serialize instance.
update(new_core_attr_subset_candidate[, ...])	Update a subset of the core attributes.

execute_post_core_attrs_update_actions

Methods

de_pre_serialize	Construct an instance from a serializable representation.
dump	Serialize instance and save the result in a JSON file.
dumps	Serialize instance.
execute_post_core_attrs_update_actions
get_core_attrs	Return the core attributes.
get_de_pre_serialization_funcs	Return the de-pre-serialization functions.
get_disk_absence_registry	Return the disk clipping registry, \(\left\{\Omega_{k;\text{DAR};⌑}\right\}_{k=0}^{N_{\text{D}}-1}\).
get_disk_clipping_registry	Return the disk clipping registry, \(\left\{\Omega_{k;\text{DCR};⌑}\right\}_{k=0}^{N_{\text{D}}-1}\).
get_disk_overlap_map	Return the image of the disk overlap map, \(\mathcal{I}_{\text{DOM};⌑;n,m}\).
get_disk_supports	Return the image stack of the disk supports, \(\left\{\mathcal{I}_{k; \text{DS};⌑;n,m}\right\}_{k=0}^{N_{\text{D}}-1}\).
get_illumination_support	Return the image of the illumination support, \(\mathcal{I}_{\text{OI};⌑;n,m}\).
get_image	Return the image of the target fake CBED pattern, \(\mathcal{I}_{\text{CBED};⌑;n,m}\).
get_pre_serialization_funcs	Return the pre-serialization functions.
get_signal	Return the hyperspy signal representation of the fake CBED pattern.
get_validation_and_conversion_funcs	Return the validation and conversion functions.
load	Construct an instance from a serialized representation that is stored in a JSON file.
loads	Construct an instance from a serialized representation.
override_image_then_reapply_mask	Override the target fake CBED pattern image and reapply masking.
pre_serialize	Pre-serialize instance.
update	Update a subset of the core attributes.

Attributes

core_attrs	dict: The "core attributes".
de_pre_serialization_funcs	dict: The de-pre-serialization functions.
device	torch.device: The device on which computationally intensive PyTorch operations are performed and attributes of the type torch.Tensor are stored.
disk_absence_registry	torch.Tensor: The disk clipping registry, \(\left\{\Omega_{k;\text{DAR};⌑}\right\}_{k=0}^{N_{\text{D}}-1}\).
disk_clipping_registry	torch.Tensor: The disk clipping registry, \(\left\{\Omega_{k;\text{DCR};⌑}\right\}_{k=0}^{N_{\text{D}}-1}\).
disk_overlap_map	torch.Tensor: The image of the disk overlap map, \(\mathcal{I}_{\text{DOM};⌑;n,m}\).
disk_supports	torch.Tensor: The image stack of the disk supports, \(\left\{\mathcal{I}_{k; \text{DS};⌑;n,m}\right\}_{k=0}^{N_{\text{D}}-1}\).
illumination_support	torch.Tensor: The image of the illumination support, \(\mathcal{I}_{\text{OI};⌑;n,m}\).
image	torch.Tensor: The image of the target fake CBED pattern, \(\mathcal{I}_{\text{CBED};⌑;n,m}\).
image_has_been_overridden	bool: Equals True if the image of the target fake CBED pattern has been overridden.
num_disks	int: The total number of CBED disks defined, \(N_{\text{D}}\).
pre_serialization_funcs	dict: The pre-serialization functions.
signal	hyperspy._signals.signal2d.Signal2D: The hyperspy signal representation of the fake CBED pattern.
validation_and_conversion_funcs	dict: The validation and conversion functions.

property core_attrs

dict: The “core attributes”.

The keys of core_attrs are the same as the attribute validation_and_conversion_funcs, which is also a dict object.

Note that core_attrs should be considered read-only.

property de_pre_serialization_funcs

dict: The de-pre-serialization functions.

de_pre_serialization_funcs has the same keys as the attribute validation_and_conversion_funcs, which is also a dict object.

Let validation_and_conversion_funcs and pre_serialization_funcs denote the attributes validation_and_conversion_funcs pre_serialization_funcs respectively, the last of which being a dict object as well.

Let core_attrs_candidate_1 be any dict object that has the same keys as validation_and_conversion_funcs, where for each dict key key in core_attrs_candidate_1, validation_and_conversion_funcs[key](core_attrs_candidate_1) does not raise an exception.

Let serializable_rep be a dict object that has the same keys as core_attrs_candidate_1, where for each dict key key in core_attrs_candidate_1, serializable_rep[key] is set to pre_serialization_funcs[key](core_attrs_candidate_1[key]).

The items of de_pre_serialization_funcs are expected to be set to callable objects that would lead to de_pre_serialization_funcs[key](serializable_rep[key]) not raising an exception for each dict key key in serializable_rep.

Let core_attrs_candidate_2 be a dict object that has the same keys as serializable_rep, where for each dict key key in validation_and_conversion_funcs, core_attrs_candidate_2[key] is set to de_pre_serialization_funcs[key](serializable_rep[key]).

The items of de_pre_serialization_funcs are also expected to be set to callable objects that would lead to validation_and_conversion_funcs[key](core_attrs_candidate_2) not raising an exception for each dict key key in core_attrs_candidate_2.

Note that de_pre_serialization_funcs should be considered read-only.

classmethod de_pre_serialize(serializable_rep={}, skip_validation_and_conversion=False)

Construct an instance from a serializable representation.

Parameters:

serializable_repdict, optional

A dict object that has the same keys as the attribute validation_and_conversion_funcs, which is also a dict object.

Let validation_and_conversion_funcs and de_pre_serialization_funcs denote the attributes validation_and_conversion_funcs de_pre_serialization_funcs respectively, the last of which being a dict object as well.

The items of serializable_rep are expected to be objects that would lead to de_pre_serialization_funcs[key](serializable_rep[key]) not raising an exception for each dict key key in serializable_rep.

Let core_attrs_candidate be a dict object that has the same keys as serializable_rep, where for each dict key key in serializable_rep, core_attrs_candidate[key] is set to de_pre_serialization_funcs[key](serializable_rep[key])``.

The items of serializable_rep are also expected to be set to objects that would lead to validation_and_conversion_funcs[key](core_attrs_candidate) not raising an exception for each dict key key in serializable_rep.

skip_validation_and_conversionbool, optional

Let core_attrs denote the attribute core_attrs, which is a dict object.

If skip_validation_and_conversion is set to False, then for each key key in serializable_rep, core_attrs[key] is set to validation_and_conversion_funcs[key] (core_attrs_candidate), with validation_and_conversion_funcs and core_attrs_candidate_1 being introduced in the above description of serializable_rep.

Otherwise, if skip_validation_and_conversion is set to True, then core_attrs is set to core_attrs_candidate.copy(). This option is desired primarily when the user wants to avoid potentially expensive deep copies and/or conversions of the dict values of core_attrs_candidate, as it is guaranteed that no copies or conversions are made in this case.

Returns:

instance_of_current_clsCurrent class

An instance constructed from the serializable representation serializable_rep.

property device

torch.device: The device on which computationally intensive PyTorch operations are performed and attributes of the type torch.Tensor are stored.

Note that device should be considered read-only.

property disk_absence_registry

torch.Tensor: The disk clipping registry, \(\left\{\Omega_{k;\text{DAR};⌑}\right\}_{k=0}^{N_{\text{D}}-1}\).

See the summary documentation of the class fakecbed.discretized.CBEDPattern for additional context, in particular a description of the calculation of \(\left\{\Omega_{k;\text{DCR};⌑}\right\}_{k=0}^{N_{\text{D}}-1}\).

Note that \(N_{\text{D}}\) is equal to the value of the attribute fakecbed.discretized.CBEDPattern.num_disks, \(\mathcal{I}_{\text{OI};⌑;n,m}\) is the image of the illumination support, and \(\mathcal{I}_{k;\text{DS};⌑;n,m}\) is the image of the support of the \(k^{\text{th}}\) distorted CBED disk.

disk_absence_registry is a one-dimensional PyTorch tensor of length equal to \(N_{\text{D}}\). For every nonnegative integer k less than \(N_{\text{D}}\), disk_absence_registry[k] is \(\Omega_{k;\text{DAR};⌑}\), with the integer \(k\) being equal to the value of k. If disk_absence_registry[k] is equal to False, then the image of the support of the \(k^{\text{th}}\) distorted CBED disk has at least one nonzero pixel. Otherwise, if disk_absence_registry[k] is equal to True, then the opposite of the above scenario is true.

Note that disk_absence_registry should be considered read-only.

property disk_clipping_registry

torch.Tensor: The disk clipping registry, \(\left\{\Omega_{k;\text{DCR};⌑}\right\}_{k=0}^{N_{\text{D}}-1}\).

See the summary documentation of the class fakecbed.discretized.CBEDPattern for additional context, in particular a description of the calculation of \(\left\{\Omega_{k;\text{DCR};⌑}\right\}_{k=0}^{N_{\text{D}}-1}\).

Note that \(N_{\text{D}}\) is equal to the value of the attribute fakecbed.discretized.CBEDPattern.num_disks, \(\mathcal{I}_{\text{OI};⌑;n,m}\) is the image of the illumination support, and \(\mathcal{I}_{k;\text{DS};⌑;n,m}\) is the image of the support of the \(k^{\text{th}}\) distorted CBED disk.

disk_clipping_registry is a one-dimensional PyTorch tensor of length equal to \(N_{\text{D}}\). For every nonnegative integer k less than \(N_{\text{D}}\), disk_clipping_registry[k] is \(\Omega_{k;\text{DCR};⌑}\), with the integer \(k\) being equal to the value of k. If disk_clipping_registry[k] is equal to False, then every nonzero pixel of the image of the support of the \(k^{\text{th}}\) distorted CBED disk is at least two pixels away from (i.e. at least next-nearest neighbours to) every zero-valued pixel of the image of the illumination support and is at least one pixel away from every pixel bordering the image of the illumination support, and that the image of the support of the \(k^{\text{th}}\) distorted CBED disk has at least one nonzero pixel. Otherwise, if disk_clipping_registry[k] is equal to True, then the opposite of the above scenario is true.

Note that disk_clipping_registry should be considered read-only.

property disk_overlap_map

torch.Tensor: The image of the disk overlap map, \(\mathcal{I}_{\text{DOM};⌑;n,m}\).

See the summary documentation of the class fakecbed.discretized.CBEDPattern for additional context, in particular a description of the calculation of \(\mathcal{I}_{\text{DOM};⌑;n,m}\).

Note that \(\mathcal{I}_{\text{CBED};⌑;n,m}\) is the image of the target fake CBED pattern, which is stored in the attribute fakecbed.discretized.CBEDPattern.image

Let core_attrs denote the attribute core_attrs.

disk_overlap_map is a PyTorch tensor having a shape equal to 2*(core_attrs["num_pixels_across_pattern"],).

For every pair of nonnegative integers (n, m) that does not raise an IndexError exception upon calling disk_overlap_map[n, m], disk_overlap_map[n, m] is equal to \(\mathcal{I}_{\text{DOM};⌑;n,m}\), with the integers \(n\) and \(m\) being equal to the values of n and m respectively. In other words, for each such pair of integers (n, m), disk_overlap_map[n, m] is equal to the number of imaged CBED disks that overlap at the corresponding pixel of the image of the target fake CBED pattern.

Note that disk_overlap_map should be considered read-only.

property disk_supports

torch.Tensor: The image stack of the disk supports, \(\left\{\mathcal{I}_{k; \text{DS};⌑;n,m}\right\}_{k=0}^{N_{\text{D}}-1}\).

See the summary documentation of the class fakecbed.discretized.CBEDPattern for additional context, in particular a description of the calculation of \(\left\{\mathcal{I}_{k; \text{DS};⌑;n,m}\right\}_{k=0}^{N_{\text{D}}-1}\).

Let core_attrs and num_disks denote the attributes core_attrs and fakecbed.discretized.CBEDPattern.num_disks respectively.

disk_supports is a PyTorch tensor having a shape equal to (num_disks,) + 2*(core_attrs["num_pixels_across_pattern"],).

For every pair of nonnegative integers (k, n, m) that does not raise an IndexError exception upon calling disk_supports[k, n, m], disk_supports[k, n, m] is equal to \(\mathcal{I}_{k;\text{DS};⌑;n,m}\), with the integers \(k\), \(n\), and \(m\) being equal to the values of k, n, and m respectively. Furthermore, for each such triplet of integers (k, n, m), if disk_supports[k, n, m] equals zero, then the \(k^{\text{th}}\) distorted CBED disk is not supported at the pixel of the image of the target fake CBED pattern specified by (n, m).

Note that disk_supports should be considered read-only.

dump(filename='serialized_rep_of_fancytype.json', overwrite=False)

Serialize instance and save the result in a JSON file.

Parameters:

filenamestr, optional

The relative or absolute path to the JSON file in which to store the serialized representation of an instance.

overwritebool, optional

If overwrite is set to False and a file exists at the path filename, then the serialized instance is not written to that file and an exception is raised. Otherwise, the serialized instance will be written to that file barring no other issues occur.

Returns:

dumps()

Serialize instance.

Returns:

serialized_repdict

A serialized representation of an instance.

get_core_attrs(deep_copy=True)

Return the core attributes.

Parameters:

deep_copybool, optional

Let core_attrs denote the attribute core_attrs, which is a dict object.

If deep_copy is set to True, then a deep copy of core_attrs is returned. Otherwise, a shallow copy of core_attrs is returned.

Returns:

core_attrsdict

The attribute core_attrs.

classmethod get_de_pre_serialization_funcs()

Return the de-pre-serialization functions.

Returns:

de_pre_serialization_funcsdict

The attribute de_pre_serialization_funcs.

get_disk_absence_registry(deep_copy=True)

Return the disk clipping registry, \(\left\{\Omega_{k;\text{DAR};⌑}\right\}_{k=0}^{N_{\text{D}}-1}\).

Parameters:

deep_copybool, optional

Let disk_absence_registry denote the attribute fakecbed.discretized.CBEDPattern.disk_absence_registry.

If deep_copy is set to True, then a deep copy of disk_absence_registry is returned. Otherwise, a reference to disk_absence_registry is returned.

Returns:

disk_absence_registrytorch.Tensor (bool, ndim=1)

The attribute fakecbed.discretized.CBEDPattern.disk_absence_registry.

get_disk_clipping_registry(deep_copy=True)

Return the disk clipping registry, \(\left\{\Omega_{k;\text{DCR};⌑}\right\}_{k=0}^{N_{\text{D}}-1}\).

Parameters:

deep_copybool, optional

Let disk_clipping_registry denote the attribute fakecbed.discretized.CBEDPattern.disk_clipping_registry.

If deep_copy is set to True, then a deep copy of disk_clipping_registry is returned. Otherwise, a reference to disk_clipping_registry is returned.

Returns:

disk_clipping_registrytorch.Tensor (bool, ndim=1)

The attribute fakecbed.discretized.CBEDPattern.disk_clipping_registry.

get_disk_overlap_map(deep_copy=True)

Return the image of the disk overlap map, \(\mathcal{I}_{\text{DOM};⌑;n,m}\).

Parameters:

deep_copybool, optional

Let disk_overlap_map denote the attribute fakecbed.discretized.CBEDPattern.disk_overlap_map.

If deep_copy is set to True, then a deep copy of disk_overlap_map is returned. Otherwise, a reference to disk_overlap_map is returned.

Returns:

disk_overlap_maptorch.Tensor (int, ndim=2)

The attribute fakecbed.discretized.CBEDPattern.disk_overlap_map.

get_disk_supports(deep_copy=True)

Return the image stack of the disk supports, \(\left\{\mathcal{I}_{k; \text{DS};⌑;n,m}\right\}_{k=0}^{N_{\text{D}}-1}\).

Parameters:

deep_copybool, optional

Let disk_supports denote the attribute fakecbed.discretized.CBEDPattern.disk_supports.

If deep_copy is set to True, then a deep copy of disk_supports is returned. Otherwise, a reference to disk_supports is returned.

Returns:

disk_supportstorch.Tensor (bool, ndim=3)

The attribute fakecbed.discretized.CBEDPattern.disk_supports.

get_illumination_support(deep_copy=True)

Return the image of the illumination support, \(\mathcal{I}_{\text{OI};⌑;n,m}\).

Parameters:

deep_copybool, optional

Let illumination_support denote the attribute fakecbed.discretized.CBEDPattern.illumination_support.

If deep_copy is set to True, then a deep copy of illumination_support is returned. Otherwise, a reference to illumination_support is returned.

Returns:

illumination_supporttorch.Tensor (bool, ndim=2)

The attribute fakecbed.discretized.CBEDPattern.illumination_support.

get_image(deep_copy=True)

Return the image of the target fake CBED pattern, \(\mathcal{I}_{\text{CBED};⌑;n,m}\).

Parameters:

deep_copybool, optional

Let image denote the attribute fakecbed.discretized.CBEDPattern.image.

If deep_copy is set to True, then a deep copy of image is returned. Otherwise, a reference to image is returned.

Returns:

imagetorch.Tensor (float, ndim=2)

The attribute fakecbed.discretized.CBEDPattern.image.

classmethod get_pre_serialization_funcs()

Return the pre-serialization functions.

Returns:

pre_serialization_funcsdict

The attribute pre_serialization_funcs.

get_signal(deep_copy=True)

Return the hyperspy signal representation of the fake CBED pattern.

Parameters:

deep_copybool, optional

Let signal denote the attribute fakecbed.discretized.CBEDPattern.signal.

If deep_copy is set to True, then a deep copy of signal is returned. Otherwise, a reference to signal is returned.

Returns:

signalhyperspy._signals.signal2d.Signal2D

The attribute fakecbed.discretized.CBEDPattern.signal.

classmethod get_validation_and_conversion_funcs()

Return the validation and conversion functions.

Returns:

validation_and_conversion_funcsdict

The attribute validation_and_conversion_funcs.

property illumination_support

torch.Tensor: The image of the illumination support, \(\mathcal{I}_{\text{OI};⌑;n,m}\).

See the summary documentation of the class fakecbed.discretized.CBEDPattern for additional context, in particular a description of the calculation of \(\mathcal{I}_{\text{OI};⌑;n,m}\).

Note that \(\mathcal{I}_{\text{CBED};⌑;n,m}\) is the image of the target fake CBED pattern, which is stored in the attribute fakecbed.discretized.CBEDPattern.image

Let core_attrs denote the attribute core_attrs.

illumination_support is a PyTorch tensor having a shape equal to 2*(core_attrs["num_pixels_across_pattern"],).

For every pair of nonnegative integers (n, m) that does not raise an IndexError exception upon calling illumination_support[n, m], illumination_support[n, m] is equal to \(\mathcal{I}_{\text{OI};⌑;n,m}\), with the integers \(n\) and \(m\) being equal to the values of n and m respectively. Furthermore, for each such pair of integers (n, m), if illumination_support[n, m] equals zero, then the corresponding pixel of the image of the target fake CBED pattern is also zero.

Note that illumination_support should be considered read-only.

property image

torch.Tensor: The image of the target fake CBED pattern, \(\mathcal{I}_{\text{CBED};⌑;n,m}\).

See the summary documentation of the class fakecbed.discretized.CBEDPattern for additional context, in particular a description of the calculation of \(\mathcal{I}_{\text{CBED};⌑;n,m}\).

Let core_attrs denote the attribute core_attrs.

image is a PyTorch tensor having a shape equal to 2*(core_attrs["num_pixels_across_pattern"],).

For every pair of nonnegative integers (n, m) that does not raise an IndexError exception upon calling image[n, m], image[n, m] is equal to \(\mathcal{I}_{\text{CBED};⌑;n,m}\), with the integers \(n\) and \(m\) being equal to the values of n and m respectively.

Note that image should be considered read-only.

property image_has_been_overridden

bool: Equals True if the image of the target fake CBED pattern has been overridden.

Let override_image_then_reapply_mask, and update denote the methods fakecbed.discretized.CBEDPattern.override_image_then_reapply_mask(), and update() respectively. image_has_been_overridden equals True if the method override_image_then_reapply_mask has been called without raising an exception after either instance update via the method update, or instance construction. Otherwise, image_has_been_overridden equals False.

Note that image_has_been_overridden should be considered read-only.

classmethod load(filename='serialized_rep_of_fancytype.json', skip_validation_and_conversion=False)

Construct an instance from a serialized representation that is stored in a JSON file.

Users can save serialized representations to JSON files using the method fancytypes.PreSerializable.dump().

Parameters:

filenamestr, optional

The relative or absolute path to the JSON file that is storing the serialized representation of an instance.

filename is expected to be such that json.load(open(filename, "r")) does not raise an exception.

Let serializable_rep=json.load(open(filename, "r")).

Let validation_and_conversion_funcs and de_pre_serialization_funcs denote the attributes validation_and_conversion_funcs de_pre_serialization_funcs respectively, both of which being dict objects as well.

filename is also expected to be such that de_pre_serialization_funcs[key](serializable_rep[key]) does not raise an exception for each dict key key in de_pre_serialization_funcs.

Let core_attrs_candidate be a dict object that has the same keys as de_pre_serialization_funcs, where for each dict key key in serializable_rep, core_attrs_candidate[key] is set to de_pre_serialization_funcs[key](serializable_rep[key])``.

filename is also expected to be such that validation_and_conversion_funcs[key](core_attrs_candidate) does not raise an exception for each dict key key in serializable_rep.

skip_validation_and_conversionbool, optional

Let core_attrs denote the attribute core_attrs, which is a dict object.

Let core_attrs_candidate be as defined in the above description of filename.

If skip_validation_and_conversion is set to False, then for each key key in core_attrs_candidate, core_attrs[key] is set to validation_and_conversion_funcs[key] (core_attrs_candidate), , with validation_and_conversion_funcs and core_attrs_candidate being introduced in the above description of filename.

Otherwise, if skip_validation_and_conversion is set to True, then core_attrs is set to core_attrs_candidate.copy(). This option is desired primarily when the user wants to avoid potentially expensive deep copies and/or conversions of the dict values of core_attrs_candidate, as it is guaranteed that no copies or conversions are made in this case.

Returns:

instance_of_current_clsCurrent class

An instance constructed from the serialized representation stored in the JSON file.

classmethod loads(serialized_rep='{}', skip_validation_and_conversion=False)

Construct an instance from a serialized representation.

Users can generate serialized representations using the method dumps().

Parameters:

serialized_repstr | bytes | bytearray, optional

The serialized representation.

serialized_rep is expected to be such that json.loads(serialized_rep) does not raise an exception.

Let serializable_rep=json.loads(serialized_rep).

Let validation_and_conversion_funcs and de_pre_serialization_funcs denote the attributes validation_and_conversion_funcs de_pre_serialization_funcs respectively, both of which being dict objects as well.

serialized_rep is also expected to be such that de_pre_serialization_funcs[key](serializable_rep[key]) does not raise an exception for each dict key key in de_pre_serialization_funcs.

Let core_attrs_candidate be a dict object that has the same keys as serializable_rep, where for each dict key key in de_pre_serialization_funcs, core_attrs_candidate[key] is set to de_pre_serialization_funcs[key](serializable_rep[key])``.

serialized_rep is also expected to be such that validation_and_conversion_funcs[key](core_attrs_candidate) does not raise an exception for each dict key key in serializable_rep.

skip_validation_and_conversionbool, optional

Let core_attrs denote the attribute core_attrs, which is a dict object.

If skip_validation_and_conversion is set to False, then for each key key in core_attrs_candidate, core_attrs[key] is set to validation_and_conversion_funcs[key] (core_attrs_candidate), with validation_and_conversion_funcs and core_attrs_candidate_1 being introduced in the above description of serialized_rep.

Otherwise, if skip_validation_and_conversion is set to True, then core_attrs is set to core_attrs_candidate.copy(). This option is desired primarily when the user wants to avoid potentially expensive deep copies and/or conversions of the dict values of core_attrs_candidate, as it is guaranteed that no copies or conversions are made in this case.

Returns:

instance_of_current_clsCurrent class

An instance constructed from the serialized representation.

property num_disks

int: The total number of CBED disks defined, \(N_{\text{D}}\).

See the summary documentation of the class fakecbed.discretized.CBEDPattern for additional context.

Let core_attrs denote the attribute core_attrs. num_disks is equal to len(core_attrs["undistorted_disks"]).

Note that num_disks should be considered read-only.

override_image_then_reapply_mask(overriding_image, skip_validation_and_conversion=False)

Override the target fake CBED pattern image and reapply masking.

See the summary documentation of the class fakecbed.discretized.CBEDPattern for additional context.

Let image, illumination_support, and core_attrs denote the attributes fakecbed.discretized.CBEDPattern.image, fakecbed.discretized.CBEDPattern.illumination_support, and core_attrs. overriding_image is the overriding image.

Upon calling the method override_image_then_reapply_mask, the attribute image is updated effectively by:

coords_of_cold_pixels = core_attrs["cold_pixels"]
L, R, B, T = core_attrs["mask_frame"]
N_I_x = core_attrs["num_pixels_across_pattern"]
N_I_y = N_I_x

image = (overriding_image * illumination_support).clip(min=0)
image[:T, :] = 0
image[max(N_I_y-B, 0):, :] = 0
image[:, :L] = 0
image[:, max(N_I_x-R, 0):] = 0
for coords_of_cold_pixel in coords_of_cold_pixels:
    image[coords_of_cold_pixel] = 0

and then finally min-max normalization is applied to image.

Parameters:

overriding_imagearray_like (float, shape=image.shape)

The overriding image.

skip_validation_and_conversionbool, optional

If skip_validation_and_conversion is set to False, then validations and conversions are performed on the above parameters.

Otherwise, if skip_validation_and_conversion is set to True, no validations and conversions are performed on the above parameters. This option is desired primarily when the user wants to avoid potentially expensive validation and/or conversion operations.

property pre_serialization_funcs

dict: The pre-serialization functions.

pre_serialization_funcs has the same keys as the attribute validation_and_conversion_funcs, which is also a dict object.

Let validation_and_conversion_funcs and core_attrs denote the attributes validation_and_conversion_funcs and core_attrs respectively, the last of which being a dict object as well.

For each dict key key in core_attrs, pre_serialization_funcs[key](core_attrs[key]) is expected to yield a serializable object, i.e. it should yield an object that can be passed into the function json.dumps without raising an exception.

Note that pre_serialization_funcs should be considered read-only.

pre_serialize()

Pre-serialize instance.

Returns:

serializable_repdict

A serializable representation of an instance.

property signal

hyperspy._signals.signal2d.Signal2D: The hyperspy signal representation of the fake CBED pattern.

See the summary documentation of the class fakecbed.discretized.CBEDPattern for additional context.

Let image, illumination_support, disk_overlap_map, disk_supports, disk_clipping_registry, image_has_been_overridden, num_disks, disk_absence_registry, and core_attrs denote the attributes fakecbed.discretized.CBEDPattern.image, fakecbed.discretized.CBEDPattern.illumination_support, fakecbed.discretized.CBEDPattern.disk_overlap_map, fakecbed.discretized.CBEDPattern.disk_supports, fakecbed.discretized.CBEDPattern.disk_clipping_registry, fakecbed.discretized.CBEDPattern.disk_absence_registry, fakecbed.discretized.CBEDPattern.image_has_been_overridden, fakecbed.discretized.CBEDPattern.num_disks, and core_attrs. Furthermore, let pre_serialize denote the method pre_serialize().

The signal data, signal.data, is a NumPy array having a shape equal to (num_disks+3,)+2*(core_attrs["num_pixels_across_pattern"],). The elements of signal.data are set effectively by:

L, R, B, T = core_attrs["mask_frame"]
N_I_x = core_attrs["num_pixels_across_pattern"]
N_I_y = N_I_x

signal.data[0] = image.numpy(force=True)
signal.data[1] = illumination_support.numpy(force=True)
signal.data[1, :T, :] = 0
signal.data[1, max(N_I_y-B, 0):, :] = 0
signal.data[1, :, :L] = 0
signal.data[1, :, max(N_I_x-R, 0):] = 0
signal.data[2] = disk_overlap_map.numpy(force=True)
signal.data[3:] = disk_supports.numpy(force=True)

The signal metadata, signal.metadata, stores serializable forms of several instance attributes, in addition to other items of metadata. signal.metadata.as_dictionary() yields a dictionary signal_metadata that is calculated effectively by:

distortion_model = core_attrs["distortion_model"]

title = ("Fake Undistorted CBED Intensity Pattern"
         if distortion_model.is_trivial
         else "Fake Distorted CBED Intensity Pattern")

pre_serialized_core_attrs = pre_serialize()

fakecbed_metadata = {"num_disks": \
                     num_disks, 
                     "disk_clipping_registry": \
                     disk_clipping_registry.numpy(force=True),
                     "disk_absence_registry": \
                     disk_absence_registry.numpy(force=True),
                     "pre_serialized_core_attrs": \
                     pre_serialized_core_attrs, 
                     "cbed_pattern_image_has_been_overridden": \
                     image_has_been_overridden}

signal_metadata = {"General": {"title": title},
                   "Signal": {"pixel value units": "dimensionless"},
                   "FakeCBED": fakecbed_metadata}

Note that signal should be considered read-only.

update(new_core_attr_subset_candidate, skip_validation_and_conversion=False)

Update a subset of the core attributes.

Parameters:

new_core_attr_subset_candidatedict, optional

A dict object.

skip_validation_and_conversionbool, optional

Let validation_and_conversion_funcs and core_attrs denote the attributes validation_and_conversion_funcs and core_attrs respectively, both of which being dict objects.

If skip_validation_and_conversion is set to False, then for each key key in core_attrs that is also in new_core_attr_subset_candidate, core_attrs[key] is set to validation_and_conversion_funcs[key] (new_core_attr_subset_candidate).

Otherwise, if skip_validation_and_conversion is set to True, then for each key key in core_attrs that is also in new_core_attr_subset_candidate, core_attrs[key] is set to new_core_attr_subset_candidate[key]. This option is desired primarily when the user wants to avoid potentially expensive deep copies and/or conversions of the dict values of new_core_attr_subset_candidate, as it is guaranteed that no copies or conversions are made in this case.

property validation_and_conversion_funcs

dict: The validation and conversion functions.

The keys of validation_and_conversion_funcs are the names of the constructor parameters, excluding skip_validation_and_conversion if it exists as a construction parameter.

Let core_attrs denote the attribute core_attrs, which is also a dict object.

For each dict key key in core_attrs, validation_and_conversion_funcs[key](core_attrs) is expected to not raise an exception.

Note that validation_and_conversion_funcs should be considered read-only.