Python API reference

This is the complete reference of the Python API of HELIOS++.

Surveys and legs

class helios.Survey

The main class representing the survey. It combines all the information about the survey, including the scanner, platform. Legs can be added using the add_leg method. The survey can be executed using the run method.

Parameters:

scanner (Scanner) – The scanner to use for the survey.
platform (Platform) – The platform to use for the survey.
scene (StaticScene) – The scene to use for the survey.
legs (Tuple[Leg, ...]) – The legs to use for the survey. Legs can also be added using the add_leg method.
name (str) – The name of the survey.
gps_time (datetime) – The GPS start time for the survey. If none is specified, the current time will be used.
full_waveform_settings (FullWaveformSettings) – The settings for the full waveform recording. If none is specified, the default settings will be used.

add_leg(leg: helios.leg.Leg | None = None, platform_settings: helios.platforms.PlatformSettings | None = None, scanner_settings: helios.scanner.ScannerSettings | None = None, trajectory_settings: helios.platforms.TrajectorySettings | None = None, **parameters)

Add a new leg to the survey.

It can either be already constructed or it will be constructed from the provided settings.

The settings can be provided as class instances or directly as the individual parameters of those classes.

Parameters:

leg (Optional[Leg]) – The leg to add. If none is specified, a leg will be constructed from the provided settings.
platform_settings (Optional[PlatformSettings]) – The settings for the platform for this leg.
scanner_settings (Optional[ScannerSettings]) – The settings for the scanner for this leg.
trajectory_settings (Optional[TrajectorySettings]) – The settings for the trajectory for this leg.

from_xml(survey_file: helios.validation.AssetPath)

Construct the survey object from an XML file.

Parameters:: survey_file (AssetPath) – The path to the XML file containing the survey definition. The XML file should conform to the schema defined in “xsd/survey.xsd”.

full_waveform_settings: helios.settings.FullWaveformSettings

gps_time: datetime.datetime

legs: Tuple[helios.leg.Leg, Ellipsis] = ()

name: str = ''

platform: helios.platforms.Platform

run(execution_settings: helios.settings.ExecutionSettings | None = None, output_settings: helios.settings.OutputSettings | None = None, callbacks: Sequence[helios.callbacks.SurveyHook] | None = None, live: bool | helios.live.LiveViewer = False, **parameters)

Run the survey with the given execution and output settings. The settings can be provided as class instances or directly as the individual parameters of those classes.

Parameters:

execution_settings (Optional[ExecutionSettings]) – The execution settings to use for the survey.
output_settings (Optional[OutputSettings]) – The output settings to use for the survey.
callbacks (Optional[Sequence[SurveyHook]]) – The callbacks to use for the survey execution.
live (bool | LiveViewer) – Whether to use a live viewer for the survey execution. If True, a LiveViewer instance will be created and used. If False, no live viewer will be used. If a LiveViewer instance is provided, it will be used.
parameters – Individual parameters to set on the execution and output settings. These will override the settings provided in the execution_settings and output_settings parameters.

scanner: helios.scanner.Scanner

scene: helios.scene.StaticScene

class helios.Leg

Class representing a leg of a survey. A leg is a combination of platform settings (defining the platform position and, if moving, the speed), scanner settings and trajectory settings. It represents a single segment of a survey where the platform and scanner settings are constant. In the waypoint mode, the leg will be defined by a single or by a start and end waypoint. For interpolated trajectories, the leg will be defined by the trajectory.

Parameters:

platform_settings – The settings for the platform for this leg. See PlatformSettings for an overview of the available options.
scanner_settings – The settings for the scanner for this leg. See ScannerSettings for an overview of the available options.
trajectory_settings – The settings for the trajectory for this leg. See TrajectorySettings for an overview of the available options.

platform_settings: helios.platforms.PlatformSettingsBase

scanner_settings: helios.scanner.ScannerSettingsBase

trajectory_settings: helios.platforms.TrajectorySettings | None

Scanner and scanner settings

class helios.Scanner

Base class for validated objects in Helios++.

from_xml(scanner_file: helios.validation.AssetPath, scanner_id: str = '')

Classmethod to load a scanner from an XML file. The XML file should conform to the schema defined in “xsd/scanner.xsd”. The scanner_id parameter can be used to specify which scanner to load if the XML file contains multiple scanners. The method validates the XML file against the schema before loading the scanner.

Parameters:

scanner_file (AssetPath) – The path to the XML file containing the scanner definition.
scanner_id (str) – The ID of the scanner to load from the XML file.

