Sunstone Map

An angular library to help create maps for the Sunstone-RTLS system.

Installing

Install by running the following the command:

npm install sunstone-map

The dependencies get installed automatically, but you have to include their stylesheets manually.

Stylesheets that needs to be added:

"node_modules/leaflet/dist/leaflet.css",
"node_modules/leaflet.pm/dist/leaflet.pm.css"

Usage

Import SunstoneMapModule into your app or feature module:

import {SunstoneMapModule} from 'sunstone-map'
 
@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    SunstoneMapModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

The library provides a single component called SunstoneMapComponent. A map can be created through this component.

Creating a map

Create a new angular component that will house your map.

Add the sunstone map to your component's template file. Note that the component must be wrapped into a div width fixed width and height in order for the map to show up.

<div class="map">
    <sunstone-map
        [imageUrl]="'https://omt-hq.sunstone-cloud.com/settings/map/svg'"
        [mapConfig]="mapConfig"
        [settings]="settings"
    ></sunstone-map>
</div>

The SunstoneMapComponent has many attributes and events that can be set, three of which are mandatory: imageUrl,mapConfig,settings Read more abut the attributes here.

Adding tags to the map

First create a field in your components ts file to store the tags and bind to the SunstoneMapComponent tagList attribute

app.component.ts:

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
    //load the tag data from api
    tags: TagModel[] = [
        {
            pos: [0,0],
            tagId: 12
        }
    ];
 
    settings: FeatureSettings = {
        useWithTags: true,
 
        tagFeatures: {},
        zoneFeatures: {},
        pathFeatures: {}
  };
  //load it from the api
  mapConfig: MapConfigModel;
}

app.component.html:

<div class="map">
    <sunstone-map
        [imageUrl]="'https://omt-hq.sunstone-cloud.com/settings/map/svg'"
        [mapConfig]="mapConfig"
        [settings]="settings"
        [tagList]="tags"
    ></sunstone-map>
</div>

Handling tag selection

If you want to handle selecting tag on the map you need to expand the previous example the following way:

app.component.ts:

 
selectedTag: TagModel;
 
 settings: FeatureSettings = {
        useWithTags: true,
 
        tagFeatures: {
            useSelectedTag: true, // use tag selection
        },
        zoneFeatures: {},
        pathFeatures: {}
  };
 
//tag selection event handler
tagSelected(tag: TagModel) {
    this.selectedTag = tag;
    //do whatever
}
 

app.component.html:

<div class="map">
    <sunstone-map
        [imageUrl]="'https://omt-hq.sunstone-cloud.com/settings/map/svg'"
        [mapConfig]="mapConfig"
        [settings]="settings"
        [tagList]="tags"
        (selectedTag)="selectedTag"
        (tagSelected)="tagSelected($event)"
    ></sunstone-map>
</div>

Reference

SunstoneMapComponent

Attributes

Attribute	Type	Description
imageUrl	string	Url for the map image
mapConfig	MapConfigModel	The Sunstone mapconfig from the api used to set up the map transformations
settings	FeatureSettings	Settings that turns on or off map featuers
tagList	TagModel[]	Array of tags to be displayed on the map
anchorList	AnchorModel[]	Array of anchors to be displayed on the map
selectedTag	TagModel	The selected tag
zoneList	ZoneModel[]	Array of zones to be displayed on the map
spaghettiData	SpaghettiData[]	Array of spaghetti data to display paths and/or heat on the map
minTime	number	Used with spaghetti data, the minimum time that the path should be displayed from
maxTime	number	Used with spaghetti data, the maximum time that the path should be displayed to

Events

Event	Data	Description
tagSelected	TagModel	Fired when a tag is selected (clicked) on the map.
mapLoaded	Map	Fired when the map finished loading.
zoneCreated	{upperBounds: number[], lowerBounds: number[]}	Fired when a new zone is created.
zoneEdited	ZoneModel	Fired when a zone is edited.
zoneRemoved	ZoneModel	Fired when a zone is removed.
zoneSelected	ZoneModel	Firead when a zone is selected.

Functions

