ImageSpec

class hrtfpykit.datasets.ImageSpec(path=None, grouped_by=('subject',), extensions=None, ear_one_hot=False, ear_index=False, concatenate=False, transform=None, name=None)

Define subject image paths or transformed image values.

ImageSpec asks a dataset to index image files by subject, or by subject and ear when images are stored in left and right groups. Image resources can come from a dataset configuration or from a custom folder aligned with the dataset subject IDs, such as photographs, rendered ear views, or other visual information used alongside acoustic targets. The dataset scans the image root, intersects available subjects with the other requested resources, and returns the selected image value in each sample.

path selects the image root used by this resource family. When path is provided, it overrides the image root declared by the active dataset configuration for this spec. Absolute paths are used directly and relative paths are resolved from the dataset root. When path is None, the configured image path is used if the dataset declares one. If neither location is available and an image spec is requested, dataset construction raises an error. If several image specs are requested, the first one controls the image 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 "image".

By default, the returned value is a str path when one file matches the subject key, or a list[str] when multiple files match. The image is not opened by hrtfpykit unless transform is provided. A transform receives each image path and returns the image representation chosen by the user. When concatenate=True, a transform is required and the transformed values are concatenated with numpy.concatenate() along axis 0.

Returning paths by default is intentional. hrtfpykit organizes image files by subject or by subject and ear, while the user decides how images should be opened, resized, normalized, augmented, or converted for a particular experiment. The transform callable is the hook for that custom image pipeline.

Image roots must contain one folder per dataset subject. Subject folders can be named with the canonical dataset subject ID, subjectN, or subject_N. When grouped_by=("subject", "ear"), each subject folder must contain ear folders such as left and right. Files are discovered recursively inside the matched subject or ear folder.

Notes

Image availability and semantic meaning are defined by the dataset or the user-provided resource folder. ImageSpec does not assume a particular imaging protocol; it only defines how files are aligned, grouped, and returned.

Parameters:

  • path (str, Path, or None, default=None) – Optional image root path. None uses the active dataset image configuration when available. Absolute paths are used directly. Relative paths are resolved from the dataset root.

  • grouped_by ({subject} or (subject, ear), default=(subject,)) – Whether images are grouped only by subject or by subject and ear.

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

  • ear_one_hot (bool, default=False) – Whether ear context encodings are exposed in sample inputs.

  • ear_index (bool, default=False) – Whether ear context encodings are exposed in sample inputs.

  • concatenate (bool, default=False) – Whether transformed image values should be concatenated by the value selector.

  • transform (callable or None, default=None) – Optional transform applied to each image path string. Use it to define how each image should be opened, preprocessed, augmented, 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:

ImageSpec

Examples

>>> from pathlib import Path
>>> from hrtfpykit.datasets import HUTUBS, ImageSpec
>>> dataset = HUTUBS(
...     root="datasets/hutubs",
...     inputs=ImageSpec(
...         path="ear_images",
...         grouped_by="subject",
...         name="image",
...     ),
... )
>>> image_value = dataset[0]["inputs"]["image"]
>>> first_image_path = image_value[0] if isinstance(image_value, list) else image_value
>>> print(type(first_image_path).__name__)
str
>>> print(Path(first_image_path).suffix)
.png