Spatial reprojection search processors

Lucenia supports search-time coordinate reprojection for both query input and search results, eliminating the need for bulky preprocessing tools, or maintaining multiple copies of the same data in different projections. This enables direct integration with clients and systems that operate in different spatial reference systems without additional Extraction, Transformation, and Loading (ETL) complexity.

Lucenia transforms your geometries on-the-fly using configurable processors in the search request pipeline and response pipeline - perfect for search UI tools, STAC browsing portals, and geospatial APIs that must handle Coordinate Reference System (CRS) differences at runtime.

Request fields

The following table lists all available request fields.

Field	Type	Description	Required
field	String	The source geometry field to reproject. Either a string in WKT format or a GeoJSON is expected.	Yes
ignore_missing	Boolean	If true and field does not exist, the processor quietly exits without modifying the document (Defaults to false)	Yes
target_field	String	The new runtime field to assign the reprojected geometry to. (Defaults to the same as the field)	Yes
source_crs	String	The coordinate reference system used by the field. (Defaults to "EPSG:4326")	No
target_crs	String	The coordinate reference system to reproject the field into. (Defaults to "EPSG:4326")	No
shape_type	String	Which field mapping type is used when processing the field. (Defaults to geo_shape)	No
provider	String	The processor's identifier. (Defaults to "sis")	No

Example

The following examples demonstrate using a search pipeline with a reprojection processor to reproject between standard World Geodetic System of 1984 latitude, longitude (decimal degrees) projection and Mercator X, Y (meters) projection (used by common Web Mapping tools).

Create a Search Request Reprojection Processor

The example below creates a search request processor to reproject query geometry from Mercator into WGS84 projection.

PUT /_search/pipeline/reproject_to_wgs84
{
  "description" : "reproject spatial query geometries from EPSG:3857 X,Y coordinate system to EPSG:4326 lat,lon coordinate system",
  "request_processors" : [
    {
      "reproject" : {
        "field" : "geometry",
        "source_crs" : "EPSG:3857",
        "shape_type" : "shape"
      }
    }
  ]
}

The input geometry field in the query is treated as a shape and dynamically reprojected from the EPSG:3857 (X, Y) coordinate system to EPSG:4326 (lat, lon), using the same field name. This enables conversion of a user-provided shape query in Easting/Northing (X, Y) to a geo_shape query in (lat, lon), aligning with the coordinate system of the indexed data.

Using the Search Request Reprojection Processor

To search with the reprojection processor, specify the pipeline name in the search_pipeline query parameter. For example, the following request searches in EPSG:3857 (Y, Y) coordinate system even though the user provided the geometry in the EPSG:4326 (lat, lon) coordinate system.

GET /mercator_data/_search?search_pipeline=reproject_to_wgs84
{
  "query" : {
    "geo_shape" : {
      "geometry" : {
        "shape" : {
            "type" : "envelope",
            "coordinates": [ [1812358.0, 6139791.0], [1812369.2, 6139780.1]]
        },
        "relation" :  "intersects"
      }
    }
  }
}

An example result is provided below:

  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0,
    "hits": [
      {
        "_index": "mercator_data",
        "_id": "roads_1_0",
        "_score": 0,
        "_source": {
          "filename": "roads_1",
          "feature_id": 0,
          "geometry": "LINESTRING (16.2806999 48.1975878,16.2806995 48.1976023,16.2806986 48.1976328,16.2807182 48.1984326)",
          "properties": {
            "osm_id": 149673,
            "fclass": "tertiary",
            "code": "5115",
            "maxspeed": 30,
            "length": 92,
            "edge_id": 1,
            "oneway": "B",
            "speed": 27,
            "layer": 0,
            "ref": null,
            "ete": 13,
            "name": "Waidhausenstraße",
            "bridge": "F",
            "lastchange": "2022-01-23T01:36:31Z",
            "tunnel": "F"
          }
        }
      }
    ]
  }  

