geotypes 0.1.0__tar.gz

geotypes-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jackson Shields
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

geotypes-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: geotypes
+Version: 0.1.0
+Summary: A set of useful utilities for working with geospatial data. Makes it simpler to do common operations.
+Author-email: Jackson Shields <jacksonhshields@gmail.com>
+Maintainer-email: Jackson Shields <jacksonhshields@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/jacksonhshields/geotypes
+Project-URL: Documentation, https://jacksonhshields.github.io/geotypes/
+Project-URL: Repository, https://github.com/jacksonhshields/geotypes.git
+Project-URL: Issues, https://github.com/jacksonhshields/geotypes/issues
+Keywords: geospatial,gis,geopandas,rasterio,shapely,coordinates,utm,navigation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: geopandas
+Requires-Dist: affine
+Requires-Dist: rasterio
+Requires-Dist: pymap3d
+Requires-Dist: utm
+Requires-Dist: geopy
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Dynamic: license-file
+
+# geotypes
+
+geotypes is a python package for making it easy to work with geospatial data, particularly useful for geospatial planning and analysis. It wraps GeoPandas and rasterio with simple data types to make it easier and more pythonic to work with for some applications.
+
+Visit the [documentation](https://jacksonhshields.github.io/geotypes/) for installation, getting started, tutorials and API reference.
+
+
+
+Geotypes adds some high-level wrappers around geopandas and shapely to allow for easier use. They allow easy conversion between georeference schemes, better tracking of what coordinate system the variables are in and easy conversion between types.
+These include:
+
+* GeoPoint
+* LL
+* GeoPath
+* GeoPoints
+* GeoArea
+* XY
+* LocalPath
+* LocalPoints
+* LocalArea
+* Raster
+
+
+
+## Installation
+Use pip to install geotypes. 
+
+GDAL is not added to the requirements. If you already have libgdal-dev installed, you can use:
+```
+gdalversion=$(gdalinfo --version | cut -d\  -f2 | sed s'#,##') && pip3 install GDAL==$gdalversion
+```
+
+
+
+With GDAL installed or not, you can install geotypes with:
+```bash
+pip install git@github.com:jacksonhshields/geotypes.git
+
+```
+
+
+## Tutorials
+
+To get started with geotypes, check out the tutorials, which run you through the data types and how to use them.
+
+
+## Basic Usage
+
+### GeoPoint
+The GeoPoint is an x,y coordinate with an associated Coordinate Reference System (CRS). It allows easy conversion to LL and XY data types.
+
+```
+p = geotypes.geometry.GeoPoint(x=151.28826000, y=-33.79798000, crs="epsg:4326") # initialise a lat, lon centred in Manly.
+print("GeoPoint", p)
+ll = p.to_ll() # Converts to lat,lon data type
+print("In LL", ll)
+p_utm = p.to_crs("EPSG:32756")  # converts to utm zone 56S
+print("In UTM Zone 56S", p_utm)
+```
+
+### LL
+
+## LL
+The lat,lon data type is there for convience and to make it explicit about what is latitude, what is longitude.
+```
+ll = geotypes.geometry.LL(-33.79798000,151.28826000)
+print(ll)
+# Convert to geopoint
+p = ll.to_geopoint()
+print(p)
+```
+
+
+### GeoPath
+A path in geographic space, effectively a geopandas geoseries / shapely linestring with an associated CRS. It is commonly used to represent sampling transects (such as AUV transects). It has some convient functions to collect samples at set distances along the path - which can be done no-matter what coordinate system the path is in.
+```
+# Define a set of points. This is a simple broad grid in CRS "EPSG:32756"
+points = [(342041.99358729343, 6259392.849573873),
+ (342495.27623430215, 6259603.771833958),
+ (342579.64503957686, 6259422.458960008),
+ (342126.36269032373, 6259211.536449324),
+ (342210.73189359176, 6259030.223443877),
+ (342664.01394509675, 6259241.146205157)]
+
+# create the geopath object
+geopath = geotypes.geometry.GeoPath(points, crs="EPSG:32756")
+print(geopath)
+
+# Iterating over it returns a geopoint.
+print("Geopoints:")
+for p in geopath:
+    print(p)
+print("\n")
+
+# Easily convert to other crs
+geopath4326 = geopath.to_crs("EPSG:4326")
+print(geopath4326)
+
+# Sample points along the geopath
+geopath_subsampled = geopath.sample_points_along_path(d=20) # sample a point every 20 meters.
+print("Number of points in original {}, in subsampled {}".format(len(geopath), len(geopath_subsampled)))
+```
+
+
+### GeoArea
+
+A GeoArea is a wrapper around a geopandas GeoSeries with just one element, a polygon or multipolygon. They are used within the situ framework to represent sampling bounds or focal areas. As such, they have easy access to random sampling.
+
+```
+# Define a geoarea
+geoarea = geotypes.geometry.GeoArea([(151.28412747953516, -33.78781691040293),
+ (151.30572252046485, -33.78781691040293),
+ (151.30572478467255, -33.805848131225765),
+ (151.28412521532746, -33.805848131225765),
+ (151.28412747953516, -33.78781691040293)], crs='EPSG:4326')
+
+# get some samples from within it - these are GeoPoints:
+for n in range(5):
+    print(geoarea.random_point_geo())
+# you can get also get points directly as LLs, regardless of the CRS.
+for n in range(5):
+    print(geoarea.random_point_ll())
+```
+
+### Local Equivalents
+There are local equivalents to the classes presented above. These include:
+- XY: Equivalent of GeoPoint
+- LocalPoints: Equivalent of GeoPoints
+- LocalPath: Equivalent of GeoPath
+- LocalArea: Equivalent of GeoArea
+These are just wrappers around the shapely geometry classes, but offer some extra functionality, including being able to convert to and from the Geo equivalents.
+
+```
+origin_ll = geoarea.centroid_ll()
+# Convert the position to local
+xy = p.to_local(origin_ll)
+# Now go back to GeoPoint, this time with a different CRS.
+pll = xy.to_geo(origin_ll, "epsg:4326")
+# Print all to compare
+print(p, xy, pll)
+
+
+# Convert a GeoPath to a LocalPath
+localpath = geopath.to_local(origin_ll)
+# And go back again
+geopath2 = localpath.to_geo(origin_ll, geopath.crs)
+```
+
+### Rasters
+
+There is an abstraction of rasterio Rasters to make it easier to work with rasters. You can use the Raster.get_value function with any geotypes geometry object to get the value or values at that point.
+
+```
+from geotypes.rasters import Raster
+r = Raster('manly_uw.tif')
+ll = LL(-33.79931, 151.29412)
+from geotypes.geometry import LL
+ll = LL(-33.79931, 151.29412)
+r.get_value(ll)
+>>> -7.871370315551758
+```

geotypes-0.1.0/README.md

@@ -0,0 +1,161 @@
+# geotypes
+
+geotypes is a python package for making it easy to work with geospatial data, particularly useful for geospatial planning and analysis. It wraps GeoPandas and rasterio with simple data types to make it easier and more pythonic to work with for some applications.
+
+Visit the [documentation](https://jacksonhshields.github.io/geotypes/) for installation, getting started, tutorials and API reference.
+
+
+
+Geotypes adds some high-level wrappers around geopandas and shapely to allow for easier use. They allow easy conversion between georeference schemes, better tracking of what coordinate system the variables are in and easy conversion between types.
+These include:
+
+* GeoPoint
+* LL
+* GeoPath
+* GeoPoints
+* GeoArea
+* XY
+* LocalPath
+* LocalPoints
+* LocalArea
+* Raster
+
+
+
+## Installation
+Use pip to install geotypes. 
+
+GDAL is not added to the requirements. If you already have libgdal-dev installed, you can use:
+```
+gdalversion=$(gdalinfo --version | cut -d\  -f2 | sed s'#,##') && pip3 install GDAL==$gdalversion
+```
+
+
+
+With GDAL installed or not, you can install geotypes with:
+```bash
+pip install git@github.com:jacksonhshields/geotypes.git
+
+```
+
+
+## Tutorials
+
+To get started with geotypes, check out the tutorials, which run you through the data types and how to use them.
+
+
+## Basic Usage
+
+### GeoPoint
+The GeoPoint is an x,y coordinate with an associated Coordinate Reference System (CRS). It allows easy conversion to LL and XY data types.
+
+```
+p = geotypes.geometry.GeoPoint(x=151.28826000, y=-33.79798000, crs="epsg:4326") # initialise a lat, lon centred in Manly.
+print("GeoPoint", p)
+ll = p.to_ll() # Converts to lat,lon data type
+print("In LL", ll)
+p_utm = p.to_crs("EPSG:32756")  # converts to utm zone 56S
+print("In UTM Zone 56S", p_utm)
+```
+
+### LL
+
+## LL
+The lat,lon data type is there for convience and to make it explicit about what is latitude, what is longitude.
+```
+ll = geotypes.geometry.LL(-33.79798000,151.28826000)
+print(ll)
+# Convert to geopoint
+p = ll.to_geopoint()
+print(p)
+```
+
+
+### GeoPath
+A path in geographic space, effectively a geopandas geoseries / shapely linestring with an associated CRS. It is commonly used to represent sampling transects (such as AUV transects). It has some convient functions to collect samples at set distances along the path - which can be done no-matter what coordinate system the path is in.
+```
+# Define a set of points. This is a simple broad grid in CRS "EPSG:32756"
+points = [(342041.99358729343, 6259392.849573873),
+ (342495.27623430215, 6259603.771833958),
+ (342579.64503957686, 6259422.458960008),
+ (342126.36269032373, 6259211.536449324),
+ (342210.73189359176, 6259030.223443877),
+ (342664.01394509675, 6259241.146205157)]
+
+# create the geopath object
+geopath = geotypes.geometry.GeoPath(points, crs="EPSG:32756")
+print(geopath)
+
+# Iterating over it returns a geopoint.
+print("Geopoints:")
+for p in geopath:
+    print(p)
+print("\n")
+
+# Easily convert to other crs
+geopath4326 = geopath.to_crs("EPSG:4326")
+print(geopath4326)
+
+# Sample points along the geopath
+geopath_subsampled = geopath.sample_points_along_path(d=20) # sample a point every 20 meters.
+print("Number of points in original {}, in subsampled {}".format(len(geopath), len(geopath_subsampled)))
+```
+
+
+### GeoArea
+
+A GeoArea is a wrapper around a geopandas GeoSeries with just one element, a polygon or multipolygon. They are used within the situ framework to represent sampling bounds or focal areas. As such, they have easy access to random sampling.
+
+```
+# Define a geoarea
+geoarea = geotypes.geometry.GeoArea([(151.28412747953516, -33.78781691040293),
+ (151.30572252046485, -33.78781691040293),
+ (151.30572478467255, -33.805848131225765),
+ (151.28412521532746, -33.805848131225765),
+ (151.28412747953516, -33.78781691040293)], crs='EPSG:4326')
+
+# get some samples from within it - these are GeoPoints:
+for n in range(5):
+    print(geoarea.random_point_geo())
+# you can get also get points directly as LLs, regardless of the CRS.
+for n in range(5):
+    print(geoarea.random_point_ll())
+```
+
+### Local Equivalents
+There are local equivalents to the classes presented above. These include:
+- XY: Equivalent of GeoPoint
+- LocalPoints: Equivalent of GeoPoints
+- LocalPath: Equivalent of GeoPath
+- LocalArea: Equivalent of GeoArea
+These are just wrappers around the shapely geometry classes, but offer some extra functionality, including being able to convert to and from the Geo equivalents.
+
+```
+origin_ll = geoarea.centroid_ll()
+# Convert the position to local
+xy = p.to_local(origin_ll)
+# Now go back to GeoPoint, this time with a different CRS.
+pll = xy.to_geo(origin_ll, "epsg:4326")
+# Print all to compare
+print(p, xy, pll)
+
+
+# Convert a GeoPath to a LocalPath
+localpath = geopath.to_local(origin_ll)
+# And go back again
+geopath2 = localpath.to_geo(origin_ll, geopath.crs)
+```
+
+### Rasters
+
+There is an abstraction of rasterio Rasters to make it easier to work with rasters. You can use the Raster.get_value function with any geotypes geometry object to get the value or values at that point.
+
+```
+from geotypes.rasters import Raster
+r = Raster('manly_uw.tif')
+ll = LL(-33.79931, 151.29412)
+from geotypes.geometry import LL
+ll = LL(-33.79931, 151.29412)
+r.get_value(ll)
+>>> -7.871370315551758
+```

geotypes-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "geotypes"
+version = "0.1.0"
+description = "A set of useful utilities for working with geospatial data. Makes it simpler to do common operations."
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "Jackson Shields", email = "jacksonhshields@gmail.com"}
+]
+maintainers = [
+    {name = "Jackson Shields", email = "jacksonhshields@gmail.com"}
+]
+keywords = ["geospatial", "gis", "geopandas", "rasterio", "shapely", "coordinates", "utm", "navigation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: GIS",
+]
+requires-python = ">=3.8"
+dependencies = [
+    "pandas",
+    "numpy",
+    "matplotlib",
+    "geopandas",
+    "affine",
+    "rasterio",
+    "pymap3d",
+    "utm",
+    "geopy",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "black",
+    "isort",
+    "flake8",
+]
+docs = [
+    "sphinx",
+    "sphinx-rtd-theme",
+]
+
+[project.urls]
+Homepage = "https://github.com/jacksonhshields/geotypes"
+Documentation = "https://jacksonhshields.github.io/geotypes/"
+Repository = "https://github.com/jacksonhshields/geotypes.git"
+Issues = "https://github.com/jacksonhshields/geotypes/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.black]
+line-length = 100
+target-version = ["py38", "py39", "py310", "py311", "py312"]
+
+[tool.isort]
+profile = "black"
+line_length = 100

