Make the th3index family selectable at build time with the H3 flag

.github/workflows/maven.yml

@@ -0,0 +1,110 @@
+name: Maven CI
+
+on:
+  push:
+    branches: ["main", "feat/**", "fix/**"]
+    paths-ignore:
+      - "**/*.md"
+      - "doc/**"
+  pull_request:
+    branches: ["main", "feat/**", "fix/**"]
+    paths-ignore:
+      - "**/*.md"
+      - "doc/**"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build and test (Java 21 / Spark 3.5)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Java 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "21"
+          cache: maven
+
+      - name: Install libmeos runtime dependencies
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y libjson-c5 libgeos-c1t64 libproj25 proj-data libgsl27 libh3-1
+
+      - name: Set up libmeos.so and LD_LIBRARY_PATH
+        run: |
+          mkdir -p /tmp/libmeos
+          cp "$GITHUB_WORKSPACE/lib/libmeos.so" /tmp/libmeos/libmeos.so
+          echo "LD_LIBRARY_PATH=/tmp/libmeos" >> "$GITHUB_ENV"
+
+      - name: Provide the MEOS spatial_ref_sys table
+        run: |
+          # libmeos resolves SRID metadata (geodetic recognition for
+          # tgeogpoint, transforms) from its built-in default path
+          # /usr/local/share/spatial_ref_sys.csv. The vendored .so ships
+          # without that data file, so geography input fails with
+          # MEOS_ERR_INVALID_ARG. Fetch the canonical table to the default
+          # path, as a runtime data dependency rather than a vendored blob.
+          sudo mkdir -p /usr/local/share
+          sudo curl -fsSL \
+            https://raw.githubusercontent.com/MobilityDB/MobilityDB/master/meos/src/geo/spatial_ref_sys.csv \
+            -o /usr/local/share/spatial_ref_sys.csv
+          test -s /usr/local/share/spatial_ref_sys.csv
+
+      - name: Install JMEOS 1.4 to local Maven repository
+        run: |
+          mvn install:install-file \
+            -Dfile=libs/JMEOS-1.4.jar \
+            -DgroupId=org.jmeos \
+            -DartifactId=jmeos \
+            -Dversion=1.4 \
+            -Dpackaging=jar \
+            -q
+
+      - name: License header check
+        run: bash tools/scripts/check_license.sh
+
+      - name: Compile
+        run: mvn -B compile
+
+      - name: Verify the H3 flag excludes the th3index package
+        run: |
+          mvn -B clean compile -DH3=OFF
+          for f in h3 demo; do
+            if [ -d "target/classes/org/mobilitydb/spark/$f" ]; then
+              echo "ERROR: $f package compiled despite -DH3=OFF"; exit 1
+            fi
+          done
+          mvn -B clean compile
+
+      - name: Unit tests
+        run: mvn -B test
+
+      - name: Native crash diagnostics
+        if: failure()
+        run: |
+          echo "===== JVM fatal error logs ====="
+          find . -name 'hs_err_pid*.log' -print -exec cat {} \; 2>/dev/null || true
+          echo "===== surefire dump streams ====="
+          for f in $(find . -path '*/surefire-reports/*' \( -name '*.dump' -o -name '*.dumpstream' -o -name '*-jvmRun*.dump' \) 2>/dev/null); do
+            echo "----- $f -----"; cat "$f" 2>/dev/null || true
+          done
+          echo "===== surefire reports + test stdout ====="
+          for f in $(find target/surefire-reports -name '*.txt' 2>/dev/null); do
+            echo "----- $f -----"; cat "$f" 2>/dev/null || true
+          done
+
+      - name: Package (fat jar)
+        run: mvn -B package -DskipTests
+
+      - name: Upload fat jar
+        uses: actions/upload-artifact@v4
+        with:
+          name: mobilityspark-spark.jar
+          path: target/*-spark.jar

.gitignore

@@ -3,14 +3,21 @@
 .project
 .settings/
 
-# Intellij
+# IntelliJ IDEA
 .idea/
 *.iml
 *.iws
+*.ipr
 
-# Mac
+# macOS
 .DS_Store
+**/.DS_Store
 
 # Maven
 log/
 target/
+
+# Large BerlinMOD benchmark data (generated locally — too large for GitHub)
+berlinmod/data/trips.csv
+dependency-reduced-pom.xml
+hs_err_pid*.log

