| Name | equi7grid JSON |
| Version |
0.2.4
JSON |
| download |
| home_page | https://mrs.geo.tuwien.ac.at |
| Summary | Definition and tools for Equi7Grid and its tiling system |
| upload_time | 2023-08-16 06:49:18 |
| maintainer | |
| docs_url | None |
| author | TU Wien |
| requires_python | |
| license | mit |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Equi7Grid
[](https://github.com/TUW-GEO/Equi7Grid/actions/workflows/ubuntu.yml)
[](https://github.com/TUW-GEO/Equi7Grid/actions/workflows/windows.yml)
[](https://coveralls.io/github/TUW-GEO/Equi7Grid?branch=master)
[](https://badge.fury.io/py/Equi7Grid)
[](https://equi7grid.readthedocs.io/)
The **Equi7Grid** is a spatial reference system designed to handle efficiently the archiving, processing, and displaying of **high resolution raster image data**. It supports geo-datacubes holding large volumes of satellite imagery, as it preserves geometric accuracy and **minimises data oversampling over global land surfaces** to a very low value of 3%.
---
This package contains:
- Geometries and projection-files defining the contentinal zones, coordinate system, projection parameters, base tilings, etc.
- A python class for working with Equi7Grid: how to convert to, how to use the tiling system, how to identify coordinates, etc.
A detailed documentation on the Equi7Grid definition is at
`~/docs/doc_files/`
and its scientific background is published in this [**journal article**](https://www.sciencedirect.com/science/article/pii/S0098300414001629).
## Geometries
Shapefiles for the continental zone boundaries and tilings are here
`~/src/equi7grid/grids/`
... with files in `PROJ` projected to the Equi7Grid space (meters), and in `GEOG` corresponding files in common geographic Lon-Lat space (degrees):
Overlays for visualisation in Google Earth are here:
`~/docs/doc_files/google_earth_overlays/`
The 7 projections (or more precisely the Projected Coordinate Reference Systems, PROJCS) are completely defined by WKT-strings in the .prj-files at
`~/wkt/`
or simply by following **proj4-strings**:
```
AF: '+proj=aeqd +lat_0=8.5 +lon_0=21.5 +x_0=5621452.01998 +y_0=5990638.42298 +datum=WGS84 +units=m +no_defs'
AN: '+proj=aeqd +lat_0=-90 +lon_0=0 +x_0=3714266.97719 +y_0=3402016.50625 +datum=WGS84 +units=m +no_defs'
AS: '+proj=aeqd +lat_0=47 +lon_0=94 +x_0=4340913.84808 +y_0=4812712.92347 +datum=WGS84 +units=m +no_defs'
EU: '+proj=aeqd +lat_0=53 +lon_0=24 +x_0=5837287.81977 +y_0=2121415.69617 +datum=WGS84 +units=m +no_defs'
NA: '+proj=aeqd +lat_0=52 +lon_0=-97.5 +x_0=8264722.17686 +y_0=4867518.35323 +datum=WGS84 +units=m +no_defs'
OC: '+proj=aeqd +lat_0=-19.5 +lon_0=131.5 +x_0=6988408.5356 +y_0=7654884.53733 +datum=WGS84 +units=m +no_defs'
SA: '+proj=aeqd +lat_0=-14 +lon_0=-60.5 +x_0=7257179.23559 +y_0=5592024.44605 +datum=WGS84 +units=m +no_defs'
```
## User installation
This package can be installed through pip:
```bash
pip install Equi7Grid
```
Installs for `scipy` and `gdal` are required from conda or conda-forge (see [below](#devinst) how to set up a fresh environment).
## Usage examples
The `Equi7Grid` package provides python tools to interact with different projections, query information from the Equi7Grid geometries, and access the tiling system.
### Example 1: Retrieving Equi7 tiles covering a region of interest
You can retrieve all tiles covering a region of interest defined using Lon-Lat coordinates using `search_tiles_in_roi`:
<!-- snippet: search-tiles-in-lon-lat-roi -->
<a id='snippet-search-tiles-in-lon-lat-roi'></a>
```py
tiles = Equi7Grid(500).search_tiles_in_roi(bbox=[(0, 30), (10, 40)], coverland=True)
assert sorted(tiles) == sorted([
'EU500M_E036N006T6', 'EU500M_E042N000T6', 'EU500M_E042N006T6',
'AF500M_E030N084T6', 'AF500M_E030N090T6', 'AF500M_E036N084T6',
'AF500M_E036N090T6', 'AF500M_E042N084T6', 'AF500M_E042N090T6'])
```
<sup><a href='/tests/test_equi7grid.py#L327-L333' title='Snippet source file'>snippet source</a> | <a href='#snippet-search-tiles-in-lon-lat-roi' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->
### Example 2: Reproject a GeoTIFF file to Equi7 tiles
The package provides with the `image2equi7grid()` a convenient method to quickly convert existing raster data stored as GeoTIFFs to tiles in Equi7Grid projection(s):
<!-- snippet: image2equi7grid-example -->
<a id='snippet-image2equi7grid-example'></a>
```py
input_file = input_dir / "lake_in_russia_lonlat.tif"
image2equi7grid(Equi7Grid(100), input_file.as_posix(), out_dir.as_posix())
assert (out_dir / "EQUI7_AS100M/E018N066T6/lake_in_russia_lonlat_AS100M_E018N066T6.tif").exists()
assert (out_dir / "EQUI7_EU100M/E072N030T6/lake_in_russia_lonlat_EU100M_E072N030T6.tif").exists()
```
<sup><a href='/tests/test_approve_image2equi7grid.py#L18-L24' title='Snippet source file'>snippet source</a> | <a href='#snippet-image2equi7grid-example' title='Start of snippet'>anchor</a></sup>
<!-- endSnippet -->
The tool uses `gdal` to efficiently warp the raster data to the Equi7 projection, and generate a folder structure for each Equi7 tile that covers the input raster.
**Note 1**: The input file of this (advanced) example lies between Asia and Europe, and by default the function writes output for all tiles that cover the input, in this example for the Equi7 tiles *EU100M_E072N030T6* and *AS100M_E018N066T6*. Checkout the function `image2equi7grid()` for more options on output, format, encoding, etc.
**Note 2**: Windows users might need to manually specify the `gdal_path` as part of the function arguments, for example:
```py
image2equi7grid(gdal_path=r"C:\...your_path...\envs\equi7grid\Library\bin")
```
### More examples ...
checkout the tests at
`~/tests/test_equi7grid.py`
which exemplify many more functions.
## <a name="devinst"></a>Development installation
For development, we recommend using the `make` tool to automatically create python environments and install more complex
dependencies i.e. `gdal`.
Instruction on how to set up an environment on systems without proper `make` support, such as Windows, can be found in a
subsequent section.
### Creating python environments with *make*
#### Conda
Make sure miniconda3 is installed by following
the [official installation instructions](https://conda.io/projects/conda/en/stable/user-guide/install/index.html).
To create a new development environment using `conda` make the `conda` rule:
```bash
make conda
```
This will create a new conda environment called `equi7grid` and install all necessary dependencies.
#### Virtualenv
Make sure you have installed `virtualenv` and `gdal` on your system.
For instance under Ubuntu you can install gdal using ``apt install libgdal-dev``, and `virtualenv`
using ``apt install python3-venv``.
To set up a virtualenv environment simply make the `venv` rule:
```bash
make venv
```
This will create a `virtualenv` environment within a `venv` folder at the root of the project.
It will install the `gdal` dependency using [pygdal](https://pypi.org/project/pygdal/) which requires `gdal` to be
installed on the system.
#### Installing test dependencies
To create a testing environment you can set the `TEST_ENV=1` parameter:
```bash
make venv TEST_ENV=1
```
After activating the environment you can make the `test` rule to run all unit tests:
```bash
make test
```
### Creating python environments on Windows
First make sure miniconda3 is installed on your system by following
the [installation instructions](https://conda.io/projects/conda/en/stable/user-guide/install/index.html).
Create the `equi7grid` conda environment from the `environment.yml` provided at the root of the repository.
```
conda env create -f environment_win.yml
```
See also the official anaconda documentation
for [detailed instructions on environments and environment files](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html).
Now you should be able to activate the environment:
```
conda activate equi7grid
```
Once activate, you can install the `Equi7Grid` package in development mode using pip by running the following command in
the root directory of the repository:
```
pip install -e .
```
#### Installing test dependencies
To install the test dependencies as well use:
```
pip install -e .[testing]
```
Now you should be able to run all unit tests:
```
pytest tests/
```
You can also have a look at the source of the Makefile for more detailed installation and testing options.
## Contribute
We are happy if you want to contribute. Please raise an issue explaining what
is missing or if you find a bug. We will also gladly accept pull requests
against our master branch for new features or bug fixes.
### Guidelines
If you want to contribute please follow these steps:
- Fork the Equi7Grid repository to your account
- Clone the repository
- make a new feature branch from the Equi7Grid master branch
- Add your feature
- Please include tests for your contributions in one of the test directories.
We use py.test so a simple function called test_my_feature is enough
- submit a pull request to our master branch
## Citation
[](https://doi.org/10.5281/zenodo.1048530)
If you use the software in a publication then please cite it using the Zenodo DOI.
Be aware that this badge links to the latest package version.
Please select your specific version at https://doi.org/10.5281/zenodo.1048530 to get the DOI of that version.
You should normally always use the DOI for the specific version of your record in citations.
This is to ensure that other researchers can access the exact research artefact you used for reproducibility.
You can find additional information regarding DOI versioning at http://help.zenodo.org/#versioning
Raw data
{
"_id": null,
"home_page": "https://mrs.geo.tuwien.ac.at",
"name": "equi7grid",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "TU Wien",
"author_email": "remote.sensing@geo.tuwien.ac.at",
"download_url": "https://files.pythonhosted.org/packages/7e/2f/f522befd9fb609f9ec992d9f791851623387f941cbd5ee4da4cabee43c5d/equi7grid-0.2.4.tar.gz",
"platform": "any",
"description": "# Equi7Grid\n\n[](https://github.com/TUW-GEO/Equi7Grid/actions/workflows/ubuntu.yml)\n[](https://github.com/TUW-GEO/Equi7Grid/actions/workflows/windows.yml)\n[](https://coveralls.io/github/TUW-GEO/Equi7Grid?branch=master)\n[](https://badge.fury.io/py/Equi7Grid)\n[](https://equi7grid.readthedocs.io/)\n\nThe **Equi7Grid** is a spatial reference system designed to handle efficiently the archiving, processing, and displaying of **high resolution raster image data**. It supports geo-datacubes holding large volumes of satellite imagery, as it preserves geometric accuracy and **minimises data oversampling over global land surfaces** to a very low value of 3%.\n\n---\n\n\n\nThis package contains:\n- Geometries and projection-files defining the contentinal zones, coordinate system, projection parameters, base tilings, etc.\n- A python class for working with Equi7Grid: how to convert to, how to use the tiling system, how to identify coordinates, etc.\n\nA detailed documentation on the Equi7Grid definition is at\n\n`~/docs/doc_files/`\n\nand its scientific background is published in this [**journal article**](https://www.sciencedirect.com/science/article/pii/S0098300414001629).\n\n## Geometries\n\nShapefiles for the continental zone boundaries and tilings are here\n\n`~/src/equi7grid/grids/`\n\n... with files in `PROJ` projected to the Equi7Grid space (meters), and in `GEOG` corresponding files in common geographic Lon-Lat space (degrees):\n\nOverlays for visualisation in Google Earth are here:\n\n`~/docs/doc_files/google_earth_overlays/`\n\nThe 7 projections (or more precisely the Projected Coordinate Reference Systems, PROJCS) are completely defined by WKT-strings in the .prj-files at \n\n`~/wkt/`\n\nor simply by following **proj4-strings**:\n\n```\nAF: '+proj=aeqd +lat_0=8.5 +lon_0=21.5 +x_0=5621452.01998 +y_0=5990638.42298 +datum=WGS84 +units=m +no_defs'\nAN: '+proj=aeqd +lat_0=-90 +lon_0=0 +x_0=3714266.97719 +y_0=3402016.50625 +datum=WGS84 +units=m +no_defs'\nAS: '+proj=aeqd +lat_0=47 +lon_0=94 +x_0=4340913.84808 +y_0=4812712.92347 +datum=WGS84 +units=m +no_defs'\nEU: '+proj=aeqd +lat_0=53 +lon_0=24 +x_0=5837287.81977 +y_0=2121415.69617 +datum=WGS84 +units=m +no_defs'\nNA: '+proj=aeqd +lat_0=52 +lon_0=-97.5 +x_0=8264722.17686 +y_0=4867518.35323 +datum=WGS84 +units=m +no_defs'\nOC: '+proj=aeqd +lat_0=-19.5 +lon_0=131.5 +x_0=6988408.5356 +y_0=7654884.53733 +datum=WGS84 +units=m +no_defs'\nSA: '+proj=aeqd +lat_0=-14 +lon_0=-60.5 +x_0=7257179.23559 +y_0=5592024.44605 +datum=WGS84 +units=m +no_defs'\n```\n\n## User installation\n\nThis package can be installed through pip:\n\n```bash\npip install Equi7Grid\n```\n\nInstalls for `scipy` and `gdal` are required from conda or conda-forge (see [below](#devinst) how to set up a fresh environment).\n\n## Usage examples\n\nThe `Equi7Grid` package provides python tools to interact with different projections, query information from the Equi7Grid geometries, and access the tiling system.\n\n### Example 1: Retrieving Equi7 tiles covering a region of interest\n\nYou can retrieve all tiles covering a region of interest defined using Lon-Lat coordinates using `search_tiles_in_roi`:\n\n<!-- snippet: search-tiles-in-lon-lat-roi -->\n<a id='snippet-search-tiles-in-lon-lat-roi'></a>\n```py\ntiles = Equi7Grid(500).search_tiles_in_roi(bbox=[(0, 30), (10, 40)], coverland=True)\nassert sorted(tiles) == sorted([\n 'EU500M_E036N006T6', 'EU500M_E042N000T6', 'EU500M_E042N006T6',\n 'AF500M_E030N084T6', 'AF500M_E030N090T6', 'AF500M_E036N084T6',\n 'AF500M_E036N090T6', 'AF500M_E042N084T6', 'AF500M_E042N090T6'])\n```\n<sup><a href='/tests/test_equi7grid.py#L327-L333' title='Snippet source file'>snippet source</a> | <a href='#snippet-search-tiles-in-lon-lat-roi' title='Start of snippet'>anchor</a></sup>\n<!-- endSnippet -->\n\n### Example 2: Reproject a GeoTIFF file to Equi7 tiles\nThe package provides with the `image2equi7grid()` a convenient method to quickly convert existing raster data stored as GeoTIFFs to tiles in Equi7Grid projection(s):\n\n<!-- snippet: image2equi7grid-example -->\n<a id='snippet-image2equi7grid-example'></a>\n```py\ninput_file = input_dir / \"lake_in_russia_lonlat.tif\"\nimage2equi7grid(Equi7Grid(100), input_file.as_posix(), out_dir.as_posix())\n\nassert (out_dir / \"EQUI7_AS100M/E018N066T6/lake_in_russia_lonlat_AS100M_E018N066T6.tif\").exists()\nassert (out_dir / \"EQUI7_EU100M/E072N030T6/lake_in_russia_lonlat_EU100M_E072N030T6.tif\").exists()\n```\n<sup><a href='/tests/test_approve_image2equi7grid.py#L18-L24' title='Snippet source file'>snippet source</a> | <a href='#snippet-image2equi7grid-example' title='Start of snippet'>anchor</a></sup>\n<!-- endSnippet -->\n\nThe tool uses `gdal` to efficiently warp the raster data to the Equi7 projection, and generate a folder structure for each Equi7 tile that covers the input raster.\n\n**Note 1**: The input file of this (advanced) example lies between Asia and Europe, and by default the function writes output for all tiles that cover the input, in this example for the Equi7 tiles *EU100M_E072N030T6* and *AS100M_E018N066T6*. Checkout the function `image2equi7grid()` for more options on output, format, encoding, etc.\n\n**Note 2**: Windows users might need to manually specify the `gdal_path` as part of the function arguments, for example:\n```py\nimage2equi7grid(gdal_path=r\"C:\\...your_path...\\envs\\equi7grid\\Library\\bin\")\n```\n\n### More examples ...\ncheckout the tests at\n\n`~/tests/test_equi7grid.py`\n\nwhich exemplify many more functions.\n\n## <a name=\"devinst\"></a>Development installation\n\nFor development, we recommend using the `make` tool to automatically create python environments and install more complex\ndependencies i.e. `gdal`.\n\nInstruction on how to set up an environment on systems without proper `make` support, such as Windows, can be found in a\nsubsequent section.\n\n### Creating python environments with *make*\n\n#### Conda\n\nMake sure miniconda3 is installed by following\nthe [official installation instructions](https://conda.io/projects/conda/en/stable/user-guide/install/index.html).\nTo create a new development environment using `conda` make the `conda` rule:\n\n```bash\nmake conda\n```\n\nThis will create a new conda environment called `equi7grid` and install all necessary dependencies.\n\n#### Virtualenv\n\nMake sure you have installed `virtualenv` and `gdal` on your system.\nFor instance under Ubuntu you can install gdal using ``apt install libgdal-dev``, and `virtualenv`\nusing ``apt install python3-venv``.\nTo set up a virtualenv environment simply make the `venv` rule:\n\n```bash\nmake venv\n```\n\nThis will create a `virtualenv` environment within a `venv` folder at the root of the project.\nIt will install the `gdal` dependency using [pygdal](https://pypi.org/project/pygdal/) which requires `gdal` to be\ninstalled on the system.\n\n#### Installing test dependencies\n\nTo create a testing environment you can set the `TEST_ENV=1` parameter:\n\n```bash\nmake venv TEST_ENV=1\n```\n\nAfter activating the environment you can make the `test` rule to run all unit tests:\n\n```bash\nmake test\n```\n\n### Creating python environments on Windows\n\nFirst make sure miniconda3 is installed on your system by following\nthe [installation instructions](https://conda.io/projects/conda/en/stable/user-guide/install/index.html).\n\nCreate the `equi7grid` conda environment from the `environment.yml` provided at the root of the repository.\n\n```\nconda env create -f environment_win.yml\n```\n\nSee also the official anaconda documentation\nfor [detailed instructions on environments and environment files](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html).\n\nNow you should be able to activate the environment:\n\n```\nconda activate equi7grid\n```\n\nOnce activate, you can install the `Equi7Grid` package in development mode using pip by running the following command in\nthe root directory of the repository:\n\n```\npip install -e .\n```\n\n#### Installing test dependencies\n\nTo install the test dependencies as well use:\n\n```\npip install -e .[testing]\n```\n\nNow you should be able to run all unit tests:\n\n```\npytest tests/\n```\n\nYou can also have a look at the source of the Makefile for more detailed installation and testing options.\n\n## Contribute\n\nWe are happy if you want to contribute. Please raise an issue explaining what\nis missing or if you find a bug. We will also gladly accept pull requests\nagainst our master branch for new features or bug fixes.\n\n### Guidelines\n\nIf you want to contribute please follow these steps:\n\n- Fork the Equi7Grid repository to your account\n- Clone the repository\n- make a new feature branch from the Equi7Grid master branch\n- Add your feature\n- Please include tests for your contributions in one of the test directories.\n We use py.test so a simple function called test_my_feature is enough\n- submit a pull request to our master branch\n\n## Citation\n\n[](https://doi.org/10.5281/zenodo.1048530)\n\nIf you use the software in a publication then please cite it using the Zenodo DOI.\nBe aware that this badge links to the latest package version.\n\nPlease select your specific version at https://doi.org/10.5281/zenodo.1048530 to get the DOI of that version.\nYou should normally always use the DOI for the specific version of your record in citations.\nThis is to ensure that other researchers can access the exact research artefact you used for reproducibility.\n\nYou can find additional information regarding DOI versioning at http://help.zenodo.org/#versioning\n",
"bugtrack_url": null,
"license": "mit",
"summary": "Definition and tools for Equi7Grid and its tiling system",
"version": "0.2.4",
"project_urls": {
"Documentation": "https://equi7grid.readthedocs.io/",
"Homepage": "https://mrs.geo.tuwien.ac.at"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a56c60be394b0dcd9efdaeee15df5806a3ab426b08d0aba3b25339e8dfb242bd",
"md5": "16d502ae5b86f23b5a1596ef3883d235",
"sha256": "525cc22dbb7d863c16060702a830ff6d7bee512e8917ce709d9423301a6eefb2"
},
"downloads": -1,
"filename": "equi7grid-0.2.4-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "16d502ae5b86f23b5a1596ef3883d235",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 692593,
"upload_time": "2023-08-16T06:49:16",
"upload_time_iso_8601": "2023-08-16T06:49:16.793233Z",
"url": "https://files.pythonhosted.org/packages/a5/6c/60be394b0dcd9efdaeee15df5806a3ab426b08d0aba3b25339e8dfb242bd/equi7grid-0.2.4-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7e2ff522befd9fb609f9ec992d9f791851623387f941cbd5ee4da4cabee43c5d",
"md5": "e0cefc775d014957088d5c2479111143",
"sha256": "425a95fd7825cc2218fecd65986297d4064898c7be291189153e6ce294f10e03"
},
"downloads": -1,
"filename": "equi7grid-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "e0cefc775d014957088d5c2479111143",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 698897,
"upload_time": "2023-08-16T06:49:18",
"upload_time_iso_8601": "2023-08-16T06:49:18.241223Z",
"url": "https://files.pythonhosted.org/packages/7e/2f/f522befd9fb609f9ec992d9f791851623387f941cbd5ee4da4cabee43c5d/equi7grid-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-16 06:49:18",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "equi7grid"
}
