Package: equi7grid
Equi7GridTheEqui7Gridis a spatial reference system designed to handle efficiently the archiving, processing, and displaying ofhigh resolution raster image data. It supports geo-datacubes holding large volumes of satellite imagery, as it preserves geometric accuracy andminimises data oversampling over global land surfacesto 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 thisjournal article.GeometriesShapefiles for the continental zone boundaries and tilings are here~/src/equi7grid/grids/... with files inPROJprojected to the Equi7Grid space (meters), and inGEOGcorresponding 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 followingproj4-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 installationThis package can be installed through pip:pipinstallEqui7GridInstalls forscipyandgdalare required from conda or conda-forge (seebelowhow to set up a fresh environment).Usage examplesTheEqui7Gridpackage 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 interestYou can retrieve all tiles covering a region of interest defined using Lon-Lat coordinates usingsearch_tiles_in_roi:tiles=Equi7Grid(500).search_tiles_in_roi(bbox=[(0,30),(10,40)],coverland=True)assertsorted(tiles)==sorted(['EU500M_E036N006T6','EU500M_E042N000T6','EU500M_E042N006T6','AF500M_E030N084T6','AF500M_E030N090T6','AF500M_E036N084T6','AF500M_E036N090T6','AF500M_E042N084T6','AF500M_E042N090T6'])snippet source|anchorExample 2: Reproject a GeoTIFF file to Equi7 tilesThe package provides with theimage2equi7grid()a convenient method to quickly convert existing raster data stored as GeoTIFFs to tiles in Equi7Grid projection(s):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()snippet source|anchorThe tool usesgdalto 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 tilesEU100M_E072N030T6andAS100M_E018N066T6. Checkout the functionimage2equi7grid()for more options on output, format, encoding, etc.Note 2: Windows users might need to manually specify thegdal_pathas part of the function arguments, for example:image2equi7grid(gdal_path=r"C:\...your_path...\envs\equi7grid\Library\bin")More examples ...checkout the tests at~/tests/test_equi7grid.pywhich exemplify many more functions.Development installationFor development, we recommend using themaketool to automatically create python environments and install more complex
dependencies i.e.gdal.Instruction on how to set up an environment on systems without propermakesupport, such as Windows, can be found in a
subsequent section.Creating python environments withmakeCondaMake sure miniconda3 is installed by following
theofficial installation instructions.
To create a new development environment usingcondamake thecondarule:makecondaThis will create a new conda environment calledequi7gridand install all necessary dependencies.VirtualenvMake sure you have installedvirtualenvandgdalon your system.
For instance under Ubuntu you can install gdal usingapt install libgdal-dev, andvirtualenvusingapt install python3-venv.
To set up a virtualenv environment simply make thevenvrule:makevenvThis will create avirtualenvenvironment within avenvfolder at the root of the project.
It will install thegdaldependency usingpygdalwhich requiresgdalto be
installed on the system.Installing test dependenciesTo create a testing environment you can set theTEST_ENV=1parameter:makevenvTEST_ENV=1After activating the environment you can make thetestrule to run all unit tests:maketestCreating python environments on WindowsFirst make sure miniconda3 is installed on your system by following
theinstallation instructions.Create theequi7gridconda environment from theenvironment.ymlprovided at the root of the repository.conda env create -f environment_win.ymlSee also the official anaconda documentation
fordetailed instructions on environments and environment files.Now you should be able to activate the environment:conda activate equi7gridOnce activate, you can install theEqui7Gridpackage in development mode using pip by running the following command in
the root directory of the repository:pip install -e .Installing test dependenciesTo 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.ContributeWe 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.GuidelinesIf you want to contribute please follow these steps:Fork the Equi7Grid repository to your accountClone the repositorymake a new feature branch from the Equi7Grid master branchAdd your featurePlease include tests for your contributions in one of the test directories.
We use py.test so a simple function called test_my_feature is enoughsubmit a pull request to our master branchCitationIf 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 athttps://doi.org/10.5281/zenodo.1048530to 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 athttp://help.zenodo.org/#versioning