2.3. distoptica.DistortionModel

class DistortionModel(coord_transform_params=None, sampling_grid_dims_in_pixels=(512, 512), device_name=None, least_squares_alg_params=None, skip_validation_and_conversion=False)

Bases: PreSerializableAndUpdatable

An optical distortion model.

To begin our discussion on optical distortion models, let us consider two thought experiments. First, let \(E_{\square}\) denote an imaging experiment of a sample wherein the imaging aparatus is operating at a fixed set of target parameters, and all the optical elements used in the imaging aparatus are idealized in the sense that they do not introduce any optical distortions. Secondly, let \(E_{⌑}\) denote an imaging experiment that is identical to \(E_{\square}\) except that the optical elements used in the imaging aparatus possess imperfections in the sense that they introduce a particular set of optical distortions. We will refer to the set of images resulting from the imaging experiment \(E_{\square}\) as the set of undistorted images, and the set of images resulting from the imaging experiment \(E_{⌑}\) as the set of distorted images.

We assume that the images resulting from both imaging experiments are formed at a common image plane, that each experiment yields the same number of images \(N_{\mathcal{I}}\), that all images have the same number of channels \(N_{\mathcal{I};C}\), and that all images are of the same spatial dimensions, i.e. they have the same dimensions in pixels with the same pixel sizes. Let \(N_{\mathcal{I};x}\) and \(N_{\mathcal{I};y}\) be the number of pixels in either image from left to right and top to bottom respectively.

For simplicity, we describe positions within images using fractional coordinates. First, 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.

The optical distortions introduced by experiment \(E_{⌑}\) can be described by a coordinate transformation, which maps a given coordinate pair \(\left(u_{x},u_{y}\right)\) to a corresponding coordinate pair \(\left(q_{x},q_{y}\right)\). Let \(T_{⌑;x}\left(u_{x},u_{y}\right)\) be the component of the coordinate transformation that maps \(\left(u_{x},u_{y}\right)\) to its corresponding \(q_{x}\), and let \(T_{⌑;y}\left(u_{x},u_{y}\right)\) be the component of the coordinate transformation that maps \(\left(u_{x},u_{y}\right)\) to its corresponding \(q_{y}\). See the documentation for the class distoptica.CoordTransformParams for a mathematical description of \(T_{⌑;x}\left(u_{x},u_{y}\right)\) and \(T_{⌑;y}\left(u_{x},u_{y}\right)\).

We assume that there exists a right inverse to the coordinate transformation, i.e. that there are functions \(T_{\square;x}\left(q_{x},q_{y}\right)\) and \(T_{\square;y}\left(q_{x},q_{y}\right)\) satisfying:

(2.3.1)\[T_{⌑;x}\left(u_{x}=T_{\square;x}\left(q_{x},q_{y}\right),u_{y}= T_{\square;y}\left(q_{x},q_{y}\right)\right)\equiv q_{x},\]

(2.3.2)\[T_{⌑;y}\left(u_{x}=T_{\square;x}\left(q_{x},q_{y}\right),u_{y}= T_{\square;y}\left(q_{x},q_{y}\right)\right)\equiv q_{y},\]

In other words, \(T_{\square;x}\left(q_{x},q_{y}\right)\) maps \(\left(q_{x},q_{y}\right)\) to its corresponding \(u_{x}\), and \(T_{\square;y}\left(q_{x},q_{y}\right)\) maps \(\left(q_{x},q_{y}\right)\) to its corresponding \(u_{y}\), when \(\left(T_{\square;x}\left(q_{x},q_{y}\right), T_{\square;y}\left(q_{x},q_{y}\right)\right)\) is well-defined at \(\left(q_{x},q_{y}\right)\). See the documentation for the class distoptica.LeastSquaresAlgParams for a discussion on how \(T_{\square;x}\left(q_{x},q_{y}\right)\) and \(T_{\square;y}\left(q_{x},q_{y}\right)\) are calculated.

One of the primary purposes of the class distoptica.DistortionModel is to distort undistorted images or to undistort distorted images, given a coordinate transformation \(\left(T_{⌑;x}\left(u_{x},u_{y}\right), T_{⌑;x}\left(u_{x},u_{y}\right)\right)\), and then subsequently resample the transformed images. To describe how distoptica.DistortionModel approximates the aforementioned images transformations and resampling, it is worth introducing several mathematical objects. First, let \(\mathcal{I}_{\square;l,k,n,m}\) be the value of the pixel centered at \(\left(u_{x},u_{y}\right)= \left(u_{\mathcal{I};x;m},u_{\mathcal{I};y;n}\right)\) in the \(k^{\text{th}}\) channel of the \(l^{\text{th}}\) undistorted image, where

(2.3.3)\[l\in\left\{ l^{\prime}\right\} _{l^{\prime}=0}^{N_{\mathcal{I}}-1},\]

(2.3.4)\[k\in\left\{ k^{\prime}\right\} _{k^{\prime}=0}^{N_{\mathcal{I};C}-1},\]

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

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

