Skip to content
Louis-Gm/phytospatial

Layer

Vector

A wrapper class around a GeoPandas GeoDataFrame to represent vector spatial data with additional properties and methods.

Attributes:

Name Type Description
data GeoDataFrame

The underlying GeoDataFrame containing the spatial data.
Properties

crs: The Coordinate Reference System of the geometries in the GeoDataFrame. bounds: The bounding box of all geometries in the GeoDataFrame as (minx, miny, maxx, maxy). columns: The list of column names in the GeoDataFrame. spatial_index (rt.RTree): A dynamically generated, zero-copy Rust spatial index containing the geometry bounds.

Source code in src/phytospatial/vector/layer.py 
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
class Vector:
    """
    A wrapper class around a GeoPandas GeoDataFrame to represent vector spatial data with additional properties and methods.

    Attributes:
        data (gpd.GeoDataFrame): The underlying GeoDataFrame containing the spatial data.

    Properties:
        crs: The Coordinate Reference System of the geometries in the GeoDataFrame.
        bounds: The bounding box of all geometries in the GeoDataFrame as (minx, miny, maxx, maxy).
        columns: The list of column names in the GeoDataFrame.
        spatial_index (rt.RTree): A dynamically generated, zero-copy Rust spatial index containing the geometry bounds.
    """
    def __init__(self, data: gpd.GeoDataFrame):
        """
        Initializes the Vector layer and allocates internal caching structures.

        Args:
            data (gpd.GeoDataFrame): The structural geometry payload.

        Raises:
            TypeError: If the provided data is not a valid GeoDataFrame.
        """
        if not isinstance(data, gpd.GeoDataFrame):
            raise TypeError(f"Expected GeoDataFrame, got {type(data)}")
        self._data = data
        self._spatial_index: Optional[rt.RTree] = None

    @property
    def data(self) -> gpd.GeoDataFrame:
        """
        Retrieves the underlying geometry dataframe.

        Returns:
            gpd.GeoDataFrame: The primary spatial data structure.
        """
        return self._data

    @data.setter
    def data(self, value: gpd.GeoDataFrame):
        """
        Replaces the underlying geometry dataframe and invalidates any cached spatial indices.

        Args:
            value (gpd.GeoDataFrame): The new spatial data structure.

        Raises:
            TypeError: If the provided data is not a valid GeoDataFrame.
        """
        if not isinstance(value, gpd.GeoDataFrame):
            raise TypeError(f"Expected GeoDataFrame, got {type(value)}")
        self._data = value
        self._spatial_index = None

    @property
    def crs(self):
        """
        Retrieves the Coordinate Reference System mapping for the geometries.

        Returns:
            The CRS definition inherent to the GeoDataFrame.
        """
        return self._data.crs

    @property
    def bounds(self):
        """
        Calculates the absolute maximum spatial extents encompassing all active geometries.

        Returns:
            tuple: A strictly ordered bounding box defined as (minx, miny, maxx, maxy).
        """
        return self._data.total_bounds

    @property
    def columns(self):
        """
        Extracts the schema attributes currently associated with the geometries.

        Returns:
            list: The string identifiers corresponding to available feature columns.
        """
        return self._data.columns.tolist()

    @property
    def spatial_index(self) -> rt.RTree:
        """
        Accesses or constructs a heavily optimized C-level spatial RTree for the active geometries.

        Returns:
            rt.RTree: An immutable, binary-stable RTree index.
        """
        if self._spatial_index is None:
            bounds_df = pl.from_pandas(self._data.bounds)
            num_items = len(bounds_df)

            rt_builder = rt.RTreeBuilder(num_items)
            rt_builder.add(
                bounds_df["minx"].to_arrow(),
                bounds_df["miny"].to_arrow(),
                bounds_df["maxx"].to_arrow(),
                bounds_df["maxy"].to_arrow()
            )
            self._spatial_index = rt_builder.finish(method="str")

        return self._spatial_index

    def query_bounds(
            self, 
            minx: float, 
            miny: float, 
            maxx: float, 
            maxy: float
            ) -> np.ndarray:
        """
        Executes an accelerated broad-phase intersection search against the spatial index.

        Args:
            minx (float): The absolute minimum longitudinal constraint.
            miny (float): The absolute minimum latitudinal constraint.
            maxx (float): The absolute maximum longitudinal constraint.
            maxy (float): The absolute maximum latitudinal constraint.

        Returns:
            np.ndarray: A contiguous array of integer indices identifying geometries whose 
                        bounding boxes overlap with the specified spatial constraints.
        """
        return rt.search(self.spatial_index, minx, miny, maxx, maxy).to_numpy()

    def __len__(self) -> int:
        """
        Computes the total count of spatial features currently managed by the Vector.

        Returns:
            int: The scalar count of geometries.
        """
        return len(self._data)

    def __repr__(self):
        """
        Generates a deterministic string representation of the Vector state.

        Returns:
            str: A formatted descriptor establishing feature length and coordinate reference.
        """
        return f"<Vector features={len(self._data)} crs={self.crs}>"

