Nuanced Pterodactyl Monk

    @awarns/geofencing
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.0 • Public • Published

    @awarns/geofencing

    npm (scoped) npm

    This module allows to perform basic geofencing analysis based on the locations obtained by the tasks declared in the @awarns/geolocation package. It is also compatible with any other custom entity matching the GeolocationLike interface (for example, an entity produced by a custom indoor positioning system).

    The geofencing mechanism inside this package allows to detect multiple degrees of nearness towards the registered areas of interest.

    Install the plugin using the following command line instruction:

    ns plugin add @awarns/geofencing

    Usage

    After installing and configuring this plugin, you'll be granted with two interaction mechanisms to work with it:

    1. The plugin API. Through it, you'll be able to configure and update the areas of interest which are relevant to your application.
    2. The geofencing task, which allows to detect if one or more locations which have just been acquired are close to one or more registered areas of interest. When a change in the proximity is detected, this task emits an AoIProximityChange record, described below.

    API

    areasOfInterest

    The areasOfInterest singleton object is the main plugin entrypoint. Through it, you can set up and manage areas of interest. This is the complete API:

    Method Return type Description
    insert(aois: Array<AreaOfInterest>) Promise<void> Inserts the given list of areas of interest into the local database. More details on the AreaOfInterest interface right after this table
    getById(id: string) Promise<AreaOfInterest> Allows to retrieve a stored area of interest by its id
    getAll() Promise<Array<AreaOfInterest>> Allows to retrieve all the stored areas of interest at once
    list() Observable<Array<AreaOfInterest>> Allows to observe changes in all the stored areas of interest. It is recommended to install the RxJS package too, to operate with the output of this method
    deleteAll() Promise<void> Allows to clear all the stored areas of interest at once

    AreaOfInterest

    Property Type Description
    id string The unique identifier of the area
    name string A display name for the area
    longitude number The longitude of the center of the area
    latitude number The latitude of the center of the area
    radius number The radius of the area, from its center's longitude and latitude
    category string (Optional) Free text field, can be used to classify the area in an arbitrary category
    level number (Optional) Can be used to rank areas

    Tasks

    Task name Description
    checkAreaOfInterestProximity Given one or more locations included in the payload of the event invoking the task, this task checks their proximity towards a set of registered areas of interest
    filterGeolocationByAoIProximity Given one or more locations included in the payload of the event invoking the task, this task checks their proximity towards a set of registered areas of interest and only outputs those that fall nearby or inside their radii

    Check area of interest proximity

    To register this task for its use, you just need to import it and call its generator function inside your application's task list:

    import { Task } from '@awarns/core/tasks';
    import { checkAreaOfInterestProximityTask } from '@awarns/geofencing';
    
    export const demoTasks: Array<Task> = [
        checkAreaOfInterestProximityTask(),
    ];

    Task generator parameters:

    The task generator takes no parameters.

    Task output events:

    Example usage in the application task graph:

    on(
      'startEvent',
      run('acquirePhoneGeolocation')
        .every(1, 'minutes')
        .cancelOn('stopEvent')
    );
    
    on(
      'geolocationAcquired',
      run('checkAreaOfInterestProximity', {
        nearbyRange: 100, // Area approximation radius, in meters (defaults to 100)
        offset: 15, // Optional distance calculation offset, in meters. Can help mitigating location error (defaults to 0)
      })
    );
    
    on('movedCloseToAreaOfInterest', run('writeRecords'));
    on('movedInsideAreaOfInterest', run('writeRecords'));
    on('movedOutsideAreaOfInterest', run('writeRecords'));
    on('movedAwayFromAreaOfInterest', run('writeRecords'));

    Note: To use the acquirePhoneGeolocation and writeRecords tasks, the geolocation and persistence packages must be installed and configured. See geolocation package and persistence package docs.

    Filter geolocations based on area of interest proximity

    To register this task for its use, you just need to import it and call its generator function inside your application's task list:

    import { Task } from '@awarns/core/tasks';
    import { filterGeolocationByAoIProximityTask } from '@awarns/geofencing';
    
    export const demoTasks: Array<Task> = [
      filterGeolocationByAoIProximityTask(),
    ];

    Task generator parameters:

    The task generator takes no parameters.

    Task output events:

    Example usage in the application task graph:

    on(
      'startEvent',
      run('acquirePhoneGeolocation')
        .every(1, 'minutes')
        .cancelOn('stopEvent')
    );
    
    on(
      'geolocationAcquired',
      run('filterGeolocationByAoIProximity', {
        nearbyRange: 100, // Area approximation radius, in meters (defaults to 100)
        offset: 15, // Optional distance calculation offset, in meters. Can help mitigating location error (defaults to 0)
        includeNearby: true // Optional indicate if points nearby an area should be taken into consideration (defaults to false)
      })
    );
    
    on('geolocationCloseToAoIAcquired', run('writeRecords')); // Just write the locations captured nearby an area of interest

    Note: To use the acquirePhoneGeolocation and writeRecords tasks, the geolocation and persistence packages must be installed and configured. See geolocation package and persistence package docs.

    Events

    Name Payload Description
    movedCloseToAreaOfInterest Array<AoIProximityChange> Detected that one or more of the given locations represent an approximation towards the surroundings of one or more registered areas of interest. The approximation radius can be configured in the application workflow. See an example below this table
    movedInsideAreaOfInterest Array<AoIProximityChange> Detected that one or more of the given locations have just fallen between the center of one or more registered areas and their radii
    movedOutsideAreaOfInterest Array<AoIProximityChange> Detected that one or more of the given locations have just fallen outside one or more area radii, but are still within their approximation radii. This event won't fire while there's still a location that falls inside an area
    movedAwayFromAreaOfInterest Array<AoIProximityChange> Detected that one or more of the given locations have just fallen completely outside one or more area approximation radii. This event won't fire while there's still a location that falls inside the approximation radius of an area
    geolocationCloseToAoIAcquired 'Geolocation' | 'Array' A location or a list of locations which have passed the area of interest filter (fall nearby or inside the known areas)

    Records

    AoIProximityChange

    Property Type Description
    id string Record's unique id
    type string Always aoi-proximity-change
    change Change Can be either start or end. The former indicates a transition to the proximity indicated by the the record, whereas the later indicates no longer being in the reported level of proximity
    timestamp Date The local time when the proximity change was detected
    aoi AreaOfInterest The area of interest towards which the proximity change has been detected
    proximity GeofencingProximity Indicates the relative proximity towards the area. Look at the change property to identify if the change is towards the proximity or contrary to it. See all the proximity options below

    GeofencingProximity

    Option Description
    INSIDE One or more locations fall within the center and the radius of an area
    NEARBY One or more locations fall outside the center and the radius of an area, but they fall within its approximation radius
    OUTSIDE One or more locations fall completely outside an area and its approximation radius. This option will never be used in an AoIProximityChange record

    License

    Apache License Version 2.0

    Install

    npm i @awarns/geofencing

    DownloadsWeekly Downloads

    0

    Version

    1.1.0

    License

    Apache-2.0

    Unpacked Size

    58.4 kB

    Total Files

    47

    Last publish

    Collaborators

    • matey
    • albertogonper