LICENSE

@@ -0,0 +1,22 @@
+-------------------------------------------------------------------------------
+This MobilityDB code is provided under The PostgreSQL License.
+
+Copyright (c) 2020-2025, Université libre de Bruxelles and MobilityDB
+contributors
+
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose, without fee, and without a written agreement is
+hereby granted, provided that the above copyright notice and this paragraph and
+the following two paragraphs appear in all copies.
+
+IN NO EVENT SHALL UNIVERSITE LIBRE DE BRUXELLES BE LIABLE TO ANY PARTY FOR
+DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING
+LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION,
+EVEN IF UNIVERSITE LIBRE DE BRUXELLES HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.
+
+UNIVERSITE LIBRE DE BRUXELLES SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
+BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND
+UNIVERSITE LIBRE DE BRUXELLES HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE,
+SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

README.md

@@ -0,0 +1,175 @@
+MobilitySpark
+=============
+
+[MEOS (Mobility Engine, Open Source)](https://www.libmeos.org/) is a C library that enables the
+manipulation of temporal and spatiotemporal data based on
+[MobilityDB](https://mobilitydb.com/)'s data types and functions.
+
+MobilitySpark is a binding for [Apache Spark](https://spark.apache.org/) built on top of MEOS
+via [JMEOS](https://github.com/MobilityDB/JMEOS) (the Java binding for MEOS).
+
+<img src="doc/images/mobilitydb-logo.svg" width="200" alt="MobilityDB Logo" />
+
+The MobilityDB project is developed by the Computer & Decision Engineering Department of the
+[Université libre de Bruxelles](https://www.ulb.be/) (ULB) under the direction of
+[Prof. Esteban Zimányi](http://cs.ulb.ac.be/members/esteban/).
+ULB is an OGC Associate Member and member of the OGC Moving Feature Standard Working Group
+([MF-SWG](https://www.ogc.org/projects/groups/movfeatswg)).
+
+<img src="doc/images/OGC_Associate_Member_3DR.png" width="100" alt="OGC Associate Member Logo" />
+
+---
+
+## 1. Requirements
+
+- **Java 21** (OpenJDK or Temurin)
+- **Apache Maven 3.8+**
+- **Apache Spark 3.5** (provided at runtime; not needed to compile)
+- **JMEOS 1.4** — bundled in `libs/JMEOS-1.4.jar`
+  (the Java binding for MEOS 1.4; includes `libmeos.so` for Linux).
+  A small `MeosNative.java` supplement covers ~70 MEOS-1.4-renamed
+  symbols not yet in the released JAR.
+
+---
+
+## 2. Building MobilitySpark
+
+### Clone the repository
+
+```sh
+git clone https://github.com/MobilityDB/MobilitySpark.git
+cd MobilitySpark
+```
+
+### Compile
+
+```sh
+mvn compile
+```
+
+### Package (fat jar for `spark-submit`)
+
+```sh
+mvn package -DskipTests
+```
+
+The fat jar is written to `target/mobilityspark-0.1.0-SNAPSHOT-spark.jar`.
+
+---
+
+## 3. Using MobilitySpark
+
+### 3.1. Initialise MEOS and register UDFs
+
+```java
+SparkSession spark = SparkSession.builder().master("local[2]").getOrCreate();
+try (MobilitySparkSession ms = MobilitySparkSession.create(spark)) {
+    // All UDFs are now available in Spark SQL
+    spark.sql("SELECT atTime(trip, TIMESTAMP '2020-01-01 00:30:00') FROM trips").show();
+}
+```
+
+### 3.2. Available UDFs
+
+MobilitySpark covers **100% of MobilityDB's active addressable SQL surface**
+(858/858 functions) — the same audit methodology runs against MobilityDuck
+to keep both bindings in lockstep. See
+[`docs/parity-100.md`](docs/parity-100.md) for the achievement note,
+[`docs/parity-status.md`](docs/parity-status.md) for the per-section
+coverage report (regenerable via `python3 scripts/parity-audit.py`),
+and the comprehensive UDF inventory in [PR #5](https://github.com/MobilityDB/MobilitySpark/pull/5).
+
+A small sample (every UDF group in MobilityDB has a Spark equivalent):
+
+| UDF | Signature | Description |
+|-----|-----------|-------------|
+| `atTime` | `(STRING, TIMESTAMP) → STRING` | Restrict tgeompoint to a timestamp |
+| `eIntersects` | `(STRING, STRING) → BOOLEAN` | Ever intersects a geometry |
+| `nearestApproachDistance` | `(STRING, STRING) → DOUBLE` | Min distance at any common instant |
+| `eDwithin` | `(STRING, STRING, DOUBLE) → BOOLEAN` | Ever within given distance |
+| `spaceTimeTiles` | `(STRING, DOUBLE×3, STRING, STRING, TIMESTAMP, BOOLEAN) → ARRAY<STRING>` | Multidimensional tiling for parallel partitioning |
+| `tfloatSeqSetGaps` | `(ARRAY<STRING>, STRING, DOUBLE, STRING) → STRING` | Build a tfloat sequence-set with gap detection |
+
+All tgeompoint values are stored as **hex-WKB strings** (output of `temporal_as_hexwkb`).
+Geometry values are **hex-EWKB strings** (output of `geo_as_hexewkb`).
+Set / span / spanset / tbox / stbox values follow the same hex-encoding convention.
+
+### 3.3. Portable SQL (BerlinMOD benchmark)
+
+The SQL queries in `berlinmod/` use **named functions only** — no operator symbols — so the
+same file runs unchanged on MobilityDB (PostgreSQL), MobilityDuck (DuckDB), and MobilitySpark
+(Spark SQL). This is the portability contract defined in
+[Discussion #861](https://github.com/MobilityDB/MobilityDB/discussions/861).
+
+Run the demo:
+
+```sh
+spark-submit --class org.mobilitydb.spark.demo.BerlinMODDemo \
+    target/mobilityspark-0.1.0-SNAPSHOT-spark.jar
+```
+
+### 3.4. Sample queries
+
+Restrict a trip to a query instant:
+```sql
+SELECT atTime(trip, TIMESTAMP '2020-01-01 00:30:00+00') AS pos FROM Trips;
+```
+
+Find vehicles that ever passed a query point:
+```sql
+SELECT DISTINCT v.licence
+FROM Vehicles v JOIN Trips t ON t.vehId = v.vehId
+JOIN QueryPoints p ON eIntersects(t.trip, p.geom);
+```
+
+Minimum nearest-approach distance between vehicle pairs:
+```sql
+SELECT MIN(nearestApproachDistance(t1.trip, t2.trip)) AS min_dist
+FROM Trips t1 JOIN Trips t2 ON t1.vehId < t2.vehId;
+```
+
+---
+
+## 4. Running the tests
+
+Unit tests run without a Spark session (each UDF is a plain Java lambda):
+
+```sh
+mvn test
+```
+
+---
+
+## 5. Examples
+
+Numbered examples mirror the MEOS C examples (`meos/examples/01_hello_world.c`, etc.):
+
+| Class | Description |
+|-------|-------------|
+| `N01HelloWorld` | Round-trip a tgeompoint through hex-WKB |
+| `N03BerlinMOD` | BerlinMOD Q1/Q3/Q4/Q5/Q6 portable SQL |
+
+Run with:
+```sh
+spark-submit --class org.mobilitydb.spark.examples.N01HelloWorld \
+    target/mobilityspark-0.1.0-SNAPSHOT-spark.jar
+```
+
+---
+
+## 6. Project structure
+
+```
+src/main/java/org/mobilitydb/spark/
+  MobilitySparkSession.java   — entry point: init MEOS + register all UDFs
+  temporal/TemporalUDFs.java  — atTime and other time-axis UDFs
+  geo/GeoUDFs.java            — eIntersects, nearestApproachDistance, eDwithin
+  examples/N01HelloWorld.java — hello-world example
+  examples/N03BerlinMOD.java  — BerlinMOD portable SQL demo
+  demo/BerlinMODDemo.java     — Q1/Q3/Q4/Q5/Q6 implementation
+  udfs/TemporalUDFs.java      — convenience facade (registerAll)
+
+berlinmod/                    — portable SQL files (RFC #861)
+libs/JMEOS-1.3.jar            — JMEOS 1.3 (includes libmeos.so)
+tools/scripts/                — license header checker
+```