Forecast

Overview

Forecast is turbulence prediction data issued by SkyPath. It is issued for up to 24 hours forecast. Forecast Flow orchestrates the retrieval and management of forecast predictions. This page provides a detailed understanding of the flow architecture and how to use it.

Startup and Initialization

Upon instantiation, Forecast Flow sets up initial configurations and prepares the system for data fetching based on provided map area polygon. It immediately subscribes to internal events to handle periodic updates and user-triggered fetches.

To create Forecast Flow call createForecastFlow factory method from sdk object.

See example:

// Initialize SDK
const sdk = await createSkyPathSDK(...);

// Create Forecast Flow (only if enabled for this user)
const forecastFlow = sdk.IS_FORECAST_ENABLED ? sdk.createForecastFlow() : null;

info

Check sdk.IS_FORECAST_ENABLED before creating the flow. See Feature flags for details.

Lifecycle Management

• Start: Allocates resources, setting up intervals and listeners for data updates;
• Update: Triggers an update of the data, fetching new data for relevant map area polygon;
• Stop: Temporarily stops all operations, keeps resources, and pauses updates / intervals;
• Terminate: Completely stops all operations, releases resources, and removes all listeners, effectively shutting down the flow;

Data Retrieval Process

Under the hood, forecast flow abstracts the complexity for communication with SkyPath platform API in efficient way handling necessary data transformations, mappings and access management:

• Data fetching: The whole world-wide set of H3 hexagons is being checked if data needs updating it fetches new data accordingly. It handles concurrency and ensures that data fetching for the same hexagon is not duplicated;
• Data Merging: New data is merged into the existing set of H3 hexagon, appending it to the stored values;
• Data invalidation: Once new data is generated on the back-end side, the old data is invalidated and erased with the fresh;

info

Data update process is triggered automatically by the flow, but can also be triggered manually by the user by calling updateConfig() method.

Automatic updates are triggered periodically every 5 minutes.

Once data update is triggered and successfully completed, the flow emits data update event, which can be listened to by the user to update the UI or perform any other necessary actions. This can be done by subscribing to the event using onData method that takes a callback function as an argument and returns ForecastData object for current and previous data:

forecastFlow.onData((data, previousData) => {
  // You may get data in different formats
  const rawReportsData = data.toRawObject();                   // Raw reports
  const hexagonsArray = data.toHexagonsArray();                // Hexagons array
  const geoJsonFeatureCollection = data.toFeatureCollection(); // GeoJSON Feature Collection

  // ...use the data to update the UI...
})

If an error occurs during the update process, the flow emits an error event, which can be listened to by the user to handle the error. This can be done by subscribing to the event using onError method that takes a callback function as an argument and returns an Error object:

forecastFlow.onError((error) => {
  // Handle the error
})

Tracking the processing status of the flow can be done by subscribing to the onIsProcessingChange event. This event is emitted when the flow starts or stops processing data. The event returns a boolean value indicating the processing status:

forecastFlow.onIsProcessingChange((isProcessing) => {
  // Handle the processing status
})

Configuration

To update the flow with new settings, call updateConfig method:

forecastFlow.updateConfig(config)

The updateConfig(config: Config) method takes the following arguments where the polygon is a custom area on a world map and settings are the configuration for the flow:

Property	Description	Type	Default
polygon	Map viewport rectangle or a route corridor polygon	Polygon	null
forecast	forecast in hours	Forecast	0
maxAltitude	Maximum altitude to load data for	Altitude	52
minAltitude	Minimum altitude to load data for	Altitude	0
minSeverity	Minimum severity level to load data from	Severity	0

Once update is triggered and successfully completed, the flow emits data update event, which can be listened to by the user to update the UI or perform any other necessary actions. This can be done by subscribing to the event using onData method that takes a callback function as an argument and returns ForecastData data object:

forecastFlow.onData((data) => {
  // Use the data to update the UI
})

info

Use utility functions to facilitate the interaction with the data retrieved from the Forecast Flow and represent it on a map. For more information, please refer to the dedicated Forecast section in utilities documentation.

Examples

Basic usage

// Import the SDK
import createSkyPathSDK from "@skypath-io/web-sdk";

// Initialize SDK
const sdk = await createSkyPathSDK({
  // Your auth parameters here
});

// Create Forecast Flow
const forecastFlow = sdk.createForecastFlow()

// Subscribe to the data update event
forecastFlow.onData((data) => {
  // Use the data to update the UI
})

// Subscribe to the error event
forecastFlow.onError((error) => {
  // Handle the error
})

// Subscribe to the processing status event
forecastFlow.onIsProcessingChange((isProcessing) => {
  // Handle the processing status
})

// Start the flow when needed
forecastFlow.start()

// Later in the code update the polygon
forecastFlow.updateConfig({
  polygon: [
    [
      -143.6279359720371,
      54.91893678195086
    ],
    [
      -143.6279359720371,
      20.948470420620993
    ],
    [
      -56.37206402796207,
      20.948470420620993
    ],
    [
      -56.37206402796207,
      54.91893678195086
    ],
    [
      -143.6279359720371,
      54.91893678195086
    ]
  ],
  forecast: 0,
  maxAltitude: 35,
  minAltitude: 35,
  minSeverity: 2,
})

// Later in the code terminate the flow when jobs are done
forecastFlow.terminate()

Advanced usage

For advanced examples check the React Demo Application.