remotior_sensus.tools.band_classification module

Band classification.

This tool allows for the classification of remote sensing images, providing several algorithms such as Minimum Distance, Maximum Likelihood, Spectral Angle Mapping. Also, machine learning algorithms are provided through PyTorch (pytorch_multi_layer_perceptron) and scikit-learn (random_forest, random_forest_ovr, support_vector_machine, multi_layer_perceptron).

Pretrained models are also available.

Currently, included pretrained models are:

Swin-v2-Base model for Sentinel-2 single image. Requirements: Sentinel-2 bandset (TCI RGB (B04, B03, B02), TOA bands B05, B06, B07, B08, B11, B12). Normalization: TCI RGB bands divided by 255; B05, B06, B07, B08, B11, B12 divided by 8160 and clipped to 0-1. Framework: PyTorch. Source: Sentinel2_SwinB_SI_MS, pretrained by the Allen Institute for Artificial Intelligence (SatlasPretrain: https://satlas-pretrain.allen.ai). The model weights are released under the Open Data Commons Attribution License (ODC-BY). The repository code is licensed under the Apache License 2.0 (https://huggingface.co/allenai/satlas-pretrain). This tool downloads the official SatlasPretrain weights (Bastani et al., “SatlasPretrain: A Large-Scale Dataset for Remote Sensing Image Understanding”, ICCV 2023, arXiv:2211.15660, https://doi.org/10.48550/arXiv.2211.15660). All model weights remain the property of their respective authors.
Swin-v2-Tiny model for Sentinel-2 single image. Requirements: Sentinel-2 bandset (TCI RGB (B04, B03, B02), TOA bands B05, B06, B07, B08, B11, B12). Normalization: TCI RGB bands divided by 255; B05, B06, B07, B08, B11, B12 divided by 8160 and clipped to 0-1. Framework: PyTorch. Source: Sentinel2_SwinT_SI_MS, pretrained by the Allen Institute for Artificial Intelligence (SatlasPretrain: https://satlas-pretrain.allen.ai). The model weights are released under the Open Data Commons Attribution License (ODC-BY). The repository code is licensed under the Apache License 2.0 (https://huggingface.co/allenai/satlas-pretrain). This tool downloads the official SatlasPretrain weights (Bastani et al., “SatlasPretrain: A Large-Scale Dataset for Remote Sensing Image Understanding”, ICCV 2023, arXiv:2211.15660, https://doi.org/10.48550/arXiv.2211.15660). All model weights remain the property of their respective authors.
Swin-v2-Base model for Landsat 8 or Landsat 9 single image. Requirements: Landsat 8 or Landsat 9 bandset (Collection 2 Level-1 bands B01, B02, B03, B04, B05, B06, B07, B08, B09, B10, B11); Normalization: (band - 4000)/16320 and clipped to 0-1. Framework: PyTorch. Source: Landsat_SwinB_SI, pretrained by the Allen Institute for Artificial Intelligence (SatlasPretrain: https://satlas-pretrain.allen.ai). The model weights are released under the Open Data Commons Attribution License (ODC-BY). The repository code is licensed under the Apache License 2.0 (https://huggingface.co/allenai/satlas-pretrain). This tool downloads the official SatlasPretrain weights (Bastani et al., “SatlasPretrain: A Large-Scale Dataset for Remote Sensing Image Understanding”, ICCV 2023, arXiv:2211.15660, https://doi.org/10.48550/arXiv.2211.15660). All model weights remain the property of their respective authors.

Also, pretrained segmentation models are available:

Swin-v2-Base segmentation for Sentinel-2 single image (4 bands). Requirements: Sentinel-2 bandset (TCI RGB (B04, B03, B02), TOA bands B08). Normalization: TCI RGB bands divided by 255; B08 divided by 8160 and clipped to 0-1. Framework: PyTorch. Output classes: background, water, developed, tree, shrub, grass, crop, bare, snow, wetland, mangroves, moss. Source: Satlas_MS_tci-b08_epoch150, pretrained by DPR Team as part of the DPR Zoo Segmentation Hub framework (https://github.com/DPR25/dpr-zoo-segmentation-hub) based on SatlasPretrain models. The repository code is licensed under the MIT License (https://huggingface.co/martinkorelic/dpr-zoo-models). This tool downloads the model weights (DPR Team, 2025. Made as part of Arnes Hackathon 2025). All model weights remain the property of their respective authors.
Swin-v2-Base segmentation for Sentinel-2 single image (3 bands). Requirements: Sentinel-2 bandset (TCI RGB (B04, B03, B02)). Normalization: TCI RGB bands divided by 255. Framework: PyTorch. Output classes: background, water, developed, tree, shrub, grass, crop, bare, snow, wetland, mangroves, moss. Source: Satlas_RGB1_epoch70, pretrained by DPR Team as part of the DPR Zoo Segmentation Hub framework (https://github.com/DPR25/dpr-zoo-segmentation-hub) based on SatlasPretrain models. The repository code is licensed under the MIT License (https://huggingface.co/martinkorelic/dpr-zoo-models). This tool downloads the model weights (DPR Team, 2025. Made as part of Arnes Hackathon 2025). All model weights remain the property of their respective authors.

This module includes tools for training the algorithms using Regions of Interest (ROIs) or spectral signatures.

Typical usage example:

>>> # import Remotior Sensus and start the session
>>> import remotior_sensus
>>> rs = remotior_sensus.Session()
>>> file_list = ['file1.tif', 'file2.tif', 'file3.tif']
>>> # create BandSet
>>> catalog = rs.bandset_catalog()
>>> catalog.create_bandset(file_list, bandset_number=1)
>>> # create signature catalog
>>> signature_catalog = rs.spectral_signatures_catalog(
... bandset=catalog.get(1)
... )
>>> # import vector for training
>>> signature_catalog.import_vector(
... file_path='roi.gpkg',
... macroclass_field='macroclass', class_field='class',
... macroclass_name_field='macroclass', class_name_field='class',
... calculate_signature=True
... )
>>> # start the classification process
>>> classification = rs.band_classification(
... input_bands=file_list, output_path='output.tif',
... spectral_signatures=signature_catalog,
... algorithm_name=cfg.maximum_likelihood
... )
>>> # classification using a pretrained model
>>> file_list_2 = ['S2_B04.tif', 'S2_B03.tif', 'S2_B02.tif', 'S2_B05.tif',
... 'S2_B06.tif', 'S2_B07.tif', 'S2_B08.tif', 'S2_B11.tif', 'S2_B12.tif'
... ]
>>> # create BandSet
>>> catalog_2 = rs.bandset_catalog()
>>> catalog_2.create_bandset(file_list_2, bandset_number=1)
>>> # create signature catalog
>>> signature_catalog_2 = rs.spectral_signatures_catalog(
... bandset=catalog.get(1)
... )
>>> # import vector for training
>>> signature_catalog_2.import_vector(
... file_path='roi.gpkg',
... macroclass_field='macroclass', class_field='class',
... macroclass_name_field='macroclass', class_name_field='class',
... calculate_signature=True
... )
>>> classification_2 = rs.band_classification(
... input_bands=file_list_2, output_path='output.tif',
... spectral_signatures=signature_catalog_2,
... algorithm_name=cfg.pytorch_pretrained_s2_swin_v2_tiny_a,
... additional_algorithm_name=cfg.random_forest,
... )

class remotior_sensus.tools.band_classification.Classifier(algorithm_name, spectral_signatures, covariance_matrices, model_classifier, input_normalization, normalization_values, additional_algorithm_name, pretrained_model_path, pretrained_model_replace, n_processes, num_classes, feature_importance=None)

Bases: object

Manages classifiers.

A classifier is an object which includes the required parameters to perform a classification, including the tools to perform the training.

algorithm_name: algorithm name selected form cfg.classification_algorithms.

spectral_signatures: a SpectralSignaturesCatalog() containing spectral signatures.

covariance_matrices: dictionary of previously calculated covariance matrices (used in maximum likelihood only).

model_classifier: classifier object.

input_normalization: perform input normalization; options are z_score or linear_scaling.

normalization_values: list of normalization paramters defined for each variable [normalization expressions, mean values, standar deviation values, minimum values, maximum values].

framework_name: name of framework such as classification_framework, scikit_framework, or pytorch_framework.

classification_function: the actual classification function.

function_argument = a dictionary including arguments for the: classification function such as model_classifier, covariance_matrices, normalization_values, spectral_signatures_catalog.

Examples

Fit a classifier

>>> # Start a session
>>> import remotior_sensus
>>> rs = remotior_sensus.Session()
>>> # create a BandSet
>>> catalog = rs.bandset_catalog()
>>> file_list = ['file1.tif', 'file2.tif', 'file3.tif']
>>> catalog.create_bandset(file_list, wavelengths=['Landsat 8'])
>>> # set a BandSet reference in signature catalog
>>> signature_catalog = rs.spectral_signatures_catalog(
>>>     bandset=catalog.get(1))
>>> # import vector in signature catalog
>>> signature_catalog.import_vector(
>>>     file_path='file.gpkg', macroclass_field='macroclass', class_field='class',
>>>     macroclass_name_field='macroclass', class_name_field='class',
>>>     calculate_signature=True)
>>> # train a minimum distance classifier
>>> classifier = Classifier.train(
>>>     spectral_signatures=signature_catalog,
>>>     algorithm_name='minimum distance'
>>> )

__init__(algorithm_name, spectral_signatures, covariance_matrices, model_classifier, input_normalization, normalization_values, additional_algorithm_name, pretrained_model_path, pretrained_model_replace, n_processes, num_classes, feature_importance=None)

Initializes a classifier.

A classifier is an object which includes the

Parameters:

algorithm_name – algorithm name selected form cfg.classification_algorithms.
spectral_signatures – a SpectralSignaturesCatalog() containing spectral signatures.
covariance_matrices – dictionary of previously calculated covariance matrices (used in maximum likelihood only).
model_classifier – classifier object.
input_normalization – perform input normalization; options are z_score or linear_scaling.
normalization_values – list of normalization parameters defined for each variable [normalization expressions, mean values, standard deviation values, minimum values, maximum values].
additional_algorithm_name – additional algorithm name useful for pretrained models, using parameters of the named algorithm; after executing the pretrained model, the additional algorithm is executed on the embeddings.
pretrained_model_path – path to pretrained model
pretrained_model_replace – pretrained model replace list
n_processes – number of processes
num_classes – number of classes for pretrained model
feature_importance – optional feature importance for some algorithms

classmethod load_classifier(algorithm_name=None, spectral_signatures=None, covariance_matrices=None, model_classifier=None, input_normalization=None, normalization_values=None, additional_algorithm_name=None, pretrained_model_path=None, pretrained_model_replace=None, n_processes=None, num_classes=None, feature_importance=None)

Loads a classifier.

Creates a classifier from loading.

Parameters:

algorithm_name – algorithm name selected form cfg.classification_algorithms.
spectral_signatures – a SpectralSignaturesCatalog() containing spectral signatures.
covariance_matrices – dictionary of previously calculated covariance matrices (used in maximum likelihood only).
model_classifier – classifier object.
input_normalization – perform input normalization; options are z_score or linear_scaling.
normalization_values – list of normalization parameters defined for each variable [normalization expressions, mean values, standard deviation values, minimum values, maximum values].
additional_algorithm_name – additional algorithm name useful for pretrained models, using parameters of the named algorithm; after executing the pretrained model, the additional algorithm is executed on the embeddings.
pretrained_model_path – path to pretrained model
pretrained_model_replace – pretrained model replace keys
num_classes – number of classes for pretrained model
n_processes – number of processes

Returns:

Classifier() object.

Examples

Load a classifier

>>> classifier = Classifier.load_classifier(
>>> algorithm_name=algorithm_name, spectral_signatures=spectral_signatures,
>>> covariance_matrices=covariance_matrices, model_classifier=model_classifier,
>>> input_normalization=input_normalization, normalization_values=normalization_values)

Runs prediction.

Performs multiprocess classification using a trained classifier using input bands.

Parameters:

input_raster_list – list of paths of input rasters.
output_raster_path – path of output file.
n_processes – number of parallel processes.
available_ram – number of megabytes of RAM available to processes.
macroclass – if True, use macroclass ID from ROIs or spectral signatures; if False use class ID.
threshold – if False, classification without threshold; if True, use single threshold for each signature; if float, use this value as threshold for all the signature.
classification_confidence – if True, write also additional classification confidence rasters as output.
signature_raster – if True, write additional rasters for each spectral signature as output.
virtual_raster – if True, create virtual raster output.
min_progress – minimum progress value for Progress().
max_progress – maximum progress value for Progress().

Returns:

OutputManager() object with

path = [output path]

Examples

Save a trainied classifier

>>> classifier = Classifier()
>>> # after the training
>>> prediction = classifier.run_prediction(
... input_raster_list=['file1.tif', 'file2.tif', 'file3.tif'],
... output_raster_path='file_path')

save_model(output_path: str) → OutputManager

Saves classifier model.

Saves a classifier model to file to be loaded later.

Parameters:

output_path – path of output file.

Returns:

OutputManager() object with

path = [output path]

Examples

Save a trainied classifier

>>> classifier = Classifier()
>>> # after the training
>>> saved_model = classifier.save_model(output_path=output_path)

classmethod train(spectral_signatures=None, algorithm_name=None, additional_algorithm_name=None, covariance_matrices=None, svc_classification_confidence=None, n_processes: int | None = None, available_ram: int | None = None, cross_validation=True, x_matrix=None, y=None, class_weight=None, input_normalization=None, normalization_values=None, find_best_estimator=False, rf_max_features=None, rf_number_trees=100, rf_min_samples_split=None, svm_c=None, svm_gamma=None, svm_kernel=None, pytorch_model=None, pytorch_optimizer=None, mlp_training_portion=None, pytorch_loss_function=None, mlp_hidden_layer_sizes=None, mlp_alpha=None, mlp_learning_rate_init=None, mlp_max_iter=None, mlp_batch_size=None, mlp_activation=None, pytorch_optimization_n_iter_no_change=None, pytorch_optimization_tol=None, pytorch_device=None, pretrained_model_path=None, pretrained_model_replace=None, num_classes=None, min_progress=1, max_progress=100)

Trains a classifier.

Trains a classifier using ROIs or spectral signatures.

Parameters:

spectral_signatures – a SpectralSignaturesCatalog() containing spectral signatures.
algorithm_name – algorithm name selected from cfg.classification_algorithms; if None, minimum distance is used.
additional_algorithm_name – additional algorithm name useful for pretrained models, using parameters of the named algorithm; after executing the pretrained model, the additional algorithm is executed on the embeddings.
n_processes – number of parallel processes.
available_ram – number of megabytes of RAM available to processes.
cross_validation – if True, perform cross validation for algorithms provided through scikit-learn (random_forest, random_forest_ovr, support_vector_machine, multi_layer_perceptron).
x_matrix – optional previously saved x matrix.
y – optional previously saved y matrix.
covariance_matrices – dictionary of previously calculated covariance matrices (used in maximum likelihood only).
svc_classification_confidence – if True, write also additional classification confidence rasters as output; required information for support_vector_machine.
input_normalization – perform input normalization; options are z_score or linear_scaling.
normalization_values – list of normalization paramters defined for each variable [normalization expressions, mean values, standar deviation values, minimum values, maximum values].
class_weight – specific for random forest and support vector machine, if None each class has equal weight 1, if balanced weight is computed inversely proportional to class frequency.
find_best_estimator – specific for scikit classifiers, if True, find automatically the best parameters and fit the model, if integer the greater the value the more are the tested combinations.
rf_max_features – specific for random forest, if None all features are considered in node splitting, available options are sqrt as square root of all the features, an integer number, or a float number for a fraction of all the features.
rf_number_trees – specific for random forest, number of trees in the forest.
rf_min_samples_split – specific for random forest through scikit, sets the minimum number of samples required to split an0 internal node; default = 2.
svm_c – specific for support_vector_machine through scikit, sets the regularization parameter C; default = 1.
svm_gamma – specific for support_vector_machine through scikit, sets the kernel coefficient; default = scale.
svm_kernel – specific for support_vector_machine through scikit, sets the kernel; default = rbf.
mlp_training_portion – specific for multi_layer_perceptron and pytorch_multi_layer_perceptron, the proportion of data to be used as training (default = 0.9) and the remaining part as test (default = 0.1).
mlp_hidden_layer_sizes – specific for multi_layer_perceptron and pytorch_multi_layer_perceptron, list of values where each value defines the number of neurons in a hidden layer (e.g., [200, 100] for two hidden layers of 200 and 100 neurons respectively); default = [100].
mlp_alpha – specific for multi_layer_perceptron and pytorch_multi_layer_perceptron, weight decay (also L2 regularization term) for Adam optimizer (default = 0.0001).
mlp_learning_rate_init – specific for multi_layer_perceptron and pytorch_multi_layer_perceptron, sets initial learning rate (default = 0.001).
mlp_max_iter – specific for multi_layer_perceptron and pytorch_multi_layer_perceptron, sets the maximum number of iterations (default = 200).
mlp_batch_size – specific for multi_layer_perceptron and pytorch_multi_layer_perceptron, sets the number of samples per batch for optimizer; if auto, the batch is the minimum value between 200 and the number of samples (default = auto).
mlp_activation – specific for multi_layer_perceptron and pytorch_multi_layer_perceptron, sets the activation function (default = relu).
pytorch_model – specific for pytorch_multi_layer_perceptron, custom pytorch nn.Module.
pytorch_optimizer – specific for pytorch_multi_layer_perceptron, custom pytorch optimizer.
pytorch_loss_function – specific for pytorch_multi_layer_perceptron, sets a custom loss function (default = CrossEntropyLoss).
pytorch_optimization_n_iter_no_change – specific for pytorch_multi_layer_perceptron, sets the maximum number of epochs where the loss is not improving by at least the value pytorch_optimization_tol (default = 5).
pytorch_optimization_tol – specific for pytorch_multi_layer_perceptron, sets the tolerance of optimization (default = 0.0001).
pytorch_device – specific for pytorch_multi_layer_perceptron, processing device cpu (default) or cuda if available.
pretrained_model_path – path to pretrained model
pretrained_model_replace – pretrained model replace keys
num_classes – number of classes for pretrained model
min_progress – minimum progress value for Progress().
max_progress – maximum progress value for Progress().

Returns:

Classifier() object.

Examples

Load a classifier

>>> import remotior_sensus
>>> rs = remotior_sensus.Session()
>>> signature_catalog = rs.spectral_signatures_catalog()
>>> classifier = Classifier.train(
>>> spectral_signatures=spectral_signatures,
>>> algorithm_name='minimum distance')

Performs band classification.

This tool allows for classification of raster bands using the selected algorithm.

Parameters:

input_bands – list of input raster paths, or a BandSet number, or a previously defined BandSet.
output_path – path of output file.
overwrite – if True, output overwrites existing files.
spectral_signatures – a SpectralSignaturesCatalog() containing spectral signatures.
algorithm_name – algorithm name selected from cfg.classification_algorithms; if None, minimum distance is used.
bandset_catalog – BandSetCatalog object.
macroclass – if True, use macroclass ID from ROIs or spectral signatures; if False use class ID.
threshold – if False, classification without threshold; if True, use single threshold for each signature; if float, use this value as threshold for all the signature.
classification_confidence – if True, write also additional classification confidence rasters as output.
signature_raster – if True, write additional rasters for each spectral signature as output.
n_processes – number of parallel processes.
available_ram – number of megabytes of RAM available to processes.
cross_validation – if True, perform cross validation for algorithms provided through scikit-learn (random_forest, random_forest_ovr, support_vector_machine, multi_layer_perceptron).
load_classifier – path to a previously saved classifier.
x_input – optional previously saved x matrix.
y_input – optional previously saved y matrix.
covariance_matrices – dictionary of previously calculated covariance matrices (used in maximum_likelihood).
input_normalization – perform input normalization; options are z_score or linear_scaling.
only_fit – perform only classifier fitting.
save_classifier – save classifier to file.
class_weight – specific for random forest and support vector machine, if None each class has equal weight 1, if ‘balanced’ weight is computed inversely proportional to class frequency.
find_best_estimator – specific for scikit classifiers, if True, find automatically the best parameters and fit the model, if integer the greater the value the more are the tested combinations.
rf_max_features – specific for random forest, if None all features are considered in node splitting, available options are sqrt as square root of all the features, an integer number, or a float number for a fraction of all the features.
rf_number_trees – specific for random forest, number of trees in the forest.
rf_min_samples_split – specific for random forest through scikit, sets the minimum number of samples required to split an internal node; default = 2.
svm_c – specific for support_vector_machine through scikit, sets the regularization parameter C; default = 1.
svm_gamma – specific for support_vector_machine through scikit, sets the kernel coefficient; default = scale.
svm_kernel – specific for support_vector_machine through scikit, sets the kernel; default = rbf.
mlp_training_portion – specific for multi_layer_perceptron and pytorch_multi_layer_perceptron, the proportion of data to be used as training (default = 0.9) and the remaining part as test (default = 0.1).
mlp_hidden_layer_sizes – specific for multi_layer_perceptron and pytorch_multi_layer_perceptron, list of values where each value defines the number of neurons in a hidden layer (e.g., [200, 100] for two hidden layers of 200 and 100 neurons respectively); default = [100].
mlp_alpha – specific for multi_layer_perceptron and pytorch_multi_layer_perceptron, weight decay (also L2 regularization term) for Adam optimizer (default = 0.0001).
mlp_learning_rate_init – specific for multi_layer_perceptron and pytorch_multi_layer_perceptron, sets initial learning rate (default = 0.001).
mlp_max_iter – specific for multi_layer_perceptron and pytorch_multi_layer_perceptron, sets the maximum number of iterations (default = 200).
mlp_batch_size – specific for multi_layer_perceptron and pytorch_multi_layer_perceptron, sets the number of samples per batch for optimizer; if auto, the batch is the minimum value between 200 and the number of samples (default = auto).
mlp_activation – specific for multi_layer_perceptron and pytorch_multi_layer_perceptron, sets the activation function (default = relu).
pytorch_model – specific for pytorch_multi_layer_perceptron, custom pytorch nn.Module.
pytorch_optimizer – specific for pytorch_multi_layer_perceptron, custom pytorch optimizer.
pytorch_loss_function – specific for pytorch_multi_layer_perceptron, sets a custom loss function (default CrossEntropyLoss).
pytorch_optimization_n_iter_no_change – specific for pytorch_multi_layer_perceptron, sets the maximum number of epochs where the loss is not improving by at least the value pytorch_optimization_tol (default = 5).
pytorch_optimization_tol – specific for pytorch_multi_layer_perceptron, sets the tolerance of optimization (default = 0.0001).
pytorch_device – specific for pytorch_multi_layer_perceptron, processing device cpu (default) or cuda if available.
pretrained_model_path – specific for pretrained models such as pytorch_pretrained_s2_swin_v2_base, the path to the pth file of the pretrained model.
additional_algorithm_name – additional algorithm name useful for pretrained models, using parameters of the named algorithm; after executing the pretrained model, the additional algorithm is executed on the embeddings.
progress_message – if True then start progress message, if False does not start the progress message (useful if launched from other tools).

Returns:

If only_fit is True returns OutputManager() object with

extra = {‘classifier’: classifier, ‘model_path’: output model path}

If only_fit is False returns OutputManager() object with

path = classification path
extra = {‘model_path’: output model path}

remotior_sensus.tools.band_classification.check_pretrained_model_path(algorithm_name, pretrained_model_path=None)