bounds property

Calculates the absolute maximum spatial extents encompassing all active geometries.

Returns:

Name Type Description
tuple

A strictly ordered bounding box defined as (minx, miny, maxx, maxy).

columns property

Extracts the schema attributes currently associated with the geometries.

Returns:

Name Type Description
list

The string identifiers corresponding to available feature columns.

crs property

Retrieves the Coordinate Reference System mapping for the geometries.

Returns:

Type Description

The CRS definition inherent to the GeoDataFrame.

data property writable

Retrieves the underlying geometry dataframe.

Returns:

Type Description
GeoDataFrame

gpd.GeoDataFrame: The primary spatial data structure.

spatial_index property

Accesses or constructs a heavily optimized C-level spatial RTree for the active geometries.

Returns:

Type Description
RTree

rt.RTree: An immutable, binary-stable RTree index.

__init__(data)

Initializes the Vector layer and allocates internal caching structures.

Parameters:

Name Type Description Default
data GeoDataFrame

The structural geometry payload.

 required

Raises:

Type Description
TypeError

If the provided data is not a valid GeoDataFrame.
Source code in src/phytospatial/vector/layer.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
def __init__(self, data: gpd.GeoDataFrame):
    """
    Initializes the Vector layer and allocates internal caching structures.

    Args:
        data (gpd.GeoDataFrame): The structural geometry payload.

    Raises:
        TypeError: If the provided data is not a valid GeoDataFrame.
    """
    if not isinstance(data, gpd.GeoDataFrame):
        raise TypeError(f"Expected GeoDataFrame, got {type(data)}")
    self._data = data
    self._spatial_index: Optional[rt.RTree] = None

__len__()

Computes the total count of spatial features currently managed by the Vector.

Returns:

Name Type Description
int int

The scalar count of geometries.
Source code in src/phytospatial/vector/layer.py 
144
145
146
147
148
149
150
151
def __len__(self) -> int:
    """
    Computes the total count of spatial features currently managed by the Vector.

    Returns:
        int: The scalar count of geometries.
    """
    return len(self._data)

__repr__()

Generates a deterministic string representation of the Vector state.

Returns:

Name Type Description
str

A formatted descriptor establishing feature length and coordinate reference.
Source code in src/phytospatial/vector/layer.py 
153
154
155
156
157
158
159
160
def __repr__(self):
    """
    Generates a deterministic string representation of the Vector state.

    Returns:
        str: A formatted descriptor establishing feature length and coordinate reference.
    """
    return f"<Vector features={len(self._data)} crs={self.crs}>"

query_bounds(minx, miny, maxx, maxy)

Executes an accelerated broad-phase intersection search against the spatial index.

Parameters:

Name Type Description Default
minx float

The absolute minimum longitudinal constraint.

 required
miny float

The absolute minimum latitudinal constraint.

 required
maxx float

The absolute maximum longitudinal constraint.

 required
maxy float

The absolute maximum latitudinal constraint.

 required

Returns:

Type Description
ndarray

np.ndarray: A contiguous array of integer indices identifying geometries whose bounding boxes overlap with the specified spatial constraints.
Source code in src/phytospatial/vector/layer.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def query_bounds(
        self, 
        minx: float, 
        miny: float, 
        maxx: float, 
        maxy: float
        ) -> np.ndarray:
    """
    Executes an accelerated broad-phase intersection search against the spatial index.

    Args:
        minx (float): The absolute minimum longitudinal constraint.
        miny (float): The absolute minimum latitudinal constraint.
        maxx (float): The absolute maximum longitudinal constraint.
        maxy (float): The absolute maximum latitudinal constraint.

    Returns:
        np.ndarray: A contiguous array of integer indices identifying geometries whose 
                    bounding boxes overlap with the specified spatial constraints.
    """
    return rt.search(self.spatial_index, minx, miny, maxx, maxy).to_numpy()