# Geosquare Grid
Geosquare Grid is a Python library that provides methods for converting between geographic coordinates (longitude and latitude) and grid identifiers (GIDs). It also includes functionality for spatial operations and geometry handling, making it a useful tool for geospatial analysis and mapping applications.
## Features
- Convert longitude/latitude to GID and vice versa.
- Retrieve bounds for grid cells.
- Get geometries for grid cells.
- Find all grid cells that overlap with specified geometries.
- Easy integration with QGIS for geospatial applications.
## Installation
You can install the Geosquare Grid library using pip:
```bash
pip install geosquare-grid
```
## Usage
Here is a simple example of how to use the Geosquare Grid library:
```python
from geosquare_grid import GeosquareGrid
# Initialize the GeosquareGrid object
grid = GeosquareGrid()
# Convert longitude and latitude to GID
gid = grid.lonlat_to_gid(longitude=106.8938638928753022, latitude=-6.2608983083383016, level=5)
print(f"GID: {gid}")
# Convert GID back to longitude and latitude
longitude, latitude = grid.gid_to_lonlat(gid)
print(f"Longitude: {longitude}, Latitude: {latitude}")
# Get bounds for the grid cell
bounds = grid.get_bounds()
print(f"Bounds: {bounds}")
```
## Methods
### `lonlat_to_gid`
Converts geographic coordinates to a geospatial grid identifier (GID).
**Parameters:**
- `longitude` (float): Longitude in decimal degrees (-180 to 180).
- `latitude` (float): Latitude in decimal degrees (-90 to 90).
- `level` (int): Precision level (1-14).
**Returns:**
- `str`: Grid identifier.
---
### `gid_to_lonlat`
Converts a grid ID to geographic coordinates.
**Parameters:**
- `gid` (str): Grid identifier.
**Returns:**
- `Tuple[float, float]`: Longitude and latitude of the grid cell's lower-left corner.
---
### `gid_to_bound`
Converts a grid ID to its geographical bounds.
**Parameters:**
- `gid` (str): Grid identifier.
**Returns:**
- `Tuple[float, float, float, float]`: Bounding box `(min_longitude, min_latitude, max_longitude, max_latitude)`.
---
### `get_bounds`
Returns the geographic boundary of the grid cell.
**Returns:**
- `Tuple[float, float, float, float]`: Bounding box `(min_longitude, min_latitude, max_longitude, max_latitude)`.
---
### `polyfill`
Finds all grid cells that intersect with a polygon.
**Parameters:**
- `geometry` (Polygon): Polygon geometry to fill.
- `size` (Union[int, List[int]]): Grid cell size or range of sizes.
- `start` (str): Starting cell identifier (default: "2").
- `fullcover` (bool): If `True`, only fully contained cells are returned.
**Returns:**
- `List[str]`: List of grid cell identifiers.
## Grid Cell Resolution Reference
| Size (meter) | Level | Approximate Cell Dimensions |
|----------|-------|----------------------------|
| 10000000 | 1 | Country-sized |
| 1000000 | 3 | Large region |
| 100000 | 5 | City-sized |
| 10000 | 7 | Neighborhood |
| 5000 | 8 | Block-sized |
| 1000 | 9 | Block-sized |
| 500 | 10 | Large building |
| 100 | 11 | Building complex |
| 50 | 12 | Building |
| 10 | 13 | Building |
| 5 | 14 | Room-sized |
## Documentation
For more detailed documentation, including advanced usage and API reference, please refer to the [docs](docs/index.rst).
## Versioning
This project uses automatic versioning based on Git tags with [setuptools_scm](https://github.com/pypa/setuptools_scm/).
### How it works:
- The version is automatically determined from Git tags
- Development versions include the commit hash (e.g., `1.0.0.dev0+g1234567`)
- Release versions match the Git tag exactly (e.g., `1.0.0`)
### Creating a new release:
1. Create and push a Git tag:
```bash
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin --tags
```
2. The GitHub Actions workflow will automatically build and publish to PyPI when a release is created
### Version management script:
Use the included script for version management:
```bash
# Show current version
python scripts/version_manager.py --current
# Create a new tag
python scripts/version_manager.py --create-tag v1.0.0 --message "Release version 1.0.0"
```
## License
This project is licensed under the GPL-3.0 license. See the [LICENSE](LICENSE) file for more details.
Raw data
{
"_id": null,
"home_page": "https://github.com/geosquareai/geosquare-grid",
"name": "geosquare-grid",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "geography, grid, coordinates, spatial, GIS",
"author": "Geosquare Team",
"author_email": "Geosquare Team <admin@geosquare.ai>",
"download_url": "https://files.pythonhosted.org/packages/5c/62/84249ff94d4ea1e90abc386c6d89a90fe4f9eb51f5bc525a93742fcf0e3f/geosquare_grid-1.1.1.tar.gz",
"platform": null,
"description": "# Geosquare Grid\n\nGeosquare Grid is a Python library that provides methods for converting between geographic coordinates (longitude and latitude) and grid identifiers (GIDs). It also includes functionality for spatial operations and geometry handling, making it a useful tool for geospatial analysis and mapping applications.\n\n## Features\n\n- Convert longitude/latitude to GID and vice versa.\n- Retrieve bounds for grid cells.\n- Get geometries for grid cells.\n- Find all grid cells that overlap with specified geometries.\n- Easy integration with QGIS for geospatial applications.\n\n## Installation\n\nYou can install the Geosquare Grid library using pip:\n\n```bash\npip install geosquare-grid\n```\n\n## Usage\n\nHere is a simple example of how to use the Geosquare Grid library:\n\n```python\nfrom geosquare_grid import GeosquareGrid\n\n# Initialize the GeosquareGrid object\ngrid = GeosquareGrid()\n\n# Convert longitude and latitude to GID\ngid = grid.lonlat_to_gid(longitude=106.8938638928753022, latitude=-6.2608983083383016, level=5)\nprint(f\"GID: {gid}\")\n\n# Convert GID back to longitude and latitude\nlongitude, latitude = grid.gid_to_lonlat(gid)\nprint(f\"Longitude: {longitude}, Latitude: {latitude}\")\n\n# Get bounds for the grid cell\nbounds = grid.get_bounds()\nprint(f\"Bounds: {bounds}\")\n```\n\n## Methods\n\n### `lonlat_to_gid`\nConverts geographic coordinates to a geospatial grid identifier (GID).\n\n**Parameters:**\n- `longitude` (float): Longitude in decimal degrees (-180 to 180).\n- `latitude` (float): Latitude in decimal degrees (-90 to 90).\n- `level` (int): Precision level (1-14).\n\n**Returns:**\n- `str`: Grid identifier.\n\n---\n\n### `gid_to_lonlat`\nConverts a grid ID to geographic coordinates.\n\n**Parameters:**\n- `gid` (str): Grid identifier.\n\n**Returns:**\n- `Tuple[float, float]`: Longitude and latitude of the grid cell's lower-left corner.\n\n---\n\n### `gid_to_bound`\nConverts a grid ID to its geographical bounds.\n\n**Parameters:**\n- `gid` (str): Grid identifier.\n\n**Returns:**\n- `Tuple[float, float, float, float]`: Bounding box `(min_longitude, min_latitude, max_longitude, max_latitude)`.\n\n---\n\n### `get_bounds`\nReturns the geographic boundary of the grid cell.\n\n**Returns:**\n- `Tuple[float, float, float, float]`: Bounding box `(min_longitude, min_latitude, max_longitude, max_latitude)`.\n\n---\n\n### `polyfill`\nFinds all grid cells that intersect with a polygon.\n\n**Parameters:**\n- `geometry` (Polygon): Polygon geometry to fill.\n- `size` (Union[int, List[int]]): Grid cell size or range of sizes.\n- `start` (str): Starting cell identifier (default: \"2\").\n- `fullcover` (bool): If `True`, only fully contained cells are returned.\n\n**Returns:**\n- `List[str]`: List of grid cell identifiers.\n\n## Grid Cell Resolution Reference\n\n| Size (meter) | Level | Approximate Cell Dimensions |\n|----------|-------|----------------------------|\n| 10000000 | 1 | Country-sized |\n| 1000000 | 3 | Large region |\n| 100000 | 5 | City-sized |\n| 10000 | 7 | Neighborhood |\n| 5000 | 8 | Block-sized |\n| 1000 | 9 | Block-sized |\n| 500 | 10 | Large building |\n| 100 | 11 | Building complex |\n| 50 | 12 | Building |\n| 10 | 13 | Building |\n| 5 | 14 | Room-sized |\n\n## Documentation\n\nFor more detailed documentation, including advanced usage and API reference, please refer to the [docs](docs/index.rst).\n\n## Versioning\n\nThis project uses automatic versioning based on Git tags with [setuptools_scm](https://github.com/pypa/setuptools_scm/). \n\n### How it works:\n- The version is automatically determined from Git tags\n- Development versions include the commit hash (e.g., `1.0.0.dev0+g1234567`)\n- Release versions match the Git tag exactly (e.g., `1.0.0`)\n\n### Creating a new release:\n1. Create and push a Git tag:\n ```bash\n git tag -a v1.0.0 -m \"Release version 1.0.0\"\n git push origin --tags\n ```\n2. The GitHub Actions workflow will automatically build and publish to PyPI when a release is created\n\n### Version management script:\nUse the included script for version management:\n```bash\n# Show current version\npython scripts/version_manager.py --current\n\n# Create a new tag\npython scripts/version_manager.py --create-tag v1.0.0 --message \"Release version 1.0.0\"\n```\n\n## License\n\nThis project is licensed under the GPL-3.0 license. See the [LICENSE](LICENSE) file for more details.\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "A library for converting geographic coordinates to grid identifiers (GIDs) and performing spatial operations.",
"version": "1.1.1",
"project_urls": {
"Homepage": "https://github.com/geosquareai/geosquare-grid",
"Repository": "https://github.com/geosquareai/geosquare-grid"
},
"split_keywords": [
"geography",
" grid",
" coordinates",
" spatial",
" gis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0b84268ba9054ded401dd5afcf04ab4ee54ddd249d4d110895603de2219b8be4",
"md5": "eb4504b47e2f82cee53408cd0ec5b341",
"sha256": "23ffc6f02c75af489723c8abaebfcf409f445ace6cc61e55bf65323ae695a0e9"
},
"downloads": -1,
"filename": "geosquare_grid-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eb4504b47e2f82cee53408cd0ec5b341",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 23130,
"upload_time": "2025-08-28T01:07:54",
"upload_time_iso_8601": "2025-08-28T01:07:54.614900Z",
"url": "https://files.pythonhosted.org/packages/0b/84/268ba9054ded401dd5afcf04ab4ee54ddd249d4d110895603de2219b8be4/geosquare_grid-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5c6284249ff94d4ea1e90abc386c6d89a90fe4f9eb51f5bc525a93742fcf0e3f",
"md5": "552c03d22c91fbacdc6244b953eb9f15",
"sha256": "252a9a4ae1f1c6d5d4ef1b29e21b9d759cd2e4d0cdf5018b97cb4dd7e93af47a"
},
"downloads": -1,
"filename": "geosquare_grid-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "552c03d22c91fbacdc6244b953eb9f15",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 30303,
"upload_time": "2025-08-28T01:07:56",
"upload_time_iso_8601": "2025-08-28T01:07:56.382456Z",
"url": "https://files.pythonhosted.org/packages/5c/62/84249ff94d4ea1e90abc386c6d89a90fe4f9eb51f5bc525a93742fcf0e3f/geosquare_grid-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 01:07:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "geosquareai",
"github_project": "geosquare-grid",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "geosquare-grid"
}
JSON
