Prediction Interface#

class glasses_detector.components.pred_interface.PredInterface[source]#

Bases: ABC

Interface for handling image-based predictions.

This interface provides a common API for handling predictions (e.g. saving, loading, etc.) for all models. It also provides a common API for making predictions on images, directories, and files.

Any class that inherits from this interface must implement the predict() method. This method should take a single image path or a list of image paths and return a single prediction or a list of predictions, respectively.

static save(pred: Default | dict[str, Default], filepath: FilePath)[source]#

Saves a prediction to a file.

This method saves a prediction or a dictionary of named predictions to the provided file. The type of the file will be inferred automatically from the extension and will be saved accordingly.

Supported File Types#
Extension	Format
`.txt`	For a single prediction, it is flattened and saved as a single line separated by spaces. For a dictionary of predictions, each row contains the name of the prediction followed by the flattened prediction values separated by spaces (no header!).
`.csv`	For a single prediction, it is flattened and saved as a single line separated by commas. For a dictionary of predictions, each row contains the name of the prediction followed by the flattened prediction values separated by commas (no header!).
`.json`	For a single prediction, it is saved as a single JSON object. For a dictionary of predictions, each prediction is saved as a separate JSON object with the name of the prediction as the key.
`.yml`, `.yaml`	For a single prediction, it is saved as a single YAML object. For a dictionary of predictions, each prediction is saved as a separate YAML object with the name of the prediction as the key.
`.pkl`	For a single prediction, it is saved as a single pickle object. For a dictionary of predictions, each prediction is saved as a separate pickle object with the name of the prediction as the key.
`.npy`, `.npz`	For a single prediction, it is saved as a single numpy array or scalar. For a dictionary of predictions, it is flattened to a 2D matrix where each row contains the name of the prediction followed by the flattened prediction values. For `.npy`, `numpy.save()` is used and for `.npz`, `numpy.savez_compressed()` is used.
`.dat`	For a single prediction, it is saved as a single numpy array or scalar using `numpy.ndarray.tofile()`. For a dictionary of predictions, they are first flattened to a 2D matrix before saving.
`.jpg`, `.jpeg`, `.png`, `.bmp`, `.pgm`, `.webp`	For a single prediction, it is saved as an image. For a dictionary of predictions, each prediction is saved as a separate image with the name of the prediction as the file name. In the case of multiple predictions, all images are saved under directory called `filepath`, just without an extension.

Parameters:

pred (Default | dict[str, Default]) – The single prediction or a dictionary of predictions to save.
filepath (FilePath) – The path to save the prediction(-s) to.

Raises:

ValueError – If the file type is not supported.

abstract predict(image: FilePath, **kwargs) → Default[source]#

abstract predict(image: Collection[FilePath], **kwargs) → list[Default]

Generates a prediction for the given image(-s).

Takes a path to an image or a list of paths to images and returns a prediction or a list of predictions, respectively.

Parameters:

image (FilePath | Collection[FilePath]) – The path to an image or a list of paths to images to generate predictions for.
**kwargs – Additional keyword arguments to pass to the prediction method.

Returns:

The prediction or a list of predictions for the given image(-s).

Return type:

Default | list[Default]

process_file(input_path: FilePath, output_path: FilePath | None = None, ext: str | None = None, show: bool = False, **pred_kwargs) → Default | None[source]#

process_file(input_path: Collection[FilePath], output_path: Collection[FilePath] | None = None, ext: str | None = None, show: bool = False, **pred_kwargs) → list[Default | None]

Processes a single image or a list of images.

Takes a path to the image or a list of paths to images, generates the prediction(-s), and returns them, based on how predict() behaves. If the output path is specified, the prediction(-s) will be saved to the given path(-s) based on the extension of the output path. The following cases are considered:

If output_path is None, no predictions are saved. If there are multiple output paths (one for each input path) and some of the entries are None, then only the outputs for the corresponding predictions are not be saved.
If the output path is a single file, then the predictions are saved to that file. If there are multiple input paths, then the corresponding predictions are aggregated to a single file.
If output_path is a directory, then the prediction(-s) are saved to that directory. For each input path, a corresponding file is created in the specified output directory with the same name as the input. The extension, if not provided as ext, is set to .jpg for images and .txt for other predictions.
If output_path is a list of output paths, then the predictions are saved to the corresponding output paths. If the number of input paths and output paths do not match, then the number of predictions are be truncated or expanded with None to match the number of input paths and a warning is raised. all the output paths are interpreted as files.

