API Documentation

Map Initialization

initMap

Function

initMap(options) -> {Promise<Map>}

Returns

A Promise that delivers the Mapbox GL Map when initialized; this is the Mapbox web map object that will be used throughout the rest of the API.

Description

Initializes a Mapbox web map.

ParameterTypeRequiredDescription
optionsObjectYesA configuration object for the map
options.mapDivStringYesThe div ID of the web map container
options.mapboxglObjectYesThe Mapbox GL object
options.mapboxKeyStringYesThe Mapbox API key
options.kineticaUrlStringYesThe URL of the Kinetica REST API
options.wmsUrlStringYesThe URL of the Kinetica WMS endpoint
options.centerArray<Number>NoThe center point at which the map should initialize
options.zoomIntegerNoThe Mapbox zoom scale with which to initialize the map
options.usernameStringNoThe basic auth username for the Kinetica REST API
options.passwordStringNoThe basic auth password for the Kinetica REST API

Example

Map centered on Kinetica HQ:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
initMap(
    {
        mapDiv : "kineticaHQ",
        mapboxgl : window.mapboxgl,
        mapboxKey : 'abc123',
        kineticaUrl : "http://kinetica:9191",
        wmsUrl : "http://kinetica:9191/wms",
        center : [-122.398, 37.793],
        zoom : 15,
        username : "admin",
        password : "admin"
    }
)

WMS Layer

addWmsLayer

Function

addWmsLayer(map, options) -> {Promise<Object>}

Returns

A layer parameters object; useful for testing purposes.

Description

Adds a WMS raster-styled layer to the Mapbox map.

ParameterTypeRequiredDescription
mapObjectYesThe Mapbox web map object
optionsObjectYesA configuration object for the WMS layer
options.layerIdStringYesA unique identifier of the layer; cannot have the same ID as any other added layer
options.layerTypeStringYes

The styling used to render the WMS image; options:

  • raster
  • cb_raster
  • heatmap
  • contour
  • labels

Can optionally use options.renderingOptions.layers in lieu of this property

options.wmsUrlStringYesThe URL of the Kinetica WMS endpoint
options.tableNameStringYesThe name of the source table for the layer, containing geospatial data
options.xAttrStringYes (if x,y)The name of the column containing x values (often longitude)
options.yAttrStringYes (if x,y)The name of the column containing y values (often latitude)
options.geoAttrStringYes (if WKT)The name of the column containing WKT values
options.beforeStringNoThe layer before (underneath) which to add the new layer; if specified layer ID is not found, the new layer will be added on top of all existing layers
options.renderingOptionsObjectNo

Rendering options that dictate the styling of the WMS layer; see the WMS documentation for the corresponding layer type for examples and default values:

Example

Raster image of offices from an office table with lat & lon columns for coordinates:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
addWmsLayer(
    map,
    {
        wmsUrl : 'http://kinetica:9191/wms',
        layerId : 'offices',
        layerType : 'raster',
        tableName : 'office',
        xAttr : 'lon',
        yAttr : 'lat',
        renderingOptions :
        {
            POINTCOLORS: 'FF0000',
            POINTSHAPES: 'square',
            POINTSIZES: 4
        }
    }
)

updateWmsLayer

Function

updateWmsLayer(map, options) -> {Object}

Returns

An object containing the map, WMS URL, source name, layer name, query parameters, and the redraw function; useful for testing purposes

Description

Updates a WMS layer's parameters with the passed options. Useful for updating WMS output styling parameters based on UI interactions.

ParameterTypeRequiredDescription
mapObjectYesThe Mapbox web map object
optionsObjectYesA configuration object for the WMS layer
options.layerIdStringYesThe unique identifier of the layer to update
options.wmsUrlStringYesThe URL of the Kinetica WMS endpoint
options.renderingOptionsObjectNo

Rendering options that dictate the styling of the WMS layer; see the WMS documentation for the corresponding layer type for examples and default values:

Example

Update raster image of offices, turning each point into a green circle:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
updateWmsLayer(
    map,
    {
        layerId : 'offices',
        wmsUrl : 'http://kinetica:9191/wms',
        renderingOptions :
        {
            POINTCOLORS: '00FF00',
            POINTSHAPES: 'circle',
            POINTSIZES: 3
        }
    }
)

updateWmsLayerType

Function

updateWmsLayerType(map, layerId, layerType, debounceLimit) -> {Object}

Returns

An object containing the redraw function and the debounce limit; useful for testing purposes

Description

Changes an existing WMS layer's rendering type and sets all of its parameters to the default values. Useful for changing a layer's presentation without having to destroy the old layer and create a new one.