class helios.ScannerSettings

Class representing the settings for a scanner. These can be set for each leg of a survey.

Parameters:

is_active (bool) – Whether the scanner is active during the leg. If false, no points will be recorded during this leg.
head_rotation (AngleVelocity) – The rotation speed of the scanner head in radians per second. For scanners with rotating head.
rotation_start_angle (Angle) – The start angle of the scanner head rotation in radians. For scanners with rotating head.
rotation_stop_angle (Angle) – The stop angle of the scanner head rotation in radians. For scanners with rotating head.
pulse_frequency (Frequency) – The pulse frequency of the scanner in Hz.
scan_angle (Angle) – The scan angle of the scanner in radians. May be ignored for some scanner types (e.g. optics = risley).
min_vertical_angle (Angle) – The minimum vertical angle of the scanner in radians. To be used to define the scan angle for TLS scanners (with non-symmetrical field of view).
max_vertical_angle (Angle) – The maximum vertical angle of the scanner in radians. To be used to define the scan angle for TLS scanners (with non-symmetrical field of view).
scan_frequency (Frequency) – The scan frequency of the scanner in Hz.
beam_divergence_angle (Angle) – The beam divergence angle of the scanner in radians.
trajectory_time_interval (TimeInterval) – The time interval in seconds at which the trajectory points are written.
vertical_resolution (Angle) – The vertical resolution of the scanner in radians. To be used for TLS with rotating optics and rotating head.
horizontal_resolution (Angle) – The horizontal resolution of the scanner in radians. To be used for TLS with rotating optics and rotating head.
max_duration (TimeInterval) – The maximum simulated duration of the leg in seconds.
optics_warmup_phase (TimeInterval) – The simulated optics warmup phase in seconds before the first pulse.

beam_divergence_angle: helios.validation.Angle

head_rotation: helios.validation.AngleVelocity = 0

horizontal_resolution: helios.validation.Angle = 0

is_active: bool = True

max_duration: helios.validation.TimeInterval = 0

max_vertical_angle: helios.validation.Angle

min_vertical_angle: helios.validation.Angle

optics_warmup_phase: helios.validation.TimeInterval = 0

pulse_frequency: helios.validation.Frequency = 300000

rotation_start_angle: helios.validation.Angle = 0

rotation_stop_angle: helios.validation.Angle = 0

scan_angle: helios.validation.Angle = 0

scan_frequency: helios.validation.ScanFrequency = 200

trajectory_time_interval: helios.validation.TimeInterval = 0.01

vertical_resolution: helios.validation.Angle = 0

helios.list_scanners() → list[str]

List all predefined scanner names.

Returns:: A list of all predefined scanner names that can be used to create scanners with scanner_from_name().
Return type:: list[str]

helios.scanner_from_name(scanner_name: str) → Scanner: Create a predefined scanner by its string name.

Platform, platform settings and trajectories

class helios.Platform

Base class for validated objects in Helios++.

from_xml(platform_file: helios.validation.AssetPath, platform_id: str = ''): Classmethod to load a platform from an XML file. The XML file should conform to the schema defined in “xsd/platform.xsd”. The platform_id parameter can be used to specify which platform to load if the XML file contains multiple platforms.

load_interpolate_platform(trajectory: numpydantic.NDArray, platform_file: helios.validation.AssetPath, platform_id: str = '', interpolation_method: Literal['CANONICAL', 'ARINC 705'] = 'ARINC 705', sync_gps_time: bool = False, is_roll_pitch_yaw_in_radians: bool = True)

Load a platform from an XML file with interpolation enabled.

Args:: trajectory: 1-D structured NumPy array of shape (n,). platform_file: File path to platform XML file. platform_id: ID of desired platform. interpolation_method: Interpolation method to use. Options are “CANONICAL” and “ARINC 705”. sync_gps_time: Whether to sync GPS time with platform’s start time. is_roll_pitch_yaw_in_radians: Whether roll, pitch, and yaw in the trajectory are in radians.

platform_settings: PlatformSettings | None = None

class helios.PlatformSettings

Base class for validated objects in Helios++.

do_force_on_ground(scene: helios.scene.StaticScene)

Move waypoint z coordinate to ground level

Parameters:: scene (StaticScene) – The scene to query for the ground level.

x: float = 0

y: float = 0

z: float = 0

class helios.StaticPlatformSettings

Base class for validated objects in Helios++.

force_on_ground: bool = False

x: float = 0

y: float = 0

z: float = 0

class helios.DynamicPlatformSettings

