@fscharter/flowmap-data 8.0.2-fsc.1

package/src/getViewStateForLocations.ts

@@ -0,0 +1,86 @@
+/*
+ * Copyright (c) Flowmap.gl contributors
+ * Copyright (c) 2018-2020 Teralytics
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {geoBounds} from 'd3-geo';
+import {fitBounds} from '@math.gl/web-mercator';
+import type {
+  FeatureCollection,
+  GeometryCollection,
+  GeometryObject,
+} from 'geojson';
+import type {ViewState} from './types';
+
+export type LocationProperties = any;
+
+export type GetViewStateOptions = {
+  pad?: number; // size ratio
+  padding?: {top: number; bottom: number; left: number; right: number};
+  tileSize?: number;
+  // minZoom?: number;  // not supported by fitBounds
+  maxZoom?: number;
+};
+
+export function getViewStateForFeatures(
+  featureCollection:
+    | FeatureCollection<GeometryObject, LocationProperties>
+    | GeometryCollection,
+  size: [number, number],
+  opts?: GetViewStateOptions,
+): ViewState & {width: number; height: number} {
+  const {pad = 0.05, maxZoom = 100} = opts || {};
+  const bounds = geoBounds(featureCollection as any);
+  const [[x1, y1], [x2, y2]] = bounds;
+  const paddedBounds: [[number, number], [number, number]] = pad
+    ? [
+        [x1 - pad * (x2 - x1), y1 - pad * (y2 - y1)],
+        [x2 + pad * (x2 - x1), y2 + pad * (y2 - y1)],
+      ]
+    : bounds;
+  const [width, height] = size;
+  return {
+    ...fitBounds({
+      width,
+      height,
+      bounds: paddedBounds,
+      padding: opts?.padding,
+      // minZoom,
+      maxZoom,
+    }),
+    width,
+    height,
+    bearing: 0,
+    pitch: 0,
+  };
+}
+
+export function getViewStateForLocations<L>(
+  locations: Iterable<L>,
+  getLocationCoords: (location: L) => [number, number],
+  size: [number, number],
+  opts?: GetViewStateOptions,
+): ViewState & {width: number; height: number} {
+  const asGeometry = (location: L) => ({
+    type: 'Point',
+    coordinates: getLocationCoords(location),
+  });
+  let geometries;
+  if (Array.isArray(locations)) {
+    geometries = locations.map(asGeometry);
+  } else {
+    geometries = [];
+    for (const location of locations) {
+      geometries.push(asGeometry(location));
+    }
+  }
+  return getViewStateForFeatures(
+    {
+      type: 'GeometryCollection',
+      geometries,
+    } as any,
+    size,
+    opts,
+  );
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/*
+ * Copyright (c) Flowmap.gl contributors
+ * Copyright (c) 2018-2020 Teralytics
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from './types';
+export * from './colors';
+export * from './FlowmapState';
+export * from './FlowmapSelectors';
+export * from './selector-functions';
+export * from './time';
+export * from './getViewStateForLocations';
+export * from './provider/FlowmapDataProvider';
+export * from './cluster/cluster';
+export * from './cluster/ClusterIndex';
+export {default as FlowmapAggregateAccessors} from './FlowmapAggregateAccessors';
+export type {default as FlowmapDataProvider} from './provider/FlowmapDataProvider';
+export {default as LocalFlowmapDataProvider} from './provider/LocalFlowmapDataProvider';

package/src/provider/FlowmapDataProvider.ts

@@ -0,0 +1,81 @@
+/*
+ * Copyright (c) Flowmap.gl contributors
+ * Copyright (c) 2018-2020 Teralytics
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {AggregateFlow, Cluster, LocationAccessors, LocationTotals} from '..';
+import {FlowmapState} from '../FlowmapState';
+import {
+  ClusterNode,
+  FlowmapData,
+  FlowmapDataAccessors,
+  LayersData,
+  ViewportProps,
+} from '../types';
+
+export default interface FlowmapDataProvider<L, F> {
+  setAccessors(accessors: FlowmapDataAccessors<L, F>): void;
+
+  setFlowmapState(flowmapState: FlowmapState): Promise<void>;
+
+  // clearData(): void;
+
+  getViewportForLocations(
+    dims: [number, number],
+  ): Promise<ViewportProps | undefined>;
+
+  // getFlowTotals(): Promise<FlowTotals>;
+
+  getFlowByIndex(index: number): Promise<F | AggregateFlow | undefined>;
+
+  getLocationById(id: string | number): Promise<L | Cluster | undefined>;
+
+  getLocationByIndex(idx: number): Promise<L | ClusterNode | undefined>;
+
+  getTotalsForLocation(
+    id: string | number,
+  ): Promise<LocationTotals | undefined>;
+
+  // getLocationsInBbox(
+  //   bbox: [number, number, number, number],
+  // ): Promise<Array<FlowLocation | ClusterNode> | undefined>;
+
+  // getLocationsForSearchBox(): Promise<(FlowLocation | ClusterNode)[] | undefined>;
+
+  getLayersData(): Promise<LayersData | undefined>;
+
+  /**
+   * This is to give the data provider control over when/how often layersData
+   * is updated which leads to the flowmap being redrawn.
+   */
+  updateLayersData(
+    setLayersData: (layersData: LayersData | undefined) => void,
+    changeFlags: Record<string, boolean>,
+  ): Promise<void>;
+}
+
+export function isFlowmapData<L, F>(
+  data: Record<string, any>,
+): data is FlowmapData<L, F> {
+  return (
+    data && data.locations && data.flows
+    // TODO: test that they are iterable
+    // Array.isArray(data.locations) &&
+    // Array.isArray(data.flows)
+  );
+}
+
+export function isFlowmapDataProvider<L, F>(
+  dataProvider: Record<string, any>,
+): dataProvider is FlowmapDataProvider<L, F> {
+  return (
+    dataProvider &&
+    typeof dataProvider.setFlowmapState === 'function' &&
+    typeof dataProvider.getViewportForLocations === 'function' &&
+    typeof dataProvider.getFlowByIndex === 'function' &&
+    typeof dataProvider.getLocationById === 'function' &&
+    typeof dataProvider.getLocationByIndex === 'function' &&
+    typeof dataProvider.getLayersData === 'function'
+  );
+}

