realm.area

Areas describe a circular, rectangular or polygonal section within a realm. They are a great way to demark districts of a city, fields within a farm, buildings within a complex or security zones on a mining site. They can also act as a stationary or roaming geofence and provide a filtering mechanism for objects in subscriptions and instructions.

Shape Data Structure

Your areas can be circles, rectangles or polygons. For each, the data structure looks a little bit different. You don't need to specify which kind of shape you want - Hivekit will guess based on the values in your shape structure.

Circle

{
    // longitude of the circle's center in degree
    cx: 8.812937349780645,
    // latitude of the circle's center in degree
    cy: 54.33334283065705, 
    // radius of the circle in meter
    r: 300
}

Rectangle

{
    // longitude of the western side of the rectangle
    x1: -0.033536750798090945,
    // latitude of the northern side of the rectangle
    y1: 51.52172026165903,
    // longitude of the eastern side of the rectangle
    x2: -0.0327062299280377,
    // latitude of the southern side of the rectangle
    y2: 51.52104216363214
}

Polygon

Polygons can define any irregular shape. The points need to be in order. The last point will be connected to the first. Hivekit currently does not support holes in polygonal areas.

{
    points: [
        // x = longitude, y = latitude
        { x: -80.19  ,y: 25.774 },
        { x: -66.118 ,y: 18.466 },
        { x: -64.757 ,y: 32.321 },
    ]
}

Methods

realm.area.create(id, options)

Creates a new area

• id a unique identifier for this area within its realm
• options optional parameters that define the area
• options.label a name for the area
• options.shape the shape of the area
• options.data meta data for the area, e.g. display properties like color
• returns Promise success

await myRealm.area.create('berlin/kreuzberg', {
    label: 'Kreuzberg',
    shape: { cx:  13.40388, cy: 52.49871, r: 1000},
    data: { color: '#FF00FF'}
})

realm.area.get(id)

Returns the data for an existing area

• id a unique identifier for this area within its realm
• returns Promise area data

kreuzberg = await myRealm.area.get('berlin/kreuzberg')

kreuzberg = {
  label: 'Kreuzberg',
  shape: 'circle',
  shapeData: { cx:  13.40388, cy: 52.49871, r: 1000},
  data: { color: '#FF00FF' }
}

realm.area.update(id, options)

Updates an existing area.

• id a unique identifier for this area within its realm
• options optional parameters that define the area
• options.label a name for the area
• options.shape the shape of the area
• options.data meta data for the area, e.g. display properties like color
• returns Promise success

myRealm.area.update('geofence/b14', {
    shape: {
        x1: -0.03353,
        y1: 51.52172,
        x2: -0.03270,
        y2: 51.521
    }
})

realm.area.delete(id)

Deletes an existing area

• id a unique identifier for this area within its realm
• returns Promise success

realm.area.list()

Lists all areas within a realm

• returns Promise area list

const areas = await myRealm.area.list();

areas = {
'berlin/mitte': {id:'berlin/mitte', label: 'Mitte',  shape: 'rectangle' },
'berlin/kreuzberg': {id:'berlin/kreuzberg', label: 'Kreuzberg',  shape: 'circle' },
'berlin/neukoelln': {id:'berlin/neukoelln', label: 'Neukoelln',  shape: 'polygon' },
}

realm.area.subscribe(options)

Subscribes to the creation,updating and deletion of areas.

• options is an optional object with the following attributes
• options.where an array of attribute selectors, e.g. ['city=kiev']
• options.executeImmediately if true, the subscription is triggered immediatly with all objects matching the given criteria. If false or ommited, the subscription will only notify you once something changes.
• returns Promise subscription

const subscription = await myRealm.area.subscribe({
    executeImmediately: true,
    where: ['city="kyiv"'],
});
subscription.on('update', areas => {
    // do something with the list of areas
})