geotypes-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

geotypes-0.1.0/src/geotypes/__init__.py

@@ -0,0 +1,43 @@
+import warnings
+
+# Import modules
+from . import geometry
+
+# Export main geometry classes for convenient access
+from .geometry import (
+    GeoType,
+    LL,
+    XY,
+    GeoPoint,
+    GeoPath,
+    GeoPoints,
+    GeoArea,
+    LocalPath,
+    LocalPoints,
+    LocalArea,
+)
+
+# Try to import optional raster/feature modules
+try:
+    from . import rasters
+    from . import features
+    from .rasters import Raster
+except ImportError as e:
+    warnings.warn(f"geotypes raster capability not loaded. Error: {e}")
+
+__all__ = [
+    "geometry",
+    "rasters",
+    "features",
+    "GeoType",
+    "LL",
+    "XY",
+    "GeoPoint",
+    "GeoPath",
+    "GeoPoints",
+    "GeoArea",
+    "LocalPath",
+    "LocalPoints",
+    "LocalArea",
+    "Raster",
+]

geotypes-0.1.0/src/geotypes/features.py

@@ -0,0 +1,164 @@
+import numpy as np
+import warnings
+from .geometry import LL, GeoPoint, GeoPoints, GeoPath, check_crs_equal
+from .rasters import Raster, RasterRegistry
+from typing import Union, Iterable, Optional
+from multiprocessing import Pool, cpu_count
+
+class FeatureExtractorBase:
+    def get_output_format(self):
+        """
+        Returns the output format of the feature vector, where the length corresponds to the length of the feature vector.
+        i.e. if the feature vector contains [depth,slope,aspect,rugosity] this function would return ["depth","slope","aspect","rugosity"]
+
+
+        Returns:
+            [str]: maps index to feature vector item.
+        """
+        raise NotImplementedError()
+
+    def get_z(self, p: Union[LL, GeoPoint]):
+        """
+        Gets the features at a given lat/lon
+
+        Args:
+            p: (LL,GeoPoint) Lat/lon or GeoPoint
+
+        Returns:
+            np.ndarray: Features at the given location.
+        """
+        raise NotImplementedError()
+
+    def get_zs(self, ps: GeoPoints) -> np.ndarray:
+        """
+        Gets the features at a given set of lat/lon points
+
+        Args:
+            ps: (GeoPoints) The set of points
+
+        Returns:
+            np.ndarray: The features at the given location.
+        """
+        raise NotImplementedError()
+
+    def check_valid(self, samples: Union[GeoPoint, LL, GeoPoints, GeoPath]):
+        """
+        Checks if a sample set is valid.
+
+        Args:
+            samples: (GeoPoint, LL, GeoPoints, GeoPath) The samples to check.
+
+        Returns:
+            bool: True if the samples are valid, False otherwise.
+        """
+        raise NotImplementedError()
+
+    def get_named_zs(self, p: Union[LL, GeoPoint]):
+        """
+        Gets the features at a given lat/lon
+
+        Args:
+            p: (LL,GeoPoint) Lat/lon or GeoPoint
+
+        Returns:
+            dict: Features at the given location.
+        """
+        raise NotImplementedError()
+
+class FeaturesFromRaster:
+    """
+    Gathers raw features from a raster.
+    """
+    def __init__(self, raster_registry: RasterRegistry):
+        self.raster_registry = raster_registry
+
+    def get_output_format(self):
+        """
+        Returns the output format of the feature vector, where the length corresponds to the length of the feature vector.
+        i.e. if the feature vector contains [depth,slope,aspect,rugosity] this function would return ["depth","slope","aspect","rugosity"]
+        Returns:
+            [str]: maps index to feature vector item.
+        """
+        return list(self.raster_registry.keys())
+
+    def get_z(self, p: Union[LL, GeoPoint]):
+        """
+        Gets the features at a given lat/lon
+
+        Args:
+            p: (LL,GeoPoint) Lat/lon or GeoPoint
+
+        Returns:
+            np.ndarray: Features at the given location.
+        """
+
+        # Checks for either LL or GeoPoint
+        if isinstance(p, LL):
+            use_ll = True
+        elif isinstance(p, GeoPoint):
+            use_ll = False
+        else:
+            raise ValueError("p must be LL or GeoPoint")
+
+        feats = []
+        data_ok = True
+        # iterate over the rasters and get the values
+        for rname,ritem in self.raster_registry.items():
+            if use_ll:
+                v = ritem.dataset.get_value_at_ll(p, band=ritem.band)  # check if the value is valid
+            else:
+                v = ritem.dataset.get_value_at_geo(p, band=ritem.band)
+                # v = ritem.dataset.get_value(p)
+
+            if v is None: # if not, then we can't use this point
+                data_ok = False
+                break
+            feats.append(v)
+        if not data_ok: # if we couldn't get the data, then return None
+            return None
+
+        feat_arr = np.array(feats)
+        # feat_arr = np.concatenate(feats, axis=-1) # concatenate the features
+        feat_arr = feat_arr.squeeze() # squeeze the features
+        return feat_arr # return the features
+
+
+    def get_zs(self, ps: GeoPoints) -> np.ndarray:
+        """
+        Gets the features at a given set of lat/lon points
+
+        Args:
+            ps: (GeoPoints) The set of points
+
+        Returns:
+            np.ndarray: The features at the given location.
+        """
+        features = []
+        for rname, ritem in self.raster_registry.items():
+            if check_crs_equal(ritem.dataset.dataset.crs, ps.crs):
+                ps_crs = ps
+            else:
+                ps_crs = ps.to_crs(ritem.dataset.dataset.crs)
+
+            features.append(np.array(ritem.dataset.get_value(ps_crs)).squeeze())
+
+        if len(features) == 0:
+            return None
+        return np.asarray(features).T
+
+    def check_valid(self, samples: Union[GeoPoint, LL, GeoPoints, GeoPath]):
+        """
+        Checks if a sample set is valid.
+
+        Args:
+            samples: (GeoPoint, LL, GeoPoints, GeoPath) The samples to check.
+
+        Returns:
+            bool: True if the samples are valid, False otherwise.
+        """
+        if isinstance(samples, (GeoPoint, LL)):
+            samples = [samples]
+        for p in samples:
+            if self.get_z(p) is None:
+                return False
+        return True