package/src/provider/LocalFlowmapDataProvider.ts

@@ -0,0 +1,185 @@
+/*
+ * Copyright (c) Flowmap.gl contributors
+ * Copyright (c) 2018-2020 Teralytics
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type FlowmapDataProvider from './FlowmapDataProvider';
+import type {
+  Cluster,
+  ClusterNode,
+  FlowmapData,
+  FlowmapDataAccessors,
+  LayersData,
+  LocationTotals,
+  ViewportProps,
+  AggregateFlow,
+} from '../types';
+import {FlowmapState} from '../FlowmapState';
+import FlowmapSelectors from '../FlowmapSelectors';
+import {
+  GetViewStateOptions,
+  getViewStateForLocations,
+} from '../getViewStateForLocations';
+import {ClusterIndex} from '../cluster/ClusterIndex';
+
+export default class LocalFlowmapDataProvider<
+  L extends Record<string, any>,
+  F extends Record<string, any>,
+> implements FlowmapDataProvider<L, F>
+{
+  private selectors: FlowmapSelectors<L, F>;
+  private flowmapData: FlowmapData<L, F> | undefined;
+  private flowmapState: FlowmapState | undefined;
+
+  constructor(accessors: FlowmapDataAccessors<L, F>) {
+    // scope selectors to the concrete instance of FlowmapDataProvider
+    this.selectors = new FlowmapSelectors<L, F>(accessors);
+    this.flowmapData = undefined;
+    this.flowmapState = undefined;
+  }
+
+  setAccessors(accessors: FlowmapDataAccessors<L, F>) {
+    this.selectors.setAccessors(accessors);
+  }
+
+  setFlowmapData(flowmapData: FlowmapData<L, F>): void {
+    this.flowmapData = flowmapData;
+  }
+
+  getSelectors(): FlowmapSelectors<L, F> {
+    return this.selectors;
+  }
+
+  getFlowmapData(): FlowmapData<L, F> | undefined {
+    return this.flowmapData;
+  }
+
+  async setFlowmapState(flowmapState: FlowmapState): Promise<void> {
+    this.flowmapState = flowmapState;
+  }
+
+  getFlowmapState(): FlowmapState | undefined {
+    return this.flowmapState;
+  }
+
+  async getFlowByIndex(idx: number): Promise<F | AggregateFlow | undefined> {
+    if (!this.flowmapState || !this.flowmapData) {
+      return undefined;
+    }
+    const flows = this.selectors.getFlowsForFlowmapLayer(
+      this.flowmapState,
+      this.flowmapData,
+    );
+    return flows?.[idx];
+  }
+
+  // TODO: this is unreliable, should replace by unqiue ID
+  async getLocationByIndex(idx: number): Promise<L | ClusterNode | undefined> {
+    if (!this.flowmapState || !this.flowmapData) {
+      return undefined;
+    }
+    const locations = this.selectors.getLocationsForFlowmapLayer(
+      this.flowmapState,
+      this.flowmapData,
+    );
+    return locations?.[idx];
+  }
+
+  async getLayersData(): Promise<LayersData | undefined> {
+    if (!this.flowmapState || !this.flowmapData) {
+      return undefined;
+    }
+    return this.selectors.getLayersData(this.flowmapState, this.flowmapData);
+  }
+
+  async getLocationById(id: string | number): Promise<L | Cluster | undefined> {
+    if (!this.flowmapState || !this.flowmapData) {
+      return undefined;
+    }
+    const clusterIndex = this.selectors.getClusterIndex(
+      this.flowmapState,
+      this.flowmapData,
+    );
+    if (clusterIndex) {
+      const cluster = clusterIndex.getClusterById(id);
+      if (cluster) {
+        return cluster;
+      }
+    }
+    const locationsById = this.selectors.getLocationsById(
+      this.flowmapState,
+      this.flowmapData,
+    );
+    return locationsById?.get(id);
+  }
+
+  async getTotalsForLocation(
+    id: string | number,
+  ): Promise<LocationTotals | undefined> {
+    if (!this.flowmapState || !this.flowmapData) {
+      return undefined;
+    }
+    return this.selectors
+      .getLocationTotals(this.flowmapState, this.flowmapData)
+      ?.get(id);
+  }
+
+  async getViewportForLocations(
+    dims: [number, number],
+    opts?: GetViewStateOptions,
+  ): Promise<ViewportProps | undefined> {
+    if (!this.flowmapData?.locations) {
+      return undefined;
+    }
+    // @ts-ignore
+    return getViewStateForLocations(
+      this.flowmapData.locations,
+      (loc) => [
+        this.selectors.accessors.getLocationLon(loc),
+        this.selectors.accessors.getLocationLat(loc),
+      ],
+      dims,
+      opts,
+    );
+  }
+
+  async updateLayersData(
+    setLayersData: (layersData: LayersData | undefined) => void,
+  ) {
+    setLayersData(await this.getLayersData());
+  }
+
+  getClusterZoom(): number | undefined {
+    return this.flowmapState && this.flowmapData
+      ? this.selectors.getClusterZoom(this.flowmapState, this.flowmapData)
+      : undefined;
+  }
+
+  getClusterIndex(): ClusterIndex<F> | undefined {
+    return this.flowmapState && this.flowmapData
+      ? this.selectors.getClusterIndex(this.flowmapState, this.flowmapData)
+      : undefined;
+  }
+
+  getLocationsById(): Map<string | number, L> | undefined {
+    return this.flowmapState && this.flowmapData
+      ? this.selectors.getLocationsById(this.flowmapState, this.flowmapData)
+      : undefined;
+  }
+
+  getLocationTotals(): Map<string | number, LocationTotals> | undefined {
+    return this.flowmapState && this.flowmapData
+      ? this.selectors.getLocationTotals(this.flowmapState, this.flowmapData)
+      : undefined;
+  }
+
+  getFlowsForFlowmapLayer(): Array<F | AggregateFlow> | undefined {
+    return this.flowmapState && this.flowmapData
+      ? this.selectors.getFlowsForFlowmapLayer(
+          this.flowmapState,
+          this.flowmapData,
+        )
+      : undefined;
+  }
+}

package/src/selector-functions.ts

@@ -0,0 +1,93 @@
+/*
+ * Copyright (c) Flowmap.gl contributors
+ * Copyright (c) 2018-2020 Teralytics
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {WebMercatorViewport} from '@math.gl/web-mercator';
+import {
+  ClusterLevel,
+  isCluster,
+  LocationAccessors,
+  ViewportProps,
+} from './types';
+import {scaleLinear} from 'd3-scale';
+import {ClusterIndex, LocationWeightGetter} from './cluster/ClusterIndex';
+import {descending} from 'd3-array';
+
+// TODO: use re-reselect
+
+export const getViewportBoundingBox = (
+  viewport: ViewportProps,
+  maxLocationCircleSize = 0,
+): [number, number, number, number] => {
+  const pad = maxLocationCircleSize;
+  const bounds = new WebMercatorViewport({
+    ...viewport,
+    width: viewport.width + pad * 2,
+    height: viewport.height + pad * 2,
+  }).getBounds();
+  return [bounds[0][0], bounds[0][1], bounds[1][0], bounds[1][1]];
+};
+
+export const getFlowThicknessScale = (
+  magnitudeExtent: [number, number] | undefined,
+) => {
+  if (!magnitudeExtent) return undefined;
+  return scaleLinear()
+    .range([0.025, 0.5])
+    .domain([
+      0,
+      // should support diff mode too
+      Math.max.apply(
+        null,
+        magnitudeExtent.map((x: number | undefined) => Math.abs(x || 0)),
+      ),
+    ]);
+};
+
+/**
+ * Adding meaningful cluster names.
+ * NOTE: this will mutate the nodes in clusterIndex
+ */
+export function addClusterNames<L, F>(
+  clusterIndex: ClusterIndex<F>,
+  clusterLevels: ClusterLevel[],
+  locationsById: Map<string | number, L>,
+  locationAccessors: LocationAccessors<L>,
+  getLocationWeight: LocationWeightGetter,
+): void {
+  const {getLocationId, getLocationName, getLocationClusterName} =
+    locationAccessors;
+  const getName = (id: string | number) => {
+    const loc = locationsById.get(id);
+    if (loc) {
+      return getLocationName ? getLocationName(loc) : getLocationId(loc) || id;
+    }
+    return `"${id}"`;
+  };
+  for (const level of clusterLevels) {
+    for (const node of level.nodes) {
+      // Here mutating the nodes (adding names)
+      if (isCluster(node)) {
+        const leaves = clusterIndex.expandCluster(node);
+
+        leaves.sort((a, b) =>
+          descending(getLocationWeight(a), getLocationWeight(b)),
+        );
+
+        if (getLocationClusterName) {
+          node.name = getLocationClusterName(leaves);
+        } else {
+          const topId = leaves[0];
+          const otherId = leaves.length === 2 ? leaves[1] : undefined;
+          node.name = `"${getName(topId)}" and ${
+            otherId ? `"${getName(otherId)}"` : `${leaves.length - 1} others`
+          }`;
+        }
+      } else {
+        (node as any).name = getName(node.id);
+      }
+    }
+  }
+}

