geospatial Queries#

Geospatial Query in FanInSAR is used to retrieve or sample values from GeoDataset. Query includes:

Query Type	Description
`Points`	A collection of points, can be used to sample multiple pixel values from GeoDataset.
`BoundingBox`	A bounding box, can be used to sample rectangular region values from GeoDataset.
`Polygons`	A collection of polygons, can be used to sample multiple pixel values from GeoDataset.
`GeoQuery`	A combination of `Points`, `BoundingBox`, and `Polygons`. It is highly recommended if you want to sample values using multiple query types simultaneously from a GeoDataset.

Points query#

class faninsar.query.Points(points: ~typing.Sequence[float | ~typing.Sequence[float]], crs: ~typing.Any = None, dtype: ~numpy.dtype = <class 'numpy.float32'>)#

Bases: object

A class to represent a collection of points.

Examples

>>> pts = Points([[1, 2], [2, 3], [3, 4]])
>>> pt = pts[1]

set difference of two Points:

>>> pts - pt
Points:
    x    y
0  1.0  2.0
1  3.0  4.0
[count=2, crs='None']

set union of two Points:

>>> pts + Points([1,5])
Points:
    x    y
0  1.0  2.0
1  2.0  3.0
2  3.0  4.0
3  1.0  5.0
[count=4, crs='None']

in operator:

>>> pts[1] in pts
True

>>> Points([1, 5]) in pts
False

convert to numpy array using np.array:

>>> np.array(pts, dtype=np.int16)
array([[1, 2],
        [2, 3],
        [3, 4]], dtype=int16)

extract x and y coordinates:

>>> pts.x
array([1., 2., 3.], dtype=float32)
>>> pts.y
array([2., 3., 4.], dtype=float32)

extract values:

>>> pts.values
array([[1., 2.],
        [2., 3.],
        [3., 4.]], dtype=float32)

convert to GeoDataFrame:

>>> pts.to_GeoDataFrame()
    x       y       geometry
0   1.0     2.0     POINT (1.00000 2.00000)
1   2.0     3.0     POINT (2.00000 3.00000)
2   3.0     4.0     POINT (3.00000 4.00000)

__init__(points: ~typing.Sequence[float | ~typing.Sequence[float]], crs: ~typing.Any = None, dtype: ~numpy.dtype = <class 'numpy.float32'>) → None#

Initialize a Points object.

Parameters:

points (Sequence[float | Sequence[float]]) – The points to be sampled. The shape of the points can be (2) or (n, 2) where n is the number of points. The first column is the x coordinate and the second column is the y coordinate. if the shape is (2), the points will be reshaped to (1, 2).
crs (Any, optional, default: None) – The coordinate reference system of the points. Can be any object that can be passed to pyproj.crs.CRS.from_user_input().
dtype (np.dtype, optional) – The data type of the points. Default is np.float32.

Raises:

ValueError – If the shape of the points is not (n, 2).

property x: ndarray#: Return the x coordinates of the points.

property y: ndarray#: Return the y coordinates of the points.

property values: ndarray#: Return the values of the points with shape (n, 2) where n is the number of points.

property dtype: dtype#: Return the data type of the points.

property crs: CRS | None#: Return the coordinate reference system of the points.

set_crs(crs: Any) → None#: Set the coordinate reference system of the points.

Warning

This method will only set the crs attribute without converting the points to a new coordinate reference system. If you want to convert the points values to a new coordinate, please use to_crs()

to_crs(crs: Any) → Points#

Convert the points values to a new coordinate reference system.

Parameters:: crs (Any) – The new coordinate reference system. Can be any object that can be passed to pyproj.crs.CRS.from_user_input().
Returns:: The points in the new coordinate reference system.
Return type:: Points

classmethod from_GeoDataFrame(gdf: GeoDataFrame, x_field: str = 'auto', y_field: str = 'auto') → Points#

initialize a Points object from a GeoDataFrame.

Parameters:

gdf (gpd.GeoDataFrame) – The GeoDataFrame to be parsed.
x_field/y_field (str, optional, default: "auto") –
The field name of the x/y coordinates if geometry not exists. If auto, will try to find the field name automatically from following fields (case insensitive):
- x: x, xs, lon, longitude, long, longs, longitudes
- y: y, ys, lat, latitude, lats, latitudes

Returns:

The Points object.

Return type:

Points

classmethod from_shapefile(filename: str | Path, x_field: str = 'auto', y_field: str = 'auto', **kwargs) → Points#

initialize a Points object from a file.

Parameters:

filename (str | Path) – The path to the shapefile. file type can be any type that can be passed to geopandas.read_file().
x_field/y_field (str, optional, default: "auto") –
The field name of the x/y coordinates. If “auto”, will try to find the field name automatically from following fields (case insensitive):
- x : x, xs, lon, longitude
- y : y, ys, lat, latitude
**kwargs (dict) – Other parameters passed to geopandas.read_file().

Returns:

The Points object.

Return type:

Points

classmethod from_csv(filename: str | Path, x_field: str = 'auto', y_field: str = 'auto', crs: Any = None, **kwargs) → Points#