Base class for validated objects in Helios++.

speed_m_s: Annotated[float, Field(ge=0)] = 70

trajectory_settings: TrajectorySettings

class helios.TrajectorySettings

Class representing the settings for a trajectory. These can be set for each leg of a survey and are applied to the trajectory loaded in the Platform instance

Parameters:

start_time – The time in seconds at which the trajectory starts. This is used to select a subset of the trajectory to be used for the leg by GPS time.
end_time – The time in seconds at which the trajectory ends. This is used to select a subset of the trajectory to be used for the leg by GPS time.
teleport_to_start – Whether to teleport to the start of the trajectory at the beginning of the leg. If false, the platform will start at the position of the end of the previous leg. If true, the platform will be teleported to the start of the trajectory at the beginning of the leg.

end_time: float = 0

start_time: float = 0

teleport_to_start: bool = False

helios.load_traj_csv(csv: helios.validation.AssetPath, tIndex: Annotated[int, Field(strict=True, ge=0, le=6)] = 0, rollIndex: Annotated[int, Field(strict=True, ge=0, le=6)] = 1, pitchIndex: Annotated[int, Field(strict=True, ge=0, le=6)] = 2, yawIndex: Annotated[int, Field(strict=True, ge=0, le=6)] = 3, xIndex: Annotated[int, Field(strict=True, ge=0, le=6)] = 4, yIndex: Annotated[int, Field(strict=True, ge=0, le=6)] = 5, zIndex: Annotated[int, Field(strict=True, ge=0, le=6)] = 6, trajectory_separator: Annotated[str, Field(strict=True, min_length=1, max_length=1)] = ',', rpy_in_radians: bool = False)

Load a csv trajectory from a file.

The parameters define how the csv is parsed. All the ..Index parameters define the column order of the csv.

Parameters:

csv (AssetPath) – File path to csv to load.
tIndex (int) – Column number of time field
xIndex (int) – Column number of x coordinates
yIndex (int) – Column number of y coordinates
zIndex (int) – Column number of z coordinates
rollIndex (int) – Column number of roll
pitchIndex (int) – Column number of pitch
yawIndex (int) – Column number of yaw
trajectory_separator (str) – Char which separates columns.
rpy_in_radians (bool) – Whether roll, pitch, and yaw in the csv are in radians. If false, they are assumed to be in degrees and will be converted to radians.

Returns:

A structured numpy array with fields ‘t’, ‘x’, ‘y’, ‘z’, ‘roll’, ‘pitch’, ‘yaw’. ‘roll’, ‘pitch’, and ‘yaw’ are in radians.

helios.list_platforms() → list[str]

List all predefined platform names.

Returns:: A list of all predefined platform names that can be used to create platforms with platform_from_name().
Return type:: list[str]

helios.platform_from_name(platform_name: str) → Platform

Create a predefined platform by its string name.

Parameters:: platform_name (str) – The name of the predefined platform to create. Use list_platforms() to see all available platforms.
Returns:: The created platform instance.
Return type:: Platform

Scene

class helios.StaticScene

Class representing a static scene. A scene is composed of multiple scene parts, which can be transformed independently and have different materials.

Parameters:: scene_parts (Tuple[ScenePart, ...]) – The scene parts that make up the scene.

add_scene_part(scene_part: ScenePart)

Add a scene part to the scene.

Parameters:: scene_part (ScenePart) – The scene part to add to the scene.

property bbox: BoundingBox: The axis-aligned bounding box of the scene.

from_binary(binary_file: helios.validation.AssetPath)

Load the scene from a binary file.

Parameters:: binary_file (AssetPath) – The path to the binary file to load the scene from.

from_xml(scene_file: helios.validation.AssetPath)

Load the scene from an XML file.

Parameters:: scene_file (AssetPath) – The path to the XML file to load the scene from.

scene_parts: Tuple[ScenePart, Ellipsis] = ()

to_binary(binary_file: pathlib.Path, compression_level: helios.validation.CompressionLevel = 6)

Save the scene to a binary file.

Parameters:

binary_file (Path) – The path to the binary file to save the scene to.
compression_level (CompressionLevel) – The compression level to use for the binary file.

class helios.ScenePart

Class representing a part of the scene. A scene part is a collection of primitives that share the same material and that is typically loaded from one file. A scene can be composed of multiple scene parts, which can be transformed independently and have different materials. Scene parts can be loaded from .obj, .tiff, .xyz and .vox files.

