samgis_web.io_package package

Submodules

samgis_web.io_package.coordinates_pixel_conversion module

functions useful to convert to/from latitude-longitude coordinates to pixel image coordinates

samgis_web.io_package.coordinates_pixel_conversion.get_latlng_to_pixel_coordinates(latlng_origin_ne, latlng_origin_sw, latlng_current_point, zoom, k)[source]

Parse the input request lambda event

Parameters:

  • latlng_origin_ne (LatLngDict) – NE latitude-longitude origin point

  • latlng_origin_sw (LatLngDict) – SW latitude-longitude origin point

  • latlng_current_point (LatLngDict) – latitude-longitude prompt point

  • zoom (int | float) – Level of detail

  • k (str) – prompt type

Returns:

pixel image coordinate point

Return type:

ImagePixelCoordinates

samgis_web.io_package.geo_helpers module

handle geo-referenced raster images

samgis_web.io_package.geo_helpers.get_vectorized_raster_as_geojson(mask, transform)[source]

Get shapes and values of connected regions in a dataset or array

Parameters:

  • mask (ndarray) – numpy mask

  • transform (TupleFloat) – tuple of float to transform into an Affine transform

Return type:

DictStrInt

Returns:

dict containing the output geojson and the geojson shapes number

samgis_web.io_package.geo_helpers.load_affine_transformation_from_matrix(matrix_source_coefficients)[source]

Wrapper for rasterio.Affine.from_gdal() method. Useful to read WorldFiles (TFW, PGW)

Parameters:

matrix_source_coefficients (ListFloat) – 6 floats ordered by GDAL.

Return type:

Affine

Returns:

Affine transform

samgis_web.io_package.raster_helpers module

helpers for computer vision duties

samgis_web.io_package.raster_helpers.calculate_slope(dem_array, cell_size, calctype='degree')[source]

Return a numpy array representing slope (1st grade derivative)

Parameters:

  • dem_array (ndarray) – input numpy array

  • cell_size (int) – window size to calculate slope

  • calctype (str, default: 'degree') – calculus type

Returns:

slope image

Return type:

ndarray

samgis_web.io_package.raster_helpers.check_empty_array(arr, val)[source]
Return True if the input numpy array is empy. Check if

  • all values are all the same value (0, 1 or given ‘val’ input float value)

  • all values that are not NaN are a given ‘val’ float value

Parameters:

  • arr (ndarray) – input numpy array

  • val (float) – value to use for check if array is empty

Returns:

True if the input numpy array is empty, False otherwise

Return type:

bool

samgis_web.io_package.raster_helpers.get_mapbox__terrain_rgb_formula(red, green, blue, casted_type=<class 'numpy.uint16'>)[source]

Mapbox Terrain-DEM v1 is a Mapbox-provided raster tileset is a global elevation layer. This tileset contains raw height values in meters in the Red, Green, and Blue channels of PNG tiles that can be decoded to raw heights in meters. Mapbox Terrain-DEM is an optimized version of the Mapbox Terrain-RGB v1 tileset, with some updated data and some compression to reduce precision at lower zoom levels, making smaller, faster-loading tiles. You can use Terrain-DEM for a wide variety of applications, both visual and analytical, from styling terrain slope and hillshades to generating 3D terrain meshes for video games.

# Data sources and updates Elevation data is not improved on a set schedule and is updated when and where it becomes available.

# Attribution When using this tileset publicly in a design or application you must provide [proper attribution](https://docs.mapbox.com/help/dive-deeper/attribution/).

# Terrain-RGB tiles The Mapbox Terrain-DEM tileset contains Terrain-RGB tiles. Terrain-RGB tiles include elevation data that is encoded using each color channel as a position in a base-256 numbering system. This approach allows for 16,777,216 unique values which can be mapped to 0.1 meter height increments, enabling vertical precision necessary for cartographic and 3D applications. To learn how to retrieve a Terrain-RGB tile and decode elevation data from its RGB values, see Mapbox Access elevation data guide.

