artist.data_parser.paint_scenario_parser ======================================== .. py:module:: artist.data_parser.paint_scenario_parser Attributes ---------- .. autoapisummary:: artist.data_parser.paint_scenario_parser.log Functions --------- .. autoapisummary:: artist.data_parser.paint_scenario_parser.extract_paint_tower_measurements artist.data_parser.paint_scenario_parser.extract_paint_heliostat_properties artist.data_parser.paint_scenario_parser.extract_paint_deflectometry_data artist.data_parser.paint_scenario_parser._ideal_surface_generator artist.data_parser.paint_scenario_parser._fitted_surface_generator artist.data_parser.paint_scenario_parser._process_heliostats_from_paths artist.data_parser.paint_scenario_parser.extract_paint_heliostats_ideal_surface artist.data_parser.paint_scenario_parser.extract_paint_heliostats_fitted_surface artist.data_parser.paint_scenario_parser.extract_paint_heliostats_mixed_surface artist.data_parser.paint_scenario_parser.corner_points_to_plane artist.data_parser.paint_scenario_parser.build_heliostat_data_mapping Module Contents --------------- .. py:data:: log A logger for the paint data loader. .. py:function:: extract_paint_tower_measurements(tower_measurements_path: pathlib.Path, device: torch.device | None = None) -> tuple[artist.scenario.configuration_classes.PowerPlantConfig, artist.scenario.configuration_classes.TargetAreaListConfig] Extract tower data from a ``PAINT`` tower measurements file for scenario generation. Parameters ---------- tower_measurements_path : pathlib.Path The path to the tower measurement file. 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 ------- PowerPlantConfig The configuration of the power plant. TargetAreaListConfig The configuration of the tower target areas. .. py:function:: extract_paint_heliostat_properties(heliostat_properties_path: pathlib.Path, power_plant_position: torch.Tensor, device: torch.device | None = None) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, artist.scenario.configuration_classes.KinematicDeviations, torch.Tensor, list[tuple[str, bool, list[float], artist.scenario.configuration_classes.ActuatorParameters]]] Extract heliostat properties from paint. Parameters ---------- heliostat_properties_path : pathlib.Path The path to the heliostat properties file. power_plant_position : torch.Tensor Tensor of shape [3]. The power plant position. 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 heliostat position. Tensor of shape [4]. torch.Tensor The facet translation vectors. Tensor of shape [number_of_facets, 4]. torch.Tensor The facet canting vectors in east and north direction. Tensor of shape [number_of_facets, 2, 4]. KinematicDeviations The kinematic deviation parameters. torch.Tensor The initial orientation. Tensor of shape [4]. list[tuple[str, bool, list[float], ActuatorParameters]] The actuator parameter list. .. py:function:: extract_paint_deflectometry_data(heliostat_deflectometry_path: pathlib.Path, number_of_facets: int, device: torch.device | None = None) -> tuple[list[torch.Tensor], list[torch.Tensor]] Extract paint deflectometry data. Parameters ---------- heliostat_deflectometry_path : pathlib.Path The heliostat deflectometry file path. number_of_facets : int The number of facets. 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 ------- list[torch.Tensor] The surface points per facet. list[torch.Tensor] The surface normals per facet. .. py:function:: _ideal_surface_generator(file_tuple: tuple[str, pathlib.Path], facet_translation_vectors: torch.Tensor, canting: torch.Tensor, number_of_nurbs_control_points: torch.Tensor, device: torch.device | None, **kwargs: Any) -> artist.scenario.configuration_classes.SurfaceConfig Generate a surface configuration for an ideal heliostat. This is a helper function designed to be passed as a callable to the `_process_heliostats_from_paths` function, handling the specific logic for generating an ideal surface. Parameters ---------- file_tuple : tuple[str, pathlib.Path] A tuple containing the heliostat name and path to the properties file, not used in this function but required for API compatibility. facet_translation_vectors : torch.Tensor The translation vectors for each facet. Tensor of shape [number_of_facets, 4]. canting : torch.Tensor The canting vectors for each facet. Tensor of shape [number_of_facets, 2, 4]. number_of_nurbs_control_points : torch.Tensor The number of NURBS control points. Tensor of shape [2]. device : torch.device | None The device to use. \*\*kwargs : Any Additional keyword arguments, not used by this function but accepted for API compatibility. Returns ------- SurfaceConfig The generated ideal surface configuration object. .. py:function:: _fitted_surface_generator(file_tuple: tuple[str, pathlib.Path, pathlib.Path], facet_translation_vectors: torch.Tensor, canting: torch.Tensor, number_of_nurbs_control_points: torch.Tensor, device: torch.device | None, **kwargs: Any) -> artist.scenario.configuration_classes.SurfaceConfig Generate a surface configuration for a fitted heliostat. This is a helper function designed to be passed as a callable to the `_process_heliostats_from_paths` function, handling the specific logic for generating a fitted surface based on deflectometry data. Parameters ---------- file_tuple : tuple[str, pathlib.Path, pathlib.Path] A tuple containing the heliostat name, path to the properties file, and path to deflectometry data file. facet_translation_vectors : torch.Tensor The translation vectors for each facet. Tensor of shape [number_of_facets, 4]. canting : torch.Tensor The canting vectors for each facet. Tensor of shape [number_of_facets, 2, 4]. number_of_nurbs_control_points : torch.Tensor The number of NURBS control points. Tensor of shape [2]. device : torch.device | None The device to use. \*\*kwargs : Any Additional keyword arguments used for the fitting process, including: - `nurbs_fit_optimizer`: The PyTorch optimizer for the NURBS fit. - `nurbs_fit_scheduler`: The PyTorch learning rate scheduler for the fit. - `deflectometry_step_size`: Step size to reduce data points for efficiency. - `nurbs_fit_method`: The fitting method to use. - `nurbs_fit_tolerance`: The tolerance for the fitting convergence. - `nurbs_fit_max_epoch`: The maximum number of epochs for the fit. Returns ------- SurfaceConfig The generated fitted surface configuration object. .. py:function:: _process_heliostats_from_paths(paths: list[tuple[str, pathlib.Path]] | list[tuple[str, pathlib.Path, pathlib.Path]], power_plant_position: torch.Tensor, number_of_nurbs_control_points: torch.Tensor, surface_config_generator: Callable, device: torch.device | None = None, **kwargs: Any) -> tuple[artist.scenario.configuration_classes.HeliostatListConfig, artist.scenario.configuration_classes.PrototypeConfig] Process heliostat properties from file paths. Parameters ---------- paths : list[tuple[str, pathlib.Path]] | list[tuple[str, pathlib.Path, pathlib.Path]] The list of heliostat paths, where each element's structure depends on whether the surface is ideal or fitted, i.e., for ideal surfaces only the heliostat name and path to the properties file is required, whilst for the fitted surface the path to the deflectometry file is also required. power_plant_position : torch.Tensor The position of the power plant in latitude, longitude and elevation. number_of_nurbs_control_points : torch.Tensor The number of NURBS control points. surface_config_generator : Callable A function that generates the surface configuration, either ideal or fitted. device : torch.device | None The device to use. \*\*kwargs : Any Any additional arguments to pass to the surface config generator function. Returns ------- HeliostatListConfig The configuration of all heliostats in the scenario. PrototypeConfig The configuration for a heliostat prototype. .. py:function:: extract_paint_heliostats_ideal_surface(paths: list[tuple[str, pathlib.Path]], power_plant_position: torch.Tensor, number_of_nurbs_control_points: torch.Tensor = torch.tensor([10, 10]), device: torch.device | None = None) -> tuple[artist.scenario.configuration_classes.HeliostatListConfig, artist.scenario.configuration_classes.PrototypeConfig] Extract heliostat data with ideal surfaces from ``PAINT`` heliostat properties files. Parameters ---------- paths : list[tuple[str, pathlib.Path]] Name of the heliostat and path to the heliostat properties file power_plant_position : torch.Tensor The position of the power plant in latitude, longitude and elevation. Tensor of shape [3]. number_of_nurbs_control_points : torch.Tensor The number of NURBS control points in both dimensions (default is torch.tensor([10,10])). Tensor of shape [2]. 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 ------- HeliostatListConfig The configuration of all heliostats in the scenario. PrototypeConfig The configuration for a heliostat prototype. .. py:function:: extract_paint_heliostats_fitted_surface(paths: list[tuple[str, pathlib.Path, pathlib.Path]], power_plant_position: torch.Tensor, nurbs_fit_optimizer: torch.optim.Optimizer, nurbs_fit_scheduler: torch.optim.lr_scheduler.LRScheduler, number_of_nurbs_control_points: torch.Tensor = torch.tensor([10, 10]), deflectometry_step_size: int = 100, nurbs_fit_method: str = config_dictionary.fit_nurbs_from_normals, nurbs_fit_tolerance: float = 1e-10, nurbs_fit_max_epoch: int = 400, device: torch.device | None = None) -> tuple[artist.scenario.configuration_classes.HeliostatListConfig, artist.scenario.configuration_classes.PrototypeConfig] Extract heliostat data with fitted surfaces from ``PAINT`` heliostat properties and deflectometry files. Parameters ---------- paths : list[tuple[str, pathlib.Path, pathlib.Path]] Name of the heliostat and a pair of heliostat properties and deflectometry file paths. power_plant_position : torch.Tensor The position of the power plant in latitude, longitude and elevation. Tensor of shape [3]. nurbs_fit_optimizer : torch.optim.Optimizer The NURBS fit optimizer. nurbs_fit_scheduler : torch.optim.lr_scheduler.LRScheduler The NURBS fit learning rate scheduler. number_of_nurbs_control_points : torch.Tensor The number of NURBS control points in both dimensions (default is torch.tensor([10,10])). Tensor of shape [2]. deflectometry_step_size : int The step size used to reduce the number of deflectometry points and normals for compute efficiency (default is 100). nurbs_fit_method : str The method used to fit the NURBS, either from deflectometry points or normals (default is config_dictionary.fit_nurbs_from_normals). nurbs_fit_tolerance : float The tolerance value used for fitting NURBS surfaces to deflectometry (default is 1e-10). nurbs_fit_max_epoch : int The maximum number of epochs for the NURBS fit (default is 400). 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 ------- HeliostatListConfig The configuration of all heliostats in the scenario. PrototypeConfig The configuration for a heliostat prototype. .. py:function:: extract_paint_heliostats_mixed_surface(paths: list[tuple[str, pathlib.Path]] | list[tuple[str, pathlib.Path, pathlib.Path]], power_plant_position: torch.Tensor, nurbs_fit_optimizer: torch.optim.Optimizer, nurbs_fit_scheduler: torch.optim.lr_scheduler.LRScheduler, number_of_nurbs_control_points: torch.Tensor = torch.tensor([10, 10]), deflectometry_step_size: int = 100, nurbs_fit_method: str = config_dictionary.fit_nurbs_from_normals, nurbs_fit_tolerance: float = 1e-10, nurbs_fit_max_epoch: int = 400, device: torch.device | None = None) -> tuple[artist.scenario.configuration_classes.HeliostatListConfig, artist.scenario.configuration_classes.PrototypeConfig] Extract heliostat data with a mix of ideal and fitted surfaces from PAINT files. This function processes a list of heliostat file paths. If a deflectometry path is provided for a heliostat, a fitted surface is generated. Otherwise, an ideal surface is used. Parameters ---------- paths : list[tuple[str, pathlib.Path, pathlib.Path]] | list[tuple[str, pathlib.Path, pathlib.Path, pathlib.Path]] A list where each tuple contains the heliostat name, path to the properties file, and an optional path to the deflectometry file. power_plant_position : torch.Tensor The position of the power plant in latitude, longitude, and elevation. Tensor of shape [3]. nurbs_fit_optimizer : torch.optim.Optimizer The NURBS fit optimizer. nurbs_fit_scheduler : torch.optim.lr_scheduler.LRScheduler The NURBS fit learning rate scheduler. number_of_nurbs_control_points : torch.Tensor The number of NURBS control points in both dimensions (default is torch.tensor([10,10])). Tensor of shape [2]. deflectometry_step_size : int The step size used to reduce the number of deflectometry points and normals for compute efficiency (default is 100). nurbs_fit_method : str The method used to fit the NURBS, either from deflectometry points or normals (default is config_dictionary.fit_nurbs_from_normals). nurbs_fit_tolerance : float The tolerance value used for fitting NURBS surfaces to deflectometry (default is 1e-10). nurbs_fit_max_epoch : int The maximum number of epochs for the NURBS fit (default is 400). 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 ------- HeliostatListConfig The configuration of all heliostats in the scenario. PrototypeConfig The configuration for a heliostat prototype. This is always based on an ideal surface. .. py:function:: corner_points_to_plane(upper_left: torch.Tensor, upper_right: torch.Tensor, lower_left: torch.Tensor, lower_right: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor] Span a plane from corner points. Parameters ---------- upper_left : torch.Tensor The upper left corner coordinate. Tensor of shape [3]. upper_right : torch.Tensor The upper right corner coordinate. Tensor of shape [3]. lower_left : torch.Tensor The lower left corner coordinate. Tensor of shape [3]. lower_right : torch.Tensor The lower right corner coordinate. Tensor of shape [3]. Returns ------- torch.Tensor The plane measurement in east direction. torch.Tensor The plane measurement in up direction. .. py:function:: build_heliostat_data_mapping(base_path: str, heliostat_names: list[str], number_of_measurements: int, image_variant: str, randomize: bool = True, seed: int = 42) -> list[tuple[str, list[pathlib.Path], list[pathlib.Path]]] Build a mapping of heliostat names to their calibration property and image files loaded from ``PAINT``. It assumes that the data directory has the same structure and file names the ``PAINT`` database. This method loads property and image files from the specified variant, and returns a structured mapping. If fewer measurements are available than requested, a warning is logged and the available subset is used. Optionally, the selection can be randomized using a fixed seed. Parameters ---------- base_path : str Path to the root directory containing heliostat calibration data. heliostat_names : list[str] List of heliostat names to include in the mapping. number_of_measurements : int Number of valid calibration samples to retrieve per heliostat. image_variant : str Image variant to use. Must match the expected filename suffix (``flux``, ``flux-centered``, ``cropped``, or ``raw``). randomize : bool Whether to shuffle the measurement files before selection (default is True). seed : int Random seed for reproducibility (default is 42). Returns ------- list[tuple[str, list[pathlib.Path], list[pathlib.Path]]] A list of tuples for each heliostat, where each tuple contains: - the heliostat name, - a list of selected property file paths, - a list of corresponding image file paths.