ParameterTypeRequiredDescription
mapObjectYesThe Mapbox web map object
layerIdStringYesThe unique identifier of the layer to update
layerTypeStringYesThe type to which the layer should be updated
debounceLimitNumberNoThe debounce limit to use as a delay between the end of panend/zoomend events; default is 2000ms

Example

Update layer of offices to a heatmap:

1
2
3
4
5
6
updateWmsLayerType(
    map,
    'offices',
    'heatmap',
    1000
)

removeWmsLayer

Function

removeWmsLayer(map, layerId) -> {Void}

Returns

Void

Description

Removes a WMS layer from the map, based on layer ID; this includes the layer source and event listeners

ParameterTypeRequiredDescription
mapObjectYesThe Mapbox web map object
layerIdStringYesThe unique identifier of the layer to remove

Example

Remove offices layer:

1
2
3
4
removeWmsLayer(
    map,
    'offices'
)

addCbLegend

Function

addCbLegend(map, legendTitle, location, cbConfig) -> {Void}

Returns

Void

Description

Adds a WMS raster styled layer to the Mapbox map

ParameterTypeRequiredDescription
mapObjectYesThe Mapbox web map object
legendTitleStringYesA title to add to the top of the legend
locationStringYesThe location of the screen to render; e.g., top-right
cbConfigObjectYesAn object containing the class-break configuration values
cbConfig.cbValsArray<String>YesAn array of class-break specifications to be shown next to the colored legend tokens
cbConfig.pointColorsArray<String>YesAn array of class-break colors to be rendered as tokens next to the class breaks

Example

Add a legend to a class break on offices by the number of employees at each; offices of up to 20 employees will be green, between 21 and 40 will be yellow, and 41 or more employees will be shaded red:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
addCbLegend(
    map,
    'Offices by Employees',
    'top-right',
    {
        cbVals :
        [
            '0-20',
            '20-40',
            '<other>'
        ],
        pointColors :
        [
            '00FF00',
            'FFFF00',
            'FF0000'
        ]
    }
)

setLayerOpacity

Function

setLayerOpacity(map, layerId, opacity) -> {Void}

Returns

Void

Description

A helper function to easily set a layer's opacity

ParameterTypeRequiredDescription
mapObjectYesThe Mapbox web map object
layerIdStringYesThe unique identifier of the layer to modify
opacityNumberYesThe opacity to assign the layer, between 0 and 1

Example

Set opacity of offices layer to 50%:

1
2
3
4
5
removeWmsLayer(
    map,
    'offices',
    .5
)

Cluster Layer

addClusterLayer

Function

addClusterLayer(map, options) -> {Promise}

Returns

Returns a promise that resolves with the map, cluster object, update function, and options used to generate the cluster. Useful for testing purposes.

Description

Adds a geohash cluster visualization layer to the Mapbox map

ParameterTypeRequiredDescription
mapObjectYesThe Mapbox web map object
optionsObjectYesA configuration object for the cluster layer
options.layerIdStringYesA unique identifier for the layer; cannot have the same ID as any other added layer
options.mapboxglObjectYesThe Mapbox GL object
options.kineticaUrlStringYesThe URL of the Kinetica REST API
options.tableNameStringYesThe name of the source table for the layer, containing geospatial data
options.xAttrStringYesThe name of the column containing x values (often longitude)
options.yAttrStringYesThe name of the column containing y values (often latitude)
options.geohashAttrStringYesThe name of the column containing geohashes
options.precisionIntegerYesThe geohash precision (number of beginning geohash characters) to use on the initial database groupby of geohashes; cannot exceed the length of any geohash; higher numbers will produce a more granular view at some performance cost
options.clusterRadiusIntegerNoThe visual radius, in pixels, on the map within which to generate clusters; does not impact database performance, only client-side rendering
options.clusterMaxZoomIntegerNoThe maximum zoom with which clusters can be generated; defaults to 14
options.useBboxBooleanNoWhether to generate clusters only within the current bounding box or not to restrict the generation area; defaults to No; when Yes, more granular, high-density clusters tend to be generated
options.minSizeIntegerNoThe minimum visual size of each cluster dot; defaults to 1 pixel
options.maxSizeIntegerNoThe maximum visual size of each cluster dot; defaults to 20 pixels
options.minColorStringNoThe color of the smallest clusters; defaults to red; a gradient will form between this color and the one in maxColor
options.maxColorStringNoThe color of the largest clusters; defaults to green; a gradient will form between this color and the one specified in minColor
options.dbAggregationsArray<String>No

An array of custom aggregations to perform at the database level at the specified precision of the geohashes; these will be included as properties for the custom client-side aggregations

Note

COUNT(*) is calculated by default and should not be specified as an aggregate

options.clientAggregationsArray<Object>No

