artist.geometry.coordinates =========================== .. py:module:: artist.geometry.coordinates Functions --------- .. autoapisummary:: artist.geometry.coordinates.convert_3d_points_to_4d_format artist.geometry.coordinates.convert_3d_directions_to_4d_format artist.geometry.coordinates.normalize_points artist.geometry.coordinates.bitmap_coordinates_to_target_coordinates artist.geometry.coordinates.azimuth_elevation_to_enu artist.geometry.coordinates.convert_wgs84_coordinates_to_local_enu Module Contents --------------- .. 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_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:: 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:: 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:: 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:: 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]``.