@tsingroc/tsingroc-components 3.14.0 → 3.14.1

package/src/deckgl/WeatherData.ts

@@ -0,0 +1,157 @@
+import type * as wl from "weatherlayers-gl";
+import type { BitmapBoundingBox } from "@deck.gl/layers";
+
+export interface WeatherData {
+  dims: {
+    longitude: number;
+    latitude: number;
+    time: number;
+  };
+  coords: {
+    /** deg */
+    longitude: number[];
+    /** deg */
+    latitude: number[];
+    /** Unix 时间戳 */
+    time: number[];
+  };
+  data_vars: {
+    /** ℃ */
+    temperature_2m?: number[][][];
+    /** hPa */
+    surface_pressure?: number[][][];
+    /** % */
+    cloud_cover?: number[][][];
+    /** ℃ */
+    dew_point_2m?: number[][][];
+    /** % */
+    relative_humidity_2m?: number[][][];
+    /** 风速沿纬线向**东**吹（西风）的分量，m/s */
+    wind_component_u_10m?: number[][][];
+    /** 风速沿经线向**北**吹（南风）的分量，m/s */
+    wind_component_v_10m?: number[][][];
+    /** m/s */
+    wind_speed_10m?: number[][][];
+    /** deg，`0` 表示**北风**（往南吹），随着角度增大，风向**顺时针**旋转。*/
+    wind_direction_10m?: number[][][];
+    /** mm */
+    rain?: number[][][];
+  };
+}
+
+export const getBounds = (data: WeatherData): BitmapBoundingBox => {
+  const [lngMin, lngMax] = [
+    data.coords.longitude[0],
+    data.coords.longitude.at(-1)!,
+  ].sort();
+  const [latMin, latMax] = [
+    data.coords.latitude[0],
+    data.coords.latitude.at(-1)!,
+  ].sort();
+  return [lngMin, latMin, lngMax, latMax];
+};
+
+export function extractScalarData(
+  data: WeatherData,
+  variable: keyof WeatherData["data_vars"],
+) {
+  const result = Array.from({ length: data.dims.time }, () => ({
+    image: {
+      data: new Float32Array(data.dims.longitude * data.dims.latitude),
+      width: data.dims.longitude,
+      height: data.dims.latitude,
+    } satisfies wl.TextureData as wl.TextureData,
+    min: Infinity,
+    max: -Infinity,
+    mean: 0,
+  }));
+  let p = 0;
+  for (let i = 0; i < data.dims.longitude; i++) {
+    for (let j = 0; j < data.dims.latitude; j++) {
+      for (let t = 0; t < data.dims.time; t++) {
+        let value = data.data_vars[variable]![i][j][t];
+        if (value === -9999) value = NaN;
+        result[t].image.data[p] = value;
+        if (value > result[t].max) result[t].max = value;
+        if (value < result[t].min) result[t].min = value;
+      }
+      p++;
+    }
+  }
+  for (const item of result) {
+    item.mean =
+      (item.image.data as Float32Array).reduce((a, b) => a + b) /
+      item.image.data.length;
+  }
+  return result;
+}
+
+export function extractVectorData(
+  data: WeatherData,
+  variableU: keyof WeatherData["data_vars"],
+  variableV: keyof WeatherData["data_vars"],
+) {
+  const result = Array.from(
+    { length: data.dims.time },
+    () =>
+      ({
+        data: new Float32Array(data.dims.longitude * data.dims.latitude * 2),
+        width: data.dims.longitude,
+        height: data.dims.latitude,
+      }) satisfies wl.TextureData as wl.TextureData,
+  );
+  let p = 0;
+  for (let i = 0; i < data.dims.longitude; i++) {
+    for (let j = 0; j < data.dims.latitude; j++) {
+      for (let t = 0; t < data.dims.time; t++) {
+        let u = data.data_vars[variableU]![i][j][t];
+        let v = data.data_vars[variableV]![i][j][t];
+        if (u === -9999) u = NaN;
+        if (v === -9999) v = NaN;
+        result[t].data[p] = u;
+        result[t].data[p + 1] = v;
+      }
+      p += 2;
+    }
+  }
+  return result;
+}
+
+export function extractMagnitudeData(
+  data: WeatherData,
+  variableU: keyof WeatherData["data_vars"],
+  variableV: keyof WeatherData["data_vars"],
+) {
+  const result = Array.from({ length: data.dims.time }, () => ({
+    image: {
+      data: new Float32Array(data.dims.longitude * data.dims.latitude),
+      width: data.dims.longitude,
+      height: data.dims.latitude,
+    } satisfies wl.TextureData as wl.TextureData,
+    min: Infinity,
+    max: -Infinity,
+    mean: 0,
+  }));
+  let p = 0;
+  for (let i = 0; i < data.dims.longitude; i++) {
+    for (let j = 0; j < data.dims.latitude; j++) {
+      for (let t = 0; t < data.dims.time; t++) {
+        let u = data.data_vars[variableU]![i][j][t];
+        let v = data.data_vars[variableV]![i][j][t];
+        if (u === -9999) u = NaN;
+        if (v === -9999) v = NaN;
+        const value = Math.sqrt(u * u + v * v);
+        result[t].image.data[p] = value;
+        if (value > result[t].max) result[t].max = value;
+        if (value < result[t].min) result[t].min = value;
+      }
+      p++;
+    }
+  }
+  for (const item of result) {
+    item.mean =
+      (item.image.data as Float32Array).reduce((a, b) => a + b) /
+      item.image.data.length;
+  }
+  return result;
+}

