or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-geometry.mdformat-conversion.mdindex.mdmulti-geometry.mdsimplification.mdspatial-utilities.mdvalidation.mdvisitor-pattern.md
tile.json

tessl/maven-org-elasticsearch--elasticsearch-geo

Elasticsearch geometry library providing core geometric shapes and spatial utility classes for geometric computations and operations.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.elasticsearch/elasticsearch-geo@9.1.x

To install, run

npx @tessl/cli install tessl/maven-org-elasticsearch--elasticsearch-geo@9.1.0

index.mddocs/

Elasticsearch Geo

The Elasticsearch Geo library is a Java geometry library providing comprehensive geometric shapes and spatial utility classes for Elasticsearch's geo-spatial functionality. It offers zero-dependency geometric primitives with built-in validation, standardization utilities, and efficient operations for handling geospatial data processing workflows.

Package Information

  • Package Name: org.elasticsearch:elasticsearch-geo
  • Language: Java
  • Installation: Add to Maven pom.xml: 
    <dependency>
  <groupId>org.elasticsearch</groupId>
  <artifactId>elasticsearch-geo</artifactId>
  <version>9.1.3</version>
</dependency>

Core Imports

// Core geometry classes
import org.elasticsearch.geometry.Point;
import org.elasticsearch.geometry.Circle;
import org.elasticsearch.geometry.Polygon;
import org.elasticsearch.geometry.Rectangle;
import org.elasticsearch.geometry.Line;
import org.elasticsearch.geometry.LinearRing;

// Multi-geometry collections
import org.elasticsearch.geometry.MultiPoint;
import org.elasticsearch.geometry.MultiLine;
import org.elasticsearch.geometry.MultiPolygon;
import org.elasticsearch.geometry.GeometryCollection;

// Base interfaces and visitor pattern
import org.elasticsearch.geometry.Geometry;
import org.elasticsearch.geometry.GeometryVisitor;
import org.elasticsearch.geometry.ShapeType;

// Utility classes
import org.elasticsearch.geometry.utils.WellKnownText;
import org.elasticsearch.geometry.utils.WellKnownBinary;
import org.elasticsearch.geometry.utils.Geohash;
import org.elasticsearch.geometry.utils.GeometryValidator;
import org.elasticsearch.geometry.utils.StandardValidator;
import org.elasticsearch.geometry.utils.GeographyValidator;
import org.elasticsearch.geometry.utils.SpatialEnvelopeVisitor;
import org.elasticsearch.geometry.utils.CircleUtils;
import org.elasticsearch.geometry.utils.BitUtil;

Basic Usage

// Create a simple point geometry
Point point = new Point(-73.935242, 40.730610); // longitude, latitude

// Create a circle around the point with 1000 meter radius
Circle circle = new Circle(-73.935242, 40.730610, 1000.0);

// Create a polygon with a linear ring
double[] lons = {-74.0, -73.9, -73.9, -74.0, -74.0};
double[] lats = {40.7, 40.7, 40.8, 40.8, 40.7};
LinearRing ring = new LinearRing(lons, lats);
Polygon polygon = new Polygon(ring);

// Convert geometry to Well-Known Text format
String wkt = WellKnownText.toWKT(point);
// Result: "POINT(-73.935242 40.730610)"

// Parse WKT back to geometry
GeometryValidator validator = StandardValidator.instance(true);
Geometry parsed = WellKnownText.fromWKT(validator, false, "POINT(-73.935242 40.730610)");

Architecture

The library is built around several core concepts:

  • Geometry Interface: Base interface implemented by all geometry types, providing type information and visitor pattern support
  • Visitor Pattern: Type-safe processing of different geometry types through the GeometryVisitor interface
  • Shape Types: Enumeration defining all supported geometry types (Point, Polygon, Circle, etc.)
  • Format Support: Utilities for converting between geometry objects and standard formats (WKT, WKB, GeoHash)
  • Validation Framework: Pluggable validation system for ensuring geometric validity
  • Simplification Framework: Memory-efficient algorithms for reducing geometry complexity while preserving essential features

Capabilities

Core Geometry Types

Create and manipulate fundamental geometric shapes including points, circles, rectangles, lines, and polygons with support for 2D and 3D coordinates.

// Basic 2D point
Point point2d = new Point(-73.935242, 40.730610);

// 3D point with altitude
Point point3d = new Point(-73.935242, 40.730610, 150.0);

// Circle with radius in meters
Circle circle = new Circle(-73.935242, 40.730610, 1000.0);