(2.3.7)\[u_{\mathcal{I};x;m}=\left(m+\frac{1}{2}\right)\Delta u_{\mathcal{I};x},\]

(2.3.8)\[u_{\mathcal{I};y;n}=1-\left(n+\frac{1}{2}\right) \Delta u_{\mathcal{I};y},\]

(2.3.9)\[\Delta u_{\mathcal{I};x}=\frac{1}{N_{\mathcal{I};x}},\]

(2.3.10)\[\Delta u_{\mathcal{I};y}=\frac{1}{N_{\mathcal{I};y}},\]

Next, let \(\mathcal{I}_{⌑;l,k,n,m}\) be the value of the pixel centered at \(\left(q_{x},q_{y}\right)= \left(q_{\mathcal{I};x;m},q_{\mathcal{I};y;n}\right)\) in the \(k^{\text{th}}\) channel of the \(l^{\text{th}}\) distorted image, where

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

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

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

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

Next, let \(\check{\mathcal{I}}_{\square;l,k}\left(u_{x},u_{y}\right)\) be the interpolation of the \(k^{\text{th}}\) channel of the \(l^{\text{th}}\) undistorted image at \(\left(u_{x},u_{y}\right)\). Next, let \(\check{\mathcal{I}}_{⌑;l,k}\left(q_{x},q_{y}\right)\) be the interpolation of the \(k^{\text{th}}\) channel of the \(l^{\text{th}}\) distorted image at \(\left(q_{x},q_{y}\right)\). Next, let \(\mathring{\mathcal{I}}_{\square;l,k,i,j}\) be the value of the pixel centered at \(\left(u_{x},u_{y}\right)= \left(u_{\mathring{\mathcal{I}};x;j},u_{\mathring{\mathcal{I}};y;i}\right)\) in the \(k^{\text{th}}\) channel of the \(l^{\text{th}}\) resampled undistorted image, where

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

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

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

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

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

(2.3.20)\[\Delta u_{\mathcal{\mathring{I}};y}= \frac{1}{N_{\mathcal{\mathring{I}};y}},\]

and \(N_{\mathcal{\mathring{I}};x}\) and \(N_{\mathcal{\mathring{I}};y}\) are the number of pixels in the sampling grid from left to right and top to bottom respectively. Next, let \(\mathring{\mathcal{I}}_{⌑;l,k,i,j}\) be the value of the pixel centered at \(\left(q_{x},q_{y}\right)= \left(q_{\mathring{\mathcal{I}};x;j},q_{\mathring{\mathcal{I}};y;i}\right)\) in the \(k^{\text{th}}\) channel of the \(l^{\text{th}}\) resampled distorted image, where

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

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

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

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

Next, let \(\mathbf{J}_{⌑}\left(u_{x},u_{y}\right)\) be the Jacobian of \(\left(T_{⌑;x}\left(u_{x},u_{y}\right), T_{⌑;x}\left(u_{x},u_{y}\right)\right)\):

(2.3.25)\[\begin{split}\mathbf{J}_{⌑}\left(u_{x},u_{y}\right)= \begin{pmatrix}\frac{\partial T_{⌑;x}}{\partial u_{x}} & \frac{\partial T_{⌑;x}}{\partial u_{y}}\\ \frac{\partial T_{⌑;y}}{\partial u_{x}} & \frac{\partial T_{⌑;y}}{\partial u_{y}} \end{pmatrix}.\end{split}\]

Lastly, let \(\mathbf{J}_{\square}\left(q_{x},q_{y}\right)\) be the Jacobian of \(\left(T_{\square;x}\left(q_{x},q_{y}\right), T_{\square;x}\left(q_{x},q_{y}\right)\right)\):

(2.3.26)\[\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}\]

The same class, via the method undistort_then_resample_images(), approximates undistorting then resampling images by:

(2.3.27)\[\begin{split}\mathring{\mathcal{I}}_{\square;l,k,i,j}&\approx \frac{N_{\mathcal{I};x}N_{\mathcal{I};y}}{N_{\mathring{\mathcal{I}};x} N_{\mathring{\mathcal{I}};y}} \left|\text{det}\left(\mathbf{J}_{⌑}\left(u_{\mathring{\mathcal{I}}; x;j},u_{\mathring{\mathcal{I}};y;i}\right)\right)\right|\\ &\hphantom{\approx}\quad\times\check{\mathcal{I}}_{⌑;l,k}\left( T_{⌑;x}\left(u_{\mathring{\mathcal{I}};x;j}, u_{\mathring{\mathcal{I}};y;i}\right),T_{⌑;y}\left( u_{\mathring{\mathcal{I}};x;j}, u_{\mathring{\mathcal{I}};y;i}\right)\right),\end{split}\]

where \(\mathbf{J}_{⌑}\left(u_{\mathring{\mathcal{I}};x;j}, u_{\mathring{\mathcal{I}};y;i}\right)\) is calculated via Eq. (2.3.25), with the derivatives being calculated analytically.

