GIS Utilities#

This module contains tools to help project between coordinate systems. The module will first use GDAL if installed. If GDAL is not installed then pyproj is used. Main functions are:

  • project_point_ll2utm

  • project_point_utm2ll

These can take in a point or an array or list of points to project.

latitude and longitude can be input as:

  • ‘DD:mm:ss.ms’

  • ‘DD.decimal_degrees’

  • float(DD.decimal_degrees)

watex.utils.gistools.assert_elevation_value(elevation)[source]#

make sure elevation is a floating point number

watex.utils.gistools.assert_lat_value(latitude)[source]#

make sure latitude is in decimal degrees

watex.utils.gistools.assert_lon_value(longitude)[source]#

make sure longitude is in decimal degrees

watex.utils.gistools.assert_xy_coordinate_system(x, y)[source]#

Assert the coordinates system of x and y.

Parameters

  • x (arraylike 1d) – Array of position coordinates x and y

  • y (arraylike 1d) – Array of position coordinates x and y

Returns

cs – Coordinates system [‘utm’| ‘dms’|’ll’] as:

-‘ll’ for longitude -latitude coordinate system - ‘dms’ for degree-minute-second (DD:MM:SS) coordinate system. - ‘utm’ for ‘UTM’ coordinate system.

Return type

str

Note

Note that any other values that does not fit longitude-latitude (‘ll’) or Degree-minute-seconds (‘DD:MM:SS’) should be considered as ‘UTM’ coordinate system.

Examples

>>> import numpy as np
>>> np.random.seed (42 )
>>> from watex.utils.gistools import assert_xy_coordinate_system
>>> x, y = np.random.rand(7 ), np.arange (7 )
>>> assert_xy_coordinate_system (x, y)
'll'
>>> assert_xy_coordinate_system (x, y*180)
'utm'
>>> x = ['28:24:43.08','28:24:42.69','28:24:42.31']
>>> y = ['109:19:58.34','109:19:58.93','109:19:59.51']
>>> assert_xy_coordinate_system (x, y)
'dms'
watex.utils.gistools.convert_position_float2str(position)[source]#

convert position float to a string in the format of DD:MM:SS

Parameters

**position** (float) – decimal degrees of latitude or longitude

Returns

**position_str** – latitude or longitude in format of DD:MM:SS.ms

Return type

string

Example

>>> import watex.utils.gis_tools as gis_tools
>>> gis_tools.convert_position_float2str(-118.34563)
watex.utils.gistools.convert_position_str2float(position_str)[source]#

Convert a position string in the format of DD:MM:SS to decimal degrees

Parameters

**position_str** (string ('DD:MM:SS.ms')) – degrees of latitude or longitude

Returns

**position** – latitude or longitude in decimal degrees

Return type

float

Example

>>> import watex.utils.gis_tools as gis_tools
>>> gis_tools.convert_position_str2float('-118:34:56.3')
watex.utils.gistools.epsg_project(x, y, epsg_from, epsg_to, proj_str=None)[source]#

project some xy points using the pyproj modules

Parameters

  • x (integer or float) – x coordinate of point

  • y (integer or float) – y coordinate of point

  • epsg_from (int) – epsg code of x, y points provided. To provide custom projection, set to 0 and provide proj_str

  • epsg_to (TYPE) – epsg code to project to. To provide custom projection, set to 0 and provide proj_str

  • proj_str (str) – Proj4 string to provide to pyproj if using custom projection. This proj string will be applied if epsg_from or epsg_to == 0. The default is None.

Returns

x and y coordinates of projected point.

Return type

xp, yp

watex.utils.gistools.get_epsg(latitude, longitude)[source]#

get epsg code for the utm projection (WGS84 datum) of a given latitude and longitude pair

Parameters

  • latitude ([ string | float ]) – latitude in [ ‘DD:mm:ss.ms’ | ‘DD.decimal’ | float ]

  • longitude ([ string | float ]) – longitude in [ ‘DD:mm:ss.ms’ | ‘DD.decimal’ | float ]

Returns

EPSG number

Return type

int

Example
>>> gis_tools.get_epsg(-34.299442, '149:12:03.71')

32755

watex.utils.gistools.get_utm_string_from_sr(spatialreference)[source]#

return utm zone string from spatial reference instance

watex.utils.gistools.get_utm_zone(latitude, longitude)[source]#

Get utm zone from a given latitude and longitude

Parameters

  • latitude ([ string | float ]) – latitude in [ ‘DD:mm:ss.ms’ | ‘DD.decimal’ | float ]

  • longitude ([ string | float ]) – longitude in [ ‘DD:mm:ss.ms’ | ‘DD.decimal’ | float ]

Returns

zone number

Return type

int