Parameters:: force_on_ground (Union[ForceOnGroundStrategy, PositiveInt]) – The strategy to use for forcing the scene part on the ground. This is used to position legs with ‘force_on_ground’ strategy on the ground level of the scene.

property bbox: BoundingBox: The axis-aligned bounding box of the scene part.

force_on_ground: helios.settings.ForceOnGroundStrategy | pydantic.PositiveInt

from_numpy_array(points: numpydantic.NDArray, voxel_size: pydantic.PositiveFloat, *, normals_file_columns: list[pydantic.NonNegativeInt] | None = None, rgb_file_columns: list[pydantic.NonNegativeInt] | None = None, max_color_value: pydantic.NonNegativeFloat = 0.0, default_normal: helios.validation.R3Vector = np.array([np.finfo(np.float64).max] * 3, dtype=np.float64), sparse: bool = True, estimate_normals: bool = False, snap_neighbor_normal: bool = False): Load the scene part from a numpy array.

from_obj(obj_file: helios.validation.AssetPath, up_axis: Literal['y', 'z'] = 'z')

Load the scene part from an OBJ file.

For paths (potentially) containing wildcards, use ‘ScenePart.from_objs()’ instead!

Parameters:

obj_file (AssetPath) – The path to the OBJ file to load the scene part from. Can potentially contain wildcards (‘*’).
up_axis (Literal["y", "z"]) – The up axis to use for the loaded scene part.

Returns:

The loaded scene part.

Return type:

ScenePart

from_objs(obj_files: helios.validation.MultiAssetPath, up_axis: Literal['y', 'z'] = 'z')

Load multiple scene parts from OBJ files

Expects a single Path containing some (or none) wildcards (‘*’). Supports ‘**’ for matching multiple directories.

Parameters:

obj_files (MultiAssetPath) – The path to the OBJ files to load the scene parts from. Can potentially contain wildcards (‘*’).
up_axis (Literal["y", "z"]) – The up axis to use for the loaded scene parts.

Returns:

The loaded scene parts.

Return type:

list[ScenePart]

from_open3d(geometry, **kwargs)

Load the scene part from an Open3D geometry. The geometry can be either an open3d.geometry.TriangleMesh or an open3d.geometry.PointCloud. In case of a triangle mesh, the behaviour is similar to ‘ScenePart.from_obj()’, in case of a point cloud, the behaviour is similar to ‘ScenePart.from_xyz()’ and the provided point cloud data will be voxelized. See below for the specific additional parameters that can be provided for each geometry type.

Parameters:

geometry (open3d.geometry.TriangleMesh | open3d.geometry.PointCloud) – The Open3D geometry to load the scene part from.
kwargs – Additional parameters to use for loading the scene part, depending on the provided geometry: a) for open3d.geometry.TriangleMesh: up_axis; b) for open3d.geometry.PointCloud: voxel_size, max_color_value, default_normal, sparse, estimate_normals, snap_neighbor_normal

Returns:

The loaded scene part.

Return type:

ScenePart

from_tiff(tiff_file: helios.validation.AssetPath)

Load the scene part from a TIFF file.

For paths (potentially) containing wildcards, use ‘ScenePart.from_tiffs()’ instead!

Parameters:: tiff_file (AssetPath) – The path to the TIFF file to load the scene part from.
Returns:: The loaded scene part.
Return type:: ScenePart

from_tiffs(tiff_files: helios.validation.MultiAssetPath)

Load multiple scene parts from TIFF files

Expects a single Path containing some (or none) wildcards (‘*’). Supports ‘**’ for matching multiple directories.

Parameters:: tiff_files (MultiAssetPath) – The path to the TIFF files to load the scene parts from. Can potentially contain wildcards (‘*’).
Returns:: The loaded scene parts.
Return type:: list[ScenePart]
Returns:: The loaded scene parts.
Return type:: list[ScenePart]

from_vox(vox_file: helios.validation.AssetPath, intersection_mode: Literal['scaled', 'fixed', 'transmittive'] = 'transmittive', intersection_argument: float | None = None, random_shift: bool = False, ladlut_path: str | None = None)

Load the scene part from a VOX file.

Parameters:

vox_file (AssetPath) – The path to the VOX file to load the scene part from.
intersection_mode (Literal["scaled", "fixed", "transmittive"]) – The mode to use for calculating the intersection of rays with the voxels [‘transmittive’, ‘fixed’, ‘scaled’].
intersection_argument (Optional[float]) – Scaling factor; only used for intersection mode ‘scaled’.
random_shift (bool) – Whether to apply a random shift to the scaled cubes within the original voxel resolution; only used for intersection mode ‘scaled’.
ladlut_path (Optional[str]) – The path to the txt file with look-up-tables (LUTs) for custom leaf angle distributions (LADs). See data/lut for examples.