# Layer Reference This tileset contains one layer with raster data.

  • Data up to zoom 15. The data is encoded to the equivalent of zoom 15 at 256 tile resolution (and zoom 14 for 512 tiles). Any higher zoom levels will not increase the resolution of the data loaded by your application.

  • 0.1 meter height increments. Elevation data is mapped to 0.1 meter height increments, which gives it the vertical precision necessary for cartographic and 3D applications.

  • Buffered tiles. Each map tile includes a 1-pixel buffer around the edges to enable tile interpolation in uses cases like terrain meshes.

# Elevation data Mapbox Terrain-DEM uses multiple data sources depending on the zoom level and location. Different sources often use different vertical datum references, including but not limited to NAVD 88, EGM 96, and Ordnance Datum Newlyn.

Different sources often use different vertical datum references; thus, attempting to normalize Mapbox elevation data to a particular geoid or vertical datum may lead to inaccuracies in data.

After retrieving tiles via one of Mapbox Mobile SDKs or Mapbox GL JS, you can use this equation to decode pixel values to height values:

height = -10000 + ((R * 256 * 256 + G * 256 + B) * 0.1)

Text from https://docs.mapbox.com/data/tilesets/reference/mapbox-terrain-dem-v1/#elevation-data

Args: red: red-valued channel image array green: green-valued channel image array blue: blue-valued channel image array casted_type: numpy type needed to avoid OverflowError

Returns:

Mapbox Terrain-DEM 2d digital elevation model raster

Return type:

ndarray

samgis_web.io_package.raster_helpers.get_nextzen_terrain_rgb_formula(red, green, blue, casted_type=<class 'numpy.uint16'>)[source]

Compute a 32-bits 2d digital elevation model from a nextzen ‘terrarium’ (terrain-rgb) raster. ‘Terrarium’ format PNG tiles contain raw elevation data in meters, in Mercator projection (EPSG:3857). All values are positive with a 32,768 offset, split into the red, green, and blue channels, with 16 bits of integer and 8 bits of fraction. To decode:

(red * 256 + green + blue / 256) - 32768

More details on https://www.mapzen.com/blog/elevation/

Parameters:

  • red (ndarray) – red-valued channel image array

  • green (ndarray) – green-valued channel image array

  • blue (ndarray) – blue-valued channel image array

  • casted_type (default: <class 'numpy.uint16'>) – numpy type needed to avoid OverflowError

Returns:

nextzen ‘terrarium’ 2d digital elevation model raster at 32 bits

Return type:

ndarray

samgis_web.io_package.raster_helpers.get_raster_terrain_rgb_like(arr, xyz_provider_name, nan_value_int=-12000, casted_type=<class 'numpy.uint16'>)[source]

Compute a 32-bits 2d digital elevation model from a terrain-rgb raster.

Parameters:

  • arr (ndarray) – rgb raster

  • xyz_provider_name – xyz provider

  • nan_value_int (int, default: -12000) – threshold int value to replace NaN

  • casted_type (default: <class 'numpy.uint16'>) – numpy type needed to avoid OverflowError

Returns:

2d digital elevation model raster at 32 bits

Return type:

ndarray

samgis_web.io_package.raster_helpers.get_rgb_image(arr_channel0, arr_channel1, arr_channel2, invert_image=True)[source]

Return an RGB image from input R,G,B channel arrays

Parameters:

  • arr_channel0 (ndarray) – channel image 0

  • arr_channel1 (ndarray) – channel image 1

  • arr_channel2 (ndarray) – channel image 2

  • invert_image (bool, default: True) – invert the RGB image channel order

Returns:

RGB image

Return type:

ndarray

samgis_web.io_package.raster_helpers.get_rgb_prediction_image(raster_cropped, slope_cellsize, invert_image=True)[source]

Return an RGB image from input numpy array

Parameters:

  • raster_cropped (ndarray) – input numpy array

  • slope_cellsize (int) – window size to calculate slope and curvature (1st and 2nd degree array derivative)

  • invert_image (bool, default: True)

Returns:

image filename, image path (with filename)