package/src/deckgl/index.ts

@@ -0,0 +1,4 @@
+export {
+  default as TiandituLayer,
+  type TiandituLayerProps,
+} from "./TiandituLayer";

package/src/echarts/coordinateSystem.ts

@@ -0,0 +1,132 @@
+import type {
+  BarSeriesOption,
+  BoxplotSeriesOption,
+  FlowGLSeriesOption,
+  GridComponentOption,
+  LineSeriesOption,
+  XAXisComponentOption,
+  YAXisComponentOption,
+} from "echarts";
+import { useId } from "react";
+
+import type { EChartsComponent, EChartsSeries } from ".";
+
+export type GridPreset = (
+  grid: GridComponentOption,
+  xAxis: XAXisComponentOption,
+  yAxis: YAXisComponentOption,
+) => void;
+
+export interface GridOption {
+  /**
+   * 坐标网格的其它设置，参见 [ECharts 文档][1]。
+   *
+   * [1]: https://echarts.apache.org/zh/option.html#grid
+   */
+  option?: GridComponentOption;
+  /**
+   * X 轴的设置，参见 [ECharts 文档][1]。
+   *
+   * [1]: https://echarts.apache.org/zh/option.html#xAxis
+   */
+  xAxis?: XAXisComponentOption;
+  /**
+   * Y 轴的设置，参见 [ECharts 文档][1]。
+   *
+   * [1]: https://echarts.apache.org/zh/option.html#yAxis
+   */
+  yAxis?: YAXisComponentOption;
+  /**
+   * 预设列表。预设的优先级**高于**上述设置。
+   *
+   * 可用的预设：{@linkcode minimalGrid}
+   */
+  presets?: GridPreset[];
+  /** 要绘制在该坐标系上的系列。*/
+  series?: EChartsSeries<
+    | LineSeriesOption
+    | BarSeriesOption
+    | BoxplotSeriesOption
+    | FlowGLSeriesOption
+  >[];
+}
+
+/**
+ * 添加一个直角坐标系。X 轴和 Y 轴的数据类型默认值与 ECharts 原版一致。
+ *
+ * **注意**：该组件是一个 React hook，需要遵守正常使用 hook 的准则。
+ */
+export function useGrid(option: GridOption): EChartsComponent {
+  const grid: GridComponentOption = {
+    id: useId(),
+    left: 0,
+    right: 0,
+    top: 24,
+    bottom: 0,
+    containLabel: true,
+    ...option.option,
+  };
+  const gridId = grid.id as string;
+  const xAxis: XAXisComponentOption = {
+    id: gridId + "x",
+    gridId,
+    nameGap: 6,
+    ...option.xAxis,
+    nameTextStyle: { fontWeight: "bold", ...option.xAxis?.nameTextStyle },
+    axisTick: {
+      alignWithLabel: true,
+      ...option.xAxis?.axisTick,
+      // 此处需要强转，因为 alignWithLabel 仅当 boundaryGap = true 时有效，但无效也没有影响
+    } as XAXisComponentOption["axisTick"],
+  };
+  const xAxisId = xAxis.id as string;
+  const yAxis: YAXisComponentOption = {
+    id: gridId + "y",
+    type: option.yAxis?.type ?? "value",
+    gridId,
+    nameGap: 12,
+    ...option.yAxis,
+    nameTextStyle: {
+      align: "left",
+      fontWeight: "bold",
+      ...option.yAxis?.nameTextStyle,
+    },
+  };
+  const yAxisId = yAxis.id as string;
+  option.presets?.forEach((preset) => preset(grid, xAxis, yAxis));
+  return {
+    grid: [grid],
+    xAxis: [xAxis],
+    yAxis: [yAxis],
+    series: option.series
+      ?.flatMap((item) => item.series)
+      ?.map((series) => ({
+        ...series,
+        coordinateSystem: "cartesian2d",
+        xAxisId,
+        yAxisId,
+      })),
+  };
+}
+
+const MINIMAL_GRID: GridPreset = (grid, xAxis, yAxis) => {
+  grid.top = 0;
+  xAxis.show = false;
+  if (
+    (xAxis.type === undefined && (xAxis as { data: [] }).data !== undefined) ||
+    xAxis.type === "category"
+  ) {
+    (xAxis as { boundaryGap: boolean }).boundaryGap = false;
+  } else {
+    xAxis.min = "dataMin";
+    xAxis.max = "dataMax";
+  }
+  xAxis.axisLabel = { inside: true };
+  yAxis.show = false;
+  yAxis.axisLabel = { inside: true };
+};
+
+/** 使用该预设可以隐藏直角坐标系的坐标轴和网格线，只留下图像本身，并且使其填满整个容器。*/
+export function minimalGrid() {
+  return MINIMAL_GRID;
+}