Returns:

The loaded scene part.

Return type:

ScenePart

from_xml(scene_part_file: helios.validation.AssetPath, id: int)

from_xyz(xyz_file: helios.validation.AssetPath, voxel_size: pydantic.PositiveFloat, separator: str | None = None, max_color_value: pydantic.NonNegativeFloat = 0.0, default_normal: helios.validation.R3Vector = np.array([np.finfo(np.float64).max] * 3, dtype=np.float64), sparse: bool = True, estimate_normals: bool = False, normals_file_columns: list[pydantic.NonNegativeInt] = [3, 4, 5], rgb_file_columns: list[pydantic.NonNegativeInt] = [6, 7, 8], snap_neighbor_normal: bool = False)

Load the scene part from an XYZ file.

Parameters:

xyz_file (AssetPath) – The path to the XYZ file to load the scene part from. Can potentially contain wildcards (‘*’).
voxel_size (PositiveFloat) – The voxel size to use for voxelizing the XYZ point cloud so that it can be converted to a 3D model with surfaces that can be scanned.
separator (Optional[str]) – The separator used in the XYZ file. If not provided, the separator will be automatically detected.
max_color_value (NonNegativeFloat) – The maximum color value used for normalizing RGB values in the XYZ file.
default_normal (R3Vector) – The default normal to use for points in the XYZ file that do not have a normal.
sparse (bool) – Whether to use a sparse voxel grid for the conversion of the XYZ point cloud to a 3D model. If false, a dense voxel grid will be used, which can lead to higher memory usage.
estimate_normals (bool) – Whether to estimate normals for points in the XYZ file that do not have a normal. This can be used if the XYZ file does not contain normals or if the provided normals are not reliable.
normals_file_columns (list[NonNegativeInt]) – The columns in the XYZ file to use for the normal components if the XYZ file contains normals. The default is [3, 4, 5].
rgb_file_columns (list[NonNegativeInt]) – The columns in the XYZ file to use for the RGB components if the XYZ file contains RGB values. The default is [6, 7, 8].
snap_neighbor_normal (bool) – Whether to snap the normal of points in the XYZ file that do not have a normal to the normal of their nearest neighbor that has a normal.

Returns:

The loaded scene part.

Return type:

ScenePart

from_xyzs(xyz_files: helios.validation.MultiAssetPath, voxel_size: pydantic.PositiveFloat, separator: str | None = None, max_color_value: pydantic.NonNegativeFloat = 0.0, default_normal: helios.validation.R3Vector = np.array([np.finfo(np.float64).max] * 3, dtype=np.float64), sparse: bool = False, estimate_normals: bool = False, normals_file_columns: list[pydantic.NonNegativeInt] = [3, 4, 5], rgb_file_columns: list[pydantic.NonNegativeInt] = [6, 7, 8], snap_neighbor_normal: bool = False)

Load multiple scene parts from XYZ files.

Expects a single Path containing some (or none) wildcards (‘*’). Supports ‘**’ for matching multiple directories.

Each parameters should be a single shared value for all files.

Parameters:

xyz_file (AssetPath) – The path to the XYZ file to load the scene part from. Can potentially contain wildcards (‘*’).
voxel_size (PositiveFloat) – The voxel size to use for voxelizing the XYZ point cloud so that it can be converted to a 3D model with surfaces that can be scanned.
separator (Optional[str]) – The separator used in the XYZ file.
max_color_value (NonNegativeFloat) – The maximum color value used for normalizing RGB values in the XYZ file.
default_normal (R3Vector) – The default normal to use for points in the XYZ file that do not have a normal.
sparse (bool) – Whether to use a sparse voxel grid for the conversion of the XYZ point cloud to a 3D model. If false, a dense voxel grid will be used, which can lead to higher memory usage.
estimate_normals (bool) – Whether to estimate normals for points in the XYZ file that do not have a normal. This can be used if the XYZ file does not contain normals or if the provided normals are not reliable.
normals_file_columns (list[NonNegativeInt]) – The columns in the XYZ file to use for the normal components if the XYZ file contains normals. The default is [3, 4, 5].
rgb_file_columns (list[NonNegativeInt]) – The columns in the XYZ file to use for the RGB components if the XYZ file contains RGB values. The default is [6, 7, 8].
snap_neighbor_normal (bool) – Whether to snap the normal of points in the XYZ file that do not have a normal to the normal of their nearest neighbor that has a normal.

