Expressions and functions¶
Expressions take the form of parenthesized lists that may contain other expressions. The first item in a list is the name of a function or method, or an expression that evaluates to a function. The second item is the function's first argument or the object to which the method is bound. The remaining list items are the positional and keyword arguments for the named function or method. The list of functions and callables available in an expression includes:
- Python operators such as
+
,/
, and<=
- Python builtins such as
dict
,list
, andmap
- All public functions from itertools, e.g.
islice
, andrepeat
- All functions importable from Shapely 2.0, e.g.
Point
, andunary_union
- All methods of Shapely geometry classes
- Functions specific to fio-planet
Expressions are evaluated by fio_planet.features.snuggs.eval()
. Let's look at
some examples using that function.
Note
The outer parentheses are not optional within snuggs.eval()
.
Note
snuggs.eval()
does not use Python's builtin eval()
but isn't intended
to be a secure computing environment. Expressions which access the
computer's filesystem and create new processes are possible.
Builtin Python functions¶
bool
:
>>> snuggs.eval('(bool 0)')
False
range
:
>>> snuggs.eval('(range 1 4)')
range(1, 4)
list
:
>>> snuggs.eval('(list (range 1 4))')
[1, 2, 3]
Values can be bound to names for use in expressions.
>>> snuggs.eval('(list (range start stop))', start=0, stop=5)
[0, 1, 2, 3, 4]
Itertools functions¶
Here's an example of using itertools.repeat()
.
>>> snuggs.eval('(list (repeat "*" times))', times=6)
['*', '*', '*', '*', '*', '*']
Shapely functions¶
Here's an expression that evaluates to a Shapely Point instance.
>>> snuggs.eval('(Point 0 0)')
<POINT (0 0)>
The expression below evaluates to a MultiPoint instance.
>>> snuggs.eval('(union (Point 0 0) (Point 1 1))')
<MULTIPOINT (0 0, 1 1)>
Functions specific to fio-planet¶
The fio-planet package introduces four new functions not available in Python's
standard library, Fiona, or Shapely: collect
, dump
, identity
, and
vertex_count
.
The collect
function turns a list of geometries into a geometry collection
and dump
does the inverse, turning a geometry collection into a sequence of
geometries.
>>> snuggs.eval('(collect (Point 0 0) (Point 1 1))')
<GEOMETRYCOLLECTION (POINT (0 0), POINT (1 1))>
>>> snuggs.eval('(list (dump (collect (Point 0 0) (Point 1 1))))')
[<POINT (0 0)>, <POINT (1 1)>]
The identity
function returns its single argument.
>>> snuggs.eval('(identity 42)')
42
To count the number of vertices in a geometry, use vertex_count
.
>>> snuggs.eval('(vertex_count (Point 0 0))')
1
The area
, buffer
, distance
, length
, simplify
, and set_precision
functions shadow, or override, functions from the shapely module. They
automatically reproject geometry objects from their natural coordinate
reference system (CRS) of OGC:CRS84
to EPSG:6933
so that the shapes can be
measured or modified using meters as units.
buffer
dilates (or erodes) a given geometry, with coordinates in decimal
longitude and latitude degrees, by a given distance in meters.
>>> snuggs.eval('(buffer (Point 0 0) :distance 100)')
<POLYGON ((0.001 0, 0.001 0, 0.001 0, 0.001 0, 0.001 -0.001, 0.001 -0.001, 0...>
The area
and length
of this polygon have units of square meter and meter.
>>> snuggs.eval('(area (buffer (Point 0 0) :distance 100))')
31214.451487413342
>>> snuggs.eval('(length (buffer (Point 0 0) :distance 100))')
627.3096977558143
The distance
between two geometries is in meters.
>>> snuggs.eval('(distance (Point 0 0) (Point 0.1 0.1))')
15995.164946207413
A geometry can be simplified to a tolerance value in meters using simplify
.
There are more examples of this function under
topics:simplification.
>>> snuggs.eval('(simplify (buffer (Point 0 0) :distance 100) :tolerance 100)')
<POLYGON ((0.001 0, 0 -0.001, -0.001 0, 0 0.001, 0.001 0))>
The set_precision
function snaps a geometry to a fixed precision grid with a
size in meters.
>>> snuggs.eval('(set_precision (Point 0.001 0.001) :grid_size 500)')
<POINT (0 0)>
Feature and geometry context for expressions¶
fio-filter
and fio-map
evaluate expressions in the context of a GeoJSON
feature and its geometry attribute. These are named f
and g
. For example,
here is an expression that tests whether the input feature is within 62.5
kilometers of the given point.
< (distance g (Point 4 43)) 62.5E3
fio-reduce
evaluates expressions in the context of the sequence of all input
geometries, named c
. For example, this expression dissolves input
geometries using Shapely's unary_union
.
unary_union c