Name	Return type	Arguments	Description
forceUpdate	void	-	Forcefully updates the elements on the map,ignoring change detection.

Models

MapConfigModel

Interface for mapconfig data from the Sunstone RestAPI. Read more here

export interface MapConfigModel {
    scale: number;
    xoff: number;
    yoff: number;
    xmirror: number;
    ymirror: number;
    switchxy: number;
  }

FeatureSettings

Settings that turns on or off map featuers

Setting	Type	Description
useWithTags	boolean	Whether to display tags on the map or not. Requires tagList attribute to be set.
useWithHeat	boolean	Whether to display heat on the map or not. Requires spaghettiData attribute to be set.
useWithAnchors	boolean	Whether to display anchors on the map or not. Requires anchorList attribute to be set.
useWithZones	boolean	Whether to display zones on the map or not. Requires zoneList attribute to be set.
useWithPath	boolean	Whether to display paths on the map or not. Requires spaghettiData attribute to be set.
tagFeatures	TagFeatures	Tag specific settings
zoneFeatures	ZoneFeatures	Zone specific settings
pathFeatures	PathFeatures	Path specific settings
heatFeatures	HeatFeatures	Heat specifi settings

TagFeatures

Tag specific settings

Setting	Type	Description
followSelected	boolean	If true the map will pan to the tag when selected and follow it around when it moves.
useSelectedTag	boolean	Sets if a selected tag will be used. Related attributes and events will only work if this is true.
selectedTagColor	string	The selected tag's color in hex color format. Default: #00FF00
trailMovement	boolean	Sets it so the movement of the tag will be trailed by dots
maxTrail	number	How long the trail should be

ZoneFeatures

Zone specific settings

Setting	Type	Description
zoneFillColor	string	The fill color of the zone in hex format.
zoneStrokeColor	string	The outline color of the zone in hex format.
useZoneEditor	boolean	Whether to use zone editor functionality or not.
useSelectedZone	boolean	Whether to use zone selection.
selectedZoneColor	string	The color of the selected zone. Default: #00FF00

PathFeatures

Path specific settings

Setting	Type	Description
color	string	The color of the path in hex format. Leave it empty for random colors.
directionIndicator	string	The string to use on the path to indicate direction (or display any text.)

HeatFeatures

The heatmap is displayed using leaflet.heat, the docs for the options can be found here

TagModel

Interface for tag data. Read more here

export interface TagModel {
    tagId: number;
    pos?: number[];
    type?: string;
    description?: string;
    velocity?: number[];
    updatedAt_msFromEpoch?: number;
    updatedAt?: string; // ISO8601_FRAC_FORMAT
    orient?: number;
 
    markerOptions?: GLMarkerOptions;
}

GLMarkerOptions

export interface GLMarkerOptions{
    color?: string; // color in hex format
    opacity?: number; // opacity value between 0-1
    popupPos?: number[]; // position of the popup relative to the icon's anchor position
    rotation?: number; // marker rotation in radian
    icon?: GLIconOptions; // icon of the marker
}

GLIconOptions

export interface GLIconOptions {
    url: string; // path to the icon img
    size: number[]; // size of the icon [width,height]
    anchorPos: number[]; //icon anchor position relative to the top-left corner of the image [x,y]
}

The anchorPos property is in the image's pixel coordinates and relative to the top-left corner of the image, where the top-left corner is [0,0] coordinates. Eg.: If our image is a size of [64,64] the anchorPos of [32,32] would represent the center of the image.

Values for the standard leaflet marker are:

size:[25,41]

anchorPos:[12,41]

where [12,41] represents the tip of the marker

ZoneModel

Interface for zone data. Read more here

export interface ZoneModel {
    zoneName?: string;
    upperBounds: number[];
    lowerBounds: number[];
    zoneId: number;
  }
 

AnchorModel

Interface for anchor data. Read more here

export interface AnchorModel {
    anchorId: number;
    pos: number[];
}
 

SpaghettiData

Interface representing path data of a tag

export interface SpaghettiData {
    tagId: number;
    data: Array<{
        pos: number[],
        time: number
    }>;
}