Returns

is northern

Return type

[ True | False ]

Returns

UTM zone

Return type

string

Example
>>> lat, lon = ('-34:17:57.99', 149.2010301)
>>> zone_number, is_northing, utm_zone = gis_tools.get_utm_zone(lat, lon)
>>> print(zone_number, is_northing, utm_zone)

(55, False, ‘55H’)

watex.utils.gistools.get_utm_zone_2(latitude, longitude)[source]#

Get utm zone from a given latitude and longitude

watex.utils.gistools.ll_to_utm(reference_ellipsoid, lat, lon)[source]#

converts lat/long to UTM coords. Equations from USGS Bulletin 1532 East Longitudes are positive, West longitudes are negative. North latitudes are positive, South latitudes are negative Lat and Long are in decimal degrees Written by Chuck Gantz- chuck.gantz@globalstar.com

Outputs:

UTMzone, easting, northing

watex.utils.gistools.project_point_ll2utm(lat, lon, datum='WGS84', utm_zone=None, epsg=None)[source]#

Project a point that is in latitude and longitude to the specified UTM coordinate system.

Parameters

  • latitude ([ string | float ]) – latitude in [ ‘DD:mm:ss.ms’ | ‘DD.decimal’ | float ]

  • longitude ([ string | float ]) – longitude in [ ‘DD:mm:ss.ms’ | ‘DD.decimal’ | float ]

  • datum (string) – well known datum

  • utm_zone ([ string | int ]) – utm_zone {0-9}{0-9}{C-X} or {+, -}{0-9}{0-9}

  • epsg ([ int | string ]) – EPSG number defining projection (see http://spatialreference.org/ref/ for moreinfo) Overrides utm_zone if both are provided

Returns

project point(s)

Return type

tuple if a single point, np.recarray if multiple points * tuple is (easting, northing,utm_zone) * recarray has attributes (easting, northing, utm_zone, elevation)

Single Point
>>> gis_tools.project_point_ll2utm('-34:17:57.99', '149.2010301')

(702562.6911014864, 6202448.5654573515, ‘55H’)

Multiple Points
>>> lat = np.arange(20, 40, 5)
>>> lon = np.arange(-110, -90, 5)
>>> gis_tools.project_point_ll2utm(lat, lon, datum='NAD27')
rec.array([( -23546.69921068, 2219176.82320353, 0., ‘13R’),

( 500000. , 2764789.91224626, 0., ‘13R’), ( 982556.42985037, 3329149.98905941, 0., ‘13R’), (1414124.6019547 , 3918877.48599922, 0., ‘13R’)],

dtype=[(‘easting’, ‘<f8’), (‘northing’, ‘<f8’),

(‘elev’, ‘<f8’), (‘utm_zone’, ‘<U3’)])

watex.utils.gistools.project_point_ll2utm_2(lat, lon, datum='WGS84', utm_zone=None, epsg=None)[source]#

Project a point that is in Lat, Lon (will be converted to decimal degrees) into UTM coordinates.

Parameters

  • **lat** (float or string (DD:MM:SS.ms)) – latitude of point

  • **lon** (float or string (DD:MM:SS.ms)) – longitude of point

  • **datum** (string) – well known datum ex. WGS84, NAD27, NAD83, etc.

  • **utm_zone** (string) – zone number and ‘S’ or ‘N’ e.g. ‘55S’

  • **epsg** (int) – epsg number defining projection (see http://spatialreference.org/ref/ for moreinfo) Overrides utm_zone if both are provided

Returns

**proj_point** – projected point in UTM in Datum

Return type

tuple(easting, northing, zone)

watex.utils.gistools.project_point_utm2ll(easting, northing, utm_zone, datum='WGS84', epsg=None)[source]#

Project a point that is in UTM to the specified geographic coordinate system.

Parameters

  • easting (float) – easting in meters

  • northing (float) – northing in meters

  • datum (string) – well known datum

  • utm_zone ([ string | int ]) – utm_zone {0-9}{0-9}{C-X} or {+, -}{0-9}{0-9}

  • epsg ([ int | string ]) – EPSG number defining projection (see http://spatialreference.org/ref/ for moreinfo) Overrides utm_zone if both are provided

Returns

project point(s)

Return type

tuple if a single point, np.recarray if multiple points * tuple is (easting, northing,utm_zone) * recarray has attributes (easting, northing, utm_zone, elevation)

Single Point
>>> gis_tools.project_point_utm2ll(670804.18810336,

… 4429474.30215206, … datum=’WGS84’, … utm_zone=’11T’, … epsg=26711) (40.000087, -114.999128)

Multiple Points
>>> gis_tools.project_point_utm2ll([670804.18810336, 680200],

… [4429474.30215206, 4330200], … datum=’WGS84’, utm_zone=’11T’, … epsg=26711) rec.array([(40.000087, -114.999128), (39.104208, -114.916058)],

dtype=[(‘latitude’, ‘<f8’), (‘longitude’, ‘<f8’)])

watex.utils.gistools.project_point_utm2ll_2(easting, northing, utm_zone, datum='WGS84', epsg=None)[source]#

Project a point that is in Lat, Lon (will be converted to decimal degrees) into UTM coordinates.

Parameters

  • **easting** (float) – easting coordinate in meters

  • **northing** (float) – northing coordinate in meters

  • **utm_zone** (string (##N or ##S)) – utm zone in the form of number and North or South hemisphere, 10S or 03N

  • **datum** (string) – well known datum ex. WGS84, NAD27, etc.

Returns

**proj_point** – projected point in lat and lon in Datum, as decimal degrees.

Return type

tuple(lat, lon)

watex.utils.gistools.project_points_ll2utm(lat, lon, datum='WGS84', utm_zone=None, epsg=None)[source]#

Project a list of points that is in Lat, Lon (will be converted to decimal degrees) into UTM coordinates.

Parameters

  • **lat** (float or string (DD:MM:SS.ms)) – latitude of point

  • **lon** (float or string (DD:MM:SS.ms)) – longitude of point

  • **datum** (string) – well known datum ex. WGS84, NAD27, NAD83, etc.

  • **utm_zone** (string) – zone number and ‘S’ or ‘N’ e.g. ‘55S’. Defaults to the centre point of the provided points

  • **epsg** (int) – epsg number defining projection (see http://spatialreference.org/ref/ for moreinfo) Overrides utm_zone if both are provided

Returns

**proj_point** – projected point in UTM in Datum

Return type

tuple(easting, northing, zone)

watex.utils.gistools.split_utm_zone(utm_zone)[source]#

Split utme zone into zone number and is northing

Parameters

utm_zone ([ string | int ]) – utm zone string as {0-9}{0-9}{C-X} or {+,-}{0-9}{0-9}

Returns

utm zone number

Return type

int

Returns

is_northern

Return type

boolean [ True | False ]

Example
>>> gis_tools.split_utm_zone('11S')

11, True

watex.utils.gistools.utm_letter_designator(latitude)[source]#

Get the UTM zone letter designation for a given latitude

Parameters

latitude ([ string | float ]) – latitude in [ ‘DD:mm:ss.ms’ | ‘DD.decimal’ | float ]

Returns

UTM zone letter designation

Return type

string

Example
>>> gis_utils.utm_letter_designator('-34:17:57.99')

H

watex.utils.gistools.utm_to_ll(reference_ellipsoid, northing, easting, zone)[source]#

converts UTM coords to lat/long. Equations from USGS Bulletin 1532 East Longitudes are positive, West longitudes are negative. North latitudes are positive, South latitudes are negative Lat and Long are in decimal degrees. Written by Chuck Gantz- chuck.gantz@globalstar.com Converted to Python by Russ Nelson <nelson@crynwr.com>

Outputs:

Lat,Lon

watex.utils.gistools.utm_wgs84_conv(lat, lon)[source]#

Bidirectional UTM-WGS84 converter Turbo87/utm :param lat: :param lon: :return: tuple(e, n, zone, lett)

watex.utils.gistools.utm_zone_to_epsg(zone_number, is_northern)[source]#

get epsg code (WGS84 datum) for a given utm zone

Parameters

  • zone_number (int) – UTM zone number

  • is_northing ([ True | False ]) – Boolean of UTM is in northern hemisphere

Returns

EPSG number

Return type

int

Example
>>> gis_tools.utm_zone_to_epsg(55, False)

32755

watex.utils.gistools.validate_epsg(epsg)[source]#

Make sure epsg is an integer

Parameters

epsg ([ int | str ]) – EPSG number

Returns

EPSG number

Return type

int

watex.utils.gistools.validate_input_values(values, location_type=None)[source]#

make sure the input values for lat, lon, easting, northing will be an numpy array with a float data type

can input a string as a comma separated list

Parameters

values ([ float | string | list | numpy.ndarray ]) – values to project, can be given as: * float * string of a single value or a comma separate string ‘34.2, 34.5’ * list of floats or string * numpy.ndarray

Returns

array of floats

Return type

numpy.ndarray(dtype=float)

watex.utils.gistools.validate_utm_zone(utm_zone)[source]#

Make sure utm zone is a valid string

Parameters

utm_zone ([ int | string ]) – UTM zone as {0-9}{0-9}{C-X} or {+, -}{0-9}{0-9}

Returns

valid UTM zone

Return type

[ int | string ]