package/src/echarts/gl.ts

@@ -0,0 +1,158 @@
+import type {
+  ComponentOption,
+  SeriesOnCartesianOptionMixin,
+  SeriesOnGeoOptionMixin,
+} from "echarts/types/src/util/types.js";
+import type { FlowGLSeriesOption as OrigFlowGLSeriesOption } from "echarts";
+import "echarts-gl";
+
+import type { EChartsSeries } from ".";
+
+// 由于官方没有提供类型定义，这里只能自行补充
+declare module "echarts/types/dist/echarts" {
+  interface RegisteredSeriesOption {
+    flowGL: FlowGLSeriesOption;
+  }
+  interface FlowGLSeriesOption
+    extends ComponentOption,
+      SeriesOnCartesianOptionMixin,
+      SeriesOnGeoOptionMixin {
+    type: "flowGL";
+    /**
+     * 粒子的密度，实际的粒子数量是设置数目的平方。粒子密度越大迹线效果越好，但是性能开销也会越大。
+     * 除了该属性，使用 `particleType` 也可以得到更加清晰连贯的迹线。
+     * @default 128
+     */
+    particleDensity?: number;
+    /**
+     * 粒子的类型，可以设置为点 `"point"` 或线 `"line"`。
+     * 线类型的粒子会用一条线连接上个运动的位置和当前运动的位置，这会让这个轨迹更加连贯。
+     * @default "point"
+     */
+    particleType?: "point" | "line";
+    /**
+     * 粒子的大小，如果 `particleType == "line"` 则代表线宽。
+     * @default 1
+     */
+    particleSize?: number;
+    /**
+     * 粒子的速度，默认为 1。注意在 `particleType` 为 `"point"` 的时候过大的速度会让整个轨迹变得断断续续。
+     * @default 1
+     */
+    particleSpeed?: number;
+    /**
+     * 粒子的轨迹长度，数值越大轨迹越长。
+     * @default 2
+     */
+    particleTrail?: number;
+    /**
+     * 画面的超采样比率，采用 4 的超采样可以有效的提高画面的清晰度，减少画面锯齿。
+     * 但是因为需要处理更多的像素数量，所以也对性能有更高的要求。
+     * @default 1
+     */
+    supersampling?: number;
+    /**
+     * 传入的网格数据的网格宽度数量。
+     * @default "auto"
+     */
+    gridWidth?: number | "auto";
+    /**
+     * 传入的网格数据的网格高度数量。
+     * @default "auto"
+     */
+    gridHeight?: number | "auto";
+    /**
+     * 每行数据包含四个值，分别表示位置 x、y，速度 sx、sy。
+     * 如果使用地理坐标系，则分别表示位置 lng、lat，速度 sLng、sLat。
+     */
+    data: [number, number, number, number][];
+    /**
+     * 向量场迹线的样式。
+     */
+    itemStyle?: FlowGLSeriesItemStyle;
+  }
+  interface FlowGLSeriesItemStyle {
+    /**
+     * 向量场迹线的颜色。
+     * @default "#fff"
+     */
+    color?: string;
+    /**
+     * 向量场迹线的透明度。
+     * @default 0.8
+     */
+    opacity?: number;
+  }
+}
+
+export interface FlowGLSeriesOption {
+  /** 系列名称，不可与其他系列重名。*/
+  name: string;
+  /**
+   * 每行数据包含四个值，分别表示位置 x、y，速度 sx、sy。
+   *
+   * 如果需要使用风场数据，可以直接调用 {@linkcode preprocessWindData} 来将数据处理成此处需要的格式。
+   */
+  data: [number, number, number, number][];
+  /**
+   * 其它需要添加到系列上的选项，参见 [ECharts 文档][1]。
+   *
+   * [1]: https://echarts.apache.org/zh/option-gl.html#series-flowGL
+   */
+  option?: Partial<OrigFlowGLSeriesOption>;
+}
+
+/**
+ * 在坐标系上绘制一个流场。
+ *
+ * 推荐使用以下坐标系配置：
+ *
+ * ```ts
+ * echarts.useGrid({
+ *   xAxis: { type: "value" },
+ *   yAxis: { min: "dataMin", max: "dataMax" },
+ *   presets: [echarts.minimalGrid()],
+ * })
+ * ```
+ */
+export function flowGLSeries(
+  option: FlowGLSeriesOption,
+): EChartsSeries<OrigFlowGLSeriesOption> {
+  return {
+    series: [
+      {
+        type: "flowGL",
+        id: option.name,
+        name: option.name,
+        data: option.data,
+        particleDensity: 20,
+        particleSize: 3,
+        supersampling: window.devicePixelRatio,
+        ...option.option,
+      },
+    ],
+  };
+}
+
+export interface WindData {
+  /** 位置，由空格分隔的经纬度数字组成。*/
+  location: string;
+  /** 风向，单位是角度（deg），`0` 表示**东风**，随着角度增大，风向**顺时针**旋转。*/
+  wind_direction_80m: number;
+  /** 风速。*/
+  wind_speed_80m: number;
+}
+
+/** 将 JSON 格式的天气数据预处理成 FlowGL 接受的格式。*/
+export function preprocessWindData(
+  data: WindData[],
+): [number, number, number, number][] {
+  return data.map((item) => {
+    const [x, y] = item.location.split(" ").map(Number.parseFloat);
+    // prettier-ignore
+    const sx = -Math.cos(item.wind_direction_80m * (Math.PI / 180)) * item.wind_speed_80m;
+    // prettier-ignore
+    const sy = +Math.sin(item.wind_direction_80m * (Math.PI / 180)) * item.wind_speed_80m;
+    return [x, y, sx, sy];
+  });
+}