initialize a Points object from a csv/txt file.

Parameters:

filename (str | Path) – The path to the csv/txt file.
x_field/y_field (str, optional, default: "auto") –
The field name of the x/y coordinates. If “auto”, will try to find the field name automatically from following fields (case insensitive):
- x : x, xs, lon, longitude
- y : y, ys, lat, latitude
crs (Any, optional, default: None) – The coordinate reference system of the points. Can be any object that can be passed to pyproj.crs.CRS.from_user_input().
**kwargs (dict) – Other parameters passed to pandas.read_csv().

Returns:

The Points object.

Return type:

Points

to_DataFrame() → DataFrame#

Convert the Points to a DataFrame.

Returns:: The DataFrame with columns x and y.
Return type:: pd.DataFrame

to_GeoDataFrame() → GeoDataFrame#

Convert the Points to a GeoDataFrame.

Returns:: The GeoDataFrame.
Return type:: gpd.GeoDataFrame

to_shapefile(filename: str | Path, **kwargs) → None#

Save the Points to a shapefile.

Parameters:

filename (str | Path) – The path to the shapefile.
**kwargs (dict) – Other parameters passed to geopandas.GeoDataFrame.to_file().

Bounding Box query#

class faninsar.query.BoundingBox(left: float, bottom: float, right: float, top: float, crs: CRS | str | None = None)#

Bases: object

a class used for indexing datasets using a spatial bounding box.

Note

This class is a modified version of the BoundingBox class from the torchgeo package. The main modifications include:

Removal of date bounds
Change of the bounding box to (left, bottom, right, top), which aligns with the rasterio.coords.BoundingBox class.
Addition of the CRS attribute to automatically convert the bounding box to the CRS of the dataset.

__init__(left: float, bottom: float, right: float, top: float, crs: CRS | str | None = None) → None#

Initialize a BoundingBox.

Parameters:

left (float) – The western boundary.
bottom (float) – The southern boundary.
right (float) – The eastern boundary.
top (float) – The northern boundary.
crs (CRS | str | None, optional) – The coordinate reference system of the bounding box. Can be any object that can be passed to pyproj.crs.CRS.from_user_input(). Default is None.

property area: float#

Area of bounding box.

Area is defined as spatial area.

Returns:: area

to_crs(crs: CRS | str) → BoundingBox#

Convert the bounding box to a new coordinate reference system.

Parameters:: crs (CRS | str) – The new coordinate reference system. Can be any object that can be passed to pyproj.crs.CRS.from_user_input().

set_crs(crs: CRS | str) → None#

Set the coordinate reference system of the bounding box.

Parameters:

crs (CRS | str) –

The new coordinate reference system. Can be any object that can be passed to pyproj.crs.CRS.from_user_input().

Warning

This method will only set the crs attribute without converting the bounding box to a new coordinate reference system. If you want to convert the bounding box values to a new coordinate, please use to_crs()

to_dict() → dict[str, float]#

Convert the bounding box to a dictionary.

Returns:: dictionary with keys ‘left’, ‘bottom’, ‘right’, ‘top’

to_GeoDataFrame() → GeoDataFrame#

Convert the bounding box to a GeoDataFrame.

Returns:: GeoDataFrame with the bounding box as a polygon

intersects(other: BoundingBox) → bool#

Whether or not two bounding boxes intersect.

Parameters:: other – another bounding box
Returns:: True if bounding boxes intersect, else False

split(proportion: float, horizontal: bool = True) → tuple[BoundingBox, BoundingBox]#

Split BoundingBox in two.

Parameters:

proportion – split proportion in range (0,1)
horizontal – whether the split is horizontal or vertical

Returns:

A tuple with the resulting BoundingBoxes

Polygons query#

class faninsar.query.Polygons(gdf: GeoDataFrame | GeoSeries, types: Literal['desired', 'undesired'] | Sequence[Literal['desired', 'undesired']] = 'desired', crs: Any = None, all_touched=True, pad: bool = False)#

Bases: object

Polygons object is used to store the regions that need to be retrieved (“desired”) or removed (“undesired”) from a dataset.

Tip

When a mixed-types Polygons, where both “desired” and “undesired” polygons, are provided:

the “undesired” polygons will only be useful when there are overlapping regions with the “desired” polygons. Otherwise, the “desired” polygons are enough.
you can use to_desired() to get the desired polygons from a mixed-types Polygons object.

__init__(gdf: GeoDataFrame | GeoSeries, types: Literal['desired', 'undesired'] | Sequence[Literal['desired', 'undesired']] = 'desired', crs: Any = None, all_touched=True, pad: bool = False) → None#

Initialize a Polygons object.

Parameters:

gdf (GeoDataFrame | GeoSeries) – The GeoDataFrame or GeoSeries containing the “desired” or “undesired” regions/polygons.
types ('desired' | 'undesired' | Sequence['desired', 'undesired']) – The types of polygons. If ‘desired’, the polygons are the desired regions. If ‘undesired’, the polygons are the regions to be removed. Default is ‘desired’.
crs (Any, optional) – The CRS of the polygons. Can be any object that can be passed to pyproj.crs.CRS.from_user_input() . If None, the CRS of the input geometry will be used. Default is None.
all_touched (bool, optional) – Whether to include all pixels touched by the polygon. Default is True.
pad (bool, optional) – If True, the features will be padded in each direction by one half of a pixel prior to cropping raster. Defaults to False.

