Geom

This module provides geometric operations and spatial analysis functions for vector data.

filter_vector(vector, condition, inplace=False)

Filters the geometries in the Vector based on a boolean condition.

Parameters:

Name	Type	Description	Default
vector	Vector	The input Vector object containing geometries to be filtered.	required
condition	Union[Series, Callable]	A boolean Series or a callable function that returns a boolean Series for filtering.	required
inplace	bool	If True, modifies the input Vector in place. If False, returns a new Vector with filtered geometries. Defaults to False.	False

Returns:

Name	Type	Description
Vector	Vector	A Vector object with geometries filtered based on the condition. If inplace is True, returns the modified input Vector.

Source code in src/phytospatial/vector/geom.py

def filter_vector(
        vector: Vector, 
        condition: Union[pd.Series, Callable], 
        inplace: bool = False
        ) -> Vector:
    """
    Filters the geometries in the Vector based on a boolean condition.

    Args:
        vector (Vector): The input Vector object containing geometries to be filtered.
        condition (Union[pd.Series, Callable]): A boolean Series or a callable function that returns a boolean Series for filtering.
        inplace (bool): If True, modifies the input Vector in place. 
                        If False, returns a new Vector with filtered geometries. Defaults to False.

    Returns:
        Vector: A Vector object with geometries filtered based on the condition. If inplace is True, returns the modified input Vector.
    """                    
    mask = condition(vector.data) if callable(condition) else condition
    filtered_gdf = vector.data[mask]

    if inplace:
        vector.data = filtered_gdf
        return vector
    return Vector(filtered_gdf.copy())

force_Z(vector, dimensionality=2, inplace=False)

Alters the geometric dimensionality of the spatial data by either stripping or appending a Z-axis.

Parameters:

Name	Type	Description	Default
vector	Vector	The input Vector object containing the geometries to transform.	required
dimensionality	int	The target number of spatial dimensions. Must be strictly 2 or 3. Defaults to 2.	2
inplace	bool	If True, applies the dimensionality transformation directly to the underlying GeoDataFrame of the input Vector. If False, generates and returns a new Vector instance. Defaults to False.	False

Returns:

Name	Type	Description
Vector	Vector	A Vector object ensuring all geometries conform to the requested dimensionality.

Raises:

Type	Description
ValueError	If the provided dimensionality argument is not exactly 2 or 3.

Source code in src/phytospatial/vector/geom.py

def force_Z(
    vector: Vector,
    dimensionality: int = 2,
    inplace: bool = False
    ) -> Vector:
    """
    Alters the geometric dimensionality of the spatial data by either stripping or appending a Z-axis.

    Args:
        vector (Vector): The input Vector object containing the geometries to transform.
        dimensionality (int): The target number of spatial dimensions. Must be strictly 2 or 3. Defaults to 2.
        inplace (bool): If True, applies the dimensionality transformation directly to the underlying 
            GeoDataFrame of the input Vector. If False, generates and returns a new Vector instance. 
            Defaults to False.

    Returns:
        Vector: A Vector object ensuring all geometries conform to the requested dimensionality.

    Raises:
        ValueError: If the provided dimensionality argument is not exactly 2 or 3.
    """
    if dimensionality not in (2, 3):
        raise ValueError(f"Dimensionality must be strictly 2 or 3. Received: {dimensionality}")

    gdf = vector.data if inplace else vector.data.copy()

    if dimensionality == 2 and gdf.geometry.has_z.any():
        gdf.geometry = gpd.GeoSeries.from_wkb(gdf.geometry.to_wkb(output_dimension=2))
    elif dimensionality == 3 and not gdf.geometry.has_z.all():
        gdf.geometry = gpd.GeoSeries.from_wkb(gdf.geometry.to_wkb(output_dimension=3))

    if inplace:
        vector.data = gdf
        return vector

    return Vector(gdf)

select_columns(vector, columns, inplace=False)

Selects a subset of columns from the Vector's GeoDataFrame, ensuring that the geometry column is retained.

Parameters:

Name	Type	Description	Default
vector	Vector	The input Vector object containing the GeoDataFrame.	required
columns	list	A list of column names to select.	required
inplace	bool	If True, modifies the input Vector in place. If False, returns a new Vector with the selected columns. Defaults to False.	False

Returns:

Name	Type	Description
Vector	Vector	A Vector object with the selected columns. If inplace is True, returns the modified input Vector.

Source code in src/phytospatial/vector/geom.py

