griffine 0.1.0__tar.gz

griffine-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: "Continuous integration"
+
+concurrency:
+  group: ${{ github.ref }}
+  cancel-in-progress: false
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  ci:
+    name: Continuous integration
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Sync
+        run: uv sync
+      - name: Pre-Commit Hooks
+        run: uv run pre-commit run --all-files
+      - name: Test
+        run: uv run pytest
+      - name: "Upload coverage to Codecov"
+        uses: codecov/codecov-action@v4
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+        with:
+          fail_ci_if_error: false
+          verbose: true

griffine-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Build and release
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  release:
+    types:
+      - published
+
+jobs:
+  build-package:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/griffine
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Create virtual environment
+        run: uv venv
+      - name: Install build
+        run: uv pip install build
+      - name: Build
+        run: .venv/bin/python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        if: startsWith(github.ref, 'refs/tags')

griffine-0.1.0/.gitignore

@@ -0,0 +1,127 @@
+__version__.py
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Environments
+.env
+.env.*
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/

griffine-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,50 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff_check
+        name: ruff check
+        entry: ruff check --force-exclude
+        language: python
+        'types_or': [python, pyi]
+        args: [--fix, --exit-non-zero-on-fix]
+        require_serial: true
+      - id: ruff_format
+        name: ruff format
+        entry: ruff format --force-exclude
+        language: python
+        'types_or': [python, pyi]
+        args: []
+        require_serial: true
+      - id: check-added-large-files
+        name: Check for added large files
+        entry: check-added-large-files
+        language: system
+      - id: check-toml
+        name: Check Toml
+        entry: check-toml
+        language: system
+        types: [toml]
+      - id: check-yaml
+        name: Check Yaml
+        entry: check-yaml
+        language: system
+        types: [yaml]
+      - id: end-of-file-fixer
+        name: Fix End of Files
+        entry: end-of-file-fixer
+        language: system
+        types: [text]
+        stages: [pre-commit, pre-push, manual]
+      - id: trailing-whitespace
+        name: Trim Trailing Whitespace
+        entry: trailing-whitespace-fixer
+        language: system
+        types: [text]
+        stages: [pre-commit, pre-push, manual]
+      - id: mypy
+        name: mypy
+        entry: mypy
+        language: python
+        'types_or': [python, pyi]
+        args: []
+        require_serial: true

griffine-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## [0.0.1] - 2025-04-24
+
+Initial release 🎉
+
+[unreleased]: https://github.com/jkeifer/griffine/compare/v0.1.0...HEAD
+[0.0.1]: https://github.com/jkeifer/griffine/releases/tag/v0.1.0

griffine-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jarrett Keifer
+
+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.