property all_touched: bool#: whether to include all pixels touched by the polygon.

property pad: bool#: whether to pad the features in each direction by one half of a pixel prior to cropping raster.

property geometry: GeoSeries#: the geometry column of the polygons.

property types: Series#: the types of polygons.

property frame: GeoDataFrame#: GeoDataFrame format of polygons.

property desired: Polygons#: desired part of polygons.

property undesired: Polygons#: undesired part of polygons.

property is_mixed: bool#: whether the polygons contain both desired and undesired polygons.

to_desired() → Polygons#: Return a desired polygons, with the regions of undesired polygons being removed.

Warning

This method should only be used when the Polygons object contains both “desired” and “undesired” polygons. If the Polygons object only contains “undesired” polygons, the returned Polygons object will be empty.

to_bbox() → list[BoundingBox]#: Return a list of BoundingBox objects representing the bounding boxes of the polygons.

Warning

This method will only return the bounding boxes of the desired polygons. If the Polygons object only contains “undesired” polygons, the returned list will be empty.

to_GeoDataFrame() → GeoDataFrame#: Return a GeoDataFrame of the polygons. This method is an alias of frame for API consistency with Points and BoundingBox.

property crs: CRS#: the CRS of the polygons.

to_crs(crs: Any) → Polygons#

Return a new Polygons object with new CRS.

Parameters:: crs (Any) – The new CRS. Can be any object that can be passed to pyproj.crs.CRS.from_user_input().
Returns:: The new Polygons object.
Return type:: Polygons

set_crs(crs: Any, allow_override: bool = False) → None#

Set the CRS of polygons.

Warning

This method will only set the crs attribute without converting the geometries to a new coordinate reference system. If you want to convert the geometries to a new coordinate, please use to_crs()

Parameters:

crs (Any) – The new CRS. Can be any object that can be passed to pyproj.crs.CRS.from_user_input().
allow_override (bool, optional) – Whether to allow overriding the existing CRS. If False, a CRSError will be raised if the CRS has already been set. Default is False.

Raises:

CRSError – If the CRS has already been set and allow_override is False.

classmethod from_file(filename: str | Path, types: Literal['desired', 'undesired'] | Sequence[Literal['desired', 'undesired']] = 'desired', crs: Any = None, **kwargs) → Polygons#

initialize a Polygon object from a shapefile.

Parameters:

filename (str | Path) – The path to the shapefile. file type can be any type that can be passed to geopandas.read_file().
types ('desired' | 'undesired' | Sequence['desired', 'undesired'], optional) – The types of polygons. If ‘desired’, the polygons are the desired polygons. If ‘undesired’, the polygons are the polygons to be removed. Default is ‘desired’.
crs (Any, optional) – The CRS of the polygons. Can be any object that can be passed to pyproj.crs.CRS.from_user_input(). If None, the CRS of the input geometries will be used. Default is None.
**kwargs (dict) – Other parameters passed to geopandas.read_file().

Returns:

The Polygons object.

Return type:

Polygons

copy() → Polygons#: Return a copy of the Polygons object.

plot(**kwargs) → Axes#

Plot the polygons on a map.

Parameters:: **kwargs (dict) – Other parameters passed to geopandas.GeoDataFrame.plot().
Returns:: The matplotlib axes.
Return type:: Axes

GeoQuery#

class faninsar.query.GeoQuery(points: Points | None = None, boxes: BoundingBox | list[BoundingBox] | None = None, polygons: Polygons | None = None)#

Bases: object

A combined query of the Points, BoundingBox, and Polygons queries. This class is used to sample data from a GeoDataset using multiple points, bounding boxes, and polygons at the same time.

__init__(points: Points | None = None, boxes: BoundingBox | list[BoundingBox] | None = None, polygons: Polygons | None = None) → None#

Initialize a GeoQuery instance.

Parameters:

points (Points | None, optional) – The Points instance used to retrieve point values from the dataset. Default is None.
boxes (BoundingBox | list[BoundingBox] | None, optional) – The BoundingBox or a list of BoundingBox instances used to retrieve bounding box values from the dataset. Default is None.
polygons (Polygons | None, optional) – The Polygons instance used to retrieve polygon values from the dataset. Default is None.

Raises:

ValueError: – If neither points, boxes, nor polygons are provided.
TypeError: – If points is not a Points instance, boxes is not a BoundingBox or a list of BoundingBox instances, or polygons is not a Polygons instance.

property points: Points | None#: Return the points of the samples.

property boxes: list[BoundingBox] | None#: Return the bounding boxes of the samples.

property polygons: Points | None#: Return the polygons of the samples.

geospatial Queries#

Points query#

Bounding Box query#

Polygons query#

GeoQuery#

This Page