artist.util.utils

Functions

`rotate_distortions`(→ torch.Tensor)	Rotate the distortions for the light source.
`rotate_e`(→ torch.Tensor)	Rotate around the east axis.
`rotate_n`(→ torch.Tensor)	Rotate around the north axis.
`rotate_u`(→ torch.Tensor)	Rotate around the up axis.
`translate_enu`(→ torch.Tensor)	Translate in all directions.
`convert_3d_points_to_4d_format`(→ torch.Tensor)	Append ones to the last dimension of a 3D point vectors.
`convert_3d_directions_to_4d_format`(→ torch.Tensor)	Append zeros to the last dimension of 3D direction vectors.
`normalize_points`(→ torch.Tensor)	Normalize each column of a 2D tensor to the open interval (0, 1).
`decompose_rotations`(→ tuple[torch.Tensor, ...)	Get the individual angles along the east-, north- and up-axis, to rotate and initial vector into a target vector.
`angle_between_vectors`(→ torch.Tensor)	Calculate the angle between two vectors.
`transform_initial_angle`(→ torch.Tensor)	Compute the transformed angle of an initial angle in a rotated coordinate system.
`get_center_of_mass`(→ torch.Tensor)	Calculate the coordinates of the flux density center of mass.
`create_nurbs_evaluation_grid`(→ torch.Tensor)	Create a grid of evaluation points for a nurbs surface.
`create_ideal_canted_nurbs_control_points`(→ torch.Tensor)	Create ideal, canted and translated control points for each facet.
`normalize_bitmaps`(→ torch.Tensor)	Normalize a bitmap.
`trapezoid_distribution`(→ torch.Tensor)	Create a one dimensional trapezoid distribution.
`crop_flux_distributions_around_center`(→ torch.Tensor)	Crop a centered rectangular region from grayscale intensity images based on physical dimensions.
`azimuth_elevation_to_enu`(→ torch.Tensor)	Transform coordinates from azimuth and elevation to east, north and up.
`convert_wgs84_coordinates_to_local_enu`(→ torch.Tensor)	Transform coordinates from latitude, longitude and altitude (WGS84) to local east, north and up (ENU).

Module Contents

artist.util.utils.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

etorch.Tensor: East rotation angles in radians.
utorch.Tensor: Up rotation angles in radians.
devicetorch.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.

artist.util.utils.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

etorch.Tensor: East rotation angles in radians.
devicetorch.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.

artist.util.utils.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

ntorch.Tensor: North rotation angles in radians.
devicetorch.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.

artist.util.utils.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

utorch.Tensor: Up rotation angles in radians.
devicetorch.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.

artist.util.utils.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

etorch.Tensor: East translations.
ntorch.Tensor: North translations.
utorch.Tensor: Up translations.
devicetorch.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.

artist.util.utils.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

pointstorch.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.
devicetorch.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].

artist.util.utils.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

directionstorch.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.
devicetorch.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].

artist.util.utils.normalize_points(points: torch.Tensor) → torch.Tensor

Normalize each column of a 2D tensor to the open interval (0, 1).

Parameters

pointstorch.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].

artist.util.utils.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_vectortorch.Tensor: The initial vector. Tensor of shape [number_of_heliostats, 4].
rotated_vectortorch.Tensor: The rotated vector. Tensor of shape [4].
devicetorch.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.

artist.util.utils.angle_between_vectors(vector_1: torch.Tensor, vector_2: torch.Tensor) → torch.Tensor

Calculate the angle between two vectors.

Parameters

vector_1torch.Tensor: The first vector.
vector_2torch.Tensor: The second vector.

Return

torch.Tensor: The angle between the input vectors.

artist.util.utils.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_angletorch.Tensor: The initial angle, or offset along the east-axis.
initial_orientationtorch.Tensor: The initial orientation of the coordinate system.
devicetorch.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.

artist.util.utils.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

bitmapstorch.Tensor: The flux densities in form of bitmaps. Tensor of shape [number_of_active_heliostats, bitmap_resolution_e, bitmap_resolution_u].
target_centerstorch.Tensor: The positions of the centers of the targets. Tensor of shape [number_of_active_heliostats, 4].
target_widthsfloat: The widths of the target surfaces. Tensor of shape [number_of_active_heliostats].
target_heightsfloat: The heights of the target surfaces. Tensor of shape [number_of_active_heliostats].
thresholdfloat: Determines how intense a pixel in the bitmap needs to be to be registered (default is 0.0).
devicetorch.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].

artist.util.utils.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_pointstorch.Tensor: The number of nurbs evaluation points in east and north direction. Tensor of shape [2].
epsilonfloat: 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.
devicetorch.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].

artist.util.utils.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_pointstorch.Tensor: The number of NURBS control points. Tensor of shape [2].
cantingtorch.Tensor: The canting vector for each facet. Tensor of shape [number_of_facets, 2, 4].
facet_translation_vectorstorch.Tensor: The facet translation vector for each facet. Tensor of shape [number_of_facets, 4].
devicetorch.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].

artist.util.utils.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_distributionstorch.Tensor: The flux distributions to be normalized. Tensor of shape [number_of_bitmaps, bitmap_resolution_e, bitmap_resolution_u].
target_area_widthstorch.Tensor: The target area widths. Tensor of shape [number_of_bitmaps].
target_area_heightstorch.Tensor: The target area heights. Tensor of shape [number_of_bitmaps].
number_of_raystorch.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].

artist.util.utils.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_widthint: The total width of the trapezoid.
slope_widthint: The width of the slope of the trapezoid.
plateau_widthint: The width of the plateau.
devicetorch.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].

artist.util.utils.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_distributionstorch.Tensor: Grayscale intensity images. Tensor of shape [number_of_bitmaps, bitmap_height, bitmap_width].
crop_widthfloat: Desired width of the cropped region in meters.
crop_heightfloat: Desired height of the cropped region in meters.
target_plane_widthstorch.Tensor: Physical widths in meters of each image in the batch. Tensor of shape [number_of_bitmaps].
target_plane_heightstorch.Tensor: Physical heights in meters of each image in the batch. Tensor of shape [number_of_bitmaps].
devicetorch.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].

artist.util.utils.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

azimuthtorch.Tensor: Azimuth, 0° points toward the south (degrees). Tensor of shape [number_of_samples].
elevationtorch.Tensor: Elevation angle above horizon, neglecting aberrations (degrees). Tensor of shape [number_of_samples].
slant_rangefloat: Slant range in meters (default is 1.0).
degreebool: Whether input is given in degrees (default is True).
devicetorch.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].

artist.util.utils.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_transformtorch.Tensor: The coordinates in latitude, longitude, altitude that are to be transformed. Tensor of shape [number_of_coordinates, 3].
reference_pointtorch.Tensor: The center of origin of the ENU coordinate system in WGS84 coordinates. Tensor of shape [3].
devicetorch.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].