Returns:

The loaded scene parts.

Return type:

list[ScenePart]

property materials: MaterialDict

Dictionary-like access to materials in the scene part.

Returns:: A dictionary-like object for accessing and modifying materials in the scene part via their names.
Return type:: MaterialDict

rotate(quaternion: helios.validation.Quaternion | None = None, axis: helios.validation.R3Vector | None = None, angle: helios.validation.Angle | None = None, from_axis: helios.validation.R3Vector | None = None, to_axis: helios.validation.R3Vector | None = None, rotation_center: helios.validation.R3Vector | None = None)

Rotate the scene part.

The rotation can be specified as one of the following parameters:

A quaternion
An axis and an angle
An origin and an image vector

Optionally, you may specify a rotation center. If omitted the origin of the coordinate system of the scene part will be used.

Parameters:

quaternion (Optional[Quaternion]) – The quaternion to use for the rotation.
axis – The axis to use for the rotation. Must be provided together with the ‘angle’ parameter.
angle – The angle to use for the rotation. Must be provided together with the ‘axis’ parameter.
from_axis – The origin vector to use for the rotation. Must be provided together with the ‘to_axis’ parameter.
to_axis – The image vector to use for the rotation. Must be provided together with the ‘from_axis’ parameter.
rotation_center – The center to use for the rotation. If omitted, the origin of the coordinate system of the scene part will be used.

scale(factor: pydantic.PositiveFloat)

Scale the scene part by a factor.

Parameters:: factor (PositiveFloat) – The factor to scale the scene part by.

translate(offset: helios.validation.R3Vector)

Translate the scene part by an offset.

Parameters:: offset (R3Vector) – The offset to translate the scene part by.

update_material(material: Material, indices: list[int] | None = None, range_start: int | None = None, range_stop: int | None = None)

Update material(s) for the scene part.

It can be provided in one of the following ways:

‘indices’: a list of specific primitive indices to update
‘range_start’ & ‘range_stop’: an index range to update

If neither is provided, the material will be applied to all primitives.

Parameters:

material (Material) – The material to apply to the scene part.
indices (Optional[list[int]]) – A list of specific primitive indices to update.
range_start (Optional[int]) – The start of the range of indices to update.
range_stop (Optional[int]) – The end of the range of indices to update.

class helios.scene.Material

Class representing a material that can be applied to primitives in a scene part. A material defines the visual properties of the primitives, such as their color and reflectance, but also helios-specific properties such as the classification and whether the scene part should be considered as ground.

Parameters:

name (str) – The name of the material. This is used to reference the material when applying it to primitives in a scene part.
is_ground (bool) – Whether the material should be considered as ground. This is used to position legs with ‘force_on_ground’ strategy on the ground level of the scene.
spectra (str) – The name of the spectra file to use for the material. The spectra file should be located in one of the asset directories.
reflectance (float) – The reflectance of the material. This is used in the intensity calculation for returns on the respective scene parts.
specularity (float) – The specularity of the material. This is used in the intensity calculation for returns on the respective scene parts.
specular_exponent (float) – The specular exponent of the material. This is used in the intensity calculation for returns on the respective scene parts.
classification (int) – The classification of the material. This is used to assign a classification value to points that hit the respective scene parts.
ambient_components (NDArray[Shape["4"], np.float64]) – The ambient components of the material. In .mtl files, this is the Ka component. This is used in the intensity calculation for returns on the respective scene parts.
diffuse_components (NDArray[Shape["4"], np.float64]) – The diffuse components of the material. In .mtl files, this is the Kd component. This is used in the intensity calculation for returns on the respective scene parts.
specular_components (NDArray[Shape["4"], np.float64]) – The specular components of the material. In .mtl files, this is the Ks component. This is used in the intensity calculation for returns on the respective scene parts.

ambient_components: numpydantic.NDArray[numpydantic.Shape[4], numpy.float64]

classification: int = 0

diffuse_components: numpydantic.NDArray[numpydantic.Shape[4], numpy.float64]

classmethod from_file(material_file: helios.validation.AssetPath, material_id: str = '')

is_ground: bool = False

name: str = ''

reflectance: float

spectra: str = ''

specular_components: numpydantic.NDArray[numpydantic.Shape[4], numpy.float64]

specular_exponent: float = 10

specularity: float = 0

class helios.ForceOnGroundStrategy

