Observations flow

Overview

Observations Flow orchestrates the retrieval and management of historical and live data of observations. This page provides a detailed understanding of the Observations Flow's architecture and its role in facilitating real-time data updates.

Startup and Initialization

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

To crate Observations Flow call createObservationsFlow factory method from sdk object.

See example:

// Initialize SDK
const sdk = await createSkyPathSDK({
  // Your auth parameters here
});
// Create Observations Flow
const observationsFlow = sdk.createObservationsFlow()

The createObservationsFlow() method doesn't take any arguments, all configuration for the flow is provided with updateConfig() method.

Data Retrieval Process

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

• Data fetching: The data for the whole world map is being fetch based on the viewport rectangle and settings set. It handles concurrent loading and ensures that new data is fetching only for new areas;
• Data Merging: New data is merged with already loaded areas of world map, appending it to the stored values;
• Data enrichment: Once new data is available on the back-end side, the old data is being enriched with the fresh data;

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 areas and settings;
• 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;

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

observationsFlow.updateConfig(config)

The updateConfig(config: Config) method takes the following arguments where polygon is the map viewport rectangle and settings are the configuration for the flow:

Property	Description	Type	Default
polygon	Map viewport boundary box rectangle or a route corridor polygon	Polygon	null
aircraftCategory	Aircraft category	AircraftCategory	"C60"
hours	Data history time	Hours	"2"
severity	Severity level of observations	Severity	[0, 1, 2, 3, 4]
altitudeFrom	Altitude from in thousands of feet	number	5
altitudeTo	Altitude to in thousands of feet	number	52

updateConfig method arguments

type Config = {
  polygon: Polygon,
  aircraftCategory: AircraftCategory,
  hours: Hours,
  severity: Severity,
  altitudeFrom: number, // from 5-52
  altitudeTo: number, // from 5-52
}

type Polygon = [
  [lat: number, lng: number],
  [lat: number, lng: number],
  [lat: number, lng: number],
  [lat: number, lng: number],
  [lat: number, lng: number], // last item need's to be same as first item
]

// Observations.availableConfigInputs.aircraftCategory
type AircraftCategory = "C10" | "C20" | "C30" | "C40" | "C50" | "C60" | "C70" | "C80" | "C90" | "C100" | "C110"

// Observations.availableConfigInputs.hours
type Hours = "0.5" | "1" | "2" | "3" | "4"

// Observations.availableConfigInputs.severity
type Severity = [0, 1, 2, 3, 4] // 0-4 | From smooth to moderate-severe

all props have default values except for polygon which is mandatory, e.g. colorado state:

const polygon = [
  [-109.059391, 40.9967431],
  [-109.0374184, 36.9677238],
  [-102.0061684, 37.0203723],
  [-102.0720863, 41.0133248],
  [-109.059391, 40.9967431],
]

Supported altitude ranges are from 5000(5) to 52000(52) feet.

Config fields altitudeFrom and altitudeTo take values in thousands of feet.

Example of updateConfig method call:

const severity = Observations.availableConfigInputs.severity

observationsFlow.updateConfig({
  polygon: GeoUtils.getMapPolygon(map), // map = mapbox ref
  aircraftCategory: Observations.availableConfigInputs.aircraftCategory.C10,
  hours: Observations.availableConfigInputs.hours.oneHour,
  severity: [severity.smooth, severity.light, severity.lightModerate],
  altitudeFrom: 10,
  altitudeTo: 20,
})

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((data: Data) => {}) method:

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

Data received in the callback is an object with the following structure:

Data object structure

type Report = {
  sp_alt: number
  ts: number
  sev: number
  tick: number
  edr: number
}

type Data = Array<{
  hexId: string
  sev: number
  reports: Array<Report>
}>

Examples

Basic usage

import createSkyPathSDK, { GeoUtils, Observations } from "@yamasee/skypath-sdk-web";

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

// Create Observations Flow
const observationsFlow = sdk.createObservationsFlow()

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

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

const severity = Observations.availableConfigInputs.severity

// Later in the code update the configuration
observationsFlow.updateConfig({
  polygon: GeoUtils.getMapPolygon(map), // map = mapbox ref
  aircraftCategory: Observations.availableConfigInputs.aircraftCategory.C10,
  hours: Observations.availableConfigInputs.hours.oneHour,
  severity: [severity.smooth, severity.light, severity.lightModerate],
  altitudeFrom: 10,
  altitudeTo: 20,
})

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

Advanced usage

For advanced examples check the React Demo Application.