Spatial Index

Optimised data structure for spatial search

Overview

Joule provides implementation of a spatial Index based on the Quad Tree data structure and algorithm. The search area is divided in to rectangle and thus the world is flattened from a sphere in to a rectangle spatial index.

This feature is provided as a service which can be embedded within custom processors and has its own DSL.

DSL Example

The below example creates a search tree of the world as flattened rectangle.

spatial index:
  top left coordinates: [-180f,-90f]
  width: 360
  area: 64800
  max levels: 24
  preferred max elements: 50

Attributes schema

AttributeDescriptionData TypeRequired

top left coordinates

North west coordinate to create the spatial index

Float Default: [-180f, -90f]

width

Width of the search area in terms of degrees

Integer

Default: 360

area

Search area

Integer

Default: 64800

max levels

Maximun number of sub spatial indexes. Range must be within 0 to 24.

Integer

Default: 16

preferred max elements

Maximun number of elements within a bounded area.

Integer

Default: 500

API Example

This example demonstrates how to query initialise the spatial index and query it thereafter within a custom processor.

private QuadTree<GeoFence> geoFenceSearchTree;

@Override
public void initialize(Properties prop) throws ProcessorException {
    super.initialize(prop);
    geoFenceSearchTree.initialise();
    
    // Other custom initialization
}

/**
* Query the geoFenceSearchTree with passed location information 
*
* @param event
* @param entityLatitude
* @param entityLongitude
*/
private GeoTrackingInfo queryGeospace(final StreamEvent event, final double entityLatitude, final double entityLongitude){
    // Perform geofence search
    Collection<GeoFence> foundGeoFences = geoFenceSearchTree.query(new Tuple<>(entityLatitude, entityLongitude));
    Object trackingKey = event.getValue(trackingEventKey);
    
    // Update stateful tracking
    GeoTrackingInfo info = state.get(trackingKey);
    
    info.setCurrentLatLng(entityLatitude, entityLongitude, event.getEventTime());
    info.setCurrentGeofenceIds(foundGeoFences);
    
    return info;        
}

/**
* Set QuadTree for processor
*
* @param geoFenceSearchTree
*/
@JsonProperty(value = "spatial index")
public void setGeoFenceSearchTree(QuadTree<GeoFence> geoFenceSearchTree) {
   this.geoFenceSearchTree = geoFenceSearchTree;
}

Last updated