An array of custom map/reduce aggregations to perform on the client side, for each cluster displayed at the current zoom level; aggregation configurations should be objects with the following properties:

  • key: name of column (or column alias defined in dbAggregations expression) on which to apply the aggregation; this name must be used throughout the map/reduce config
  • initial: initial value of aggregation variable
  • map: optional mapping function on (key, properties), where each value of the column (or column alias defined in dbAggregations expressions) can be accessed within the function at properties.<column>
  • reduce: reducing function on (accumulated, properties) where each mapped value of the column (or column alias defined in dbAggregations expressions) can be accessed within the function at properties.<column> and accumulated into the value at accumulated.<column>

Tip

See below for an example setup using both database & client-side aggregations

Note

A WKT column is not currently allowed when creating clusters--x/y columns must be used.

Example

Clustering of employees from an office_employee table with lat & lon columns for coordinates, each cluster calculating the total of the salaries earned by all employees located at offices within the cluster:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
addClusterLayer(
    map,
    {
        layerId : 'office_employees',
        mapboxgl: window.mapboxgl,
        kineticaUrl : 'http://kinetica:9191',
        tableName : 'office_employee',
        xAttr : 'lon',
        yAttr : 'lat',
        geohashAttr : 'geo_hash',
        precision : 4,
        clusterRadius : 40,
        clusterMaxZoom : 14,
        useBbox : true,
        minSize : 1,
        maxSize : 20,
        minColor : '#FF0000',
        maxColor : '#00FF00',
        dbAggregations :
        [
            'SUM(salary) employeeSalaries'
        ],
        clientAggregations :
        [
            {
                key: 'employeeSalaries',
                initial: 0,
                map: (key, properties) => {
                    return Number(properties.employeeSalaries);
                },
                reduce: (accumulated, properties) => {
                    return accumulated.employeeSalaries + properties.employeeSalaries;
                }
            }
        ]
    }
)

Events

The following events can be acted upon using the Kinetica Kickbox.js Event API

Event NameDescription
beforeWmsLayerAddedFires just before a WMS layer is added to the map
afterWmsLayerAddedFires just after a WMS layer has been added to the map
beforeClusterLayerAddedFires just before a cluster layer is added to the map
afterClusterLayerAddedFires just after a cluster layer is added to the map
beforeWmsLayerRemovedFires just before a WMS layer is removed from the map
afterWmsLayerRemovedFires just after a WMS layer is removed from the map
beforeWmsSourceRemovedFires just before a WMS layer is removed from the map
afterWmsSourceRemovedFires just after a WMS layer is removed from the map
beforeZoomToBoundsFires just before zooming to bounds
afterZoomToBoundsFires just after zooming to bounds
beforeWmsLayerUpdatedFires just before a WMS layer is updated
afterWmsLayerUpdatedFires just before a WMS layer is updated

on

Function

on(name, cb) -> {Void}

Returns

Void

Description

Registers a callback with the given event name; an ID can be specified to allow a subsequent unregister call by ID instead of function signature, which requires storing function references globally

ParameterTypeRequiredDescription
nameStringYesThe event name with which to register the listener callback
cbFunctionYesThe callback to invoke when the event is fired
cb.kbFnIdStringNoThe callback ID to use when unregistering the handler using offById

Example

Log to console immediately after a WMS layer is added, and assign a callback ID of myCallbackId for subsequent use in turning this event handler off using offById:

1
2
3
4
5
6
7
    var afterWmsLayerUpdatedCb = (e) => { console.log('[' + e.eventName + ']  WMS layer has been updated'); }
    afterWmsLayerUpdatedCb.kbFnId = 'myCallbackId';

    on(
        'afterWmsLayerUpdated',
        afterWmsLayerUpdatedCb
    )

off

Function

off(name, cb) -> {Void}

Returns

Void

Description

Unregisters a callback with the given event name and callback function

ParameterTypeRequiredDescription
nameStringYesThe event name from which to unregister the listener callback
cbFunctionYesThe callback function to unregister

Example

Stop calling afterWmsLayerUpdateCb when afterWmsLayerUpdated events occur:

1
2
3
4
off(
    'afterWmsLayerUpdated',
    afterWmsLayerUpdateCb
)

Note

As noted in on, the callback function reference passed in here must be the same reference passed to the on function

offById

Function

offById(name, cbId) -> {Void}

Returns

Void

Description

Unregisters a callback that has a kbFnId property equal to the specified cbId

ParameterTypeRequiredDescription
nameStringYesThe event name from which to unregister the listener callback
cbIdStringYesThe ID of the callback function to unregister

Example

Stop calling the callback function with an ID of myCallbackId when afterWmsLayerUpdated events occur:

1
2
3
4
offById(
    'afterWmsLayerUpdated',
    'myCallbackId'
)

Note

This ID must match the one assigned to the callback function before calling the on function

trigger

Function

trigger(name) -> {Void}