Enum representing the strategy to use for forcing points on the ground.

LEAST_COMPLEX = 1: Use the minimum z vertex to calculate ground translation. Least computationally accurate.

MOST_COMPLEX = -1: Force on ground with optimum vertex (the one which is closest to the ground plane). Optimum solution guaranteed, but computationally expensive.

NONE = 0: Do not force points on the ground.

class helios.scene.MaterialDict(owner: ScenePart)

A dictionary-like interface for accessing and modifying materials via their names.

items(): D.items() -> a set-like object providing a view on D’s items

keys(): D.keys() -> a set-like object providing a view on D’s keys

values(): D.values() -> an object providing a view on D’s values

class helios.scene.BoundingBox

Class representing an axis-aligned bounding box. Used for representing the bounds of scene parts and scenes.

property bounds: tuple[helios.validation.R3Vector, helios.validation.R3Vector]: The lower left and upper right corner of the bounding box.

property centroid: helios.validation.R3Vector: The centroid of the bounding box.

Settings

class helios.ExecutionSettings

Class representing the execution settings for a HELIOS++ survey.

Parameters:

parallelization (ParallelizationStrategy) – The parallelization strategy to use for processing the survey.
num_threads (Optional[ThreadCount]) – The number of threads to use for processing the survey. If None, the number of hardware threads will be used.
chunk_size (PositiveInt) – The chunk size to use for processing the survey. Only used if the parallelization strategy is set to CHUNK.
warehouse_factor (PositiveInt) – The warehouse factor to use for processing the survey. Only used if the parallelization strategy is set to WAREHOUSE.
log_file (bool) – Whether to write a log file for the survey. If true, a log file will be written to the output directory.
log_file_only (bool) – Whether to write only a log file for the survey. If true, no logging output will be written to the console.
verbosity (LogVerbosity) – The logging verbosity level to use for processing the survey.
factory_type (KDTreeFactoryType) – The type of KDTree factory to use for building the KDTree.
kdt_num_threads (Optional[ThreadCount]) – The number of threads to use for building the KDTree. If None, the number of hardware threads will be used.
kdt_geom_num_threads (Optional[ThreadCount]) – The number of threads to use for building the geometry of the KDTree. If None, the number of hardware threads will be used.
sah_nodes (PositiveInt) – The number of nodes to use for the SAH approximation. Only used if the factory type is set to SAH_APPROXIMATION.
discard_shutdown (bool) – Whether to discard the shutdown message when the survey is finished.

chunk_size: pydantic.PositiveInt = 32

discard_shutdown: bool = True

factory_type: KDTreeFactoryType

kdt_geom_num_threads: helios.validation.ThreadCount = None

kdt_num_threads: helios.validation.ThreadCount = None

log_file: bool = False

log_file_only: bool = False

num_threads: helios.validation.ThreadCount = None

parallelization: ParallelizationStrategy

progressbar: ProgressBarStrategy

sah_nodes: pydantic.PositiveInt = 32

verbosity: LogVerbosity

warehouse_factor: pydantic.PositiveInt = 4

class helios.OutputSettings

Class representing the output settings for a HELIOS++ survey.

Parameters:

format (OutputFormat) – The output format to use for writing the point clouds.
split_by_channel (bool) – Whether to split the output point clouds by channel.
output_dir (CreatedDirectory) – The output directory to write the point clouds to.
write_waveform (bool) – Whether to write the waveform data for the points.
write_pulse (bool) – Whether to write the pulse data for the points.
las_scale (Length) – The scale to use for writing LAS files. Only used if the output format is set to LAS or LAZ.

format: OutputFormat

las_scale: helios.validation.Length = 0.0001

output_dir: helios.validation.CreatedDirectory = 'output'

split_by_channel: bool = False

write_pulse: bool = False

write_waveform: bool = False

class helios.OutputFormat

Enum representing the output format to use for writing the point clouds.

LAS = 'las': LAS format (v1.4).

LASPY = 'laspy': laspy format

LAZ = 'laz': LAZ format (v1.4, compressed).

NPY = 'npy': Structured numpy array with fields for x, y, z coordinates and additional attributes.

XYZ = 'xyz': Plain text format with x, y, z coordinates and additional attributes as columns.

class helios.FullWaveformSettings

Class representing the settings for full waveform processing.

Parameters:

