artist.geometry =============== .. py:module:: artist.geometry Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/artist/geometry/coordinates/index /autoapi/artist/geometry/rotations/index /autoapi/artist/geometry/transforms/index Functions --------- .. autoapisummary:: artist.geometry.azimuth_elevation_to_enu artist.geometry.bitmap_coordinates_to_target_coordinates artist.geometry.convert_3d_directions_to_4d_format artist.geometry.convert_3d_points_to_4d_format artist.geometry.convert_wgs84_coordinates_to_local_enu artist.geometry.normalize_points artist.geometry.decompose_rotations artist.geometry.rotation_angle_and_axis artist.geometry.perform_canting artist.geometry.rotate_distortions artist.geometry.rotate_e artist.geometry.rotate_n artist.geometry.rotate_u artist.geometry.translate_enu Package Contents ---------------- .. 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). Shape is ``[number_of_samples]``. elevation : torch.Tensor Elevation angle above horizon, neglecting aberrations (degrees). Shape is ``[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. Shape is ``[number_of_samples, 3]``. .. py:function:: 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_coordinates : torch.Tensor Pixel coordinates in the bitmap for each heliostat, as (e, u) pairs. Shape is ``[number_of_active_heliostats, 2]``. bitmap_resolution : torch.Tensor Resolution of the bitmap (width, height) in pixels. Shape is ``[2]``. solar_tower : SolarTower Solar tower containing all target area definitions (planar and cylindrical). target_area_indices : torch.Tensor Global target area index for each heliostat (planar indices first, cylindrical second). Shape is ``[number_of_active_heliostats]``. 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 World coordinates on the target surface in homogeneous format. Shape is ``[number_of_active_heliostats, 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 a 0 as 4th dimension. This function can handle batched tensors. Parameters ---------- directions : torch.Tensor Input direction in a 3D format. Shape is ``[..., 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 zeros appended at the last dimension. Shape is ``[..., 4]``. .. 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 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 ---------- points : torch.Tensor Input points in a 3D format. Shape is ``[..., 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. Shape is ``[..., 4]``. .. 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 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_transform : torch.Tensor The coordinates in latitude, longitude, altitude that are to be transformed. Shape is ``[number_of_coordinates, 3]``. reference_point : torch.Tensor The center of origin of the ENU coordinate system in WGS84 coordinates. Shape is ``[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, north offsets in meters, and the altitude differences from the reference point. Shape is ``[number_of_coordinates, 3]``. .. 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. Shape is ``[number_of_points, number_of_dimensions]``. Returns ------- torch.Tensor The normalized points. Shape is ``[number_of_points, number_of_dimensions]``. .. py:function:: 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_vector : torch.Tensor Initial vectors in homogeneous coordinates. Shape is ``[number_of_heliostats, 4]``. Only the first three components (ENU) are used. target_vector : torch.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]``. .. py:function:: 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_orientation : torch.Tensor The original orientation. Shape is ``[4]``. to_orientation : torch.Tensor The rotated orientation. Shape is ``[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 rotation axis. Shape is ``[3]``. torch.Tensor The angle of the rotation as a scalar tensor. .. py:function:: 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_angles : torch.Tensor Canting angles. Shape is ``[number_of_surfaces, number_of_facets, 2, 4]``. data : torch.Tensor Data to be canted. Shape is ``[number_of_surfaces, number_of_facets, number_of_points_per_facet, 4]``. inverse : bool Indicates the direction of the rotation. Use ``inverse=False`` for canting and ``inverse=True`` for decanting (default is False). 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 (de-)canted data. Shape is ``[number_of_surfaces, number_of_facets, number_of_points_per_facet, 4]``. .. 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. Shape is ``[number_of_heliostats, number_of_rays, number_of_surface_points]``. u : torch.Tensor Up rotation angles in radians. Shape is ``[number_of_heliostats, number_of_rays, number_of_surface_points]``. 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 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]``. .. 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. Shape is ``[number_of_heliostats]``. 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 Batched 4×4 east-axis rotation matrices, one per heliostat. Shape is ``[number_of_heliostats, 4, 4]``. .. 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. Shape is ``[number_of_heliostats]``. 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 Batched 4×4 north-axis rotation matrices, one per heliostat. Shape is ``[number_of_heliostats, 4, 4]``. .. 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. Shape is ``[number_of_heliostats]``. 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 Batched 4×4 up-axis rotation matrices, one per heliostat. Shape is ``[number_of_heliostats, 4, 4]``. .. 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 translation distances in meters. Shape is ``[number_of_heliostats]``. n : torch.Tensor North translation distances in meters. Shape is ``[number_of_heliostats]``. u : torch.Tensor Up translation distances in meters. Shape is ``[number_of_heliostats]``. 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 Batched 4×4 translation matrices, one per heliostat. Shape is ``[number_of_heliostats, 4, 4]``.