artist.data_parser.paint_scenario_parser

Attributes

log

A logger for the paint data loader.

Functions

`extract_paint_tower_measurements`(...)	Extract tower data from a `PAINT` tower measurements file for scenario generation.
`extract_paint_heliostat_properties`(...)	Extract heliostat properties from paint.
`extract_paint_deflectometry_data`(...)	Extract paint deflectometry data.
`_ideal_surface_generator`(...)	Generate a surface configuration for an ideal heliostat.
`_fitted_surface_generator`(...)	Generate a surface configuration for a fitted heliostat.
`_process_heliostats_from_paths`(...)	Process heliostat properties from file paths.
`extract_paint_heliostats_ideal_surface`(, device, ...)	Extract heliostat data with ideal surfaces from `PAINT` heliostat properties files.
`extract_paint_heliostats_fitted_surface`(, ...)	Extract heliostat data with fitted surfaces from `PAINT` heliostat properties and deflectometry files.
`extract_paint_heliostats_mixed_surface`(, ...)	Extract heliostat data with a mix of ideal and fitted surfaces from PAINT files.
`corner_points_to_plane`(→ tuple[torch.Tensor, torch.Tensor])	Span a plane from corner points.
`build_heliostat_data_mapping`(→ list[tuple[str, ...)	Build a mapping of heliostat names to their calibration property and image files loaded from `PAINT`.

Module Contents

artist.data_parser.paint_scenario_parser.log: A logger for the paint data loader.

artist.data_parser.paint_scenario_parser.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_pathpathlib.Path: The path to the tower measurement file.
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

PowerPlantConfig: The configuration of the power plant.
TargetAreaListConfig: The configuration of the tower target areas.

artist.data_parser.paint_scenario_parser.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_pathpathlib.Path: The path to the heliostat properties file.
power_plant_positiontorch.Tensor: Tensor of shape [3]. The power plant position.
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 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.

artist.data_parser.paint_scenario_parser.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_pathpathlib.Path: The heliostat deflectometry file path.
number_of_facetsint: The number of facets.
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

list[torch.Tensor]: The surface points per facet.
list[torch.Tensor]: The surface normals per facet.

artist.data_parser.paint_scenario_parser._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_tupletuple[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_vectorstorch.Tensor: The translation vectors for each facet. Tensor of shape [number_of_facets, 4].
cantingtorch.Tensor: The canting vectors for each facet. Tensor of shape [number_of_facets, 2, 4].
number_of_nurbs_control_pointstorch.Tensor: The number of NURBS control points. Tensor of shape [2].
devicetorch.device | None: The device to use.
**kwargsAny: Additional keyword arguments, not used by this function but accepted for API compatibility.

Returns

SurfaceConfig: The generated ideal surface configuration object.

artist.data_parser.paint_scenario_parser._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_tupletuple[str, pathlib.Path, pathlib.Path]: A tuple containing the heliostat name, path to the properties file, and path to deflectometry data file.
facet_translation_vectorstorch.Tensor: The translation vectors for each facet. Tensor of shape [number_of_facets, 4].
cantingtorch.Tensor: The canting vectors for each facet. Tensor of shape [number_of_facets, 2, 4].
number_of_nurbs_control_pointstorch.Tensor: The number of NURBS control points. Tensor of shape [2].
devicetorch.device | None: The device to use.
**kwargsAny: 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.

artist.data_parser.paint_scenario_parser._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

pathslist[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_positiontorch.Tensor: The position of the power plant in latitude, longitude and elevation.
number_of_nurbs_control_pointstorch.Tensor: The number of NURBS control points.
surface_config_generatorCallable: A function that generates the surface configuration, either ideal or fitted.
devicetorch.device | None: The device to use.
**kwargsAny: 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.

artist.data_parser.paint_scenario_parser.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

pathslist[tuple[str, pathlib.Path]]: Name of the heliostat and path to the heliostat properties file
power_plant_positiontorch.Tensor: The position of the power plant in latitude, longitude and elevation. Tensor of shape [3].
number_of_nurbs_control_pointstorch.Tensor: The number of NURBS control points in both dimensions (default is torch.tensor([10,10])). Tensor of shape [2].
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

HeliostatListConfig: The configuration of all heliostats in the scenario.
PrototypeConfig: The configuration for a heliostat prototype.

artist.data_parser.paint_scenario_parser.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

pathslist[tuple[str, pathlib.Path, pathlib.Path]]: Name of the heliostat and a pair of heliostat properties and deflectometry file paths.
power_plant_positiontorch.Tensor: The position of the power plant in latitude, longitude and elevation. Tensor of shape [3].
nurbs_fit_optimizertorch.optim.Optimizer: The NURBS fit optimizer.
nurbs_fit_schedulertorch.optim.lr_scheduler.LRScheduler: The NURBS fit learning rate scheduler.
number_of_nurbs_control_pointstorch.Tensor: The number of NURBS control points in both dimensions (default is torch.tensor([10,10])). Tensor of shape [2].
deflectometry_step_sizeint: The step size used to reduce the number of deflectometry points and normals for compute efficiency (default is 100).
nurbs_fit_methodstr: The method used to fit the NURBS, either from deflectometry points or normals (default is config_dictionary.fit_nurbs_from_normals).
nurbs_fit_tolerancefloat: The tolerance value used for fitting NURBS surfaces to deflectometry (default is 1e-10).
nurbs_fit_max_epochint: The maximum number of epochs for the NURBS fit (default is 400).
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

HeliostatListConfig: The configuration of all heliostats in the scenario.
PrototypeConfig: The configuration for a heliostat prototype.

artist.data_parser.paint_scenario_parser.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

pathslist[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_positiontorch.Tensor: The position of the power plant in latitude, longitude, and elevation. Tensor of shape [3].
nurbs_fit_optimizertorch.optim.Optimizer: The NURBS fit optimizer.
nurbs_fit_schedulertorch.optim.lr_scheduler.LRScheduler: The NURBS fit learning rate scheduler.
number_of_nurbs_control_pointstorch.Tensor: The number of NURBS control points in both dimensions (default is torch.tensor([10,10])). Tensor of shape [2].
deflectometry_step_sizeint: The step size used to reduce the number of deflectometry points and normals for compute efficiency (default is 100).
nurbs_fit_methodstr: The method used to fit the NURBS, either from deflectometry points or normals (default is config_dictionary.fit_nurbs_from_normals).
nurbs_fit_tolerancefloat: The tolerance value used for fitting NURBS surfaces to deflectometry (default is 1e-10).
nurbs_fit_max_epochint: The maximum number of epochs for the NURBS fit (default is 400).
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

HeliostatListConfig: The configuration of all heliostats in the scenario.
PrototypeConfig: The configuration for a heliostat prototype. This is always based on an ideal surface.

artist.data_parser.paint_scenario_parser.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_lefttorch.Tensor: The upper left corner coordinate. Tensor of shape [3].
upper_righttorch.Tensor: The upper right corner coordinate. Tensor of shape [3].
lower_lefttorch.Tensor: The lower left corner coordinate. Tensor of shape [3].
lower_righttorch.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.

artist.data_parser.paint_scenario_parser.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_pathstr: Path to the root directory containing heliostat calibration data.
heliostat_nameslist[str]: List of heliostat names to include in the mapping.
number_of_measurementsint: Number of valid calibration samples to retrieve per heliostat.
image_variantstr: Image variant to use. Must match the expected filename suffix (flux, flux-centered, cropped, or raw).
randomizebool: Whether to shuffle the measurement files before selection (default is True).
seedint: 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.