Location Filter

The location filter module is a utility module, that is usually accessed via The Entry.neighbors function or the find_entry API. However, the uitl module is importable and the functions can be used directly for more advanced use cases.

Location utility functions can convert the various possible inputs into a shapely.Polygon that can be used as a search area.

metacatalog.util.location.around(entry, distance, unit='km', query=None, buffer_use_epsg=3857)

Find other Entries around a given instance by specifying a distance around the entry. If an sqlalchemy query is supplied, the resulting query is returned, otherwise the filter area itself is returned.

Parameters:

• entry (Entry) – The Entry instance that is used to find neighbors. A list of Entry instances is also accepted, as well as an EntryGroup, which will resolve to a list of entries. A list will be converted to the Convex Hull around all instances.

• distance (int, float) – The search distance around the entry instance(s). The distance should be given in meter, if km or miles is used, specify the unit accordingly. Also mind the Note below.

• unit (str) – Can be one of ['meter', 'km', 'mile', 'nautic']. The unit will be used to convert the given distance to meter.

• buffer_use_epsg (int) – The EPSG number of a projected CRS that shall be used during buffering. Mind the Note below.

Note

metacatalog uses unprojected WGS84 coordinates for the contained coordinates. For applying a buffer, the coordinates of the argument need to be transformed into a projected coordinate reference system using meter as a unit. After buffering, the search area is back-transformed to WGS84. This can have accuracy implications. Nevertheless, this step is necessary, as the database can then filter without reprojections of possibly large amounts of data. By default the argument is transformed to Transversal Mercartor Projection, as this has global coverage. Unfortunately, the transformation error can get massive in some, especially small, study areas. Whenever possible overwrite the CRS to be used for buffering by a local reference system like UTM.

See also

build_query, get_search_shape

metacatalog.util.location.build_query(query: Query, area: Polygon) → Query

Small helper function to create the spatial filter.

Parameters:

• query (Query) – sqlalchemy orm query object. The filter will be appended (in an AND manner) to the exisiting query.

• area (Polygon) – shapely.geometry.Polygon of the search area. It will be resolved by a Within spatial filter.

Returns:

query – The filtered (unexecuted) sqlalchemy ORM query object.

Return type:

Query

metacatalog.util.location.get_search_shape(arg, buffer=None, buffer_use_epsg=3857) → BaseGeometry

Calculate a search shape from a whole bunch of arguments. The search shape can optionally be buffered.

Note

Some arguments might resolve to a Point geometry. In these cases make sure to use a buffer value, at least by a small value. Otherwise the query will end up to search for exact matches, which will always turn False, even for the Point itself.

Parameters:

• buffer (int, float) – Optional. If given, the search area resolved from the argument will be buffered by the given value. Remind that buffer has to transform the data to apply Euklidean buffers.

• buffer_use_epsg (int) – The EPSG number of a projected CRS that shall be used during buffering. Mind the Note below.

• arg (list, str, byte, shapely.BaseGeometry) –

  A search area can be generate from a rich list of input arguments. Depending on the data type and shape of arg, different search areas are resolved.

  • str has to be a WKT of type Point or Polygon

  • byte has to be a WKB of type Point or Polygon

  • BaseGeometry any valid shapely Geometry, that implements the buffer function

  • list has to be a list of int or float values. Resolving is based on shape:

    • len(arg)==2 is used as Point(arg). Remind to buffer the Point

    • len(arg)==4 is a BoundingBox defined as [left, bottom, right, up]

    • 2 dimensional lists are converted to Polygons

Note

metacatalog uses unprojected WGS84 coordinates for the contained coordinates. For applying a buffer, the coordinates of the argument need to be transformed into a projected coordinate reference system using meter as a unit. After buffering, the search area is back-transformed to WGS84. This can have accuracy implications. Nevertheless, this step is necessary, as the database can then filter without reprojections of possibly large amounts of data. By default the argument is transformed to Transversal Mercartor Projection, as this has global coverage. Unfortunately, the transformation error can get massive in some, especially small, study areas. Whenever possible overwrite the CRS to be used for buffering by a local reference system like UTM.

Returns:

area – The resolved Polygon, which can be used to create a spatial filter to find Entries within the area.

Return type:

shapely.geometry.Polygon

See also

build_query, around