dgs.models.dataset.dataset.BaseDataset

class dgs.models.dataset.dataset.BaseDataset(*args: Any, **kwargs: Any)

Base class for custom datasets.

Every dataset is based around the State object, which is just a fancy dict containing all the data of the current step. But there are two different approaches when thinking about “one sample”. They have different use-cases and therefore different advantages and disadvantages.

Using the Bounding Box as Index

One sample of the dataset (one __getitem__() call) contains the data of one single bounding-box. Therefore, a batch of this dataset contains B bounding-boxes, with the same amount of filepaths, images, key-points, … . The bounding-boxes can be sampled randomly from the dataset, because there is no time-based information. This method can be used for generating and training the visual Re-ID embeddings, because the model does not care when or in which order the bounding-boxes representing the Person-ID (class labels) are perceived.

A dataset with this kind of structure will always return a single State containing the data.

Using the Image ID as Index

One sample of the dataset contains the data of all people / bounding-boxes detected on one single image. Because now we can be sure that all detections of this image are in the current sample, it is possible to move through the dataset in a frame-by-frame manner, keeping time-based information. This is especially useful when working with tracks because the tracks of the current frame depend on the tracks of the previous frame(s), at least in most scenarios.

Due to the time-dependencies, it is not (really) possible to use batches without precomputing part of the tracks, which might result in a worse performance during training. During evaluation, it is possible to use the ground-truth track-information, even though this might change the results of the model, and it has to be shown how grave this influences the results.

When batches are used, the batch-size will vary because every image can have a different number of detections. Every image has a specific number of detections N, ranging from zero to an arbitrary number. This means that with a batch size of B, we obtain B original images, but the length of the resulting State will most likely be larger. Constant batches are possible when trimming overflowing detections, but this is not recommended. The other option is to keep the batches with differing sizes. The DataLoader loads a fixed batch of images, the __getitem__() call of the Dataset then computes the resulting detections and returns those as a list of State ‘s.

Params:

• dataset_path (FilePath) – Path to the directory of the dataset. The value has to either be a local project path, or a valid absolute path.

• data_path (FilePath) – The path to the file containing the data for this dataset. Either from within the dataset_path directory, or as absolute path. If you want to combine multiple files to a single (concatenated) dataset, check out the function get_concatenated_dataset() or the paths parameter.

Optional Params:

• force_img_reshape (bool, optional) – Whether to accept that images in one folder might have different shapes. Default DEF_VAL.dataset.force_img_reshape.

