artist.geometry.coordinates

Functions

`convert_3d_points_to_4d_format`(→ torch.Tensor)	Append ones to the last dimension of 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).
`bitmap_coordinates_to_target_coordinates`(→ torch.Tensor)	Convert bitmap pixel coordinates to 4D homogeneous world coordinates on the target surface.
`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 WGS84 coordinates (latitude, longitude, altitude) to local east, north, and up (ENU) offsets.

Module Contents

artist.geometry.coordinates.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.coordinates.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.coordinates.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.coordinates.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.coordinates.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.coordinates.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].