Skip to main content
Version: 1.0.x

Utilities

Importing​

Utility functions and constants are exported as namespaces next to the default createSkyPathSDK export:

import { CoreUtils, GeoUtils, Observations } from "@skypath-io/web-sdk";

const debouncedUpdate = CoreUtils.debounce({ fn: updateLayer, delay: 300 });
const polygon = GeoUtils.getMapPolygon({ map });
const { severity } = Observations.availableConfigInputs;

All functions take a single options object.

Utility Functions​

Core​

Available as CoreUtils.<name>.

debounce​

The debounce function ensures that the given function fn is only called once within the specified delay period, even if it is triggered multiple times. This is useful for scenarios where you want to limit the rate at which a function can be executed, such as handling user input or resize events.

Parameters​

{ fn, delay }

  • fn: Function
    The function to debounce. This is the function that will be executed after the delay period has elapsed since the last time the debounced function was called.

  • delay: number
    The delay in milliseconds. This specifies how long to wait after the last invocation before executing the function.

Returns​
  • Function
    The debounced function. This returned function can be called multiple times, but it will only execute the original function fn after the specified delay has passed since the last call.

throttle​

The throttle function ensures that the given function fn is only called at most once within the specified delay period, even if it is triggered multiple times. This is useful for scenarios where you want to limit the rate at which a function can be executed, such as handling window resize or scroll events.

Parameters​

{ fn, delay }

  • fn: Function
    The function to throttle. This is the function that will be executed at most once within the specified delay period.

  • delay: number
    The delay in milliseconds. This specifies the minimum time interval between consecutive calls to the function fn.

Returns​
  • Function
    The throttled function. This returned function can be called multiple times, but it will only execute the original function fn at most once every delay milliseconds.

mergeByProperty​

The mergeByProperty function merges two arrays of objects based on a specified property. It updates objects in the target array with matching objects from the source array by the specified property and adds non-matching objects from the source array to the target array.

Parameters​

{ target, source, propName }

  • target: object[]
    The target array of objects. This array will be merged with objects from the source array based on the specified property.

  • source: object[]
    The source array of objects. Objects from this array will be used to update or add to the target array based on the specified property.

  • propName: string
    The property name to merge by. This specifies which property of the objects to use for matching and merging.

Returns​
  • object[]
    The merged array of objects. This array contains all objects from the target array updated with matching objects from the source array and any additional non-matching objects from the source array.

Geographic​

Available as GeoUtils.<name>.

getHexagonsFeatureCollection​

The getHexagonsFeatureCollection function generates a GeoJSON FeatureCollection from an array of H3 hexagon IDs. It adjusts coordinates to account for antimeridian crossing and ensures valid longitude and latitude ranges, without mutating the original data.

Parameters​

  • hexagons: Array<{hexId: string}>
    An array of objects, each containing a hexId representing an H3 hexagon. The default value is an empty array if no input is provided.

  • scale: number (optional)
    Scale factor for each hexagon polygon. The default value is 1.

Returns​
  • Object
    A GeoJSON FeatureCollection representing the hexagons. If the input array is empty or not provided, the function returns undefined.

getHexIdsByMapBoundsAndResolution​

The getHexIdsByMapBoundsAndResolution function calculates the H3 hexagon IDs that intersect with the given map bounds at a specified resolution. This function is useful for identifying the hexagon cells that fall within a specific geographic area defined by the map bounds.

Parameters​

{ mapBounds, resolution }

  • mapBounds: Array<number>
    The bounding box of the map. This is an object representing the geographic area of interest.

  • resolution: number
    The H3 resolution to use. This specifies the resolution level of the H3 hexagons. The default value is 0.

Returns​
  • Array<string>
    An array of H3 hexagon IDs that intersect with the given map bounds.

getHexIdsFromMapboxMap​

The getHexIdsFromMapboxMap function retrieves the H3 hexagon IDs that intersect with the current viewport of a Mapbox map instance at a specified resolution. This function is useful for obtaining hexagon IDs that cover the visible area of a Mapbox map.

Parameters​

{ map, resolution }

  • map: object
    The Mapbox map instance. This is the Mapbox GL JS map object from which the viewport bounds will be retrieved.

  • resolution: number (optional)
    The H3 resolution to use. This specifies the resolution level of the H3 hexagons. If not provided, a default resolution will be used.

Returns​
  • Array<string>
    An array of H3 hexagon IDs that intersect with the current viewport of the Mapbox map. If the map instance is not provided, the function returns undefined.

getMapPolygon​

The getMapPolygon function retrieves the current viewport bounds of a Mapbox map instance and returns them as a polygon of [longitude, latitude] points. This polygon represents the geographic area currently visible in the map viewport.

Parameters​

{ map }

  • map: object
    The Mapbox map instance. This is the Mapbox GL JS map object from which the viewport bounds will be retrieved.
Returns​
  • Array<Array<number>>
    A Polygon: an array of [longitude, latitude] points. This polygon outlines the current viewport bounds of the Mapbox map.

Aircraft category​

mapAircraftIcaoToAircraftType​

A method of the initialized SDK object, not of CoreUtils. It converts an aircraft ICAO code to an aircraft type, using the mapping the SDK loads from the server during initialization.

const sdk = await createSkyPathSDK({ /* ... */ });

const aircraftType = sdk.mapAircraftIcaoToAircraftType({ icao: "A320" });
Parameters​

{ icao }

  • icao: string
    The aircraft ICAO code to map to an aircraft type.
Returns​
  • string
    The aircraft type corresponding to the given ICAO code.

Constants​

The allowed values for flow configuration are available as Observations.availableConfigInputs:

import { Observations } from "@skypath-io/web-sdk";

const { aircraftCategory, hours, severity, maxAltitude, minAltitude } =
  Observations.availableConfigInputs;

Aircraft categories​

Observations.availableConfigInputs.aircraftCategory

{
  C10: "C10",
  C20: "C20",
  C30: "C30",
  C40: "C40",
  C50: "C50",
  C60: "C60",
  C70: "C70",
  C80: "C80",
  C90: "C90",
  C100: "C100",
  C110: "C110",
}

History hours​

Observations.availableConfigInputs.hours

{
  halfAnHour: "0.5",
  oneHour: "1",
  twoHours: "2",
  threeHours: "3",
  fourHours: "4",
}

The values are strings. historyHours in the Observations flow expects a number, so convert it: Number(hours.twoHours).

Severity​

Observations.availableConfigInputs.severity

{
  smooth: 0,
  light: 1,
  lightModerate: 2,
  moderate: 3,
  moderateSevere: 4,
}

Altitude range​

Observations.availableConfigInputs.maxAltitude and Observations.availableConfigInputs.minAltitude

maxAltitude = 52;
minAltitude = 0;