package/src/time.ts

@@ -0,0 +1,166 @@
+/*
+ * Copyright (c) Flowmap.gl contributors
+ * Copyright (c) 2018-2020 Teralytics
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {timeFormat, timeParse} from 'd3-time-format';
+import {
+  timeDay,
+  timeHour,
+  TimeInterval,
+  timeMinute,
+  timeMonth,
+  timeSecond,
+  timeWeek,
+  timeYear,
+} from 'd3-time';
+
+const dateParsers = [
+  timeParse('%Y-%m-%d'),
+  timeParse('%Y-%m-%d %H:%M'),
+  timeParse('%Y-%m-%d %H:%M:%S'),
+  timeParse('%Y'),
+  timeParse('%Y-%m'),
+];
+
+export function parseTime(input: string | Date | undefined): Date | undefined {
+  if (input != null) {
+    if (input instanceof Date) {
+      return input;
+    }
+    for (const parse of dateParsers) {
+      const date = parse(input);
+      if (date) {
+        return date;
+      }
+    }
+  }
+  return undefined;
+}
+
+export enum TimeGranularityKey {
+  SECOND = 'SECOND',
+  MINUTE = 'MINUTE',
+  HOUR = 'HOUR',
+  DAY = 'DAY',
+  MONTH = 'MONTH',
+  YEAR = 'YEAR',
+}
+
+export interface TimeGranularity {
+  key: TimeGranularityKey;
+  order: number;
+  interval: TimeInterval;
+  format: (date: Date) => string;
+  formatFull: (date: Date) => string;
+}
+
+// const preferredLocale = navigator.languages ? navigator.languages[0] : 'en';
+
+const formatMillisecond = timeFormat('.%L'),
+  formatSecond = timeFormat(':%S'),
+  formatMinute = timeFormat('%I:%M'),
+  // formatHour = (d: Date) => d.toLocaleString(preferredLocale, { hour: 'numeric' }),
+  formatHour = timeFormat('%I %p'),
+  formatDay = timeFormat('%a %d'),
+  formatWeek = timeFormat('%b %d'),
+  formatMonth = timeFormat('%b'),
+  formatYear = timeFormat('%Y');
+
+export function tickMultiFormat(date: Date) {
+  return (
+    timeSecond(date) < date
+      ? formatMillisecond
+      : timeMinute(date) < date
+      ? formatSecond
+      : timeHour(date) < date
+      ? formatMinute
+      : timeDay(date) < date
+      ? formatHour
+      : timeMonth(date) < date
+      ? timeWeek(date) < date
+        ? formatDay
+        : formatWeek
+      : timeYear(date) < date
+      ? formatMonth
+      : formatYear
+  )(date);
+}
+
+export const TIME_GRANULARITIES: TimeGranularity[] = [
+  {
+    order: 0,
+    key: TimeGranularityKey.SECOND,
+    interval: timeSecond,
+    format: formatSecond,
+    formatFull: timeFormat('%Y-%m-%d %H:%M:%S'),
+  },
+  {
+    order: 1,
+    key: TimeGranularityKey.MINUTE,
+    interval: timeMinute,
+    format: formatMinute,
+    formatFull: timeFormat('%Y-%m-%d %H:%M'),
+  },
+  {
+    order: 2,
+    key: TimeGranularityKey.HOUR,
+    interval: timeHour,
+    // format: (d: Date) => d.toLocaleString(preferredLocale, { hour: 'numeric', minute: '2-digit' }),
+    format: formatHour,
+    formatFull: timeFormat('%a %d %b %Y, %I %p'),
+  },
+  {
+    order: 3,
+    key: TimeGranularityKey.DAY,
+    interval: timeDay,
+    format: formatDay,
+    formatFull: timeFormat('%a %d %b %Y'),
+  },
+  {
+    order: 4,
+    key: TimeGranularityKey.MONTH,
+    interval: timeMonth,
+    format: formatMonth,
+    formatFull: timeFormat('%b %Y'),
+  },
+  {
+    order: 5,
+    key: TimeGranularityKey.YEAR,
+    interval: timeYear,
+    format: formatYear,
+    formatFull: timeFormat('%Y'),
+  },
+];
+
+export function getTimeGranularityByKey(key: TimeGranularityKey) {
+  return TIME_GRANULARITIES.find((s) => s.key === key);
+}
+
+export function getTimeGranularityByOrder(order: number) {
+  return TIME_GRANULARITIES.find((s) => s.order === order);
+}
+
+export function getTimeGranularityForDate(date: Date): TimeGranularity {
+  let prev = undefined;
+  for (const current of TIME_GRANULARITIES) {
+    const {interval} = current;
+    const floored = interval(date);
+    if (floored < date) {
+      if (!prev) return current;
+      return prev;
+    }
+    prev = current;
+  }
+  return TIME_GRANULARITIES[TIME_GRANULARITIES.length - 1];
+}
+
+export function areRangesEqual(
+  a: [Date, Date] | undefined,
+  b: [Date, Date] | undefined,
+): boolean {
+  if (!a && !b) return true;
+  if (!a || !b) return false;
+  return a[0] === b[0] && a[1] === b[1];
+}