The class distoptica.DistortionModel, via the method distort_then_resample_images(), approximates distorting then resampling images by:

(2.3.28)\[\begin{split}\mathring{\mathcal{I}}_{⌑;l,k,i,j}&\approx \frac{N_{\mathcal{I};x}N_{\mathcal{I};y}}{ N_{\mathring{\mathcal{I}};x}N_{\mathring{\mathcal{I}};y}}\left| \text{det}\left(\mathbf{J}_{\square}\left( q_{\mathring{\mathcal{I}};x;j}, q_{\mathring{\mathcal{I}};y;i}\right)\right)\right|\\ &\hphantom{\approx}\quad\times\check{\mathcal{I}}_{\square;l,k}\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}\]

where \(\mathbf{J}_{\square}\left(q_{\mathring{\mathcal{I}};x;j}, q_{\mathring{\mathcal{I}};y;i}\right)\) is calculated via Eq. (2.3.26), with the derivatives being calculated numerically using the second-order accurate central differences method.

Parameters:

coord_transform_paramsdistoptica.CoordTransformParams | None, optional

If coord_transform_params is set to None, then the coordinate transformation \(\left(T_{⌑;x}\left(u_{x},u_{y}\right), T_{⌑;y}\left(u_{x},u_{y}\right)\right)\) to be used is the identity transformation. Otherwise, coord_transform_params specifies the parameters of the coordinate transformation to be used.

sampling_grid_dims_in_pixelsarray_like (int, shape=(2,)), optional

The dimensions of the sampling grid, in units of pixels: sampling_grid_dims_in_pixels[0] and sampling_grid_dims_in_pixels[1] are \(N_{\mathring{\mathcal{I}};x}\) and \(N_{\mathring{\mathcal{I}};y}\) respectively.

device_namestr | None, optional

This parameter specifies the device to be used to perform computationally intensive calls to PyTorch functions and where to store attributes of the type torch.Tensor. If device_name is a string, then it is the name of the device to be used, e.g. ”cuda” or ”cpu”. If device_name is set to None and a GPU device is available, then a GPU device is to be used. Otherwise, the CPU is used.

least_squares_alg_paramsdistoptica.LeastSquaresAlgParams | None, optional

If least_squares_alg_params is set to None, then the parameters of the least-squares algorithm to be used to calculate \(\left(T_{\square;x}\left(q_{x},q_{y}\right), T_{\square;y}\left(q_{x},q_{y}\right)\right)\) are those specified by distoptica.LeastSquaresAlgParams(). Otherwise, least_squares_alg_params specifies the parameters of the least-squares algorithm to be used.

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.

Let params_to_be_mapped_to_core_attrs denote the dict representation of the constructor parameters excluding the parameter skip_validation_and_conversion, where each dict key key is a different constructor parameter name, excluding the name "skip_validation_and_conversion", and params_to_be_mapped_to_core_attrs[key] would yield the value of the constructor parameter with the name given by key.

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

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

Attributes:

convergence_map_of_distorted_then_resampled_images

torch.Tensor: The convergence map of the iterative algorithm used

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

flow_field_of_coord_transform

array_like: The flow field of the coordinate transformation

flow_field_of_coord_transform_right_inverse

array_like: The flow field of the right-inverse of the coordinate

is_azimuthally_symmetric

bool: A boolean variable indicating whether the distortion model

is_standard

bool: A boolean variable indicating whether the distortion model

is_trivial

bool: A boolean variable indicating whether the distortion model

mask_frame_of_distorted_then_resampled_images

array_like: The minimum frame to mask all boolean values of

out_of_bounds_map_of_distorted_then_resampled_images

torch.Tensor: The out-of-bounds map of distorted then resampled

out_of_bounds_map_of_undistorted_then_resampled_images

torch.Tensor: The out-of-bounds map of undistorted then resampled

pre_serialization_funcs

dict: The pre-serialization functions.

sampling_grid

array_like: The fractional coordinates of the sampling grid.

validation_and_conversion_funcs

dict: The validation and conversion functions.

Methods

de_pre_serialize([serializable_rep, ...])	Construct an instance from a serializable representation.
distort_then_resample_images([...])	Distort then resample a 1D stack of undistorted images.
dump([filename, overwrite])	Serialize instance and save the result in a JSON file.
dumps()	Serialize instance.
execute_post_core_attrs_update_actions()	Execute the sequence of actions that follows immediately after updating the core attributes.
get_convergence_map_of_distorted_then_resampled_images([...])	Return the convergence map of the iterative algorithm used to distort then resample images.
get_core_attrs([deep_copy])	Return the core attributes.
get_de_pre_serialization_funcs()	Return the de-pre-serialization functions.
get_flow_field_of_coord_transform([deep_copy])	Return the flow field of the coordinate transformation corresponding to the distortion model.
get_flow_field_of_coord_transform_right_inverse([...])	Return the flow field of the right-inverse of the coordinate transformation corresponding to the distortion model.
get_out_of_bounds_map_of_distorted_then_resampled_images([...])	Return the out-of-bounds map of distorted then resampled images.
get_out_of_bounds_map_of_undistorted_then_resampled_images([...])	Return the out-of-bounds map of undistorted then resampled images.
get_pre_serialization_funcs()	Return the pre-serialization functions.
get_sampling_grid([deep_copy])	Return the fractional coordinates of the sampling grid.
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.
pre_serialize()	Pre-serialize instance.
undistort_then_resample_images([...])	Undistort and resample a 1D stack of distorted images.
update(new_core_attr_subset_candidate[, ...])	Update a subset of the core attributes.

