2.1.1.1.1.5. emicroml.modelling.cbed.distortion.estimation.ml_data_dict_to_distortion_models

ml_data_dict_to_distortion_models(ml_data_dict, sampling_grid_dims_in_pixels=(512, 512), device_name=None, least_squares_alg_params=None)

Convert a dictionary representation of ML data instances to a sequence of distortion models.

The current function converts a dictionary representation ml_data_dict of complete or incomplete machine learning (ML) data instances to a sequence of distortion models. A complete dictionary representation is identical in structure to a dictionary returned by the method emicroml.modelling.cbed.distortion.estimation.MLDataset.get_ml_data_instances() of the class emicroml.modelling.cbed.distortion.estimation.MLDataset. See the documentation for said method for more details. An incomplete dictionary representation is identical in structure to a complete dictionary representation, except that at least one dict item is missing. If incomplete, the dictionary representation must have the following keys: "distortion_centers", "quadratic_radial_distortion_amplitudes", "spiral_distortion_amplitudes", "elliptical_distortion_vectors"`, and ``"parabolic_distortion_vectors". The dict items corresponding to the aforementioned dict keys are the only dict items used to construct the distortion models.

For each ML data instance, an instance distortion_model of the class distoptica.DistortionModel is constructed according to the ML data instance’s features. See the documentation for the class distoptica.DistortionModel for a discussion on distortion models.

Parameters:

ml_data_dictdict

The dictionary representation of the ML data instances to be converted. The current function assumes that all normalizable features of the ML data instances are unnormalized. If the normalizable features of the ML data instances are not normalized, they can be unnormalized using the function emicroml.modelling.cbed.distortion.estimation.unnormalize_normalizable_elems_in_ml_data_dict() prior to using the current function.

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

The dimensions of the sampling grid, in units of pixels, used for all distortion models.

least_squares_alg_paramsdistoptica.LeastSquaresAlgParams | None, optional

least_squares_alg_params specifies the parameters of the least-squares algorithm to be used to calculate the mappings of fractional Cartesian coordinates of distorted images to those of the corresponding undistorted images. least_squares_alg_params is used to calculate the distortion models mentioned above in the summary documentation. If least_squares_alg_params is set to None, then the parameter will be reassigned to the value distoptica.LeastSquaresAlgParams(). See the documentation for the class distoptica.LeastSquaresAlgParams for details on the parameters of the least-squares algorithm.

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 for each distortion model represented by the class distoptica.DistortionModel. 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.

Returns:

distortion_modelsarray_like (distoptica.DistortionModel, ndim=1)

The distortion models.