bin_size (TimeInterval) – The size of the bins to use for full waveform processing in seconds. Default is 0.25 ns.
beam_sample_quality (PositiveInt) – The beam sample quality to use for full waveform processing. Default is 3.
win_size (TimeInterval) – The size of the window to use for full waveform processing in seconds. Default is 1.0 ns.
max_fullwave_range (TimeInterval) – The maximum range to use for full waveform processing in seconds. Default is 0.0 ns (no maximum range).

beam_sample_quality: pydantic.PositiveInt = 3

bin_size: helios.validation.TimeInterval

max_fullwave_range: helios.validation.TimeInterval

win_size: helios.validation.TimeInterval

class helios.LogVerbosity

Enum representing the logging verbosity level to use for processing the survey.

DEFAULT = 56: Default logging level.

QUIET = 32: Only error messages will be logged.

SILENT = 0: No logging output will be produced.

TIME = 40: Log timing information.

VERBOSE = 60: Verbose logging output.

VERY_VERBOSE = 63: Very verbose logging output.

apply() → None

class helios.ParallelizationStrategy

Enum representing the parallelization strategy to use for processing the survey.

CHUNK = 0: chunk

WAREHOUSE = 1: warehouse

class helios.KDTreeFactoryType

Enum representing the type of KDTree factory to use for building the KDTree.

SAH = 2: Surface Area Heuristic (SAH) based KDTree

SAH_APPROXIMATION = 4: fast approximation of SAH based KDTree (default)

SAH_BEST_AXIS = 3: SAH based KDTree with best axis criteria

SIMPLE = 1: Simple KDTree based on median balancing

Utils

helios.add_asset_directory(directory: pathlib.Path) → _AssetDirectoryRegistration

Add a directory to the list of directories that will be searched for assets.

Parameters:: directory (Path) – The directory to add.

helios.combine_parameters(groups: None | list[list[str]] = None, **parameters)

Combine parameter spaces for parameter studies.

This function allows to define lists of possible values for different parameters and to combine them in complex ways to generate a list of parameter dicionaries. Arbitrary parameters can be passed as keyword arguments. Parameter values may be lists to define a set of possible values for that parameter, but they don’t have to.

There is two ways of combining two parameter ranges: Either the cartesian product of possibilities can be generated or the two ranges can be zipped. The function allows both methods and arbirtrary combinations there of. The combination behaviour is controlled by the groups parameter, which accepts a list of lists that define groups that should be zipped together.

Parameter values of type string may contain Python string formatting syntax. This way, they can reference other parameters in the resulting parameter dictionary and interpolate their values.

Parameters:

groups (Union[None, list[list[str]]]) – The list of groups that should be zipped instead of generating the cartesian product. Each group is a list of parameter names. Passing None will result in each parameter forming its own group and cartesian products being generated. This is the default behaviour.
parameters (dict) – The actual parameters given as keyword arguments. Values can either be single values or lists of possible values.

Returns:

A list of dictionaries where each dictionary represents a unique combination of the parameters.

Return type:

list[dict]

Raises:

ValueError – If any parameter within a group is not iterable or if the lengths of the iterables within a group varies.

helios.utils.set_rng_seed(seed: int | datetime.datetime = datetime.now(timezone.utc)) → None

Set the seed of the random number generator.

Parameters:: seed (Union[int, datetime]) – The seed to set. Can be an integer or a datetime object.

Validation

class helios.validation.Model

Base class for validated objects in Helios++.

clone(): Create a deep copy of the object

classmethod from_bundle(path: pathlib.Path, filename: pathlib.Path | None = None)

Load a model instance from a serialized bundle directory.

Parameters

pathPath: Bundle directory path.
filenameOptional[Path], optional: Relative path to the root YAML file within the bundle. If omitted, the class default serialization filename is used.

Returns

Model: Deserialized instance of cls.

classmethod from_yaml(path: pathlib.Path)

Load an instance of this model class from a YAML file.

Parameters

pathPath: Path to a serialized YAML document.

Returns

Model: Deserialized instance of cls.

to_bundle(path: pathlib.Path, binary: bool = False, force: bool = False)

Serialize this model into a relocatable directory bundle.

Parameters

pathPath: Target bundle directory.
binarybool, optional: If True, use binary sidecar serialization where supported.
forcebool, optional: If True, clear an existing non-empty bundle directory.

Returns

Path: Path to the root YAML file inside the bundle.

to_yaml(path: pathlib.Path, shallow: bool = False)

Serialize this model instance to YAML.

Parameters

pathPath: Destination YAML file path or destination directory.
shallowbool, optional: If True, nested models are serialized into separate files and linked by references. If False (default), nested models are inlined.

Returns

Path: Path to the generated root YAML file.