Methods

de_pre_serialize	Construct an instance from a serializable representation.
distort_then_resample_images	Distort then resample a 1D stack of undistorted images.
dump	Serialize instance and save the result in a JSON file.
dumps	Serialize instance.
execute_post_core_attrs_update_actions	Execute the sequence of actions that follows immediately after updating the core attributes.
get_convergence_map_of_distorted_then_resampled_images	Return the convergence map of the iterative algorithm used to distort then resample images.
get_core_attrs	Return the core attributes.
get_de_pre_serialization_funcs	Return the de-pre-serialization functions.
get_flow_field_of_coord_transform	Return the flow field of the coordinate transformation corresponding to the distortion model.
get_flow_field_of_coord_transform_right_inverse	Return the flow field of the right-inverse of the coordinate transformation corresponding to the distortion model.
get_out_of_bounds_map_of_distorted_then_resampled_images	Return the out-of-bounds map of distorted then resampled images.
get_out_of_bounds_map_of_undistorted_then_resampled_images	Return the out-of-bounds map of undistorted then resampled images.
get_pre_serialization_funcs	Return the pre-serialization functions.
get_sampling_grid	Return the fractional coordinates of the sampling grid.
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.
pre_serialize	Pre-serialize instance.
undistort_then_resample_images	Undistort and resample a 1D stack of distorted images.
update	Update a subset of the core attributes.

Attributes

convergence_map_of_distorted_then_resampled_images	torch.Tensor: The convergence map of the iterative algorithm used to distort then resample images.
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.
flow_field_of_coord_transform	array_like: The flow field of the coordinate transformation corresponding to the distortion model.
flow_field_of_coord_transform_right_inverse	array_like: The flow field of the right-inverse of the coordinate transformation corresponding to the distortion model.
is_azimuthally_symmetric	bool: A boolean variable indicating whether the distortion model is azimuthally symmetric.
is_standard	bool: A boolean variable indicating whether the distortion model is standard.
is_trivial	bool: A boolean variable indicating whether the distortion model is trivial.
mask_frame_of_distorted_then_resampled_images	array_like: The minimum frame to mask all boolean values of False in the attribute distoptica.DistortionModel.convergence_map_of_distorted_then_resampled_images.
out_of_bounds_map_of_distorted_then_resampled_images	torch.Tensor: The out-of-bounds map of distorted then resampled images.
out_of_bounds_map_of_undistorted_then_resampled_images	torch.Tensor: The out-of-bounds map of undistorted then resampled images.
pre_serialization_funcs	dict: The pre-serialization functions.
sampling_grid	array_like: The fractional coordinates of the sampling grid.
validation_and_conversion_funcs	dict: The validation and conversion functions.

property convergence_map_of_distorted_then_resampled_images

torch.Tensor: The convergence map of the iterative algorithm used to distort then resample images.

See the documentation for the method distoptica.DistortionModel.distort_then_resample_images() for additional context.

convergence_map_of_distorted_then_resampled_images is a PyTorch tensor having a shape equal to \(\left(N_{\mathring{\mathcal{I}};y}, N_{\mathring{\mathcal{I}};x}\right)\), where \(N_{\mathring{\mathcal{I}};x}\) and \(N_{\mathring{\mathcal{I}};y}\) being the number of pixels in the sampling grid from left to right and top to bottom respectively.

Let distorted_then_resampled_images denote the output of a call to the method distoptica.DistortionModel.distort_then_resample_images().

For every row index i and column index j, convergence_map_of_distorted_then_resampled_images[i, j] evaluates to False if the iterative algorithm used to calculate distorted_images does not converge within the error tolerance for elements distorted_images[:, :, i, j], and evaluates to True otherwise.

Note that convergence_map_of_distorted_then_resampled_images should be considered read-only.

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.

distort_then_resample_images(undistorted_images=((0.0,),))

Distort then resample a 1D stack of undistorted images.

See the summary documentation of the class distoptica.DistortionModel for additional context.

Each undistorted image is distorted and subsequently resampled according to Eq. (2.3.28).

Parameters:

undistorted_imagesarray_like (float, ndim=2) | array_like (float, ndim=3) | array_like (float, ndim=4), optional