package/src/echarts/index.ts

@@ -0,0 +1,120 @@
+import type {
+  AxisPointerComponentOption,
+  Color,
+  DataZoomComponentOption,
+  EChartsOption,
+  GraphicComponentOption,
+  GridComponentOption,
+  LegendComponentOption,
+  RadarComponentOption,
+  SeriesOption,
+  TooltipComponentOption,
+  XAXisComponentOption,
+  YAXisComponentOption,
+} from "echarts";
+import { useMemo } from "react";
+
+export * from "./coordinateSystem";
+export * from "./radar";
+export * from "./legend";
+export * from "./tooltip";
+export * from "./series";
+
+/** 一个可组合的 ECharts 组件。*/
+export interface EChartsComponent {
+  grid?: GridComponentOption[];
+  xAxis?: XAXisComponentOption[];
+  yAxis?: YAXisComponentOption[];
+  radar?: RadarComponentOption[];
+  legend?: LegendComponentOption[];
+  tooltip?: TooltipComponentOption[];
+  axisPointer?: AxisPointerComponentOption[];
+  dataZoom?: DataZoomComponentOption[];
+  graphic?: GraphicComponentOption[];
+  series?: SeriesOption[];
+}
+
+/** 一个 ECharts 系列。*/
+export interface EChartsSeries<T = SeriesOption> {
+  series: T[];
+}
+
+/** ECharts 中不可组合的设置项。*/
+export interface EChartsNonComposableOption {
+  color?: Color[];
+  backgroundColor?: string;
+}
+
+/**
+ * 第一个参数 `base` 中可以填入不可组合的 ECharts 配置项，例如 `color`。
+ * 剩余的参数就是需要组合的各个 ECharts 组件。
+ */
+export function buildEChartsOption(
+  base: EChartsNonComposableOption,
+  ...components: EChartsComponent[]
+) {
+  const option: EChartsComponent & EChartsNonComposableOption = { ...base };
+  for (const component of components) {
+    Object.entries(component).forEach(([k, value]) => {
+      const key = k as keyof EChartsComponent;
+      (option[key] ??= []).push(...(value ?? []));
+    });
+  }
+  return option as EChartsOption;
+}
+
+/**
+ * 用组件组合出 ECharts 的配置对象，并将其缓存以减少重渲染。
+ *
+ * **注意**：该优化只有在传入的每个组件都已经分别被缓存的情况下才有效！
+ * 如果不需要细粒度的记忆化，可以直接将所有组件和 `buildEChartsOption`
+ * 整个用 `useMemo` 包裹起来。
+ */
+export function useMemoizedEChartsOption(
+  base: EChartsNonComposableOption,
+  ...components: EChartsComponent[]
+) {
+  return useMemo(
+    () => buildEChartsOption(base, ...components),
+    components, // eslint-disable-line react-hooks/exhaustive-deps
+  );
+}
+
+// 一些零散工具
+
+/** 一个从 01:00 到 24:00 的数组，可以在等待数据加载时填充 X 轴。*/
+export const HOURS_OF_DAY = Array.from(
+  { length: 24 },
+  (_, index) => (index + 1).toString().padStart(2, "0") + ":00",
+);
+
+/** 虚线图标，可用于图例。*/
+export const DASHES_ICON: string =
+  "path://M304.43 532.76H221.4c-11.47 0-20.76-9.3-20.76-20.76s9.29-20.76 20.76-20.76h83.03c11.47 0 20.76 9.3 20.76 20.76s-9.29 20.76-20.76 20.76zM581.19 532.76H442.81c-11.47 0-20.76-9.3-20.76-20.76s9.29-20.76 20.76-20.76h138.38c11.47 0 20.76 9.3 20.76 20.76s-9.3 20.76-20.76 20.76zM802.59 532.76h-83.03c-11.47 0-20.76-9.3-20.76-20.76s9.29-20.76 20.76-20.76h83.03c11.47 0 20.76 9.3 20.76 20.76s-9.29 20.76-20.76 20.76z";
+
+/** 公用调色板 1。*/
+export const PALETTE_1 = [
+  "#2FDAFF",
+  "#77DA9B",
+  "#FFB82E",
+  "#5470C6",
+  "#91CC75",
+  "#FAC858",
+  "#EE6666",
+  "#73C0DE",
+  "#3BA272",
+  "#FC8452",
+  "#9A60B4",
+  "#EA7CCC",
+];
+
+/** 公用调色板 2。*/
+export const PALETTE_2 = [
+  "#ECA926",
+  "#32ADF4",
+  "#DC7756",
+  "#62CE89",
+  "#4256B9",
+  "#00D0FF",
+  "#96D0DD",
+];