For more details on how each file type is saved, regardless if it is a single prediction or the aggregated predictions, see save().

NB: aggregation of multiple images to a single file is different from that of process_dir() - here, the full paths are used as sample identifiers, unlike just the names of the images.

Tip

If multiple images are provided (as a list of input paths), they are likely to be loaded into a single batch for a faster prediction (see predict() for more details), thus more memory is required than if they were processed individually. For this reason, consider not to pass too many images at once (e.g., <200).

Note

If some input path does not lead to a valid image file, e.g., does not exist, its prediction is set to None. Also, if at least one prediction fails, then all predictions are set to None. In both cases, a warning is is raised and the files or the lines in the aggregated file are skipped (not saved).

Parameters:

input_path (FilePath | Collection[FilePath]) – The path to an image or a list of paths to images to generate predictions for.
output_path (FilePath | Collection[FilePath] | None, optional) – The path to save the prediction(-s) to. If None, no predictions are saved. If a single file, the predictions are aggregated (if multiple) and saved to that file. If a directory, the predictions are saved to that directory with the names copied from inputs. Defaults to None.
ext (str | None, optional) – The extension to use for the output file(-s). Only used when output_path is a directory. If None, the extension is set to ".jpg" for images and ".txt" for other predictions (depends on what is returned by predict() returns) For available options, refer to save(). Defaults to None.
show (bool, optional) – Whether to show the predictions. Images will be shown using PIL.Image.Image.show() and other predictions will be printed to stdout. Defaults to False.
**pred_kwargs – Additional keyword arguments to pass to predict().

Returns:

The prediction or a list of predictions for the given image(-s). Any failed predictions will be set to None.

Return type:

Default | None | list[Default | None]

Processes a directory of images.

Takes a path to a directory of images, optionally sub-groups to batches, generates the predictions for every image and returns them if output_path is None or saves them to a specified file or as files to a specified directory. The following cases are considered:

If output_path is None, the predictions are returned as a dictionary of predictions where the keys are the names of the images and the values are the corresponding predictions.
If output_path is a single file, the predictions are aggregated to a single file.
If output_path is a directory, the predictions are saved to that directory. For each input path, a corresponding file is created in the specified output directory with the same name as the input. The extension, if not provided as ext, is set automatically as explained in process_file().

For more details on how each file type is saved, regardless if it is a single prediction or the aggregated predictions, see save().

NB: aggregation of images to a single file/dictionary is different from that of process_file() (when multiple file paths are passed) - here, only the names of the images are used as keys, unlike the full paths.

Tip

For very large directories, consider specifying output_path as a directory because aggregating the predictions to a single file or waiting for them to be returned might consume too much memory and lead to errors.

Note

Any files in the input directory that are not valid images or those for which the prediction fails for any reason are are simply skipped and a warning is raised - for more details, see process_file().

Parameters:

input_path (FilePath) – The path to a directory of images to generate predictions for.
output_path (FilePath | None, optional) – The path to save the prediction(-s) to. If None, the predictions are returned as a dictionary, if a single file, the predictions are aggregated to a single file, and if a directory, the predictions are saved to that directory with the names copied from inputs. Defaults to None.
ext (str | None, optional) – The extension to use for the output file(-s). Only used when output_path is a directory. The extension should include a leading dot, e.g., ".txt", ".npy", ".jpg" etc (see save()). If None, the behavior follows process_file(). Defaults to None.
batch_size (int, optional) – The batch size to use when processing the images. This groups the files in the specified directory to batches of size batch_size before processing them. In some cases, larger batch sizes can speed up the processing at the cost of more memory usage. Defaults to 1.
show (bool, optional) – Whether to show the predictions. Images will be shown using PIL.Image.Image.show() and other predictions will be printed to stdout. It is not recommended to set this to True as it might spam your stdout. Defaults to False.
pbar (bool | str | tqdm, optional) – Whether to show a progress bar. If True, a progress bar with no description is shown. If str, a progress bar with the given description is shown. If an instance of tqdm, it is used as is. Defaults to True.
update_total (bool, optional) – Whether to update the total number of files in the progress bar. This is only relevant if pbar is an instance of tqdm. For example, if the number of total files is already known and captured by tqdm.tqdm.total, then there is no need to update it. Defaults to True.
**pred_kwargs – Additional keyword arguments to pass to predict().

Returns:

The dictionary of predictions if output_path is None or None if output_path is specified.

Return type:

dict[str, Default | None] | None