Utilities for Hexagonal ASCII grids

Copyright

Copyright (c) 2016-2020 Luís Moreira de Sousa. All rights reserved. Any use of this software constitutes full acceptance of all terms of the document licence.

Project updates

For the latest updates please consult hex-utils project page at ResearchGate.

New information is also posted on Twitter under the #HexASCII tag.

Description

This project aims to deliver a series of tools to facilitate the manipulation and usage of hexagonal raster grids. These tools rely on the Hexagonal ASCII file format (or HASC for short) for the physical storage of hexagonal rasters.

• hasc2gml - from an input HASC file creates a GML file with a vector feature for each hexagonal cell. Simplifies the display of hexagonal rasters in common desktop GIS software.

• asc2hasc - creates an HASC file from an input ESRI ASCII grid. It can either preserve cell area or approximate spatial resolution.

• surface2hasc - creates an HASC file from a continuous surface function.

• surface2asc - creates an ESRI ASCII file from a continuous surface function.

Future work includes the development of a Graphical User Interface (GUI) for these tools on QGIS, making the usage of hexagonal grids even simpler.

This tool suite can be installed from the PyPi repository.

Installation Requirements

The Python package manager is required to install dependencies; on Debian based systems it can be obtained like:

sudo apt install python3-pip

Installing from PyPi

The easiest way to install hex-utils is through the universal package available from the Python Package Index (PyPi); an example again on Debian based systems:

sudo pip3 install hex-utils

Installing from Git

Start by cloning the repository to your system:

git clone git@codeberg.org:ldesousa/hex-utils.git

Change to the new folder:

cd hex-utils.git

It is possible to install directly from the master branch, but it is more advisable to use one of the tagged releases, e.g.:

git checkout tags/v0.4.4

Then install the scripts system wide:

sudo python3 setup.py install

Finally, install the remaining dependencies:

sudo pip3 install -r requirements.txt

Note that you may already have some of these packages installed on your system. That being the case, the best option is to use a virtual environment.

Special requirements

The hasc2gml script requires the Python GDAL library; the asc2hasc script requires the scipy library. Functional Python packages of these libraries might not be available for all systems. In such cases pre-compiled and system specific are required. On Debian based systems these can be installed with the following command:

sudo apt install python3-gdal python3-scipy

To install the GDAL bindings library from PyPi.org make sure it matches the version installed on your system. For instance, on Ubuntu 20.04 this will be 3.0.4:

$ apt search libgdal
Sorting... Done
Full Text Search... Done
libgdal-dev/focal,now 3.0.4+dfsg-1build3 amd64 [installed]

The requirements.txt file should be edited accordingly before installing. Or to install directly from PyPi.org:

pip install GDAL==3.0.4

QGis plug-in

The tools in this package can also be used through a QGis plug-in offering a graphical user interface to most of the functionalities.

Citing hex-utils

Please use the reference below to cite the hex-utilstoolkit:

de Sousa L. M. and Leitão, J. P. Hex-utils: A Tool Set Supporting HexASCII Hexagonal rasters. Proceedings of the 3rd International Conference on Geographical Information Systems Theory, Applications and Management: GISTAM, 1, 177-183, 2017.

Licence

This suite of programmes is released under the EUPL 1.1 licence. For full details please consult the LICENCE file.