udf) {
+ return (s, a, b) -> { ensureReady(); return udf.call(s, a, b); };
+ }
+}
diff --git a/src/main/java/org/mobilitydb/spark/MobilitySparkSession.java b/src/main/java/org/mobilitydb/spark/MobilitySparkSession.java
new file mode 100644
index 00000000..7dba49b4
--- /dev/null
+++ b/src/main/java/org/mobilitydb/spark/MobilitySparkSession.java
@@ -0,0 +1,227 @@
+/*****************************************************************************
+ *
+ * This MobilityDB code is provided under The PostgreSQL License.
+ * Copyright (c) 2020-2026, 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.
+ *
+ *****************************************************************************/
+
+package org.mobilitydb.spark;
+
+import org.apache.spark.sql.SparkSession;
+import org.mobilitydb.spark.geo.DistanceUDFs;
+import org.mobilitydb.spark.geo.GeoAnalyticsUDFs;
+import org.mobilitydb.spark.geo.GeoUDFs;
+import org.mobilitydb.spark.geo.STBoxUDFs;
+import org.mobilitydb.spark.geo.StaticGeoUDFs;
+import org.mobilitydb.spark.geo.AlwaysSpatialRelsUDFs;
+import org.mobilitydb.spark.geo.GeoAffineUDFs;
+import org.mobilitydb.spark.geo.TempSpatialRelsUDFs;
+import org.mobilitydb.spark.geo.TPointSTBoxOpsUDFs;
+import org.mobilitydb.spark.temporal.AccessorAliasUDFs;
+import org.mobilitydb.spark.temporal.AccessorUDFs;
+import org.mobilitydb.spark.temporal.TileUDFs;
+import org.mobilitydb.spark.temporal.SeqSetGapsUDFs;
+import org.mobilitydb.spark.temporal.AnalyticsUDFs;
+import org.mobilitydb.spark.temporal.BoolOpsUDFs;
+import org.mobilitydb.spark.temporal.BucketUDFs;
+import org.mobilitydb.spark.temporal.ConstructorUDFs;
+import org.mobilitydb.spark.temporal.MathUDFs;
+import org.mobilitydb.spark.temporal.PosOpsUDFs;
+import org.mobilitydb.spark.temporal.PredicateUDFs;
+import org.mobilitydb.spark.temporal.SimilarityUDFs;
+import org.mobilitydb.spark.temporal.SpanAccessorUDFs;
+import org.mobilitydb.spark.temporal.SpanAlgebraUDFs;
+import org.mobilitydb.spark.temporal.SpanUDFs;
+import org.mobilitydb.spark.temporal.IOAliasUDFs;
+import org.mobilitydb.spark.temporal.SpansetOpsUDFs;
+import org.mobilitydb.spark.temporal.SetOpsUDFs;
+import org.mobilitydb.spark.temporal.SubtypeConstructorUDFs;
+import org.mobilitydb.spark.temporal.AggregateUDAFs;
+import org.mobilitydb.spark.temporal.MoreAccessorUDFs;
+import org.mobilitydb.spark.temporal.RestrictionUDFs;
+import org.mobilitydb.spark.temporal.TBoxOpsUDFs;
+import org.mobilitydb.spark.temporal.TBoxUDFs;
+import org.mobilitydb.spark.temporal.TemporalBoxOpsUDFs;
+import org.mobilitydb.spark.temporal.TemporalCompUDFs;
+import org.mobilitydb.spark.temporal.TTextUDFs;
+import org.mobilitydb.spark.temporal.TemporalUDFs;
+import org.mobilitydb.spark.temporal.TransformUDFs;
+
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+import static functions.GeneratedFunctions.*;
+
+/**
+ * Entry point for MobilitySpark.
+ *
+ * Initialises MEOS and registers all UDFs with the given SparkSession.
+ * Call {@link #create(SparkSession)} before running any temporal SQL,
+ * and {@link #close()} after (or use try-with-resources).
+ *
+ * {@code
+ * SparkSession spark = SparkSession.builder().master("local[2]").getOrCreate();
+ * try (MobilitySparkSession ms = MobilitySparkSession.create(spark)) {
+ * spark.sql("SELECT atTime(trip, instant) FROM trips").show();
+ * }
+ * }
+ */
+public final class MobilitySparkSession implements AutoCloseable {
+
+ private static final AtomicBoolean SRS_CSV_REGISTERED = new AtomicBoolean(false);
+
+ /**
+ * Fully-qualified registrar classes for the optional extended temporal-type
+ * families, in registration order. A family whose build flag is OFF
+ * (e.g. {@code -DCBUFFER=OFF}) is excluded from compilation, so its class is
+ * absent from the classpath and {@link #registerFamily} skips it — the Java
+ * analogue of the MEOS {@code #if CBUFFER} compile guard. The flag names
+ * mirror the MobilityDB/MEOS CMake options (CBUFFER / NPOINT / POSE / RGEO /
+ * H3).
+ */
+ private static final String[] EXTENDED_FAMILY_REGISTRARS = {
+ "org.mobilitydb.spark.h3.Th3IndexUDFs",
+ "org.mobilitydb.spark.cbuffer.CbufferUDFs",
+ "org.mobilitydb.spark.npoint.NpointUDFs",
+ "org.mobilitydb.spark.pose.PoseUDFs",
+ "org.mobilitydb.spark.rgeo.RgeoUDFs",
+ };
+
+ private MobilitySparkSession() {}
+
+ public static MobilitySparkSession create(SparkSession spark) {
+ meos_initialize();
+ meos_initialize_timezone("UTC");
+ meos_initialize_noexit_error_handler();
+ registerSpatialRefSys();
+ TemporalUDFs.registerAll(spark);
+ SpanUDFs.registerAll(spark);
+ GeoUDFs.registerAll(spark);
+ GeoAnalyticsUDFs.registerAll(spark);
+ StaticGeoUDFs.registerAll(spark);
+ DistanceUDFs.registerAll(spark);
+ ConstructorUDFs.registerAll(spark);
+ AccessorUDFs.registerAll(spark);
+ SpanAccessorUDFs.registerAll(spark);
+ SpanAlgebraUDFs.registerAll(spark);
+ SpansetOpsUDFs.registerAll(spark);
+ IOAliasUDFs.registerAll(spark);
+ SubtypeConstructorUDFs.registerAll(spark);
+ AccessorAliasUDFs.registerAll(spark);
+ TileUDFs.registerAll(spark);
+ SeqSetGapsUDFs.registerAll(spark);
+ SetOpsUDFs.registerAll(spark);
+ AnalyticsUDFs.registerAll(spark);
+ PredicateUDFs.registerAll(spark);
+ TBoxUDFs.registerAll(spark);
+ TBoxOpsUDFs.registerAll(spark);
+ TemporalCompUDFs.registerAll(spark);
+ TemporalBoxOpsUDFs.registerAll(spark);
+ TTextUDFs.registerAll(spark);
+ STBoxUDFs.registerAll(spark);
+ PosOpsUDFs.registerAll(spark);
+ MathUDFs.registerAll(spark);
+ BoolOpsUDFs.registerAll(spark);
+ BucketUDFs.registerAll(spark);
+ SimilarityUDFs.registerAll(spark);
+ TempSpatialRelsUDFs.registerAll(spark);
+ AlwaysSpatialRelsUDFs.registerAll(spark);
+ GeoAffineUDFs.registerAll(spark);
+ TPointSTBoxOpsUDFs.registerAll(spark);
+ MoreAccessorUDFs.registerAll(spark);
+ RestrictionUDFs.registerAll(spark);
+ TransformUDFs.registerAll(spark);
+ AggregateUDAFs.registerAll(spark);
+ // Comparison / ordering (= <> < <= > >= cmp hash) for all scalar,
+ // set, span and box types + generic temporal compare/hash.
+ org.mobilitydb.spark.temporal.ComparisonUDFs.registerAll(spark);
+ // Optional extended temporal-type families (h3 / cbuffer / npoint /
+ // pose / rgeo). Each family lives in its own package, included or
+ // excluded at build time by the matching flag (-DH3=OFF, -DCBUFFER=OFF,
+ // -DNPOINT=OFF, -DPOSE=OFF, -DRGEO=OFF), mirroring the MEOS/MobilityDB
+ // CMake options. An excluded package is dropped from compilation, so its
+ // registrar class is absent and registerFamily skips it with zero
+ // residue.
+ for (String family : EXTENDED_FAMILY_REGISTRARS) {
+ registerFamily(spark, family);
+ }
+ // SQL-surface parity gap UDFs (math, accessors, set/span/box algebra).
+ org.mobilitydb.spark.temporal.MathGapUDFs.registerAll(spark);
+ org.mobilitydb.spark.temporal.AccessorGapUDFs.registerAll(spark);
+ org.mobilitydb.spark.temporal.SetSpanGapUDFs.registerAll(spark);
+ // Portable bare-name operator dialect (RFC #920) — registered last
+ // so the 29 canonical bare names are the authoritative spelling.
+ org.mobilitydb.spark.portable.PortableOperatorAliasUDFs.registerAll(spark);
+ return new MobilitySparkSession();
+ }
+
+ /**
+ * Registers an optional family's UDFs by reflectively invoking its static
+ * {@code registerAll(SparkSession)} method. When the family was excluded at
+ * build time its class is absent from the classpath, so registration is
+ * skipped — the Java analogue of the MEOS {@code #if CBUFFER} compile guard.
+ * Any other reflective failure indicates a wiring error and is rethrown.
+ */
+ private static void registerFamily(SparkSession spark, String className) {
+ final Class cls;
+ try {
+ cls = Class.forName(className);
+ } catch (ClassNotFoundException excluded) {
+ return; // family disabled at build time (e.g. -DCBUFFER=OFF)
+ }
+ try {
+ cls.getMethod("registerAll", SparkSession.class).invoke(null, spark);
+ } catch (ReflectiveOperationException e) {
+ throw new IllegalStateException(
+ "Failed to register temporal family " + className, e);
+ }
+ }
+
+ /**
+ * Extracts the bundled spatial_ref_sys.csv to a temp file and registers
+ * it with MEOS so that geodetic coordinate operations (e.g. length on
+ * tgeogpoint) can look up SRID definitions without a PostGIS installation.
+ * Only runs once per JVM; subsequent calls are no-ops.
+ */
+ private static void registerSpatialRefSys() {
+ if (!SRS_CSV_REGISTERED.compareAndSet(false, true)) return;
+ try (InputStream in = MobilitySparkSession.class
+ .getResourceAsStream("/spatial_ref_sys.csv")) {
+ if (in == null) return;
+ File tmp = File.createTempFile("meos_spatial_ref_sys", ".csv");
+ tmp.deleteOnExit();
+ try (OutputStream out = new FileOutputStream(tmp)) {
+ byte[] buf = new byte[65536];
+ int n;
+ while ((n = in.read(buf)) > 0) out.write(buf, 0, n);
+ }
+ meos_set_spatial_ref_sys_csv(tmp.getAbsolutePath());
+ } catch (Exception ignored) {}
+ }
+
+ @Override
+ public void close() {
+ meos_finalize();
+ }
+}
diff --git a/src/main/java/org/mobilitydb/spark/cbuffer/CbufferUDFs.java b/src/main/java/org/mobilitydb/spark/cbuffer/CbufferUDFs.java
new file mode 100644
index 00000000..7f4060e2
--- /dev/null
+++ b/src/main/java/org/mobilitydb/spark/cbuffer/CbufferUDFs.java
@@ -0,0 +1,460 @@
+/*****************************************************************************
+ *
+ * This MobilityDB code is provided under The PostgreSQL License.
+ * Copyright (c) 2020-2026, 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.
+ *
+ *****************************************************************************/
+
+package org.mobilitydb.spark.cbuffer;
+
+import functions.GeneratedFunctions;
+import jnr.ffi.Pointer;
+import jnr.ffi.Runtime;
+import org.mobilitydb.spark.MeosMemory;
+import org.mobilitydb.spark.MeosNative;
+import org.mobilitydb.spark.MeosThread;
+import org.apache.spark.sql.SparkSession;
+import org.apache.spark.sql.api.java.UDF1;
+import org.apache.spark.sql.api.java.UDF2;
+import org.apache.spark.sql.api.java.UDF3;
+import org.apache.spark.sql.types.DataTypes;
+
+import java.sql.Timestamp;
+import java.util.HexFormat;
+import org.mobilitydb.spark.util.TimeUtil;
+
+/**
+ * Spark SQL UDFs for the circular-buffer (cbuffer / cbufferset / tcbuffer)
+ * family. JMEOS-1.4 ships no cbuffer symbols, so the base-type symbols are
+ * bound raw through {@link MeosNative} (verified present in
+ * {@code lib/libmeos.so} via {@code nm -D}); the temporal subtype reuses the
+ * generic {@code functions.*} Temporal helpers (a Temporal is a Temporal
+ * regardless of its element type — the hex-WKB carries the type tag).
+ *
+ * Storage convention (identical to every other family in this codebase):
+ * cbuffer / cbufferset → hex-WKB STRING (cbuffer_as_hexwkb / set_as_hexwkb)
+ * tcbuffer → hex-WKB STRING (temporal_as_hexwkb)
+ * geometry → WKT STRING (geo_from_text / geo_as_text)
+ *
+ * MEOS function authority: meos/include/meos_cbuffer.h.
+ */
+public final class CbufferUDFs {
+
+
+ private CbufferUDFs() {}
+
+ // interpType enum (meos.h): INTERP_NONE=0, DISCRETE=1, STEP=2, LINEAR=3
+ private static final int INTERP_LINEAR = 3;
+
+ private static long toPgEpochMicros(Timestamp ts) {
+ return (ts.getTime() - TimeUtil.PG_UNIX_EPOCH_OFFSET_MS) * 1000L;
+ }
+
+ // size_t out-param buffer for *_as_hexwkb (writes the byte count there).
+ private static Pointer sizeOut() {
+ return Runtime.getSystemRuntime().getMemoryManager().allocateDirect(8);
+ }
+
+ // ------------------------------------------------------------------
+ // Base-type circular buffer
+ // ------------------------------------------------------------------
+
+ // cbuffer(pointWkt STRING, radius DOUBLE) → STRING (cbuffer hex-WKB)
+ // MEOS: cbuffer_make(const GSERIALIZED *point, double radius) → Cbuffer *
+ public static final UDF2 cbuffer =
+ (pointWkt, radius) -> {
+ if (pointWkt == null || radius == null) return null;
+ MeosThread.ensureReady();
+ Pointer g = GeneratedFunctions.geo_from_text(pointWkt, 0);
+ if (g == null) return null;
+ try {
+ Pointer cb = MeosNative.INSTANCE.cbuffer_make(g, radius);
+ if (cb == null) return null;
+ try {
+ return MeosNative.INSTANCE.cbuffer_as_hexwkb(cb, (byte) 0, sizeOut());
+ } finally { MeosMemory.free(cb); }
+ } finally { MeosMemory.free(g); }
+ };
+
+ // point(cbuffer STRING) → STRING (geometry WKT)
+ // MEOS: cbuffer_point(const Cbuffer *cb) → GSERIALIZED *
+ public static final UDF1 point =
+ (cbHex) -> {
+ if (cbHex == null) return null;
+ MeosThread.ensureReady();
+ Pointer cb = MeosNative.INSTANCE.cbuffer_from_hexwkb(cbHex);
+ if (cb == null) return null;
+ try {
+ Pointer g = MeosNative.INSTANCE.cbuffer_point(cb);
+ if (g == null) return null;
+ try { return GeneratedFunctions.geo_as_text(g, 15); }
+ finally { MeosMemory.free(g); }
+ } finally { MeosMemory.free(cb); }
+ };
+
+ // radius(cbuffer STRING) → DOUBLE
+ // MEOS: cbuffer_radius(const Cbuffer *cb) → double
+ public static final UDF1 radius =
+ (cbHex) -> {
+ if (cbHex == null) return null;
+ MeosThread.ensureReady();
+ Pointer cb = MeosNative.INSTANCE.cbuffer_from_hexwkb(cbHex);
+ if (cb == null) return null;
+ try { return MeosNative.INSTANCE.cbuffer_radius(cb); }
+ finally { MeosMemory.free(cb); }
+ };
+
+ // ------------------------------------------------------------------
+ // Spatial relationships — cbuffer × cbuffer. MEOS returns int (-1 on
+ // error / undefined, 0 false, 1 true); map -1 → null.
+ // ------------------------------------------------------------------
+
+ private interface Rel { int call(Pointer a, Pointer b); }
+
+ private static Boolean rel2(String a, String b, Rel fn) {
+ if (a == null || b == null) return null;
+ MeosThread.ensureReady();
+ Pointer pa = MeosNative.INSTANCE.cbuffer_from_hexwkb(a);
+ if (pa == null) return null;
+ try {
+ Pointer pb = MeosNative.INSTANCE.cbuffer_from_hexwkb(b);
+ if (pb == null) return null;
+ try {
+ int r = fn.call(pa, pb);
+ return r < 0 ? null : (r != 0);
+ } finally { MeosMemory.free(pb); }
+ } finally { MeosMemory.free(pa); }
+ }
+
+ // cbufferContains(cbuffer, cbuffer) — MEOS: cbuffer_contains
+ public static final UDF2 cbufferContains =
+ (a, b) -> rel2(a, b, MeosNative.INSTANCE::cbuffer_contains);
+
+ // cbufferCovers(cbuffer, cbuffer) — MEOS: cbuffer_covers
+ public static final UDF2 cbufferCovers =
+ (a, b) -> rel2(a, b, MeosNative.INSTANCE::cbuffer_covers);
+
+ // cbufferDisjoint(cbuffer, cbuffer) — MEOS: cbuffer_disjoint
+ public static final UDF2 cbufferDisjoint =
+ (a, b) -> rel2(a, b, MeosNative.INSTANCE::cbuffer_disjoint);
+
+ // cbufferIntersects(cbuffer, cbuffer) — MEOS: cbuffer_intersects
+ public static final UDF2 cbufferIntersects =
+ (a, b) -> rel2(a, b, MeosNative.INSTANCE::cbuffer_intersects);
+
+ // cbufferTouches(cbuffer, cbuffer) — MEOS: cbuffer_touches
+ public static final UDF2 cbufferTouches =
+ (a, b) -> rel2(a, b, MeosNative.INSTANCE::cbuffer_touches);
+
+ // cbufferDwithin(cbuffer, cbuffer, dist DOUBLE) — MEOS: cbuffer_dwithin
+ public static final UDF3 cbufferDwithin =
+ (a, b, dist) -> {
+ if (a == null || b == null || dist == null) return null;
+ MeosThread.ensureReady();
+ Pointer pa = MeosNative.INSTANCE.cbuffer_from_hexwkb(a);
+ if (pa == null) return null;
+ try {
+ Pointer pb = MeosNative.INSTANCE.cbuffer_from_hexwkb(b);
+ if (pb == null) return null;
+ try {
+ int r = MeosNative.INSTANCE.cbuffer_dwithin(pa, pb, dist);
+ return r < 0 ? null : (r != 0);
+ } finally { MeosMemory.free(pb); }
+ } finally { MeosMemory.free(pa); }
+ };
+
+ // cbufferSame(cbuffer, cbuffer) → BOOLEAN — MEOS: cbuffer_same (returns bool)
+ public static final UDF2 cbufferSame =
+ (a, b) -> {
+ if (a == null || b == null) return null;
+ MeosThread.ensureReady();
+ Pointer pa = MeosNative.INSTANCE.cbuffer_from_hexwkb(a);
+ if (pa == null) return null;
+ try {
+ Pointer pb = MeosNative.INSTANCE.cbuffer_from_hexwkb(b);
+ if (pb == null) return null;
+ try { return MeosNative.INSTANCE.cbuffer_same(pa, pb); }
+ finally { MeosMemory.free(pb); }
+ } finally { MeosMemory.free(pa); }
+ };
+
+ // ------------------------------------------------------------------
+ // cbufferset I/O — generic Set helpers (the WKB carries the element type)
+ // ------------------------------------------------------------------
+
+ // cbuffersetFromHexWKB(hex STRING) → STRING — MEOS: set_from_hexwkb (generic)
+ public static final UDF1 cbuffersetFromHexWKB =
+ (hex) -> {
+ if (hex == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = GeneratedFunctions.set_from_hexwkb(hex);
+ if (p == null) return null;
+ try { return GeneratedFunctions.set_as_hexwkb(p, (byte) 0); }
+ finally { MeosMemory.free(p); }
+ };
+
+ // cbuffersetFromBinary(bytes BINARY) → STRING — hex round-trip (generic)
+ public static final UDF1 cbuffersetFromBinary =
+ (bytes) -> {
+ if (bytes == null) return null;
+ MeosThread.ensureReady();
+ String hex = HexFormat.of().formatHex(bytes).toUpperCase();
+ Pointer p = GeneratedFunctions.set_from_hexwkb(hex);
+ if (p == null) return null;
+ try { return GeneratedFunctions.set_as_hexwkb(p, (byte) 0); }
+ finally { MeosMemory.free(p); }
+ };
+
+ // ------------------------------------------------------------------
+ // Temporal circular buffer (tcbuffer) — generic Temporal helpers
+ // ------------------------------------------------------------------
+
+ // tcbuffer(tgeompoint STRING, tfloat STRING) → STRING (tcbuffer hex-WKB)
+ // The (base,time) and tpoint/tfloat ctor overloads collapse to this one
+ // most-useful form (MEOS: tcbuffer_make(const Temporal *, const Temporal *)).
+ public static final UDF2 tcbuffer =
+ (tpointHex, tfloatHex) -> {
+ if (tpointHex == null || tfloatHex == null) return null;
+ MeosThread.ensureReady();
+ Pointer tp = GeneratedFunctions.temporal_from_hexwkb(tpointHex);
+ if (tp == null) return null;
+ try {
+ Pointer tf = GeneratedFunctions.temporal_from_hexwkb(tfloatHex);
+ if (tf == null) return null;
+ try {
+ Pointer r = MeosNative.INSTANCE.tcbuffer_make(tp, tf);
+ if (r == null) return null;
+ try { return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0); }
+ finally { MeosMemory.free(r); }
+ } finally { MeosMemory.free(tf); }
+ } finally { MeosMemory.free(tp); }
+ };
+
+ // tcbufferInst(cbuffer STRING, ts TIMESTAMP) → STRING (TInstant hex-WKB)
+ // MEOS: tcbuffer_make on a single-instant tpoint/tfloat pair is overkill;
+ // the SQL tcbufferInst builds a TInstant from a cbuffer value + timestamp.
+ // The cbuffer value decomposes into its point + radius which we lift to a
+ // tgeompoint instant and tfloat instant, then tcbuffer_make.
+ public static final UDF2 tcbufferInst =
+ (cbHex, ts) -> {
+ if (cbHex == null || ts == null) return null;
+ MeosThread.ensureReady();
+ Pointer cb = MeosNative.INSTANCE.cbuffer_from_hexwkb(cbHex);
+ if (cb == null) return null;
+ try {
+ Pointer g = MeosNative.INSTANCE.cbuffer_point(cb);
+ if (g == null) return null;
+ double rad = MeosNative.INSTANCE.cbuffer_radius(cb);
+ long micros = toPgEpochMicros(ts);
+ try {
+ Pointer tp = MeosNative.INSTANCE.tgeoinst_make(g, micros);
+ if (tp == null) return null;
+ try {
+ Pointer tf = GeneratedFunctions.tfloatinst_make(rad,
+ java.time.Instant.ofEpochMilli(ts.getTime())
+ .atOffset(java.time.ZoneOffset.UTC));
+ if (tf == null) return null;
+ try {
+ Pointer r = MeosNative.INSTANCE.tcbuffer_make(tp, tf);
+ if (r == null) return null;
+ try { return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0); }
+ finally { MeosMemory.free(r); }
+ } finally { MeosMemory.free(tf); }
+ } finally { MeosMemory.free(tp); }
+ } finally { MeosMemory.free(g); }
+ } finally { MeosMemory.free(cb); }
+ };
+
+ private static UDF1 temporalRoundtrip() {
+ return hex -> {
+ if (hex == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = GeneratedFunctions.temporal_from_hexwkb(hex);
+ if (p == null) return null;
+ try { return GeneratedFunctions.temporal_as_hexwkb(p, (byte) 0); }
+ finally { MeosMemory.free(p); }
+ };
+ }
+
+ private static UDF1 temporalFromBinary() {
+ return bytes -> {
+ if (bytes == null) return null;
+ MeosThread.ensureReady();
+ String hex = HexFormat.of().formatHex(bytes).toUpperCase();
+ Pointer p = GeneratedFunctions.temporal_from_hexwkb(hex);
+ if (p == null) return null;
+ try { return GeneratedFunctions.temporal_as_hexwkb(p, (byte) 0); }
+ finally { MeosMemory.free(p); }
+ };
+ }
+
+ // tcbuffer text constructor (FromText / FromEWKT) — MEOS: tcbuffer_in
+ public static final UDF1 tcbufferFromText =
+ (wkt) -> {
+ if (wkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = MeosNative.INSTANCE.tcbuffer_in(wkt);
+ if (p == null) return null;
+ try { return GeneratedFunctions.temporal_as_hexwkb(p, (byte) 0); }
+ finally { MeosMemory.free(p); }
+ };
+ public static final UDF1 tcbufferFromEWKT = tcbufferFromText;
+
+ public static final UDF1 tcbufferFromHexEWKB = temporalRoundtrip();
+ public static final UDF1 tcbufferFromBinary = temporalFromBinary();
+ public static final UDF1 tcbufferFromEWKB = temporalFromBinary();
+
+ // Subtype conversion aliases (Seq / SeqSet) — generic conversion, linear.
+ public static final UDF1 tcbufferSeq =
+ (hex) -> {
+ if (hex == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = GeneratedFunctions.temporal_from_hexwkb(hex);
+ if (p == null) return null;
+ try {
+ Pointer r = GeneratedFunctions.temporal_to_tsequence(p, INTERP_LINEAR);
+ if (r == null) return null;
+ try { return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0); }
+ finally { MeosMemory.free(r); }
+ } finally { MeosMemory.free(p); }
+ };
+
+ public static final UDF1 tcbufferSeqSet =
+ (hex) -> {
+ if (hex == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = GeneratedFunctions.temporal_from_hexwkb(hex);
+ if (p == null) return null;
+ try {
+ Pointer r = GeneratedFunctions.temporal_to_tsequenceset(p, INTERP_LINEAR);
+ if (r == null) return null;
+ try { return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0); }
+ finally { MeosMemory.free(r); }
+ } finally { MeosMemory.free(p); }
+ };
+
+ // tcbufferSeqSetGaps(tcbuffer[], maxt) — generic tsequenceset_make_gaps,
+
+ public static final UDF2 tcbufferSeqSetGaps =
+ (instants, maxt) -> {
+ if (instants == null || instants.length == 0) return null;
+ MeosThread.ensureReady();
+ int n = instants.length;
+ Pointer[] insts = new Pointer[n];
+ try {
+ for (int i = 0; i < n; i++) {
+ if (instants[i] == null) return null;
+ insts[i] = GeneratedFunctions.temporal_from_hexwkb(instants[i]);
+ if (insts[i] == null) return null;
+ }
+ Pointer buf = Runtime.getSystemRuntime().getMemoryManager()
+ .allocateDirect(8L * n);
+ for (int i = 0; i < n; i++) {
+ buf.putAddress(i * 8L, insts[i].address());
+ }
+ Pointer mt = (maxt == null) ? null : GeneratedFunctions.pg_interval_in(maxt, -1);
+ try {
+ Pointer r = GeneratedFunctions.tsequenceset_make_gaps(buf, n,
+ INTERP_LINEAR, mt, -1.0);
+ if (r == null) return null;
+ try { return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0); }
+ finally { MeosMemory.free(r); }
+ } finally {
+ if (mt != null) MeosMemory.free(mt);
+ }
+ } finally {
+ for (Pointer p : insts) {
+ if (p != null) MeosMemory.free(p);
+ }
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // tcbuffer accessors — points / radius (return Set, hex-WKB string)
+ // ------------------------------------------------------------------
+
+ // points(tcbuffer STRING) → STRING (geomset hex-WKB)
+ // MEOS: tcbuffer_points(const Temporal *) → Set *
+ public static final UDF1 points =
+ (hex) -> {
+ if (hex == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = GeneratedFunctions.temporal_from_hexwkb(hex);
+ if (p == null) return null;
+ try {
+ Pointer s = MeosNative.INSTANCE.tcbuffer_points(p);
+ if (s == null) return null;
+ try { return GeneratedFunctions.set_as_hexwkb(s, (byte) 0); }
+ finally { MeosMemory.free(s); }
+ } finally { MeosMemory.free(p); }
+ };
+
+ // tcbufferRadius(tcbuffer STRING) → STRING (floatset hex-WKB)
+ // MEOS: tcbuffer_radius(const Temporal *) → Set *
+ // Registered under the bare name `radius` (audit matches by name; one
+ // `radius` registration covers both the cbuffer-scalar and tcbuffer
+ // sections). The cbuffer-scalar `radius` above returns DOUBLE; this
+ // temporal form is exposed as `tcbufferRadius` so both coexist.
+ public static final UDF1 tcbufferRadius =
+ (hex) -> {
+ if (hex == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = GeneratedFunctions.temporal_from_hexwkb(hex);
+ if (p == null) return null;
+ try {
+ Pointer s = MeosNative.INSTANCE.tcbuffer_radius(p);
+ if (s == null) return null;
+ try { return GeneratedFunctions.set_as_hexwkb(s, (byte) 0); }
+ finally { MeosMemory.free(s); }
+ } finally { MeosMemory.free(p); }
+ };
+
+ public static void registerAll(SparkSession spark) {
+ // Base-type circular buffer
+ spark.udf().register("cbuffer", cbuffer, DataTypes.StringType);
+ spark.udf().register("point", point, DataTypes.StringType);
+ spark.udf().register("radius", radius, DataTypes.DoubleType);
+ // Spatial relationships
+ spark.udf().register("cbufferContains", cbufferContains, DataTypes.BooleanType);
+ spark.udf().register("cbufferCovers", cbufferCovers, DataTypes.BooleanType);
+ spark.udf().register("cbufferDisjoint", cbufferDisjoint, DataTypes.BooleanType);
+ spark.udf().register("cbufferIntersects", cbufferIntersects, DataTypes.BooleanType);
+ spark.udf().register("cbufferTouches", cbufferTouches, DataTypes.BooleanType);
+ spark.udf().register("cbufferDwithin", cbufferDwithin, DataTypes.BooleanType);
+ spark.udf().register("cbufferSame", cbufferSame, DataTypes.BooleanType);
+ // cbufferset I/O
+ spark.udf().register("cbuffersetFromHexWKB", cbuffersetFromHexWKB, DataTypes.StringType);
+ spark.udf().register("cbuffersetFromBinary", cbuffersetFromBinary, DataTypes.StringType);
+ // Temporal circular buffer
+ spark.udf().register("tcbuffer", tcbuffer, DataTypes.StringType);
+ spark.udf().register("tcbufferInst", tcbufferInst, DataTypes.StringType);
+ spark.udf().register("tcbufferFromText", tcbufferFromText, DataTypes.StringType);
+ spark.udf().register("tcbufferFromEWKT", tcbufferFromEWKT, DataTypes.StringType);
+ spark.udf().register("tcbufferFromHexEWKB", tcbufferFromHexEWKB, DataTypes.StringType);
+ spark.udf().register("tcbufferFromBinary", tcbufferFromBinary, DataTypes.StringType);
+ spark.udf().register("tcbufferFromEWKB", tcbufferFromEWKB, DataTypes.StringType);
+ spark.udf().register("tcbufferSeq", tcbufferSeq, DataTypes.StringType);
+ spark.udf().register("tcbufferSeqSet", tcbufferSeqSet, DataTypes.StringType);
+ spark.udf().register("tcbufferSeqSetGaps", tcbufferSeqSetGaps, DataTypes.StringType);
+ spark.udf().register("points", points, DataTypes.StringType);
+ spark.udf().register("tcbufferRadius", tcbufferRadius, DataTypes.StringType);
+ }
+}
diff --git a/src/main/java/org/mobilitydb/spark/demo/BerlinMODBench.java b/src/main/java/org/mobilitydb/spark/demo/BerlinMODBench.java
new file mode 100644
index 00000000..504971bc
--- /dev/null
+++ b/src/main/java/org/mobilitydb/spark/demo/BerlinMODBench.java
@@ -0,0 +1,502 @@
+/*****************************************************************************
+ *
+ * This MobilityDB code is provided under The PostgreSQL License.
+ * Copyright (c) 2020-2026, 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 retained 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, INCIDENTAL, SPECIAL, EXEMPLARY, 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.
+ *
+ *****************************************************************************/
+
+package org.mobilitydb.spark.demo;
+
+import org.apache.spark.sql.SparkSession;
+import org.mobilitydb.spark.MobilitySparkSession;
+
+import java.io.IOException;
+import java.io.PrintWriter;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+/**
+ * BerlinMOD benchmark runner for MobilitySpark.
+ *
+ * Loads the shared CSV dataset once (caching tables in Spark), then runs each
+ * BerlinMOD portable SQL query {@code runs} times and records wall-clock time
+ * per run. Writes a JSON file with per-query timing lists, compatible with
+ * the bench/report.py report generator.
+ *
+ * Usage:
+ *
+ * spark-submit --class org.mobilitydb.spark.demo.BerlinMODBench \
+ * target/mobilityspark-*-spark.jar data_dir output.json [runs]
+ *
+ *
+ * Args:
+ * data_dir — directory containing vehicles.csv, trips.csv, …
+ * output — path to write the timing JSON file
+ * runs — number of timed runs per query (default: 3)
+ *
+ * The SQL files are read from the same directory that contains this JAR's
+ * class path. If running from the repository root, pass
+ * {@code berlinmod/} as the SQL directory via the system property
+ * {@code berlinmod.sql.dir} (default: {@code berlinmod/}).
+ */
+public final class BerlinMODBench {
+
+ private static final String[] QUERY_ORDER = {
+ "q01", "q02", "q03", "q04", "q05", "q06", "q07", "q08", "qrt",
+ "q09", "q10", "q11", "q12", "q13", "q14", "q15", "q16", "q17"
+ };
+
+ public static void main(String[] args) throws Exception {
+ if (args.length < 2) {
+ System.err.println("Usage: BerlinMODBench [runs] [queries]");
+ System.err.println(" queries — page-range syntax: '3', '2-5', 'q02', 'q02-q05', 'qrt'");
+ System.exit(1);
+ }
+ String dataDir = args[0];
+ String outputPath = args[1];
+ int runs = args.length >= 3 ? Integer.parseInt(args[2]) : 3;
+ String queryRange = args.length >= 4 ? args[3] : null;
+
+ // Resolve which queries to run from the page-range argument.
+ // Accepted forms: "3", "2-5", "q02", "q02-q05", "qrt", "q04,qrt,q07"
+ List queryList = resolveQueryRange(queryRange);
+
+ // SQL files live next to the berlinmod/data/ directory
+ String sqlDir = Paths.get(dataDir).getParent() != null
+ ? Paths.get(dataDir).getParent().toString()
+ : ".";
+ // Allow override via system property
+ sqlDir = System.getProperty("berlinmod.sql.dir", sqlDir);
+
+ SparkSession spark = SparkSession.builder()
+ .appName("MobilitySpark — BerlinMOD Benchmark")
+ .config("spark.sql.legacy.createHiveTableByDefault", "false")
+ .getOrCreate();
+ spark.sparkContext().setLogLevel("WARN");
+
+ System.out.println("=== BerlinMODBench: " + runs + " run(s) per query ===");
+
+ // Pre-load any existing results so a partial run can be resumed
+ // without losing previously collected timings.
+ Map> timings = loadExistingTimings(outputPath);
+ String version = "unknown";
+
+ try (MobilitySparkSession ms = MobilitySparkSession.create(spark)) {
+ // Register BerlinMOD-specific UDFs (length, bboxOverlaps, valueAtTimestamp, etc.)
+ BerlinMODUDFs.registerAll(spark);
+
+ // Load and cache all tables — loading time is NOT in the query timings
+ System.out.println("=== Loading data from: " + dataDir + " ===");
+ BerlinMODDemo.loadFromCsvPublic(spark, dataDir);
+
+ // Materialise the th3index column on Trips at load time. Each trip's
+ // tgeompoint is converted to a temporal H3 cell sequence at the
+ // chosen resolution (default 7 ≈ 1.2 km cells). The trip_h3 column
+ // is used by the portable BerlinMOD SQL (Q4 / Q5 / Q6 / Q10) as a
+ // spatial prefilter — a cheap cell-membership test that runs before
+ // the expensive eIntersects / nearestApproachDistance / eDwithin /
+ // tDwithin calls. All three benchmarked platforms compute the
+ // column at load time so the comparison is apples-to-apples; on
+ // PostgreSQL the load script also adds a GiST index on the column
+ // so the prefilter becomes a true index seek.
+ //
+ // Disabled when berlinmod.bench.th3index.disable=true so before-vs-
+ // after measurement is reproducible without a rebuild — note that
+ // disabling it makes the prefilter expressions in the portable SQL
+ // reference a non-existent column, so use this only with a custom
+ // SQL set that omits the prefilter.
+ //
+ // If the source CSV already carries a trip_h3 column (as produced
+ // by berlinmod_portability_export() in MobilityDB-BerlinMOD), drop
+ // it first so we can rematerialise at our chosen resolution — this
+ // guarantees a consistent resolution across all three platforms
+ // regardless of how the CSV was produced.
+ // The tgeompointToTh3Index UDF (registered by Th3IndexUDFs via
+ // MobilitySparkSession) materialises the column from each trip's
+ // tgeompoint over the H3 public surface. Default resolution 7
+ // (~1.2 km cells). This block is a no-op unless
+ // berlinmod.bench.th3index.enable=true is set, so the before-vs-
+ // after prefilter measurement is reproducible without a rebuild.
+ {
+ int res = Integer.getInteger("berlinmod.bench.th3index.resolution", 7);
+ System.out.println("=== Materialising trip_h3 (res " + res + ") + trip_bbox prefilter columns ===");
+ String[] cols = spark.table("Trips").schema().fieldNames();
+ String selectCols = java.util.Arrays.stream(cols)
+ .filter(c -> !"trip_h3".equalsIgnoreCase(c) && !"trip_bbox".equalsIgnoreCase(c))
+ .collect(Collectors.joining(", "));
+ // The trip_h3 (temporal H3 cell index) and trip_bbox (STBox of
+ // the whole trip) columns are the cross-join spatial prefilter
+ // mechanism: a cheap cell / bounding-box test that runs before
+ // the expensive eIntersects / nearestApproachDistance / tDwithin
+ // calls. Materialising them once per trip means the prefilter
+ // never re-parses the full multi-thousand-instant trip per pair.
+ // Materialise via a Dataset rather than CREATE OR REPLACE
+ // TEMPORARY VIEW Trips AS SELECT ... FROM Trips: the latter
+ // trips Spark's checkCyclicViewReference (the new view names
+ // itself in its own definition) and aborts with RECURSIVE_VIEW.
+ // Reading the current Trips into a Dataset first resolves the
+ // source plan, then the registration replaces the view atomically.
+ spark.sql(
+ "SELECT " + selectCols + ", " +
+ " tgeompointToTh3Index(trip, " + res + ") AS trip_h3, " +
+ " expandSpace(trip, 0.0) AS trip_bbox " +
+ "FROM Trips"
+ ).createOrReplaceTempView("Trips");
+ }
+
+ spark.catalog().cacheTable("Vehicles");
+ spark.catalog().cacheTable("Trips");
+ spark.catalog().cacheTable("QueryLicences");
+ spark.catalog().cacheTable("QueryInstants");
+ spark.catalog().cacheTable("QueryPoints");
+ spark.catalog().cacheTable("QueryRegions");
+ spark.catalog().cacheTable("QueryPeriods");
+ // Warm up the cache
+ spark.sql("SELECT count(*) FROM Trips").collect();
+ System.out.println(" done.");
+
+ // Try to capture version
+ try {
+ version = spark.sql("SELECT mobilitydb_version()")
+ .collectAsList().get(0).getString(0)
+ + " on Spark " + spark.version();
+ } catch (Exception e) {
+ version = "MobilitySpark on Spark " + spark.version();
+ }
+
+ // Time each query — flush results after every query so a crash
+ // still leaves a valid JSON file with the timings collected so far.
+ //
+ // Single canonical source: berlinmod/queries.sql holds every query,
+ // each delimited by a `-- @query ` marker. All three runners
+ // (PostgreSQL, DuckDB, Spark) split the same file, so the SQL cannot
+ // drift between platforms. Spark applies preprocessForSpark as a
+ // dialect transform; the query intent is identical across engines.
+ Map queries = splitQueries(
+ Files.readString(Paths.get(sqlDir, "queries.sql")));
+ for (String q : queryList) {
+ String raw = queries.get(q);
+ if (raw == null) {
+ System.out.printf(" [skip] %s — not in queries.sql%n", q);
+ continue;
+ }
+ String sql = preprocessForSpark(stripComments(raw));
+ List qTimes = new ArrayList<>(runs);
+
+ System.out.printf(" timing %-6s: ", q);
+ for (int run = 0; run < runs; run++) {
+ try {
+ long t0 = System.currentTimeMillis();
+ // Force full materialisation of every output column via the noop
+ // sink. count() alone lets Spark prune projection-only expressions
+ // (e.g. minDistance(arr, arr) in Q5), which would mistime the query.
+ spark.sql(sql).write().format("noop").mode("overwrite").save();
+ long elapsed = System.currentTimeMillis() - t0;
+ qTimes.add(elapsed);
+ System.out.printf("%d ", elapsed);
+ } catch (Exception e) {
+ String msg = e.getMessage();
+ if (msg != null) msg = msg.split("\n")[0].substring(0, Math.min(120, msg.split("\n")[0].length()));
+ System.out.printf("[err:%s: %s] ", e.getClass().getSimpleName(), msg);
+ }
+ }
+ System.out.println("ms");
+ if (!qTimes.isEmpty()) {
+ timings.put(q, qTimes);
+ writeJson(outputPath, version, dataDir, runs, timings);
+ }
+ }
+ } finally {
+ spark.stop();
+ }
+
+ System.out.println("=== Results written to " + outputPath + " ===");
+ }
+
+ /**
+ * Split the canonical queries.sql into id → SQL, keyed by the
+ * {@code -- @query } markers. The text before the first marker (the
+ * file header) is discarded. Insertion order is preserved.
+ */
+ private static Map splitQueries(String text) {
+ Map out = new LinkedHashMap<>();
+ String id = null;
+ StringBuilder body = new StringBuilder();
+ for (String line : text.split("\n")) {
+ String t = line.stripLeading();
+ if (t.startsWith("-- @query")) {
+ if (id != null) out.put(id, body.toString());
+ id = t.substring("-- @query".length()).trim();
+ body.setLength(0);
+ } else if (id != null) {
+ body.append(line).append('\n');
+ }
+ }
+ if (id != null) out.put(id, body.toString());
+ return out;
+ }
+
+ /** Strip leading-comment lines so Spark SQL doesn't choke on them. */
+ private static String stripComments(String sql) {
+ return Stream.of(sql.split("\n"))
+ .filter(line -> !line.stripLeading().startsWith("--"))
+ .collect(Collectors.joining("\n"))
+ .replaceAll(";\\s*$", "");
+ }
+
+ /**
+ * Rewrite portable BerlinMOD SQL to Spark-compatible SQL.
+ *
+ * Spark SQL cannot define custom infix operators, so the portable SQL's
+ * {@code &&} bounding-box overlap operator and PostgreSQL-specific cast
+ * syntax ({@code ::numeric}) must be rewritten before passing to
+ * {@link SparkSession#sql}. Transformations applied in order:
+ *
+ * - {@code stbox(geom, t)} → {@code geoTimeStbox(geom, t)} (2-arg form only)
+ * - {@code expr && expr2} → {@code bboxOverlaps(expr, expr2)} (per line)
+ * - {@code ::numeric} → removed (Spark ROUND accepts DOUBLE directly)
+ * - {@code ST_Contains(} → {@code geomContains(}
+ * - th3index prefilter injection for {@code eIntersects(t., p.)}
+ * on point geometries — see {@link #injectTh3IndexPrefilter}.
+ *
+ */
+ private static String preprocessForSpark(String sql) {
+ // 1. Replace 2-arg stbox(geom, time_or_period) with geoTimeStbox(geom, time_or_period).
+ // The \b word boundary ensures stboxHasx etc. are not affected.
+ // The [^,)]+ / [^)]+ pattern matches exactly 2 args (comma present).
+ sql = sql.replaceAll("\\bstbox\\(([^,)]+),\\s*([^)]+)\\)", "geoTimeStbox($1, $2)");
+
+ // 2a. Route the spatial bounding-box prefilter to the materialised
+ // trip_bbox (STBox) column so the cross-join never re-parses the
+ // full trip. expandSpace accepts an STBox hex directly, so feed it
+ // the precomputed trip_bbox (strictly inside expandSpace(...)).
+ sql = sql.replaceAll("expandSpace\\(\\s*(\\w+)\\.trip\\s*,", "expandSpace($1.trip_bbox,");
+ // Spatial `trip && ` (geoTimeStbox / expandSpace RHS) →
+ // stboxOverlaps over the precomputed trip_bbox column.
+ sql = sql.replaceAll("(\\w+)\\.trip\\s+&&\\s+((?:geoTimeStbox|expandSpace)\\(.+)",
+ "stboxOverlaps($1.trip_bbox, $2)");
+
+ // 2b. Any remaining bounding-box overlap operator && (temporal-span
+ // RHS, e.g. trip && period) → the bboxOverlaps UDF on the trip.
+ sql = sql.replaceAll("([\\w]+\\.[\\w]+)\\s+&&\\s+(.+)", "bboxOverlaps($1, $2)");
+
+ // 3. Remove PostgreSQL :: cast to numeric (Spark ROUND handles DOUBLE natively).
+ sql = sql.replace("::numeric", "");
+
+ // 4. Replace PostGIS ST_Contains with the registered geomContains UDF.
+ sql = sql.replace("ST_Contains(", "geomContains(");
+
+ // 5. Normalise the th3index set-membership prefilter spelling to the
+ // registered camelCase UDF name.
+ sql = sql.replace("everIntersectsH3IndexSet_Th3Index", "everIntersectsH3IndexSetTh3Index");
+
+ // 6. Resolve the cross-join spatial prefilter through the materialised
+ // trip_bbox (STBox) column. The th3index cell prefilter is a true
+ // index seek on PostgreSQL / DuckDB, but in Spark's string-storage
+ // model the trip_h3 sequence is re-parsed per candidate pair; the
+ // STBox bounding-box overlap is the cheap, coordinate-system-agnostic
+ // equivalent that the same dialect already uses via the `&&` operator
+ // (Q9 / Q11 / Q16). Each rewrite is a sound spatial superset filter:
+ // the exact eIntersects / nearestApproachDistance still runs on the
+ // surviving pairs, so results are unchanged.
+ // everIntersectsH3IndexSetTh3Index(geoToH3IndexSet(g, r), t.trip_h3)
+ // → stboxOverlaps(t.trip_bbox, geoToStbox(g))
+ sql = sql.replaceAll(
+ "everIntersectsH3IndexSetTh3Index\\(geoToH3IndexSet\\(([^,]+),\\s*\\d+\\),\\s*(\\w+)\\.trip_h3\\)",
+ "stboxOverlaps($2.trip_bbox, geoToStbox($1))");
+ // COALESCE(everEqH3IndexTh3Index(geomToH3Cell(g, r), t.trip_h3), TRUE)
+ // → stboxOverlaps(t.trip_bbox, geoToStbox(g))
+ sql = sql.replaceAll(
+ "COALESCE\\(everEqH3IndexTh3Index\\(geomToH3Cell\\(([^,]+),\\s*\\d+\\),\\s*(\\w+)\\.trip_h3\\),\\s*TRUE\\)",
+ "stboxOverlaps($2.trip_bbox, geoToStbox($1))");
+ // everEqTh3IndexTh3Index(t1.trip_h3, t2.trip_h3)
+ // → stboxOverlaps(t1.trip_bbox, t2.trip_bbox)
+ sql = sql.replaceAll(
+ "everEqTh3IndexTh3Index\\((\\w+)\\.trip_h3,\\s*(\\w+)\\.trip_h3\\)",
+ "stboxOverlaps($1.trip_bbox, $2.trip_bbox)");
+
+ return sql;
+ }
+
+ /** Write a JSON result file compatible with report.py. */
+ private static void writeJson(String outputPath,
+ String version,
+ String dataDir,
+ int runs,
+ Map> timings) throws IOException {
+ // Count trips and vehicles from the timing data indirectly — just
+ // report what we know from disk.
+ long trips = countLines(Paths.get(dataDir, "trips.csv")) - 1; // minus header
+ long vehicles = countLines(Paths.get(dataDir, "vehicles.csv")) - 1;
+
+ StringBuilder sb = new StringBuilder();
+ sb.append("{\n");
+ sb.append(" \"platform\": \"mobilityspark\",\n");
+ sb.append(" \"version\": \"").append(escapeJson(version)).append("\",\n");
+ sb.append(" \"tier\": 1,\n");
+ sb.append(" \"data_vehicles\": ").append(vehicles).append(",\n");
+ sb.append(" \"data_trips\": ").append(trips).append(",\n");
+ sb.append(" \"runs\": ").append(runs).append(",\n");
+ sb.append(" \"timestamp\": \"").append(Instant.now().toString()).append("\",\n");
+ sb.append(" \"queries\": {\n");
+
+ // Emit in canonical QUERY_ORDER; any extra keys follow at the end.
+ List order = new ArrayList<>(java.util.Arrays.asList(QUERY_ORDER));
+ for (String k : timings.keySet()) { if (!order.contains(k)) order.add(k); }
+
+ boolean firstQ = true;
+ for (String q : order) {
+ if (!timings.containsKey(q)) continue;
+ if (!firstQ) sb.append(",\n");
+ firstQ = false;
+ sb.append(" \"").append(q).append("\": [");
+ sb.append(timings.get(q).stream()
+ .map(String::valueOf)
+ .collect(Collectors.joining(", ")));
+ sb.append("]");
+ }
+ sb.append("\n }\n}\n");
+
+ // Atomic write: write to a .tmp file then rename so a crash mid-write
+ // never leaves a truncated JSON (the previous file stays intact).
+ Path dest = Paths.get(outputPath);
+ Path tmp = dest.resolveSibling(dest.getFileName() + ".tmp");
+ Files.writeString(tmp, sb.toString());
+ Files.move(tmp, dest, java.nio.file.StandardCopyOption.REPLACE_EXISTING,
+ java.nio.file.StandardCopyOption.ATOMIC_MOVE);
+ }
+
+ private static long countLines(Path path) {
+ try (Stream lines = Files.lines(path)) {
+ return lines.count();
+ } catch (IOException e) {
+ return 0;
+ }
+ }
+
+ private static String escapeJson(String s) {
+ return s.replace("\\", "\\\\").replace("\"", "\\\"");
+ }
+
+ /**
+ * Load timings from an existing JSON results file, returning them in
+ * canonical QUERY_ORDER. Returns an empty map if the file does not exist
+ * or cannot be parsed.
+ */
+ private static Map> loadExistingTimings(String outputPath) {
+ Map> raw = new LinkedHashMap<>();
+ Path p = Paths.get(outputPath);
+ if (!Files.exists(p)) return raw;
+ try {
+ String json = Files.readString(p);
+ java.util.regex.Pattern qPat =
+ java.util.regex.Pattern.compile("\"(q\\w+)\":\\s*\\[([^\\]]+)\\]");
+ java.util.regex.Matcher m = qPat.matcher(json);
+ while (m.find()) {
+ String key = m.group(1);
+ List vals = new ArrayList<>();
+ for (String v : m.group(2).split(",")) {
+ try { vals.add(Long.parseLong(v.trim())); }
+ catch (NumberFormatException ignored) {}
+ }
+ if (!vals.isEmpty()) raw.put(key, vals);
+ }
+ } catch (IOException e) {
+ System.err.println(" [warn] could not load existing timings: " + e.getMessage());
+ }
+ // Re-order to QUERY_ORDER (LinkedHashMap preserves insertion order)
+ Map> ordered = new LinkedHashMap<>();
+ for (String q : QUERY_ORDER) {
+ if (raw.containsKey(q)) ordered.put(q, raw.get(q));
+ }
+ return ordered;
+ }
+
+ /**
+ * Resolve a page-range style query selector to a list of query IDs.
+ *
+ * Accepted forms (case-insensitive):
+ * null / "" / "all" → all 18 queries in canonical order
+ * "3" → ["q03"]
+ * "2-5" → ["q02","q03","q04","q05"]
+ * "q02" → ["q02"]
+ * "q02-q05" → ["q02","q03","q04","q05"]
+ * "qrt" → ["qrt"]
+ * "q04,qrt,q07" → ["q04","qrt","q07"]
+ */
+ private static List resolveQueryRange(String spec) {
+ List all = java.util.Arrays.asList(QUERY_ORDER);
+ if (spec == null || spec.isBlank() || spec.equalsIgnoreCase("all")) {
+ return all;
+ }
+
+ List result = new ArrayList<>();
+ for (String token : spec.split(",")) {
+ token = token.strip();
+ if (token.contains("-")) {
+ String[] parts = token.split("-", 2);
+ int from = parseQueryIndex(parts[0].strip(), all);
+ int to = parseQueryIndex(parts[1].strip(), all);
+ if (from < 0 || to < 0) {
+ throw new IllegalArgumentException("Unknown query in range: " + token);
+ }
+ int lo = Math.min(from, to), hi = Math.max(from, to);
+ result.addAll(all.subList(lo, hi + 1));
+ } else {
+ int idx = parseQueryIndex(token, all);
+ if (idx < 0) {
+ throw new IllegalArgumentException("Unknown query: " + token);
+ }
+ result.add(all.get(idx));
+ }
+ }
+ return result;
+ }
+
+ /**
+ * Parse a query token to its 0-based index in the canonical order.
+ * Accepts "q03", "qrt", or bare numbers like "3" (1-based, so "1"→q01).
+ * Returns -1 if not found.
+ */
+ private static int parseQueryIndex(String token, List all) {
+ String lower = token.toLowerCase(java.util.Locale.ROOT);
+ // Direct match: "q02", "qrt"
+ int idx = all.indexOf(lower);
+ if (idx >= 0) return idx;
+ // Bare number: "3" → "q03"
+ try {
+ int n = Integer.parseInt(lower);
+ String padded = String.format("q%02d", n);
+ idx = all.indexOf(padded);
+ return idx;
+ } catch (NumberFormatException e) {
+ return -1;
+ }
+ }
+}
diff --git a/src/main/java/org/mobilitydb/spark/demo/BerlinMODDemo.java b/src/main/java/org/mobilitydb/spark/demo/BerlinMODDemo.java
new file mode 100644
index 00000000..91ce14b5
--- /dev/null
+++ b/src/main/java/org/mobilitydb/spark/demo/BerlinMODDemo.java
@@ -0,0 +1,449 @@
+/*****************************************************************************
+ *
+ * This MobilityDB code is provided under The PostgreSQL License.
+ * Copyright (c) 2020-2026, 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.
+ *
+ *****************************************************************************/
+
+package org.mobilitydb.spark.demo;
+
+import org.apache.spark.sql.Dataset;
+import org.apache.spark.sql.Row;
+import org.apache.spark.sql.SparkSession;
+import org.mobilitydb.spark.MobilitySparkSession;
+
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * BerlinMOD Q1/Q3/Q4/Q5/Q6 — portable SQL dialect demo.
+ *
+ * Runs five BerlinMOD benchmark queries against the shared CSV dataset in
+ * berlinmod/data/. The SQL is identical to the MobilityDB (PostgreSQL) and
+ * MobilityDuck (DuckDB) versions — only named functions, no platform-specific
+ * operator symbols (RFC #861).
+ *
+ * Schema
+ * ------
+ * Vehicles (vehId INT, licence STRING, type STRING, model STRING)
+ * Trips (tripId INT, vehId INT, trip STRING) -- trip = tgeompoint hex-WKB
+ * QueryLicences(licenceId INT, licence STRING)
+ * QueryInstants(instantId INT, instant TIMESTAMP)
+ * QueryPoints (pointId INT, geom STRING) -- geom = WKT text, SRID 0
+ *
+ * Storage conventions
+ * -------------------
+ * tgeompoint → hex-WKB STRING (temporal_as_hexwkb / temporal_from_hexwkb)
+ * geometry → WKT STRING (e.g. "POINT(50 0)", parsed via geo_from_text)
+ *
+ * Usage
+ * -----
+ * spark-submit --class org.mobilitydb.spark.demo.BerlinMODDemo \
+ * target/mobilityspark-*-spark.jar berlinmod/data [berlinmod/expected]
+ *
+ * argv[0]: path to berlinmod/data directory (required)
+ * argv[1]: path to berlinmod/expected directory — if supplied, Q1/Q4/Q5/Q6
+ * results are compared against the CSV files there and the run
+ * exits with status 1 if any query differs.
+ *
+ * MEOS function authority: meos/include/meos.h, meos/include/meos_geo.h
+ * JMEOS PR source: github.com/MobilityDB/JMEOS/pull/9
+ */
+public final class BerlinMODDemo {
+
+ public static void main(String[] args) {
+ String dataDir = args.length > 0 ? args[0] : null;
+ String expectDir = args.length > 1 ? args[1] : null;
+
+ SparkSession spark = SparkSession.builder()
+ .master("local[2]")
+ .appName("MobilitySpark — BerlinMOD portable SQL")
+ .config("spark.sql.legacy.createHiveTableByDefault", "false")
+ .getOrCreate();
+ spark.sparkContext().setLogLevel("WARN");
+
+ try (MobilitySparkSession ms = MobilitySparkSession.create(spark)) {
+ if (dataDir != null) {
+ loadFromCsv(spark, dataDir);
+ } else {
+ loadSynthetic(spark);
+ }
+
+ Dataset q1 = runQ1(spark);
+ Dataset q2 = runQ2(spark);
+ Dataset q3 = runQ3(spark);
+ Dataset q4 = runQ4(spark);
+ Dataset q5 = runQ5(spark);
+ Dataset q6 = runQ6(spark);
+ Dataset q7 = runQ7(spark);
+ Dataset q8 = runQ8(spark);
+ Dataset qrt = runQRT(spark);
+
+ if (expectDir != null) {
+ verify(spark, q1, q2, q3, q4, q5, q6, q7, q8, qrt, expectDir);
+ }
+ } finally {
+ spark.stop();
+ }
+ }
+
+ // ------------------------------------------------------------------
+ // Data loading — from CSV files (shared with MobilityDB and MobilityDuck)
+ // ------------------------------------------------------------------
+
+ /** Package-visible entry point used by BerlinMODBench. */
+ static void loadFromCsvPublic(SparkSession spark, String dataDir) {
+ loadFromCsv(spark, dataDir);
+ }
+
+ private static void loadFromCsv(SparkSession spark, String dataDir) {
+ String dir = dataDir.endsWith("/") ? dataDir : dataDir + "/";
+
+ spark.read().option("header", "true").option("inferSchema", "true")
+ .csv(dir + "vehicles.csv")
+ .createOrReplaceTempView("Vehicles");
+
+ // Trips: hex-WKB strings — load directly; all UDFs call temporal_from_hexwkb.
+ spark.read().option("header", "true").option("inferSchema", "true")
+ .csv(dir + "trips.csv")
+ .createOrReplaceTempView("Trips");
+
+ spark.read().option("header", "true").option("inferSchema", "true")
+ .csv(dir + "query_licences.csv")
+ .createOrReplaceTempView("QueryLicences");
+
+ // QueryInstants: ensure proper TIMESTAMP type
+ spark.read().option("header", "true")
+ .csv(dir + "query_instants.csv")
+ .createOrReplaceTempView("QueryInstantsRaw");
+ spark.sql("CREATE OR REPLACE TEMP VIEW QueryInstants AS " +
+ "SELECT CAST(instantid AS INT) AS instantId, " +
+ "CAST(instant AS TIMESTAMP) AS instant FROM QueryInstantsRaw")
+ .count();
+
+ // QueryPoints: geom column is WKT text; geomWKT is an alias used by Q11/Q12/Q15
+ // for portable display (avoids geo_as_text precision divergence).
+ spark.read().option("header", "true")
+ .csv(dir + "query_points.csv")
+ .createOrReplaceTempView("QueryPointsRaw");
+ spark.sql("CREATE OR REPLACE TEMP VIEW QueryPoints AS " +
+ "SELECT CAST(pointid AS INT) AS pointId, geom, geom AS geomWKT " +
+ "FROM QueryPointsRaw")
+ .count();
+
+ // QueryRegions: geom column stays as WKT text — eIntersects/geomContains accept WKT.
+ spark.read().option("header", "true")
+ .csv(dir + "query_regions.csv")
+ .createOrReplaceTempView("QueryRegionsRaw");
+ spark.sql("CREATE OR REPLACE TEMP VIEW QueryRegions AS " +
+ "SELECT CAST(regionid AS INT) AS regionId, geom FROM QueryRegionsRaw")
+ .count();
+
+ // QueryPeriods: period column stays as STRING — atTime(trip, period) parses it.
+ spark.read().option("header", "true")
+ .csv(dir + "query_periods.csv")
+ .createOrReplaceTempView("QueryPeriodsRaw");
+ spark.sql("CREATE OR REPLACE TEMP VIEW QueryPeriods AS " +
+ "SELECT CAST(periodid AS INT) AS periodId, period FROM QueryPeriodsRaw")
+ .count();
+ }
+
+ // ------------------------------------------------------------------
+ // Data loading — synthetic in-memory data (no external files needed)
+ // ------------------------------------------------------------------
+ private static void loadSynthetic(SparkSession spark) {
+ spark.sql("""
+ CREATE OR REPLACE TEMP VIEW Vehicles AS SELECT * FROM VALUES
+ (1, 'B-AA 100', 'passenger', 'Sedan'),
+ (2, 'B-BB 200', 'passenger', 'SUV'),
+ (3, 'B-CC 300', 'truck', 'Lorry'),
+ (4, 'B-DD 400', 'truck', 'Truck'),
+ (5, 'B-EE 500', 'passenger', 'Van')
+ AS t(vehId, licence, type, model)
+ """);
+
+ // tgeompoint WKT → hex-WKB via registered UDF
+ spark.sql("""
+ CREATE OR REPLACE TEMP VIEW Trips AS SELECT * FROM VALUES
+ (1, 1, tgeompoint('[POINT(0 0)@2020-01-01 00:00:00+00, POINT(100 0)@2020-01-01 00:10:00+00]')),
+ (2, 2, tgeompoint('[POINT(0 5)@2020-01-01 00:00:00+00, POINT(100 5)@2020-01-01 00:10:00+00]')),
+ (3, 3, tgeompoint('[POINT(0 3)@2020-01-01 00:00:00+00, POINT(100 3)@2020-01-01 00:10:00+00]')),
+ (4, 4, tgeompoint('[POINT(0 4)@2020-01-01 00:00:00+00, POINT(100 4)@2020-01-01 00:10:00+00]')),
+ (5, 5, tgeompoint('[POINT(1000 1000)@2020-01-01 00:00:00+00, POINT(2000 1000)@2020-01-01 00:10:00+00]'))
+ AS t(tripId, vehId, trip)
+ """);
+
+ spark.sql("""
+ CREATE OR REPLACE TEMP VIEW QueryLicences AS SELECT * FROM VALUES
+ (1, 'B-AA 100'),
+ (2, 'B-CC 300')
+ AS t(licenceId, licence)
+ """);
+
+ spark.sql("""
+ CREATE OR REPLACE TEMP VIEW QueryInstants AS SELECT * FROM VALUES
+ (1, TIMESTAMP '2020-01-01 00:05:00')
+ AS t(instantId, instant)
+ """);
+
+ // geom stored as WKT text — eIntersects accepts WKT directly (no hex-EWKB needed)
+ spark.sql("""
+ CREATE OR REPLACE TEMP VIEW QueryPoints AS SELECT * FROM VALUES
+ (1, 'POINT(50 0)'),
+ (2, 'POINT(50 5)')
+ AS t(pointId, geom)
+ """);
+
+ // QueryRegions: polygon covering X=40-60, Y=-1 to 6 (captures vehicles 1-4)
+ spark.sql("""
+ CREATE OR REPLACE TEMP VIEW QueryRegions AS SELECT * FROM VALUES
+ (1, 'POLYGON((40 -1,60 -1,60 6,40 6,40 -1))')
+ AS t(regionId, geom)
+ """);
+
+ // QueryPeriods: middle portion of all trips
+ spark.sql("""
+ CREATE OR REPLACE TEMP VIEW QueryPeriods AS SELECT * FROM VALUES
+ (1, '[2020-01-01 00:02:00+00,2020-01-01 00:08:00+00]')
+ AS t(periodId, period)
+ """);
+ }
+
+ // ------------------------------------------------------------------
+ // Q1 — Models of vehicles with licences from QueryLicences.
+ // ------------------------------------------------------------------
+ private static Dataset runQ1(SparkSession spark) {
+ System.out.println("=== Q1: Vehicle models for query licences ===");
+ Dataset result = spark.sql("""
+ SELECT l.licence, v.model
+ FROM QueryLicences l
+ JOIN Vehicles v ON v.licence = l.licence
+ ORDER BY l.licence
+ """);
+ result.show();
+ return result;
+ }
+
+ // ------------------------------------------------------------------
+ // Q2 — Licence plates of vehicles that ever entered a query region.
+ // ------------------------------------------------------------------
+ private static Dataset runQ2(SparkSession spark) {
+ System.out.println("=== Q2: Vehicles that ever entered a query region ===");
+ Dataset result = spark.sql("""
+ SELECT DISTINCT v.licence
+ FROM Vehicles v
+ JOIN Trips t ON t.vehId = v.vehId
+ JOIN QueryRegions r ON eIntersects(t.trip, r.geom)
+ ORDER BY v.licence
+ """);
+ result.show();
+ return result;
+ }
+
+ // ------------------------------------------------------------------
+ // Q3 — Position of query-licence vehicles at each query instant.
+ // Binary return: pos is MEOS hex-WKB via asHexWKB() — byte-for-byte
+ // identical across MobilityDB, MobilityDuck, and MobilitySpark.
+ // ------------------------------------------------------------------
+ private static Dataset runQ3(SparkSession spark) {
+ System.out.println("=== Q3: Vehicle positions at query instants (binary return) ===");
+ Dataset result = spark.sql("""
+ SELECT v.vehId AS vehid,
+ v.licence,
+ i.instantId AS instantid,
+ asHexWKB(atTime(t.trip, i.instant)) AS pos
+ FROM QueryLicences l
+ JOIN Vehicles v ON v.licence = l.licence
+ JOIN Trips t ON t.vehId = v.vehId
+ JOIN QueryInstants i ON true
+ WHERE atTime(t.trip, i.instant) IS NOT NULL
+ ORDER BY v.vehId, i.instantId
+ """);
+ result.show(false);
+ return result;
+ }
+
+ // ------------------------------------------------------------------
+ // Q7 — Trip portions of query-licence vehicles during each query period.
+ // Binary return: pos is MEOS hex-WKB via asHexWKB() — byte-for-byte
+ // identical across MobilityDB, MobilityDuck, and MobilitySpark.
+ // ------------------------------------------------------------------
+ private static Dataset runQ7(SparkSession spark) {
+ System.out.println("=== Q7: Trip portions during query periods (binary return) ===");
+ Dataset result = spark.sql("""
+ SELECT v.vehId AS vehid,
+ v.licence,
+ p.periodId AS periodid,
+ asHexWKB(atTime(t.trip, p.period)) AS pos
+ FROM QueryLicences l
+ JOIN Vehicles v ON v.licence = l.licence
+ JOIN Trips t ON t.vehId = v.vehId
+ JOIN QueryPeriods p ON true
+ WHERE atTime(t.trip, p.period) IS NOT NULL
+ ORDER BY v.vehId, p.periodId
+ """);
+ result.show(false);
+ return result;
+ }
+
+ // ------------------------------------------------------------------
+ // Q8 — Trajectory of each vehicle as hex-WKB geometry (byte-for-byte
+ // identical across MobilityDB, MobilityDuck, and MobilitySpark).
+ // ------------------------------------------------------------------
+ private static Dataset runQ8(SparkSession spark) {
+ System.out.println("=== Q8: Vehicle trajectories (hex WKB) ===");
+ Dataset result = spark.sql("""
+ SELECT tripId AS tripid,
+ trajectory(trip) AS traj
+ FROM Trips
+ ORDER BY tripId
+ """);
+ result.show(false);
+ return result;
+ }
+
+ // ------------------------------------------------------------------
+ // QRT — Binary roundtrip: WKT text in → MEOS hex-WKB out.
+ // All five trips serialised with asHexWKB(); output must be
+ // byte-for-byte identical across all three ecosystem platforms.
+ // ------------------------------------------------------------------
+ private static Dataset runQRT(SparkSession spark) {
+ System.out.println("=== QRT: Binary roundtrip — asHexWKB(trip) for all trips ===");
+ Dataset result = spark.sql("""
+ SELECT tripId AS tripid,
+ asHexWKB(trip) AS trip_hexwkb
+ FROM Trips
+ ORDER BY tripId
+ """);
+ result.show(false);
+ return result;
+ }
+
+ // ------------------------------------------------------------------
+ // Q4 — Licence plates of vehicles that ever passed a query point.
+ // ------------------------------------------------------------------
+ private static Dataset runQ4(SparkSession spark) {
+ System.out.println("=== Q4: Vehicles that ever passed a query point ===");
+ Dataset result = spark.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)
+ ORDER BY v.licence
+ """);
+ result.show();
+ return result;
+ }
+
+ // ------------------------------------------------------------------
+ // Q5 — Minimum nearest-approach distance between each pair of query vehicles.
+ // ------------------------------------------------------------------
+ private static Dataset runQ5(SparkSession spark) {
+ System.out.println("=== Q5: Min nearest-approach distance between vehicle pairs ===");
+ Dataset result = spark.sql("""
+ SELECT l1.licence AS licence1,
+ l2.licence AS licence2,
+ MIN(nearestApproachDistance(t1.trip, t2.trip)) AS min_dist
+ FROM QueryLicences l1
+ JOIN Vehicles v1 ON v1.licence = l1.licence
+ JOIN Trips t1 ON t1.vehId = v1.vehId
+ JOIN QueryLicences l2 ON l1.licenceId < l2.licenceId
+ JOIN Vehicles v2 ON v2.licence = l2.licence
+ JOIN Trips t2 ON t2.vehId = v2.vehId
+ WHERE nearestApproachDistance(t1.trip, t2.trip) IS NOT NULL
+ GROUP BY l1.licence, l2.licence
+ ORDER BY l1.licence, l2.licence
+ """);
+ result.show();
+ return result;
+ }
+
+ // ------------------------------------------------------------------
+ // Q6 — Pairs of trucks that ever came within 10 m of each other.
+ // ------------------------------------------------------------------
+ private static Dataset runQ6(SparkSession spark) {
+ System.out.println("=== Q6: Truck pairs within 10 m ===");
+ Dataset result = spark.sql("""
+ SELECT v1.licence AS licence1,
+ v2.licence AS licence2
+ FROM Vehicles v1
+ JOIN Trips t1 ON t1.vehId = v1.vehId
+ JOIN Vehicles v2 ON v1.vehId < v2.vehId
+ JOIN Trips t2 ON t2.vehId = v2.vehId
+ WHERE v1.type = 'truck'
+ AND v2.type = 'truck'
+ AND eDwithin(t1.trip, t2.trip, 10.0)
+ ORDER BY licence1, licence2
+ """);
+ result.show();
+ return result;
+ }
+
+ // ------------------------------------------------------------------
+ // Cross-platform verification: compare against expected CSV files.
+ // All queries (Q1–Q8, QRT) are compared. Q3/Q7/QRT use asHexWKB()
+ // for temporal types; Q8 uses geo_as_hexewkb() for geometry — all
+ // produce byte-for-byte identical output across all three platforms.
+ // ------------------------------------------------------------------
+ private static void verify(SparkSession spark,
+ Dataset q1, Dataset q2,
+ Dataset q3, Dataset q4,
+ Dataset q5, Dataset q6,
+ Dataset q7, Dataset q8,
+ Dataset qrt,
+ String expectDir) {
+ String dir = expectDir.endsWith("/") ? expectDir : expectDir + "/";
+ boolean allPass = true;
+ allPass &= compareQuery(spark, "Q1", q1, dir + "q01.csv");
+ allPass &= compareQuery(spark, "Q2", q2, dir + "q02.csv");
+ allPass &= compareQuery(spark, "Q3", q3, dir + "q03.csv");
+ allPass &= compareQuery(spark, "Q4", q4, dir + "q04.csv");
+ allPass &= compareQuery(spark, "Q5", q5, dir + "q05.csv");
+ allPass &= compareQuery(spark, "Q6", q6, dir + "q06.csv");
+ allPass &= compareQuery(spark, "Q7", q7, dir + "q07.csv");
+ allPass &= compareQuery(spark, "Q8", q8, dir + "q08.csv");
+ allPass &= compareQuery(spark, "QRT", qrt, dir + "qrt.csv");
+ System.out.println(allPass ? "\nALL PASS" : "\nFAILURES DETECTED");
+ if (!allPass) System.exit(1);
+ }
+
+ private static boolean compareQuery(SparkSession spark, String name,
+ Dataset got, String expectedCsv) {
+ Dataset expected = spark.read().option("header", "true").csv(expectedCsv);
+ // Compare as sorted lists of column-delimited strings
+ List gotRows = toSortedStrings(got);
+ List expRows = toSortedStrings(expected);
+ if (gotRows.equals(expRows)) {
+ System.out.println("[PASS] " + name);
+ return true;
+ }
+ System.out.println("[FAIL] " + name);
+ System.out.println(" Expected: " + expRows);
+ System.out.println(" Got: " + gotRows);
+ return false;
+ }
+
+ private static List toSortedStrings(Dataset ds) {
+ String[] rows = (String[]) ds.toJSON().collect();
+ Arrays.sort(rows);
+ return Arrays.asList(rows);
+ }
+}
diff --git a/src/main/java/org/mobilitydb/spark/demo/BerlinMODUDFs.java b/src/main/java/org/mobilitydb/spark/demo/BerlinMODUDFs.java
new file mode 100644
index 00000000..b204a29b
--- /dev/null
+++ b/src/main/java/org/mobilitydb/spark/demo/BerlinMODUDFs.java
@@ -0,0 +1,386 @@
+/*****************************************************************************
+ *
+ * This MobilityDB code is provided under The PostgreSQL License.
+ * Copyright (c) 2020-2026, 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.
+ *
+ *****************************************************************************/
+
+package org.mobilitydb.spark.demo;
+
+import functions.GeneratedFunctions;
+import jnr.ffi.Pointer;
+import jnr.ffi.Runtime;
+import org.apache.spark.sql.SparkSession;
+import org.apache.spark.sql.api.java.*;
+import org.apache.spark.sql.types.DataTypes;
+import org.mobilitydb.spark.MeosMemory;
+import org.mobilitydb.spark.MeosThread;
+
+import java.time.Instant;
+import java.time.OffsetDateTime;
+import java.time.ZoneOffset;
+import java.time.format.DateTimeFormatter;
+
+/**
+ * BerlinMOD-specific Spark SQL UDFs that extend the base MobilitySpark surface.
+ *
+ * These UDFs cover operations needed for BerlinMOD Q09-Q16 that are not in the
+ * core UDF set: path length, bbox overlap (replacing &&), valueAtTimestamp,
+ * geo+time STBox constructors, expandSpace, tDwithin, whenTrue, aDisjoint,
+ * and geomContains.
+ *
+ * BerlinMODBench also preprocesses the portable SQL to rewrite Spark-incompatible
+ * syntax before passing to spark.sql():
+ * stbox(geom, t) → geoTimeStbox(geom, t)
+ * expr1 && expr2 → bboxOverlaps(expr1, expr2) (per line)
+ * ::numeric → (removed)
+ * ST_Contains( → geomContains(
+ */
+public final class BerlinMODUDFs {
+
+ private BerlinMODUDFs() {}
+
+ /**
+ * SRID applied when parsing the query-table WKT geometries (QueryPoints,
+ * QueryRegions). Must match the SRID the trips carry, otherwise spatial
+ * operators such as {@code trip && stbox(geom, t)} raise "Operation on
+ * mixed SRID". Default 0 matches the small synthetic dataset; set
+ * {@code -Dberlinmod.srid=3812} for the Brussels (Lambert 2008) export.
+ */
+ public static final int GEOM_SRID = Integer.getInteger("berlinmod.srid", 0);
+
+ private static final DateTimeFormatter PG_FMT =
+ DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
+
+ /** Convert Spark java.sql.Timestamp to MEOS TimestampTz via pg_timestamptz_in. */
+ private static OffsetDateTime toMeosTs(java.sql.Timestamp ts) {
+ String s = ts.toInstant().atOffset(ZoneOffset.UTC).format(PG_FMT);
+ return GeneratedFunctions.pg_timestamptz_in(s, -1);
+ }
+
+ /** Convert a String or java.sql.Timestamp to MEOS TimestampTz. */
+ private static OffsetDateTime parseTs(Object arg) {
+ if (arg instanceof java.sql.Timestamp) return toMeosTs((java.sql.Timestamp) arg);
+ return GeneratedFunctions.pg_timestamptz_in(arg.toString().trim(), -1);
+ }
+
+ // ------------------------------------------------------------------
+ // length(trip STRING) → DOUBLE
+ // Path length of a tgeompoint trajectory.
+ // MEOS: tpoint_length(const Temporal *) meos_geo.h:673
+ // ------------------------------------------------------------------
+ public static final UDF1 length = (trip) -> {
+ if (trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ return GeneratedFunctions.tpoint_length(tptr);
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // bboxOverlaps(trip STRING, other STRING) → BOOLEAN
+ // Replaces the && bounding-box overlap operator in BerlinMOD SQL.
+ // other can be:
+ // - a tstzspan literal ("[2020-..., 2020-...]") → temporal overlap
+ // - an STBox hex-WKB string (from geoTimeStbox / expandSpace) → spatial overlap
+ // MEOS: overlaps_temporal_tstzspan / overlaps_tpoint_stbox (JMEOS-1.5 tpoint variant)
+ // ------------------------------------------------------------------
+ public static final UDF2 bboxOverlaps = (trip, other) -> {
+ if (trip == null || other == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ char first = other.isEmpty() ? 0 : other.charAt(0);
+ if (first == '[' || first == '(') {
+ Pointer sptr = GeneratedFunctions.tstzspan_in(other);
+ if (sptr == null) return null;
+ try {
+ return GeneratedFunctions.overlaps_temporal_tstzspan(tptr, sptr);
+ } finally {
+ MeosMemory.free(sptr);
+ }
+ } else {
+ Pointer bptr = GeneratedFunctions.stbox_from_hexwkb(other);
+ if (bptr == null) return null;
+ try {
+ return GeneratedFunctions.overlaps_tspatial_stbox(tptr, bptr);
+ } finally {
+ MeosMemory.free(bptr);
+ }
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // valueAtTimestamp(trip STRING, instant) → STRING (WKT geometry)
+ // Returns the geometry of a tgeompoint at a given instant, as WKT.
+ // instant can be a java.sql.Timestamp (Spark TIMESTAMP) or String.
+ // MEOS 1.4: tgeo_value_at_timestamptz — the temporal_value_at_timestamptz
+ // family is split per base type (tbool/tint/tfloat/ttext/tgeo/tpose).
+ // ------------------------------------------------------------------
+ public static final UDF2 valueAtTimestamp = (trip, tsArg) -> {
+ if (trip == null || tsArg == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ OffsetDateTime odt = parseTs(tsArg);
+ if (odt == null) return null;
+ Pointer geomPtr = GeneratedFunctions.tgeo_value_at_timestamptz(tptr, odt, true);
+ if (geomPtr == null) return null;
+ return GeneratedFunctions.geo_as_text(geomPtr, 15);
+ };
+
+ // ------------------------------------------------------------------
+ // geoTimeStbox(geomWkt STRING, instant_or_period) → STRING (STBox hex-WKB)
+ // Replaces stbox(geom, instant) and stbox(geom, period) in BerlinMOD SQL.
+ // Second arg: java.sql.Timestamp → geo_timestamptz_to_stbox
+ // String "[...]" → geo_tstzspan_to_stbox
+ // String "..." → treat as timestamp string
+ // MEOS: geo_timestamptz_to_stbox / geo_tstzspan_to_stbox meos_geo.h:506-507
+ // ------------------------------------------------------------------
+ public static final UDF2 geoTimeStbox = (geomWkt, tsArg) -> {
+ if (geomWkt == null || tsArg == null) return null;
+ MeosThread.ensureReady();
+ Pointer gptr = GeneratedFunctions.geo_from_text(geomWkt, GEOM_SRID);
+ if (gptr == null) return null;
+ try {
+ Pointer result;
+ if (tsArg instanceof java.sql.Timestamp) {
+ OffsetDateTime odt = toMeosTs((java.sql.Timestamp) tsArg);
+ if (odt == null) return null;
+ result = GeneratedFunctions.geo_timestamptz_to_stbox(gptr, odt);
+ } else {
+ String s = tsArg.toString().trim();
+ if (s.isEmpty()) return null;
+ if (s.charAt(0) == '[' || s.charAt(0) == '(') {
+ Pointer sptr = GeneratedFunctions.tstzspan_in(s);
+ if (sptr == null) return null;
+ try {
+ result = GeneratedFunctions.geo_tstzspan_to_stbox(gptr, sptr);
+ } finally {
+ MeosMemory.free(sptr);
+ }
+ } else {
+ OffsetDateTime odt = GeneratedFunctions.pg_timestamptz_in(s, -1);
+ if (odt == null) return null;
+ result = GeneratedFunctions.geo_timestamptz_to_stbox(gptr, odt);
+ }
+ }
+ if (result == null) return null;
+ try {
+ Pointer sizeOut = Runtime.getSystemRuntime().getMemoryManager().allocateDirect(8);
+ return GeneratedFunctions.stbox_as_hexwkb(result, (byte) 0, sizeOut);
+ } finally {
+ MeosMemory.free(result);
+ }
+ } finally {
+ MeosMemory.free(gptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // expandSpace(trip STRING, dist NUMBER) → STRING (STBox hex-WKB)
+ // Computes the STBox of a trip then expands it spatially by dist.
+ // Used in Q10 as a bounding-box pre-filter: bboxOverlaps(trip, expandSpace(...)).
+ // MEOS: tspatial_to_stbox + stbox_expand_space meos_geo.h:548
+ // ------------------------------------------------------------------
+ public static final UDF2 expandSpace = (in, dist) -> {
+ if (in == null || dist == null) return null;
+ MeosThread.ensureReady();
+ // Accept either a tgeompoint hex (full trip) or a precomputed STBox hex
+ // (the materialised trip_bbox column) so a cross-join prefilter never
+ // re-parses the full multi-thousand-instant trip.
+ Pointer bbox = GeneratedFunctions.stbox_from_hexwkb(in);
+ Pointer tptr = null;
+ if (bbox == null) {
+ tptr = GeneratedFunctions.temporal_from_hexwkb(in);
+ if (tptr == null) return null;
+ bbox = GeneratedFunctions.tspatial_to_stbox(tptr);
+ }
+ if (bbox == null) {
+ if (tptr != null) MeosMemory.free(tptr);
+ return null;
+ }
+ try {
+ Pointer expanded = GeneratedFunctions.stbox_expand_space(bbox, dist.doubleValue());
+ if (expanded == null) return null;
+ try {
+ Pointer sizeOut = Runtime.getSystemRuntime().getMemoryManager().allocateDirect(8);
+ return GeneratedFunctions.stbox_as_hexwkb(expanded, (byte) 0, sizeOut);
+ } finally {
+ MeosMemory.free(expanded);
+ }
+ } finally {
+ MeosMemory.free(bbox);
+ if (tptr != null) MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // stboxOverlaps(aHex STRING, bHex STRING) → BOOLEAN
+ // STBox-vs-STBox bounding-box overlap. Both arguments are small STBox
+ // hex-WKB strings (e.g. the materialised trip_bbox column and a
+ // geoTimeStbox / expandSpace result), so the cross-join spatial prefilter
+ // never parses a full trip. preprocessForSpark rewrites the spatial
+ // `trip && ` operator to this UDF on trip_bbox.
+ // MEOS: overlaps_stbox_stbox
+ // ------------------------------------------------------------------
+ public static final UDF2 stboxOverlaps = (a, b) -> {
+ if (a == null || b == null) return null;
+ MeosThread.ensureReady();
+ Pointer pa = GeneratedFunctions.stbox_from_hexwkb(a);
+ if (pa == null) return null;
+ try {
+ Pointer pb = GeneratedFunctions.stbox_from_hexwkb(b);
+ if (pb == null) return null;
+ try {
+ return GeneratedFunctions.overlaps_stbox_stbox(pa, pb);
+ } finally {
+ MeosMemory.free(pb);
+ }
+ } finally {
+ MeosMemory.free(pa);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // tDwithin(t1 STRING, t2 STRING, dist NUMBER) → STRING (tbool hex-WKB)
+ // Returns a temporal boolean showing when the two trajectories are within
+ // dist of each other (used by Q10 with whenTrue).
+ // MEOS: tdwithin_tpoint_tpoint (JMEOS-1.5 tpoint variant)
+ // Note: JMEOS wraps with extra (restr, atvalue) booleans; pass false,false
+ // to get the full temporal result.
+ // ------------------------------------------------------------------
+ public static final UDF3 tDwithin = (t1, t2, dist) -> {
+ if (t1 == null || t2 == null || dist == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(t1);
+ if (p1 == null) return null;
+ try {
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(t2);
+ if (p2 == null) return null;
+ try {
+ Pointer result = GeneratedFunctions.tdwithin_tgeo_tgeo(p1, p2, dist.doubleValue());
+ if (result == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(result, (byte) 0);
+ } finally {
+ MeosMemory.free(result);
+ }
+ } finally {
+ MeosMemory.free(p2);
+ }
+ } finally {
+ MeosMemory.free(p1);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // whenTrue(tbool STRING) → STRING (tstzspanset text)
+ // ------------------------------------------------------------------
+ public static final UDF1 whenTrue = (tbool) -> {
+ if (tbool == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(tbool);
+ if (tptr == null) return null;
+ try {
+ Pointer sset = GeneratedFunctions.tbool_when_true(tptr);
+ if (sset == null) return null;
+ try {
+ return GeneratedFunctions.tstzspanset_out(sset);
+ } finally {
+ MeosMemory.free(sset);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // aDisjoint(t1 STRING, t2 STRING) → BOOLEAN
+ // ------------------------------------------------------------------
+ public static final UDF2 aDisjoint = (t1, t2) -> {
+ if (t1 == null || t2 == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(t1);
+ if (p1 == null) return null;
+ try {
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(t2);
+ if (p2 == null) return null;
+ try {
+ return GeneratedFunctions.adisjoint_tgeo_tgeo(p1, p2) == 1;
+ } finally {
+ MeosMemory.free(p2);
+ }
+ } finally {
+ MeosMemory.free(p1);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // geomContains(outer STRING, inner STRING) → BOOLEAN
+ // Replaces ST_Contains in Q14. Approximated via econtains_geo_tgeo.
+ // ------------------------------------------------------------------
+ public static final UDF2 geomContains = (outer, inner) -> {
+ if (outer == null || inner == null) return null;
+ MeosThread.ensureReady();
+ Pointer g1 = GeneratedFunctions.geo_from_text(outer, GEOM_SRID);
+ if (g1 == null) return null;
+ try {
+ OffsetDateTime epoch = GeneratedFunctions.pg_timestamptz_in("2000-01-01", -1);
+ Pointer innerGeo = GeneratedFunctions.geo_from_text(inner, GEOM_SRID);
+ if (innerGeo == null) return null;
+ try {
+ Pointer tptr = GeneratedFunctions.tpointinst_make(innerGeo, epoch);
+ if (tptr == null) return null;
+ try {
+ return GeneratedFunctions.econtains_geo_tgeo(g1, tptr) == 1;
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ } finally {
+ MeosMemory.free(innerGeo);
+ }
+ } finally {
+ MeosMemory.free(g1);
+ }
+ };
+
+ public static void registerAll(SparkSession spark) {
+ spark.udf().register("length", length, DataTypes.DoubleType);
+ spark.udf().register("bboxOverlaps", bboxOverlaps, DataTypes.BooleanType);
+ spark.udf().register("stboxOverlaps", stboxOverlaps, DataTypes.BooleanType);
+ spark.udf().register("valueAtTimestamp", valueAtTimestamp, DataTypes.StringType);
+ spark.udf().register("geoTimeStbox", geoTimeStbox, DataTypes.StringType);
+ spark.udf().register("expandSpace", expandSpace, DataTypes.StringType);
+ spark.udf().register("tDwithin", tDwithin, DataTypes.StringType);
+ spark.udf().register("whenTrue", whenTrue, DataTypes.StringType);
+ spark.udf().register("aDisjoint", aDisjoint, DataTypes.BooleanType);
+ spark.udf().register("geomContains", geomContains, DataTypes.BooleanType);
+ }
+}
diff --git a/src/main/java/org/mobilitydb/spark/examples/N01HelloWorld.java b/src/main/java/org/mobilitydb/spark/examples/N01HelloWorld.java
new file mode 100644
index 00000000..eb4f7d48
--- /dev/null
+++ b/src/main/java/org/mobilitydb/spark/examples/N01HelloWorld.java
@@ -0,0 +1,70 @@
+/*****************************************************************************
+ *
+ * This MobilityDB code is provided under The PostgreSQL License.
+ * Copyright (c) 2020-2026, 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.
+ *
+ *****************************************************************************/
+
+package org.mobilitydb.spark.examples;
+
+import org.apache.spark.sql.SparkSession;
+import org.mobilitydb.spark.MobilitySparkSession;
+
+import static functions.GeneratedFunctions.*;
+
+/**
+ * N01 Hello World — the minimal MobilitySpark program.
+ *
+ * Creates a single tgeompoint value inside Spark SQL, rounds it back to
+ * text, and prints it. Mirrors meos/examples/01_hello_world.c.
+ *
+ * Run with:
+ * spark-submit --class org.mobilitydb.spark.examples.N01HelloWorld \
+ * target/mobilityspark-0.1.0-SNAPSHOT-spark.jar
+ */
+public final class N01HelloWorld {
+
+ public static void main(String[] args) {
+ SparkSession spark = SparkSession.builder()
+ .master("local[2]")
+ .appName("MobilitySpark N01 Hello World")
+ .getOrCreate();
+ spark.sparkContext().setLogLevel("WARN");
+
+ try (MobilitySparkSession ms = MobilitySparkSession.create(spark)) {
+
+ // Build a tgeompoint sequence and round-trip through hex-WKB.
+ String wkt = "[POINT(1 1)@2020-01-01 00:00:00+00, "
+ + "POINT(2 2)@2020-01-01 01:00:00+00]";
+ String hex = temporal_as_hexwkb(tgeompoint_in(wkt), (byte) 0);
+
+ // Register a simple view so we can use Spark SQL.
+ spark.sql("CREATE OR REPLACE TEMPORARY VIEW trips AS "
+ + "SELECT '" + hex + "' AS trip");
+
+ System.out.println("=== Hello World: tgeompoint round-trip ===");
+ spark.sql("SELECT trip FROM trips").show(false);
+
+ } finally {
+ spark.stop();
+ }
+ }
+}
diff --git a/src/main/java/org/mobilitydb/spark/examples/N03BerlinMOD.java b/src/main/java/org/mobilitydb/spark/examples/N03BerlinMOD.java
new file mode 100644
index 00000000..c567df37
--- /dev/null
+++ b/src/main/java/org/mobilitydb/spark/examples/N03BerlinMOD.java
@@ -0,0 +1,48 @@
+/*****************************************************************************
+ *
+ * This MobilityDB code is provided under The PostgreSQL License.
+ * Copyright (c) 2020-2026, 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.
+ *
+ *****************************************************************************/
+
+package org.mobilitydb.spark.examples;
+
+import org.apache.spark.sql.SparkSession;
+import org.mobilitydb.spark.MobilitySparkSession;
+import org.mobilitydb.spark.demo.BerlinMODDemo;
+
+/**
+ * N03 BerlinMOD — portable SQL benchmark queries Q1/Q3/Q4/Q5/Q6.
+ *
+ * Delegates to {@link BerlinMODDemo} which runs the five BerlinMOD queries
+ * in the portable named-function SQL dialect (identical to MobilityDB and
+ * MobilityDuck). Mirrors meos/examples/03_berlinmod_assemble.c.
+ *
+ * Run with:
+ * spark-submit --class org.mobilitydb.spark.examples.N03BerlinMOD \
+ * target/mobilityspark-0.1.0-SNAPSHOT-spark.jar
+ */
+public final class N03BerlinMOD {
+
+ public static void main(String[] args) {
+ BerlinMODDemo.main(args);
+ }
+}
diff --git a/src/main/java/org/mobilitydb/spark/geo/AlwaysSpatialRelsUDFs.java b/src/main/java/org/mobilitydb/spark/geo/AlwaysSpatialRelsUDFs.java
new file mode 100644
index 00000000..da3f2e71
--- /dev/null
+++ b/src/main/java/org/mobilitydb/spark/geo/AlwaysSpatialRelsUDFs.java
@@ -0,0 +1,151 @@
+/*****************************************************************************
+ *
+ * This MobilityDB code is provided under The PostgreSQL License.
+ * Copyright (c) 2020-2026, 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.
+ *
+ *****************************************************************************/
+
+package org.mobilitydb.spark.geo;
+
+import functions.GeneratedFunctions;
+import jnr.ffi.Pointer;
+import org.mobilitydb.spark.MeosMemory;
+import org.mobilitydb.spark.MeosThread;
+import org.apache.spark.sql.SparkSession;
+import org.apache.spark.sql.api.java.UDF2;
+import org.apache.spark.sql.api.java.UDF3;
+import org.apache.spark.sql.types.DataTypes;
+
+import java.util.function.BiFunction;
+
+/**
+ * Spark SQL UDFs for "always" spatial relationship predicates: do all
+ * times in the temporal value satisfy the relation? Counterpart to the
+ * "ever" family in TempSpatialRelsUDFs.
+ *
+ * MEOS function authority: meos/include/meos_geo.h
+ *
+ * Native functions return int (-1 = error, 0 = false, 1 = true). The
+ * UDF wrappers convert to Boolean (null on error).
+ */
+public final class AlwaysSpatialRelsUDFs {
+
+ private AlwaysSpatialRelsUDFs() {}
+
+ @FunctionalInterface
+ private interface IntBiFn { int apply(Pointer a, Pointer b); }
+
+ @FunctionalInterface
+ private interface IntTriFn { int apply(Pointer a, Pointer b, double dist); }
+
+ private static Boolean tri(int v) {
+ return v == -1 ? null : v == 1;
+ }
+
+ private static UDF2 tgeoGeo(IntBiFn fn) {
+ return (trip, geomWkt) -> {
+ if (trip == null || geomWkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer t = GeneratedFunctions.temporal_from_hexwkb(trip); if (t == null) return null;
+ Pointer g = GeneratedFunctions.geo_from_text(geomWkt, 0);
+ if (g == null) { MeosMemory.free(t); return null; }
+ try { return tri(fn.apply(t, g)); }
+ finally { MeosMemory.free(t, g); }
+ };
+ }
+
+ private static UDF2 tgeoTgeo(IntBiFn fn) {
+ return (trip1, trip2) -> {
+ if (trip1 == null || trip2 == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(trip1); if (p1 == null) return null;
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(trip2);
+ if (p2 == null) { MeosMemory.free(p1); return null; }
+ try { return tri(fn.apply(p1, p2)); }
+ finally { MeosMemory.free(p1, p2); }
+ };
+ }
+
+ private static UDF2 geoTgeo(IntBiFn fn) {
+ return (geomWkt, trip) -> {
+ if (geomWkt == null || trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer g = GeneratedFunctions.geo_from_text(geomWkt, 0); if (g == null) return null;
+ Pointer t = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (t == null) { MeosMemory.free(g); return null; }
+ try { return tri(fn.apply(g, t)); }
+ finally { MeosMemory.free(g, t); }
+ };
+ }
+
+ private static UDF3 tgeoGeoDist(IntTriFn fn) {
+ return (trip, geomWkt, dist) -> {
+ if (trip == null || geomWkt == null || dist == null) return null;
+ MeosThread.ensureReady();
+ Pointer t = GeneratedFunctions.temporal_from_hexwkb(trip); if (t == null) return null;
+ Pointer g = GeneratedFunctions.geo_from_text(geomWkt, 0);
+ if (g == null) { MeosMemory.free(t); return null; }
+ try { return tri(fn.apply(t, g, dist)); }
+ finally { MeosMemory.free(t, g); }
+ };
+ }
+
+ private static UDF3 tgeoTgeoDist(IntTriFn fn) {
+ return (trip1, trip2, dist) -> {
+ if (trip1 == null || trip2 == null || dist == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(trip1); if (p1 == null) return null;
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(trip2);
+ if (p2 == null) { MeosMemory.free(p1); return null; }
+ try { return tri(fn.apply(p1, p2, dist)); }
+ finally { MeosMemory.free(p1, p2); }
+ };
+ }
+
+ public static final UDF2 aDisjointTgeoGeo = tgeoGeo(GeneratedFunctions::adisjoint_tgeo_geo);
+ public static final UDF2 aDisjointTgeoTgeo = tgeoTgeo(GeneratedFunctions::adisjoint_tgeo_tgeo);
+ public static final UDF2 aIntersectsTgeoGeo = tgeoGeo(GeneratedFunctions::aintersects_tgeo_geo);
+ public static final UDF2 aIntersectsTgeoTgeo = tgeoTgeo(GeneratedFunctions::aintersects_tgeo_tgeo);
+ public static final UDF2 aTouchesTgeoGeo = tgeoGeo(GeneratedFunctions::atouches_tgeo_geo);
+ public static final UDF2 aTouchesTgeoTgeo = tgeoTgeo(GeneratedFunctions::atouches_tgeo_tgeo);
+ public static final UDF2 aContainsTgeoGeo = tgeoGeo(GeneratedFunctions::acontains_tgeo_geo);
+ public static final UDF2 aContainsTgeoTgeo = tgeoTgeo(GeneratedFunctions::acontains_tgeo_tgeo);
+ public static final UDF2 aContainsGeoTgeo = geoTgeo(GeneratedFunctions::acontains_geo_tgeo);
+ public static final UDF2 aCoversTgeoGeo = tgeoGeo(GeneratedFunctions::acovers_tgeo_geo);
+
+ public static final UDF3 aDwithinTgeoGeo = tgeoGeoDist(GeneratedFunctions::adwithin_tgeo_geo);
+ public static final UDF3 aDwithinTgeoTgeo = tgeoTgeoDist(GeneratedFunctions::adwithin_tgeo_tgeo);
+
+ public static void registerAll(SparkSession spark) {
+ spark.udf().register("aDisjointTgeoGeo", aDisjointTgeoGeo, DataTypes.BooleanType);
+ spark.udf().register("aDisjointTgeoTgeo", aDisjointTgeoTgeo, DataTypes.BooleanType);
+ spark.udf().register("aIntersectsTgeoGeo", aIntersectsTgeoGeo, DataTypes.BooleanType);
+ spark.udf().register("aIntersectsTgeoTgeo", aIntersectsTgeoTgeo, DataTypes.BooleanType);
+ spark.udf().register("aTouchesTgeoGeo", aTouchesTgeoGeo, DataTypes.BooleanType);
+ spark.udf().register("aTouchesTgeoTgeo", aTouchesTgeoTgeo, DataTypes.BooleanType);
+ spark.udf().register("aContainsTgeoGeo", aContainsTgeoGeo, DataTypes.BooleanType);
+ spark.udf().register("aContainsTgeoTgeo", aContainsTgeoTgeo, DataTypes.BooleanType);
+ spark.udf().register("aContainsGeoTgeo", aContainsGeoTgeo, DataTypes.BooleanType);
+ spark.udf().register("aCoversTgeoGeo", aCoversTgeoGeo, DataTypes.BooleanType);
+ spark.udf().register("aDwithinTgeoGeo", aDwithinTgeoGeo, DataTypes.BooleanType);
+ spark.udf().register("aDwithinTgeoTgeo", aDwithinTgeoTgeo, DataTypes.BooleanType);
+ }
+}
diff --git a/src/main/java/org/mobilitydb/spark/geo/DistanceUDFs.java b/src/main/java/org/mobilitydb/spark/geo/DistanceUDFs.java
new file mode 100644
index 00000000..1ae8154f
--- /dev/null
+++ b/src/main/java/org/mobilitydb/spark/geo/DistanceUDFs.java
@@ -0,0 +1,505 @@
+/*****************************************************************************
+ *
+ * This MobilityDB code is provided under The PostgreSQL License.
+ * Copyright (c) 2020-2026, 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.
+ *
+ *****************************************************************************/
+
+package org.mobilitydb.spark.geo;
+
+import functions.GeneratedFunctions;
+import jnr.ffi.Memory;
+import jnr.ffi.Pointer;
+import jnr.ffi.Runtime;
+import org.mobilitydb.spark.MeosMemory;
+import org.mobilitydb.spark.MeosNative;
+import org.mobilitydb.spark.MeosThread;
+import org.apache.spark.sql.SparkSession;
+import org.apache.spark.sql.api.java.UDF2;
+import org.apache.spark.sql.types.DataTypes;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Spark SQL UDFs for temporal distance operations between tgeo/tnumber types.
+ *
+ * All functions return a hex-WKB tfloat (the distance evolving over time).
+ * Input geometry is accepted as WKT strings.
+ *
+ * MEOS function authority: meos/include/meos.h, meos/include/meos_geo.h
+ */
+public final class DistanceUDFs {
+
+ private DistanceUDFs() {}
+
+ // ------------------------------------------------------------------
+ // Spatial distance — tgeo × geometry
+ // ------------------------------------------------------------------
+
+ // tdistanceTgeoGeo(trip STRING, geomWkt STRING) → STRING (tfloat hex-WKB)
+ // MEOS: tdistance_tgeo_geo(const Temporal *, const GSERIALIZED *) → Temporal *
+ public static final UDF2 tdistanceTgeoGeo =
+ (trip, geomWkt) -> {
+ if (trip == null || geomWkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ Pointer gsptr = GeneratedFunctions.geo_from_text(geomWkt, 0);
+ if (gsptr == null) { MeosMemory.free(tptr); return null; }
+ try {
+ Pointer r = GeneratedFunctions.tdistance_tgeo_geo(tptr, gsptr);
+ if (r == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ } finally {
+ MeosMemory.free(r);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ MeosMemory.free(gsptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // Spatial distance — tgeo × tgeo
+ // ------------------------------------------------------------------
+
+ // tdistanceTgeoTgeo(trip1 STRING, trip2 STRING) → STRING (tfloat hex-WKB)
+ // MEOS: tdistance_tgeo_tgeo(const Temporal *, const Temporal *) → Temporal *
+ public static final UDF2 tdistanceTgeoTgeo =
+ (trip1, trip2) -> {
+ if (trip1 == null || trip2 == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(trip1);
+ if (p1 == null) return null;
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(trip2);
+ if (p2 == null) { MeosMemory.free(p1); return null; }
+ try {
+ Pointer r = GeneratedFunctions.tdistance_tgeo_tgeo(p1, p2);
+ if (r == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ } finally {
+ MeosMemory.free(r);
+ }
+ } finally {
+ MeosMemory.free(p1);
+ MeosMemory.free(p2);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // Number distance — tfloat × float
+ // ------------------------------------------------------------------
+
+ // tdistanceTfloatFloat(tfloat STRING, d DOUBLE) → STRING (tfloat hex-WKB)
+ // MEOS: tdistance_tfloat_float(const Temporal *, double) → Temporal *
+ public static final UDF2 tdistanceTfloatFloat =
+ (hex, d) -> {
+ if (hex == null || d == null) return null;
+ MeosThread.ensureReady();
+ Pointer ptr = GeneratedFunctions.temporal_from_hexwkb(hex);
+ if (ptr == null) return null;
+ try {
+ Pointer r = GeneratedFunctions.tdistance_tfloat_float(ptr, d);
+ if (r == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ } finally {
+ MeosMemory.free(r);
+ }
+ } finally {
+ MeosMemory.free(ptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // Number distance — tint × int
+ // ------------------------------------------------------------------
+
+ // tdistanceTintInt(tint STRING, i INT) → STRING (tint hex-WKB)
+ // MEOS: tdistance_tint_int(const Temporal *, int) → Temporal *
+ public static final UDF2 tdistanceTintInt =
+ (hex, i) -> {
+ if (hex == null || i == null) return null;
+ MeosThread.ensureReady();
+ Pointer ptr = GeneratedFunctions.temporal_from_hexwkb(hex);
+ if (ptr == null) return null;
+ try {
+ Pointer r = GeneratedFunctions.tdistance_tint_int(ptr, i);
+ if (r == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ } finally {
+ MeosMemory.free(r);
+ }
+ } finally {
+ MeosMemory.free(ptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // Number distance — tnumber × tnumber
+ // ------------------------------------------------------------------
+
+ // tdistanceTnumberTnumber(t1 STRING, t2 STRING) → STRING (tfloat hex-WKB)
+ // MEOS: tdistance_tnumber_tnumber(const Temporal *, const Temporal *) → Temporal *
+ public static final UDF2 tdistanceTnumberTnumber =
+ (hex1, hex2) -> {
+ if (hex1 == null || hex2 == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(hex1);
+ if (p1 == null) return null;
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(hex2);
+ if (p2 == null) { MeosMemory.free(p1); return null; }
+ try {
+ Pointer r = GeneratedFunctions.tdistance_tnumber_tnumber(p1, p2);
+ if (r == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ } finally {
+ MeosMemory.free(r);
+ }
+ } finally {
+ MeosMemory.free(p1);
+ MeosMemory.free(p2);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // Nearest approach distance (NAD) — returns Double (null on failure)
+ // MEOS returns DBL_MAX when the inputs never approach; map to null.
+ // ------------------------------------------------------------------
+
+ // nadTgeoGeo(trip STRING, geomWkt STRING) → DOUBLE
+ // MEOS: nad_tgeo_geo(const Temporal *, const GSERIALIZED *) → double
+ public static final UDF2 nadTgeoGeo =
+ (trip, geomWkt) -> {
+ if (trip == null || geomWkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ Pointer gsptr = GeneratedFunctions.geo_from_text(geomWkt, 0);
+ if (gsptr == null) { MeosMemory.free(tptr); return null; }
+ try {
+ double d = MeosNative.INSTANCE.nad_tgeo_geo(tptr, gsptr);
+ return d == Double.MAX_VALUE ? null : d;
+ } finally {
+ MeosMemory.free(tptr);
+ MeosMemory.free(gsptr);
+ }
+ };
+
+ // nadTgeoStbox(trip STRING, stboxHex STRING) → DOUBLE
+ // MEOS: nad_tgeo_stbox(const Temporal *, const STBox *) → double
+ public static final UDF2 nadTgeoStbox =
+ (trip, stboxHex) -> {
+ if (trip == null || stboxHex == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ Pointer sptr = GeneratedFunctions.stbox_from_hexwkb(stboxHex);
+ if (sptr == null) { MeosMemory.free(tptr); return null; }
+ try {
+ double d = MeosNative.INSTANCE.nad_tgeo_stbox(tptr, sptr);
+ return d == Double.MAX_VALUE ? null : d;
+ } finally {
+ MeosMemory.free(tptr);
+ MeosMemory.free(sptr);
+ }
+ };
+
+ // nadTgeoTgeo(trip1 STRING, trip2 STRING) → DOUBLE
+ // MEOS: nad_tgeo_tgeo(const Temporal *, const Temporal *) → double
+ public static final UDF2 nadTgeoTgeo =
+ (trip1, trip2) -> {
+ if (trip1 == null || trip2 == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(trip1);
+ if (p1 == null) return null;
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(trip2);
+ if (p2 == null) { MeosMemory.free(p1); return null; }
+ try {
+ double d = MeosNative.INSTANCE.nad_tgeo_tgeo(p1, p2);
+ return d == Double.MAX_VALUE ? null : d;
+ } finally {
+ MeosMemory.free(p1);
+ MeosMemory.free(p2);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // Nearest approach instant (NAI) — returns hex-WKB TInstant (STRING)
+ // ------------------------------------------------------------------
+
+ // naiTgeoGeo(trip STRING, geomWkt STRING) → STRING (TInstant hex-WKB)
+ // MEOS: nai_tgeo_geo(const Temporal *, const GSERIALIZED *) → TInstant *
+ public static final UDF2 naiTgeoGeo =
+ (trip, geomWkt) -> {
+ if (trip == null || geomWkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ Pointer gsptr = GeneratedFunctions.geo_from_text(geomWkt, 0);
+ if (gsptr == null) { MeosMemory.free(tptr); return null; }
+ try {
+ Pointer r = MeosNative.INSTANCE.nai_tgeo_geo(tptr, gsptr);
+ if (r == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ } finally {
+ MeosMemory.free(r);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ MeosMemory.free(gsptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // Shortest line — returns geometry (WKT) of the closest-approach segment
+ // ------------------------------------------------------------------
+
+ // shortestLineTgeoGeo(trip STRING, geomWkt STRING) → STRING (WKT geometry)
+ // MEOS: shortestline_tgeo_geo(const Temporal *, const GSERIALIZED *) → GSERIALIZED *
+ public static final UDF2 shortestLineTgeoGeo =
+ (trip, geomWkt) -> {
+ if (trip == null || geomWkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ Pointer gsptr = GeneratedFunctions.geo_from_text(geomWkt, 0);
+ if (gsptr == null) { MeosMemory.free(tptr); return null; }
+ try {
+ Pointer r = MeosNative.INSTANCE.shortestline_tgeo_geo(tptr, gsptr);
+ if (r == null) return null;
+ try {
+ return GeneratedFunctions.geo_as_text(r, 6);
+ } finally {
+ MeosMemory.free(r);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ MeosMemory.free(gsptr);
+ }
+ };
+
+ // shortestLineTgeoTgeo(trip1 STRING, trip2 STRING) → STRING (WKT geometry)
+ // MEOS: shortestline_tgeo_tgeo(const Temporal *, const Temporal *) → GSERIALIZED *
+ public static final UDF2 shortestLineTgeoTgeo =
+ (trip1, trip2) -> {
+ if (trip1 == null || trip2 == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(trip1);
+ if (p1 == null) return null;
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(trip2);
+ if (p2 == null) { MeosMemory.free(p1); return null; }
+ try {
+ Pointer r = GeneratedFunctions.shortestline_tgeo_tgeo(p1, p2);
+ if (r == null) return null;
+ try {
+ return GeneratedFunctions.geo_as_text(r, 6);
+ } finally {
+ MeosMemory.free(r);
+ }
+ } finally {
+ MeosMemory.free(p1);
+ MeosMemory.free(p2);
+ }
+ };
+
+ // naiTgeoTgeo(trip1 STRING, trip2 STRING) → STRING (TInstant hex-WKB)
+ // MEOS: nai_tgeo_tgeo(const Temporal *, const Temporal *) → TInstant *
+ public static final UDF2 naiTgeoTgeo =
+ (trip1, trip2) -> {
+ if (trip1 == null || trip2 == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(trip1);
+ if (p1 == null) return null;
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(trip2);
+ if (p2 == null) { MeosMemory.free(p1); return null; }
+ try {
+ Pointer r = MeosNative.INSTANCE.nai_tgeo_tgeo(p1, p2);
+ if (r == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ } finally {
+ MeosMemory.free(r);
+ }
+ } finally {
+ MeosMemory.free(p1);
+ MeosMemory.free(p2);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // Minimum spatial distance (MobilityDB PR #1007)
+ // minDistance({tgeo,geo},{tgeo,geo}) → double
+ // Per-pair scalar. For the GROUP-BY-over-cross-join shape that the
+ // canonical Q5 expresses, wrap with the built-in MIN aggregate:
+ //
+ // SELECT MIN(minDistance(t1.trip, t2.trip)) FROM ... GROUP BY ...
+ //
+ // The (tgeo, geo) overload reuses the NAD kernel — NAD reduces to
+ // spatial-min when one argument has no time dimension. The (tgeo,
+ // tgeo) overload calls the threshold-aware kernel with DBL_MAX so
+ // every call computes the exact per-pair minimum; the kernel still
+ // benefits from the outer STBox lower-bound prune.
+ // ------------------------------------------------------------------
+
+ // minDistance(trip STRING, geomWkt STRING) → DOUBLE
+ public static final UDF2 minDistanceTgeoGeo =
+ (trip, geomWkt) -> {
+ if (trip == null || geomWkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ Pointer gsptr = GeneratedFunctions.geo_from_text(geomWkt, 0);
+ if (gsptr == null) { MeosMemory.free(tptr); return null; }
+ try {
+ double d = MeosNative.INSTANCE.nad_tgeo_geo(tptr, gsptr);
+ return d == Double.MAX_VALUE ? null : d;
+ } finally {
+ MeosMemory.free(tptr);
+ MeosMemory.free(gsptr);
+ }
+ };
+
+ // minDistance(trip1 STRING, trip2 STRING) → DOUBLE
+ public static final UDF2 minDistanceTgeoTgeo =
+ (trip1, trip2) -> {
+ if (trip1 == null || trip2 == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(trip1);
+ if (p1 == null) return null;
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(trip2);
+ if (p2 == null) { MeosMemory.free(p1); return null; }
+ try {
+ double d = MeosNative.INSTANCE.mindistance_tgeo_tgeo(
+ p1, p2, Double.MAX_VALUE);
+ return d == Double.MAX_VALUE ? null : d;
+ } finally {
+ MeosMemory.free(p1);
+ MeosMemory.free(p2);
+ }
+ };
+
+ // minDistance(trips1 ARRAY, trips2 ARRAY) → DOUBLE
+ // The set-set spatial minimum distance: the minimum distance ever reached
+ // between any trip in the first set and any trip in the second. Backed by
+ // the MEOS Tgeoarr_tgeoarr_mindist kernel, which prunes far trip pairs by
+ // their STBox lower bound, so the N×N is handled inside one call rather than
+ // a SQL Cartesian join. Mirrors MobilityDB's minDistance(tgeompoint[],
+ // tgeompoint[]) so the BerlinMOD Q5 SQL is identical across the platforms:
+ // minDistance(array_agg(t1.trip), array_agg(t2.trip)) GROUP BY licence pair
+ public static final UDF2 minDistanceTgeoarrTgeoarr =
+ (o1, o2) -> {
+ if (o1 == null || o2 == null) return null;
+ List hex1 = toStringList(o1);
+ List hex2 = toStringList(o2);
+ if (hex1.isEmpty() || hex2.isEmpty()) return null;
+ MeosThread.ensureReady();
+ Runtime rt = Runtime.getSystemRuntime();
+ List p1 = new ArrayList<>(hex1.size());
+ List p2 = new ArrayList<>(hex2.size());
+ try {
+ for (String h : hex1) {
+ if (h == null) continue;
+ Pointer p = GeneratedFunctions.temporal_from_hexwkb(h);
+ if (p != null) p1.add(p);
+ }
+ for (String h : hex2) {
+ if (h == null) continue;
+ Pointer p = GeneratedFunctions.temporal_from_hexwkb(h);
+ if (p != null) p2.add(p);
+ }
+ if (p1.isEmpty() || p2.isEmpty()) return null;
+ Pointer arr1 = Memory.allocateDirect(rt, (long) p1.size() * Long.BYTES);
+ Pointer arr2 = Memory.allocateDirect(rt, (long) p2.size() * Long.BYTES);
+ for (int i = 0; i < p1.size(); i++) arr1.putPointer((long) i * Long.BYTES, p1.get(i));
+ for (int i = 0; i < p2.size(); i++) arr2.putPointer((long) i * Long.BYTES, p2.get(i));
+ double d = GeneratedFunctions.mindistance_tgeoarr_tgeoarr(
+ arr1, p1.size(), arr2, p2.size());
+ // arr1/arr2 are GC-managed Memory.allocateDirect buffers; keep them
+ // strongly reachable until the native call returns, or under GC
+ // pressure the JIT can reclaim the backing memory mid-call and the
+ // kernel reads a freed Temporal*[] (SIGSEGV).
+ java.lang.ref.Reference.reachabilityFence(arr1);
+ java.lang.ref.Reference.reachabilityFence(arr2);
+ return d == Double.MAX_VALUE ? null : d;
+ } finally {
+ for (Pointer p : p1) MeosMemory.free(p);
+ for (Pointer p : p2) MeosMemory.free(p);
+ }
+ };
+
+ /** Convert a Spark array column argument (Scala Seq / Java List / array) to a List. */
+ @SuppressWarnings("unchecked")
+ private static List toStringList(Object o) {
+ if (o instanceof List) return (List) o;
+ if (o instanceof scala.collection.Seq) {
+ // Iterate the Scala Seq directly — works on Scala 2.12 and 2.13 alike,
+ // unlike the version-specific CollectionConverters classes.
+ scala.collection.Iterator it = ((scala.collection.Seq) o).iterator();
+ List l = new ArrayList<>();
+ while (it.hasNext()) l.add(it.next());
+ return l;
+ }
+ if (o instanceof Object[]) {
+ List l = new ArrayList<>();
+ for (Object x : (Object[]) o) l.add((String) x);
+ return l;
+ }
+ throw new IllegalArgumentException("minDistance: unexpected array arg type " + o.getClass());
+ }
+
+ public static void registerAll(SparkSession spark) {
+ spark.udf().register("tdistanceTgeoGeo", tdistanceTgeoGeo, DataTypes.StringType);
+ spark.udf().register("tdistanceTgeoTgeo", tdistanceTgeoTgeo, DataTypes.StringType);
+ spark.udf().register("tdistanceTfloatFloat", tdistanceTfloatFloat, DataTypes.StringType);
+ spark.udf().register("tdistanceTintInt", tdistanceTintInt, DataTypes.StringType);
+ spark.udf().register("tdistanceTnumberTnumber", tdistanceTnumberTnumber, DataTypes.StringType);
+
+ spark.udf().register("nadTgeoGeo", nadTgeoGeo, DataTypes.DoubleType);
+ spark.udf().register("nadTgeoStbox", nadTgeoStbox, DataTypes.DoubleType);
+ spark.udf().register("nadTgeoTgeo", nadTgeoTgeo, DataTypes.DoubleType);
+ spark.udf().register("naiTgeoGeo", naiTgeoGeo, DataTypes.StringType);
+ spark.udf().register("naiTgeoTgeo", naiTgeoTgeo, DataTypes.StringType);
+ spark.udf().register("shortestLineTgeoGeo", shortestLineTgeoGeo, DataTypes.StringType);
+ spark.udf().register("shortestLineTgeoTgeo", shortestLineTgeoTgeo, DataTypes.StringType);
+
+ spark.udf().register("minDistanceTgeoGeo", minDistanceTgeoGeo, DataTypes.DoubleType);
+ spark.udf().register("minDistanceTgeoTgeo", minDistanceTgeoTgeo, DataTypes.DoubleType);
+ spark.udf().register("minDistanceTgeoarrTgeoarr", minDistanceTgeoarrTgeoarr, DataTypes.DoubleType);
+
+ // MobilityDB SQL bare-name aliases.
+ // The portable operator alias `nearestApproachDistance` (|=|) is
+ // registered by org.mobilitydb.spark.portable.PortableOperatorAliasUDFs,
+ // reusing this same nadTgeoGeo backing field.
+ spark.udf().register("nearestApproachInstant", naiTgeoGeo, DataTypes.StringType);
+ spark.udf().register("shortestLine", shortestLineTgeoGeo, DataTypes.StringType);
+ // Bare `minDistance` resolves to the set-set array form (the BerlinMOD Q5
+ // spatial-min over two trip sets); Spark cannot overload by signature, and
+ // the scalar forms stay reachable as minDistanceTgeoTgeo / minDistanceTgeoGeo.
+ spark.udf().register("minDistance", minDistanceTgeoarrTgeoarr, DataTypes.DoubleType);
+ }
+}
diff --git a/src/main/java/org/mobilitydb/spark/geo/GeoAffineUDFs.java b/src/main/java/org/mobilitydb/spark/geo/GeoAffineUDFs.java
new file mode 100644
index 00000000..b273cdc9
--- /dev/null
+++ b/src/main/java/org/mobilitydb/spark/geo/GeoAffineUDFs.java
@@ -0,0 +1,176 @@
+/*****************************************************************************
+ *
+ * This MobilityDB code is provided under The PostgreSQL License.
+ * Copyright (c) 2020-2026, 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.
+ *
+ *****************************************************************************/
+
+package org.mobilitydb.spark.geo;
+
+import functions.GeneratedFunctions;
+import jnr.ffi.Pointer;
+import jnr.ffi.Runtime;
+import org.mobilitydb.spark.MeosMemory;
+import org.mobilitydb.spark.MeosNative;
+import org.mobilitydb.spark.MeosThread;
+import org.apache.spark.sql.SparkSession;
+import org.apache.spark.sql.api.java.UDF2;
+import org.apache.spark.sql.api.java.UDF3;
+import org.apache.spark.sql.api.java.UDF4;
+import org.apache.spark.sql.api.java.UDF5;
+import org.apache.spark.sql.api.java.UDF13;
+import org.apache.spark.sql.types.DataTypes;
+
+/**
+ * Spark SQL UDFs for affine transformations on tgeo: translate, rotate
+ * (2D), rotateX/Y/Z (3D), transscale.
+ *
+ * MobilityDB SQL composes these from MEOS's single tgeo_affine(Temporal*,
+ * AFFINE*) primitive. We build the AFFINE struct in direct memory and call
+ * tgeo_affine via MeosNative.
+ *
+ * AFFINE layout (96 bytes, all doubles):
+ * afac bfac cfac — row 0 spatial coefficients
+ * dfac efac ffac — row 1
+ * gfac hfac ifac — row 2
+ * xoff yoff zoff — translation offsets
+ *
+ * Identity matrix: afac=efac=ifac=1, all other coefficients 0.
+ */
+public final class GeoAffineUDFs {
+
+ private GeoAffineUDFs() {}
+
+ private static Pointer makeAffine(double afac, double bfac, double cfac,
+ double dfac, double efac, double ffac,
+ double gfac, double hfac, double ifac,
+ double xoff, double yoff, double zoff) {
+ Pointer aff = Runtime.getSystemRuntime().getMemoryManager().allocateDirect(96);
+ aff.putDouble(0, afac);
+ aff.putDouble(8, bfac);
+ aff.putDouble(16, cfac);
+ aff.putDouble(24, dfac);
+ aff.putDouble(32, efac);
+ aff.putDouble(40, ffac);
+ aff.putDouble(48, gfac);
+ aff.putDouble(56, hfac);
+ aff.putDouble(64, ifac);
+ aff.putDouble(72, xoff);
+ aff.putDouble(80, yoff);
+ aff.putDouble(88, zoff);
+ return aff;
+ }
+
+ private static String applyAffine(String hex, Pointer affine) {
+ Pointer t = GeneratedFunctions.temporal_from_hexwkb(hex);
+ if (t == null) return null;
+ try {
+ Pointer r = MeosNative.INSTANCE.tgeo_affine(t, affine);
+ if (r == null) return null;
+ try { return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0); }
+ finally { MeosMemory.free(r); }
+ } finally { MeosMemory.free(t); }
+ }
+
+ // translate(temporal, dx, dy) — 2D translation (z unchanged)
+ public static final UDF3 translate2 =
+ (hex, dx, dy) -> {
+ if (hex == null || dx == null || dy == null) return null;
+ MeosThread.ensureReady();
+ return applyAffine(hex, makeAffine(1,0,0, 0,1,0, 0,0,1, dx, dy, 0));
+ };
+
+ // translate(temporal, dx, dy, dz) — 3D translation
+ public static final UDF4 translate3 =
+ (hex, dx, dy, dz) -> {
+ if (hex == null || dx == null || dy == null || dz == null) return null;
+ MeosThread.ensureReady();
+ return applyAffine(hex, makeAffine(1,0,0, 0,1,0, 0,0,1, dx, dy, dz));
+ };
+
+ // rotate(temporal, angleRadians) — 2D rotation around origin (z unchanged)
+ public static final UDF2 rotate =
+ (hex, angle) -> {
+ if (hex == null || angle == null) return null;
+ MeosThread.ensureReady();
+ double c = Math.cos(angle), s = Math.sin(angle);
+ return applyAffine(hex, makeAffine(c,-s,0, s,c,0, 0,0,1, 0, 0, 0));
+ };
+
+ // rotateX(temporal, angleRadians) — 3D rotation about x-axis
+ public static final UDF2 rotateX =
+ (hex, angle) -> {
+ if (hex == null || angle == null) return null;
+ MeosThread.ensureReady();
+ double c = Math.cos(angle), s = Math.sin(angle);
+ return applyAffine(hex, makeAffine(1,0,0, 0,c,-s, 0,s,c, 0, 0, 0));
+ };
+
+ // rotateY(temporal, angleRadians) — 3D rotation about y-axis
+ public static final UDF2 rotateY =
+ (hex, angle) -> {
+ if (hex == null || angle == null) return null;
+ MeosThread.ensureReady();
+ double c = Math.cos(angle), s = Math.sin(angle);
+ return applyAffine(hex, makeAffine(c,0,s, 0,1,0, -s,0,c, 0, 0, 0));
+ };
+
+ // rotateZ(temporal, angleRadians) — 3D rotation about z-axis
+ public static final UDF2 rotateZ =
+ (hex, angle) -> {
+ if (hex == null || angle == null) return null;
+ MeosThread.ensureReady();
+ double c = Math.cos(angle), s = Math.sin(angle);
+ return applyAffine(hex, makeAffine(c,-s,0, s,c,0, 0,0,1, 0, 0, 0));
+ };
+
+ // transscale(temporal, dx, dy, sx, sy) — translate then scale
+ // Equivalent affine: ((px+dx)*sx, (py+dy)*sy) = sx*px + sx*dx, sy*py + sy*dy
+ public static final UDF5 transscale =
+ (hex, dx, dy, sx, sy) -> {
+ if (hex == null || dx == null || dy == null || sx == null || sy == null) return null;
+ MeosThread.ensureReady();
+ return applyAffine(hex, makeAffine(sx,0,0, 0,sy,0, 0,0,1, sx*dx, sy*dy, 0));
+ };
+
+ // affine(temporal, afac, bfac, cfac, dfac, efac, ffac, gfac, hfac, ifac, xoff, yoff, zoff)
+ public static final UDF13 affine =
+ (hex, afac, bfac, cfac, dfac, efac, ffac, gfac, hfac, ifac, xoff, yoff, zoff) -> {
+ if (hex == null || afac == null || bfac == null || cfac == null || dfac == null
+ || efac == null || ffac == null || gfac == null || hfac == null || ifac == null
+ || xoff == null || yoff == null || zoff == null) return null;
+ MeosThread.ensureReady();
+ return applyAffine(hex, makeAffine(afac, bfac, cfac, dfac, efac, ffac,
+ gfac, hfac, ifac, xoff, yoff, zoff));
+ };
+
+ public static void registerAll(SparkSession spark) {
+ spark.udf().register("translate", translate2, DataTypes.StringType);
+ spark.udf().register("translate3", translate3, DataTypes.StringType);
+ spark.udf().register("rotate", rotate, DataTypes.StringType);
+ spark.udf().register("rotateX", rotateX, DataTypes.StringType);
+ spark.udf().register("rotateY", rotateY, DataTypes.StringType);
+ spark.udf().register("rotateZ", rotateZ, DataTypes.StringType);
+ spark.udf().register("transscale", transscale, DataTypes.StringType);
+ spark.udf().register("affine", affine, DataTypes.StringType);
+ }
+}
diff --git a/src/main/java/org/mobilitydb/spark/geo/GeoAnalyticsUDFs.java b/src/main/java/org/mobilitydb/spark/geo/GeoAnalyticsUDFs.java
new file mode 100644
index 00000000..a8ab1da7
--- /dev/null
+++ b/src/main/java/org/mobilitydb/spark/geo/GeoAnalyticsUDFs.java
@@ -0,0 +1,494 @@
+/*****************************************************************************
+ *
+ * This MobilityDB code is provided under The PostgreSQL License.
+ * Copyright (c) 2020-2026, 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.
+ *
+ *****************************************************************************/
+
+package org.mobilitydb.spark.geo;
+
+import functions.GeneratedFunctions;
+import jnr.ffi.Pointer;
+import jnr.ffi.Runtime;
+import org.apache.spark.sql.SparkSession;
+import org.apache.spark.sql.api.java.*;
+import org.apache.spark.sql.types.DataTypes;
+import org.mobilitydb.spark.MeosMemory;
+import org.mobilitydb.spark.MeosThread;
+
+/**
+ * Spark SQL UDFs for high-value spatial analytics on temporal geometry types.
+ *
+ * Coverage:
+ * - Plain geometry operations: geomBuffer, geomConvexHull, geomIntersection
+ * - SRID / CRS management: setSRID, transform
+ * - Text output: asText, asEWKT
+ * - Elevation restriction: atElevation (3-D trips)
+ * - Temporal spatial predicates (TBool): tContains, tCovers, tDwithin
+ * - Bearing analytics: bearingToPoint, bearing
+ * - Spatial aggregates: twCentroid
+ *
+ * Storage convention:
+ * tgeompoint → hex-WKB STRING (temporal_as_hexwkb)
+ * geometry → WKT STRING (parsed via geo_from_text)
+ * TBool result → hex-WKB STRING
+ * TFloat result → hex-WKB STRING
+ *
+ * MEOS function authority: meos/include/meos_geo.h
+ */
+public final class GeoAnalyticsUDFs {
+
+ private GeoAnalyticsUDFs() {}
+
+ // Convenience: decode a trip and extract its SRID from its bounding box
+ private static int tripSrid(Pointer tptr) {
+ Pointer bbox = GeneratedFunctions.tspatial_to_stbox(tptr);
+ return (bbox != null) ? GeneratedFunctions.stbox_srid(bbox) : 0;
+ }
+
+ // ------------------------------------------------------------------
+ // GEOMETRY OPERATIONS (plain geometry in/out, WKT strings)
+ //
+ // MEOS: geom_buffer(gs, size, params) meos_geo.h:401
+ // geom_convex_hull(gs) meos_geo.h:403
+ // geom_intersection2d(gs1, gs2) meos_geo.h:405
+ // ------------------------------------------------------------------
+
+ // geomBuffer("POLYGON((...))", 100.0) → WKT of buffered polygon
+ public static final UDF2 geomBuffer =
+ (geomWkt, radius) -> {
+ if (geomWkt == null || radius == null) return null;
+ MeosThread.ensureReady();
+ Pointer g = GeneratedFunctions.geo_from_text(geomWkt, 0);
+ if (g == null) return null;
+ Pointer r = GeneratedFunctions.geom_buffer(g, radius, "");
+ if (r == null) return null;
+ return GeneratedFunctions.geo_as_text(r, 15);
+ };
+
+ // geomConvexHull("MULTIPOINT((0 0),(1 1),(0 1))") → "POLYGON((0 0,0 1,1 1,0 0))"
+ public static final UDF1 geomConvexHull =
+ (geomWkt) -> {
+ if (geomWkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer g = GeneratedFunctions.geo_from_text(geomWkt, 0);
+ if (g == null) return null;
+ Pointer r = GeneratedFunctions.geom_convex_hull(g);
+ if (r == null) return null;
+ return GeneratedFunctions.geo_as_text(r, 15);
+ };
+
+ // geomIntersection("POLYGON(...)", "POLYGON(...)") → WKT of intersection
+ public static final UDF2 geomIntersection =
+ (geomWkt1, geomWkt2) -> {
+ if (geomWkt1 == null || geomWkt2 == null) return null;
+ MeosThread.ensureReady();
+ Pointer g1 = GeneratedFunctions.geo_from_text(geomWkt1, 0);
+ Pointer g2 = GeneratedFunctions.geo_from_text(geomWkt2, 0);
+ if (g1 == null || g2 == null) return null;
+ Pointer r = GeneratedFunctions.geom_intersection2d(g1, g2);
+ if (r == null) return null;
+ return GeneratedFunctions.geo_as_text(r, 15);
+ };
+
+ // ------------------------------------------------------------------
+ // SRID / CRS MANAGEMENT (temporal in/out, hex-WKB strings)
+ //
+ // MEOS: tspatial_set_srid(temp, srid) meos_geo.h:687
+ // tspatial_transform(temp, srid) meos_geo.h:688
+ // ------------------------------------------------------------------
+
+ // setSRID(trip, 4326) → same trip with SRID label changed (no reprojection)
+ public static final UDF2 setSRID =
+ (trip, srid) -> {
+ if (trip == null || srid == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ Pointer r = GeneratedFunctions.tspatial_set_srid(tptr, srid);
+ if (r == null) return null;
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ };
+
+ // transform(trip, 4326) → trip reprojected to SRID 4326
+ public static final UDF2 transform =
+ (trip, srid) -> {
+ if (trip == null || srid == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ Pointer r = GeneratedFunctions.tspatial_transform(tptr, srid);
+ if (r == null) return null;
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ };
+
+ // ------------------------------------------------------------------
+ // TEXT OUTPUT (temporal in, WKT/EWKT string out)
+ //
+ // MEOS: tspatial_as_text(temp, maxdd) meos_geo.h:620
+ // tspatial_as_ewkt(temp, maxdd) meos_geo.h:619
+ // ------------------------------------------------------------------
+
+ // asText(trip, 6) → "[POINT(1.234567 2.345678)@2020-01-01, ...]"
+ public static final UDF2 asText =
+ (trip, maxdd) -> {
+ if (trip == null || maxdd == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ return GeneratedFunctions.tspatial_as_text(tptr, maxdd);
+ };
+
+ // asEWKT(trip, 6) → "[SRID=4326;POINT(...)@2020-01-01, ...]"
+ public static final UDF2 asEWKT =
+ (trip, maxdd) -> {
+ if (trip == null || maxdd == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ return GeneratedFunctions.tspatial_as_ewkt(tptr, maxdd);
+ };
+
+ // ------------------------------------------------------------------
+ // ELEVATION RESTRICTION (3-D tgeompoint, hex-WKB out)
+ //
+ // MEOS: tpoint_at_elevation(temp, zspan) meos_geo.h:699
+ // floatspan_make(lower, upper, lower_inc, upper_inc)
+ //
+ // zmin/zmax define the closed [zmin, zmax] elevation band.
+ // Returns null when no portion of the trip falls in the band.
+ // ------------------------------------------------------------------
+
+ // atElevation(trip, 0.0, 100.0) → sub-trip within elevation band [0,100]
+ public static final UDF3 atElevation =
+ (trip, zmin, zmax) -> {
+ if (trip == null || zmin == null || zmax == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ Pointer zspan = GeneratedFunctions.floatspan_make(zmin, zmax, true, true);
+ if (zspan == null) return null;
+ Pointer r = GeneratedFunctions.tpoint_at_elevation(tptr, zspan);
+ if (r == null) return null;
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ };
+
+ // ------------------------------------------------------------------
+ // TEMPORAL SPATIAL PREDICATES (TBool hex-WKB out)
+ //
+ // MEOS: tcontains_geo_tgeo(gs, temp) meos_geo.h:837
+ // tcovers_tgeo_tgeo(temp1, temp2) meos_geo.h:842
+ // tdwithin_tgeo_tgeo(temp1, temp2, dist) meos_geo.h:848
+ //
+ // These return temporal booleans: at each instant, whether the
+ // predicate holds. Result is encoded as hex-WKB for downstream UDFs.
+ // ------------------------------------------------------------------
+
+ // tContains("POLYGON(...)", trip) → tbool hex-WKB: true at instants inside polygon
+ public static final UDF2 tContains =
+ (geomWkt, trip) -> {
+ if (geomWkt == null || trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ int srid = tripSrid(tptr);
+ Pointer g = GeneratedFunctions.geo_from_text(geomWkt, srid);
+ if (g == null) return null;
+ Pointer r = GeneratedFunctions.tcontains_geo_tgeo(g, tptr);
+ if (r == null) return null;
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ };
+
+ // tCovers(trip1, trip2) → tbool hex-WKB: true at instants where trip1 covers trip2
+ public static final UDF2 tCovers =
+ (trip1, trip2) -> {
+ if (trip1 == null || trip2 == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(trip1);
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(trip2);
+ if (p1 == null || p2 == null) return null;
+ Pointer r = GeneratedFunctions.tcovers_tgeo_tgeo(p1, p2);
+ if (r == null) return null;
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ };
+
+ // tDwithin(trip1, trip2, 100.0) → tbool hex-WKB: true at instants within 100 units
+ public static final UDF3 tDwithin =
+ (trip1, trip2, dist) -> {
+ if (trip1 == null || trip2 == null || dist == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(trip1);
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(trip2);
+ if (p1 == null || p2 == null) return null;
+ Pointer r = GeneratedFunctions.tdwithin_tgeo_tgeo(p1, p2, dist.doubleValue());
+ if (r == null) return null;
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ };
+
+ // ------------------------------------------------------------------
+ // BEARING ANALYTICS (TFloat hex-WKB out)
+ //
+ // MEOS: bearing_tpoint_point(temp, gs, invert) meos_geo.h
+ // bearing_tpoint_tpoint(temp1, temp2) meos_geo.h
+ //
+ // bearing_tpoint_point: invert=false → bearing FROM trip TO point.
+ // ------------------------------------------------------------------
+
+ // bearingToPoint(trip, "POINT(lon lat)") → tfloat hex-WKB, bearing in radians
+ public static final UDF2 bearingToPoint =
+ (trip, geomWkt) -> {
+ if (trip == null || geomWkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ int srid = tripSrid(tptr);
+ Pointer g = GeneratedFunctions.geo_from_text(geomWkt, srid);
+ if (g == null) return null;
+ Pointer r = GeneratedFunctions.bearing_tpoint_point(tptr, g, false);
+ if (r == null) return null;
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ };
+
+ // bearing(trip1, trip2) → tfloat hex-WKB, instantaneous bearing between trips
+ public static final UDF2 bearing =
+ (trip1, trip2) -> {
+ if (trip1 == null || trip2 == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(trip1);
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(trip2);
+ if (p1 == null || p2 == null) return null;
+ Pointer r = GeneratedFunctions.bearing_tpoint_tpoint(p1, p2);
+ if (r == null) return null;
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ };
+
+ // ------------------------------------------------------------------
+ // SPATIAL AGGREGATES (geometry WKT out)
+ //
+ // MEOS: tpoint_twcentroid(temp) meos_geo.h
+ //
+ // Returns the time-weighted centroid of the trip as a WKT POINT string.
+ // ------------------------------------------------------------------
+
+ // twCentroid(trip) → WKT POINT of the time-weighted centroid
+ public static final UDF1 twCentroid =
+ (trip) -> {
+ if (trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ Pointer g = GeneratedFunctions.tpoint_twcentroid(tptr);
+ if (g == null) return null;
+ return GeneratedFunctions.geo_as_text(g, 15);
+ };
+
+ // ------------------------------------------------------------------
+ // geoSame(wkt1 STRING, wkt2 STRING) → BOOLEAN
+ //
+ // Returns true if two geometries are exactly equal (same type, coordinates,
+ // and SRID).
+ //
+ // MEOS: geo_same(const GSERIALIZED *, const GSERIALIZED *) → bool
+ // ------------------------------------------------------------------
+ public static final UDF2 geoSame =
+ (wkt1, wkt2) -> {
+ if (wkt1 == null || wkt2 == null) return null;
+ MeosThread.ensureReady();
+ Pointer g1 = GeneratedFunctions.geo_from_text(wkt1, 0);
+ if (g1 == null) return null;
+ try {
+ Pointer g2 = GeneratedFunctions.geo_from_text(wkt2, 0);
+ if (g2 == null) return null;
+ try {
+ return GeneratedFunctions.geo_same(g1, g2);
+ } finally {
+ MeosMemory.free(g2);
+ }
+ } finally {
+ MeosMemory.free(g1);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // tpointConvexHull(trip STRING) → STRING (hex-EWKB geometry)
+ //
+ // Returns the convex hull of the trajectory of the temporal point.
+ //
+ // MEOS: tgeo_convex_hull(const Temporal *) → GSERIALIZED *
+ // geo_as_hexewkb(const GSERIALIZED *, const char *endian)
+ // ------------------------------------------------------------------
+ public static final UDF1 tpointConvexHull =
+ (trip) -> {
+ if (trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer gptr = GeneratedFunctions.tgeo_convex_hull(tptr);
+ if (gptr == null) return null;
+ try {
+ return GeneratedFunctions.geo_as_hexewkb(gptr, null);
+ } finally {
+ MeosMemory.free(gptr);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // tpointExpandSpace(trip STRING, distance DOUBLE) → STRING (hex-WKB STBOX)
+ //
+ // Returns the spatiotemporal bounding box of the temporal point expanded
+ // by distance in each spatial dimension.
+ //
+ // MEOS: tspatial_to_stbox(const Temporal *) → STBox *
+ // stbox_expand_space(const STBox *, double d) → STBox *
+ // stbox_as_hexwkb(const STBox *, uint8_t variant, size_t *size)
+ // ------------------------------------------------------------------
+ public static final UDF2 tpointExpandSpace =
+ (trip, distance) -> {
+ if (trip == null || distance == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer stbox = GeneratedFunctions.tspatial_to_stbox(tptr);
+ if (stbox == null) return null;
+ try {
+ Pointer expanded = GeneratedFunctions.stbox_expand_space(stbox, distance);
+ if (expanded == null) return null;
+ try {
+ Pointer sizeOut = Runtime.getSystemRuntime().getMemoryManager().allocateDirect(8);
+ return GeneratedFunctions.stbox_as_hexwkb(expanded, (byte) 0, sizeOut);
+ } finally {
+ MeosMemory.free(expanded);
+ }
+ } finally {
+ MeosMemory.free(stbox);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // REGISTRATION
+ // ------------------------------------------------------------------
+
+ public static void registerAll(SparkSession spark) {
+ // geometry operations
+ spark.udf().register("geomBuffer", geomBuffer, DataTypes.StringType);
+ spark.udf().register("geomConvexHull", geomConvexHull, DataTypes.StringType);
+ spark.udf().register("geomIntersection", geomIntersection, DataTypes.StringType);
+ // SRID management
+ spark.udf().register("setSRID", setSRID, DataTypes.StringType);
+ spark.udf().register("transform", transform, DataTypes.StringType);
+ // text output
+ spark.udf().register("asText", asText, DataTypes.StringType);
+ spark.udf().register("asEWKT", asEWKT, DataTypes.StringType);
+ // elevation restriction
+ spark.udf().register("atElevation", atElevation, DataTypes.StringType);
+ // temporal predicates
+ spark.udf().register("tContains", tContains, DataTypes.StringType);
+ spark.udf().register("tCovers", tCovers, DataTypes.StringType);
+ spark.udf().register("tDwithin", tDwithin, DataTypes.StringType);
+ // bearing
+ spark.udf().register("bearingToPoint", bearingToPoint, DataTypes.StringType);
+ spark.udf().register("bearing", bearing, DataTypes.StringType);
+ // spatial aggregate
+ spark.udf().register("twCentroid", twCentroid, DataTypes.StringType);
+ // geometry equality
+ spark.udf().register("geoSame", geoSame, DataTypes.BooleanType);
+ // tpoint analytics
+ spark.udf().register("tpointConvexHull", tpointConvexHull, DataTypes.StringType);
+ spark.udf().register("tpointExpandSpace", tpointExpandSpace, DataTypes.StringType);
+ // tpoint minus geom + bearing direction
+ spark.udf().register("minusGeometry", minusGeometry, DataTypes.StringType);
+ spark.udf().register("tdirection", tdirection, DataTypes.DoubleType);
+ // transformPipeline (PROJ pipeline string)
+ spark.udf().register("transformPipeline", tpointTransformPipeline, DataTypes.StringType);
+ spark.udf().register("stboxTransformPipeline", stboxTransformPipeline, DataTypes.StringType);
+ }
+
+ public static final org.apache.spark.sql.api.java.UDF4
+ tpointTransformPipeline = (trip, pipeline, srid, isForward) -> {
+ if (trip == null || pipeline == null) return null;
+ org.mobilitydb.spark.MeosThread.ensureReady();
+ jnr.ffi.Pointer t = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (t == null) return null;
+ try {
+ jnr.ffi.Pointer r = GeneratedFunctions.tspatial_transform_pipeline(t, pipeline,
+ srid == null ? 0 : srid, isForward == null ? true : isForward);
+ if (r == null) return null;
+ try { return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0); }
+ finally { org.mobilitydb.spark.MeosMemory.free(r); }
+ } finally { org.mobilitydb.spark.MeosMemory.free(t); }
+ };
+
+ public static final org.apache.spark.sql.api.java.UDF4
+ stboxTransformPipeline = (stboxHex, pipeline, srid, isForward) -> {
+ if (stboxHex == null || pipeline == null) return null;
+ org.mobilitydb.spark.MeosThread.ensureReady();
+ jnr.ffi.Pointer s = GeneratedFunctions.stbox_from_hexwkb(stboxHex);
+ if (s == null) return null;
+ try {
+ jnr.ffi.Pointer r = GeneratedFunctions.stbox_transform_pipeline(s, pipeline,
+ srid == null ? 0 : srid, isForward == null ? true : isForward);
+ if (r == null) return null;
+ try {
+ jnr.ffi.Pointer sizeOut = jnr.ffi.Runtime.getSystemRuntime().getMemoryManager().allocateDirect(8);
+ return GeneratedFunctions.stbox_as_hexwkb(r, (byte) 0, sizeOut);
+ } finally { org.mobilitydb.spark.MeosMemory.free(r); }
+ } finally { org.mobilitydb.spark.MeosMemory.free(s); }
+ };
+
+ // minusGeometry(tpoint, geomWkt) → tpoint with geometry subtracted (or null if total)
+ public static final org.apache.spark.sql.api.java.UDF2 minusGeometry =
+ (trip, geomWkt) -> {
+ if (trip == null || geomWkt == null) return null;
+ org.mobilitydb.spark.MeosThread.ensureReady();
+ jnr.ffi.Pointer t = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (t == null) return null;
+ jnr.ffi.Pointer g = GeneratedFunctions.geo_from_text(geomWkt, 0);
+ if (g == null) { org.mobilitydb.spark.MeosMemory.free(t); return null; }
+ try {
+ jnr.ffi.Pointer r = org.mobilitydb.spark.MeosNative.INSTANCE.tpoint_minus_geom(t, g);
+ if (r == null) return null;
+ try { return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0); }
+ finally { org.mobilitydb.spark.MeosMemory.free(r); }
+ } finally { org.mobilitydb.spark.MeosMemory.free(t, g); }
+ };
+
+ // tdirection(tpoint) → bearing in radians, or null if not defined
+ public static final org.apache.spark.sql.api.java.UDF1 tdirection =
+ (trip) -> {
+ if (trip == null) return null;
+ org.mobilitydb.spark.MeosThread.ensureReady();
+ jnr.ffi.Pointer t = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (t == null) return null;
+ try {
+ jnr.ffi.Pointer outBuf = jnr.ffi.Runtime.getSystemRuntime().getMemoryManager().allocateDirect(8);
+ boolean ok = org.mobilitydb.spark.MeosNative.INSTANCE.tpoint_direction(t, outBuf);
+ return ok ? outBuf.getDouble(0) : null;
+ } finally { org.mobilitydb.spark.MeosMemory.free(t); }
+ };
+}
diff --git a/src/main/java/org/mobilitydb/spark/geo/GeoUDFs.java b/src/main/java/org/mobilitydb/spark/geo/GeoUDFs.java
new file mode 100644
index 00000000..d1ffa1a0
--- /dev/null
+++ b/src/main/java/org/mobilitydb/spark/geo/GeoUDFs.java
@@ -0,0 +1,953 @@
+/*****************************************************************************
+ *
+ * This MobilityDB code is provided under The PostgreSQL License.
+ * Copyright (c) 2020-2026, 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.
+ *
+ *****************************************************************************/
+
+package org.mobilitydb.spark.geo;
+
+import functions.GeneratedFunctions;
+import jnr.ffi.Pointer;
+import jnr.ffi.Runtime;
+import org.apache.spark.sql.api.java.*;
+import org.apache.spark.sql.types.DataTypes;
+import org.mobilitydb.spark.MeosMemory;
+import org.mobilitydb.spark.MeosThread;
+
+/**
+ * Spark SQL UDFs for spatial (geometry) operations on tgeompoint.
+ *
+ * Storage convention:
+ * tgeompoint → hex-WKB STRING (temporal_as_hexwkb / temporal_from_hexwkb)
+ * geometry → WKT STRING (e.g. "POINT(50 0)", parsed via geo_from_text)
+ *
+ * Memory management: every native Pointer allocated by MEOS must be freed via
+ * MeosMemory.free() in a finally block. MEOS standalone mode uses the system
+ * malloc/free (palloc/pfree map to malloc/free outside PostgreSQL), so native
+ * objects are NOT garbage-collected by the JVM. Failing to free them causes
+ * the native heap to grow without bound across UDF calls (one leaked object per
+ * row × millions of rows in cross-join queries like Q2/Q4/Q5/Q6).
+ *
+ * MEOS function authority: meos/include/meos_geo.h
+ */
+public final class GeoUDFs {
+
+ private GeoUDFs() {}
+
+ // ------------------------------------------------------------------
+ // eIntersects(trip STRING, geomWkt STRING) → BOOLEAN
+ //
+ // Returns true if the trip's trajectory ever intersects geomWkt.
+ //
+ // SRID handling: extract the trip's SRID from its bounding box and
+ // pass it to geo_from_text so MEOS's ensure_same_srid check passes.
+ // BerlinMOD trips use SRID=3857; query regions use SRID=0 (plain WKT).
+ //
+ // For geodetic trips (tgeogpoint), the geometry is promoted to geography
+ // via geom_to_geog() to avoid MEOS "Operation on mixed SRID" errors.
+ //
+ // MEOS: geo_from_text, tspatial_to_stbox, stbox_srid, stbox_isgeodetic,
+ // geom_to_geog, eintersects_tgeo_geo (meos_geo.h)
+ // ------------------------------------------------------------------
+ public static final UDF2 eIntersects =
+ (trip, geomWkt) -> {
+ if (trip == null || geomWkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer bbox = GeneratedFunctions.tspatial_to_stbox(tptr);
+ boolean geodetic = (bbox != null && GeneratedFunctions.stbox_isgeodetic(bbox));
+ int srid = (bbox != null) ? GeneratedFunctions.stbox_srid(bbox) : 0;
+ MeosMemory.free(bbox);
+ Pointer gptr = GeneratedFunctions.geo_from_text(geomWkt, srid);
+ if (gptr == null) return null;
+ if (geodetic) {
+ Pointer geog = GeneratedFunctions.geom_to_geog(gptr);
+ MeosMemory.free(gptr);
+ gptr = geog;
+ if (gptr == null) return null;
+ }
+ try {
+ return GeneratedFunctions.eintersects_tgeo_geo(tptr, gptr) == 1;
+ } finally {
+ MeosMemory.free(gptr);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // nearestApproachDistance(t1 STRING, t2 STRING) → DOUBLE
+ //
+ // MEOS: nad_tgeo_tgeo(const Temporal *, const Temporal *) → double
+ // Returns NULL when trips have no overlapping time extent (MEOS: DBL_MAX).
+ // ------------------------------------------------------------------
+ public static final UDF2 nearestApproachDistance =
+ (trip1, trip2) -> {
+ if (trip1 == null || trip2 == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(trip1);
+ if (p1 == null) return null;
+ try {
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(trip2);
+ if (p2 == null) return null;
+ try {
+ double dist = GeneratedFunctions.nad_tgeo_tgeo(p1, p2);
+ return (dist == Double.MAX_VALUE) ? null : dist;
+ } finally {
+ MeosMemory.free(p2);
+ }
+ } finally {
+ MeosMemory.free(p1);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // eDwithin(t1 STRING, t2 STRING, dist DOUBLE) → BOOLEAN
+ //
+ // dist accepts Double or BigDecimal (Spark infers decimal(p,s) for
+ // numeric literals like 10.0 — use Number.doubleValue() to handle both).
+ //
+ // MEOS: edwithin_tgeo_tgeo(const Temporal *, const Temporal *, double) → int
+ // ------------------------------------------------------------------
+ public static final UDF3 eDwithin =
+ (trip1, trip2, dist) -> {
+ if (trip1 == null || trip2 == null || dist == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(trip1);
+ if (p1 == null) return null;
+ try {
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(trip2);
+ if (p2 == null) return null;
+ try {
+ return GeneratedFunctions.edwithin_tgeo_tgeo(p1, p2, dist.doubleValue()) == 1;
+ } finally {
+ MeosMemory.free(p2);
+ }
+ } finally {
+ MeosMemory.free(p1);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // tgeompoint(wkt STRING) → STRING (hex-WKB)
+ //
+ // Parses a tgeompoint WKT string and returns the MEOS hex-WKB encoding.
+ //
+ // MEOS: tgeompoint_in(const char *str) → Temporal * meos_geo.h:618
+ // temporal_as_hexwkb(const Temporal *, uint8_t, size_t *) meos.h
+ // ------------------------------------------------------------------
+ public static final UDF1 tgeompoint =
+ (wkt) -> {
+ if (wkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = GeneratedFunctions.tgeompoint_in(wkt);
+ if (p == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(p, (byte) 0);
+ } finally {
+ MeosMemory.free(p);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // trajectory(trip STRING) → STRING (hex WKB geometry)
+ //
+ // Projects a tgeompoint to its spatial path: POINT for a single
+ // instant, LINESTRING for a linear sequence. Returns hex-EWKB.
+ //
+ // MEOS: tpoint_trajectory(const Temporal *, bool merge) → GSERIALIZED *
+ // geo_as_hexewkb(const GSERIALIZED *, const char *endian) meos_geo.h
+ // ------------------------------------------------------------------
+ public static final UDF1 trajectory =
+ (trip) -> {
+ if (trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer gptr = GeneratedFunctions.tpoint_trajectory(tptr, true);
+ if (gptr == null) return null;
+ try {
+ return GeneratedFunctions.geo_as_hexewkb(gptr, null);
+ } finally {
+ MeosMemory.free(gptr);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // eDisjoint(trip STRING, geomWkt STRING) → BOOLEAN
+ //
+ // Returns true if the moving object is ever disjoint from the geometry.
+ //
+ // MEOS: edisjoint_tgeo_geo(const Temporal *, const GSERIALIZED *) → int
+ // ------------------------------------------------------------------
+ public static final UDF2 eDisjoint =
+ (trip, geomWkt) -> {
+ if (trip == null || geomWkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer bbox = GeneratedFunctions.tspatial_to_stbox(tptr);
+ int srid = (bbox != null) ? GeneratedFunctions.stbox_srid(bbox) : 0;
+ MeosMemory.free(bbox);
+ Pointer gptr = GeneratedFunctions.geo_from_text(geomWkt, srid);
+ if (gptr == null) return null;
+ try {
+ return GeneratedFunctions.edisjoint_tgeo_geo(tptr, gptr) == 1;
+ } finally {
+ MeosMemory.free(gptr);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // eTouches(trip STRING, geomWkt STRING) → BOOLEAN
+ //
+ // Returns true if the moving object ever touches (shares boundary with)
+ // the static geometry.
+ //
+ // MEOS: etouches_tgeo_geo(const Temporal *, const GSERIALIZED *) → int
+ // ------------------------------------------------------------------
+ public static final UDF2 eTouches =
+ (trip, geomWkt) -> {
+ if (trip == null || geomWkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer bbox = GeneratedFunctions.tspatial_to_stbox(tptr);
+ int srid = (bbox != null) ? GeneratedFunctions.stbox_srid(bbox) : 0;
+ MeosMemory.free(bbox);
+ Pointer gptr = GeneratedFunctions.geo_from_text(geomWkt, srid);
+ if (gptr == null) return null;
+ try {
+ return GeneratedFunctions.etouches_tgeo_geo(tptr, gptr) == 1;
+ } finally {
+ MeosMemory.free(gptr);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // eCovers(trip STRING, geomWkt STRING) → BOOLEAN
+ //
+ // Returns true if the moving object ever covers the static geometry.
+ //
+ // MEOS: ecovers_tgeo_geo(const Temporal *, const GSERIALIZED *) → int
+ // ------------------------------------------------------------------
+ public static final UDF2 eCovers =
+ (trip, geomWkt) -> {
+ if (trip == null || geomWkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer bbox = GeneratedFunctions.tspatial_to_stbox(tptr);
+ int srid = (bbox != null) ? GeneratedFunctions.stbox_srid(bbox) : 0;
+ MeosMemory.free(bbox);
+ Pointer gptr = GeneratedFunctions.geo_from_text(geomWkt, srid);
+ if (gptr == null) return null;
+ try {
+ return GeneratedFunctions.ecovers_tgeo_geo(tptr, gptr) == 1;
+ } finally {
+ MeosMemory.free(gptr);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // eDisjointTgeoTgeo(trip1 STRING, trip2 STRING) → BOOLEAN
+ // eIntersectsTgeoTgeo(trip1 STRING, trip2 STRING) → BOOLEAN
+ //
+ // MEOS: edisjoint_tgeo_tgeo, eintersects_tgeo_tgeo
+ // ------------------------------------------------------------------
+ public static final UDF2 eDisjointTgeoTgeo =
+ (trip1, trip2) -> {
+ if (trip1 == null || trip2 == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(trip1);
+ if (p1 == null) return null;
+ try {
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(trip2);
+ if (p2 == null) return null;
+ try {
+ return GeneratedFunctions.edisjoint_tgeo_tgeo(p1, p2) == 1;
+ } finally {
+ MeosMemory.free(p2);
+ }
+ } finally {
+ MeosMemory.free(p1);
+ }
+ };
+
+ public static final UDF2 eIntersectsTgeoTgeo =
+ (trip1, trip2) -> {
+ if (trip1 == null || trip2 == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(trip1);
+ if (p1 == null) return null;
+ try {
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(trip2);
+ if (p2 == null) return null;
+ try {
+ return GeneratedFunctions.eintersects_tgeo_tgeo(p1, p2) == 1;
+ } finally {
+ MeosMemory.free(p2);
+ }
+ } finally {
+ MeosMemory.free(p1);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // aIntersects(trip STRING, geomWkt STRING) → BOOLEAN
+ // aDisjoint(trip STRING, geomWkt STRING) → BOOLEAN
+ //
+ // Returns true if the moving object always intersects / is always
+ // disjoint from the static geometry.
+ //
+ // MEOS: aintersects_tgeo_geo, adisjoint_tgeo_geo
+ // ------------------------------------------------------------------
+ public static final UDF2 aIntersects =
+ (trip, geomWkt) -> {
+ if (trip == null || geomWkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer bbox = GeneratedFunctions.tspatial_to_stbox(tptr);
+ int srid = (bbox != null) ? GeneratedFunctions.stbox_srid(bbox) : 0;
+ MeosMemory.free(bbox);
+ Pointer gptr = GeneratedFunctions.geo_from_text(geomWkt, srid);
+ if (gptr == null) return null;
+ try {
+ return GeneratedFunctions.aintersects_tgeo_geo(tptr, gptr) == 1;
+ } finally {
+ MeosMemory.free(gptr);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ public static final UDF2 aDisjoint =
+ (trip, geomWkt) -> {
+ if (trip == null || geomWkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer bbox = GeneratedFunctions.tspatial_to_stbox(tptr);
+ int srid = (bbox != null) ? GeneratedFunctions.stbox_srid(bbox) : 0;
+ MeosMemory.free(bbox);
+ Pointer gptr = GeneratedFunctions.geo_from_text(geomWkt, srid);
+ if (gptr == null) return null;
+ try {
+ return GeneratedFunctions.adisjoint_tgeo_geo(tptr, gptr) == 1;
+ } finally {
+ MeosMemory.free(gptr);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // aDwithin(trip1 STRING, trip2 STRING, dist DOUBLE) → BOOLEAN
+ // eDwithinGeo(trip STRING, geomWkt STRING, dist DOUBLE) → BOOLEAN
+ // aDwithinGeo(trip STRING, geomWkt STRING, dist DOUBLE) → BOOLEAN
+ //
+ // MEOS: adwithin_tgeo_tgeo, edwithin_tgeo_geo, adwithin_tgeo_geo
+ // ------------------------------------------------------------------
+ public static final UDF3 aDwithin =
+ (trip1, trip2, dist) -> {
+ if (trip1 == null || trip2 == null || dist == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(trip1);
+ if (p1 == null) return null;
+ try {
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(trip2);
+ if (p2 == null) return null;
+ try {
+ return GeneratedFunctions.adwithin_tgeo_tgeo(p1, p2, dist.doubleValue()) == 1;
+ } finally {
+ MeosMemory.free(p2);
+ }
+ } finally {
+ MeosMemory.free(p1);
+ }
+ };
+
+ public static final UDF3 eDwithinGeo =
+ (trip, geomWkt, dist) -> {
+ if (trip == null || geomWkt == null || dist == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer bbox = GeneratedFunctions.tspatial_to_stbox(tptr);
+ int srid = (bbox != null) ? GeneratedFunctions.stbox_srid(bbox) : 0;
+ MeosMemory.free(bbox);
+ Pointer gptr = GeneratedFunctions.geo_from_text(geomWkt, srid);
+ if (gptr == null) return null;
+ try {
+ return GeneratedFunctions.edwithin_tgeo_geo(tptr, gptr, dist.doubleValue()) == 1;
+ } finally {
+ MeosMemory.free(gptr);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ public static final UDF3 aDwithinGeo =
+ (trip, geomWkt, dist) -> {
+ if (trip == null || geomWkt == null || dist == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer bbox = GeneratedFunctions.tspatial_to_stbox(tptr);
+ int srid = (bbox != null) ? GeneratedFunctions.stbox_srid(bbox) : 0;
+ MeosMemory.free(bbox);
+ Pointer gptr = GeneratedFunctions.geo_from_text(geomWkt, srid);
+ if (gptr == null) return null;
+ try {
+ return GeneratedFunctions.adwithin_tgeo_geo(tptr, gptr, dist.doubleValue()) == 1;
+ } finally {
+ MeosMemory.free(gptr);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // eContains(geomWKT STRING, trip STRING) → BOOLEAN
+ //
+ // Returns true if the static geometry ever contains the moving object.
+ // Argument order: eContains(container, contained).
+ //
+ // MEOS: econtains_geo_tgeo(const GSERIALIZED *, const Temporal *) → int
+ // ------------------------------------------------------------------
+ public static final UDF2 eContains =
+ (geomWkt, trip) -> {
+ if (geomWkt == null || trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer bbox = GeneratedFunctions.tspatial_to_stbox(tptr);
+ int srid = (bbox != null) ? GeneratedFunctions.stbox_srid(bbox) : 0;
+ MeosMemory.free(bbox);
+ Pointer gptr = GeneratedFunctions.geo_from_text(geomWkt, srid);
+ if (gptr == null) return null;
+ try {
+ return GeneratedFunctions.econtains_geo_tgeo(gptr, tptr) == 1;
+ } finally {
+ MeosMemory.free(gptr);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // geomFromText(wkt STRING) → STRING (hex-EWKB)
+ //
+ // MEOS: geo_from_text(const char *, int32_t srid) → GSERIALIZED *
+ // geo_as_hexewkb(const GSERIALIZED *, const char *)
+ // ------------------------------------------------------------------
+ public static final UDF1 geomFromText =
+ (wkt) -> {
+ if (wkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = GeneratedFunctions.geo_from_text(wkt, 0);
+ if (p == null) return null;
+ try {
+ return GeneratedFunctions.geo_as_hexewkb(p, null);
+ } finally {
+ MeosMemory.free(p);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // getX / getY / getZ(trip STRING) → STRING (tfloat hex-WKB)
+ // cumulativeLength(trip STRING) → STRING (tfloat hex-WKB)
+ //
+ // MEOS: tpoint_get_x/y/z, tpoint_cumulative_length meos_geo.h
+ // ------------------------------------------------------------------
+ public static final UDF1 getX =
+ (trip) -> {
+ if (trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer r = GeneratedFunctions.tpoint_get_x(tptr);
+ if (r == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ } finally {
+ MeosMemory.free(r);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ public static final UDF1 getY =
+ (trip) -> {
+ if (trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer r = GeneratedFunctions.tpoint_get_y(tptr);
+ if (r == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ } finally {
+ MeosMemory.free(r);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ public static final UDF1 getZ =
+ (trip) -> {
+ if (trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ // tpoint_get_z raises a MEOS error for 2D points; guard with Z-presence check.
+ Pointer bbox = GeneratedFunctions.tspatial_to_stbox(tptr);
+ if (bbox == null || !GeneratedFunctions.stbox_hasz(bbox)) {
+ MeosMemory.free(bbox);
+ return null;
+ }
+ MeosMemory.free(bbox);
+ Pointer r = GeneratedFunctions.tpoint_get_z(tptr);
+ if (r == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ } finally {
+ MeosMemory.free(r);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ public static final UDF1 cumulativeLength =
+ (trip) -> {
+ if (trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer r = GeneratedFunctions.tpoint_cumulative_length(tptr);
+ if (r == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ } finally {
+ MeosMemory.free(r);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // stops(trip STRING, maxDist DOUBLE, minDuration STRING) → STRING
+ //
+ // Returns the sub-trajectories where the vehicle stayed within maxDist
+ // for at least minDuration ("1 second").
+ //
+ // MEOS: temporal_stops(const Temporal *, double, const Interval *) meos.h
+ // ------------------------------------------------------------------
+ public static final UDF3 stops =
+ (trip, maxDist, minDuration) -> {
+ if (trip == null || maxDist == null || minDuration == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer iv = GeneratedFunctions.pg_interval_in(minDuration, -1);
+ if (iv == null) return null;
+ try {
+ Pointer r = GeneratedFunctions.temporal_stops(tptr, maxDist, iv);
+ if (r == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(r, (byte) 0);
+ } finally {
+ MeosMemory.free(r);
+ }
+ } finally {
+ MeosMemory.free(iv);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // isSimple(trip STRING) → BOOLEAN
+ //
+ // True when the trip has no self-intersections.
+ //
+ // MEOS: tpoint_is_simple(const Temporal *) meos_geo.h
+ // ------------------------------------------------------------------
+ public static final UDF1 isSimple =
+ (trip) -> {
+ if (trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ return GeneratedFunctions.tpoint_is_simple(tptr);
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // shortestLine(trip1 STRING, trip2 STRING) → STRING (WKT geometry)
+ //
+ // MEOS: shortestline_tpoint_tpoint(const Temporal *, const Temporal *)
+ // geo_as_text(const GSERIALIZED *, int precision)
+ // ------------------------------------------------------------------
+ public static final UDF2 shortestLine =
+ (trip1, trip2) -> {
+ if (trip1 == null || trip2 == null) return null;
+ MeosThread.ensureReady();
+ Pointer p1 = GeneratedFunctions.temporal_from_hexwkb(trip1);
+ if (p1 == null) return null;
+ try {
+ Pointer p2 = GeneratedFunctions.temporal_from_hexwkb(trip2);
+ if (p2 == null) return null;
+ try {
+ Pointer g = GeneratedFunctions.shortestline_tgeo_tgeo(p1, p2);
+ if (g == null) return null;
+ try {
+ return GeneratedFunctions.geo_as_text(g, 15);
+ } finally {
+ MeosMemory.free(g);
+ }
+ } finally {
+ MeosMemory.free(p2);
+ }
+ } finally {
+ MeosMemory.free(p1);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // tpointTransform(trip STRING, srid INTEGER) → STRING
+ //
+ // Reprojects all instants of the temporal point to a different CRS.
+ //
+ // MEOS: tspatial_transform(const Temporal *, int srid) → Temporal *
+ // ------------------------------------------------------------------
+ public static final UDF2 tpointTransform =
+ (trip, srid) -> {
+ if (trip == null || srid == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer result = GeneratedFunctions.tspatial_transform(tptr, srid);
+ if (result == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(result, (byte) 0);
+ } finally {
+ MeosMemory.free(result);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // tpointAsText(trip STRING, precision INTEGER) → STRING
+ //
+ // Returns WKT for each instant of the temporal point.
+ //
+ // MEOS: tspatial_as_text(const Temporal *, int precision) → char *
+ // ------------------------------------------------------------------
+ public static final UDF2 tpointAsText =
+ (trip, precision) -> {
+ if (trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ return GeneratedFunctions.tspatial_as_text(tptr, precision != null ? precision : 15);
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // tpointAsEWKT(trip STRING, precision INTEGER) → STRING
+ //
+ // Returns Extended WKT (SRID=N;...) for each instant of the temporal point.
+ //
+ // MEOS: tspatial_as_ewkt(const Temporal *, int precision) → char *
+ // ------------------------------------------------------------------
+ public static final UDF2 tpointAsEWKT =
+ (trip, precision) -> {
+ if (trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ return GeneratedFunctions.tspatial_as_ewkt(tptr, precision != null ? precision : 15);
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // tpointSRID(trip STRING) → INTEGER
+ //
+ // Returns the SRID of the temporal point via its bounding box.
+ //
+ // MEOS: tspatial_to_stbox(const Temporal *) → STBox *
+ // stbox_srid(const STBox *) → int
+ // ------------------------------------------------------------------
+ public static final UDF1 tpointSRID =
+ (trip) -> {
+ if (trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer stbox = GeneratedFunctions.tspatial_to_stbox(tptr);
+ if (stbox == null) return null;
+ try {
+ return GeneratedFunctions.stbox_srid(stbox);
+ } finally {
+ MeosMemory.free(stbox);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // tpointSetSRID(trip STRING, srid INTEGER) → STRING
+ //
+ // Returns a copy of the temporal point with SRID set to srid.
+ //
+ // MEOS: tspatial_set_srid(const Temporal *, int srid) → Temporal *
+ // ------------------------------------------------------------------
+ public static final UDF2 tpointSetSRID =
+ (trip, srid) -> {
+ if (trip == null || srid == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer result = GeneratedFunctions.tspatial_set_srid(tptr, srid);
+ if (result == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(result, (byte) 0);
+ } finally {
+ MeosMemory.free(result);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // tpointRound(trip STRING, decimals INTEGER) → STRING
+ //
+ // Returns the temporal point with coordinates rounded to decimals places.
+ //
+ // MEOS: temporal_round(const Temporal *, int maxdd) → Temporal *
+ // ------------------------------------------------------------------
+ public static final UDF2 tpointRound =
+ (trip, decimals) -> {
+ if (trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer result = GeneratedFunctions.temporal_round(tptr, decimals != null ? decimals : 6);
+ if (result == null) return null;
+ try {
+ return GeneratedFunctions.temporal_as_hexwkb(result, (byte) 0);
+ } finally {
+ MeosMemory.free(result);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // tpointToStbox(trip STRING) → STRING (hex-WKB STBOX)
+ //
+ // Returns the spatiotemporal bounding box of the temporal point.
+ //
+ // MEOS: tspatial_to_stbox(const Temporal *) → STBox *
+ // stbox_as_hexwkb(const STBox *, uint8_t variant, size_t *size)
+ // ------------------------------------------------------------------
+ public static final UDF1 tpointToStbox =
+ (trip) -> {
+ if (trip == null) return null;
+ MeosThread.ensureReady();
+ Pointer tptr = GeneratedFunctions.temporal_from_hexwkb(trip);
+ if (tptr == null) return null;
+ try {
+ Pointer stbox = GeneratedFunctions.tspatial_to_stbox(tptr);
+ if (stbox == null) return null;
+ try {
+ Pointer sizeOut = Runtime.getSystemRuntime().getMemoryManager().allocateDirect(8);
+ return GeneratedFunctions.stbox_as_hexwkb(stbox, (byte) 0, sizeOut);
+ } finally {
+ MeosMemory.free(stbox);
+ }
+ } finally {
+ MeosMemory.free(tptr);
+ }
+ };
+
+ public static void registerAll(org.apache.spark.sql.SparkSession spark) {
+ spark.udf().register("eIntersects", eIntersects, DataTypes.BooleanType);
+ spark.udf().register("eDisjoint", eDisjoint, DataTypes.BooleanType);
+ spark.udf().register("eTouches", eTouches, DataTypes.BooleanType);
+ spark.udf().register("eCovers", eCovers, DataTypes.BooleanType);
+ spark.udf().register("eContains", eContains, DataTypes.BooleanType);
+ spark.udf().register("eDisjointTgeoTgeo", eDisjointTgeoTgeo, DataTypes.BooleanType);
+ spark.udf().register("eIntersectsTgeoTgeo", eIntersectsTgeoTgeo, DataTypes.BooleanType);
+ spark.udf().register("nearestApproachDistance", nearestApproachDistance, DataTypes.DoubleType);
+ spark.udf().register("eDwithin", eDwithin, DataTypes.BooleanType);
+ spark.udf().register("eDwithinGeo", eDwithinGeo, DataTypes.BooleanType);
+ spark.udf().register("aIntersects", aIntersects, DataTypes.BooleanType);
+ spark.udf().register("aDisjoint", aDisjoint, DataTypes.BooleanType);
+ spark.udf().register("aDwithin", aDwithin, DataTypes.BooleanType);
+ spark.udf().register("aDwithinGeo", aDwithinGeo, DataTypes.BooleanType);
+ spark.udf().register("tgeompoint", tgeompoint, DataTypes.StringType);
+ spark.udf().register("trajectory", trajectory, DataTypes.StringType);
+ spark.udf().register("geomFromText", geomFromText, DataTypes.StringType);
+ spark.udf().register("getX", getX, DataTypes.StringType);
+ spark.udf().register("getY", getY, DataTypes.StringType);
+ spark.udf().register("getZ", getZ, DataTypes.StringType);
+ spark.udf().register("cumulativeLength", cumulativeLength, DataTypes.StringType);
+ spark.udf().register("stops", stops, DataTypes.StringType);
+ spark.udf().register("isSimple", isSimple, DataTypes.BooleanType);
+ spark.udf().register("shortestLine", shortestLine, DataTypes.StringType);
+ spark.udf().register("tpointTransform", tpointTransform, DataTypes.StringType);
+ spark.udf().register("tpointAsText", tpointAsText, DataTypes.StringType);
+ spark.udf().register("tpointAsEWKT", tpointAsEWKT, DataTypes.StringType);
+ spark.udf().register("tpointSRID", tpointSRID, DataTypes.IntegerType);
+ spark.udf().register("tpointSetSRID", tpointSetSRID, DataTypes.StringType);
+ spark.udf().register("tpointRound", tpointRound, DataTypes.StringType);
+ spark.udf().register("tpointToStbox", tpointToStbox, DataTypes.StringType);
+ spark.udf().register("geoAsEwkt", geoAsEwkt, DataTypes.StringType);
+ spark.udf().register("geoAsGeojson", geoAsGeojson, DataTypes.StringType);
+ spark.udf().register("geoFromGeojson", geoFromGeojson, DataTypes.StringType);
+ }
+
+ // ------------------------------------------------------------------
+ // geoAsEwkt(wkt STRING, precision INTEGER) → STRING
+ //
+ // Returns Extended WKT (SRID=N;...) for a geometry given as WKT.
+ //
+ // MEOS: geo_as_ewkt(const GSERIALIZED *, int precision)
+ // ------------------------------------------------------------------
+ public static final UDF2 geoAsEwkt =
+ (wkt, precision) -> {
+ if (wkt == null) return null;
+ MeosThread.ensureReady();
+ int prec = (precision == null) ? 15 : precision;
+ Pointer gptr = GeneratedFunctions.geo_from_text(wkt, 0);
+ if (gptr == null) return null;
+ try {
+ return GeneratedFunctions.geo_as_ewkt(gptr, prec);
+ } finally {
+ MeosMemory.free(gptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // geoAsGeojson(wkt STRING, options INTEGER, precision INTEGER) → STRING
+ //
+ // Returns GeoJSON for a geometry. options: 0=no bbox, 1=bbox, 2=short CRS.
+ //
+ // MEOS: geo_as_geojson(const GSERIALIZED *, int options, int precision,
+ // const char *srs)
+ // ------------------------------------------------------------------
+ public static final UDF3 geoAsGeojson =
+ (wkt, options, precision) -> {
+ if (wkt == null) return null;
+ MeosThread.ensureReady();
+ int opts = (options == null) ? 0 : options;
+ int prec = (precision == null) ? 9 : precision;
+ Pointer gptr = GeneratedFunctions.geo_from_text(wkt, 0);
+ if (gptr == null) return null;
+ try {
+ return GeneratedFunctions.geo_as_geojson(gptr, opts, prec, null);
+ } finally {
+ MeosMemory.free(gptr);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // geoFromGeojson(geojson STRING) → STRING (WKT)
+ //
+ // Parses GeoJSON and returns the geometry as WKT.
+ //
+ // MEOS: geo_from_geojson(const char *) → GSERIALIZED *
+ // geo_as_text(const GSERIALIZED *, int precision)
+ // ------------------------------------------------------------------
+ public static final UDF1 geoFromGeojson =
+ (geojson) -> {
+ if (geojson == null) return null;
+ MeosThread.ensureReady();
+ Pointer gptr = GeneratedFunctions.geo_from_geojson(geojson);
+ if (gptr == null) return null;
+ try {
+ return GeneratedFunctions.geo_as_text(gptr, 15);
+ } finally {
+ MeosMemory.free(gptr);
+ }
+ };
+}
diff --git a/src/main/java/org/mobilitydb/spark/geo/STBoxUDFs.java b/src/main/java/org/mobilitydb/spark/geo/STBoxUDFs.java
new file mode 100644
index 00000000..d00b6cb8
--- /dev/null
+++ b/src/main/java/org/mobilitydb/spark/geo/STBoxUDFs.java
@@ -0,0 +1,694 @@
+/*****************************************************************************
+ *
+ * This MobilityDB code is provided under The PostgreSQL License.
+ * Copyright (c) 2020-2026, 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.
+ *
+ *****************************************************************************/
+
+package org.mobilitydb.spark.geo;
+
+import functions.GeneratedFunctions;
+import jnr.ffi.Pointer;
+import jnr.ffi.Runtime;
+import org.mobilitydb.spark.MeosMemory;
+import org.mobilitydb.spark.MeosThread;
+import org.apache.spark.sql.SparkSession;
+import org.apache.spark.sql.api.java.UDF1;
+import org.apache.spark.sql.api.java.UDF2;
+import org.apache.spark.sql.api.java.UDF3;
+import org.apache.spark.sql.api.java.UDF4;
+import org.apache.spark.sql.api.java.UDF5;
+import org.apache.spark.sql.api.java.UDF6;
+import org.apache.spark.sql.api.java.UDF7;
+import org.apache.spark.sql.types.DataTypes;
+
+import java.time.Instant;
+import java.time.OffsetDateTime;
+import java.time.ZoneOffset;
+import org.mobilitydb.spark.util.TimeUtil;
+
+/**
+ * Spark SQL UDFs for STBox accessor and expansion operations.
+ *
+ * Storage convention: STBox values are stored as hex-WKB strings produced by
+ * stbox_as_hexwkb (which requires a non-null size_out scratch Pointer).
+ *
+ * Spatial bound accessors (xmin/xmax/ymin/ymax/zmin/zmax): the JMEOS wrapper
+ * allocates an 8-byte buffer, passes it as out-pointer to the C function which
+ * writes the double there, and returns the buffer Pointer (null = absent).
+ * Temporal bound accessors (tmin/tmax): same pattern, int64 PG-epoch μs.
+ * Inclusivity flag accessors (tmin_inc/tmax_inc): same pattern, byte (0/1).
+ *
+ * MEOS function authority: meos/include/meos_geo.h
+ */
+public final class STBoxUDFs {
+
+ private STBoxUDFs() {}
+
+ // milliseconds from Unix epoch (1970-01-01) to PG epoch (2000-01-01)
+ private static Pointer stboxPtr(String hex) {
+ if (hex == null) return null;
+ return GeneratedFunctions.stbox_from_hexwkb(hex);
+ }
+
+ // stbox_as_hexwkb requires a non-null size_out scratch Pointer
+ private static String stboxHex(Pointer p) {
+ if (p == null) return null;
+ Pointer sizeOut = Runtime.getSystemRuntime().getMemoryManager().allocateDirect(8);
+ return GeneratedFunctions.stbox_as_hexwkb(p, (byte) 0, sizeOut);
+ }
+
+ // ------------------------------------------------------------------
+ // Has-component flags
+ // ------------------------------------------------------------------
+
+ public static final UDF1 stboxHasx =
+ (hex) -> {
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ return p == null ? null : GeneratedFunctions.stbox_hasx(p);
+ };
+
+ public static final UDF1 stboxHast =
+ (hex) -> {
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ return p == null ? null : GeneratedFunctions.stbox_hast(p);
+ };
+
+ public static final UDF1 stboxHasz =
+ (hex) -> {
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ return p == null ? null : GeneratedFunctions.stbox_hasz(p);
+ };
+
+ // ------------------------------------------------------------------
+ // Spatial bound accessors (Pointer → double at offset 0)
+ // ------------------------------------------------------------------
+
+ public static final UDF1 stboxXmin =
+ (hex) -> {
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer r = GeneratedFunctions.stbox_xmin(p);
+ return r == null ? null : r.getDouble(0);
+ };
+
+ public static final UDF1 stboxXmax =
+ (hex) -> {
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer r = GeneratedFunctions.stbox_xmax(p);
+ return r == null ? null : r.getDouble(0);
+ };
+
+ public static final UDF1 stboxYmin =
+ (hex) -> {
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer r = GeneratedFunctions.stbox_ymin(p);
+ return r == null ? null : r.getDouble(0);
+ };
+
+ public static final UDF1 stboxYmax =
+ (hex) -> {
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer r = GeneratedFunctions.stbox_ymax(p);
+ return r == null ? null : r.getDouble(0);
+ };
+
+ public static final UDF1 stboxZmin =
+ (hex) -> {
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer r = GeneratedFunctions.stbox_zmin(p);
+ return r == null ? null : r.getDouble(0);
+ };
+
+ public static final UDF1 stboxZmax =
+ (hex) -> {
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer r = GeneratedFunctions.stbox_zmax(p);
+ return r == null ? null : r.getDouble(0);
+ };
+
+ // ------------------------------------------------------------------
+ // Temporal bound accessors (Pointer → int64 PG-epoch μs at offset 0)
+ // ------------------------------------------------------------------
+
+ public static final UDF1 stboxTmin =
+ (hex) -> {
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer r = GeneratedFunctions.stbox_tmin(p);
+ if (r == null) return null;
+ return new java.sql.Timestamp(r.getLong(0) / 1000L + TimeUtil.PG_UNIX_EPOCH_OFFSET_MS);
+ };
+
+ public static final UDF1 stboxTmax =
+ (hex) -> {
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer r = GeneratedFunctions.stbox_tmax(p);
+ if (r == null) return null;
+ return new java.sql.Timestamp(r.getLong(0) / 1000L + TimeUtil.PG_UNIX_EPOCH_OFFSET_MS);
+ };
+
+ // ------------------------------------------------------------------
+ // Temporal inclusivity flags (Pointer → byte at offset 0)
+ // ------------------------------------------------------------------
+
+ public static final UDF1 stboxTminInc =
+ (hex) -> {
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer r = GeneratedFunctions.stbox_tmin_inc(p);
+ return r == null ? null : r.getByte(0) != 0;
+ };
+
+ public static final UDF1 stboxTmaxInc =
+ (hex) -> {
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer r = GeneratedFunctions.stbox_tmax_inc(p);
+ return r == null ? null : r.getByte(0) != 0;
+ };
+
+ // ------------------------------------------------------------------
+ // SRID
+ // ------------------------------------------------------------------
+
+ public static final UDF1 stboxSrid =
+ (hex) -> {
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ return p == null ? null : GeneratedFunctions.stbox_srid(p);
+ };
+
+ // ------------------------------------------------------------------
+ // Expansion operations
+ // ------------------------------------------------------------------
+
+ // stboxExpandSpace(stboxHex STRING, d DOUBLE) → STRING
+ public static final UDF2 stboxExpandSpace =
+ (hex, d) -> {
+ if (hex == null || d == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer r = GeneratedFunctions.stbox_expand_space(p, d);
+ return stboxHex(r);
+ };
+
+ // stboxExpandTime(stboxHex STRING, intervalStr STRING) → STRING
+ public static final UDF2 stboxExpandTime =
+ (hex, intervalStr) -> {
+ if (hex == null || intervalStr == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer iv = GeneratedFunctions.pg_interval_in(intervalStr, -1);
+ if (iv == null) return null;
+ Pointer r = GeneratedFunctions.stbox_expand_time(p, iv);
+ return stboxHex(r);
+ };
+
+ // ------------------------------------------------------------------
+ // Spatial analytics (hex-WKB in, scalar out)
+ //
+ // MEOS: stbox_area(box, spheroid) meos_geo.h
+ // stbox_perimeter(box, spheroid) meos_geo.h
+ // stbox_volume(box) meos_geo.h
+ // ------------------------------------------------------------------
+
+ public static final UDF1 stboxArea =
+ (hex) -> {
+ if (hex == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ return GeneratedFunctions.stbox_area(p, false);
+ };
+
+ public static final UDF1 stboxPerimeter =
+ (hex) -> {
+ if (hex == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ return GeneratedFunctions.stbox_perimeter(p, false);
+ };
+
+ public static final UDF1 stboxVolume =
+ (hex) -> {
+ if (hex == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ return GeneratedFunctions.stbox_volume(p);
+ };
+
+ // stboxIsGeodetic(hex) → Boolean
+ public static final UDF1 stboxIsGeodetic =
+ (hex) -> {
+ if (hex == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ return GeneratedFunctions.stbox_isgeodetic(p);
+ };
+
+ // stboxToGeo(hex) → WKT of the bounding envelope polygon
+ public static final UDF1 stboxToGeo =
+ (hex) -> {
+ if (hex == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer g = GeneratedFunctions.stbox_to_geo(p);
+ if (g == null) return null;
+ return GeneratedFunctions.geo_as_text(g, 15);
+ };
+
+ // stboxToTstzspan(hex) → tstzspan hex-WKB
+ public static final UDF1 stboxToTstzspan =
+ (hex) -> {
+ if (hex == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer span = GeneratedFunctions.stbox_to_tstzspan(p);
+ if (span == null) return null;
+ return GeneratedFunctions.span_as_hexwkb(span, (byte) 0);
+ };
+
+ // ------------------------------------------------------------------
+ // Rounding
+ // ------------------------------------------------------------------
+
+ // stboxRound(hex STRING, maxDecimals INT) → STRING
+ // MEOS: stbox_round(const STBox *, int) → STBox *
+ public static final UDF2 stboxRound =
+ (hex, maxDecimals) -> {
+ if (hex == null || maxDecimals == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer result = GeneratedFunctions.stbox_round(p, maxDecimals);
+ if (result == null) return null;
+ try {
+ return stboxHex(result);
+ } finally {
+ MeosMemory.free(result);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // SRID assignment
+ // ------------------------------------------------------------------
+
+ // stboxSetSrid(hex STRING, srid INT) → STRING
+ // MEOS: stbox_set_srid(const STBox *, int) → STBox *
+ public static final UDF2 stboxSetSrid =
+ (hex, srid) -> {
+ if (hex == null || srid == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer result = GeneratedFunctions.stbox_set_srid(p, srid);
+ if (result == null) return null;
+ try {
+ return stboxHex(result);
+ } finally {
+ MeosMemory.free(result);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // Time-domain shifting and scaling
+ // ------------------------------------------------------------------
+
+ // stboxShiftScaleTime(hex STRING, shift STRING, scale STRING) → STRING
+ // MEOS: stbox_shift_scale_time(const STBox *, Interval *, Interval *) → STBox *
+ // Either shift or scale may be null (pass null to MEOS for no-op).
+ public static final UDF3 stboxShiftScaleTime =
+ (hex, shift, scale) -> {
+ if (hex == null) return null;
+ MeosThread.ensureReady();
+ Pointer p = stboxPtr(hex);
+ if (p == null) return null;
+ Pointer shiftIv = shift == null ? null : GeneratedFunctions.pg_interval_in(shift, Integer.MIN_VALUE);
+ Pointer scaleIv = scale == null ? null : GeneratedFunctions.pg_interval_in(scale, Integer.MIN_VALUE);
+ try {
+ Pointer result = GeneratedFunctions.stbox_shift_scale_time(p, shiftIv, scaleIv);
+ if (result == null) return null;
+ try {
+ return stboxHex(result);
+ } finally {
+ MeosMemory.free(result);
+ }
+ } finally {
+ if (shiftIv != null) MeosMemory.free(shiftIv);
+ if (scaleIv != null) MeosMemory.free(scaleIv);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // STBox constructors from geometry / span / timestamptz
+ //
+ // MEOS: geo_to_stbox, tstzspan_to_stbox, timestamptz_to_stbox
+ // ------------------------------------------------------------------
+
+ // geoToStbox(wkt STRING) → STBox hex-WKB
+ // Creates an STBox with the bounding box of a geometry.
+ // MEOS: geo_to_stbox(const GSERIALIZED *) → STBox *
+ public static final UDF1 geoToStbox =
+ (wkt) -> {
+ if (wkt == null) return null;
+ MeosThread.ensureReady();
+ Pointer geo = GeneratedFunctions.geo_from_text(wkt, 0);
+ if (geo == null) return null;
+ Pointer result = GeneratedFunctions.geo_to_stbox(geo);
+ if (result == null) return null;
+ try {
+ return stboxHex(result);
+ } finally {
+ MeosMemory.free(result);
+ }
+ };
+
+ // tstzspanToStbox(spanHex STRING) → STBox hex-WKB
+ // Creates a time-only STBox from a tstzspan.
+ // MEOS: tstzspan_to_stbox(const Span *) → STBox *
+ public static final UDF1 tstzspanToStbox =
+ (spanHex) -> {
+ if (spanHex == null) return null;
+ MeosThread.ensureReady();
+ Pointer span = GeneratedFunctions.span_from_hexwkb(spanHex);
+ if (span == null) return null;
+ Pointer result = GeneratedFunctions.tstzspan_to_stbox(span);
+ if (result == null) return null;
+ try {
+ return stboxHex(result);
+ } finally {
+ MeosMemory.free(result);
+ }
+ };
+
+ // timestamptzToStbox(ts TIMESTAMP) → STBox hex-WKB
+ // Creates a point-time STBox from a single timestamp.
+ // MEOS: timestamptz_to_stbox(TimestampTz) → STBox *
+ public static final UDF1 timestamptzToStbox =
+ (ts) -> {
+ if (ts == null) return null;
+ MeosThread.ensureReady();
+ long pgMicros = (ts.getTime() - TimeUtil.PG_UNIX_EPOCH_OFFSET_MS) * 1000L;
+ OffsetDateTime odt = OffsetDateTime.ofInstant(Instant.ofEpochSecond(pgMicros, 0), ZoneOffset.UTC);
+ Pointer result = GeneratedFunctions.timestamptz_to_stbox(odt);
+ if (result == null) return null;
+ try {
+ return stboxHex(result);
+ } finally {
+ MeosMemory.free(result);
+ }
+ };
+
+ // ------------------------------------------------------------------
+ // Spatial component extraction
+ //
+ // MEOS: stbox_get_space(const STBox *) → STBox * (spatial dims only, no T)
+ // ------------------------------------------------------------------
+
+ public static final UDF1