Skip to content

orbisgis/h2gis

Repository files navigation

H2GIS

GitHub codecov Codacy Badge

H2GIS is a spatial extension of the H2 database engine in the spirit of PostGIS. It adds support for managing spatial features and operations on the new Geometry type of H2, the Open Geospatial Consortium (OGC) Simple Features for SQL (SFSQL) functions and additional spatial functions that we (the CNRS) develop.

H2GIS is the root project for the OrbisGIS data management library. It contains tools to run geometry analysis and read/write geospatial file formats.

H2GIS is licensed under the LGPL 3 license terms.

GEOMETRY data type

Since H2 2.2.X version, the geometry encoding to store the value in H2 is the EWKB (extended well-known binary) format. The EWKB format is not an OGC standard, but a PostGIS specific format that includes the spatial reference system (SRID) identifier. Its textual representation using the WKT (well-known text) uses the pattern :

'SRID=4326;POINT(0 0)'

H2 supports POINT, LINESTRING, POLYGON, MULTIPOINT, MULTILINESTRING, MULTIPOLYGON, and GEOMETRYCOLLECTION geometries with the following coordinate dimension 2D (XY), Z (XYZ), M (XYM), and ZM (XYZM).

H2 provides the same syntax as PostGIS to build a table with a geometry data type.

e.g
CREATE TABLE mygeometrytable (ID INTEGER, GEOM GEOMETRY);
CREATE TABLE mygeometrytable (ID INTEGER, GEOM GEOMETRY(POINT));
CREATE TABLE mygeometrytable (ID INTEGER, GEOM GEOMETRY(POINT, 4326));
CREATE TABLE mygeometrytable (ID INTEGER, GEOM GEOMETRY(POINTZ, 4326));
CREATE TABLE mygeometrytable (ID INTEGER, GEOM GEOMETRY(POINTZM, 4326));
CREATE TABLE mygeometrytable (ID INTEGER, GEOM GEOMETRY(POINTM, 4326));

Spatial functions

h2gis-functions is the main module of the H2GIS distribution. It extends H2 by adding analysis capabilities,including

  • spatial operators (ST_Intersection, ST_Difference, etc.)
  • spatial predicates (ST_Intersects, ST_Contains, etc.)
  • additional spatial SQL functions that are not in Simple Features for SQL (SFSQL)

Ex: ST_Extent, ST_Explode, ST_MakeGrid

H2GIS contains a set of driver functions (I/O)) to read/write file formats such as .shp, .dbf, .geojson, .gpx

This I/O package include 2 implementation of TableEngine that allow you to immediatly 'link' a table with a shape file.

It include also file copy functions (import):

  • SHPREAD( ) and SHPWRITE( ) to read and write Esri shape files.
  • DBFREAD( ) and DBFWRITE( ) to read and write DBase III files.
  • GeoJsonRead() and GeoJsonWrite()
  • to read and write GeoJSON files.
  • GPXRead() to read GPX files.

Usage

H2GIS requires Java 11. Run maven clean install -P standalone in the H2GIS's root directory.

In the folder h2gis-dist/target/ you will find a zip file h2gis-standalone-bin.zip.Unzip the file then open h2gis-dist-xxx.jar It will open a browser based console application.

~ $ unzip h2gis-standalone-bin.zip

~ $ cd h2gis-standalone

~/h2gis-standalone $ java -jar h2gis-dist-xxx.jar

Click Connect in the web interface

Create a database and run the following commands to add spatial features (do it only after the creation of a new database):

Initialize the H2GIS extension

To initialize the H2GIS extension apply the SQL syntax:

CREATE ALIAS IF NOT EXISTS H2GIS_SPATIAL FOR "org.h2gis.functions.factory.H2GISFunctions.load";
CALL H2GIS_SPATIAL();

When the functions are installed you can open a shapefile by calling the following SQL request:

CALL FILE_TABLE('/home/user/myshapefile.shp', 'tablename');

This special table will be immediatly created (no matter the file size). The content will allways be synchronized with the file content.

You can also copy the content of the file into a regular H2 table:

CALL SHPREAD('/home/user/myshapefile.shp', 'tablename');

Or copy the content of a spatial table in a new shape file:

CALL SHPWRITE('/home/user/newshapefile.shp', 'tablename');

Contributing

For legal reasons, contributors are asked to provide a contributor license agreement (CLA).

The message need to include the following statement:

"I wrote the code, it's mine, and I'm contributing it to H2GIS for distribution licensed under the LGPL 3.0."

If you want to contribute send a PR on GitHub and refer the CLA in your message.

Download

To download the last H2GIS stable release and find documentation please go to http://www.h2gis.org

You can include H2GIS in your project thanks to Maven repositories.

From maven central, check https://search.maven.org/artifact/org.orbisgis/h2gis/2.2.1/bundle

To use the current snapshot add in the pom

<repository>
  <id>orbisgis-snapshot</id>
  <name>OrbisGIS sonatype snapshot repository</name>
  <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
</repository>

Acknowledgements

The H2GIS team uses open source software. Specifically, we would like to thank :

Supporters

Many thanks for those who reported bugs or provide patches...

Team

H2GIS is leaded by scientists and engineers in GIS and informatic sciences from CNRS within the French Lab-STICC laboratory (DECIDE team of Vannes). H2GIS is funded by research programs.