Create a Search Response Reprojection Processor

The example below builds on the previous one by adding a search response processor that reprojects search result geometries from WGS84 (lat, lon) coordinate system into a new runtime-generated field called geometryMercator in the Mercator (X, Y) Easting, Northing coordinate system - demonstrating search-time ETL.

PUT /_search/pipeline/reproject_to_mercator
{
  "description" : "reproject spatial query result geometries from EPSG:4326 lat,lon WGS84 coordinate system to EPSG:3857 X,Y mercator coordinate system",
  "response_processors" : [
    {
      "reproject" : {
        "field" : "geometry",
        "target_field" : "geometryMercator",
        "target_crs" : "EPSG:3857"
      }
    }
  ]
}

Using the Search Response Reprojection Processor

To search with the reprojection processor and reproject the results on-the-fly, specify the pipeline name in the search_pipeline query parameter. For example, the following request searches in EPSG:4326 (lat, lon) coordinate system and reprojects the resulting geometries into the newly defined geometryMercator field defined in the EPSG:3857 (x, y) coordinate system.

GET /_search/pipeline/reproject_to_mercator
{
  "query": {
    "geo_shape": {
      "geometry": {
        "shape": {
          "type": "polygon",
            "coordinates": [[
              [18.34, 47.695],
              [15.84, 52.025],
              [10.84, 52.025],
              [8.34, 47.695],
              [10.84, 43.365],
              [15.84, 43.365],
              [18.34, 47.695]
            ]]
        },
        "relation": "intersects"
      }
    }
  }
}

An example result is provided below:

  "hits": {
    "total": {
      "value": 1,
      "relation": "gte"
    },
    "max_score": 0,
    "hits": [
      {
        "_index": "geodocuments",
        "_id": "roads_1_0",
        "_score": 0,
        "_source": {
          "feature_id": 0,
          "filename": "roads_1",
          "geometryMercator": "LINESTRING (1812359.2226260998 6139789.580365501, 1812359.1780983037 6139792.001938222, 1812359.077910762 6139797.0955934115, 1812361.2597727813 6139930.66734541)",
          "geometry": "LINESTRING (16.2806999 48.1975878,16.2806995 48.1976023,16.2806986 48.1976328,16.2807182 48.1984326)",
          "properties": {
            "osm_id": 149673,
            "fclass": "tertiary",
            "code": "5115",
            "maxspeed": 30,
            "length": 92,
            "edge_id": 1,
            "oneway": "B",
            "speed": 27,
            "layer": 0,
            "ref": null,
            "ete": 13,
            "name": "Waidhausenstraße",
            "bridge": "F",
            "lastchange": "2022-01-23T01:36:31Z",
            "tunnel": "F"
          }
        }
      } 
    ]
  }

Reprojection Providers

Overview

Reprojection in Lucenia is powered by pluggable mathematical transformation libraries. Two providers are included out-of-the-box:

• Apache SIS (default): Accurate and standards-compliant with OGC and EPSG support.
• Proj4j: Lightweight and fast alternative for simpler or faster use cases.

Both support EPSG codes:

{
  "target_crs" : "EPSG:4326"
}

But only proj4j supports custom projection strings:

{
  "target_crs": "+proj=longlat +a=3396190 +b=3396190 +no_defs"
}

The above example defines a Mars-compatible spherical WGS84-style projection.

To select a provider, use the provider parameter when defining the search processor:

PUT /_search/pipeline/reproject_to_mercator
{
  "description" : "reproject spatial query result geometries from EPSG:4326 lat,lon WGS84 coordinate system to EPSG:3857 X,Y mercator coordinate system",
  "response_processors" : [
    {
      "reproject" : {
        "field" : "geometry",
        "target_field" : "geometryMercator",
        "target_crs" : "EPSG:3857",
        "provider" : "proj4j"
      }
    }
  ]
}

Registering a Custom Reprojection Provider

