GeoSQL.Common (GeoSQL v1.2.0)

Commonly supported, but non-standard, GIS SQL functions. These are found in multiple database implementations, though they may differ in minor syntactical details in each implementation.

Implementation differences

In cases where the generated SQL differs based on the database in use, those functions will take an optional Ecto.Repo argument. When provided, this allows the function to decide which implementation-specific ipmlementation to use.

When no Ecto.Repo is provided, functions default to PostGIS-compatible syntax.

Database support

The features in the GeoSQL.Common modules are intended to contain functions available in all support SQL GIS extensions.

Some backends may require special initialization or dependencies loaded for some of these functions to work. For example, SpatiaLite must be built with the GEO package for some of these functions to be available.

Consult the documentation for the database GIS extension being used for such requirements.

Summary

Affine Transformations

rotate(geometry, rotate_radians, repo \\ nil)

scale(geometry, scale_x, scale_y, repo \\ nil)

translate(geometry, delta_x, delta_y, delta_z \\ 0)

Bounding Boxes

estimated_extent(table, column, repo \\ nil)

expand(geometry, units_to_expand)

extent(geometry, repo \\ nil)

max_coord(geometry, axis, repo \\ nil)

min_coord(geometry, axis, repo \\ nil)

Coverages

covered_by(geometryA, geometryB)

covers(geometryA, geometryB)

Data Formats

as_geojson(geometry, repo \\ nil)

as_gml(geometry, gml_version, precision, repo \\ nil)

as_kml(geometry, precision, name \\ "", repo \\ nil)

geom_from_geojson(geojson, repo \\ nil)

geom_from_gml(gml, srid \\ 0, repo \\ nil)

Passing an srid of 0 (the default) will not set an srid on the results. It is ignored for Spatialite in all cases.

geom_from_kml(kml, repo \\ nil)

Geometry Accessors

exterior_ring(geometry)

is_polygon_clockwise(geometry)

is_polygon_counter_clockwise(geometry)

number_of_dimensions(geometry)

number_of_geometries(geometry_collection)

number_of_points(geometry)

number_of_rings(geometry)

Geometry Constructors

collect(geometryList)

collect(geometryA, geometryB)

make_point(x, y, repo \\ nil)

make_point_m(x, y, z, repo \\ nil)

make_point_z(x, y, z, repo \\ nil)

make_point_zm(x, y, z, m, repo \\ nil)

Geometry Editors

add_point(line, point, position \\ -1)

collection_extract(collection, type)

multi(collection)

project(geometry, distance, azimuth)

remove_point(line, offset)

remove_repeated_points(geometry, tolerance \\ 0, repo \\ nil)

reverse(geometry)

segmentize(geometry, max_segement_length)

set_point(geometry, index, point)

snap(geometry, reference, precision)

snap_to_grid(geometry, size)

snap_to_grid(geometry, size_x, size_y)

snap_to_grid(geometry, origin_x, origin_y, size_x, size_y)

snap_to_grid(geometry, point, size_x, size_y, size_z, size_m)

Geometry Mutations

flip_coordinates(geometry, repo \\ nil)

shift_longitude(geometry, repo \\ nil)

Geometry Processing

build_area(geometry)

concave_hull(geometry, precision \\ 1, allow_holes? \\ false)

largest_empty_circle(geometry, tolerance \\ 0.0, repo \\ nil)

line_merge(geometry, directed? \\ false, repo \\ nil)

maximum_inscribed_circle(geometry, repo \\ nil)

minimum_bounding_circle(geometry, repo \\ nil)

minimum_bounding_radius(geometry, repo \\ nil)

offset_curve(line, distance)

oriented_envelope(geometry)

polygonize(geometry)

reduce_precision(geometry, grid_size)

shared_paths(geometryA, geometryB)

simplify(geometry, tolerance)

simplify_preserve_topology(geometry, tolerance)

triangulate_polygon(geometry, repo \\ nil)

Geometry Validation

is_valid_detail(geometry, esri_compat? \\ false)

is_valid_reason(geometry, esri_compat? \\ false)

make_valid(geometry)

Linear Referencing

add_measure(line, measure_start, measure_end)

interpolate_point(line, point)

line_interpolate_point(line, fraction, use_spheroid? \\ false, repo \\ nil)

Spatialite does not support spheroid calculations, and therefore use_spheroid? is ignored on that platform.

line_interpolate_points(line, fraction, use_spheroid? \\ true, repo \\ nil)

Note that Spatialite does not support spheroid calculations.

line_locate_point(line, point, use_spheroid? \\ false, repo \\ nil)

Spatialite does not support spheroid calculations, and therefore use_spheroid? is ignored on that platform.

line_substring(line, start_fraction, end_fraction, repo \\ nil)

locate_along(geometry, measure)

locate_between(geometry, measure_start, measure_end)

Measurement

azimuth(originGeometry, targetGeometry)

closest_point(geometryA, geometryB, use_spheroid? \\ false, repo \\ nil)

max_distance(geometryA, geometryB)

minimum_clearance(geometry, repo \\ nil)

minimum_clearance_line(geometry, repo \\ nil)

shortest_line(geometryA, geometryB, use_spheroid? \\ false, repo \\ nil)

Overlays

node(geometry)

split(inputGeometry, bladeGeometry)

subdivide(geometry, max_vertices \\ 256)

unary_union(geometry)

Spatial Reference Systems

set_srid(geometry, srid, repo \\ nil)

transform_pipeline(geometry, pipeline, srid, repo \\ nil)

Topology Relationships

relate_match(matrix, pattern)

Well-Known Binary (WKB)

as_ewkb(geometry, repo \\ nil)

geom_from_ewkb(geometry, repo \\ nil)

Well-Known Text (WKT)

as_ewkt(geometry, repo \\ nil)

bd_m_poly_from_text(wkt, srid)

bd_poly_from_text(wkt, srid)

geom_from_ewkt(geometry, repo \\ nil)

Affine Transformations

rotate(geometry, rotate_radians, repo \\ nil)

(macro)

scale(geometry, scale_x, scale_y, repo \\ nil)

(macro)

@spec scale(
  GeoSQL.geometry_input(),
  scale_x :: number(),
  scale_y :: number(),
  Ecto.Repo.t() | nil
) ::
  GeoSQL.fragment()

translate(geometry, delta_x, delta_y, delta_z \\ 0)

(macro)

Bounding Boxes

estimated_extent(table, column, repo \\ nil)

(macro)

@spec estimated_extent(
  table :: String.t() | {schema :: String.t(), table :: String.t()},
  column :: String.t(),
  Ecto.Repo.t() | nil
) :: GeoSQL.fragment()

expand(geometry, units_to_expand)

(macro)

@spec expand(
  geometry :: GeoSQL.geometry_input(),
  units_to_expand :: number()
) :: GeoSQL.fragment()

extent(geometry, repo \\ nil)

(macro)

@spec extent(GeoSQL.geometry_input(), Ecto.Repo.t() | nil) :: GeoSQL.fragment()

max_coord(geometry, axis, repo \\ nil)

(macro)

@spec max_coord(GeoSQL.geometry_input(), axis :: :x | :y | :z, Ecto.Repo.t() | nil) ::
  GeoSQL.fragment()

min_coord(geometry, axis, repo \\ nil)

(macro)

@spec min_coord(GeoSQL.geometry_input(), axis :: :x | :y | :z, Ecto.Repo.t() | nil) ::
  GeoSQL.fragment()

Coverages

covered_by(geometryA, geometryB)

(macro)

covers(geometryA, geometryB)

(macro)

Data Formats

as_geojson(geometry, repo \\ nil)

(macro)

@spec as_geojson(geometry :: GeoSQL.geometry_input(), Ecto.Repo.t() | nil) ::
  GeoSQL.fragment()

as_gml(geometry, gml_version, precision, repo \\ nil)

(macro)

@spec as_gml(
  geometry :: GeoSQL.geometry_input(),
  gml_version :: 2 | 3,
  precision :: pos_integer(),
  Ecto.Repo.t()
) :: GeoSQL.fragment()

as_kml(geometry, precision, name \\ "", repo \\ nil)

(macro)

@spec as_kml(
  geometry :: GeoSQL.geometry_input(),
  precision :: pos_integer(),
  name :: String.t(),
  Ecto.Repo.t() | nil
) :: GeoSQL.fragment()

geom_from_geojson(geojson, repo \\ nil)

(macro)

@spec geom_from_geojson(
  geojson :: GeoSQL.geometry_input() | String.t(),
  Ecto.Repo.t() | nil
) ::
  GeoSQL.fragment()

geom_from_gml(gml, srid \\ 0, repo \\ nil)

(macro)

@spec geom_from_gml(
  gml :: GeoSQL.geometry_input() | String.t(),
  srid :: non_neg_integer(),
  Ecto.Repo.t() | nil
) :: GeoSQL.fragment()

Passing an srid of 0 (the default) will not set an srid on the results. It is ignored for Spatialite in all cases.

geom_from_kml(kml, repo \\ nil)

(macro)

@spec geom_from_kml(kml :: GeoSQL.geometry_input() | String.t(), Ecto.Repo.t() | nil) ::
  GeoSQL.fragment()

Geometry Accessors

exterior_ring(geometry)

(macro)

is_polygon_clockwise(geometry)

(macro)

@spec is_polygon_clockwise(geometry :: GeoSQL.geometry_input()) :: GeoSQL.fragment()

is_polygon_counter_clockwise(geometry)

(macro)

@spec is_polygon_counter_clockwise(geometry :: GeoSQL.geometry_input()) ::
  GeoSQL.fragment()

number_of_dimensions(geometry)

(macro)

number_of_geometries(geometry_collection)

(macro)

number_of_points(geometry)

(macro)

number_of_rings(geometry)

(macro)

Geometry Constructors

collect(geometryList)

(macro)

collect(geometryA, geometryB)

(macro)

make_point(x, y, repo \\ nil)

(macro)

@spec make_point(
  x :: [GeoSQL.fragment()] | [number()],
  y :: [GeoSQL.fragment()] | [number()],
  Ecto.Repo.t() | nil
) :: GeoSQL.fragment()

make_point_m(x, y, z, repo \\ nil)

(macro)

@spec make_point_m(
  x :: [GeoSQL.fragment()] | [number()],
  y :: [GeoSQL.fragment()] | [number()],
  z :: [GeoSQL.fragment()] | [number()],
  Ecto.Repo.t() | nil
) :: GeoSQL.fragment()

make_point_z(x, y, z, repo \\ nil)

(macro)

@spec make_point_z(
  x :: [GeoSQL.fragment()] | [number()],
  y :: [GeoSQL.fragment()] | [number()],
  z :: [GeoSQL.fragment()] | [number()],
  Ecto.Repo.t() | nil
) :: GeoSQL.fragment()

make_point_zm(x, y, z, m, repo \\ nil)

(macro)

@spec make_point_zm(
  x :: [GeoSQL.fragment()] | [number()],
  y :: [GeoSQL.fragment()] | [number()],
  z :: [GeoSQL.fragment()] | [number()],
  m :: [GeoSQL.fragment()] | [number()],
  Ecto.Repo.t() | nil
) :: GeoSQL.fragment()

Geometry Editors

add_point(line, point, position \\ -1)

(macro)

@spec add_point(
  line :: GeoSQL.geometry_input(),
  point :: GeoSQL.geometry_input(),
  position :: integer()
) :: GeoSQL.fragment()

collection_extract(collection, type)

(macro)

@spec collection_extract(
  collection :: GeoSQL.geometry_input(),
  type :: :point | :line_string | :polygon
) :: GeoSQL.fragment()

multi(collection)

(macro)

@spec multi(geometry :: GeoSQL.geometry_input()) :: GeoSQL.fragment()

project(geometry, distance, azimuth)

(macro)

@spec project(
  geometry :: GeoSQL.geometry_input(),
  distance :: number(),
  azimuth :: number()
) ::
  GeoSQL.fragment()

remove_point(line, offset)

(macro)

@spec remove_point(line :: GeoSQL.geometry_input(), offset :: integer()) ::
  GeoSQL.fragment()

remove_repeated_points(geometry, tolerance \\ 0, repo \\ nil)

(macro)

@spec remove_repeated_points(
  GeoSQL.geometry_input(),
  tolerance :: number(),
  Ecto.Repo.t() | nil
) :: GeoSQL.fragment()

reverse(geometry)

(macro)

@spec reverse(geometry :: GeoSQL.geometry_input()) :: GeoSQL.fragment()

segmentize(geometry, max_segement_length)

(macro)

@spec segmentize(geometry :: GeoSQL.geometry_input(), max_segement_length :: number()) ::
  GeoSQL.fragment()

set_point(geometry, index, point)

(macro)

@spec set_point(
  geometry :: GeoSQL.geometry_input(),
  index :: integer(),
  point :: GeoSQL.geometry_input()
) :: GeoSQL.fragment()

snap(geometry, reference, precision)

(macro)

snap_to_grid(geometry, size)

(macro)

@spec snap_to_grid(GeoSQL.geometry_input(), size :: number()) :: GeoSQL.fragment()

snap_to_grid(geometry, size_x, size_y)

(macro)

@spec snap_to_grid(
  GeoSQL.geometry_input(),
  reference :: GeoSQL.geometry_input(),
  precision :: number()
) :: GeoSQL.fragment()

@spec snap_to_grid(GeoSQL.geometry_input(), size_x :: number(), size_y :: number()) ::
  GeoSQL.fragment()

snap_to_grid(geometry, origin_x, origin_y, size_x, size_y)

(macro)

@spec snap_to_grid(
  GeoSQL.geometry_input(),
  origin_x :: number(),
  origin_y :: number(),
  size_x :: number(),
  size_y :: number()
) :: GeoSQL.fragment()

snap_to_grid(geometry, point, size_x, size_y, size_z, size_m)

(macro)

@spec snap_to_grid(
  GeoSQL.geometry_input(),
  point :: GeoSQL.geometry_input(),
  size_x :: number(),
  size_y :: number(),
  size_z :: number(),
  size_m :: number()
) :: GeoSQL.fragment()

Geometry Mutations

flip_coordinates(geometry, repo \\ nil)

(macro)

@spec flip_coordinates(GeoSQL.geometry_input(), Ecto.Repo.t() | nil) ::
  GeoSQL.fragment()

shift_longitude(geometry, repo \\ nil)

(macro)

@spec shift_longitude(GeoSQL.geometry_input(), Ecto.Repo.t() | nil) ::
  GeoSQL.fragment()

Geometry Processing

build_area(geometry)

(macro)

concave_hull(geometry, precision \\ 1, allow_holes? \\ false)

(macro)

@spec concave_hull(
  GeoSQL.geometry_input(),
  precision :: number(),
  allow_holes? :: boolean()
) ::
  GeoSQL.fragment()

largest_empty_circle(geometry, tolerance \\ 0.0, repo \\ nil)

(macro)

@spec largest_empty_circle(
  GeoSQL.geometry_input(),
  tolerance :: number(),
  Ecto.Repo.t() | nil
) ::
  GeoSQL.fragment()

line_merge(geometry, directed? \\ false, repo \\ nil)

(macro)

@spec line_merge(GeoSQL.geometry_input(), directed? :: boolean(), Ecto.Repo.t() | nil) ::
  GeoSQL.fragment()

maximum_inscribed_circle(geometry, repo \\ nil)

(macro)

@spec maximum_inscribed_circle(GeoSQL.geometry_input(), Ecto.Repo.t() | nil) ::
  GeoSQL.fragment()

minimum_bounding_circle(geometry, repo \\ nil)

(macro)

@spec minimum_bounding_circle(GeoSQL.geometry_input(), Ecto.Repo.t() | nil) ::
  GeoSQL.fragment()

minimum_bounding_radius(geometry, repo \\ nil)

(macro)

@spec minimum_bounding_radius(GeoSQL.geometry_input(), Ecto.Repo.t() | nil) ::
  GeoSQL.fragment()

offset_curve(line, distance)

(macro)

oriented_envelope(geometry)

(macro)

polygonize(geometry)

(macro)

reduce_precision(geometry, grid_size)

(macro)

shared_paths(geometryA, geometryB)

(macro)

simplify(geometry, tolerance)

(macro)

simplify_preserve_topology(geometry, tolerance)

(macro)

triangulate_polygon(geometry, repo \\ nil)

(macro)

@spec triangulate_polygon(GeoSQL.geometry_input(), Ecto.Repo.t() | nil) ::
  GeoSQL.fragment()

Geometry Validation

is_valid_detail(geometry, esri_compat? \\ false)

(macro)

@spec is_valid_detail(geometry :: GeoSQL.geometry_input(), esri_compat? :: boolean()) ::
  GeoSQL.fragment()

is_valid_reason(geometry, esri_compat? \\ false)

(macro)

@spec is_valid_reason(geometry :: GeoSQL.geometry_input(), esri_compat? :: boolean()) ::
  GeoSQL.fragment()

make_valid(geometry)

(macro)

Linear Referencing

add_measure(line, measure_start, measure_end)

(macro)

@spec add_measure(
  line :: GeoSQL.geometry_input(),
  measure_start :: number(),
  measure_end :: number()
) :: GeoSQL.fragment()

interpolate_point(line, point)

(macro)

@spec interpolate_point(
  line :: GeoSQL.geometry_input(),
  point :: GeoSQL.geometry_input()
) :: GeoSQL.fragment()

line_interpolate_point(line, fraction, use_spheroid? \\ false, repo \\ nil)

(macro)

@spec line_interpolate_point(
  line :: GeoSQL.geometry_input(),
  fraction :: number(),
  use_spheroid? :: boolean(),
  Ecto.Repo.t() | nil
) :: GeoSQL.fragment()

Spatialite does not support spheroid calculations, and therefore use_spheroid? is ignored on that platform.

line_interpolate_points(line, fraction, use_spheroid? \\ true, repo \\ nil)

(macro)

@spec line_interpolate_points(
  line :: GeoSQL.geometry_input(),
  fraction :: number(),
  use_spheroid? :: boolean(),
  Ecto.Repo.t() | nil
) :: GeoSQL.fragment()

Note that Spatialite does not support spheroid calculations.

line_locate_point(line, point, use_spheroid? \\ false, repo \\ nil)

(macro)

@spec line_locate_point(
  line :: GeoSQL.geometry_input(),
  point :: GeoSQL.geometry_input(),
  use_spheroid? :: boolean(),
  Ecto.Repo.t() | nil
) :: GeoSQL.fragment()

Spatialite does not support spheroid calculations, and therefore use_spheroid? is ignored on that platform.

line_substring(line, start_fraction, end_fraction, repo \\ nil)

(macro)

@spec line_substring(
  line :: GeoSQL.geometry_input() | GeoSQL.fragment(),
  start_fraction :: number(),
  end_fraction :: number(),
  Ecto.Repo.t() | nil
) :: GeoSQL.fragment()

locate_along(geometry, measure)

(macro)

@spec locate_along(GeoSQL.geometry_input(), measure :: number()) :: GeoSQL.fragment()

locate_between(geometry, measure_start, measure_end)

(macro)

@spec locate_between(
  GeoSQL.geometry_input(),
  measure_start :: number(),
  measure_end :: number()
) ::
  GeoSQL.fragment()

Measurement

azimuth(originGeometry, targetGeometry)

(macro)

closest_point(geometryA, geometryB, use_spheroid? \\ false, repo \\ nil)

(macro)

@spec closest_point(
  GeoSQL.geometry_input(),
  GeoSQL.geometry_input(),
  use_spheroid? :: boolean(),
  Ecto.Repo.t()
) :: GeoSQL.fragment()

max_distance(geometryA, geometryB)

(macro)

minimum_clearance(geometry, repo \\ nil)

(macro)

minimum_clearance_line(geometry, repo \\ nil)

(macro)

shortest_line(geometryA, geometryB, use_spheroid? \\ false, repo \\ nil)

(macro)

@spec shortest_line(
  GeoSQL.geometry_input(),
  GeoSQL.geometry_input(),
  use_spheroid? :: boolean(),
  Ecto.Repo.t() | nil
) :: GeoSQL.fragment()

Overlays

node(geometry)

(macro)

split(inputGeometry, bladeGeometry)

(macro)

subdivide(geometry, max_vertices \\ 256)

(macro)

unary_union(geometry)

(macro)

Spatial Reference Systems

set_srid(geometry, srid, repo \\ nil)

(macro)

@spec set_srid(
  geometry :: GeoSQL.geometry_input(),
  srid :: pos_integer(),
  Ecto.Repo.t() | nil
) :: GeoSQL.fragment()

transform_pipeline(geometry, pipeline, srid, repo \\ nil)

(macro)

@spec transform_pipeline(
  GeoSQL.geometry_input(),
  pipeline :: String.t(),
  srid :: pos_integer(),
  Ecto.Repo.t() | nil
) :: GeoSQL.fragment()

Topology Relationships

relate_match(matrix, pattern)

(macro)

Well-Known Binary (WKB)

as_ewkb(geometry, repo \\ nil)

(macro)

@spec as_ewkb(GeoSQL.geometry_input(), Ecto.Repo.t() | nil) :: GeoSQL.fragment()

geom_from_ewkb(geometry, repo \\ nil)

(macro)

@spec geom_from_ewkb(GeoSQL.geometry_input(), Ecto.Repo.t() | nil) ::
  GeoSQL.fragment()

Well-Known Text (WKT)

as_ewkt(geometry, repo \\ nil)

(macro)

@spec as_ewkt(GeoSQL.geometry_input(), Ecto.Repo.t() | nil) :: GeoSQL.fragment()

bd_m_poly_from_text(wkt, srid)

(macro)

@spec bd_m_poly_from_text(
  String.t() | GeoSQL.geometry_input(),
  pos_integer() | GeoSQL.geometry_input()
) :: GeoSQL.fragment()

bd_poly_from_text(wkt, srid)

(macro)

@spec bd_poly_from_text(
  String.t() | GeoSQL.geometry_input(),
  pos_integer() | GeoSQL.geometry_input()
) :: GeoSQL.fragment()

geom_from_ewkt(geometry, repo \\ nil)

(macro)

@spec geom_from_ewkt(GeoSQL.geometry_input(), Ecto.Repo.t() | nil) ::
  GeoSQL.fragment()