pycvcam.core.Transform

Transform Class

class Transform(parameters=None, constants=None)

Transform is the base class to manage transformations from \(\mathbb{R}^{\text{input_dim}}\) to \(\mathbb{R}^{\text{output_dim}}\).

A tranformation is a function that maps points from an input space to an output space. The transformation is defined by:

• a set of n_params parameters \(\{\lambda_1, \lambda_2, \ldots, \lambda_N\}\) that define the transformation.

• a set of n_constants constants that are constant for the transformation. (Can not be optimized and no jacobian with respect to these constants).

\[\vec{X}_O = T(\vec{X}_I, \lambda_1, \lambda_2, \ldots, \lambda_N)\]

where \(\vec{X}_O\) are the output points, \(\vec{X}_I\) are the input points, and \(\{\lambda_1, \lambda_2, \ldots, \lambda_N\}\) are the parameters of the transformation.

This class provides the base for all transformations. It defines the interface for extrinsic, distortion, and intrinsic transformations.

See also

• pycvcam.core.Extrinsic for extrinsic transformations.

• pycvcam.core.Distortion for distortion transformations.

• pycvcam.core.Intrinsic for intrinsic transformations.

Each sub-classes must implement the following methods and properties:

• _input_dim: (class attribute) The dimension of the input points as integer (example: 2 for 2D points).

• _output_dim: (class attribute) The dimension of the output points as integer (example: 2 for 2D points).

• _transform: (method) Apply the transformation to the given points with shape (n_points, input_dim) and return the transformed points with shape (n_points, output_dim), and optionally the Jacobian matrices if requested.

• _inverse_transform: (method) Apply the inverse transformation to the given points with shape (n_points, output_dim) and return the transformed points with shape (n_points, input_dim), and optionally the Jacobian matrices if requested.

The following properties are not required but can be overwritting to provide additional information about the transformation:

• parameters (property and setter) The parameters of the transformation in a 1D numpy array of shape (n_params,) or None if the transformation does not have parameters or they are not set. Default only impose 1D array of floats or None.

• constants (property and setter) The constants of the transformation in a 1D numpy array of shape (n_constants,) or None if the transformation does not have constants or they are not set. Default only impose 1D array of floats or None.

• parameter_names (property) The names of the parameters as a list of strings or None if the transformation does not have parameters or they are not set. Default is None.

• constant_names (property) The names of the constants as a list of strings or None if the transformation does not have constants or they are not set. Default is None.

• is_set: (method) Check if the transformation is set (i.e., if the parameters are initialized). Default is to return True if the parameters and constants are not None. Default is to return True if the parameters and constants are not None.

• _result_class: (class attribute) The class used for the result of the transformation (sub-class of TransformResult). Default is pycvcam.core.TransformResult.

• _inverse_result_class: (class attribute) The class used for the result of the inverse transformation (sub-class of TransformResult). Default is pycvcam.core.TransformResult.

• _get_jacobian_shorthands: (method) A dictionary of short-hand notation for the Jacobian matrices, which can be used to add custom views of the jacobian_dp matrix with respect to the parameters of the transformation. Default is an empty dictionary.

• _get_transform_aliases: (method) A dictionary of aliases for the transformation, which can be used to add custom names for the transformation parameters. Default is an empty list.

• _get_inverse_transform_aliases: (method) A dictionary of aliases for the inverse transformation, which can be used to add custom names for the inverse transformation parameters. Default is an empty list.

More details on the transformation methods are provided in the transform and inverse_transform methods.

See also

• pycvcam.core.Transform.transform() for applying the transformation to points.

• pycvcam.core.Transform.inverse_transform() for applying the inverse transformation to points.

• pycvcam.core.TransformResult for the result of the transformation.

Note

... in the shape of the attributes indicates that the shape can have any number of leading dimensions, which is useful for batch processing of points.

Parameters:

• parameters (Optional[ArrayLike])

• constants (Optional[ArrayLike])

Public Methods of Transform subclasses

Transformation caracteristics

To have informations on the transformation caracteristics, use the following methods:

Transform.input_dim	[Get] the input dimension of the transformation.
Transform.output_dim	[Get] the output dimension of the transformation.
Transform.parameters	[Get/Set] the parameters of the transformation.
Transform.n_params	[Get] the number of parameters of the transformation.
Transform.parameter_names	[Get] the names of the parameters of the transformation.
Transform.constants	[Get/Set] to return the constants of the transformation.
Transform.n_constants	[Get] the number of constants of the transformation.
Transform.constant_names	[Get] the names of the constants of the transformation.

Transforming Points

To transform points using the transformation from \(\mathbb{R}^{\text{input_dim}}\) to \(\mathbb{R}^{\text{output_dim}}\), use the following method:

Transform.transform(points, *[, transpose, ...])	Transform the given points using the transformation from \(\mathbb{R}^{\text{input_dim}}\) to \(\mathbb{R}^{\text{output_dim}}\).
Transform.inverse_transform(points, *[, ...])	Apply the inverse transformation to the given points using the transformation from \(\mathbb{R}^{\text{output_dim}}\) to \(\mathbb{R}^{\text{input_dim}}\).

Save and Load Transformations

To save and load transformations, use the following methods:

Transform.copy()	Return a deep copy of the transformation.
Transform.to_dict()	Serialize the transformation to a dictionary.
Transform.from_dict(data)	Create a Transform object from a dictionary.
Transform.to_json(filepath)	Write the transformation to a JSON file.
Transform.from_json(filepath)	Read a Transform object from a JSON file.

Developing Custom Transformations

To create a custom transformation, subclass the Transform class and implement the required methods. Refer to the documentation of each method for guidance on their implementation.

First edit the class attributes if necessary:

• _input_dim: Set this to the dimension of the input space.

• _output_dim: Set this to the dimension of the output space.

• _result_class: Set this to the class used for the result of the transformation.

• _inverse_result_class: Set this to the class used for the result of the inverse transformation

Transform._get_jacobian_shorthands()	Return a dictionary of short-hand notation for the Jacobian matrices.
Transform._get_transform_aliases()	Return a list of aliases for the transformed points.
Transform._get_inverse_transform_aliases()	Return a list of aliases for the inverse transformed points.
Transform.is_set()	Method to check if the transformation parameters and constants are set.
Transform._return_transform_result(...)	Return the result of the transformation as a TransformResult object.
Transform._return_inverse_transform_result(...)	Return the result of the inverse transformation as a TransformResult object.
Transform._transform(points, *[, dx, dp])	Apply the transformation to the given points.
Transform._inverse_transform(points, *[, dx, dp])	Apply the inverse transformation to the given points.