ParticleDetection.modelling.runners

ParticleDetection.modelling.runners.detection

Functions to run inference with a trained network and save the results for further computations.

Author: Adrian Niemann (adrian.niemann@ovgu.de)

Date: 11.08.2022

SavingFunction

Minimal signature for a function intended for saving DetectionResult.

See also

annotation_to_json(), rods_to_csv(), rods_to_mat()

alias of Callable[[DetectionResult, Union[Path, str, ndarray], dict, Union[Path, str]], None]

detect(dataset: str | Path | ndarray | DataSet | Iterable[str] | Iterable[Path] | Iterable[ndarray], configuration: detectron2.config.CfgNode | str | Path, weights: str | Path, **kwargs) → None[source]
detect(dataset: str | Path | ndarray | DataSet | Iterable[str] | Iterable[Path] | Iterable[ndarray], configuration: detectron2.config.CfgNode | str | Path, weights: str | Path, classes: dict = {}, output_dir: str | Path = Path.cwd(), threshold: float = 0.5, saving_functions: Iterable[Callable[[DetectionResult, Path | str | ndarray, dict, Path | str], None]] = [], **kwargs) → None
detect(dataset: str, configuration: detectron2.config.CfgNode | str | Path, weights: Path | str, frames: List[int], cam1_name: str, cam2_name: str, **kwargs) → None

Run object detection on a dataset with custom result saving.

Run object detection on a given dataset with the possibility to visualize all or some results. Additionally, it is possible to apply (custom) saving functions to the detection result of each given image. The detection can be run either on the CPU or GPU.

Parameters:

  • dataset (Union[str, Path, np.ndarray, ds.DataSet, Iterable[str], Iterable[Path], Iterable[np.ndarray]]) – The data(set) on which object detection will be run. This can be a collection of paths to image files or already loaded images. Already loaded images are expected to be in BGR format. The use of a DataSet already registered to the Detectron2 framework is also possible.

  • configuration (Union[CfgNode, str, Path]) – Configuration for the Detectron2 model and inferences settings given as a CfgNode or path to a *.yaml file in the Detectron2 configuration format.

  • weights (Union[Path, str]) – Path to a *.pth model file, e.g. “model_final.pth”.

  • classes (dict) –

    Dictionary of classes detectable by the model with

    {key} -> Index of class in the model

    {value} -> Name of the class

    By default {}.

  • output_dir (Union[str, Path], optional) –

    Path to the intended output directory. It’s parent directory must exist prior to running this function.

    By default Path.cwd().

  • threshold (float, optional) –

    Threshold for the minimum score of predicted instances.

    By default 0.5.

  • saving_functions (Iterable[SavingFunction], optional) –

    Threshold for the minimum score of predicted instances.

    By default [].

  • log_name (str, optional) –

    Filename for logging output in the output directory.

    By default "detection.log".

  • visualize (bool, optional) –

    Flag for allowing visualization.

    By default False.

  • when (vis_Specifies the number of randomly chosen visualized samples) –

    visualize is True.

    -1 -> All images are viszalized.

    n > 0-> Chooses n images of the given set to be visualized after inference.

    By default -1, i.e. use all images for visualization.

  • device (Literal["cpu", "cuda"], optional) –

    Device the detection is going to be run with, i.e. CPU or GPU.

    By default "cpu".

  • **kwargs (dict, optional) –

    The dataset parameter can accept formattable strings, i.e. dataset.format(…) can be run. This allows to specify a dataset using the following keywords that are going to be inserted using string formatting. For this the string must contain a frame and a cam_id field that can be formatted. See the Examples section for more information.

    framesList[int]

    A list of frames, that shall be used for rod detection.

    By default []

    cam1_namestr

    The name/ID of the first camera in the experiment. This name will be used for image discovery (see dataset_format) and naming of the output *.csv file’s columns.

    By default "".

    cam2_namestr

    The name/ID of the second camera in the experiment. This name will be used for image discovery (see dataset_format) and naming of the output *.csv file’s columns.

    By default "".

    Additional keyword arguments can be inserted here, that shall be available in the given saving_functions, e.g. method for rods_to_csv().

See also

rods_to_csv(), rods_to_mat(), annotation_to_json(), visualize()

Examples

Default Use:

>>> detect(["file1.png", "file2.png"], "config.json", "weights.pth",
...        {0: "test_class", 1: "next_class"},
...        saving_functions=[export.annotations_to_json, ])

Dataset Format Use:

>>> detect("my/path/{cam_id:s}/experiment_{frame:05d}.png",
...        "config.json", "weights.pth",
...        frames = [1, 12], cam1_name = "test", cam2_name = "none")

These settings yield the following files being used for inference:

>>> ["my/path/test/experiment_00001.png",
...  "my/path/none/experiment_00001.png"
...  "my/path/test/experiment_00012.png",
...  "my/path/none/experiment_00012.png"]
run_detection(dataset: DataSet | List[str], configuration: detectron2.config.CfgNode | str, weights: str | None = None, classes: dict | None = None, output_dir: str = './', log_name: str = 'detection.log', visualize: bool = True, vis_random_samples: int = -1, threshold: float = 0.5, **kwargs) → list[source]

Runs inference on a given set of images and can visualize the output.

In addition to running inference this script also generates rod endpoints from the generated masks, if the network predicted these.

Deprecated since version 0.4.0: run_detection() will be completely replaced by detect() to allow more modular saving of data. Internally this function already uses detect().