package/src/echarts/legend.ts

@@ -0,0 +1,36 @@
+import type { LegendComponentOption } from "echarts";
+
+import type { EChartsComponent } from ".";
+
+export type LegendDataItem = Exclude<
+  (LegendComponentOption["data"] & {})[0],
+  string
+>;
+
+export interface LegendOption {
+  /**
+   * 图例中要显示的系列或数据项。
+   */
+  data: (string | LegendDataItem)[];
+  /**
+   * 其它图例设置项，参见 [ECharts 文档][1]。
+   *
+   * [1]: https://echarts.apache.org/zh/option.html#legend
+   */
+  option?: LegendComponentOption;
+}
+
+/** 添加一个图例。 */
+export function legend(option: LegendOption): EChartsComponent {
+  return {
+    legend: [
+      {
+        top: 0,
+        right: 0,
+        padding: 0,
+        data: option.data,
+        ...option.option,
+      },
+    ],
+  };
+}

package/src/echarts/radar.ts

@@ -0,0 +1,46 @@
+import type { RadarComponentOption, RadarSeriesOption } from "echarts";
+
+import type { EChartsComponent } from ".";
+
+export interface RadarOption {
+  /** 名称，不可与其它组件和系列重名。*/
+  name: string;
+  /** 雷达图的各维度。*/
+  dimensions: RadarComponentOption["indicator"] & {};
+  /** 雷达图的数据。*/
+  data: RadarSeriesOption["data"] & {};
+  /**
+   * 其它传递给雷达图组件的设置项，参见 [ECharts 文档][1]。
+   *
+   * [1]: https://echarts.apache.org/zh/option.html#radar
+   */
+  option?: RadarComponentOption;
+  /**
+   * 其它传递给雷达系列的设置项，参见 [ECharts 文档][1]。
+   *
+   * [1]: https://echarts.apache.org/zh/option.html#series-radar
+   */
+  series?: RadarSeriesOption;
+}
+
+/** 添加一张雷达图。*/
+export function radar(option: RadarOption): EChartsComponent {
+  return {
+    radar: [
+      {
+        id: option.name + "-radar",
+        indicator: option.dimensions,
+        ...option.option,
+      },
+    ],
+    series: [
+      {
+        type: "radar",
+        name: option.name,
+        radarId: option.name + "-radar",
+        data: option.data,
+        ...option.series,
+      },
+    ],
+  };
+}