Ellipse ingest processor

Introduced 0.2.0

The ellipse ingest processor converts an ellipse geometry — supplied as either Well-Known Text (WKT) or GeoJSON — into a regular polygon approximation at index time and stores it in a geo_shape or shape field. Ellipses model directional or asymmetric coverage areas (for example, cellular sector coverage, sensor footprints, or search-and-rescue probability areas) more accurately than a single point or a uniform circle.

Because Lucenia indexes the polygonized representation, you can run the full set of spatial queries (geo_shape intersects, within, disjoint, and contains) against the resulting field without any additional client-side preprocessing.

Request fields

The following table lists all available request fields.

Field	Type	Description	Required
field	String	The source field containing the ellipse. The value must be either a WKT ELLIPSE(...) string or a GeoJSON-style object (see Input formats).	Yes
error_distance	Double	The maximum tolerated error, in meters, between the true ellipse and its polygon approximation. Smaller values produce more polygon sides (higher fidelity) at the cost of indexing speed and storage. Natural-language distances such as "1m" or "10cm" are accepted by the underlying parser.	Yes
shape_type	String	The field-mapping type used for the output polygon. Must be either geo_shape (geographic lat/lon) or shape (cartesian X/Y).	Yes
target_field	String	The field that will receive the polygonized ellipse. Defaults to the same value as field, overwriting the original ellipse.	No
ignore_missing	Boolean	If true and the source field is missing from the document, the processor quietly exits without modifying the document. Defaults to false.	No

Input formats

The processor accepts the ellipse geometry in two equivalent forms.

Well-Known Text (WKT)

Lucenia extends WKT with an ELLIPSE primitive:

ELLIPSE(centerLon centerLat semiMajorAxisMeters semiMinorAxisMeters orientationDegrees)

For example, an ellipse centered at (101.0, 1.0) with a 10-meter semi-major axis, 5-meter semi-minor axis, and rotated 45° from north:

ELLIPSE(101.0 1.0 10 5 45)

GeoJSON

{
  "type": "ellipse",
  "coordinates": [101.0, 1.0],
  "semiMajorAxis": "10m",
  "semiMinorAxis": "5m",
  "orientationDegrees": 45
}

semiMajorAxis and semiMinorAxis accept natural-language distances (for example, "10m", "500cm", or "1.2km").

Example

The following walkthrough builds a small pipeline that ingests cellular-tower coverage ellipses, then runs a spatial query against them. It mirrors the Ellipse Ingest Processor tutorial, which provides the matching demo data set.

Step 1: Create the index

Map the destination field as geo_shape so the polygonized ellipse can be indexed and queried geographically:

PUT /cellular_towers
{
  "mappings": {
    "properties": {
      "tower_id":   { "type": "keyword" },
      "site_name":  { "type": "text" },
      "location":   { "type": "geo_point" },
      "ellipse":    { "type": "geo_shape" },
      "maintenance": {
        "properties": {
          "installation_date": {
            "type": "date",
            "format": "yyyy-MM-dd"
          }
        }
      }
    }
  }
}

Step 2: Create the ingest pipeline

PUT /_ingest/pipeline/ellipse_pipeline
{
  "description": "Index ellipses from WKT or GeoJSON",
  "processors": [
    {
      "ellipse": {
        "field": "ellipse",
        "error_distance": 0.01,
        "shape_type": "geo_shape"
      }
    }
  ]
}

An error_distance of 0.01 meters (1 cm) yields a high-fidelity polygon. Increase the value to reduce the number of polygon sides when indexing throughput or storage is the priority.

Step 3: Index a document through the pipeline

The following request uses the WKT form. The processor replaces the value of the ellipse field with a polygon before the document is indexed:

PUT /cellular_towers/_doc/1?pipeline=ellipse_pipeline
{
  "tower_id": "TWR-0001",
  "site_name": "North Ridge",
  "location": { "lat": 1.0, "lon": 101.0 },
  "ellipse": "ELLIPSE(101.0 1.0 250 120 30)",
  "maintenance": {
    "installation_date": "2021-08-14"
  }
}

The GeoJSON form is equivalent:

PUT /cellular_towers/_doc/2?pipeline=ellipse_pipeline
{
  "tower_id": "TWR-0002",
  "site_name": "South Ridge",
  "location": { "lat": 1.01, "lon": 101.02 },
  "ellipse": {
    "type": "ellipse",
    "coordinates": [101.02, 1.01],
    "semiMajorAxis": "300m",
    "semiMinorAxis": "150m",
    "orientationDegrees": 75
  },
  "maintenance": {
    "installation_date": "2019-03-02"
  }
}

Step 4: Query overlapping coverage

Because the indexed value is a standard geo_shape polygon, any geo_shape query works. The following search returns towers whose coverage overlaps a target polygon and were installed more than two years ago:

GET /cellular_towers/_search
{
  "query": {
    "bool": {
      "must": [
        {
          "geo_shape": {
            "ellipse": {
              "shape": {
                "type": "envelope",
                "coordinates": [ [100.99, 1.02], [101.03, 0.99] ]
              },
              "relation": "intersects"
            }
          }
        }
      ],
      "filter": {
        "range": {
          "maintenance.installation_date": {
            "lt": "now-2y"
          }
        }
      }
    }
  }
}

Tuning error_distance

The processor converts an ellipse to a regular polygon whose vertex count is derived from error_distance and the ellipse's semi-axes. As a rule of thumb:

• Use a small value (centimeters to a few meters) when downstream analytics rely on precise boundary geometry — for example, identifying narrow strips of overlap between adjacent sector coverages.
• Use a larger value (tens of meters) when you are ingesting millions of ellipses and approximate footprints are sufficient — for example, coarse coverage heatmaps or screening queries that are later refined by a more expensive check.

error_distance is always interpreted as a positive distance; negative values are coerced to their absolute value.

Output shape type

The shape_type parameter selects the indexing primitive used for the polygonized result:

• geo_shape — geographic coordinates (longitude, latitude in degrees). Use this when the source ellipse is defined in WGS84 and you want spherical-earth semantics.
• shape — planar X/Y coordinates. Use this when the source ellipse is already in a projected coordinate system. To reproject incoming geometries from another CRS before applying the ellipse processor, chain it with the spatial reprojection processor.

info

The target_field parameter accepts the same field name as field, in which case the original ellipse representation is replaced by its polygonized form. Set target_field to a different field if you need to retain the original WKT or GeoJSON alongside the indexed polygon.