Parameters:

  • dataset (Union[ds.DataSet, List[str]]) – Either a DataSet already registered to the Detectron2 framework or a list of paths to image files intended for running inference on.

  • configuration (Union[CfgNode, str]) – Configuration for the Detectron2 model and inferences settings given as a CfgNode or path to a *.yaml file in the Detectron2 configuration format.

  • weights (str, optional) – Path to a *.pth model file. Is optional, if the weights are already given in the configuration.

  • classes (dict, optional) –

    Dictionary of classes detectable by the model with

    {key} -> Index of class in the model

    {value} -> Name of the class

    By default None.

  • output_dir (str, optional) –

    Path to the intended output directory. It’s parent directory must exist prior to running this function.

    By default "./".

  • log_name (str, optional) –

    Filename for logging output in the output directory.

    By default "detection.log".

  • visualize (bool, optional) –

    Flag for allowing visualization.

    By default True.

  • vis_random_samples (int, optional) –

    Specifies the number of randomly chosen visualized samples when visualize is True.

    -1 -> All images are viszalized.

    n > 0-> Chooses n images of the given set to be visualized after inference.

    By default -1.

  • threshold (float, optional) –

    Threshold for the minimum score of predicted instances.

    By default 0.5.

  • **kwargs – Keyword arguments for visualization.visualize(), except for prediction, original, and output_dir.

Returns:

list

See also

rods_to_mat()

run_detection_csv(dataset_format: str, configuration: detectron2.config.CfgNode | str, weights: str | None = None, classes: dict | None = None, output_dir: str = './', log_name: str = 'detection.log', threshold: float = 0.5, frames: List[int] = [], cam1_name: str = 'gp1', cam2_name: str = 'gp2') → None[source]

Runs inference on a given set of images and saves the output to a *.csv.

This function runs a rod detection on images and generates rod enpoints from the generated masks, if the network predicted these. Finally, these endpoints are saved to a single rods_df.csv file in the specified output folder.

Deprecated since version 0.4.0: run_detection_csv() will be completely replaced by detect() to allow more modular saving of data. Internally this function already uses detect().

Parameters:

  • dataset_format (str) –

    String that can be formatted to specify the file locations of images, that shall be used for inference. For this the string must contain a frame and a cam_id field that can be formatted.

    Example:

    "my/dataset/path/{cam_id:s}/experiment_{frame:05d}.png"

  • configuration (Union[CfgNode, str]) – Configuration for the Detectron2 model and inferences settings given as a CfgNode or path to a *.yaml file in the Detectron2 configuration format.

  • weights (str, optional) – Path to a *.pth model file. Is optional, if the weights are already given in the configuration.

  • classes (dict, optional) –

    Dictionary of classes detectable by the model with

    {key} -> Index of class in the model

    {value} -> Name of the class

    By default None.

  • output_dir (str, optional) –

    Path to the intended output directory. It’s parent directory must exist prior to running this function.

    By default "./".

  • log_name (str, optional) –

    Filename for logging output in the output directory.

    By default "detection.log".

  • threshold (float, optional) –

    Threshold for the minimum score of predicted instances.

    By default 0.5.

  • frames (List[int], optional) –

    A list of frames, that shall be used for rod detection.

    By default [].

  • cam1_name (str, optional) –

    The name/ID of the first camera in the experiment. This name will be used for image discovery (see dataset_format) and naming of the output *.csv file’s columns.

    By default "gp1".

  • cam2_name (str, optional) –

    The name/ID of the second camera in the experiment. This name will be used for image discovery (see dataset_format) and naming of the output *.csv file’s columns.

    By default "gp2".

See also

rods_to_csv()

ParticleDetection.modelling.runners.training

Function(s) to train a new model using the Detectron2 framework.

Author: Adrian Niemann (adrian.niemann@ovgu.de)

Date: 10.08.2022

run_training(train_set: DataSet, configuration: str | detectron2.config.CfgNode, val_set: DataSet | None = None, output_dir: str = './', log_name: str = 'training.log', resume: bool = True, visualize: bool = False, img_augmentations: List[detectron2.data.transforms.Augmentation] | None = None, freeze_layers: List[str] | None = None)[source]

Runs the training of a model with the given training data.

Runs the training of a model which is defined by the given configuration. The training can be resumed and further specification of layers to train/not to train is possible. During training the different model performance metrics are logged in the Tensorboard format. Additional COCO metrics are available only if a validation dataset is given. These metrics are also logged in the Tensorboard format.

Parameters:

  • train_set (DataSet) – A DataSet already registered to the Detectron2 framework, that is used for training the model.

  • configuration (Union[str, CfgNode]) – Configuration for the Detectron2 model with training settings given as a CfgNode or path to a *.yaml file in the Detectron2 configuration format.

  • val_set (DataSet, optional) –

    A DataSet already registered to the Detectron2 framework, that is used for testing the model during training.

    By default None.

  • output_dir (str, optional) –

    Path to the intended output directory. It’s parent directory must exist prior to running this function.

    By default "./".

  • log_name (str, optional) –

    Filename for logging output in the output directory.

    By default "training.log".

  • resume (bool, optional) –

    Flag to continue with previous training progress in the output folder.

    By default True.

  • visualize (bool, optional) –

    Flag for allowing visualization of one randomly selected image from the given training dataset with 10 randomly chosen annotations overlaid on the image.

    By default False.

  • img_augmentations (List[Augmentation], optional) –

    Image augmentations to be used during training.

    By default None.

  • freeze_layers (List[str], optional) –

    Layers/layer collections to be frozen during training. The model’s layer names are obtained using model.named_parameters().

    By default None.