Geospatial Maps (geomap)

Geo Map is a GPS coordinates based dataset which can be used to find the nearby object and handle position objects easily.

Mobility is one of the key use case for IoT. IoTIFY provides several helper functions to handle mobility simulation, such as drive() to simulate moving vehicles under real traffic conditions.
One of the key requirement of any simulation is to find the nearby objects. E.g. a simulated car may need to find a nearby patrol pump or charging station and drive towards.
A simulated passenger may need to call a nearby taxi. A truck needs to find nearby trucks to enable platooning. All such use case require a dataset which is geospatially indexed.

Geo Map is another form of gset which is based on location, i.e. Lattitude and Longitude.

Lets take an example

{
geomap.set('mymap', 'car1', 12.225222, 12.2333333);
geomap.set('mymap', 'car2', 12.224223, 12.2353333);
geomap.set('mymap', 'car3', 12.225223, 12.2363333);
// list all cars in the current map set
state.map = geomap.get('mymap');
// Get car3's position
geomap.get('mymap', 'car3');
// find all object near car2 in 1000 meter radius
state.near = geomap.findNear('mymap', 'car2', 1000);
// find all object near given coordinates in 1000 meter radius
state.near = geomap.findWithin('mymap',12.222223, 12.2333333, 1000);
// delete the location of car2
geomap.delete('mymap', 'car2');
}

Above example shows the potential of geomap to deal easily with location based objects. Geomap object provides following functions

geomap.set(key, item, latitude, longitude, function(result){})

key: Must be a string

item: Must be a string identifying an object

latitude: Float specifying the object latitude

longitude: Float specifying the object longitude

callback: where success is true or false, indicating the result of operation.

The API returns true in callback if Geomap item can be stored successfully , else false.
There is no need to create geomap object beforhand. A new set will be created if it is empty.

Note: If callback is ommitted, the API performs synchronously and returns the success bool. Synchronous calling slows down the simulation speed drastically and should be avoided.

geomap.get(key, item, function(result){})

key: Must be a string

item: Should be a string identifying an object. If getting all items in the set, please pass undefined.

callback: called with the position of the given item or an array containing list of all the items.

If item is not specified, the API returns all the items currently available in geomap object.
The items are retuned as an array of string e.g. [“car1”, “car2”]

If item is given, the API returns the [lat, lng] for the given item if found in specified geomap.
If key can not be found, the function returns null

Note: If callback is ommitted, the API performs synchronously and returns the expected results. Synchronous calling slows down the simulation speed drastically and should be avoided.

geomap.delete(key, item, function(success){})

key: Must be a string

item: Must be a string identifying an object

callback: where success is true or false, indicating the result of operation.

The API erases the item and its coordinates stored in geompa object if found and return true, else false.

Note: If callback is ommitted, the API performs synchronously and returns the expected results. Synchronous calling slows down the simulation speed drastically and should be avoided.

geomap.purge(key, function(success){})

key: Must be a string

callback: where success is true or false, indicating the result of operation.

The API erases the geomap object and all of its items.

Note: If callback is ommitted, the API performs synchronously and returns the expected results. Synchronous calling slows down the simulation speed drastically and should be avoided.

geomap.findNear(key, item, radius, function(result){})

key: Must be a string

item: Must be a string identifying an object

radius: Radius from item in meters

callback: called with the array containing list of all the nearby items.

This API returns all nearby object of the item in the radius of given value. An array of items is returned e.g. [“car1”, “car2”]
If item didn’t exist, it will return null. If no nearby object can be found, it will return an empty array.

Note: If callback is ommitted, the API performs synchronously and returns the expected results. Synchronous calling slows down the simulation speed drastically and should be avoided.

geomap.findWithin(key, latitude, longitude, radius, function(result){})

key: Must be a string

latitude: Float specifying the object latitude

longitude: Float specifying the object longitude

radius: Radius from item in meters

callback: called with the array containing list of all the nearby items.

This API returns all nearby object of the given coordinates in the radius of given value. An array of items is returned e.g. [“car1”, “car2”]
If item didn’t exist, it will return null. If no nearby object can be found, it will return an empty array.

Note: If callback is ommitted, the API performs synchronously and returns the expected results. Synchronous calling slows down the simulation speed drastically and should be avoided.