artist.util.utils ================= .. py:module:: artist.util.utils Functions --------- .. autoapisummary:: artist.util.utils.rotate_distortions artist.util.utils.rotate_e artist.util.utils.rotate_n artist.util.utils.rotate_u artist.util.utils.translate_enu artist.util.utils.convert_3d_points_to_4d_format artist.util.utils.convert_3d_directions_to_4d_format artist.util.utils.normalize_points artist.util.utils.decompose_rotations artist.util.utils.angle_between_vectors artist.util.utils.transform_initial_angle artist.util.utils.get_center_of_mass artist.util.utils.create_nurbs_evaluation_grid artist.util.utils.create_ideal_canted_nurbs_control_points artist.util.utils.normalize_bitmaps artist.util.utils.trapezoid_distribution artist.util.utils.crop_flux_distributions_around_center artist.util.utils.azimuth_elevation_to_enu artist.util.utils.convert_wgs84_coordinates_to_local_enu Module Contents --------------- .. py:function:: rotate_distortions(e: torch.Tensor, u: torch.Tensor, device: torch.device | None = None) -> torch.Tensor Rotate the distortions for the light source. Rotate around the up and then the east axis in this very order in a right-handed east-north-up coordinate system. Positive angles result in a rotation in the mathematical direction of rotation, i.e., counter-clockwise. Points need to be multiplied as column vectors from the right-hand side with the resulting rotation matrix. Note that the order is fixed due to the non-commutative property of matrix-matrix multiplication. Parameters ---------- e : torch.Tensor East rotation angles in radians. u : torch.Tensor Up rotation angles in radians. device : torch.device | None The device on which to perform computations or load tensors and models (default is None). If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Raises ------ ValueError If the sizes of the input tensors do not match. Returns ------- torch.Tensor Corresponding rotation matrix. .. py:function:: rotate_e(e: torch.Tensor, device: torch.device | None = None) -> torch.Tensor Rotate around the east axis. Rotate around the east axis in a right-handed east-north-up coordinate system. Positive angles result in a rotation in the mathematical direction of rotation, i.e., counter-clockwise. Points need to be multiplied as column vectors from the right-hand side with the resulting rotation matrix. Parameters ---------- e : torch.Tensor East rotation angles in radians. device : torch.device | None The device on which to perform computations or load tensors and models (default is None). If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Returns ------- torch.Tensor Corresponding rotation matrix. .. py:function:: rotate_n(n: torch.Tensor, device: torch.device | None = None) -> torch.Tensor Rotate around the north axis. Rotate around the north axis in a right-handed east-north-up coordinate system. Positive angles result in a rotation in the mathematical direction of rotation, i.e., counter-clockwise. Points need to be multiplied as column vectors from the right-hand side with the resulting rotation matrix. Parameters ---------- n : torch.Tensor North rotation angles in radians. device : torch.device | None The device on which to perform computations or load tensors and models (default is None). If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Returns ------- torch.Tensor Corresponding rotation matrix. .. py:function:: rotate_u(u: torch.Tensor, device: torch.device | None = None) -> torch.Tensor Rotate around the up axis. Rotate around the up axis in a right-handed east-north-up coordinate system. Positive angles result in a rotation in the mathematical direction of rotation, i.e., counter-clockwise. Points need to be multiplied as column vectors from the right-hand side with the resulting rotation matrix. Parameters ---------- u : torch.Tensor Up rotation angles in radians. device : torch.device | None The device on which to perform computations or load tensors and models (default is None). If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Returns ------- torch.Tensor Corresponding rotation matrix. .. py:function:: translate_enu(e: torch.Tensor, n: torch.Tensor, u: torch.Tensor, device: torch.device | None = None) -> torch.Tensor Translate in all directions. Translate a given point in the east, north, and up direction. Note that the point must be multiplied as a column vector from the right-hand side of the resulting matrix. Parameters ---------- e : torch.Tensor East translations. n : torch.Tensor North translations. u : torch.Tensor Up translations. device : torch.device | None The device on which to perform computations or load tensors and models (default is None). If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Raises ------ ValueError If the sizes of the input tensors do not match. Returns ------- torch.Tensor Corresponding rotation matrix. .. py:function:: convert_3d_points_to_4d_format(points: torch.Tensor, device: torch.device | None = None) -> torch.Tensor Append ones to the last dimension of a 3D point vectors. Includes the convention that points have a 1 and directions have 0 as 4th dimension. This function can handle batched tensors. Parameters ---------- points : torch.Tensor Input points in a 3D format. Tensor of shape [..., 3]. The tensor may have arbitrary many batch dimensions, but the last shape dimension must be 3. device : torch.device | None The device on which to perform computations or load tensors and models (default is None). If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Raises ------ ValueError If the input is not 3D. Returns ------- torch.Tensor Point vector with ones appended at the last dimension. Tensor of shape [..., 4]. .. py:function:: convert_3d_directions_to_4d_format(directions: torch.Tensor, device: torch.device | None = None) -> torch.Tensor Append zeros to the last dimension of 3D direction vectors. Includes the convention that points have a 1 and directions have 0 as 4th dimension. This function can handle batched tensors. Parameters ---------- directions : torch.Tensor Input direction in a 3D format. Tensor of shape [..., 3]. The tensor may have arbitrary many batch dimensions, but the last shape dimension must be 3. device : torch.device | None The device on which to perform computations or load tensors and models (default is None). If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Raises ------ ValueError If the input is not 3D. Returns ------- torch.Tensor Direction vectors with ones appended at the last dimension. Tensor of shape [..., 4]. .. py:function:: normalize_points(points: torch.Tensor) -> torch.Tensor Normalize each column of a 2D tensor to the open interval (0, 1). Parameters ---------- points : torch.Tensor A tensor containing points to be normalized. Tensor of shape [number_of_points, 2]. Returns ------- torch.Tensor The normalized points. Tensor of shape [number_of_points, 2]. .. py:function:: decompose_rotations(initial_vector: torch.Tensor, target_vector: torch.Tensor, device: torch.device | None = None) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor] Get the individual angles along the east-, north- and up-axis, to rotate and initial vector into a target vector. Parameters ---------- initial_vector : torch.Tensor The initial vector. Tensor of shape [number_of_heliostats, 4]. rotated_vector : torch.Tensor The rotated vector. Tensor of shape [4]. device : torch.device | None The device on which to perform computations or load tensors and models (default is None). If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Returns ------- torch.Tensor The angle for the east-axis rotation. torch.Tensor The angle for the north-axis rotation. torch.Tensor The angle for the up-axis rotation. .. py:function:: angle_between_vectors(vector_1: torch.Tensor, vector_2: torch.Tensor) -> torch.Tensor Calculate the angle between two vectors. Parameters ---------- vector_1 : torch.Tensor The first vector. vector_2 : torch.Tensor The second vector. Return ------ torch.Tensor The angle between the input vectors. .. py:function:: transform_initial_angle(initial_angle: torch.Tensor, initial_orientation: torch.Tensor, device: torch.device | None = None) -> torch.Tensor Compute the transformed angle of an initial angle in a rotated coordinate system. This function accounts for a known offset, the initial angle, in the initial orientation vector. The offset represents a rotation around the east-axis. When the coordinate system is rotated to align the initial orientation with the ``ARTIST`` standard orientation, the axis for the offset rotation also changes. This function calculates the equivalent transformed angle for the offset in the rotated coordinate system. Parameters ---------- initial_angle : torch.Tensor The initial angle, or offset along the east-axis. initial_orientation : torch.Tensor The initial orientation of the coordinate system. device : torch.device | None The device on which to perform computations or load tensors and models (default is None). If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Returns ------- torch.Tensor The transformed angle in the rotated coordinate system. .. py:function:: get_center_of_mass(bitmaps: torch.Tensor, target_centers: torch.Tensor, target_widths: float, target_heights: float, threshold: float = 0.0, device: torch.device | None = None) -> torch.Tensor Calculate the coordinates of the flux density center of mass. First determine the indices of the bitmap center of mass. Next determine the position (coordinates) of the center of mass on the target. Parameters ---------- bitmaps : torch.Tensor The flux densities in form of bitmaps. Tensor of shape [number_of_active_heliostats, bitmap_resolution_e, bitmap_resolution_u]. target_centers : torch.Tensor The positions of the centers of the targets. Tensor of shape [number_of_active_heliostats, 4]. target_widths : float The widths of the target surfaces. Tensor of shape [number_of_active_heliostats]. target_heights : float The heights of the target surfaces. Tensor of shape [number_of_active_heliostats]. threshold : float Determines how intense a pixel in the bitmap needs to be to be registered (default is 0.0). device : torch.device | None The device on which to perform computations or load tensors and models (default is None). If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Returns ------- torch.Tensor The coordinates of the flux density centers of mass. Tensor of shape [number_of_active_heliostats, 4]. .. py:function:: create_nurbs_evaluation_grid(number_of_evaluation_points: torch.Tensor, epsilon: float = 1e-07, device: torch.device | None = None) -> torch.Tensor Create a grid of evaluation points for a nurbs surface. Parameters ---------- number_of_evaluation_points : torch.Tensor The number of nurbs evaluation points in east and north direction. Tensor of shape [2]. epsilon : float Offset for the nurbs evaluation points (default is 1e-7). NURBS are defined in the interval of [0, 1] but have numerical instabilities at their endpoints therefore the evaluation points need a small offset from the endpoints. device : torch.device | None The device on which to perform computations or load tensors and models (default is None). If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Returns ------- torch.Tensor The evaluation points. Tensor of shape [number_of_evaluation_points_e * number_of_evaluation_points_e, 2]. .. py:function:: create_ideal_canted_nurbs_control_points(number_of_control_points: torch.Tensor, canting: torch.Tensor, facet_translation_vectors: torch.Tensor, device: torch.device | None = None) -> torch.Tensor Create ideal, canted and translated control points for each facet. Parameters ---------- number_of_control_points : torch.Tensor The number of NURBS control points. Tensor of shape [2]. canting : torch.Tensor The canting vector for each facet. Tensor of shape [number_of_facets, 2, 4]. facet_translation_vectors : torch.Tensor The facet translation vector for each facet. Tensor of shape [number_of_facets, 4]. device : torch.device | None The device on which to perform computations or load tensors and models (default is None). If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Returns ------- torch.Tensor The canted and translated ideal NURBS control points. Tensor of shape [number_of_facets, number_of_control_points_u_direction, number_of_control_points_v_direction, 3]. .. py:function:: normalize_bitmaps(flux_distributions: torch.Tensor, target_area_widths: torch.Tensor, target_area_heights: torch.Tensor, number_of_rays: torch.Tensor | int) -> torch.Tensor Normalize a bitmap. Parameters ---------- flux_distributions : torch.Tensor The flux distributions to be normalized. Tensor of shape [number_of_bitmaps, bitmap_resolution_e, bitmap_resolution_u]. target_area_widths : torch.Tensor The target area widths. Tensor of shape [number_of_bitmaps]. target_area_heights : torch.Tensor The target area heights. Tensor of shape [number_of_bitmaps]. number_of_rays : torch.Tensor | int The number of rays used to generate the flux. Tensor of shape [number_of_bitmaps]. Returns ------- torch.Tensor The normalized and scaled flux density distributions. Tensor of shape [number_of_bitmaps, bitmap_resolution_e, bitmap_resolution_u]. .. py:function:: trapezoid_distribution(total_width: int, slope_width: int, plateau_width: int, device: torch.device | None = None) -> torch.Tensor Create a one dimensional trapezoid distribution. If the total width is less than 2 * slope_width + plateau_width, the slope is cut off. If total total width is greater than 2 * slope_width + plateau_width the trapezoid is padded with zeros on both sides. Parameters ---------- total_width : int The total width of the trapezoid. slope_width : int The width of the slope of the trapezoid. plateau_width : int The width of the plateau. device : torch.device | None The device on which to perform computations or load tensors and models (default is None). If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Returns ------- torch.Tensor The one dimensional trapezoid distribution. Tensor of shape [total_width]. .. py:function:: crop_flux_distributions_around_center(flux_distributions: torch.Tensor, crop_width: float, crop_height: float, target_plane_widths: torch.Tensor, target_plane_heights: torch.Tensor, device: torch.device | None = None) -> torch.Tensor Crop a centered rectangular region from grayscale intensity images based on physical dimensions. This function identifies the center of mass in each image and then crops a region centered around this point with the specified physical width and height (in meters). The cropping is applied via affine transformation, which accounts for the desired crop size relative to the target's physical plane dimensions. Parameters ---------- flux_distributions : torch.Tensor Grayscale intensity images. Tensor of shape [number_of_bitmaps, bitmap_height, bitmap_width]. crop_width : float Desired width of the cropped region in meters. crop_height : float Desired height of the cropped region in meters. target_plane_widths : torch.Tensor Physical widths in meters of each image in the batch. Tensor of shape [number_of_bitmaps]. target_plane_heights : torch.Tensor Physical heights in meters of each image in the batch. Tensor of shape [number_of_bitmaps]. device : torch.device | None The device on which to perform computations or load tensors and models (default is None). If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Returns ------- torch.Tensor The cropped image regions. Tensor of shape [number_of_bitmaps, bitmap_height, bitmap_width]. .. py:function:: azimuth_elevation_to_enu(azimuth: torch.Tensor, elevation: torch.Tensor, slant_range: float = 1.0, degree: bool = True, device: torch.device | None = None) -> torch.Tensor Transform coordinates from azimuth and elevation to east, north and up. This method assumes a south-oriented azimuth-elevation coordinate system, where 0° points toward the south. Parameters ---------- azimuth : torch.Tensor Azimuth, 0° points toward the south (degrees). Tensor of shape [number_of_samples]. elevation : torch.Tensor Elevation angle above horizon, neglecting aberrations (degrees). Tensor of shape [number_of_samples]. slant_range : float Slant range in meters (default is 1.0). degree : bool Whether input is given in degrees (default is True). device : torch.device | None The device on which to perform computations or load tensors and models (default is None). If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Returns ------- torch.Tensor The east, north and up (ENU) coordinates. Tensor of shape [number_of_samples, 3]. .. py:function:: convert_wgs84_coordinates_to_local_enu(coordinates_to_transform: torch.Tensor, reference_point: torch.Tensor, device: torch.device | None = None) -> torch.Tensor Transform coordinates from latitude, longitude and altitude (WGS84) to local east, north and up (ENU). This function calculates the north and east offsets in meters of a coordinate from the reference point. It converts the latitude and longitude to radians, calculates the radius of curvature values, and then computes the offsets based on the differences between the coordinate and the reference point. Finally, it returns a tensor containing these offsets along with the altitude difference. Parameters ---------- coordinates_to_transform : torch.Tensor The coordinates in latitude, longitude, altitude that are to be transformed. Tensor of shape [number_of_coordinates, 3]. reference_point : torch.Tensor The center of origin of the ENU coordinate system in WGS84 coordinates. Tensor of shape [3]. device : torch.device | None The device on which to perform computations or load tensors and models (default is None). If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Returns ------- torch.Tensor The east offsets in meters, norths offset in meters, and the altitude differences from the reference point. Tensor of shape [number_of_coordinates, 3].