MeshSpec

class hrtfpykit.datasets.MeshSpec(path=None, extensions=None, transform=None, name=None)

Define subject mesh paths returned by a dataset sample.

MeshSpec asks a dataset to include the mesh resource associated with each selected subject. Mesh files require the active dataset configuration to declare a mesh resource pattern. The optional path argument only changes the root where that pattern is searched. It does not define mesh filenames by itself. The dataset formats mesh filenames from the configured mesh pattern, subject IDs, subject numbers, and selected mesh variant, so mesh values remain aligned with the other resource families.

path is a mesh root override. When path is None, mesh files are searched from the dataset root using the active mesh configuration. When path is provided, absolute paths are used directly and relative paths are resolved from the dataset root. The configured mesh pattern is then applied below that root. If the dataset does not declare mesh resources, MeshSpec cannot resolve meshes from path alone. If several mesh specs are requested, the first mesh spec controls the mesh root and extension scan used for the resource family.

If the spec is passed to inputs, its value appears under dataset[0]["inputs"][name]. If it is passed to target, its value appears under dataset[0]["target"][name]. When name is None, the default key is "mesh". By default, the returned value is a str path. The mesh file is not parsed by hrtfpykit unless transform is provided, in which case the returned type is whatever the transform returns.

Returning paths by default is intentional. hrtfpykit organizes the mesh resources and keeps the subject alignment, while the user decides how the mesh should be opened, parsed, preprocessed, or converted for a particular experiment. The transform callable is the hook for that custom mesh pipeline.

Mesh specs affect subject availability. When a mesh spec is requested, subjects without a matching mesh file are removed before rows are built.

Notes

Dataset-specific mesh variants, default folders, and file naming rules are documented by the concrete dataset integration. This spec only declares that a mesh value is required and how the selected path or transformed value should be returned.

Parameters:

  • path (str, Path, or None, default=None) – Optional mesh root override. None uses the active dataset mesh configuration. Absolute paths are used directly. Relative paths are resolved from the dataset root. The selected dataset mesh filename pattern is still required and is applied below the selected root.

  • extensions (tuple of str or None, default=None) – Optional mesh extensions to search.

  • transform (callable or None, default=None) – Optional transform applied to the selected mesh path string. Use it to define how the mesh resource should be opened, preprocessed, or converted before it is returned in the sample.

  • name (str or None, default=None) – Optional public key used in sample dictionaries.

Returns:

Specification object consumed by dataset construction.

Return type:

MeshSpec

Examples

>>> from pathlib import Path
>>> from hrtfpykit.datasets import HUTUBS, MeshSpec
>>> dataset = HUTUBS(root="datasets/hutubs", inputs=MeshSpec(name="mesh"))
>>> mesh_path = dataset[0]["inputs"]["mesh"]
>>> print(type(mesh_path).__name__)
str
>>> print(Path(mesh_path).suffix)
.ply