griffine-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: griffine
+Version: 0.1.0
+Summary: Utilities for working with raster grids defined by affine transforms
+Project-URL: Repository, https://github.com/jkeifer/griffine
+Author-email: Jarrett Keifer <jkeifer0@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: affine>=2.4.0
+Requires-Dist: pygeoif>=1.5.1
+Description-Content-Type: text/markdown
+
+# griffine
+
+[![build-status-image]][build-status]
+[![coverage-status-image]][codecov]
+[![pypi-version]][pypi]
+
+<img src="./images/logo.svg" width=300>
+
+Utilities for working with *gri*ds that have a*ffine* transforms, typically for
+working with rasters or other gridded data.
+
+## Installation
+
+This package is distributed on pypi and can be `pip`-installed:
+
+```commandline
+pip install griffine
+```
+
+## Usage
+
+This library is composed of several major classes:
+
+* `Grid`
+* `TiledGrid`
+* `AffineGrid`
+* `TiledAffineGrid`
+* `Point`
+* `Cell` and `AffineCell`
+* `Tile` and `AffineTile`
+
+`Grid` represents a two-dimensional grid of `Cell`s, with a size defined by its
+`cols` and `rows`. A `TiledGrid` is, effectively, a grid of grids. Each cell in
+a `TiledGrid` is a `Tile`. `Tiles` are both `Cell`s and `Grid`s, where the tile
+grid is a subset of the larger `Grid` that has been tiled.
+
+`AffineGrid` is a `Grid` with the addition of an affine transformation to allow
+transformations between grid/image space and model space (in the case of
+geospatial data, model space would be the raster's coordinate reference
+system). `AffineGrids` allow looking up the `Point` represented by a `Cell`
+(using its origin, centroid, or antiorigin), or the `Cell` containing a
+`Point`.
+
+A `TiledAffineGrid` is to an `AffineGrid` as a `TiledGrid` is to a `Grid`: each
+`AffileTile` in a `TiledAffineGrid` is an `AffineGrid` representing some subset
+of the larger `AffineGrid` that was tiled. `TiledAffineGrids` allow finding the
+`AffineTile` containing` a `Cell` or a `Point`.
+
+`griffine` does not handle coordinate systems and thus does not do any
+reprojection. It is expected that users ensure they are using a consistent CRS
+between the affine transforms of their grid and any points.
+
+The [Python `__geo_interface__`
+protocol](https://gist.github.com/sgillies/2217756) is supported by all
+operations accepting a `Point` and on the `Point` class itself, to easily allow
+using or casting to point geometries from other Python libraries (`shapely`,
+`odc-geo`, etc.).
+affine_grid = grid.add_transform(transform)affine_cell.antiorigin
+### Examples
+
+```python
+# Affine re-exported from the affine package
+# Point is re-exported from the pygeoif package
+from griffine import Affine, Grid, Point
+
+# 10m pixel grid in UTM coordinates
+transform = Affine(10, 0, 200000, 0, -10, 5100000)
+
+# First we create a grid!
+grid = Grid(10000, 5000)
+
+# We can grab a cell from the grid using index notation.
+cell = grid[424, 2343]
+cell.row  # 424
+cell.col  # 2343
+
+# We can tile the grid using another grid.
+# In this example we'd get a 10x5 tile grid
+# where each tile is a grid of 1000x1000.
+tile = grid.tile_into(Grid(10, 5))[0, 0]
+tile.size  # (1000, 1000)
+
+# We can also add an affine transform to our grid.
+# A transform allows converting between grid space and
+# model space (i.e., cell coords and spatial coords).
+affine_grid = grid.add_transform(transform)
+affine_grid.origin      # Point(200000.0, 5100000.0)
+affine_grid.centroid    # Point(225000.0, 5050000.0)
+affine_grid.antiorigin  # Point(250000.0, 5000000.0)
+
+# Affine grids also support grabbing a cell via
+# index notation. Affine grids will provide affine
+# cells, which support transform-based operations too.
+affine_cell = affine_grid[0, 0]
+affine_cell.origin      # Point(200000.0, 5100000.0)
+affine_cell.centroid    # Point(200005.0, 5099995.0)
+affine_cell.antiorigin  # Point(200010.0, 5099990.0)
+
+# Transform operations can go the other way too.
+# Let's make a point and find its enclosing cell!
+point = Point(223433.2934, 5095752.8931)
+affine_cell = affine_grid.point_to_cell(point)
+affine_cell.row  # 424
+affine_cell.col  # 2343
+
+# Grids can also be tiled via a tile size expressed
+# as a grid. Here we'll get a 10x5 tile grid, but the
+# left and bottom edge tiles will not be full size.
+tiled_affine_grid = affine_grid.tile_via(Grid(1024, 1024))
+
+# Affine-enabled tiles and tile grids also support
+# transform-based operations:
+affine_tile = tiled_affine_grid.point_to_tile(point)
+affine_tile.row  # 0
+affine_tile.col  # 2
+affine_tile_cell = affine_tile.point_to_cell(point)
+affine_tile_cell.row  # 424
+affine_tile_cell.col  # 2343
+affine_tile_cell.tile_row  # 0
+affine_tile_cell.tile_col  # 2
+
+# We can work our way back up to the original grid
+# from cells and tiles as needed:
+#
+#     cell          tile      tile grid    grid
+affine_tile_cell.parent_grid.parent_grid.base_grid is affine_grid  # True
+```
+
+## How to say "griffine"
+
+The name of this library is pronounced "grif-fine", as in the words "grift",
+and "fine". It's also okay to say it "grif-feen", as rhymes with "mean".
+
+[build-status-image]: https://github.com/jkeifer/griffine/actions/workflows/ci.yml/badge.svg
+[build-status]: https://github.com/jkeifer/griffine/actions/workflows/ci.yml
+[coverage-status-image]: https://img.shields.io/codecov/c/github/jkeifer/griffine/main.svg
+[codecov]: https://codecov.io/github/jkeifer/griffine?branch=main
+[pypi-version]: https://img.shields.io/pypi/v/griffine.svg
+[pypi]: https://pypi.org/project/griffine/

griffine-0.1.0/README.md

@@ -0,0 +1,139 @@
+# griffine
+
+[![build-status-image]][build-status]
+[![coverage-status-image]][codecov]
+[![pypi-version]][pypi]
+
+<img src="./images/logo.svg" width=300>
+
+Utilities for working with *gri*ds that have a*ffine* transforms, typically for
+working with rasters or other gridded data.
+
+## Installation
+
+This package is distributed on pypi and can be `pip`-installed:
+
+```commandline
+pip install griffine
+```
+
+## Usage
+
+This library is composed of several major classes:
+
+* `Grid`
+* `TiledGrid`
+* `AffineGrid`
+* `TiledAffineGrid`
+* `Point`
+* `Cell` and `AffineCell`
+* `Tile` and `AffineTile`
+
+`Grid` represents a two-dimensional grid of `Cell`s, with a size defined by its
+`cols` and `rows`. A `TiledGrid` is, effectively, a grid of grids. Each cell in
+a `TiledGrid` is a `Tile`. `Tiles` are both `Cell`s and `Grid`s, where the tile
+grid is a subset of the larger `Grid` that has been tiled.
+
+`AffineGrid` is a `Grid` with the addition of an affine transformation to allow
+transformations between grid/image space and model space (in the case of
+geospatial data, model space would be the raster's coordinate reference
+system). `AffineGrids` allow looking up the `Point` represented by a `Cell`
+(using its origin, centroid, or antiorigin), or the `Cell` containing a
+`Point`.
+
+A `TiledAffineGrid` is to an `AffineGrid` as a `TiledGrid` is to a `Grid`: each
+`AffileTile` in a `TiledAffineGrid` is an `AffineGrid` representing some subset
+of the larger `AffineGrid` that was tiled. `TiledAffineGrids` allow finding the
+`AffineTile` containing` a `Cell` or a `Point`.
+
+`griffine` does not handle coordinate systems and thus does not do any
+reprojection. It is expected that users ensure they are using a consistent CRS
+between the affine transforms of their grid and any points.
+
+The [Python `__geo_interface__`
+protocol](https://gist.github.com/sgillies/2217756) is supported by all
+operations accepting a `Point` and on the `Point` class itself, to easily allow
+using or casting to point geometries from other Python libraries (`shapely`,
+`odc-geo`, etc.).
+affine_grid = grid.add_transform(transform)affine_cell.antiorigin
+### Examples
+
+```python
+# Affine re-exported from the affine package
+# Point is re-exported from the pygeoif package
+from griffine import Affine, Grid, Point
+
+# 10m pixel grid in UTM coordinates
+transform = Affine(10, 0, 200000, 0, -10, 5100000)
+
+# First we create a grid!
+grid = Grid(10000, 5000)
+
+# We can grab a cell from the grid using index notation.
+cell = grid[424, 2343]
+cell.row  # 424
+cell.col  # 2343
+
+# We can tile the grid using another grid.
+# In this example we'd get a 10x5 tile grid
+# where each tile is a grid of 1000x1000.
+tile = grid.tile_into(Grid(10, 5))[0, 0]
+tile.size  # (1000, 1000)
+
+# We can also add an affine transform to our grid.
+# A transform allows converting between grid space and
+# model space (i.e., cell coords and spatial coords).
+affine_grid = grid.add_transform(transform)
+affine_grid.origin      # Point(200000.0, 5100000.0)
+affine_grid.centroid    # Point(225000.0, 5050000.0)
+affine_grid.antiorigin  # Point(250000.0, 5000000.0)
+
+# Affine grids also support grabbing a cell via
+# index notation. Affine grids will provide affine
+# cells, which support transform-based operations too.
+affine_cell = affine_grid[0, 0]
+affine_cell.origin      # Point(200000.0, 5100000.0)
+affine_cell.centroid    # Point(200005.0, 5099995.0)
+affine_cell.antiorigin  # Point(200010.0, 5099990.0)
+
+# Transform operations can go the other way too.
+# Let's make a point and find its enclosing cell!
+point = Point(223433.2934, 5095752.8931)
+affine_cell = affine_grid.point_to_cell(point)
+affine_cell.row  # 424
+affine_cell.col  # 2343
+
+# Grids can also be tiled via a tile size expressed
+# as a grid. Here we'll get a 10x5 tile grid, but the
+# left and bottom edge tiles will not be full size.
+tiled_affine_grid = affine_grid.tile_via(Grid(1024, 1024))
+
+# Affine-enabled tiles and tile grids also support
+# transform-based operations:
+affine_tile = tiled_affine_grid.point_to_tile(point)
+affine_tile.row  # 0
+affine_tile.col  # 2
+affine_tile_cell = affine_tile.point_to_cell(point)
+affine_tile_cell.row  # 424
+affine_tile_cell.col  # 2343
+affine_tile_cell.tile_row  # 0
+affine_tile_cell.tile_col  # 2
+
+# We can work our way back up to the original grid
+# from cells and tiles as needed:
+#
+#     cell          tile      tile grid    grid
+affine_tile_cell.parent_grid.parent_grid.base_grid is affine_grid  # True
+```
+
+## How to say "griffine"
+
+The name of this library is pronounced "grif-fine", as in the words "grift",
+and "fine". It's also okay to say it "grif-feen", as rhymes with "mean".
+
+[build-status-image]: https://github.com/jkeifer/griffine/actions/workflows/ci.yml/badge.svg
+[build-status]: https://github.com/jkeifer/griffine/actions/workflows/ci.yml
+[coverage-status-image]: https://img.shields.io/codecov/c/github/jkeifer/griffine/main.svg
+[codecov]: https://codecov.io/github/jkeifer/griffine?branch=main
+[pypi-version]: https://img.shields.io/pypi/v/griffine.svg
+[pypi]: https://pypi.org/project/griffine/