H2GIS Python

This is a python package that allows to manipulate H2GIS spatial database using a GraalVM-compiled native library and a C interface.

Main points

• Installation: Installation and setup instructions.
• H2GIS class: Detailed documentation for the H2GIS class.
• Example: Example usage of the library.

If you want information about h2gis you can go to the h2gis website.

Installation

Requirements

• Python 3.7+
• Native H2GIS shared library compiled with GraalVM
• Supported platforms: Linux, Windows

Install the Python Package

pip install .

Ensure the native library file is present in the following structure:

h2gis/
├── lib/
│ ├── h2gis.so # Linux
│ ├── h2gis.dylib # macOS
│ └── h2gis.dll # Windows

Custom Library Path

You can specify a custom path to the native library:

fromh2gisimportH2GISdb=H2GIS(lib_path="/custom/path/to/h2gis.so")
# H2GIS Class## Overview`H2GIS`isaPythonclassthatwrapsanativesharedlibrarycompiledwithGraalVM. ItprovidesaccesstoanembeddedH2GISdatabaseusingGraalVMisolateandthreadobjects.
## Constructor```pythonH2GIS(lib_path=None)

• lib_path: Optional path to the .so, .dll, or .dylib file. If not provided, a default path is used based on the current OS.

Methods

connect(db_file: str, username="sa", password="")

Connect to a local H2GIS database file.

execute(sql: str) -> int

Execute an INSERT, UPDATE, or DELETE SQL statement.

fetch(sql: str) -> list[str]

Execute a SELECT SQL query and return results as a list of strings (one per row).

close()

Close the active database connection.

__del__()

Destructor that automatically tears down the GraalVM isolate and closes any connection.

H2GIS Class

Overview

H2GIS is a Python class that wraps a native shared library compiled with GraalVM. It provides access to an embedded H2GIS database using GraalVM isolate and thread objects.

Constructor

H2GIS(lib_path=None)

• lib_path: Optional path to the .so, .dll, or .dylib file. If not provided, a default path is used based on the current OS.

Methods

connect(db_file: str, username="sa", password="")

Connect to a local H2GIS database file.

execute(sql: str) -> int

Execute an INSERT, UPDATE, or DELETE SQL statement.

commit() -> int

Commit the current transaction by executing COMMIT;.

rollback() -> int

Rollback the current transaction by executing ROLLBACK;.

fetch(query: str, row_index: int = 1, stringformat="utf-8") -> dict[str, list]

Execute a SELECT SQL query and return all result rows as a typed dictionary. Each key is a column name, and each value is a list of column values.

parse_string_buffer(buf: bytes, num_rows: int) -> list[str | None]

Parse a buffer of length-prefixed UTF-8 strings or null entries.

parse_geometry_buffer(buf: bytes, num_rows: int) -> List[Optional[BaseGeometry]]

Parse a buffer of WKB geometry entries and return a list of Shapely geometry objects or None.

deserialize_resultset_buffer(buf: bytes) -> dict[str, list]

Deserialize the binary buffer returned by the native fetch_all function into a dictionary of columns with typed values.

isConnected() -> bool

Return True if a database connection is currently active and responsive.

ping() -> bool

Check if the database connection is alive by executing a test query.

close()

Close the current database connection but leave the isolate active.

deleteAndClose()

Delete the database file (if applicable) and close the connection.

Usage Examples

Basic Example

fromh2gisimportH2GISimportgeopandasasgpdimportpandasaspdfromshapely.wktimportloadsaswkt_loadsimportjsonimportmatplotlib.pyplotasplt# Import matplotlibimportast# Connexion and data importh2gis=H2GIS("/mydb/path/dbName")
h2gis.execute(""" DROP TABLE IF EXISTS LIEUX; CREATE TABLE LIEUX ( ID INT PRIMARY KEY AUTO_INCREMENT, NOM VARCHAR(255), DESCRIPTION VARCHAR(255), THE_GEOM GEOMETRY(GEOMETRY) ); INSERT INTO LIEUX (NOM, DESCRIPTION, THE_GEOM) VALUES ('Paris', 'Capitale de la France', ST_GeomFromText('POINT(2.3522 48.8566)', 4326)); INSERT INTO LIEUX (NOM, DESCRIPTION, THE_GEOM) VALUES ('Lyon', 'Ville gastronomique', ST_GeomFromText('POINT(4.8357 45.7640)', 4326)); INSERT INTO LIEUX (NOM, DESCRIPTION, THE_GEOM) VALUES ('Marseille', 'Port méditerranéen', ST_GeomFromText('POINT(5.3698 43.2965)', 4326)); INSERT INTO LIEUX (NOM, DESCRIPTION, THE_GEOM) VALUES ('Englobant', 'Géométrie englobante', ST_GeomFromText('POLYGON(( -4.72 48.42, -1.35 47.23, 0.88 47.90, 2.35 48.86, 4.08 49.33, 5.70 49.00, 6.65 48.16, 7.75 48.58, 7.27 47.50, 6.75 46.15, 6.00 45.45, 4.90 44.50, 4.20 43.80, 5.3698 43.2965, 3.50 43.00, 2.50 42.50, 0.50 42.80, -1.00 43.40, -1.80 44.50, -2.50 45.80, -2.90 46.80, -3.50 47.80, -4.72 48.42 ))', 4326));""")
# Fetch the select queryfetch=h2gis.fetch("SELECT NOM, DESCRIPTION, THE_GEOM as geometry FROM LIEUX;")
print(fetch)
# Convert as dataframegdf=gpd.GeoDataFrame(fetch, geometry="GEOMETRY", crs="EPSG:4326")
print(gdf)
# Gest distance between first two pointsiflen(gdf) >=2:
paris_geom=gdf[gdf['NOM'] =='Paris'].geometry.iloc[0]
lyon_geom=gdf[gdf['NOM'] =='Lyon'].geometry.iloc[0]
dist_paris_lyon=paris_geom.distance(lyon_geom) *111319.9print(f"Distance in meters between poit 1 and 2: {dist_paris_lyon:.2f} m")
else:
print("2 geometries needed to calculate a distance")
print("connected : ", h2gis.isConnected())
h2gis.close()
# Display datagdf.plot(edgecolor='black', figsize=(10, 8))
plt.xlabel("Longitude")
plt.ylabel("Latitude")
plt.show()

Custom Native Library Path

db=H2GIS(lib_path="/custom/path/h2gis.so")

Notes

• By default, the native .so, .dll are already included in the package, in the lib folder.