Developers can also implement their own reprojection logic by implementing the CRSProviderInterface and registering it via the Java Service Provider Interface (SPI) system through their own search plugin.

Below is an example class for implementing a custom projection provider:

public class MyReprojectionProvider implements CRSProviderInterface<MyCRS, MyTransform> {

  private static final String NAME = "my_crs_provider";

  @Override
  public String getName() {
      return NAME;
  }

  @Override
  public MyTransform getTransform(final MyCRS fromCRS, final MyCRS toCRS, Object... extraArgs) throws Exception {
      MyBBox bbox = (extraArgs != null && extraArgs.length > 0 && extraArgs[0] instanceof MyBBox)
          ? (MyBBox) extraArgs[0]
          : null;
      return MyCRS.findMathOperation(fromCRS, toCRS, bbox).getMathTransform();
  }

  @Override
  public MyCRS getCRS(final String crsString) throws Exception {
      return AccessController.doPrivileged((PrivilegedAction<MyCRS>) () -> {
          try {
              return MyCRS.forCode(crsString);
          } catch (FactoryException e) {
              throw new RuntimeException(e);
          }
      });
  }

  @Override
  public CRSHandler<MyCRS> createCRSHandler(
      final String fromCRS,
      final String toCRS,
      final GeometryProcessorFieldType shapeFieldType
  ) throws Exception {
      MyCRS toReferenceSystem = toCRS != null ? getCRS(toCRS) : MyHandler.DEFAULT_TO_CRS;
      return new MyHandler(getCRS(fromCRS), toReferenceSystem, getTransform(getCRS(fromCRS), toReferenceSystem), shapeFieldType);
  }

  static class MyHandler implements CRSHandler<MyCRS> {
      static final MyCRS DEFAULT_TO_CRS;

      private final MyTransform transform;
      private final MyPoint reusableFrom;
      private final MyPoint reusableTo;

      static {
          try {
              DEFAULT_TO_CRS = MyCRS.forCode(DEFAULT_TARGET_CRS_EPSG_CODE);
          } catch (FactoryException e) {
              throw new RuntimeException(e);
          }
      }

      MyHandler(
          final MyCRS fromCRS,
          final MyCRS toCRS,
          final MyTransform transform,
          final GeometryProcessorFieldType shapeFieldType
      ) {
          this.transform = transform;
          this.reusableFrom = new MyPoint(fromCRS);
          this.reusableTo = new MyPoint(toCRS);
      }

      @Override
      public MyCRS getFromCRS() {
          return reusableFrom.getCoordinateReferenceSystem();
      }

      @Override
      public MyCRS getToCRS() {
          return reusableTo.getCoordinateReferenceSystem();
      }

      @Override
      public void reproject(final double[] from, double[] to, final double tolerance) throws Exception {
          // Custom reprojection logic
      }
  }
}

To activate the provider with Java SPI, add the following line to ./resources/META-INF/services/io.skylite.geographic.referencing.CRSProviderInterface in the generated jar file in your plugin zip: com.example.geographic.referencing.MyReprojectionProvider

You will now be able to use your custom provider by providing it's registered NAME in the provider parameter of the search processor:

PUT /_search/pipeline/reproject_to_mercator
{
  "description" : "reproject spatial query result geometries from EPSG:4326 lat,lon WGS84 coordinate system to EPSG:3857 X,Y mercator coordinate system",
  "response_processors" : [
    {
      "reproject" : {
        "field" : "geometry",
        "target_field" : "geometryMercator",
        "target_crs" : "EPSG:3857",
        "provider" : "my_crs_provider"
      }
    }
  ]
}

Lucenia will discover and register your custom provider automatically on startup.

Summary

Lucenia’s reprojection processors allow seamless integration of data and queries across coordinate systems without requiring reindexing or external tools. Whether your users operate in Web Mercator, UTM zones, or Mars-based CRS, Lucenia handles the transformation transparently using robust, high-performance search pipelines.