artist.geometry

Submodules

• artist.geometry.coordinates
• artist.geometry.rotations
• artist.geometry.transforms

Functions

azimuth_elevation_to_enu(→ torch.Tensor)	Transform coordinates from azimuth and elevation to east, north, and up.
bitmap_coordinates_to_target_coordinates(→ torch.Tensor)	Convert bitmap pixel coordinates to 4D homogeneous world coordinates on the target surface.
convert_3d_directions_to_4d_format(→ torch.Tensor)	Append zeros to the last dimension of 3D direction vectors.
convert_3d_points_to_4d_format(→ torch.Tensor)	Append ones to the last dimension of 3D point vectors.
convert_wgs84_coordinates_to_local_enu(→ torch.Tensor)	Transform WGS84 coordinates (latitude, longitude, altitude) to local east, north, and up (ENU) offsets.
normalize_points(→ torch.Tensor)	Normalize each column of a 2D tensor to the open interval (0, 1).
decompose_rotations(→ tuple[torch.Tensor, ...)	Compute ENU components of the axis-angle rotation vector that rotates initial vectors toward a target vector.
rotation_angle_and_axis(→ tuple[torch.Tensor, ...)	Compute the rotation axis and angle between two orientations.
perform_canting(→ torch.Tensor)	Perform canting (rotation) on data like surface points or surface normals.
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.

Package Contents

artist.geometry.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). Shape is [number_of_samples].

elevationtorch.Tensor

Elevation angle above horizon, neglecting aberrations (degrees). Shape is [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. Shape is [number_of_samples, 3].

artist.geometry.bitmap_coordinates_to_target_coordinates(bitmap_coordinates: torch.Tensor, bitmap_resolution: torch.Tensor, solar_tower: artist.field.solar_tower.SolarTower, target_area_indices: torch.Tensor, device: torch.device | None = None) → torch.Tensor

Convert bitmap pixel coordinates to 4D homogeneous world coordinates on the target surface.

For planar target areas the pixel coordinates are mapped linearly to target plane coordinates. For cylindrical target areas the pixel coordinates are mapped to cylindrical surface coordinates using the cylinder’s radius, opening angle, height, axis, and normal.

Bitmaps and the resolution are conceptually defined as: [W, H] # width, height Tensor memory layout follows PyTorch convention: [H, W] # height, width

The bitmap is treated as a discrete image grid with resolution:

• bitmap_resolution = [width, height]

Pixel coordinates follow image indexing conventions:

• bitmap_coordinates[…, e] ∈ [0, W-1]

• bitmap_coordinates[…, u] ∈ [0, H-1]

They are interpreted as centered pixels:

• (e + 0.5) / W

• (u + 0.5) / H

This ensures each pixel represents its spatial cell center rather than its corner.

The e-axis is intentionally flipped (0.5 - e_norm) to match the desired bitmap orientation. This means: increasing bitmap e → decreases world e.

Parameters

bitmap_coordinatestorch.Tensor

Pixel coordinates in the bitmap for each heliostat, as (e, u) pairs. Shape is [number_of_active_heliostats, 2].

bitmap_resolutiontorch.Tensor

Resolution of the bitmap (width, height) in pixels. Shape is [2].

solar_towerSolarTower

Solar tower containing all target area definitions (planar and cylindrical).

target_area_indicestorch.Tensor

Global target area index for each heliostat (planar indices first, cylindrical second). Shape is [number_of_active_heliostats].

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

World coordinates on the target surface in homogeneous format. Shape is [number_of_active_heliostats, 4].

artist.geometry.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 a 0 as 4th dimension. This function can handle batched tensors.

Parameters

directionstorch.Tensor

Input direction in a 3D format. Shape is [..., 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 zeros appended at the last dimension. Shape is [..., 4].

artist.geometry.convert_3d_points_to_4d_format(points: torch.Tensor, device: torch.device | None = None) → torch.Tensor

Append ones to the last dimension of 3D point vectors.

Includes the convention that points have a 1 and directions have a 0 as 4th dimension. This function can handle batched tensors.

Parameters

pointstorch.Tensor

Input points in a 3D format. Shape is [..., 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. Shape is [..., 4].

artist.geometry.convert_wgs84_coordinates_to_local_enu(coordinates_to_transform: torch.Tensor, reference_point: torch.Tensor, device: torch.device | None = None) → torch.Tensor

Transform WGS84 coordinates (latitude, longitude, altitude) to local east, north, and up (ENU) offsets.

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.

Note that this implementation uses a local differential approximation (small-distance linearization), not a full ECEF->ENU transform. It is most accurate for coordinates near the reference point.

Parameters

coordinates_to_transformtorch.Tensor

The coordinates in latitude, longitude, altitude that are to be transformed. Shape is [number_of_coordinates, 3].

reference_pointtorch.Tensor

The center of origin of the ENU coordinate system in WGS84 coordinates. Shape is [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, north offsets in meters, and the altitude differences from the reference point. Shape is [number_of_coordinates, 3].

artist.geometry.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. Shape is [number_of_points, number_of_dimensions].

Returns

torch.Tensor

The normalized points. Shape is [number_of_points, number_of_dimensions].

artist.geometry.decompose_rotations(initial_vector: torch.Tensor, target_vector: torch.Tensor) → tuple[torch.Tensor, torch.Tensor, torch.Tensor]

Compute ENU components of the axis-angle rotation vector that rotates initial vectors toward a target vector.

This function does not perform an Euler-angle decomposition. Instead, it computes: 1) the rotation axis via cross product, and 2) the rotation magnitude via arccos of the dot product, then returns the Cartesian components of the rotation vector (theta * axis) in east, north, and up coordinates.

Parameters

initial_vectortorch.Tensor

Initial vectors in homogeneous coordinates. Shape is [number_of_heliostats, 4]. Only the first three components (ENU) are used.

target_vectortorch.Tensor

Target vector in homogeneous coordinates. Shape is [4]. Only the first three components (ENU) are used.

Returns

torch.Tensor

East component of the axis-angle rotation vector. Shape is [number_of_heliostats].

torch.Tensor

North component of the axis-angle rotation vector. Shape is [number_of_heliostats].

torch.Tensor

Up component of the axis-angle rotation vector. Shape is [number_of_heliostats].

artist.geometry.rotation_angle_and_axis(from_orientation: torch.Tensor, to_orientation: torch.Tensor, device: torch.device | None = None) → tuple[torch.Tensor, torch.Tensor]

Compute the rotation axis and angle between two orientations.

Parameters

from_orientationtorch.Tensor

The original orientation. Shape is [4].

to_orientationtorch.Tensor

The rotated orientation. Shape is [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 rotation axis. Shape is [3].

torch.Tensor

The angle of the rotation as a scalar tensor.

artist.geometry.perform_canting(canting_angles: torch.Tensor, data: torch.Tensor, inverse: bool = False, device: torch.device | None = None) → torch.Tensor

Perform canting (rotation) on data like surface points or surface normals.

Parameters

canting_anglestorch.Tensor

Canting angles. Shape is [number_of_surfaces, number_of_facets, 2, 4].

datatorch.Tensor

Data to be canted. Shape is [number_of_surfaces, number_of_facets, number_of_points_per_facet, 4].

inversebool

Indicates the direction of the rotation. Use inverse=False for canting and inverse=True for decanting (default is False).

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 (de-)canted data. Shape is [number_of_surfaces, number_of_facets, number_of_points_per_facet, 4].

artist.geometry.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. Shape is [number_of_heliostats, number_of_rays, number_of_surface_points].

utorch.Tensor

Up rotation angles in radians. Shape is [number_of_heliostats, number_of_rays, number_of_surface_points].

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 shapes of the input tensors do not match.

Returns

torch.Tensor

Batched 4×4 rotation matrices, one per distortion sample. Shape is [number_of_heliostats, number_of_rays, number_of_surface_points, 4, 4].

artist.geometry.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. Shape is [number_of_heliostats].

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

Batched 4×4 east-axis rotation matrices, one per heliostat. Shape is [number_of_heliostats, 4, 4].

artist.geometry.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. Shape is [number_of_heliostats].

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

Batched 4×4 north-axis rotation matrices, one per heliostat. Shape is [number_of_heliostats, 4, 4].

artist.geometry.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. Shape is [number_of_heliostats].

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

Batched 4×4 up-axis rotation matrices, one per heliostat. Shape is [number_of_heliostats, 4, 4].

artist.geometry.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 translation distances in meters. Shape is [number_of_heliostats].

ntorch.Tensor

North translation distances in meters. Shape is [number_of_heliostats].

utorch.Tensor

Up translation distances in meters. Shape is [number_of_heliostats].

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

Batched 4×4 translation matrices, one per heliostat. Shape is [number_of_heliostats, 4, 4].