• image_mode (str, optional) – Only applicable if force_img_reshape is True. The cropping mode used for loading the full images when calling get_image_crops(). Value has to be in CustomToAspect.modes`. Default DEF_VAL.images.image_mode.

• image_size (tuple[int, int], optional) – Only applicable if force_img_reshape is True. The size that the original images should have. Default DEF_VAL.images.image_size.

• crops_folder (FilePath, optional) – A path (global, project local, or dataset local), containing the previously cropped images. The structure is dataset-dependent, and might not be necessary for some datasets. Default is not set, and the crops are generated live. Default DEF_VAL.dataset.crops_folder.

• crop_mode (str, optional) – The mode for image cropping used when calling get_image_crops(). Value has to be in CustomToAspect.modes. Default DEF_VAL.images.crop_mode.

• crop_size (tuple[int, int], optional) – The size, the resized image should have. Default DEF_VAL.images.crop_size.

• paths (list[FilePath], optional) – A list of file paths to concatenate into a single dataset using get_concatenated_dataset(). Will be ignored by the single dataset. Can contain ‘*’ and similar wildcards used in glob.glob() to search for multiple files matching a pattern.

• Additional Params for the DataLoader

• ————————————

• batch_size (int, optional) – The batch size to use while creating the DataLoader for this Dataset. Default DEF_VAL.dataloader.batch_size.

• drop_last (bool, optional) – Whether to drop the last batch if its size is unequal to the target batch size. Default DEF_VAL.dataloader.drop_last.

• shuffle (bool, optional) – Whether to shuffle the dataset. Default DEF_VAL.dataloader.shuffle.

• workers (int, optional) – The number of workers for multi-device data-loading. Not fully supported! Therefore, default 0, no multi-device. Default DEF_VAL.dataloader.workers.

• collate_fn (bool, optional) – Which collate function to use, when collating the States for the DataLoader. Can be None or one of "lists", "states", or "history". Default DEF_VAL.dataloader.collate_fn.

• Default Values

• ————–

• .. datatemplate (yaml::) – :source: ../../dgs/default_values.yaml

  {% for param in data[‘dataloader’] %} - {{param}}: {{data[‘dataloader’][param]}} {% endfor %}

  {% for param in data[‘dataset’] %} - {{param}}: {{data[‘dataset’][param]}} {% endfor %}

Methods

__init__(config: dict[str, any], path: list[str]) → None

abstract arbitrary_to_ds(a: any, idx: int) → State | list[State]

Given an index, convert arbitrary data into a State or a list of States.

configure_torch_module(module: torch.nn.Module, train: bool | None = None) → torch.nn.Module

Set compute mode and send model to the device or multiple parallel devices if applicable.

Parameters:

• module – The torch module instance to configure.

• train – Whether to train or eval this module, defaults to the value set in the base config.

Returns:

The module on the specified device or in parallel.

get_image_crops(ds: State) → None

Add the image crops and local key-points to a given state. Works for single or batched State objects. This function modifies the given State in place.

Will load precomputed image crops by setting self.params["crops_folder"].

get_path_in_dataset(path: str) → str

Given an arbitrary file- or directory-path, return its absolute path.

1. check whether the path is a valid absolute path

2. check whether the path is a valid project path

3. check whether the path is an existing path within self.params[“dataset_path”]

Returns:

The absolute found path to the file or directory.

Raises:

FileNotFoundError – If the path is not found.

terminate() → None

Terminate this module and all of its submodules.

If nothing has to be done, just pass. Is used for terminating parallel execution and threads in specific models.

static transform_crop_resize() → torchvision.transforms.v2.Compose

Given one single image, with its corresponding bounding boxes and key-points, obtain a cropped image for every bounding box with localized key-points.

This transform expects a custom structured input as a dict.

>>> structured_input: dict[str, any] = {
    "image": tv_tensors.Image,
    "box": tv_tensors.BoundingBoxes,
    "keypoints": torch.Tensor,
    "output_size": ImgShape,
    "mode": str,
}

Returns:

A composed torchvision function that accepts a dict as input.

After calling this transform function, some values will have different shapes:

image

Now contains the image crops as tensor of shape [N x C x H x W].

bboxes

Zero, one, or multiple bounding boxes for this image as tensor of shape [N x 4]. And the bounding boxes got transformed into the XYWH format.

coordinates

Now contains the joint coordinates of every detection in local coordinates in shape [N x J x 2|3].

static transform_resize_image() → torchvision.transforms.v2.Compose

Given an image, bboxes, and key-points, resize them with custom modes.

This transform expects a custom structured input as a dict.

>>> structured_input: dict[str, any] = {
    "image": tv_tensors.Image,
    "box": tv_tensors.BoundingBoxes,
    "keypoints": torch.Tensor,
    "output_size": ImgShape,
    "mode": str,
}

Returns:

A composed torchvision function that accepts a dict as input.

validate_params(validations: dict[str, list[str | type | tuple[str, any] | Callable[[any, any], bool]]], attrib_name: str = 'params') → None

Given per key validations, validate this module’s parameters.

Throws exceptions on invalid or nonexistent params.

Parameters:

• attrib_name – name of the attribute to validate, should be “params” and only for base class “config”

• validations –

  Dictionary with the name of the parameter as key and a list of validations as value. Every validation in this list has to be true for the validation to be successful.

  The value for the validation can have multiple types:

  • A lambda function or other type of callable

  • A string as reference to a predefined validation function with one argument

  • None for existence

  • A tuple with a string as reference to a predefined validation function with one additional argument

  • It is possible to write nested validations, but then every nested validation has to be a tuple, or a tuple of tuples. For convenience, there are implementations for “any”, “all”, “not”, “eq”, “neq”, and “xor”. Those can have data which is a tuple containing other tuples or validations, or a single validation.

  • Lists and other iterables can be validated using “forall” running the given validations for every item in the input. A single validation or a tuple of (nested) validations is accepted as data.

Example

This example is an excerpt of the validation for the BaseModule-configuration.

>>> validations = {
    "device": [
            str,
            ("any",
                [
                    ("in", ["cuda", "cpu"]),
                    ("instance", torch.device)
                ]
            )
        ],
        "print_prio": [("in", PRINT_PRIORITY)],
        "callable": (lambda value: value == 1),
    }

And within the class __init__() call:

>>> self.validate_params()

Raises:

• InvalidParameterException – If one of the parameters is invalid.

• ValidationException – If the validation list is invalid or contains an unknown validation.

Attributes

device	Get the device of this module.
is_training	Get whether this module is set to training-mode.
module_name	Get the name of the module.
module_type
name	Get the name of the module.
name_safe	Get the escaped name of the module usable in filepaths by replacing spaces and underscores.
precision	Get the (floating point) precision used in multiple parts of this module.
data	Arbitrary data, which will be converted using self.arbitrary_to_ds()
dataset_path	The base path to the dataset.