core package¶
Submodules¶
core.cli module¶
Command line interface parsers.
License¶
Copyright (c) 2020 Daniel Frisinghelli
This source code is licensed under the GNU General Public License v3.
See the LICENSE file in the repository’s root directory.
core.constants module¶
A collection of constant values.
License¶
Copyright (c) 2020 Daniel Frisinghelli
This source code is licensed under the GNU General Public License v3.
See the LICENSE file in the repository’s root directory.
-
class
core.constants.
Cloud95Labels
(value)[source]¶ Bases:
core.constants.Label
Class labels of the Cloud-95 dataset.
-
Clear
= (0, 'skyblue')¶
-
Cloud
= (1, 'white')¶
-
-
class
core.constants.
Label
(value)[source]¶ Bases:
enum.Enum
Generic enumeration for class labels.
-
property
color
¶ Return the color to plot a class.
-
property
id
¶ Return the value of a class in the ground truth.
-
property
-
class
core.constants.
Landsat8
(value)[source]¶ Bases:
enum.Enum
The spectral bands of the Landsat 8 sensors.
- sensors:
Operational Land Imager (OLI), (bands 1-9)
Thermal Infrared Sensor (TIRS), (bands 10, 11)
-
blue
= 2¶
-
cirrus
= 9¶
-
green
= 3¶
-
nir
= 5¶
-
pan
= 8¶
-
red
= 4¶
-
swir1
= 6¶
-
swir2
= 7¶
-
tir1
= 10¶
-
violet
= 1¶
-
class
core.constants.
ProSnowLabels
(value)[source]¶ Bases:
core.constants.Label
Class labels of the ProSnow datasets.
-
Cloud
= (0, 'white')¶
-
Snow
= (1, 'lightblue')¶
-
Snow_free
= (2, 'sienna')¶
-
core.dataset module¶
Custom dataset classes compliant to the PyTorch standard.
Each custom dataset should inherit from torch.utils.data.Dataset to benefit from the torch.utils.data.DataLoader class, which implements helpful utilities during model training.
For any kind of image-like dataset, inherit the ImageDataset class to create your custom dataset.
License¶
Copyright (c) 2020 Daniel Frisinghelli
This source code is licensed under the GNU General Public License v3.
See the LICENSE file in the repository’s root directory.
-
class
core.dataset.
Cloud95Dataset
(root_dir, use_bands=[], tile_size=None, pad=False, gt_pattern='(.*)gt\\.tif', sort=False, seed=0, transforms=[])[source]¶ Bases:
core.dataset.ImageDataset
Class for the Cloud-95 dataset by Mohajerani et al. (2020).
- Parameters
root_dir (str) – The root directory, path to the dataset.
use_bands (list [str], optional) – A list of the spectral bands to use. The default is [].
tile_size (int or None, optional) – The size of the tiles. If not None, each scene is divided into square tiles of shape (tile_size, tile_size). The default is None.
pad (bool, optional) – Whether to center pad the input image. Set
pad
= True, if the images are not evenly divisible by thetile_size
. The image data is padded with a constant padding value of zero. For each image, the corresponding ground truth image is padded with a “no data” label. The default is False.gt_pattern (str, optional) – A regural expression to match the ground truth naming convention. All directories and subdirectories in
root_dir
are searched for files matchinggt_pattern
. The default is ‘(.*)gt\.tif’.sort (bool, optional) – Whether to chronologically sort the samples. Useful for time series data. The default is False.
seed (int, optional) – The random seed. Used to split the dataset into training, validation and test set. Useful for reproducibility. The default is 0.
transforms (list [pysegcnn.core.split.Augment], optional) – List of pysegcnn.core.split.Augment instances. Each item in
transforms
generates a distinct transformed version of the dataset. The total dataset is composed of the original untransformed dataset together with each transformed version of it. Iftransforms
= [], only the original dataset is used. The default is [].
- Returns
- Return type
None.
Methods
build_samples
(scene)Stack the bands of a sample in a single array.
Build the list of samples of the dataset.
Class labels of the Cloud-95 dataset.
Landsat 8 bands of the Cloud-95 dataset.
get_size
()Image size of the Cloud-95 dataset.
parse_scene_id
(scene_id)Parse Sparcs scene identifiers (Landsat 8).
preprocess
(data, gt)Preprocess Cloud-95 dataset images.
read_scene
(idx)Read the data of the sample with index
idx
.to_tensor
(x, dtype)Convert
x
to torch.Tensor.-
compose_scenes
()[source]¶ Build the list of samples of the dataset.
Each sample is represented by a dictionary.
- Returns
scenes –
- Each item in
scenes
is a dict with keys: 'band_name_1'
Path to the file of band_1.
'band_name_2'
Path to the file of band_2.
'band_name_n'
Path to the file of band_n.
'gt'
Path to the ground truth file.
'date'
The date of the sample.
'tile'
The tile id of the sample.
'transform'
The transformation to apply.
'id'
The scene identifier.
- Each item in
- Return type
list [dict]
-
get_labels
()[source]¶ Class labels of the Cloud-95 dataset.
- Returns
labels – The class labels.
- Return type
enum.Enum
-
get_sensor
()[source]¶ Landsat 8 bands of the Cloud-95 dataset.
- Returns
sensor – An enumeration of the bands of the sensor.
- Return type
enum.Enum
-
get_size
()[source]¶ Image size of the Cloud-95 dataset.
- Returns
size – The image size (height, width).
- Return type
tuple
-
class
core.dataset.
ImageDataset
(root_dir, use_bands=[], tile_size=None, pad=False, gt_pattern='(.*)gt.tif', sort=False, seed=0, transforms=[])[source]¶ Bases:
torch.utils.data.dataset.Dataset
Base class for multispectral image data.
Inheriting from torch.utils.data.Dataset to be compliant to the PyTorch standard. Furthermore, using instances of torch.utils.data.Dataset enables the use of the handy torch.utils.data.DataLoader class during model training.
- Parameters
root_dir (str) – The root directory, path to the dataset.
use_bands (list [str], optional) – A list of the spectral bands to use. The default is [].
tile_size (int or None, optional) – The size of the tiles. If not None, each scene is divided into square tiles of shape (tile_size, tile_size). The default is None.
pad (bool, optional) – Whether to center pad the input image. Set
pad
= True, if the images are not evenly divisible by thetile_size
. The image data is padded with a constant padding value of zero. For each image, the corresponding ground truth image is padded with a “no data” label. The default is False.gt_pattern (str, optional) – A regural expression to match the ground truth naming convention. All directories and subdirectories in
root_dir
are searched for files matchinggt_pattern
. The default is ‘(.*)gt\.tif’.sort (bool, optional) – Whether to chronologically sort the samples. Useful for time series data. The default is False.
seed (int, optional) – The random seed. Used to split the dataset into training, validation and test set. Useful for reproducibility. The default is 0.
transforms (list [pysegcnn.core.split.Augment], optional) – List of pysegcnn.core.split.Augment instances. Each item in
transforms
generates a distinct transformed version of the dataset. The total dataset is composed of the original untransformed dataset together with each transformed version of it. Iftransforms
= [], only the original dataset is used. The default is [].
- Returns
- Return type
None.
Methods
build_samples
(scene)Stack the bands of a sample in a single array.
Build the list of samples of the dataset.
Return an enumeration of the class labels of the dataset.
Return an enumeration of the bands of the sensor of the dataset.
get_size
()Return the size of the images in the dataset.
parse_scene_id
(scene_id)Parse the scene identifier.
preprocess
(data, gt)Preprocess a sample before feeding it to a model.
read_scene
(idx)Read the data of the sample with index
idx
.to_tensor
(x, dtype)Convert
x
to torch.Tensor.-
build_samples
(scene)[source]¶ Stack the bands of a sample in a single array.
- Parameters
scene (dict) –
- The sample data dictionary with keys:
'band_name_1'
data of band_1 (numpy.ndarray).
'band_name_2'
data of band_2 (numpy.ndarray).
'band_name_n'
data of band_n (numpy.ndarray).
'gt'
data of the ground truth (numpy.ndarray).
'date'
The date of the sample.
'tile'
The tile id of the sample.
'transform'
The transformation to apply.
'id'
The scene identifier.
- Returns
stack (numpy.ndarray) – The input data of the sample.
gt (TYPE) – The ground truth of the sample.
-
compose_scenes
()[source]¶ Build the list of samples of the dataset.
Each sample is represented by a dictionary.
- Raises
NotImplementedError – Raised if the pysegcnn.core.dataset.ImageDataset class is not inherited.
- Returns
samples –
- Each dictionary representing a sample should have keys:
'band_name_1'
Path to the file of band_1.
'band_name_2'
Path to the file of band_2.
'band_name_n'
Path to the file of band_n.
'gt'
Path to the ground truth file.
'date'
The date of the sample.
'tile'
The tile id of the sample.
'transform'
The transformation to apply.
'id'
The scene identifier.
- Return type
list [dict]
-
get_labels
()[source]¶ Return an enumeration of the class labels of the dataset.
Examples can be found in pysegcnn.core.constants.
- Raises
NotImplementedError – Raised if the pysegcnn.core.dataset.ImageDataset class is not inherited.
- Returns
labels – The class labels.
- Return type
enum.Enum
-
get_sensor
()[source]¶ Return an enumeration of the bands of the sensor of the dataset.
Examples can be found in pysegcnn.core.constants.
- Raises
NotImplementedError – Raised if the pysegcnn.core.dataset.ImageDataset class is not inherited.
- Returns
sensor – An enumeration of the bands of the sensor.
- Return type
enum.Enum
-
get_size
()[source]¶ Return the size of the images in the dataset.
- Raises
NotImplementedError – Raised if the pysegcnn.core.dataset.ImageDataset class is not inherited.
- Returns
size – The image size (height, width).
- Return type
tuple
-
parse_scene_id
(scene_id)[source]¶ Parse the scene identifier.
- Parameters
scene_id (str) – A scene identifier.
- Raises
NotImplementedError – Raised if the pysegcnn.core.dataset.ImageDataset class is not inherited.
- Returns
scene – A dictionary containing scene metadata. If None,
scene_id
is not a valid scene identifier.- Return type
dict or None
-
preprocess
(data, gt)[source]¶ Preprocess a sample before feeding it to a model.
- Parameters
data (numpy.ndarray) – The sample input data.
gt (numpy.ndarray) – The sample ground truth.
- Raises
NotImplementedError – Raised if the pysegcnn.core.dataset.ImageDataset class is not inherited.
- Returns
data (numpy.ndarray) – The preprocessed input data.
gt (numpy.ndarray) – The preprocessed ground truth data.
-
read_scene
(idx)[source]¶ Read the data of the sample with index
idx
.- Parameters
idx (int) – The index of the sample.
- Returns
scene_data –
- The sample data dictionary with keys:
'band_name_1'
data of band_1 (numpy.ndarray).
'band_name_2'
data of band_2 (numpy.ndarray).
'band_name_n'
data of band_n (numpy.ndarray).
'gt'
data of the ground truth (numpy.ndarray).
'date'
The date of the sample.
'tile'
The tile id of the sample.
'transform'
The transformation to apply.
'id'
The scene identifier.
- Return type
dict
-
class
core.dataset.
ProSnowDataset
(root_dir, use_bands=[], tile_size=None, pad=False, gt_pattern='(.*)gt\\.tif', sort=False, seed=0, transforms=[])[source]¶ Bases:
core.dataset.StandardEoDataset
Class for the ProSnow datasets.
- Parameters
root_dir (str) – The root directory, path to the dataset.
use_bands (list [str], optional) – A list of the spectral bands to use. The default is [].
tile_size (int or None, optional) – The size of the tiles. If not None, each scene is divided into square tiles of shape (tile_size, tile_size). The default is None.
pad (bool, optional) – Whether to center pad the input image. Set
pad
= True, if the images are not evenly divisible by thetile_size
. The image data is padded with a constant padding value of zero. For each image, the corresponding ground truth image is padded with a “no data” label. The default is False.gt_pattern (str, optional) – A regural expression to match the ground truth naming convention. All directories and subdirectories in
root_dir
are searched for files matchinggt_pattern
. The default is ‘(.*)gt\.tif’.sort (bool, optional) – Whether to chronologically sort the samples. Useful for time series data. The default is False.
seed (int, optional) – The random seed. Used to split the dataset into training, validation and test set. Useful for reproducibility. The default is 0.
transforms (list [pysegcnn.core.split.Augment], optional) – List of pysegcnn.core.split.Augment instances. Each item in
transforms
generates a distinct transformed version of the dataset. The total dataset is composed of the original untransformed dataset together with each transformed version of it. Iftransforms
= [], only the original dataset is used. The default is [].
- Returns
- Return type
None.
Methods
build_samples
(scene)Stack the bands of a sample in a single array.
compose_scenes
()Build the list of samples of the dataset.
Class labels of the ProSnow datasets.
Sentinel 2 bands of the ProSnow datasets.
get_size
()Return the size of the images in the dataset.
parse_scene_id
(scene_id)Parse ProSnow scene identifiers (Sentinel 2).
preprocess
(data, gt)Preprocess ProSnow dataset images.
read_scene
(idx)Read the data of the sample with index
idx
.to_tensor
(x, dtype)Convert
x
to torch.Tensor.-
get_labels
()[source]¶ Class labels of the ProSnow datasets.
- Returns
labels – The class labels.
- Return type
enum.Enum
-
get_sensor
()[source]¶ Sentinel 2 bands of the ProSnow datasets.
- Returns
sensor – An enumeration of the bands of the sensor.
- Return type
enum.Enum
-
class
core.dataset.
ProSnowGarmisch
(root_dir, use_bands=[], tile_size=None, pad=False, gt_pattern='(.*)gt\\.tif', sort=False, seed=0, transforms=[])[source]¶ Bases:
core.dataset.ProSnowDataset
Class for the ProSnow Garmisch dataset.
- Parameters
root_dir (str) – The root directory, path to the dataset.
use_bands (list [str], optional) – A list of the spectral bands to use. The default is [].
tile_size (int or None, optional) – The size of the tiles. If not None, each scene is divided into square tiles of shape (tile_size, tile_size). The default is None.
pad (bool, optional) – Whether to center pad the input image. Set
pad
= True, if the images are not evenly divisible by thetile_size
. The image data is padded with a constant padding value of zero. For each image, the corresponding ground truth image is padded with a “no data” label. The default is False.gt_pattern (str, optional) – A regural expression to match the ground truth naming convention. All directories and subdirectories in
root_dir
are searched for files matchinggt_pattern
. The default is ‘(.*)gt\.tif’.sort (bool, optional) – Whether to chronologically sort the samples. Useful for time series data. The default is False.
seed (int, optional) – The random seed. Used to split the dataset into training, validation and test set. Useful for reproducibility. The default is 0.
transforms (list [pysegcnn.core.split.Augment], optional) – List of pysegcnn.core.split.Augment instances. Each item in
transforms
generates a distinct transformed version of the dataset. The total dataset is composed of the original untransformed dataset together with each transformed version of it. Iftransforms
= [], only the original dataset is used. The default is [].
- Returns
- Return type
None.
Methods
build_samples
(scene)Stack the bands of a sample in a single array.
compose_scenes
()Build the list of samples of the dataset.
get_labels
()Class labels of the ProSnow datasets.
get_sensor
()Sentinel 2 bands of the ProSnow datasets.
get_size
()Image size of the ProSnow Garmisch dataset.
parse_scene_id
(scene_id)Parse ProSnow scene identifiers (Sentinel 2).
preprocess
(data, gt)Preprocess ProSnow dataset images.
read_scene
(idx)Read the data of the sample with index
idx
.to_tensor
(x, dtype)Convert
x
to torch.Tensor.
-
class
core.dataset.
ProSnowObergurgl
(root_dir, use_bands=[], tile_size=None, pad=False, gt_pattern='(.*)gt\\.tif', sort=False, seed=0, transforms=[])[source]¶ Bases:
core.dataset.ProSnowDataset
Class for the ProSnow Obergurgl dataset.
- Parameters
root_dir (str) – The root directory, path to the dataset.
use_bands (list [str], optional) – A list of the spectral bands to use. The default is [].
tile_size (int or None, optional) – The size of the tiles. If not None, each scene is divided into square tiles of shape (tile_size, tile_size). The default is None.
pad (bool, optional) – Whether to center pad the input image. Set
pad
= True, if the images are not evenly divisible by thetile_size
. The image data is padded with a constant padding value of zero. For each image, the corresponding ground truth image is padded with a “no data” label. The default is False.gt_pattern (str, optional) – A regural expression to match the ground truth naming convention. All directories and subdirectories in
root_dir
are searched for files matchinggt_pattern
. The default is ‘(.*)gt\.tif’.sort (bool, optional) – Whether to chronologically sort the samples. Useful for time series data. The default is False.
seed (int, optional) – The random seed. Used to split the dataset into training, validation and test set. Useful for reproducibility. The default is 0.
transforms (list [pysegcnn.core.split.Augment], optional) – List of pysegcnn.core.split.Augment instances. Each item in
transforms
generates a distinct transformed version of the dataset. The total dataset is composed of the original untransformed dataset together with each transformed version of it. Iftransforms
= [], only the original dataset is used. The default is [].
- Returns
- Return type
None.
Methods
build_samples
(scene)Stack the bands of a sample in a single array.
compose_scenes
()Build the list of samples of the dataset.
get_labels
()Class labels of the ProSnow datasets.
get_sensor
()Sentinel 2 bands of the ProSnow datasets.
get_size
()Image size of the ProSnow Obergurgl dataset.
parse_scene_id
(scene_id)Parse ProSnow scene identifiers (Sentinel 2).
preprocess
(data, gt)Preprocess ProSnow dataset images.
read_scene
(idx)Read the data of the sample with index
idx
.to_tensor
(x, dtype)Convert
x
to torch.Tensor.
-
class
core.dataset.
SparcsDataset
(root_dir, use_bands=[], tile_size=None, pad=False, gt_pattern='(.*)gt\\.tif', sort=False, seed=0, transforms=[])[source]¶ Bases:
core.dataset.StandardEoDataset
Class for the Sparcs dataset.
- Parameters
root_dir (str) – The root directory, path to the dataset.
use_bands (list [str], optional) – A list of the spectral bands to use. The default is [].
tile_size (int or None, optional) – The size of the tiles. If not None, each scene is divided into square tiles of shape (tile_size, tile_size). The default is None.
pad (bool, optional) – Whether to center pad the input image. Set
pad
= True, if the images are not evenly divisible by thetile_size
. The image data is padded with a constant padding value of zero. For each image, the corresponding ground truth image is padded with a “no data” label. The default is False.gt_pattern (str, optional) – A regural expression to match the ground truth naming convention. All directories and subdirectories in
root_dir
are searched for files matchinggt_pattern
. The default is ‘(.*)gt\.tif’.sort (bool, optional) – Whether to chronologically sort the samples. Useful for time series data. The default is False.
seed (int, optional) – The random seed. Used to split the dataset into training, validation and test set. Useful for reproducibility. The default is 0.
transforms (list [pysegcnn.core.split.Augment], optional) – List of pysegcnn.core.split.Augment instances. Each item in
transforms
generates a distinct transformed version of the dataset. The total dataset is composed of the original untransformed dataset together with each transformed version of it. Iftransforms
= [], only the original dataset is used. The default is [].
- Returns
- Return type
None.
Methods
build_samples
(scene)Stack the bands of a sample in a single array.
compose_scenes
()Build the list of samples of the dataset.
Class labels of the Sparcs dataset.
Landsat 8 bands of the Sparcs dataset.
get_size
()Image size of the Sparcs dataset.
parse_scene_id
(scene_id)Parse Sparcs scene identifiers (Landsat 8).
preprocess
(data, gt)Preprocess Sparcs dataset images.
read_scene
(idx)Read the data of the sample with index
idx
.to_tensor
(x, dtype)Convert
x
to torch.Tensor.-
get_labels
()[source]¶ Class labels of the Sparcs dataset.
- Returns
labels – The class labels.
- Return type
enum.Enum
-
get_sensor
()[source]¶ Landsat 8 bands of the Sparcs dataset.
- Returns
sensor – An enumeration of the bands of the sensor.
- Return type
enum.Enum
-
get_size
()[source]¶ Image size of the Sparcs dataset.
- Returns
size – The image size (height, width).
- Return type
tuple
-
class
core.dataset.
StandardEoDataset
(root_dir, use_bands=[], tile_size=None, pad=False, gt_pattern='(.*)gt\\.tif', sort=False, seed=0, transforms=[])[source]¶ Bases:
core.dataset.ImageDataset
Base class for standard Earth Observation style datasets.
pysegcnn.core.dataset.StandardEoDataset implements the ~pysegcnn.core.dataset.StandardEoDataset.compose_scenes method for datasets with the following directory structure:
- root_dir/
- scene_id_1/
scene_id_1_B1.tif scene_id_1_B2.tif . . . scene_id_1_BN.tif
- scene_id_2/
scene_id_2_B1.tif scene_id_2_B2.tif . . . scene_id_2_BN.tif
. scene_id_N/
.
If your dataset shares this directory structure, you can directly inherit pysegcnn.core.dataset.StandardEoDataset and implement the remaining methods.
See pysegcnn.core.dataset.SparcsDataset for an example.
- Parameters
root_dir (str) – The root directory, path to the dataset.
use_bands (list [str], optional) – A list of the spectral bands to use. The default is [].
tile_size (int or None, optional) – The size of the tiles. If not None, each scene is divided into square tiles of shape (tile_size, tile_size). The default is None.
pad (bool, optional) – Whether to center pad the input image. Set
pad
= True, if the images are not evenly divisible by thetile_size
. The image data is padded with a constant padding value of zero. For each image, the corresponding ground truth image is padded with a “no data” label. The default is False.gt_pattern (str, optional) – A regural expression to match the ground truth naming convention. All directories and subdirectories in
root_dir
are searched for files matchinggt_pattern
. The default is ‘(.*)gt\.tif’.sort (bool, optional) – Whether to chronologically sort the samples. Useful for time series data. The default is False.
seed (int, optional) – The random seed. Used to split the dataset into training, validation and test set. Useful for reproducibility. The default is 0.
transforms (list [pysegcnn.core.split.Augment], optional) – List of pysegcnn.core.split.Augment instances. Each item in
transforms
generates a distinct transformed version of the dataset. The total dataset is composed of the original untransformed dataset together with each transformed version of it. Iftransforms
= [], only the original dataset is used. The default is [].
- Returns
- Return type
None.
Methods
build_samples
(scene)Stack the bands of a sample in a single array.
Build the list of samples of the dataset.
get_labels
()Return an enumeration of the class labels of the dataset.
get_sensor
()Return an enumeration of the bands of the sensor of the dataset.
get_size
()Return the size of the images in the dataset.
parse_scene_id
(scene_id)Parse the scene identifier.
preprocess
(data, gt)Preprocess a sample before feeding it to a model.
read_scene
(idx)Read the data of the sample with index
idx
.to_tensor
(x, dtype)Convert
x
to torch.Tensor.-
compose_scenes
()[source]¶ Build the list of samples of the dataset.
Each sample is represented by a dictionary.
- Returns
scenes –
- Each item in
scenes
is a dict with keys: 'band_name_1'
Path to the file of band_1.
'band_name_2'
Path to the file of band_2.
'band_name_n'
Path to the file of band_n.
'gt'
Path to the ground truth file.
'date'
The date of the sample.
'tile'
The tile id of the sample.
'transform'
The transformation to apply.
'id'
The scene identifier.
- Each item in
- Return type
list [dict]
-
class
core.dataset.
SupportedDatasets
(value)[source]¶ Bases:
enum.Enum
Names and corresponding classes of the implemented datasets.
-
Cloud95
= <class 'core.dataset.Cloud95Dataset'>¶
-
Garmisch
= <class 'core.dataset.ProSnowGarmisch'>¶
-
Obergurgl
= <class 'core.dataset.ProSnowObergurgl'>¶
-
Sparcs
= <class 'core.dataset.SparcsDataset'>¶
-
core.graphics module¶
Functions to plot multispectral image data and model output.
License¶
Copyright (c) 2020 Daniel Frisinghelli
This source code is licensed under the GNU General Public License v3.
See the LICENSE file in the repository’s root directory.
-
core.graphics.
contrast_stretching
(image, alpha=5)[source]¶ Apply percentile stretching to an image to increase constrast.
- Parameters
image (numpy.ndarray) – the input image.
alpha (int, optional) – The level of the percentiles. The default is 5.
- Returns
norm – the stretched image.
- Return type
numpy.ndarray
-
core.graphics.
plot_confusion_matrix
(cm, labels, normalize=True, figsize=10, 10, cmap='Blues', state=None, outpath='c:\\eurac\\2020\\git\\pysegcnn\\pysegcnn\\main\\_graphics/')[source]¶ Plot the confusion matrix
cm
.- Parameters
cm (numpy.ndarray) – The confusion matrix.
labels (dict [int, dict]) –
The label dictionary. The keys are the values of the class labels in the ground truth
y
. Each nested dict should have keys:'color'
A named color (str).
'label'
The name of the class label (str).
normalize (bool, optional) – Whether to normalize the confusion matrix. The default is True.
figsize (tuple, optional) – The figure size in centimeters. The default is (10, 10).
cmap (str, optional) – A colormap in matplotlib.pyplot.colormaps(). The default is ‘Blues’.
state (str or None, optional) – Filename to save the plot to.
state
should be an existing model state file ending with ‘.pt’. The default is None, i.e. plot is not saved to disk.outpath (str or pathlib.Path, optional) – Output path. The default is ‘pysegcnn/main/_graphics/’.
- Returns
fig (matplotlib.figure.Figure) – The figure handle.
ax (matplotlib.axes._subplots.AxesSubplot) – The axes handle.
-
core.graphics.
plot_loss
(state_file, figsize=10, 10, step=5, colors=['lightgreen', 'green', 'skyblue', 'steelblue'], outpath='c:\\eurac\\2020\\git\\pysegcnn\\pysegcnn\\main\\_graphics/')[source]¶ Plot the observed loss and accuracy of a model run.
- Parameters
state_file (str or pathlib.Path) – The model state file. Model state files are stored in pysegcnn/main/_models.
figsize (tuple, optional) – The figure size in centimeters. The default is (10, 10).
step (int, optional) – The step of epochs for the x-axis labels. The default is 5, i.e. label each fifth epoch.
colors (list [str], optional) – A list of four named colors supported by matplotlib. The default is [‘lightgreen’, ‘green’, ‘skyblue’, ‘steelblue’].
outpath (str or pathlib.Path, optional) – Output path. The default is ‘pysegcnn/main/_graphics/’.
- Returns
fig – The figure handle.
- Return type
matplotlib.figure.Figure
-
core.graphics.
plot_sample
(x, use_bands, labels, y=None, y_pred=None, figsize=10, 10, bands=['nir', 'red', 'green'], state=None, outpath='c:\\eurac\\2020\\git\\pysegcnn\\pysegcnn\\main\\_samples/', alpha=0)[source]¶ Plot false color composite (FCC), ground truth and model prediction.
- Parameters
x (numpy.ndarray or torch.Tensor, (b, h, w)) – Array containing the raw data of the tile, shape=(bands, height, width)
use_bands (list of str) – List describing the order of the bands in
x
.labels (dict [int, dict]) –
The label dictionary. The keys are the values of the class labels in the ground truth
y
. Each nested dict should have keys:'color'
A named color (str).
'label'
The name of the class label (str).
y (numpy.ndarray or torch.Tensor or None, optional) – Array containing the ground truth of tile
x
, shape=(height, width). The default is None.y_pred (numpy.ndarray or torch.Tensor or None, optional) – Array containing the prediction for tile
x
, shape=(height, width). The default is None.figsize (tuple, optional) – The figure size in centimeters. The default is (10, 10).
bands (list [str], optional) – The bands to build the FCC. The default is [‘nir’, ‘red’, ‘green’].
state (str or None, optional) – Filename to save the plot to.
state
should be an existing model state file ending with ‘.pt’. The default is None, i.e. plot is not saved to disk.outpath (str or pathlib.Path, optional) – Output path. The default is ‘pysegcnn/main/_samples’.
alpha (int, optional) – The level of the percentiles to increase constrast in the FCC. The default is 0, i.e. no stretching.
- Returns
fig (matplotlib.figure.Figure) – The figure handle.
ax (numpy.ndarray [matplotlib.axes._subplots.AxesSubplot]) – An array of the axes handles.
core.layers module¶
Layers of a convolutional encoder-decoder network.
License¶
Copyright (c) 2020 Daniel Frisinghelli
This source code is licensed under the GNU General Public License v3.
See the LICENSE file in the repository’s root directory.
-
class
core.layers.
Block
(in_channels, out_channels, **kwargs)[source]¶ Bases:
torch.nn.modules.module.Module
Basic convolutional block.
- Parameters
in_channels (int) – Number of input channels.
out_channels (int) – Number of output channels.
**kwargs (‘dict’ [str]) – Additional arguments passed to pysegcnn.core.layers.Conv2dSame.
- Raises
TypeError – Raised if ~pysegcnn.core.layers.Block.layers method does not return an instance of torch.nn.Sequential.
- Returns
- Return type
None.
Methods
add_module
(name, module)Adds a child module to the current module.
apply
(fn)Applies
fn
recursively to every submodule (as returned by.children()
) as well as self.bfloat16
()Casts all floating point parameters and buffers to
bfloat16
datatype.buffers
([recurse])Returns an iterator over module buffers.
children
()Returns an iterator over immediate children modules.
cpu
()Moves all model parameters and buffers to the CPU.
cuda
([device])Moves all model parameters and buffers to the GPU.
double
()Casts all floating point parameters and buffers to
double
datatype.eval
()Sets the module in evaluation mode.
extra_repr
()Set the extra representation of the module
float
()Casts all floating point parameters and buffers to float datatype.
forward
()Forward pass of the block.
half
()Casts all floating point parameters and buffers to
half
datatype.layers
()Define the layers of the block.
load_state_dict
(state_dict[, strict])Copies parameters and buffers from
state_dict
into this module and its descendants.modules
()Returns an iterator over all modules in the network.
named_buffers
([prefix, recurse])Returns an iterator over module buffers, yielding both the name of the buffer as well as the buffer itself.
named_children
()Returns an iterator over immediate children modules, yielding both the name of the module as well as the module itself.
named_modules
([memo, prefix])Returns an iterator over all modules in the network, yielding both the name of the module as well as the module itself.
named_parameters
([prefix, recurse])Returns an iterator over module parameters, yielding both the name of the parameter as well as the parameter itself.
parameters
([recurse])Returns an iterator over module parameters.
register_backward_hook
(hook)Registers a backward hook on the module.
register_buffer
(name, tensor[, persistent])Adds a buffer to the module.
register_forward_hook
(hook)Registers a forward hook on the module.
register_forward_pre_hook
(hook)Registers a forward pre-hook on the module.
register_parameter
(name, param)Adds a parameter to the module.
requires_grad_
([requires_grad])Change if autograd should record operations on parameters in this module.
state_dict
([destination, prefix, keep_vars])Returns a dictionary containing a whole state of the module.
to
(*args, **kwargs)Moves and/or casts the parameters and buffers.
train
([mode])Sets the module in training mode.
type
(dst_type)Casts all parameters and buffers to
dst_type
.zero_grad
()Sets gradients of all model parameters to zero.
__call__
share_memory
-
forward
()[source]¶ Forward pass of the block.
- Raises
NotImplementedError – Raised if pysegcnn.core.layers.Block is not inherited.
- Returns
- Return type
None.
-
layers
()[source]¶ Define the layers of the block.
- Raises
NotImplementedError – Raised if pysegcnn.core.layers.Block is not inherited.
- Returns
layers – Return an instance of torch.nn.Sequential containing a sequence of layer (torch.nn.Module ) instances.
- Return type
torch.nn.Sequential [torch.nn.Module]
-
training
: bool¶
-
class
core.layers.
Conv2dSame
(*args, **kwargs)[source]¶ Bases:
torch.nn.modules.conv.Conv2d
A convolution preserving the shape of its input.
Given the kernel size, the dilation and a stride of 1, the padding is calculated such that the output of the convolution has the same spatial dimensions as the input.
- Parameters
*args (list [str]) –
- positional arguments passed to torch.nn.Conv2d:
'in_channels'
: intNumber of input channels.
'out_channels'
: intNumber of output channels.
'kernel_size'
: int or tuple [int]Size of the convolving kernel.
**kwargs (‘dict’ [str]) – Additional keyword arguments passed to `torch.nn.Conv2d`_.
_torch.nn.Conv2d (.) – https://pytorch.org/docs/stable/generated/torch.nn.Conv2d.html#torch.nn.Conv2d
- Returns
- Return type
None.
Methods
add_module
(name, module)Adds a child module to the current module.
apply
(fn)Applies
fn
recursively to every submodule (as returned by.children()
) as well as self.bfloat16
()Casts all floating point parameters and buffers to
bfloat16
datatype.buffers
([recurse])Returns an iterator over module buffers.
children
()Returns an iterator over immediate children modules.
cpu
()Moves all model parameters and buffers to the CPU.
cuda
([device])Moves all model parameters and buffers to the GPU.
double
()Casts all floating point parameters and buffers to
double
datatype.eval
()Sets the module in evaluation mode.
extra_repr
()Set the extra representation of the module
float
()Casts all floating point parameters and buffers to float datatype.
half
()Casts all floating point parameters and buffers to
half
datatype.load_state_dict
(state_dict[, strict])Copies parameters and buffers from
state_dict
into this module and its descendants.modules
()Returns an iterator over all modules in the network.
named_buffers
([prefix, recurse])Returns an iterator over module buffers, yielding both the name of the buffer as well as the buffer itself.
named_children
()Returns an iterator over immediate children modules, yielding both the name of the module as well as the module itself.
named_modules
([memo, prefix])Returns an iterator over all modules in the network, yielding both the name of the module as well as the module itself.
named_parameters
([prefix, recurse])Returns an iterator over module parameters, yielding both the name of the parameter as well as the parameter itself.
parameters
([recurse])Returns an iterator over module parameters.
register_backward_hook
(hook)Registers a backward hook on the module.
register_buffer
(name, tensor[, persistent])Adds a buffer to the module.
register_forward_hook
(hook)Registers a forward hook on the module.
register_forward_pre_hook
(hook)Registers a forward pre-hook on the module.
register_parameter
(name, param)Adds a parameter to the module.
requires_grad_
([requires_grad])Change if autograd should record operations on parameters in this module.
same_padding
(d, k)Calculate the amount of padding.
state_dict
([destination, prefix, keep_vars])Returns a dictionary containing a whole state of the module.
to
(*args, **kwargs)Moves and/or casts the parameters and buffers.
train
([mode])Sets the module in training mode.
type
(dst_type)Casts all parameters and buffers to
dst_type
.zero_grad
()Sets gradients of all model parameters to zero.
__call__
forward
reset_parameters
share_memory
-
bias
: Optional[torch.Tensor]¶
-
dilation
: Tuple[int, …]¶
-
groups
: int¶
-
kernel_size
: Tuple[int, …]¶
-
out_channels
: int¶
-
output_padding
: Tuple[int, …]¶
-
padding
: Tuple[int, …]¶
-
padding_mode
: str¶
-
static
same_padding
(d, k)[source]¶ Calculate the amount of padding.
- Parameters
d (int) – The dilation of the convolution.
k (int) – The kernel size.
- Returns
p – the amount of padding.
- Return type
int
-
stride
: Tuple[int, …]¶
-
transposed
: bool¶
-
weight
: torch.Tensor¶
-
class
core.layers.
ConvBnReluMaxPool
(in_channels, out_channels, **kwargs)[source]¶ Bases:
core.layers.EncoderBlock
Block of convolution, batchnorm, relu and 2x2 max pool.
- Parameters
in_channels (int) – Number of input channels.
out_channels (int) – Number of output channels.
**kwargs (‘dict’ [str]) – Additional keyword arguments passed to pysegcnn.core.layers.Conv2dSame.
- Returns
- Return type
None.
Methods
add_module
(name, module)Adds a child module to the current module.
apply
(fn)Applies
fn
recursively to every submodule (as returned by.children()
) as well as self.bfloat16
()Casts all floating point parameters and buffers to
bfloat16
datatype.buffers
([recurse])Returns an iterator over module buffers.
children
()Returns an iterator over immediate children modules.
cpu
()Moves all model parameters and buffers to the CPU.
cuda
([device])Moves all model parameters and buffers to the GPU.
double
()Casts all floating point parameters and buffers to
double
datatype.downsample
(x)2x2 max pooling layer, torch.nn.functional.max_pool2d.
eval
()Sets the module in evaluation mode.
Define optional extra information about this module.
float
()Casts all floating point parameters and buffers to float datatype.
forward
(x)Forward pass of an encoder block.
half
()Casts all floating point parameters and buffers to
half
datatype.layers
()Sequence of convolution, batchnorm and relu layers.
load_state_dict
(state_dict[, strict])Copies parameters and buffers from
state_dict
into this module and its descendants.modules
()Returns an iterator over all modules in the network.
named_buffers
([prefix, recurse])Returns an iterator over module buffers, yielding both the name of the buffer as well as the buffer itself.
named_children
()Returns an iterator over immediate children modules, yielding both the name of the module as well as the module itself.
named_modules
([memo, prefix])Returns an iterator over all modules in the network, yielding both the name of the module as well as the module itself.
named_parameters
([prefix, recurse])Returns an iterator over module parameters, yielding both the name of the parameter as well as the parameter itself.
parameters
([recurse])Returns an iterator over module parameters.
register_backward_hook
(hook)Registers a backward hook on the module.
register_buffer
(name, tensor[, persistent])Adds a buffer to the module.
register_forward_hook
(hook)Registers a forward hook on the module.
register_forward_pre_hook
(hook)Registers a forward pre-hook on the module.
register_parameter
(name, param)Adds a parameter to the module.
requires_grad_
([requires_grad])Change if autograd should record operations on parameters in this module.
state_dict
([destination, prefix, keep_vars])Returns a dictionary containing a whole state of the module.
to
(*args, **kwargs)Moves and/or casts the parameters and buffers.
train
([mode])Sets the module in training mode.
type
(dst_type)Casts all parameters and buffers to
dst_type
.zero_grad
()Sets gradients of all model parameters to zero.
__call__
share_memory
-
downsample
(x)[source]¶ 2x2 max pooling layer, torch.nn.functional.max_pool2d.
- Parameters
x (torch.Tensor, shape=(batch, channel, height, width)) – Input tensor.
- Returns
x (torch.Tensor, shape=(batch, channel, height // 2, width // 2)) – The 2x2 max pooled tensor.
indices (torch.Tensor or None) – The indices of the maxima. Useful for upsampling with torch.nn.functional.max_unpool2d.
-
extra_repr
()[source]¶ Define optional extra information about this module.
- Returns
Extra representation string.
- Return type
str
-
layers
()[source]¶ Sequence of convolution, batchnorm and relu layers.
- Returns
layers – An instance of torch.nn.Sequential containing the sequence of convolution, batchnorm and relu layer (torch.nn.Module) instances.
- Return type
torch.nn.Sequential [torch.nn.Module]
-
training
: bool¶
-
class
core.layers.
ConvBnReluMaxUnpool
(in_channels, out_channels, **kwargs)[source]¶ Bases:
core.layers.DecoderBlock
Block of convolution, batchnorm, relu and 2x2 max unpool.
- Parameters
in_channels (int) – Number of input channels.
out_channels (int) – Number of output channels
**kwargs (‘dict’ [str]) – Additional keyword arguments passed to pysegcnn.core.layers.Conv2dSame.
- Returns
- Return type
None.
Methods
add_module
(name, module)Adds a child module to the current module.
apply
(fn)Applies
fn
recursively to every submodule (as returned by.children()
) as well as self.bfloat16
()Casts all floating point parameters and buffers to
bfloat16
datatype.buffers
([recurse])Returns an iterator over module buffers.
children
()Returns an iterator over immediate children modules.
cpu
()Moves all model parameters and buffers to the CPU.
cuda
([device])Moves all model parameters and buffers to the GPU.
double
()Casts all floating point parameters and buffers to
double
datatype.eval
()Sets the module in evaluation mode.
Define optional extra information about this module.
float
()Casts all floating point parameters and buffers to float datatype.
forward
(x, feature, indices, skip)Forward pass of a decoder block.
half
()Casts all floating point parameters and buffers to
half
datatype.layers
()Sequence of convolution, batchnorm and relu layers.
load_state_dict
(state_dict[, strict])Copies parameters and buffers from
state_dict
into this module and its descendants.modules
()Returns an iterator over all modules in the network.
named_buffers
([prefix, recurse])Returns an iterator over module buffers, yielding both the name of the buffer as well as the buffer itself.
named_children
()Returns an iterator over immediate children modules, yielding both the name of the module as well as the module itself.
named_modules
([memo, prefix])Returns an iterator over all modules in the network, yielding both the name of the module as well as the module itself.
named_parameters
([prefix, recurse])Returns an iterator over module parameters, yielding both the name of the parameter as well as the parameter itself.
parameters
([recurse])Returns an iterator over module parameters.
register_backward_hook
(hook)Registers a backward hook on the module.
register_buffer
(name, tensor[, persistent])Adds a buffer to the module.
register_forward_hook
(hook)Registers a forward hook on the module.
register_forward_pre_hook
(hook)Registers a forward pre-hook on the module.
register_parameter
(name, param)Adds a parameter to the module.
requires_grad_
([requires_grad])Change if autograd should record operations on parameters in this module.
state_dict
([destination, prefix, keep_vars])Returns a dictionary containing a whole state of the module.
to
(*args, **kwargs)Moves and/or casts the parameters and buffers.
train
([mode])Sets the module in training mode.
type
(dst_type)Casts all parameters and buffers to
dst_type
.upsample
(x, feature, indices)2x2 max unpooling layer.
zero_grad
()Sets gradients of all model parameters to zero.
__call__
share_memory
-
extra_repr
()[source]¶ Define optional extra information about this module.
- Returns
Extra representation string.
- Return type
str
-
layers
()[source]¶ Sequence of convolution, batchnorm and relu layers.
- Returns
layers – An instance of torch.nn.Sequential containing the sequence of convolution, batchnorm and relu layer (torch.nn.Module) instances.
- Return type
torch.nn.Sequential [torch.nn.Module]
-
training
: bool¶
-
upsample
(x, feature, indices)[source]¶ 2x2 max unpooling layer.
- Parameters
x (torch.Tensor, shape=(batch, channel, height, width)) – Input tensor.
feature (torch.Tensor, shape=(batch, channel, height, width)) – Intermediate output of a layer in the encoder. Used to determine the output shape of the upsampling operation.
indices (torch.Tensor) – The indices of the maxima of the max pooling operation (as returned by torch.nn.functional.max_pool2d).
- Returns
x – The 2x2 max unpooled tensor.
- Return type
torch.Tensor, shape=(batch, channel, height * 2, width * 2)
-
class
core.layers.
ConvBnReluUpsample
(in_channels, out_channels, **kwargs)[source]¶ Bases:
core.layers.DecoderBlock
Block of convolution, batchnorm, relu and nearest neighbor upsampling.
- Parameters
in_channels (int) – Number of input channels.
out_channels (int) – Number of output channels
**kwargs (‘dict’ [str]) – Additional arguments passed to pysegcnn.core.layers.Conv2dSame.
- Returns
- Return type
None.
Methods
add_module
(name, module)Adds a child module to the current module.
apply
(fn)Applies
fn
recursively to every submodule (as returned by.children()
) as well as self.bfloat16
()Casts all floating point parameters and buffers to
bfloat16
datatype.buffers
([recurse])Returns an iterator over module buffers.
children
()Returns an iterator over immediate children modules.
cpu
()Moves all model parameters and buffers to the CPU.
cuda
([device])Moves all model parameters and buffers to the GPU.
double
()Casts all floating point parameters and buffers to
double
datatype.eval
()Sets the module in evaluation mode.
Define optional extra information about this module.
float
()Casts all floating point parameters and buffers to float datatype.
forward
(x, feature, indices, skip)Forward pass of a decoder block.
half
()Casts all floating point parameters and buffers to
half
datatype.layers
()Sequence of convolution, batchnorm and relu layers.
load_state_dict
(state_dict[, strict])Copies parameters and buffers from
state_dict
into this module and its descendants.modules
()Returns an iterator over all modules in the network.
named_buffers
([prefix, recurse])Returns an iterator over module buffers, yielding both the name of the buffer as well as the buffer itself.
named_children
()Returns an iterator over immediate children modules, yielding both the name of the module as well as the module itself.
named_modules
([memo, prefix])Returns an iterator over all modules in the network, yielding both the name of the module as well as the module itself.
named_parameters
([prefix, recurse])Returns an iterator over module parameters, yielding both the name of the parameter as well as the parameter itself.
parameters
([recurse])Returns an iterator over module parameters.
register_backward_hook
(hook)Registers a backward hook on the module.
register_buffer
(name, tensor[, persistent])Adds a buffer to the module.
register_forward_hook
(hook)Registers a forward hook on the module.
register_forward_pre_hook
(hook)Registers a forward pre-hook on the module.
register_parameter
(name, param)Adds a parameter to the module.
requires_grad_
([requires_grad])Change if autograd should record operations on parameters in this module.
state_dict
([destination, prefix, keep_vars])Returns a dictionary containing a whole state of the module.
to
(*args, **kwargs)Moves and/or casts the parameters and buffers.
train
([mode])Sets the module in training mode.
type
(dst_type)Casts all parameters and buffers to
dst_type
.upsample
(x, feature[, indices])Nearest neighbor upsampling.
zero_grad
()Sets gradients of all model parameters to zero.
__call__
share_memory
-
extra_repr
()[source]¶ Define optional extra information about this module.
- Returns
Extra representation string.
- Return type
str
-
layers
()[source]¶ Sequence of convolution, batchnorm and relu layers.
- Returns
layers – An instance of torch.nn.Sequential containing the sequence of convolution, batchnorm and relu layer (torch.nn.Module) instances.
- Return type
torch.nn.Sequential [torch.nn.Module]
-
training
: bool¶
-
upsample
(x, feature, indices=None)[source]¶ Nearest neighbor upsampling.
- Parameters
x (torch.Tensor, shape=(batch, channel, height, width)) – Input tensor.
feature (torch.Tensor, shape=(batch, channel, height, width)) – Intermediate output of a layer in the encoder. Used to determine the output shape of the upsampling operation.
indices (None, optional) – The indices of the maxima of the max pooling operation (as returned by torch.nn.functional.max_pool2d). Not required by this upsampling method.
- Returns
x – The 2x2 upsampled tensor.
- Return type
torch.Tensor, shape=(batch, channel, height, width)
-
class
core.layers.
Decoder
(filters, block, skip=True, **kwargs)[source]¶ Bases:
torch.nn.modules.module.Module
Generic convolutional decoder.
When instanciating an encoder-decoder architechure,
filters
should be the same for pysegcnn.core.layers.Encoder and pysegcnn.core.layers.Decoder.See pysegcnn.core.models.UNet for an example implementation.
- Parameters
filters (list [int]) – List of input channels to each convolutional block. The length of
filters
determines the depth of the decoder. The first element offilters
has to be the number of channels of the input images.block (pysegcnn.core.layers.DecoderBlock) – The convolutional block defining a layer in the decoder. A subclass of pysegcnn.core.layers.DecoderBlock, e.g. pysegcnn.core.layers.ConvBnReluMaxUnpool.
skip (bool) – Whether to apply skip connections from the encoder to the decoder.
**kwargs (‘dict’ [str]) – Additional arguments passed to pysegcnn.core.layers.Conv2dSame.
- Returns
- Return type
None.
Methods
add_module
(name, module)Adds a child module to the current module.
apply
(fn)Applies
fn
recursively to every submodule (as returned by.children()
) as well as self.bfloat16
()Casts all floating point parameters and buffers to
bfloat16
datatype.buffers
([recurse])Returns an iterator over module buffers.
children
()Returns an iterator over immediate children modules.
cpu
()Moves all model parameters and buffers to the CPU.
cuda
([device])Moves all model parameters and buffers to the GPU.
double
()Casts all floating point parameters and buffers to
double
datatype.eval
()Sets the module in evaluation mode.
extra_repr
()Set the extra representation of the module
float
()Casts all floating point parameters and buffers to float datatype.
forward
(x, enc_cache)Forward pass of the decoder.
half
()Casts all floating point parameters and buffers to
half
datatype.load_state_dict
(state_dict[, strict])Copies parameters and buffers from
state_dict
into this module and its descendants.modules
()Returns an iterator over all modules in the network.
named_buffers
([prefix, recurse])Returns an iterator over module buffers, yielding both the name of the buffer as well as the buffer itself.
named_children
()Returns an iterator over immediate children modules, yielding both the name of the module as well as the module itself.
named_modules
([memo, prefix])Returns an iterator over all modules in the network, yielding both the name of the module as well as the module itself.
named_parameters
([prefix, recurse])Returns an iterator over module parameters, yielding both the name of the parameter as well as the parameter itself.
parameters
([recurse])Returns an iterator over module parameters.
register_backward_hook
(hook)Registers a backward hook on the module.
register_buffer
(name, tensor[, persistent])Adds a buffer to the module.
register_forward_hook
(hook)Registers a forward hook on the module.
register_forward_pre_hook
(hook)Registers a forward pre-hook on the module.
register_parameter
(name, param)Adds a parameter to the module.
requires_grad_
([requires_grad])Change if autograd should record operations on parameters in this module.
state_dict
([destination, prefix, keep_vars])Returns a dictionary containing a whole state of the module.
to
(*args, **kwargs)Moves and/or casts the parameters and buffers.
train
([mode])Sets the module in training mode.
type
(dst_type)Casts all parameters and buffers to
dst_type
.zero_grad
()Sets gradients of all model parameters to zero.
__call__
share_memory
-
forward
(x, enc_cache)[source]¶ Forward pass of the decoder.
- Parameters
x (torch.Tensor, shape=(batch, channel, height, width)) – Output of the encoder.
enc_cache (dict [dict]) –
Cache dictionary. The keys of the dictionary are the number of the network layers and the values are dictionaries with the following (key, value) pairs:
"feature"
The intermediate encoder outputs (torch.Tensor).
"indices"
The indices of the max pooling layer (torch.Tensor).
- Returns
x – Output of the decoder.
- Return type
torch.Tensor, shape=(batch, channel, height, width)
-
training
: bool¶
-
class
core.layers.
DecoderBlock
(in_channels, out_channels, **kwargs)[source]¶ Bases:
core.layers.Block
Block of a convolutional decoder.
- Parameters
in_channels (int) – Number of input channels.
out_channels (int) – Number of output channels.
**kwargs (‘dict’ [str]) – Additional arguments passed to pysegcnn.core.layers.Conv2dSame.
- Returns
- Return type
None.
Methods
add_module
(name, module)Adds a child module to the current module.
apply
(fn)Applies
fn
recursively to every submodule (as returned by.children()
) as well as self.bfloat16
()Casts all floating point parameters and buffers to
bfloat16
datatype.buffers
([recurse])Returns an iterator over module buffers.
children
()Returns an iterator over immediate children modules.
cpu
()Moves all model parameters and buffers to the CPU.
cuda
([device])Moves all model parameters and buffers to the GPU.
double
()Casts all floating point parameters and buffers to
double
datatype.eval
()Sets the module in evaluation mode.
extra_repr
()Set the extra representation of the module
float
()Casts all floating point parameters and buffers to float datatype.
forward
(x, feature, indices, skip)Forward pass of a decoder block.
half
()Casts all floating point parameters and buffers to
half
datatype.layers
()Define the layers of the block.
load_state_dict
(state_dict[, strict])Copies parameters and buffers from
state_dict
into this module and its descendants.modules
()Returns an iterator over all modules in the network.
named_buffers
([prefix, recurse])Returns an iterator over module buffers, yielding both the name of the buffer as well as the buffer itself.
named_children
()Returns an iterator over immediate children modules, yielding both the name of the module as well as the module itself.
named_modules
([memo, prefix])Returns an iterator over all modules in the network, yielding both the name of the module as well as the module itself.
named_parameters
([prefix, recurse])Returns an iterator over module parameters, yielding both the name of the parameter as well as the parameter itself.
parameters
([recurse])Returns an iterator over module parameters.
register_backward_hook
(hook)Registers a backward hook on the module.
register_buffer
(name, tensor[, persistent])Adds a buffer to the module.
register_forward_hook
(hook)Registers a forward hook on the module.
register_forward_pre_hook
(hook)Registers a forward pre-hook on the module.
register_parameter
(name, param)Adds a parameter to the module.
requires_grad_
([requires_grad])Change if autograd should record operations on parameters in this module.
state_dict
([destination, prefix, keep_vars])Returns a dictionary containing a whole state of the module.
to
(*args, **kwargs)Moves and/or casts the parameters and buffers.
train
([mode])Sets the module in training mode.
type
(dst_type)Casts all parameters and buffers to
dst_type
.upsample
(x, feature, indices)Define the upsampling method.
zero_grad
()Sets gradients of all model parameters to zero.
__call__
share_memory
-
forward
(x, feature, indices, skip)[source]¶ Forward pass of a decoder block.
- Parameters
x (torch.Tensor, shape=(batch, channel, height, width)) – Input tensor.
feature (torch.Tensor, shape=(batch, channel, height, width)) – Intermediate output of a layer in the encoder. If
skip
= True,feature
is concatenated (along the channel axis) to the output of the respective upsampling layer in the decoder (skip connection).indices (torch.Tensor or None) – Indices of the encoder downsampling method.
skip (bool) – Whether to apply the skip connection.
- Returns
x – Output of the decoder block.
- Return type
torch.Tensor, shape=(batch, channel, height, width)
-
training
: bool¶
-
upsample
(x, feature, indices)[source]¶ Define the upsampling method.
The ~pysegcnn.core.layers.DecoderBlock.upsample method should implement the spatial upsampling operation.
- Use one of the following functions to upsample:
torch.nn.functional.max_unpool2d
torch.nn.functional.interpolate
See pysegcnn.core.layers.ConvBnReluMaxUnpool or pysegcnn.core.layers.ConvBnReluUpsample for an example implementation.
- Parameters
x (torch.Tensor, shape=(batch, channel, height, width)) – Input tensor, e.g. output of a convolutional block.
feature (torch.Tensor, shape=(batch, channel, height, width)) – Intermediate output of a layer in the encoder. Used to implement skip connections.
indices (torch.Tensor or None) – Indices of the encoder downsampling method.
- Raises
NotImplementedError – Raised if pysegcnn.core.layers.DecoderBlock is not inherited.
- Returns
x – The spatially upsampled tensor.
- Return type
torch.Tensor, shape=(batch, channel, height, width)
-
class
core.layers.
Encoder
(filters, block, **kwargs)[source]¶ Bases:
torch.nn.modules.module.Module
Generic convolutional encoder.
When instanciating an encoder-decoder architechure,
filters
should be the same for pysegcnn.core.layers.Encoder and pysegcnn.core.layers.Decoder.See pysegcnn.core.models.UNet for an example implementation.
- Parameters
filters (list [int]) – List of input channels to each convolutional block. The length of
filters
determines the depth of the encoder. The first element offilters
has to be the number of channels of the input images.block (pysegcnn.core.layers.EncoderBlock) – The convolutional block defining a layer in the encoder. A subclass of pysegcnn.core.layers.EncoderBlock, e.g. pysegcnn.core.layers.ConvBnReluMaxPool.
**kwargs (‘dict’ [str]) – Additional arguments passed to pysegcnn.core.layers.Conv2dSame.
- Returns
- Return type
None.
Methods
add_module
(name, module)Adds a child module to the current module.
apply
(fn)Applies
fn
recursively to every submodule (as returned by.children()
) as well as self.bfloat16
()Casts all floating point parameters and buffers to
bfloat16
datatype.buffers
([recurse])Returns an iterator over module buffers.
children
()Returns an iterator over immediate children modules.
cpu
()Moves all model parameters and buffers to the CPU.
cuda
([device])Moves all model parameters and buffers to the GPU.
double
()Casts all floating point parameters and buffers to
double
datatype.eval
()Sets the module in evaluation mode.
extra_repr
()Set the extra representation of the module
float
()Casts all floating point parameters and buffers to float datatype.
forward
(x)Forward pass of the encoder.
half
()Casts all floating point parameters and buffers to
half
datatype.load_state_dict
(state_dict[, strict])Copies parameters and buffers from
state_dict
into this module and its descendants.modules
()Returns an iterator over all modules in the network.
named_buffers
([prefix, recurse])Returns an iterator over module buffers, yielding both the name of the buffer as well as the buffer itself.
named_children
()Returns an iterator over immediate children modules, yielding both the name of the module as well as the module itself.
named_modules
([memo, prefix])Returns an iterator over all modules in the network, yielding both the name of the module as well as the module itself.
named_parameters
([prefix, recurse])Returns an iterator over module parameters, yielding both the name of the parameter as well as the parameter itself.
parameters
([recurse])Returns an iterator over module parameters.
register_backward_hook
(hook)Registers a backward hook on the module.
register_buffer
(name, tensor[, persistent])Adds a buffer to the module.
register_forward_hook
(hook)Registers a forward hook on the module.
register_forward_pre_hook
(hook)Registers a forward pre-hook on the module.
register_parameter
(name, param)Adds a parameter to the module.
requires_grad_
([requires_grad])Change if autograd should record operations on parameters in this module.
state_dict
([destination, prefix, keep_vars])Returns a dictionary containing a whole state of the module.
to
(*args, **kwargs)Moves and/or casts the parameters and buffers.
train
([mode])Sets the module in training mode.
type
(dst_type)Casts all parameters and buffers to
dst_type
.zero_grad
()Sets gradients of all model parameters to zero.
__call__
share_memory
-
forward
(x)[source]¶ Forward pass of the encoder.
Stores intermediate outputs in a dictionary. The keys of the dictionary are the number of the network layers and the values are dictionaries with the following (key, value) pairs:
"feature"
The intermediate encoder outputs (torch.Tensor).
"indices"
The indices of the max pooling layer, if required (torch.Tensor).
- Parameters
x (torch.Tensor, shape=(batch, channel, height, width)) – Input image.
- Returns
x – Output of the encoder.
- Return type
torch.Tensor, shape=(batch, channel, height, width)
-
training
: bool¶
-
class
core.layers.
EncoderBlock
(in_channels, out_channels, **kwargs)[source]¶ Bases:
core.layers.Block
Block of a convolutional encoder.
- Parameters
in_channels (int) – Number of input channels.
out_channels (int) – Number of output channels.
**kwargs (‘dict’ [str]) – Additional arguments passed to pysegcnn.core.layers.Conv2dSame.
- Returns
- Return type
None.
Methods
add_module
(name, module)Adds a child module to the current module.
apply
(fn)Applies
fn
recursively to every submodule (as returned by.children()
) as well as self.bfloat16
()Casts all floating point parameters and buffers to
bfloat16
datatype.buffers
([recurse])Returns an iterator over module buffers.
children
()Returns an iterator over immediate children modules.
cpu
()Moves all model parameters and buffers to the CPU.
cuda
([device])Moves all model parameters and buffers to the GPU.
double
()Casts all floating point parameters and buffers to
double
datatype.downsample
(x)Define the downsampling method.
eval
()Sets the module in evaluation mode.
extra_repr
()Set the extra representation of the module
float
()Casts all floating point parameters and buffers to float datatype.
forward
(x)Forward pass of an encoder block.
half
()Casts all floating point parameters and buffers to
half
datatype.layers
()Define the layers of the block.
load_state_dict
(state_dict[, strict])Copies parameters and buffers from
state_dict
into this module and its descendants.modules
()Returns an iterator over all modules in the network.
named_buffers
([prefix, recurse])Returns an iterator over module buffers, yielding both the name of the buffer as well as the buffer itself.
named_children
()Returns an iterator over immediate children modules, yielding both the name of the module as well as the module itself.
named_modules
([memo, prefix])Returns an iterator over all modules in the network, yielding both the name of the module as well as the module itself.
named_parameters
([prefix, recurse])Returns an iterator over module parameters, yielding both the name of the parameter as well as the parameter itself.
parameters
([recurse])Returns an iterator over module parameters.
register_backward_hook
(hook)Registers a backward hook on the module.
register_buffer
(name, tensor[, persistent])Adds a buffer to the module.
register_forward_hook
(hook)Registers a forward hook on the module.
register_forward_pre_hook
(hook)Registers a forward pre-hook on the module.
register_parameter
(name, param)Adds a parameter to the module.
requires_grad_
([requires_grad])Change if autograd should record operations on parameters in this module.
state_dict
([destination, prefix, keep_vars])Returns a dictionary containing a whole state of the module.
to
(*args, **kwargs)Moves and/or casts the parameters and buffers.
train
([mode])Sets the module in training mode.
type
(dst_type)Casts all parameters and buffers to
dst_type
.zero_grad
()Sets gradients of all model parameters to zero.
__call__
share_memory
-
downsample
(x)[source]¶ Define the downsampling method.
The ~pysegcnn.core.layers.EncoderBlock.downsample method should implement the spatial pooling operation.
- Use one of the following functions to downsample:
torch.nn.functional.max_pool2d
torch.nn.functional.interpolate
See pysegcnn.core.layers.ConvBnReluMaxPool for an example implementation.
- Parameters
x (torch.Tensor, shape=(batch, channel, height, width)) – Input tensor, e.g. output of a convolutional block.
- Raises
NotImplementedError – Raised if pysegcnn.core.layers.EncoderBlock is not inherited.
- Returns
x (torch.Tensor, shape=(batch, channel, height, width)) – The spatially downsampled tensor.
indices (torch.Tensor or None) – Optional indices of the downsampling method, e.g. indices of the maxima when using torch.nn.functional.max_pool2d. Useful for upsampling later. If no indices are required to upsample, simply return
indices
= None.
-
forward
(x)[source]¶ Forward pass of an encoder block.
- Parameters
x (torch.Tensor) – Input tensor, e.g. output of the previous block/layer.
- Returns
y (torch.Tensor, shape=(batch, channel, height, width)) – Output of the encoder block.
x (torch.Tensor, shape=(batch, channel, height, width)) – Intermediate output before applying downsampling. Useful to implement skip connections.
indices (torch.Tensor or None) – Optional indices of the downsampling method, e.g. indices of the maxima when using torch.nn.functional.max_pool2d. Useful for upsampling later. If no indices are required to upsample, simply return
indices
= None.
-
training
: bool¶
-
core.layers.
conv_bn_relu
(in_channels, out_channels, **kwargs)[source]¶ Block of convolution, batch normalization and rectified linear unit.
- Parameters
in_channels (int) – Number of input channels.
out_channels (int) – Number of output channels.
**kwargs (‘dict’ [str]) – Additional arguments passed to pysegcnn.core.layers.Conv2dSame.
- Returns
block – An instance of torch.nn.Sequential containing a sequence of convolution, batch normalization and rectified linear unit layers.
- Return type
torch.nn.Sequential [torch.nn.Module]
core.logging module¶
Logging configuration.
License¶
Copyright (c) 2020 Daniel Frisinghelli
This source code is licensed under the GNU General Public License v3.
See the LICENSE file in the repository’s root directory.
-
core.logging.
log_conf
(logfile)[source]¶ Set basic logging configuration passed to logging.config.dictConfig.
See the logging docs for a detailed description of the configuration dictionary.
- Parameters
logfile (str or pathlib.Path) – The file to save the logs to.
- Returns
LOGGING_CONFIG – The logging configuration.
- Return type
dict
core.models module¶
Neural networks for semantic image segmentation.
License¶
Copyright (c) 2020 Daniel Frisinghelli
This source code is licensed under the GNU General Public License v3.
See the LICENSE file in the repository’s root directory.
-
class
core.models.
Network
[source]¶ Bases:
torch.nn.modules.module.Module
Generic Network class.
The base class for each model. If you want to implement a new model, inherit the
~pysegcnn.core.models.Network
class.- Returns
- Return type
None.
- Attributes
state
Return the model state file.
Methods
add_module
(name, module)Adds a child module to the current module.
apply
(fn)Applies
fn
recursively to every submodule (as returned by.children()
) as well as self.bfloat16
()Casts all floating point parameters and buffers to
bfloat16
datatype.buffers
([recurse])Returns an iterator over module buffers.
children
()Returns an iterator over immediate children modules.
cpu
()Moves all model parameters and buffers to the CPU.
cuda
([device])Moves all model parameters and buffers to the GPU.
double
()Casts all floating point parameters and buffers to
double
datatype.eval
()Sets the module in evaluation mode.
extra_repr
()Set the extra representation of the module
float
()Casts all floating point parameters and buffers to float datatype.
forward
(*input)freeze
()Freeze the weights of a model.
half
()Casts all floating point parameters and buffers to
half
datatype.load
(state_file)Load a model state.
load_state_dict
(state_dict[, strict])Copies parameters and buffers from
state_dict
into this module and its descendants.modules
()Returns an iterator over all modules in the network.
named_buffers
([prefix, recurse])Returns an iterator over module buffers, yielding both the name of the buffer as well as the buffer itself.
named_children
()Returns an iterator over immediate children modules, yielding both the name of the module as well as the module itself.
named_modules
([memo, prefix])Returns an iterator over all modules in the network, yielding both the name of the module as well as the module itself.
named_parameters
([prefix, recurse])Returns an iterator over module parameters, yielding both the name of the parameter as well as the parameter itself.
parameters
([recurse])Returns an iterator over module parameters.
register_backward_hook
(hook)Registers a backward hook on the module.
register_buffer
(name, tensor[, persistent])Adds a buffer to the module.
register_forward_hook
(hook)Registers a forward hook on the module.
register_forward_pre_hook
(hook)Registers a forward pre-hook on the module.
register_parameter
(name, param)Adds a parameter to the module.
requires_grad_
([requires_grad])Change if autograd should record operations on parameters in this module.
save
(state_file, optimizer[, bands])Save the model state.
state_dict
([destination, prefix, keep_vars])Returns a dictionary containing a whole state of the module.
to
(*args, **kwargs)Moves and/or casts the parameters and buffers.
train
([mode])Sets the module in training mode.
type
(dst_type)Casts all parameters and buffers to
dst_type
.unfreeze
()Unfreeze the weights of a model.
zero_grad
()Sets gradients of all model parameters to zero.
__call__
share_memory
-
freeze
()[source]¶ Freeze the weights of a model.
Disables gradient computation: useful when using a pretrained model for inference.
- Returns
- Return type
None.
-
static
load
(state_file)[source]¶ Load a model state.
Returns the model in
state_file
with the pretrained model and optimizer weights. Useful when resuming training an existing model.- Parameters
state_file (str or pathlib.Path) – The model state file. Model state files are stored in pysegcnn/main/_models.
- Raises
FileNotFoundError – Raised if
state_file
does not exist.- Returns
model (pysegcnn.core.models.Network) – The pretrained model.
optimizer (torch.optim.Optimizer) – The optimizer used to train the model.
model_state (‘dict) – A dictionary containing the model and optimizer state, as constructed by ~pysegcnn.core.Network.save.
-
save
(state_file, optimizer, bands=None, **kwargs)[source]¶ Save the model state.
Saves the model and optimizer states together with the model construction parameters, to easily re-instanciate the model.
Optional
kwargs
are also saved.- Parameters
state_file (str or pathlib.Path) – Path to save the model state.
optimizer (torch.optim.Optimizer) – The optimizer used to train the model.
bands (list [str] or None, optional) – List of bands the model is trained with. The default is None.
**kwargs – Arbitrary keyword arguments. Each keyword argument will be saved as (key, value) pair in
state_file
.
- Returns
model_state – A dictionary containing the model and optimizer state
- Return type
dict
-
property
state
¶ Return the model state file.
- Returns
state_file – The model state file.
- Return type
pathlib.Path or None
-
training
: bool¶
-
class
core.models.
SupportedLossFunctions
(value)[source]¶ Bases:
enum.Enum
Names and corresponding classes of the tested loss functions.
-
CrossEntropy
= <class 'torch.nn.modules.loss.CrossEntropyLoss'>¶
-
-
class
core.models.
SupportedModels
(value)[source]¶ Bases:
enum.Enum
Names and corresponding classes of the implemented models.
-
Unet
= <class 'core.models.UNet'>¶
-
-
class
core.models.
SupportedOptimizers
(value)[source]¶ Bases:
enum.Enum
Names and corresponding classes of the tested optimizers.
-
Adam
= <class 'torch.optim.adam.Adam'>¶
-
-
class
core.models.
UNet
(in_channels, nclasses, filters, skip, **kwargs)[source]¶ Bases:
core.models.Network
A PyTorch implementation of U-Net.
- Slightly modified version of U-Net:
each convolution is followed by a batch normalization layer
the upsampling is implemented by a 2x2 max unpooling operation
- Parameters
in_channels (int) – Number of channels of the input images.
nclasses (int) – Number of classes.
filters (list [int]) – List of input channels to each convolutional block.
skip (bool) – Whether to apply skip connections from the encoder to the decoder.
**kwargs (‘dict’ [str]) – Additional keyword arguments passed to pysegcnn.core.layers.Conv2dSame.
- Returns
- Return type
None.
- Attributes
state
Return the model state file.
Methods
add_module
(name, module)Adds a child module to the current module.
apply
(fn)Applies
fn
recursively to every submodule (as returned by.children()
) as well as self.bfloat16
()Casts all floating point parameters and buffers to
bfloat16
datatype.buffers
([recurse])Returns an iterator over module buffers.
children
()Returns an iterator over immediate children modules.
cpu
()Moves all model parameters and buffers to the CPU.
cuda
([device])Moves all model parameters and buffers to the GPU.
double
()Casts all floating point parameters and buffers to
double
datatype.eval
()Sets the module in evaluation mode.
extra_repr
()Set the extra representation of the module
float
()Casts all floating point parameters and buffers to float datatype.
forward
(x)Forward propagation of U-Net.
freeze
()Freeze the weights of a model.
half
()Casts all floating point parameters and buffers to
half
datatype.load
(state_file)Load a model state.
load_state_dict
(state_dict[, strict])Copies parameters and buffers from
state_dict
into this module and its descendants.modules
()Returns an iterator over all modules in the network.
named_buffers
([prefix, recurse])Returns an iterator over module buffers, yielding both the name of the buffer as well as the buffer itself.
named_children
()Returns an iterator over immediate children modules, yielding both the name of the module as well as the module itself.
named_modules
([memo, prefix])Returns an iterator over all modules in the network, yielding both the name of the module as well as the module itself.
named_parameters
([prefix, recurse])Returns an iterator over module parameters, yielding both the name of the parameter as well as the parameter itself.
parameters
([recurse])Returns an iterator over module parameters.
register_backward_hook
(hook)Registers a backward hook on the module.
register_buffer
(name, tensor[, persistent])Adds a buffer to the module.
register_forward_hook
(hook)Registers a forward hook on the module.
register_forward_pre_hook
(hook)Registers a forward pre-hook on the module.
register_parameter
(name, param)Adds a parameter to the module.
requires_grad_
([requires_grad])Change if autograd should record operations on parameters in this module.
save
(state_file, optimizer[, bands])Save the model state.
state_dict
([destination, prefix, keep_vars])Returns a dictionary containing a whole state of the module.
to
(*args, **kwargs)Moves and/or casts the parameters and buffers.
train
([mode])Sets the module in training mode.
type
(dst_type)Casts all parameters and buffers to
dst_type
.unfreeze
()Unfreeze the weights of a model.
zero_grad
()Sets gradients of all model parameters to zero.
__call__
share_memory
-
forward
(x)[source]¶ Forward propagation of U-Net.
- Parameters
x (torch.Tensor) – The input image, shape=(batch_size, channels, height, width).
- Returns
y – The classified image, shape=(batch_size, height, width).
- Return type
‘torch.tensor’
-
training
: bool¶
core.predict module¶
Functions for model inference.
License¶
Copyright (c) 2020 Daniel Frisinghelli
This source code is licensed under the GNU General Public License v3.
See the LICENSE file in the repository’s root directory.
-
core.predict.
predict_samples
(ds, model, cm=False, plot=False, **kwargs)[source]¶ Classify each sample in
ds
with modelmodel
.- Parameters
ds (pysegcnn.core.split.RandomSubset or) –
pysegcnn.core.split.SceneSubset – An instance of ~pysegcnn.core.split.RandomSubset or ~pysegcnn.core.split.SceneSubset.
model (pysegcnn.core.models.Network) – An instance of ~pysegcnn.core.models.Network.
cm (bool, optional) – Whether to compute the confusion matrix. The default is False.
plot (bool, optional) – Whether to plot a false color composite, ground truth and model prediction for each sample. The default is False.
**kwargs – Additional keyword arguments passed to pysegcnn.core.graphics.plot_sample.
- Raises
TypeError – Raised if
ds
is not an instance of ~pysegcnn.core.split.RandomSubset or ~pysegcnn.core.split.SceneSubset.- Returns
output (dict) –
- Output dictionary with keys:
'input'
Model input data
'labels'
The ground truth
'prediction'
Model prediction
conf_mat (numpy.ndarray) – The confusion matrix. Note that the confusion matrix
conf_mat
is only computed ifcm
= True.
-
core.predict.
predict_scenes
(ds, model, scene_id=None, cm=False, plot=False, **kwargs)[source]¶ Classify each scene in
ds
with modelmodel
.- Parameters
ds (pysegcnn.core.split.SceneSubset) – An instance of ~pysegcnn.core.split.SceneSubset.
model (pysegcnn.core.models.Network) – An instance of ~pysegcnn.core.models.Network.
scene_id (str or None) – A valid scene identifier.
cm (bool, optional) – Whether to compute the confusion matrix. The default is False.
plot (bool, optional) – Whether to plot a false color composite, ground truth and model prediction for each scene. The default is False.
**kwargs – Additional keyword arguments passed to pysegcnn.core.graphics.plot_sample.
- Raises
TypeError – Raised if
ds
is not an instance of ~pysegcnn.core.split.SceneSubset.- Returns
output (dict) –
- Output dictionary with keys:
'input'
Model input data
'labels'
The ground truth
'prediction'
Model prediction
conf_mat (numpy.ndarray) – The confusion matrix. Note that the confusion matrix
conf_mat
is only computed ifcm
= True.
core.split module¶
Split the dataset into training, validation and test set.
License¶
Copyright (c) 2020 Daniel Frisinghelli
This source code is licensed under the GNU General Public License v3.
See the LICENSE file in the repository’s root directory.
-
class
core.split.
CustomSubset
(dataset, indices)[source]¶ Bases:
torch.utils.data.dataset.Subset
Custom subset inheriting torch.utils.data.Subset.
-
class
core.split.
DateSplit
(ds, date, dateformat)[source]¶ Bases:
core.split.Split
Split the dataset based on a date.
Class wrapper for pysegcnn.core.split.Split.date_scene_split.
- Parameters
ds (pysegcnn.core.dataset.ImageDataset) – An instance of ~pysegcnn.core.dataset.ImageDataset.
date ('str') – A date.
dateformat ('str', optional) – The format of
date
.dateformat
is used by datetime.datetime.strptime’ to parse ``date` to a datetime.datetime object. The default is ‘%Y%m%d’.
- Returns
- Return type
None.
Methods
split
()Split dataset into training, validation and test set.
Wrap pysegcnn.core.split.SceneSubset.
subsets
()Wrap pysegcnn.core.split.Split.date_scene_split.
-
class
core.split.
RandomSceneSplit
(ds, ttratio, tvratio, seed)[source]¶ Bases:
core.split.RandomSplit
Randomly split the dataset.
For each scene, all the tiles of the scene are included in either the training, validation or test set, respectively.
Class wrapper for pysegcnn.core.split.Split.random_scene_split.
- Parameters
ds (pysegcnn.core.dataset.ImageDataset) – An instance of ~pysegcnn.core.dataset.ImageDataset.
tvratio (float) – The ratio of training data to validation data, e.g.
tvratio
= 0.8 means 80% training, 20% validation.ttratio (float, optional) – The ratio of training and validation data to test data, e.g.
ttratio
= 0.6 means 60% for training and validation, 40% for testing. The default is 1.seed (int, optional) – The random seed for reproducibility. The default is 0.
- Returns
- Return type
None.
Methods
split
()Split dataset into training, validation and test set.
Wrap pysegcnn.core.split.SceneSubset.
subsets
()Wrap pysegcnn.core.split.Split.random_scene_split.
-
class
core.split.
RandomSplit
(ds, ttratio, tvratio, seed)[source]¶ Bases:
core.split.Split
Randomly split the dataset.
Generic class for random dataset splits.
- Parameters
ds (pysegcnn.core.dataset.ImageDataset) – An instance of ~pysegcnn.core.dataset.ImageDataset.
tvratio (float) – The ratio of training data to validation data, e.g.
tvratio
= 0.8 means 80% training, 20% validation.ttratio (float, optional) – The ratio of training and validation data to test data, e.g.
ttratio
= 0.6 means 60% for training and validation, 40% for testing. The default is 1.seed (int, optional) – The random seed for reproducibility. The default is 0.
- Returns
- Return type
None.
Methods
split
()Split dataset into training, validation and test set.
subset_type
()Define the type of each subset.
subsets
()Define training, validation and test sets.
-
class
core.split.
RandomSubset
(ds, indices, name, scenes, scene_ids)[source]¶ Bases:
core.split.CustomSubset
A custom subset for random dataset splits.
- Parameters
ds (pysegcnn.core.dataset.ImageDataset) – An instance of ~pysegcnn.core.dataset.ImageDataset.
indices (list [int]) – List of the subset indices to access
ds
.name (str) – Name of the subset.
scenes (list [dict]) – List of the subset tiles.
scene_ids (list or numpy.ndarray) – Container of the scene ids.
- Returns
- Return type
None.
-
class
core.split.
RandomTileSplit
(ds, ttratio, tvratio, seed)[source]¶ Bases:
core.split.RandomSplit
Randomly split the dataset.
For each scene, the tiles of the scene can be distributed among the training, validation and test set.
Class wrapper for pysegcnn.core.split.Split.random_tile_split.
- Parameters
ds (pysegcnn.core.dataset.ImageDataset) – An instance of ~pysegcnn.core.dataset.ImageDataset.
tvratio (float) – The ratio of training data to validation data, e.g.
tvratio
= 0.8 means 80% training, 20% validation.ttratio (float, optional) – The ratio of training and validation data to test data, e.g.
ttratio
= 0.6 means 60% for training and validation, 40% for testing. The default is 1.seed (int, optional) – The random seed for reproducibility. The default is 0.
- Returns
- Return type
None.
Methods
split
()Split dataset into training, validation and test set.
Wrap pysegcnn.core.split.RandomSubset.
subsets
()Wrap pysegcnn.core.split.Split.random_tile_split.
-
class
core.split.
SceneSubset
(ds, indices, name, scenes, scene_ids)[source]¶ Bases:
core.split.CustomSubset
A custom subset for dataset splits where the scenes are preserved.
- Parameters
ds (pysegcnn.core.dataset.ImageDataset) – An instance of ~pysegcnn.core.dataset.ImageDataset.
indices (list [int]) – List of the subset indices to access
ds
.name (str) – Name of the subset.
scenes (list [dict]) – List of the subset tiles.
scene_ids (list or numpy.ndarray) – Container of the scene ids.
- Returns
- Return type
None.
-
class
core.split.
Split
(ds)[source]¶ Bases:
object
Generic class handling how
ds
is split.Inherit ~pysegcnn.core.split.Split and implement the ~pysegcnn.core.split.Split.subsets and ~pysegcnn.core.split.Split.subset_type method.
- Parameters
ds (pysegcnn.core.dataset.ImageDataset) – An instance of ~pysegcnn.core.dataset.ImageDataset.
- Returns
- Return type
None.
Methods
split
()Split dataset into training, validation and test set.
Define the type of each subset.
subsets
()Define training, validation and test sets.
-
split
()[source]¶ Split dataset into training, validation and test set.
~pysegcnn.core.split.Split.split works only if ~pysegcnn.core.split.Split.subsets and ~pysegcnn.core.split.Split.subset_type are implemented.
-
subset_type
()[source]¶ Define the type of each subset.
Wrapper method for pysegcnn.core.split.RandomSubset or pysegcnn.core.split.SceneSubset.
- Raises
NotImplementedError – Raised if pysegcnn.core.split.Split is not inherited.
- Returns
- Return type
None.
-
subsets
()[source]¶ Define training, validation and test sets.
Wrapper method for pysegcnn.core.split.Split.random_tile_split, pysegcnn.core.split.Split.random_scene_split or pysegcnn.core.split.Split.date_scene_split.
- Raises
NotImplementedError – Raised if pysegcnn.core.split.Split is not inherited.
- Returns
- Return type
None.
-
class
core.split.
SupportedSplits
(value)[source]¶ Bases:
enum.Enum
Names and corresponding classes of the implemented split modes.
-
date
= <class 'core.split.DateSplit'>¶
-
random
= <class 'core.split.RandomTileSplit'>¶
-
scene
= <class 'core.split.RandomSceneSplit'>¶
-
-
core.split.
date_scene_split
(ds, date, dateformat='%Y%m%d')[source]¶ Split the dataset based on a date.
Scenes before
date
build the training set, scenes afterdate
build the validation set, the test set is empty.Useful for time series data.
- Parameters
ds (pysegcnn.core.dataset.ImageDataset) – An instance of ~pysegcnn.core.dataset.ImageDataset.
date (str) – A date.
dateformat (str, optional) – The format of
date
.dateformat
is used by datetime.datetime.strptime’ to parse ``date` to a datetime.datetime object. The default is ‘%Y%m%d’.
- Raises
AssertionError – Raised if the splits are not pairwise disjoint.
- Returns
subsets –
- Subset dictionary with keys:
'train'
dictionary containing the training scenes.
'valid'
dictionary containing the validation scenes.
'test'
dictionary containing the test scenes, empty.
- Return type
dict
-
core.split.
pairwise_disjoint
(sets)[source]¶ Check if
sets
are pairwise disjoint.Sets are pairwise disjoint if the length of their union equals the sum of their lengths.
- Parameters
sets (list [collections.Sized]) – A list of sized objects.
- Returns
disjoint – Whether the sets are pairwise disjoint.
- Return type
bool
-
core.split.
random_scene_split
(ds, tvratio, ttratio=1, seed=0)[source]¶ Randomly split the tiles of a dataset.
For each scene, all the tiles of the scene are included in either the training, validation or test set, respectively.
The parameters
ttratio
andtvratio
control the size of the training, validation and test datasets.Test dataset size : (1 -
ttratio
) * len(ds
) Train dataset size :ttratio
*tvratio
* len(ds
) Validation dataset size:ttratio
* (1 -tvratio
) * len(ds
)- Parameters
ds (pysegcnn.core.dataset.ImageDataset) – An instance of ~pysegcnn.core.dataset.ImageDataset.
tvratio (float) – The ratio of training data to validation data, e.g.
tvratio
= 0.8 means 80% training, 20% validation.ttratio (float, optional) – The ratio of training and validation data to test data, e.g.
ttratio
= 0.6 means 60% for training and validation, 40% for testing. The default is 1.seed (int, optional) – The random seed for reproducibility. The default is 0.
- Raises
AssertionError – Raised if the splits are not pairwise disjoint.
- Returns
subsets –
- Subset dictionary with keys:
'train'
dictionary containing the training scenes.
'valid'
dictionary containing the validation scenes.
'test'
dictionary containing the test scenes.
- Return type
dict
-
core.split.
random_tile_split
(ds, tvratio, ttratio=1, seed=0)[source]¶ Randomly split the tiles of a dataset.
For each scene, the tiles of the scene can be distributed among the training, validation and test set.
The parameters
ttratio
andtvratio
control the size of the training, validation and test datasets.Test dataset size : (1 -
ttratio
) * len(ds
) Train dataset size :ttratio
*tvratio
* len(ds
) Validation dataset size:ttratio
* (1 -tvratio
) * len(ds
)- Parameters
ds (pysegcnn.core.dataset.ImageDataset) – An instance of ~pysegcnn.core.dataset.ImageDataset.
tvratio (float) – The ratio of training data to validation data, e.g.
tvratio
= 0.8 means 80% training, 20% validation.ttratio (float, optional) – The ratio of training and validation data to test data, e.g.
ttratio
= 0.6 means 60% for training and validation, 40% for testing. The default is 1.seed (int, optional) – The random seed for reproducibility. The default is 0.
- Raises
AssertionError – Raised if the splits are not pairwise disjoint.
- Returns
subsets –
- Subset dictionary with keys:
'train'
dictionary containing the training scenes.
'valid'
dictionary containing the validation scenes.
'test'
dictionary containing the test scenes.
- Return type
dict
core.trainer module¶
Model configuration and training.
This module provides an end-to-end framework of dataclasses designed to train segmentation models on image datasets.
See pysegcnn/main/train.py for a complete walkthrough.
License¶
Copyright (c) 2020 Daniel Frisinghelli
This source code is licensed under the GNU General Public License v3.
See the LICENSE file in the repository’s root directory.
-
class
core.trainer.
BaseConfig
[source]¶ Bases:
object
Base dataclasses.dataclass for each configuration.
-
class
core.trainer.
DatasetConfig
(dataset_name: str, root_dir: pathlib.Path, bands: list, tile_size: int, gt_pattern: str, seed: int, sort: bool = False, transforms: list = <factory>, pad: bool = False)[source]¶ Bases:
core.trainer.BaseConfig
Dataset configuration class.
Instanciate a dataset.
- Parameters
dataset_name (str) – The name of the dataset.
root_dir (pathlib.Path) – The root directory, path to the dataset.
bands (list [str]) – A list of the spectral bands to use.
tile_size (int) – The size of the tiles. Each scene is divided into square tiles of shape (tile_size, tile_size).
gt_pattern (str) – A pattern to match the ground truth naming convention. All directories and subdirectories in
root_dir
are searched for files matchinggt_pattern
.seed (int) – The random seed. Used to split the dataset into training, validation and test set. Useful for reproducibility. The default is 0.
sort (bool, optional) – Whether to chronologically sort the samples. Useful for time series data. The default is False.
transforms (list [pysegcnn.core.split.Augment], optional) – List of pysegcnn.core.split.Augment instances. Each item in
transforms
generates a distinct transformed version of the dataset. The total dataset is composed of the original untransformed dataset together with each transformed version of it. Iftransforms
= [], only the original dataset is used. The default is [].pad (bool, optional) – Whether to center pad the input image. Set
pad
= True, if the images are not evenly divisible by thetile_size
. The image data is padded with a constant padding value of zero. For each image, the corresponding ground truth image is padded with a “no data” label. The default is False.
- Returns
- Return type
None.
Methods
Instanciate the dataset.
-
bands
: list¶
-
dataset_name
: str¶
-
gt_pattern
: str¶
-
init_dataset
()[source]¶ Instanciate the dataset.
- Returns
dataset – An instance of pysegcnn.core.dataset.ImageDataset.
- Return type
pysegcnn.core.dataset.ImageDataset
-
pad
: bool = False¶
-
root_dir
: pathlib.Path¶
-
seed
: int¶
-
sort
: bool = False¶
-
tile_size
: int¶
-
transforms
: list¶
-
class
core.trainer.
EarlyStopping
(mode='max', best=0, min_delta=0, patience=10)[source]¶ Bases:
object
`Early stopping`_ algorithm.
This implementation of the early stopping algorithm advances a counter each time a metric did not improve over a training epoch. If the metric does not improve over more than
patience
epochs, the early stopping criterion is met.See pysegcnn.core.trainer.NetworkTrainer.train for an example implementation.
- Parameters
mode (str, optional) – The mode of the early stopping. Depends on the metric measuring performance. When using model loss as metric, use
mode
= ‘min’, however, when using accuracy as metric, usemode
= ‘max’. The default is ‘max’.best (float, optional) – Threshold indicating the best metric score. At instanciation, set
best
to the worst possible score of the metric.best
will be overwritten during training. The default is 0.min_delta (float, optional) – Minimum change in early stopping metric to be considered as an improvement. The default is 0.
patience (int, optional) – The number of epochs to wait for an improvement in the early stopping metric. The default is 10.
- Raises
ValueError – Raised if
mode
is not either ‘min’ or ‘max’.- Returns
None.
.. _Early stopping – https://en.wikipedia.org/wiki/Early_stopping
Methods
decreased
(metric, best, min_delta)Whether a metric decreased with respect to a best score.
increased
(metric, best, min_delta)Whether a metric increased with respect to a best score.
stop
(metric)Advance early stopping counter.
-
decreased
(metric, best, min_delta)[source]¶ Whether a metric decreased with respect to a best score.
Measure improvement for metrics that are considered as ‘better’ when they decrease, e.g. model loss, mean squared error, etc.
- Parameters
metric (float) – The current score.
best (float) – The current best score.
min_delta (float) – Minimum change to be considered as an improvement.
- Returns
Whether the metric improved.
- Return type
bool
-
increased
(metric, best, min_delta)[source]¶ Whether a metric increased with respect to a best score.
Measure improvement for metrics that are considered as ‘better’ when they increase, e.g. accuracy, precision, recall, etc.
- Parameters
metric (float) – The current score.
best (float) – The current best score.
min_delta (float) – Minimum change to be considered as an improvement.
- Returns
Whether the metric improved.
- Return type
bool
-
class
core.trainer.
EvalConfig
(state_file: pathlib.Path, test: object, predict_scene: bool = False, plot_samples: bool = False, plot_scenes: bool = False, plot_bands: list = <factory>, cm: bool = True, figsize: tuple = (10, 10), alpha: int = 5)[source]¶ Bases:
core.trainer.BaseConfig
Model inference configuration.
Evaluate a model.
- Parameters
state_file (pathlib.Path) – Path to the model to evaluate.
test (bool or None) – Whether to evaluate the model on the training(
test
= None), the validation (test
= False) or the test set (test
= True).predict_scene (bool, optional) – The model prediction order. If False, the samples (tiles) of a dataset are predicted in any order and the scenes are not reconstructed. If True, the samples (tiles) are ordered according to the scene they belong to and a model prediction for each entire reconstructed scene is returned. The default is False.
plot_samples (bool, optional) – Whether to save a plot of false color composite, ground truth and model prediction for each sample (tile). Only used if
predict_scene
= False. The default is False.plot_scenes (bool, optional) – Whether to save a plot of false color composite, ground truth and model prediction for each entire scene. Only used if
predict_scene
= True. The default is False.plot_bands (list [str], optional) – The bands to build the false color composite. The default is [‘nir’, ‘red’, ‘green’].
cm (bool, optional) – Whether to compute and plot the confusion matrix. The default is True.
figsize (tuple, optional) – The figure size in centimeters. The default is (10, 10).
alpha (int, optional) – The level of the percentiles for contrast stretching of the false color compsite. The default is 0, i.e. no stretching.
- Returns
- Return type
None.
-
alpha
: int = 5¶
-
cm
: bool = True¶
-
figsize
: tuple = (10, 10)¶
-
plot_bands
: list¶
-
plot_samples
: bool = False¶
-
plot_scenes
: bool = False¶
-
predict_scene
: bool = False¶
-
state_file
: pathlib.Path¶
-
test
: object¶
-
class
core.trainer.
LogConfig
(state_file: pathlib.Path)[source]¶ Bases:
core.trainer.BaseConfig
Logging configuration class.
Generate the model log file.
- Parameters
state_file (pathlib.Path) – Path to a model state file.
Methods
init_log
(init_str)Generate a string to identify a new model run.
now
()Return the current date and time.
-
static
init_log
(init_str)[source]¶ Generate a string to identify a new model run.
- Parameters
init_str (str) – The string to write to the model log file.
- Returns
- Return type
None.
-
static
now
()[source]¶ Return the current date and time.
- Returns
date – The current date and time.
- Return type
datetime.datetime
-
state_file
: pathlib.Path¶
-
class
core.trainer.
ModelConfig
(model_name: str, filters: list, torch_seed: int, optim_name: str, loss_name: str, skip_connection: bool = True, kwargs: dict = <factory>, batch_size: int = 64, checkpoint: bool = False, transfer: bool = False, pretrained_model: str = '', lr: float = 0.001, early_stop: bool = False, mode: str = 'max', delta: float = 0, patience: int = 10, epochs: int = 50, nthreads: int = 2, save: bool = True)[source]¶ Bases:
core.trainer.BaseConfig
Model configuration class.
Instanciate a (pretrained) model.
- Parameters
model_name (str) – The name of the model.
filters (list [int]) – List of input channels to the convolutional layers.
torch_seed (int) – The random seed to initialize the model weights. Useful for reproducibility.
optim_name (str) – The name of the optimizer to update the model weights.
loss_name (str) – The name of the loss function measuring the model error.
skip_connection (bool, optional) – Whether to apply skip connections. The defaul is True.
kwargs (dict, optional) – The configuration for each convolution in the model. The default is {‘kernel_size’: 3, ‘stride’: 1, ‘dilation’: 1}.
batch_size (int, optional) – The model batch size. Determines the number of samples to process before updating the model weights. The default is 64.
checkpoint (bool, optional) – Whether to resume training from an existing model checkpoint. The default is False.
transfer (bool, optional) – Whether to use a model for transfer learning on a new dataset. If True, the model architecture of
pretrained_model
is adjusted to a new dataset. The default is False.pretrained_model (str, optional) – The name of the pretrained model to use for transfer learning. The default is ‘’.
lr (float, optional) – The learning rate used by the gradient descent algorithm. The default is 0.001.
early_stop (bool, optional) – Whether to apply `early stopping`_. The default is False.
mode (str, optional) – The mode of the early stopping. Depends on the metric measuring performance. When using model loss as metric, use
mode
= ‘min’, however, when using accuracy as metric, usemode
= ‘max’. For now, onlymode
= ‘max’ is supported. Only used ifearly_stop
= True. The default is ‘max’.delta (float, optional) – Minimum change in early stopping metric to be considered as an improvement. Only used if
early_stop
= True. The default is 0.patience (int, optional) – The number of epochs to wait for an improvement in the early stopping metric. If the model does not improve over more than
patience
epochs, quit training. Only used ifearly_stop
= True. The default is 10.epochs (int, optional) – The maximum number of epochs to train. The default is 50.
nthreads (int, optional) – The number of cpu threads to use during training. The default is torch.get_num_threads().
save (bool, optional) – Whether to save the model state to disk. Model states are saved in pysegcnn/main/_models. The default is True.
_early stopping (.) – https://en.wikipedia.org/wiki/Early_stopping
- Returns
- Return type
None.
Methods
Instanciate the loss function.
init_model
(ds, state_file)Instanciate the model and the optimizer.
init_optimizer
(model)Instanciate the optimizer.
load_checkpoint
(model, optimizer, state_file)Load an existing model checkpoint.
transfer_model
(state_file, ds)Adjust a pretrained model to a new dataset.
-
batch_size
: int = 64¶
-
checkpoint
: bool = False¶
-
delta
: float = 0¶
-
early_stop
: bool = False¶
-
epochs
: int = 50¶
-
filters
: list¶
-
init_loss_function
()[source]¶ Instanciate the loss function.
- Returns
loss_function – An instance of torch.nn.Module.
- Return type
torch.nn.Module
-
init_model
(ds, state_file)[source]¶ Instanciate the model and the optimizer.
If the model checkpoint
state_file
exists, the pretrained model and optimizer states are loaded, otherwise the model and the optimizer are initialized from scratch.- Parameters
ds (pysegcnn.core.dataset.ImageDataset) – An instance of pysegcnn.core.dataset.ImageDataset.
state_file (pathlib.Path) – Path to a model checkpoint.
- Returns
model (pysegcnn.core.models.Network) – An instance of pysegcnn.core.models.Network.
optimizer (torch.optim.Optimizer) – An instance of torch.optim.Optimizer.
checkpoint_state (dict [str, numpy.ndarray]) – If the model checkpoint
state_file
exists,checkpoint_state
has keys:'ta'
The accuracy on the training set (numpy.ndarray).
'tl'
The loss on the training set (numpy.ndarray).
'va'
The accuracy on the validation set (numpy.ndarray).
'vl'
The loss on the validation set (numpy.ndarray).
-
init_optimizer
(model)[source]¶ Instanciate the optimizer.
- Parameters
model (torch.nn.Module) – An instance of torch.nn.Module.
- Returns
optimizer – An instance of torch.optim.Optimizer.
- Return type
torch.optim.Optimizer
-
kwargs
: dict¶
-
static
load_checkpoint
(model, optimizer, state_file)[source]¶ Load an existing model checkpoint.
If the model checkpoint
state_file
exists, the pretrained model and optimizer states are loaded.- Parameters
model (pysegcnn.core.models.Network) – An instance of pysegcnn.core.models.Network.
optimizer (torch.optim.Optimizer) – An instance of torch.optim.Optimizer.
state_file (pathlib.Path) – Path to the model checkpoint.
- Returns
model (pysegcnn.core.models.Network) – An instance of pysegcnn.core.models.Network.
optimizer (torch.optim.Optimizer) – An instance of torch.optim.Optimizer.
checkpoint_state (dict [str, numpy.ndarray]) – If the model checkpoint
state_file
exists,checkpoint_state
has keys:'ta'
The accuracy on the training set (numpy.ndarray).
'tl'
The loss on the training set (numpy.ndarray).
'va'
The accuracy on the validation set (numpy.ndarray).
'vl'
The loss on the validation set (numpy.ndarray).
-
loss_name
: str¶
-
lr
: float = 0.001¶
-
mode
: str = 'max'¶
-
model_name
: str¶
-
nthreads
: int = 2¶
-
optim_name
: str¶
-
patience
: int = 10¶
-
pretrained_model
: str = ''¶
-
save
: bool = True¶
-
skip_connection
: bool = True¶
-
torch_seed
: int¶
-
transfer
: bool = False¶
-
static
transfer_model
(state_file, ds)[source]¶ Adjust a pretrained model to a new dataset.
The classification layer of the pretrained model in
state_file
is initilialized from scratch with the classes of the new datasetds
.The remaining model weights are preserved.
- Parameters
state_file (pathlib.Path) – Path to a pretrained model.
ds (pysegcnn.core.dataset.ImageDataset) – An instance of pysegcnn.core.dataset.ImageDataset.
- Raises
TypeError – Raised if
ds
is not an instance of pysegcnn.core.dataset.ImageDataset.ValueError – Raised if the bands of
ds
do not match the bands of the dataset the pretrained model was trained with.
- Returns
model – An instance of pysegcnn.core.models.Network. The pretrained model adjusted to the new dataset.
- Return type
pysegcnn.core.models.Network
-
class
core.trainer.
NetworkTrainer
(model: pysegcnn.core.models.Network, optimizer: torch.optim.optimizer.Optimizer, loss_function: torch.nn.modules.module.Module, train_dl: torch.utils.data.dataloader.DataLoader, valid_dl: torch.utils.data.dataloader.DataLoader, test_dl: torch.utils.data.dataloader.DataLoader, state_file: pathlib.Path, epochs: int = 1, nthreads: int = 2, early_stop: bool = False, mode: str = 'max', delta: float = 0, patience: int = 10, checkpoint_state: dict = <factory>, save: bool = True)[source]¶ Bases:
core.trainer.BaseConfig
Model training class.
Generic class to train an instance of pysegcnn.core.models.Network on a dataset of type pysegcnn.core.dataset.ImageDataset.
- Parameters
model (pysegcnn.core.models.Network) – The model to train. An instance of pysegcnn.core.models.Network.
optimizer (torch.optim.Optimizer) – The optimizer to update the model weights. An instance of torch.optim.Optimizer.
loss_function (torch.nn.Module) – The loss function to compute the model error. An instance of torch.nn.Module.
train_dl (torch.utils.data.DataLoader) – The training torch.utils.data.DataLoader instance.
valid_dl (torch.utils.data.DataLoader) – The validation torch.utils.data.DataLoader instance.
test_dl (torch.utils.data.DataLoader) – The test torch.utils.data.DataLoader instance.
state_file (pathlib.Path) – Path to save the model state.
epochs (int, optional) – The maximum number of epochs to train. The default is 1.
nthreads (int, optional) – The number of cpu threads to use during training. The default is torch.get_num_threads().
early_stop (bool, optional) – Whether to apply `early stopping`_. The default is False.
mode (str, optional) – The mode of the early stopping. Depends on the metric measuring performance. When using model loss as metric, use
mode
= ‘min’, however, when using accuracy as metric, usemode
= ‘max’. For now, onlymode
= ‘max’ is supported. Only used ifearly_stop
= True. The default is ‘max’.delta (float, optional) – Minimum change in early stopping metric to be considered as an improvement. Only used if
early_stop
= True. The default is 0.patience (int, optional) – The number of epochs to wait for an improvement in the early stopping metric. If the model does not improve over more than
patience
epochs, quit training. Only used ifearly_stop
= True. The default is 10.checkpoint_state (dict [str, numpy.ndarray], optional) –
A model checkpoint for
model
. If specified,checkpoint_state
should be a dictionary with keys:'ta'
The accuracy on the training set (numpy.ndarray).
'tl'
The loss on the training set (numpy.ndarray).
'va'
The accuracy on the validation set (numpy.ndarray).
'vl'
The loss on the validation set (numpy.ndarray).
The default is {}.
save (bool, optional) – Whether to save the model state to
state_file
. The default is True._early stopping (.) – https://en.wikipedia.org/wiki/Early_stopping
- Returns
- Return type
None.
Methods
predict
()Model inference at training time.
Save the model state.
train
()Train the model.
-
checkpoint_state
: dict¶
-
delta
: float = 0¶
-
early_stop
: bool = False¶
-
epochs
: int = 1¶
-
loss_function
: torch.nn.modules.module.Module¶
-
mode
: str = 'max'¶
-
model
: pysegcnn.core.models.Network¶
-
nthreads
: int = 2¶
-
optimizer
: torch.optim.optimizer.Optimizer¶
-
patience
: int = 10¶
-
predict
()[source]¶ Model inference at training time.
- Returns
accuracies (numpy.ndarray) – The mean model prediction accuracy on each mini-batch in the validation set.
losses (numpy.ndarray) – The model loss for each mini-batch in the validation set.
-
save
: bool = True¶
-
state_file
: pathlib.Path¶
-
test_dl
: torch.utils.data.dataloader.DataLoader¶
-
train
()[source]¶ Train the model.
- Returns
training_state – The training state dictionary with keys:
'ta'
The accuracy on the training set (numpy.ndarray).
'tl'
The loss on the training set (numpy.ndarray).
'va'
The accuracy on the validation set (numpy.ndarray).
'vl'
The loss on the validation set (numpy.ndarray).
- Return type
dict [str, numpy.ndarray]
-
train_dl
: torch.utils.data.dataloader.DataLoader¶
-
valid_dl
: torch.utils.data.dataloader.DataLoader¶
-
class
core.trainer.
SplitConfig
(split_mode: str, ttratio: float, tvratio: float, date: str = 'yyyymmdd', dateformat: str = '%Y%m%d', drop: float = 0)[source]¶ Bases:
core.trainer.BaseConfig
Dataset split configuration class.
Split a dataset into training, validation and test set.
- Parameters
split_mode (str) – The mode to split the dataset.
ttratio (float) – The ratio of training and validation data to test data, e.g.
ttratio
= 0.6 means 60% for training and validation, 40% for testing.tvratio (float) – The ratio of training data to validation data, e.g.
tvratio
= 0.8 means 80% training, 20% validation.date (str, optional) – A date. Used if
split_mode
= ‘date’. The default is ‘yyyymmdd’.dateformat (str, optional) – The format of
date
.dateformat
is used by datetime.datetime.strptime’ to parse ``date` to a datetime.datetime object. The default is ‘%Y%m%d’.drop (float, optional) – Whether to drop samples (during training only) with a fraction of pixels equal to the constant padding value >=
drop
.drop
= 0 means, do not drop any samples. The default is 0.
- Returns
- Return type
None.
Methods
dataloaders
(*args, **kwargs)Build torch.utils.data.DataLoader instances.
Split
ds
into training, validation and test set.-
static
dataloaders
(*args, **kwargs)[source]¶ Build torch.utils.data.DataLoader instances.
- Parameters
*args (list [torch.utils.data.Dataset]) – List of instances of torch.utils.data.Dataset.
**kwargs – Additional keyword arguments passed to torch.utils.data.DataLoader.
- Raises
TypeError – Raised if not each item in
args
is an instance of torch.utils.data.Dataset.- Returns
loaders – List of instances of torch.utils.data.DataLoader. If an instance of torch.utils.data.Dataset in
args
is empty, None is appended toloaders
instead of an instance of torch.utils.data.DataLoader.- Return type
list [torch.utils.data.DataLoader]
-
date
: str = 'yyyymmdd'¶
-
dateformat
: str = '%Y%m%d'¶
-
drop
: float = 0¶
-
split_mode
: str¶
-
train_val_test_split
(ds)[source]¶ Split
ds
into training, validation and test set.- Parameters
ds (pysegcnn.core.dataset.ImageDataset) – An instance of pysegcnn.core.dataset.ImageDataset.
- Raises
TypeError – Raised if
ds
is not an instance of pysegcnn.core.dataset.ImageDataset.- Returns
train_ds (pysegcnn.core.split.RandomSubset or)
pysegcnn.core.split.SceneSubset. – The training set.
valid_ds (pysegcnn.core.split.RandomSubset or)
pysegcnn.core.split.SceneSubset. – The validation set.
test_ds (pysegcnn.core.split.RandomSubset or)
pysegcnn.core.split.SceneSubset. – The test set.
-
ttratio
: float¶
-
tvratio
: float¶
-
class
core.trainer.
StateConfig
(ds: pysegcnn.core.dataset.ImageDataset, sc: core.trainer.SplitConfig, mc: core.trainer.ModelConfig)[source]¶ Bases:
core.trainer.BaseConfig
Model state configuration class.
Generate the model state filename according to the following naming convention:
model_dataset_optimizer_splitmode_splitparams_tilesize_batchsize_bands.pt
- Parameters
ds (pysegcnn.core.dataset.ImageDataset) – An instance of pysegcnn.core.dataset.ImageDataset.
sc (pysegcnn.core.trainer.SplitConfig) – An instance of pysegcnn.core.trainer.SplitConfig.
mc (pysegcnn.core.trainer.ModelConfig) – An instance of pysegcnn.core.trainer.SplitConfig.
- Returns
- Return type
None.
Methods
Generate the model state filename.
-
ds
: pysegcnn.core.dataset.ImageDataset¶
core.transforms module¶
Data augmentation.
This module provides classes implementing common image augmentation methods.
These methods may be used to artificially increase a dataset.
License¶
Copyright (c) 2020 Daniel Frisinghelli
This source code is licensed under the GNU General Public License v3.
See the LICENSE file in the repository’s root directory.
-
class
core.transforms.
Augment
(transforms)[source]¶ Bases:
object
Apply a sequence of transformations.
Container class applying each transformation in
transforms
in order.- Parameters
transforms (list or tuple) – A sequence of instances of pysegcnn.core.transforms.VariantTransform or pysegcnn.core.transforms.InvariantTransform.
- Returns
- Return type
None.
Methods
__call__
(image, gt)Apply a sequence of transformations to
image
.
-
class
core.transforms.
FlipLr
(p=0.5)[source]¶ Bases:
core.transforms.VariantTransform
Flip an image horizontally.
- Parameters
p (float, optional) – The probability to apply the transformation. The default is 0.5.
- Returns
- Return type
None.
Methods
__call__
(image)Apply transformation.
-
class
core.transforms.
FlipUd
(p=0.5)[source]¶ Bases:
core.transforms.VariantTransform
Flip an image vertically.
- Parameters
p (float, optional) – The probability to apply the transformation. The default is 0.5.
- Returns
- Return type
None.
Methods
__call__
(image)Apply transformation.
-
class
core.transforms.
InvariantTransform
[source]¶ Bases:
core.transforms.Transform
Base class for a spatially invariant transformation.
Transformation on the ground truth not required.
Methods
__call__
(image)Apply transformation.
-
class
core.transforms.
Noise
(mode, mean=0, var=0.05, p=0.5, exclude=[])[source]¶ Bases:
core.transforms.InvariantTransform
Add gaussian noise to an image.
Valid modes are:
‘add’: image = image + noise ‘speckle’ : image = image + image * noise
- Parameters
mode (str) – The mode to add the noise.
mean (float, optional) – The mean of the gaussian distribution from which the noise is sampled. The default is 0.
var (float, optional) – The variance of the gaussian distribution from which the noise is sampled. The default is 0.05.
p (float, optional) – The probability to apply the transformation. The default is 0.5.
exclude (list [float] or list [int], optional) – Values for which the noise is not added. Useful for pixels resulting from image padding. The default is [].
- Raises
ValueError – Raised if
mode
is not supported.- Returns
- Return type
None.
Methods
__call__
(image)Apply transformation.
-
modes
= ['add', 'speckle']¶
-
class
core.transforms.
Rotate
(angle, p=0.5)[source]¶ Bases:
core.transforms.VariantTransform
Rotate an image by
angle
.The image is rotated in the spatial plane.
If the input array has more then two dimensions, the spatial dimensions are assumed to be the last two dimensions of the array.
- Parameters
angle (float) – The rotation angle in degrees.
p (float, optional) – The probability to apply the transformation. The default is 0.5.
- Returns
- Return type
None.
Methods
__call__
(image)Apply transformation.
-
class
core.transforms.
Transform
[source]¶ Bases:
object
Base class for an image transformation.
Methods
__call__
(image)Apply transformation.
-
class
core.transforms.
VariantTransform
[source]¶ Bases:
core.transforms.Transform
Base class for a spatially variant transformation.
Transformation on the ground truth required.
Methods
__call__
(image)Apply transformation.
core.utils module¶
Utility functions mainly for image IO and reshaping.
License¶
Copyright (c) 2020 Daniel Frisinghelli
This source code is licensed under the GNU General Public License v3.
See the LICENSE file in the repository’s root directory.
-
core.utils.
accuracy_function
(outputs, labels)[source]¶ Calculate prediction accuracy.
- Parameters
outputs (torch.Tensor or array_like) – The model prediction.
labels (torch.Tensor or array_like) – The ground truth.
- Returns
accuracy – Mean prediction accuracy.
- Return type
float
-
core.utils.
check_tile_extend
(img_size, topleft, tile_size)[source]¶ Check if a tile exceeds the image size.
- Parameters
img_size (tuple) – The image size (height, width).
topleft (tuple) – The topleft corner of the tile (y, x).
tile_size (int) – The size of the tile.
- Returns
nrows (int) – Number of rows of the tile within the image.
ncols (TYPE) – Number of columns of the tile within the image.
-
core.utils.
destack_tiff
(image, outpath=None, overwrite=False, remove=False, suffix='')[source]¶ Destack a TIFF with more than one band into a TIFF file for each band.
Each band in
image
is saved tooutpath
as distinct TIFF file. The default filenames are: “filename(image
) + _B(i).tif”, where i is the respective number of each band inimage
.- Parameters
image (str or pathlib.Path) – The TIFF to destack.
outpath (str, optional) – Path to save the output TIFF files. The default is None. If None,
outpath
is the path toimage
.remove (bool, optional) – Whether to remove
image
from disk after destacking. The default is False.overwrite (bool, optional) – Whether to overwrite existing TIFF files.
suffix (str, optional) – String to append to the filename of
image
. If specified, the TIFF filenames for each band inimage
are, “filename(image
) + + _B(i)_ +suffix
.tif”. The default is ‘’.
- Raises
FileNotFoundError – Raised if
image
does not exist.- Returns
- Return type
None.
-
core.utils.
doy2date
(year, doy)[source]¶ Convert the (year, day of the year) date format to a datetime object.
- Parameters
year (int) – The year
doy (int) – The day of the year
- Returns
date – The converted date.
- Return type
datetime.datetime
-
core.utils.
extract_archive
(inpath, outpath, overwrite=False)[source]¶ Extract files from an archive.
- Parameters
inpath (str or pathlib.Path) – Path to an archive.
outpath (str or pathlib.Path) – Path to save extracted files.
overwrite (bool, optional) – Whether to overwrite existing extracted files.
- Returns
subdir – path to the extracted files
- Return type
str
-
core.utils.
get_radiometric_constants
(metadata)[source]¶ Retrieve the radiometric calibration constants.
- Parameters
metadata (dict) – The dictionary returned by
read_landsat_metadata
.- Returns
oli (dict) – Radiometric rescaling factors of the OLI sensor.
tir (dict) – Thermal conversion constants of the TIRS sensor.
-
core.utils.
img2np
(path, tile_size=None, tile=None, pad=False, cval=0)[source]¶ Read an image to a numpy.ndarray.
If
tile_size
is not None, the input image is divided into square tiles of size (tile_size
,tile_size
). If the image is not evenly divisible andpad
= False, a ValueError is raised. However, ifpad
= True, center padding with constant valuecval
is applied.The tiling works as follows:
(Padded) Input image:
| | | |tile_00 | tile_01 | … | tile_0n || | | ||----------------------------------------------| | | | | | | tile_10 | tile_11 | … | tile_1n | | | | | | |----------------------------------------------| | | | | | | … | … | … | … | | | | | | |----------------------------------------------| | | | | | | tile_m0 | tile_m1 | … | tile_mn | | | | | | ————————————————
where m = n. Each tile has its id, which starts at 0 in the topleft corner of the input image, i.e. tile_00 has id=0, and increases along the width axis, i.e. tile_0n has id=n, tile_10 has id=n+1, …, tile_mn has id=(m * n) - 1.
If
tile
is an integer, only the tile with id =tile
is returned.- Parameters
path (str or None or numpy.ndarray) – The image to read.
tile_size (None or int, optional) – The size of a tile. The default is None.
tile (int, optional) – The tile id. The default is None.
pad (bool, optional) – Whether to center pad the input image. The default is False.
cval (float, optional) – The constant padding value. The default is 0.
- Raises
FileNotFoundError – Raised if
path
is a path that does not exist.TypeError – Raised if
path
is not str or None or numpy.ndarray.
- Returns
image –
The image array. The output shape is:
- if
tile_size
is not None: shape=(tiles, bands, tile_size, tile_size) if the image does only have one band:
shape=(tiles, tile_size, tile_size)
- else:
shape=(bands, height, width) if the image does only have one band:
shape=(height, width)
- if
- Return type
numpy.ndarray
-
core.utils.
is_divisible
(img_size, tile_size, pad=False)[source]¶ Check whether an image is evenly divisible into square tiles.
- Parameters
img_size (tuple) – The image size (height, width).
tile_size (int) – The size of the tile.
pad (bool, optional) – Whether to center pad the input image. The default is False.
- Raises
ValueError – Raised if the image is not evenly divisible and
pad
= False.- Returns
ntiles (int) – The number of tiles fitting
img_size
.padding (tuple) – The amount of padding (bottom, left, top, right).
-
core.utils.
item_in_enum
(name, enum)[source]¶ Check if an item exists in an enumeration.
- Parameters
name (str) – Name of the item.
enum (enum.Enum) – An instance of enum.Enum.
- Raises
ValueError – Raised if
name
is not inenum
.- Returns
The value of
name
inenum
.- Return type
value
-
core.utils.
landsat_radiometric_calibration
(scene, outpath=None, exclude=[], radiance=False, overwrite=False, remove_raw=True)[source]¶ Radiometric calibration of Landsat Collection Level 1 scenes.
Convert the Landsat OLI bands to top of atmosphere radiance or reflectance and the TIRS bands to top of atmosphere brightness temperature.
Conversion is performed following the `equations`_ provided by the USGS.
The filename of each band is extended by one of the following suffixes, depending on the type of the radiometric calibration:
‘toa_ref’: top of atmosphere reflectance ‘toa_rad’: top of atmopshere radiance ‘toa_brt’: top of atmosphere brightness temperature
- Parameters
scene (str or pathlib.Path) – Path to a Landsat scene in digital number format.
outpath (str or pathlib.Path, optional) – Path to save the calibrated images. The default is None, which means saving to
scene
.exclude (list [str], optional) – Bands to exclude from the radiometric calibration. The default is [].
radiance (bool, optional) – Whether to calculate top of atmosphere radiance. The default is False, which means calculating top of atmopshere reflectance.
overwrite (bool, optional) – Whether to overwrite the calibrated images. The default is False.
remove_raw (bool, optional) – Whether to remove the raw digitial number images. The default is True.
- Raises
FileNotFoundError – Raised if
scene
does not exist.- Returns
None.
.. _equations – https://www.usgs.gov/land-resources/nli/landsat/using-usgs-landsat-level-1-data-product
-
core.utils.
parse_landsat_scene
(scene_id)[source]¶ Parse a Landsat scene identifier.
- Parameters
scene_id (str) – A Landsat scene identifier.
- Returns
scene – A dictionary containing scene metadata. If None,
scene_id
is not a valid Landsat scene identifier.- Return type
dict or None
-
core.utils.
parse_sentinel2_scene
(scene_id)[source]¶ Parse a Sentinel-2 scene identifier.
- Parameters
scene_id (str) – A Sentinel-2 scene identifier.
- Returns
scene – A dictionary containing scene metadata. If None,
scene_id
is not a valid Sentinel-2 scene identifier.- Return type
dict or None
-
core.utils.
read_landsat_metadata
(file)[source]¶ Parse the Landsat metadata *_MTL.txt file.
- Parameters
file (str or pathlib.Path) – Path to a Landsat *_MTL.txt file.
- Raises
FileNotFoundError – Raised if
file
does not exist.- Returns
metadata – The metadata text file as dictionary, where each line is a (key, value) pair.
- Return type
dict
-
core.utils.
reconstruct_scene
(tiles)[source]¶ Reconstruct a tiled image.
- Parameters
tiles (torch.Tensor or numpy.ndarray) – The tiled image, shape=(tiles, bands, tile_size, tile_size) or shape=(tiles, tile_size, tile_size).
- Returns
image – The reconstructed image.
- Return type
numpy.ndarray
-
core.utils.
standard_eo_structure
(source_path, target_path, overwrite=False, move=False, parser=<function parse_landsat_scene>)[source]¶ Modify the directory structure of a remote sensing dataset.
This function assumes that
source_path
points to a directory containing remote sensing data, where each file insource_path
and its sub-folders should contain a scene identifier in its filename. The scene identifier is used to restructure the dataset.Currently, Landsat and Sentinel-2 datasets are supported.
The directory tree in
source_path
is modified to the following structure intarget_path
:- target_path/
- scene_id_1/
files matching scene_id_1
- scene_id_2/
files matching scene_id_2
. scene_id_n/
files matching scene_id_n
- Parameters
source_path (str or pathlib.Path) – Path to the remote sensing dataset.
target_path (str or pathlib.Path) – Path to save the restructured dataset.
overwrite (bool, optional) – Whether to overwrite existing files in
target_path
. The default is True.move (bool, optional) – Whether to move the files from
source_path
totarget_path
. If True, files insource_path
are moved totarget_path
, if False, files insource_path
are copied totarget_path
. The default is False.parser (function, optional) – The scene identifier parsing function. Depends on the sensor of the dataset. See e.g., pysegcnn.core.utils.parse_landsat_scene.
- Returns
- Return type
None.
-
core.utils.
tile_topleft_corner
(img_size, tile_size)[source]¶ Return the topleft corners of the tiles in the image.
- Parameters
img_size (tuple) – The image size (height, width).
tile_size (int) – The size of the tile.
- Returns
indices – The keys of
indices
are the tile ids (int) and the values are the topleft corners (tuple = (y, x)) of the tiles.- Return type
dict