The undistorted images to be distorted and resampled. If len(undistorted_images.shape)==4, then for every quadruplet of nonnegative integers (l, k, n, m) that does not raise an IndexError exception upon calling undistorted_images[l, k, n, m], undistorted_images[l, k, n, m] is interpreted to be the quantity \(\mathcal{I}_{\square;l,k,n,m}\), introduced in the summary documentation of the class distoptica.DistortionModel, with the integers \(l\), \(k\), \(n\), and \(m\) being equal to the values of l, k, n, and m respectively, and the quadruplet of integers \(\left(N_{\mathcal{I}},N_{\mathcal{I};C},N_{\mathcal{I};y}, N_{\mathcal{I};x}\right)\), introduced in the summary documentation of the class distoptica.DistortionModel, being equal to the shape of undistorted_images. If len(undistorted_images.shape)==3, then for every quadruplet of nonnegative integers (k, n, m) that does not raise an IndexError exception upon calling undistorted_images[k, n, m], undistorted_images[k, n, m] is interpreted to be the quantity \(\mathcal{I}_{\square;0,k,n,m}\), with the integers \(k\), \(n\), and \(m\) being equal to the values of k, n, and m respectively, the triplet of integers \(\left(N_{\mathcal{I};C},N_{\mathcal{I};y}, N_{\mathcal{I};x}\right)\) being equal to the shape of undistorted_images, and \(N_{\mathcal{I}}\) being equal to unity. Otherwise, if len(undistorted_images.shape)==2, then for every pair of nonnegative integers (n, m) that does not raise an IndexError exception upon calling undistorted_images[n, m], undistorted_images[n, m] is interpreted to be the quantity \(\mathcal{I}_{\square;0,0,n,m}\), with the integers \(n\) and \(m\) being equal to the values of n, and m respectively, the pair of integers \(\left(N_{\mathcal{I};y},N_{\mathcal{I};x}\right)\) being equal to the shape of undistorted_images, and both \(N_{\mathcal{I}}\) and \(N_{\mathcal{I};C}\) being equal to unity.

Returns:

distorted_then_resampled_imagestorch.Tensor (float, ndim=4)

The images resulting from distorting then resampling the input image set. For every quadruplet of nonnegative integers (l, k, i, j) that does not raise an IndexError exception upon calling distorted_then_resampled_images[l, k, i, j], distorted_then_resampled_images[l, k, i, j] is interpreted to be the quantity \(\mathring{\mathcal{I}}_{⌑;l,k,i,j}\), introduced in the summary documentation of the class distoptica.DistortionModel, with the integers \(l\), \(k\), \(i\), and \(j\) being equal to the values of l, k, i, and j respectively, with the quadruplet of integers \(\left(N_{\mathcal{I}},N_{\mathcal{I};C}, N_{\mathring{\mathcal{I}};y},N_{\mathring{\mathcal{I}};x}\right)\), introduced in the summary documentation of the class distoptica.DistortionModel, being equal to the shape of distorted_then_resampled_images.

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.

execute_post_core_attrs_update_actions()

Execute the sequence of actions that follows immediately after updating the core attributes.

property flow_field_of_coord_transform

array_like: The flow field of the coordinate transformation corresponding to the distortion model.

See the summary documentation of the class distoptica.DistortionModel for additional context.

flow_field_of_coord_transform is a 2-element tuple, where flow_field_of_coord_transform[0] and flow_field_of_coord_transform[1] are PyTorch tensors, each having a shape equal to \(\left(N_{\mathring{\mathcal{I}};y}, N_{\mathring{\mathcal{I}};x}\right)\), with \(N_{\mathring{\mathcal{I}};x}\) and \(N_{\mathring{\mathcal{I}};y}\) being the number of pixels in the sampling grid from left to right and top to bottom respectively.

For every pair of nonnegative integers (i, j) that does not raise an IndexError exception upon calling flow_field_of_coord_transform[0, i, j], flow_field_of_coord_transform[0, i, j] and flow_field_of_coord_transform[1, i, j] are equal to the quantities

(2.3.29)\[\Delta T_{⌑;x;i,j}= T_{⌑;x}\left(u_{\mathring{\mathcal{I}};x;j}, u_{\mathring{\mathcal{I}};y;i}\right) -u_{\mathring{\mathcal{I}};x;j},\]

and

(2.3.30)\[\Delta T_{⌑;y;i,j}= T_{⌑;y}\left(u_{\mathring{\mathcal{I}};x;j}, u_{\mathring{\mathcal{I}};y;i}\right) -u_{\mathring{\mathcal{I}};y;j},\]

respectively, with the integers \(i\) and \(j\) being equal to the values of i and j respectively, \(u_{\mathcal{\mathring{I}};x;j}\) and \(u_{\mathcal{\mathring{I}};y;i}\) being given by Eqs. (2.3.17) and (2.3.18) respectively, and \(\left(T_{⌑;x}\left(u_{x},u_{y}\right), T_{⌑;x}\left(u_{x},u_{y}\right)\right)\) being the coordinate transformation corresponding to the distortion model.