// Rectangle (bounding box)
Rectangle bbox = new Rectangle(-74.0, -73.9, 40.8, 40.7); // minX, maxX, maxY, minY

// Line with multiple points
double[] lons = {-74.0, -73.9, -73.8};
double[] lats = {40.7, 40.75, 40.8};
Line line = new Line(lons, lats);

Core Geometry Types

Multi-Geometry Collections

Work with collections of geometries including MultiPoint, MultiPolygon, and generic geometry collections.

// Collection of points
List<Point> points = Arrays.asList(
    new Point(-73.935242, 40.730610),
    new Point(-73.935242, 40.730610)
);
MultiPoint multiPoint = new MultiPoint(points);

// Collection of polygons
List<Polygon> polygons = Arrays.asList(polygon1, polygon2);
MultiPolygon multiPolygon = new MultiPolygon(polygons);

// Generic geometry collection
List<Geometry> geometries = Arrays.asList(point, circle, polygon);
GeometryCollection<Geometry> collection = new GeometryCollection<>(geometries);

Multi-Geometry Collections

Format Conversion

Convert geometries to and from standard geospatial formats including Well-Known Text (WKT), Well-Known Binary (WKB), and GeoHash.

// WKT conversion
String wkt = WellKnownText.toWKT(geometry);
Geometry geometry = WellKnownText.fromWKT(validator, false, wktString);

// WKB conversion  
byte[] wkb = WellKnownBinary.toWKB(geometry, ByteOrder.BIG_ENDIAN);

// GeoHash operations
String geohash = Geohash.stringEncode(-73.935242, 40.730610, 12);
Point point = Geohash.toPoint(geohash);
Rectangle bounds = Geohash.toBoundingBox(geohash);

Format Conversion

Visitor Pattern Processing

Process different geometry types in a type-safe manner using the visitor pattern, enabling extensible operations on geometric data.

// Custom visitor implementation
public class AreaCalculator implements GeometryVisitor<Double, RuntimeException> {
    @Override
    public Double visit(Circle circle) {
        return Math.PI * Math.pow(circle.getRadiusMeters(), 2);
    }
    
    @Override
    public Double visit(Rectangle rectangle) {
        double width = rectangle.getMaxX() - rectangle.getMinX();
        double height = rectangle.getMaxY() - rectangle.getMinY();
        return width * height;
    }
    
    // ... implement other visit methods
}

// Use visitor
AreaCalculator calculator = new AreaCalculator();
Double area = geometry.visit(calculator);

Visitor Pattern Processing

Validation Framework

Validate geometries using pluggable validation framework with standard and geography-specific validators.

// Standard validation
GeometryValidator validator = StandardValidator.instance(false);
validator.validate(geometry); // throws IllegalArgumentException if invalid

// Geography validation (lat/lon bounds checking)
GeometryValidator geoValidator = GeographyValidator.instance(false);
geoValidator.validate(geometry);

// No-op validator
GeometryValidator noop = GeometryValidator.NOOP;

Validation Framework

Spatial Utilities

Additional spatial utility functions for envelope calculation, circle conversion, and bit manipulation operations.

// Calculate spatial envelope (bounding box) of geometry
Optional<Rectangle> envelope = SpatialEnvelopeVisitor.visit(geometry);

// Convert circle to regular polygon
Polygon circlePolygon = CircleUtils.createRegularGeoShapePolygon(circle, 64);

// Bit manipulation for spatial indexing
long interleaved = BitUtil.interleave(xBits, yBits);
int deinterleaved = BitUtil.deinterleave(interleavedValue);

Spatial Utilities

Geometry Simplification

Simplify complex geometries using memory-efficient algorithms while preserving essential geometric features.

// Use built-in error calculator
SimplificationErrorCalculator calculator = SimplificationErrorCalculator.TRIANGLE_AREA;

// Create streaming simplifier for coordinate processing
StreamingGeometrySimplifier<Polygon> streamingSimplifier = 
    new StreamingGeometrySimplifier<>(1000, calculator, null);

// Process coordinates one by one (memory efficient)
streamingSimplifier.addPoint(-74.0, 40.7, Double.NaN);
streamingSimplifier.addPoint(-73.9, 40.7, Double.NaN);
// ... add more points
Polygon simplified = streamingSimplifier.finish();

// Get error calculator by name
SimplificationErrorCalculator heightCalculator = 
    SimplificationErrorCalculator.byName("triangleheight");

Geometry Simplification