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.cli.structure_parser()[source]

Command line argument parser to standardize dataset structure.

Returns

Return type

None.

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.

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')
class core.constants.Sentinel2(value)[source]

Bases: enum.Enum

The spectral bands of the Sentinel-2 MultiSpectral Instrument (MSI).

aerosol = 1
blue = 2
cirrus = 10
green = 3
nir = 8
nnir = '8A'
red = 4
swir1 = 11
swir2 = 12
vapor = 9
vnir1 = 5
vnir2 = 6
vnir3 = 7
class core.constants.SparcsLabels(value)[source]

Bases: core.constants.Label

Class labels of the Sparcs dataset.

Cloud = (5, 'white')
Flooded = (6, 'yellow')
Land = (4, 'sienna')
Shadow = (0, 'grey')
Shadow_over_water = (1, 'darkblue')
Snow = (3, 'lightblue')
Water = (2, 'blue')

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 the tile_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 matching gt_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. If transforms = [], 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 Cloud-95 dataset.

get_sensor()

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.

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

parse_scene_id(scene_id)[source]

Parse Sparcs scene identifiers (Landsat 8).

Parameters

scene_id (str) – A 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

preprocess(data, gt)[source]

Preprocess Cloud-95 dataset images.

Parameters
  • data (numpy.ndarray) – The sample input data.

  • gt (numpy.ndarray) – The sample ground truth.

Returns

  • data (numpy.ndarray) – The preprocessed input data.

  • gt (numpy.ndarray) – The preprocessed ground truth data.

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 the tile_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 matching gt_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. If transforms = [], 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()

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.

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

to_tensor(x, dtype)[source]

Convert x to torch.Tensor.

Parameters
  • x (array_like) – The input data.

  • dtype (torch.dtype) – The data type used to convert x.

Returns

x – The input data tensor.

Return type

torch.Tensor

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 the tile_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 matching gt_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. If transforms = [], 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()

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

parse_scene_id(scene_id)[source]

Parse ProSnow scene identifiers (Sentinel 2).

Parameters

scene_id (str) – A 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

preprocess(data, gt)[source]

Preprocess ProSnow dataset images.

Parameters
  • data (numpy.ndarray) – The sample input data.

  • gt (numpy.ndarray) – The sample ground truth.

Returns

  • data (numpy.ndarray) – The preprocessed input data.

  • gt (numpy.ndarray) – The preprocessed ground truth data.

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 the tile_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 matching gt_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. If transforms = [], 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.

get_size()[source]

Image size of the ProSnow Garmisch dataset.

Returns

size – The image size (height, width).

Return type

tuple

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 the tile_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 matching gt_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. If transforms = [], 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.

get_size()[source]

Image size of the ProSnow Obergurgl dataset.

Returns

size – The image size (height, width).

Return type

tuple

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 the tile_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 matching gt_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. If transforms = [], 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 Sparcs dataset.

get_sensor()

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

parse_scene_id(scene_id)[source]

Parse Sparcs scene identifiers (Landsat 8).

Parameters

scene_id (str) – A 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

preprocess(data, gt)[source]

Preprocess Sparcs dataset images.

Parameters
  • data (numpy.ndarray) – The sample input data.

  • gt (numpy.ndarray) – The sample ground truth.

Returns

  • data (numpy.ndarray) – The preprocessed input data.

  • gt (numpy.ndarray) – The preprocessed ground truth data.

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 the tile_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 matching gt_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. If transforms = [], 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()

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.

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.graphics.running_mean(x, w)[source]

Compute a running mean of the input sequence.

Parameters
  • x (array_like) – The sequence to compute a running mean on.

  • w (int) – The window length of the running mean.

Returns

rm – The running mean of the sequence x.

Return type

numpy.ndarray

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
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.

extra_repr()

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.

extra_repr()

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.

extra_repr()

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 of filters 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 of filters 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
unfreeze()[source]

Unfreeze the weights of a model.

Enables gradient computation: useful when adjusting a pretrained model to a new dataset.

Returns

Return type

None.

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 model model.

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 if cm = True.

core.predict.predict_scenes(ds, model, scene_id=None, cm=False, plot=False, **kwargs)[source]

Classify each scene in ds with model model.

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 if cm = 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.

subset_type()

Wrap pysegcnn.core.split.SceneSubset.

subsets()

Wrap pysegcnn.core.split.Split.date_scene_split.

subset_type()[source]

Wrap pysegcnn.core.split.SceneSubset.

Returns

SceneSubset – The subset type.

Return type

pysegcnn.core.split.SceneSubset

subsets()[source]

Wrap pysegcnn.core.split.Split.date_scene_split.

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

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.

subset_type()

Wrap pysegcnn.core.split.SceneSubset.

subsets()

Wrap pysegcnn.core.split.Split.random_scene_split.

subset_type()[source]

Wrap pysegcnn.core.split.SceneSubset.

Returns

SceneSubset – The subset type.

Return type

pysegcnn.core.split.SceneSubset

subsets()[source]

Wrap pysegcnn.core.split.Split.random_scene_split.

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

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.

subset_type()

Wrap pysegcnn.core.split.RandomSubset.

subsets()

Wrap pysegcnn.core.split.Split.random_tile_split.

subset_type()[source]

Wrap pysegcnn.core.split.RandomSubset.

Returns

SceneSubset – The subset type.

Return type

pysegcnn.core.split.RandomSubset

subsets()[source]

Wrap pysegcnn.core.split.Split.random_tile_split.

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

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.

subset_type()

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 after date 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 and tvratio 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 and tvratio 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 matching gt_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. If transforms = [], 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 the tile_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

init_dataset()

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, use mode = ‘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

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

stop(metric)[source]

Advance early stopping counter.

Parameters

metric (float) – The current metric score.

Returns

early_stop – Whether the early stopping criterion is met.

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, use mode = ‘max’. For now, only mode = ‘max’ is supported. Only used if early_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 if early_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

init_loss_function()

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 dataset ds.

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, use mode = ‘max’. For now, only mode = ‘max’ is supported. Only used if early_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 if early_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_state()

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
save_state()[source]

Save the model state.

Returns

Return type

None.

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.

train_val_test_split(ds)

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 to loaders 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

init_state()

Generate the model state filename.

ds: pysegcnn.core.dataset.ImageDataset
init_state()[source]

Generate the model state filename.

Returns

state – The path to the model state file.

Return type

pathlib.Path

mc: core.trainer.ModelConfig
sc: core.trainer.SplitConfig

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 to outpath as distinct TIFF file. The default filenames are: “filename(image) + _B(i).tif”, where i is the respective number of each band in image.

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 to image.

  • 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 in image 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 and pad = False, a ValueError is raised. However, if pad = True, center padding with constant value cval 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)

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 in enum.

Returns

The value of name in enum.

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

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 in source_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 in target_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 to target_path. If True, files in source_path are moved to target_path, if False, files in source_path are copied to target_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

Module contents