Note that flow_field_of_coord_transform should be considered read-only.

property flow_field_of_coord_transform_right_inverse

array_like: The flow field of the right-inverse of the coordinate transformation corresponding to the distortion model.

flow_field_of_coord_transform_right_inverse is a 2-element tuple, where flow_field_of_coord_transform_right_inverse[0] and flow_field_of_coord_transform_right_inverse[1] are PyTorch tensors, each having a shape equal to \(\left(N_{\mathring{\mathcal{I}};y}, N_{\mathring{\mathcal{I}};x}\right)\), with \(N_{\mathring{\mathcal{I}};x}\) and \(N_{\mathring{\mathcal{I}};y}\) being the number of pixels in the sampling grid from left to right and top to bottom respectively.

For every pair of nonnegative integers (i, j) that does not raise an IndexError exception upon calling flow_field_of_coord_transform_right_inverse[0, i, j], flow_field_of_coord_transform_right_inverse[0, i, j] and flow_field_of_coord_transform_right_inverse[1, i, j] are equal to the quantities

(2.3.31)\[\Delta T_{\square;x;i,j}= T_{\square;x}\left(q_{\mathring{\mathcal{I}};x;j}, q_{\mathring{\mathcal{I}};y;i}\right) -q_{\mathring{\mathcal{I}};x;j},\]

and

(2.3.32)\[\Delta T_{\square;y;i,j}= T_{\square;y}\left(q_{\mathring{\mathcal{I}};x;j}, q_{\mathring{\mathcal{I}};y;i}\right) -q_{\mathring{\mathcal{I}};y;j},\]

respectively, with the integers \(i\) and \(j\) being equal to the values of i and j respectively, \(q_{\mathcal{\mathring{I}};x;j}\) and \(q_{\mathcal{\mathring{I}};y;i}\) being given by Eqs. (2.3.21) and (2.3.22) respectively, and \(\left(T_{\square;x}\left(q_{x},q_{y}\right), T_{\square;x}\left(q_{x},q_{y}\right)\right)\) being the right inverse of the coordinate transformation corresponding to the distortion model.

Note that flow_field_of_coord_transform_right_inverse should be considered read-only.

get_convergence_map_of_distorted_then_resampled_images(deep_copy=True)

Return the convergence map of the iterative algorithm used to distort then resample images.

Parameters:

deep_copybool, optional

Let convergence_map_of_distorted_then_resampled_images denote the attribute distoptica.DistortionModel.convergence_map_of_distorted_then_resampled_images.

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

Returns:

convergence_map_of_distorted_then_resampled_imagestorch.Tensor (bool, ndim=2)

The attribute distoptica.DistortionModel.convergence_map_of_distorted_then_resampled_images.

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_flow_field_of_coord_transform(deep_copy=True)

Return the flow field of the coordinate transformation corresponding to the distortion model.

Parameters:

deep_copybool, optional

Let flow_field_of_coord_transform denote the attribute distoptica.DistortionModel.flow_field_of_coord_transform.

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

Returns:

flow_field_of_coord_transformarray_like (torch.Tensor (float, ndim=2), shape=(2,))

The attribute distoptica.DistortionModel.flow_field_of_coord_transform.

get_flow_field_of_coord_transform_right_inverse(deep_copy=True)

Return the flow field of the right-inverse of the coordinate transformation corresponding to the distortion model.

Parameters:

deep_copybool, optional

Let flow_field_of_coord_transform_right_inverse denote the attribute distoptica.DistortionModel.flow_field_of_coord_transform_right_inverse.

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

Returns:

flow_field_of_coord_transform_right_inversearray_like (torch.Tensor (float, ndim=2), shape=(2,))

The attribute distoptica.DistortionModel.flow_field_of_coord_transform_right_inverse.

get_out_of_bounds_map_of_distorted_then_resampled_images(deep_copy=True)

Return the out-of-bounds map of distorted then resampled images.

Parameters:

deep_copybool, optional

Let out_of_bounds_map_of_distorted_then_resampled_images denote the attribute distoptica.DistortionModel.out_of_bounds_map_of_distorted_then_resampled_images.

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

Returns:

out_of_bounds_map_of_distorted_then_resampled_imagestorch.Tensor (bool, ndim=2)

The attribute distoptica.DistortionModel.out_of_bounds_map_of_distorted_then_resampled_images.

get_out_of_bounds_map_of_undistorted_then_resampled_images(deep_copy=True)

Return the out-of-bounds map of undistorted then resampled images.

Parameters:

deep_copybool, optional

Let out_of_bounds_map_of_undistorted_then_resampled_images denote the attribute distoptica.DistortionModel.out_of_bounds_map_of_undistorted_then_resampled_images.

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

Returns:

out_of_bounds_map_of_undistorted_then_resampled_imagestorch.Tensor (bool, ndim=2)

The attribute distoptica.DistortionModel.out_of_bounds_map_of_undistorted_then_resampled_images.