Returns

Void

Description

Triggers a Kinetica Kickbox.js event for all listeners of the event with the specified name

ParameterTypeRequiredDescription
nameStringYesThe name of the event to trigger

Example

Fire the afterWmsLayerUpdated event, triggering all listeners for that event to invoke their respective callback functions:

1
trigger('afterWmsLayerUpdated')

Identify Modes

enableIdentifyByRadiusMode

Function

enableIdentifyByRadiusMode(map, options) -> {Void}

Returns

Void

Description

Enables the identify-by-radius mode on a specified layer, after first disabling any currently active identify mode

ParameterTypeRequiredDescription
mapObjectYesThe Mapbox web map object
optionsObjectYesAn object containing the identify-by-radius mode configuration values
options.layerIdStringYesThe unique identifier of the layer on which to enable identify-by-radius mode
options.mapboxglObjectYesThe Mapbox GL object
options.MapboxDrawObjectYesThe Mapbox GL Draw object
options.kineticaUrlStringYesThe URL of the Kinetica REST API
options.tableNameStringYesThe name of the source table for the layer, containing geospatial data
options.xAttrStringYes (if x,y)The name of the column containing x values (often longitude)
options.yAttrStringYes (if x,y)The name of the column containing y values (often latitude)
options.geoAttrStringYes (if WKT)The name of the column containing WKT values
options.transformationsArray<Object>No

An array of objects that contain two properties:

  • condition - a function to determine whether a given record should be transformed
  • transformation - a function that performs a transformation on a given record

Note

The Mapbox GL and Mapbox GL Draw objects require a separate install from Kinetica Kickbox.js

Example

Enable geospatial filtering of data via click-and-drag of a circle on the offices map layer, prefixing hex values in the color_code column with a #:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
enableIdentifyByRadiusMode
(
    {
        layerId : 'offices',
        mapboxgl : window.mapboxgl,
        MapboxDraw : window.MapboxDraw,
        kineticaUrl : "http://kinetica:9191",
        tableName : 'office',
        xAttr : 'lon',
        yAttr : 'lat',
        transformations :
        [
            {
                condition: (columnName, columnType) => { return columnName === 'color_code'; },
                transformation: (record, columnName) =>
                {
                    record[columnName] = '#' + record[columnName];
                    return record;
                }
            }
        ]
    }
)

enableIdentifyByPointMode

Function

enableIdentifyByPointMode(map) -> {Void}

Returns

Void

Description

Enables the identify-by-point mode on a specified layer, after first disabling any currently active identify mode

ParameterTypeRequiredDescription
mapObjectYesThe Mapbox web map object
optionsObjectYesAn object containing the identify-by-point mode configuration values
options.layerIdStringYesThe unique identifier of the layer on which to enable identify-by-point mode
options.mapboxglObjectYesThe Mapbox GL object
options.MapboxDrawObjectYesThe Mapbox GL Draw object
options.kineticaUrlStringYesThe URL of the Kinetica REST API
options.tableNameStringYesThe name of the source table for the layer, containing geospatial data
options.xAttrStringYes (if x,y)The name of the column containing x values (often longitude)
options.yAttrStringYes (if x,y)The name of the column containing y values (often latitude)
options.geoAttrStringYes (if WKT)The name of the column containing WKT values
options.radiusInMetersNumberYesThe radius (in meters) around the clicked point to use as the search area
options.transformationsArray<Object>No

An array of objects that contain two properties:

  • condition - a function to determine whether a given record should be transformed
  • transformation - a function that performs a transformation on a given record

Note

The Mapbox GL and Mapbox GL Draw objects require a separate install from Kinetica Kickbox.js

Example

Enable geospatial filtering of data via click of a point on the offices map layer and applying a 200m fixed radius to determine the filtered area, prefixing hex values in the color_code column with a #:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
enableIdentifyByPointMode
(
    {
        layerId : 'offices',
        mapboxgl : window.mapboxgl,
        MapboxDraw : window.MapboxDraw,
        kineticaUrl : "http://kinetica:9191",
        tableName : 'office',
        xAttr : 'lon',
        yAttr : 'lat',
        radiusInMeters : 200,
        transformations :
        [
            {
                condition: (columnName, columnType) => { return columnName === 'color_code'; },
                transformation: (record, columnName) =>
                {
                    record[columnName] = '#' + record[columnName];
                    return record;
                }
            }
        ]
    }
)

disableIdentifyMode

Function

disableIdentifyMode(map) -> {Void}

Returns

Void

Description

Disables the currently active identify-by-radius or identify-by-point mode and unregisters all callbacks driving the user interaction with this mode

ParameterTypeRequiredDescription
mapObjectYesThe Mapbox web map object

Example

Disable any active identify mode:

1
disableIdentifyMode(map)