Return type:

tuple of str

samgis_web.io_package.raster_helpers.get_slope_curvature(dem, slope_cellsize, title='')[source]

Return a tuple of two numpy arrays representing slope and curvature (1st grade derivative and 2nd grade derivative)

Parameters:

  • dem (ndarray) – input numpy array

  • slope_cellsize (int) – window size to calculate slope and curvature

  • title (str, default: '') – array name

Returns:

slope image, curvature image

Return type:

tuple of ndarrays

samgis_web.io_package.raster_helpers.normalize_array(arr, high=255, norm_type='float', invert=False, title='')[source]

Return normalized numpy array between 0 and ‘high’ value. Default normalization type is int

Parameters:

  • arr (ndarray) – input numpy array

  • high (int, default: 255) – max value to use for normalization

  • norm_type (str, default: 'float') – type of normalization: could be ‘float’ or ‘int’

  • invert (bool, default: False) – bool to choose if invert the normalized numpy array

  • title (str, default: '') – array title name

Returns:

normalized numpy array

Return type:

ndarray

samgis_web.io_package.raster_helpers.normalize_array_list(arr_list, exaggerations_list=None, title='')[source]

Return a normalized numpy array from a list of numpy array and an optional list of exaggeration values.

Parameters:

  • arr_list (list[ndarray]) – list of array to use for normalization

  • exaggerations_list (list[float], default: None) – list of exaggeration values

  • title (str, default: '') – array title name

Returns:

normalized numpy array

Return type:

ndarray

samgis_web.io_package.raster_helpers.write_geojson_on_disk(geojson_content, prefix, suffix, folder_output_path='/tmp')[source]