def select_columns(
        vector: Vector, 
        columns: list, 
        inplace: bool = False
        ) -> Vector:
    """
    Selects a subset of columns from the Vector's GeoDataFrame, ensuring that the geometry column is retained.

    Args:
        vector (Vector): The input Vector object containing the GeoDataFrame.
        columns (list): A list of column names to select.
        inplace (bool): If True, modifies the input Vector in place. 
                        If False, returns a new Vector with the selected columns. Defaults to False.

    Returns:
        Vector: A Vector object with the selected columns. If inplace is True, returns the modified input Vector.
    """
    if 'geometry' not in columns:
        columns = columns + ['geometry']

    selected_gdf = vector.data[columns]

    if inplace:
        vector.data = selected_gdf
        return vector
    return Vector(selected_gdf.copy())

to_crs(vector, target_crs, inplace=False)

Reprojects the geometries in the Vector to a specified target Coordinate Reference System (CRS).

Parameters:

Name	Type	Description	Default
vector	Vector	The input Vector object containing geometries to be reprojected.	required
target_crs	Union[str, int, dict]	The target CRS to which the geometries will be reprojected.	required
inplace	bool	If True, modifies the input Vector in place. If False, returns a new Vector with reprojected geometries. Defaults to False.	False

Returns:

Name	Type	Description
Vector	Vector	A Vector object with geometries reprojected to the target CRS. If inplace is True, returns the modified input Vector.

Source code in src/phytospatial/vector/geom.py

def to_crs(
        vector: Vector, 
        target_crs: Union[str, int, dict],
        inplace: bool = False
        ) -> Vector:
    """
    Reprojects the geometries in the Vector to a specified target Coordinate Reference System (CRS).

    Args:
        vector (Vector): The input Vector object containing geometries to be reprojected.
        target_crs (Union[str, int, dict]): The target CRS to which the geometries will be reprojected.
        inplace (bool): If True, modifies the input Vector in place. 
                        If False, returns a new Vector with reprojected geometries. Defaults to False.

    Returns:
        Vector: A Vector object with geometries reprojected to the target CRS. If inplace is True, returns the modified input Vector.
    """
    if vector.crs is None:
        raise ValueError("Vector has no CRS. Cannot reproject.")

    new_gdf = vector.data.to_crs(target_crs)

    if inplace:
        vector.data = new_gdf
        return vector
    return Vector(new_gdf)

validate(vector, fix_invalid=True, drop_invalid=True, inplace=False)

Validates the geometries in the Vector, optionally fixing or dropping invalid geometries.

Parameters:

Name	Type	Description	Default
vector	Vector	The input Vector object containing geometries to be validated.	required
fix_invalid	bool	If True, attempts to fix invalid geometries using a zero-width buffer. Defaults to True.	True
drop_invalid	bool	If True, drops geometries that remain invalid after the fix attempt. Defaults to True.	True
inplace	bool	If True, modifies the input Vector in place. If False, returns a new Vector with validated geometries. Defaults to False	False

Returns:

Name	Type	Description
Vector	Vector	A Vector object with validated geometries. If inplace is True, returns the modified input Vector.

Source code in src/phytospatial/vector/geom.py

def validate(
        vector: Vector, 
        fix_invalid: bool = True, 
        drop_invalid: bool = True, 
        inplace: bool = False
        ) -> Vector:
    """
    Validates the geometries in the Vector, optionally fixing or dropping invalid geometries.

    Args:
        vector (Vector): The input Vector object containing geometries to be validated.
        fix_invalid (bool): If True, attempts to fix invalid geometries using a zero-width buffer. Defaults to True.
        drop_invalid (bool): If True, drops geometries that remain invalid after the fix attempt. Defaults to True.
        inplace (bool): If True, modifies the input Vector in place. 
                        If False, returns a new Vector with validated geometries. Defaults to False

    Returns:
        Vector: A Vector object with validated geometries. If inplace is True, returns the modified input Vector.
    """                    
    gdf = vector.data if inplace else vector.data.copy()
    invalid_mask = ~gdf.is_valid

    if not invalid_mask.any():
        return vector if inplace else Vector(gdf)

    if fix_invalid:
        gdf.loc[invalid_mask, 'geometry'] = gdf.loc[invalid_mask, 'geometry'].buffer(0)
        still_invalid = ~gdf.is_valid

        if still_invalid.any() and drop_invalid:
            gdf = gdf[gdf.is_valid]
    elif drop_invalid:
        gdf = gdf[gdf.is_valid]

    if inplace:
        vector.data = gdf
        return vector
    return Vector(gdf)