classmethod get_pre_serialization_funcs()

Return the pre-serialization functions.

Returns:

pre_serialization_funcsdict

The attribute pre_serialization_funcs.

get_sampling_grid(deep_copy=True)

Return the fractional coordinates of the sampling grid.

Parameters:

deep_copybool, optional

Let sampling_grid denote the attribute distoptica.DistortionModel.sampling_grid.

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

Returns:

sampling_gridarray_like (torch.Tensor (float, ndim=2), shape=(2,))

The attribute distoptica.DistortionModel.sampling_grid.

classmethod get_validation_and_conversion_funcs()

Return the validation and conversion functions.

Returns:

validation_and_conversion_funcsdict

The attribute validation_and_conversion_funcs.

property is_azimuthally_symmetric

bool: A boolean variable indicating whether the distortion model is azimuthally symmetric.

If is_azimuthally_symmetric is set to True, then the distortion model is azimuthally symmetric. Otherwise, the distortion model is not azimuthally symmetric.

Note that is_azimuthally_symmetric should be considered read-only.

property is_standard

bool: A boolean variable indicating whether the distortion model is standard.

See the documentation for the class distoptica.StandardCoordTransformParams for a definition of a standard distortion model.

If is_standard is set to True, then the distortion model is

standard. Otherwise, the distortion model is not standard.

Note that is_standard should be considered read-only.

property is_trivial

bool: A boolean variable indicating whether the distortion model is trivial.

We define a trivial distortion model to be one with a corresponding coordinate transformation that is equivalent to the identity transformation.

If is_trivial is set to True, then the distortion model is trivial. Otherwise, the distortion model is not trivial.

Note that is_trivial 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 mask_frame_of_distorted_then_resampled_images

array_like: The minimum frame to mask all boolean values of False in the attribute distoptica.DistortionModel.convergence_map_of_distorted_then_resampled_images.

See the documentation for the attribute distoptica.DistortionModel.convergence_map_of_distorted_then_resampled_images for additional context.