Write a [geojson](https://geojson.org) on disk.

Parameters:

  • geojson_content (str) – json to write on disk

  • prefix (str) – string prefix used in image filename

  • suffix (str) – string prefix used in image filename

  • folder_output_path (default: '/tmp') – parent folder where to write the image

Return type:

Path

Returns:

Path of written geojson file.

samgis_web.io_package.raster_helpers.write_raster_png(arr, transform, prefix, suffix, folder_output_path='/tmp')[source]

Write a raster PNG image on disk, using a given Affine transformation. Write also an [WorldFile](https://www.autodesk.com/support/technical/article/caas/sfdcarticles/sfdcarticles/What-are-the-TFW-JGW-or-PGW-files.html) containing the geographic transformation.

Parameters:

  • arr (ndarray) – (3-band) ndarray image to write on disk

  • transform (Affine) – Affine geographic transformation

  • prefix (str) – string prefix used in image filename

  • suffix (str) – string suffix used in image filename

  • folder_output_path (str | Path, default: '/tmp') – parent folder where to write the image

Return type:

tuple[Path, Path]

Returns:

tuple of written file Paths (a ndarray image and a geographic transformation file - WorldFile with TFW extension)

samgis_web.io_package.raster_helpers.write_raster_tiff(arr, transform, prefix, suffix, folder_output_path='/tmp')[source]

Write a raster TIF image on disk, using a given Affine transformation. Write also an [WorldFile](https://www.autodesk.com/support/technical/article/caas/sfdcarticles/sfdcarticles/What-are-the-TFW-JGW-or-PGW-files.html) containing the geographic transformation.

Parameters:

  • arr – (1-band) ndarray image to write on disk

  • transform (Affine) – Affine geographic transformation

  • prefix (str) – string prefix used in image filename

  • suffix (str) – string suffix used in image filename

  • folder_output_path (default: '/tmp') – parent folder where to write the image

Return type:

tuple[Path, Path]

Returns:

tuple of written file Paths (a ndarray image and a geographic transformation file - WorldFile with TFW extension)

samgis_web.io_package.raster_helpers.write_worldfile(transform, output_folder, prefix, extension)[source]

Write an [WorldFile](https://www.autodesk.com/support/technical/article/caas/sfdcarticles/sfdcarticles/What-are-the-TFW-JGW-or-PGW-files.html) containing the geographic transformation.

Parameters:

  • transform (Affine) – Affine geographic transformation

  • output_folder (Path | str) – parent folder where to write the image

  • prefix (str) – string prefix used in image filename

  • extension (WorldFile) – WorldFile extension

Returns:

Path of written WorldFile geographic transformation file

samgis_web.io_package.tms2geotiff module

samgis_web.io_package.tms2geotiff.crop_raster(w, s, e, n, raster, raster_bbox, crs='EPSG:3857', driver='GTiff')[source]

Crop a raster using given bounding box (w, s, e, n) values

Parameters:

  • w (float) – cropping west edge

  • s (float) – cropping south edge

  • e (float) – cropping east edge

  • n (float) – cropping north edge

  • raster (ndarray) – raster image to crop

  • raster_bbox (TupleFloat) – bounding box of raster to crop

  • crs (str, default: 'EPSG:3857') – The coordinate reference system. Required in ‘w’ or ‘w+’ modes, it is ignored in ‘r’ or ‘r+’ modes.

  • driver (str, default: 'GTiff') – A short format driver name (e.g. “GTiff” or “JPEG”) or a list of such names (see GDAL docs at https://gdal.org/drivers/raster/index.html ). In ‘w’ or ‘w+’ modes a single name is required. In ‘r’ or ‘r+’ modes the driver can usually be omitted. Registered drivers will be tried sequentially until a match is found. When multiple drivers are available for a format such as JPEG2000, one of them can be selected by using this keyword argument.

Return type:

tuple[ndarray, Affine]

Returns:

cropped raster with its Affine transform

samgis_web.io_package.tms2geotiff.download_extent(w, s, e, n, zoom='auto', source=None, wait=0, max_retries=2, n_connections=2, use_cache=1)[source]

Download, merge and crop a list of tiles into a single geo-referenced image or a raster geodata

Parameters:

  • w (float) – West edge

  • s (float) – South edge

  • e (float) – East edge

  • n (float) – North edge

  • zoom (int, default: 'auto') – Level of detail

  • source (TileProvider, default: None) – The tile source: web tile provider or path to local file. The web tile provider can be in the form of a xyzservices.TileProvider object or a URL. The placeholders for the XYZ in the URL need to be {x}, {y}, {z}, respectively. For local file paths, the file is read with rasterio and all bands are loaded into the basemap. IMPORTANT: tiles are assumed to be in the Spherical Mercator projection (EPSG:3857), unless the crs keyword is specified.

  • wait (int, default: 0) – if the tile API is rate-limited, the number of seconds to wait between a failed request and the next try

  • max_retries (int, default: 2) – total number of rejected requests allowed before contextily will stop trying to fetch more tiles from a rate-limited API.

  • n_connections (int, default: 2) – Number of connections for downloading tiles in parallel. Be careful not to overload the tile server and to check the tile provider’s terms of use before increasing this value. E.g., OpenStreetMap has a max. value of 2 (https://operations.osmfoundation.org/policies/tiles/). If allowed to download in parallel, a recommended value for n_connections is 16, and should never be larger than 64.

  • use_cache (bool, default: 1) – If False, caching of the downloaded tiles will be disabled. This can be useful in resource constrained environments, especially when using n_connections > 1, or when a tile provider’s terms of use don’t allow caching.

Return type:

tuple[ndarray, Affine]

Returns:

parsed request input

samgis_web.io_package.tms2geotiff.get_transform_raster(raster, raster_bbox)[source]

Convert the input raster image to RGB and extract the Affine

Parameters:

  • raster (ndarray) – raster image to geo-reference

  • raster_bbox (TupleFloat) – bounding box of raster to crop

Return type:

tuple[ndarray, Affine]

Returns:

rgb raster image and its Affine transform

samgis_web.io_package.tms2geotiff.reshape_as_image(arr)[source]

Double swapping of image axis, needed in crop_raster().

Parameters:

arr (ndarray | MaskedArray) – numpy raster array

Return type:

ndarray

Returns:

numpy raster array

Module contents

input/output helpers functions