satsense package

Module contents

Satsense package.

class satsense.Image(filename, satellite, band='rgb', normalization_parameters=None, block=None, cached=None)[source]

Bases: object

Image class that provides a unified interface to satellite images.

Under the hood rasterio is used, so any format supported by rasterio can be used.

  • filename (str) – The name of the image
  • satellite (str) – The name of the satelite (i.e. worldview3, quickbird etc.)
  • band (str) – The band for the grayscale image, or ‘rgb’. The default is ‘rgb’
  • normalization_parameters (dict or boolean, optional) –

    if False no normalization is done. if None the default normalization will be applied (cumulative with 2, 98 percentiles)

    f a Dictionary that describes the normalization parameters The following keys can be supplied:

    • technique: string
      The technique to use, can be ‘cumulative’ (default), ‘meanstd’ or ‘minmax’
    • percentiles: list[int]
      The percentiles to use (exactly 2) if technique is cumulative, default is [2, 98]
    • numstds: float
      Number of standard deviations to use if technique is meanstd
  • block (tuple or, optional) – The part of the image read defined in a rasterio compatible way, e.g. two tuples or a object
  • cached (array-like or boolean, optional) – If True bands and base images are cached in memory if an array a band or base image is cached if its name is in the array


Load an image and inspect the shape and bands

from satsense import Image >>> image = Image(‘test/data/source/section_2_sentinel.tif’, ‘quickbird’) >>> image.shape (152, 155)

>>> image.bands
{'blue': 0, 'green': 1, 'red': 2, 'nir-1': 3}
CRS({'init': 'epsg:32643'})

See also


itypes = {'canny_edge': <function get_canny_edge_image>, 'gray_ubyte': <function get_gray_ubyte_image>, 'grayscale': <function get_grayscale_image>, 'ndsi': functools.partial(<function ndxi_image>, ndxi_type='ndsi'), 'ndwi': functools.partial(<function ndxi_image>, ndxi_type='ndwi'), 'nir_ndvi': functools.partial(<function ndxi_image>, ndxi_type='nir_ndvi'), 'rb_ndvi': functools.partial(<function ndxi_image>, ndxi_type='rb_ndvi'), 'rg_ndvi': functools.partial(<function ndxi_image>, ndxi_type='rg_ndvi'), 'rgb': <function get_rgb_image>, 'texton_descriptors': <function get_texton_descriptors>, 'wvsi': functools.partial(<function ndxi_image>, ndxi_type='wvsi')}
classmethod register(itype, function)[source]

Register a new image type.

  • itype (str) – (internal) name of the image type
  • function – Function definition that should take a single Image parameter and return a numpy.ndarray or

See also


Create a subset of Image.

Parameters:block (tuple or – The part of the image to read defined in a rasterio compatible way, e.g. two tuples or a object
Returns:subsetted image
Return type:image.Image

Precompute the normalization of the image

Normalization is done using the normalization_parameters supplied during class instantiation. Normalization parameters are computed automatically for all bands when required, but doing it explicitly can save some time, e.g. if there are more bands in the image than needed.

Parameters:*bands (list[str] or None) – The list of bands to normalize, if None all bands will be normalized
Raises:ValueError: – When trying to compute the normalization on a partial image, as created by using the copy_block method.

See also

func:_normalize Get normalization limits for band(s).

Provide shape attribute.


Provide crs attribute.


Provide transform attribute.


Perform a scaled transformation.

Returns:out – An affine transformation scaled by the step size
Return type:affine.Affine
satsense.extract_features(features: Iterator[satsense.features.Feature], generator: satsense.generators.FullGenerator, n_jobs: int = -1)[source]

Compute features.

  • features – Iterable of features.
  • generator – Generator providing the required windows on the image.
  • n_jobs – The maximum number of processes to use. The default is to use the value returned by os.cpu_count().

satsense.FeatureVector – The requested feature vectors.


Extracting features from an image:

import numpy as np
from satsense import Image
from satsense.generators import FullGenerator
from satsense.extract import extract_features
from satsense.features import NirNDVI, HistogramOfGradients, Pantex

# Define the features to calculate
features = [
    HistogramOfGradients(((50, 50), (100, 100))),
    NirNDVI(((50, 50),)),
    Pantex(((50, 50), (100, 100))),

# Load the image into a generator
# This generator splits the image into chunks of 10x10 pixels
image = Image('test/data/source/section_2_sentinel.tif', 'quickbird')
generator = FullGenerator(image, (10, 10))

# Calculate all the features and append them to a list
vector = []
for feature_vector in extract_features(features, generator):
    # The shape returned is (x, y, w, v)
    # where x is the number of chunks in the x direction
    #       y is the number of chunks in the y direction
    #       w is the number of windows the feature uses
    #       v is the length of the feature per window
    # Reshape the resulting vector so it is (x, y, w * v)
    # e.g. flattened along the windows and features
    data = feature_vector.vector.reshape(
                *feature_vector.vector.shape[0:2], -1)
# dstack reshapes the vector into and (x, y, n)
# where n is the total length of all features
featureset = np.dstack(vector)
class satsense.FeatureVector(feature, vector, crs=None, transform=None)[source]

Bases: object

Class to store a feature vector in.

  • feature (satsense.feature.Feature) – The feature to store
  • vector (array-like) – The data of the computed feature
  • crs – The coordinate reference system for the data
  • transform (Affine) – The affine transformation for the data
get_filename(window, prefix='', extension='nc')[source]

Construct filename from input parameters.

  • window (tuple) – The shape of the window used to calculate the feature
  • prefix (str) – Prefix for the filename
  • extension (str) – Filename extension

Return type:


save(filename_prefix='', extension='nc')[source]

Save feature vectors to files.

  • filename_prefix (str) – Prefix for the filename
  • extension (str) – Filename extension
  • Returns – 1-D array-like (str)
classmethod from_file(feature, filename_prefix)[source]

Restore saved features.

  • feature (Feature) – The feature to restore from a file
  • filename_prefix (str) – The directory and other prefixes to find the feature file at

The feature loaded into a FeatureVector object

Return type: