spherely.to_geoarrow

Contents

spherely.to_geoarrow#

spherely.to_geoarrow(input: Geography | array_like, /, *, output_schema: object = None, projection: spherely.Projection = <spherely.Projection object at 0x7faf6fcc57b0>, planar: bool = False, tessellate_tolerance: float = 100.0, precision: int = 6) → spherely.ArrowArrayHolder#

Convert an array of geographies to an Arrow array object with a GeoArrow extension type.

See https://geoarrow.org/ for details on the GeoArrow specification.

Parameters:

  • input (array_like) – An array of geography objects.

  • output_schema (Arrow schema, pyarrow.DataType, pyarrow.Field, default None) – The geoarrow extension type to use for the output. This can indicate one of the native geoarrow types (e.g. “point”, “linestring”, “polygon”, etc) or the serialized WKT or WKB options. The type can be specified with any Arrow schema compatible object (any object implementing the Arrow PyCapsule Protocol for schemas, i.e. which has a __arrow_c_schema__ method). For example, this can be a pyarrow.DataType or pyarrow.Field, and you can use the geoarrow.pyarrow package to construct such geoarrow extension types.

  • projection (spherely.Projection, default Projection.lnglat()) – The projection to use when converting the geographies to the output encoding. By default, uses longitude/latitude coordinates (“plate carree” projection).

  • planar (bool, default False) – If set to True, the edges of linestrings and polygons in the output are assumed to be linear on the plane. In that case, additional points will be added to the line while converting to the output encoding, to ensure every point is within the tessellate_tolerance distance (100m by default) of the original line on the sphere.

  • tessellate_tolerance (float, default 100.0) – The maximum distance in meters that a point must be moved to satisfy the planar edge constraint. This is only used if planar is set to True.

  • precision (int, default 6) – The number of decimal places to include in the output. Only used when writing as WKT.

Returns:

ArrowArrayHolder – A generic Arrow array object with geograhies encoded to GeoArrow.

Examples

>>> import spherely
>>> import geoarrow.pyarrow as ga
>>> arr = spherely.to_geoarrow(arr, output_schema=ga.point())

The returned object is a generic Arrow-compatible object that then can be consumed by your Arrow library of choice. For example, using pyarrow:

>>> import pyarrow as pa
>>> arr_pa = pa.array(arr)
Contents