mask_frame_of_distorted_then_resampled_images is a 4-element tuple where mask_frame_of_distorted_then_resampled_images[0], mask_frame_of_distorted_then_resampled_images[1], mask_frame_of_distorted_then_resampled_images[2], and mask_frame_of_distorted_then_resampled_images[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_of_distorted_then_resampled_images are equal to zero, then every element of distoptica.DistortionModel.convergence_map_of_distorted_then_resampled_images evaluates to True.

Note that mask_frame_of_distorted_then_resampled_images should be considered read-only.

property out_of_bounds_map_of_distorted_then_resampled_images

torch.Tensor: The out-of-bounds map of distorted then resampled images.

See the summary documentation of the class distoptica.DistortionModel for additional context.

out_of_bounds_map_of_distorted_then_resampled_images is a PyTorch tensor having a shape equal to \(\left(N_{\mathring{\mathcal{I}};y}, N_{\mathring{\mathcal{I}};x}\right)\), where \(N_{\mathring{\mathcal{I}};x}\) and \(N_{\mathring{\mathcal{I}};y}\) being the number of pixels in the sampling grid from left to right and top to bottom respectively.

Let sampling_grid and flow_field_of_coord_transform_right_inverse denote the attributes distoptica.DistortionModel.sampling_grid and distoptica.DistortionModel.flow_field_of_coord_transform_right_inverse respectively. Furthermore, let u_x = sampling_grid[0]+flow_field_of_coord_transform_right_inverse[0] and u_y = sampling_grid[1]+flow_field_of_coord_transform_right_inverse[1].

out_of_bounds_map_of_distorted_then_resampled_images is equal to (u_x*u_x.shape[1]<=0.5) | (u_x.shape[1]-0.5<=u_x*u_x.shape[1]) | (u_y*u_y.shape[0]<=0.5) | (u_y.shape[0]-0.5<=u_y*u_y.shape[0]).

Note that out_of_bounds_map_of_coord_transform should be considered read-only.

property out_of_bounds_map_of_undistorted_then_resampled_images

torch.Tensor: The out-of-bounds map of undistorted then resampled images.

See the summary documentation of the class distoptica.DistortionModel for additional context.

out_of_bounds_map_of_undistorted_then_resampled_images is a PyTorch tensor having a shape equal to \(\left(N_{\mathring{\mathcal{I}};y}, N_{\mathring{\mathcal{I}};x}\right)\), where \(N_{\mathring{\mathcal{I}};x}\) and \(N_{\mathring{\mathcal{I}};y}\) being the number of pixels in the sampling grid from left to right and top to bottom respectively.

Let sampling_grid and flow_field_of_coord_transform denote the attributes distoptica.DistortionModel.sampling_grid and distoptica.DistortionModel.flow_field_of_coord_transform respectively. Furthermore, let q_x = sampling_grid[0]+flow_field_of_coord_transform[0] and q_y = sampling_grid[1]+flow_field_of_coord_transform[1].

out_of_bounds_map_of_undistorted_then_resampled_images is equal to (q_x*q_x.shape[1]<=0.5) | (q_x.shape[1]-0.5<=q_x*q_x.shape[1]) | (q_y*q_y.shape[0]<=0.5) | (q_y.shape[0]-0.5<=q_y*q_y.shape[0]).

Note that out_of_bounds_map_of_coord_transform should be considered read-only.

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 sampling_grid

array_like: The fractional coordinates of the sampling grid.

See the summary documentation of the class distoptica.DistortionModel for additional context.

sampling_grid is a 2-element tuple, where sampling_grid[0] and sampling_grid[1] are PyTorch tensors, each having a shape equal to \(\left(N_{\mathring{\mathcal{I}};y}, N_{\mathring{\mathcal{I}};x}\right)\), with \(N_{\mathring{\mathcal{I}};x}\) and \(N_{\mathring{\mathcal{I}};y}\) being the number of pixels in the sampling grid from left to right and top to bottom respectively.

For every pair of nonnegative integers (i, j) that does not raise an IndexError exception upon calling sampling_grid[0, i, j], sampling_grid[0, i, j] and sampling_grid[1, i, j] are equal to the quantities \(u_{\mathcal{\mathring{I}};x;j}\) and \(u_{\mathcal{\mathring{I}};y;i}\) respectively, with the integers \(i\) and \(j\) being equal to the values of i and j respectively, and \(u_{\mathcal{\mathring{I}};x;j}\) and \(u_{\mathcal{\mathring{I}};y;i}\) being given by Eqs. (2.3.17) and (2.3.18) respectively.

Note that sampling_grid should be considered read-only.

undistort_then_resample_images(distorted_images=((0.0,),))

Undistort and resample a 1D stack of distorted images.

Each distorted image is undistorted and subsequently resampled according to Eq. (2.3.27).

Parameters:

distorted_imagesarray_like (float, ndim=2) | array_like (float, ndim=3) | array_like (float, ndim=4), optional

The distorted images to be undistorted and resampled. If len(distorted_images.shape)==4, then for every quadruplet of nonnegative integers (l, k, n, m) that does not raise an IndexError exception upon calling distorted_images[l, k, n, m], distorted_images[l, k, n, m] is interpreted to be the quantity \(\mathcal{I}_{⌑;l,k,n,m}\), introduced in the summary documentation of the class distoptica.DistortionModel, with the integers \(l\), \(k\), \(n\), and \(m\) being equal to the values of l, k, n, and m respectively, and the quadruplet of integers \(\left(N_{\mathcal{I}},N_{\mathcal{I};C},N_{\mathcal{I};y}, N_{\mathcal{I};x}\right)\), introduced in the summary documentation of the class distoptica.DistortionModel, being equal to the shape of distorted_images. If len(distorted_images.shape)==3, then for every quadruplet of nonnegative integers (k, n, m) that does not raise an IndexError exception upon calling distorted_images[k, n, m], distorted_images[k, n, m] is interpreted to be the quantity \(\mathcal{I}_{⌑;0,k,n,m}\), with the integers \(k\), \(n\), and \(m\) being equal to the values of c, n, and m respectively, the triplet of integers \(\left(N_{\mathcal{I};C},N_{\mathcal{I};y}, N_{\mathcal{I};x}\right)\) being equal to the shape of distorted_images, and \(N_{\mathcal{I}}\) being equal to unity. Otherwise, if len(distorted_images.shape)==2, then for every pair of nonnegative integers (n, m) that does not raise an IndexError exception upon calling distorted_images[n, m], distorted_images[n, m] is interpreted to be the quantity \(\mathcal{I}_{⌑;0,0,n,m}\), with the integers \(n\) and \(m\) being equal to the values of n, and m respectively, the pair of integers \(\left(N_{\mathcal{I};y},N_{\mathcal{I};x}\right)\) being equal to the shape of distorted_images, and both \(N_{\mathcal{I}}\) and \(N_{\mathcal{I};C}\) being equal to unity.

Returns:

undistorted_then_resampled_imagestorch.Tensor (float, ndim=4)

The images resulting from undistorting then resampling the input image set. For every quadruplet of nonnegative integers (l, k, i, j) that does not raise an IndexError exception upon calling undistorted_then_resampled_images[l, k, i, j], undistorted_then_resampled_images[l, k, i, j] is interpreted to be the quantity \(\mathring{\mathcal{I}}_{\square;l,k,i,j}\), introduced in the summary documentation of the class distoptica.DistortionModel, with the integers \(l\), \(k\), \(i\), and \(j\) being equal to the values of l, k, i, and j respectively, with the quadruplet of integers \(\left(N_{\mathcal{I}},N_{\mathcal{I};C}, N_{\mathring{\mathcal{I}};y},N_{\mathring{\mathcal{I}};x}\right)\), introduced in the summary documentation of the class distoptica.DistortionModel, being equal to the shape of undistorted_then_resampled_images.

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.