plotilla 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +82 -2
- package/data/boundaries/canada_provinces.geojson +1 -0
- package/data/boundaries/eu_countries.geojson +1 -0
- package/data/boundaries/us_states.geojson +1 -0
- package/data/boundaries/world_countries.geojson +1 -0
- package/package.json +62 -4
- package/src/colour/colour_scale.ts +80 -0
- package/src/colour/palette.ts +220 -0
- package/src/examples/example_figures.ts +320 -0
- package/src/fields/axis_fields.ts +32 -0
- package/src/fields/colour_fields.ts +40 -0
- package/src/fields/column_fields.ts +64 -0
- package/src/fields/common_fields.ts +13 -0
- package/src/fields/decide_plot_axes.ts +77 -0
- package/src/fields/marker_fields.ts +16 -0
- package/src/figure/plot_figure.ts +67 -0
- package/src/figure/resolve_plot_figure.ts +47 -0
- package/src/figure/validate_plot_figure.ts +412 -0
- package/src/map/boundary_sets.ts +116 -0
- package/src/map/check_map_layers.ts +32 -0
- package/src/map/fetch_region_outlines.ts +48 -0
- package/src/map/geojson.ts +174 -0
- package/src/map/map_layers.ts +108 -0
- package/src/model/check_axis_shows_years.ts +58 -0
- package/src/model/map_model.ts +238 -0
- package/src/model/panel_layout.ts +171 -0
- package/src/model/panel_model.ts +85 -0
- package/src/model/plot_model.ts +347 -0
- package/src/model/statistics.ts +134 -0
- package/src/plots/bar_plot.ts +36 -0
- package/src/plots/box_plot.ts +26 -0
- package/src/plots/density_plot.ts +29 -0
- package/src/plots/heatmap_plot.ts +24 -0
- package/src/plots/histogram_plot.ts +29 -0
- package/src/plots/line_plot.ts +29 -0
- package/src/plots/map_plot.ts +46 -0
- package/src/plots/pie_plot.ts +23 -0
- package/src/plots/scatter_plot.ts +32 -0
- package/src/renderers/echarts_map.ts +194 -0
- package/src/renderers/echarts_options.ts +317 -0
- package/src/renderers/plotly_map.ts +170 -0
- package/src/renderers/plotly_options.ts +318 -0
- package/src/table/check_column.ts +34 -0
- package/src/table/check_values_have_spread.ts +47 -0
- package/src/table/compute_quantile.ts +23 -0
- package/src/table/data_table.ts +83 -0
- package/src/table/density_bandwidth.ts +94 -0
- package/src/table/find_line_fit.ts +44 -0
- package/src/table/get_number_range.ts +21 -0
- package/src/table/group_rows.ts +71 -0
- package/src/table/list_categories.ts +17 -0
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The fields of plots coloured by a column. A plot that can colour by a
|
|
3
|
+
* number also takes COLOUR_SCALE_FIELDS; one without them colours by
|
|
4
|
+
* category only, and validation refuses a numeric colour there.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { z } from "zod";
|
|
8
|
+
import { defineColumnField } from "./column_fields";
|
|
9
|
+
|
|
10
|
+
/** Whether a colouring column's values are categories or a scale. */
|
|
11
|
+
export const COLOUR_TYPES = ["categorical", "continuous"] as const;
|
|
12
|
+
/** One of COLOUR_TYPES. */
|
|
13
|
+
export type ColourType = (typeof COLOUR_TYPES)[number];
|
|
14
|
+
/** How numbers may map to colour, on charts and maps alike. */
|
|
15
|
+
export const COLOUR_SCALES = ["linear", "log", "quantile"] as const;
|
|
16
|
+
/** One of COLOUR_SCALES. */
|
|
17
|
+
export type ColourScale = (typeof COLOUR_SCALES)[number];
|
|
18
|
+
/** The colour scale a plot gets when the agent names none. */
|
|
19
|
+
export const DEFAULT_COLOUR_SCALE: ColourScale = "linear";
|
|
20
|
+
|
|
21
|
+
/** The fields of a plot or layer coloured by a column. */
|
|
22
|
+
export const COLOUR_FIELDS = {
|
|
23
|
+
colour: defineColumnField("The column that colours the marks: text gives a colour per category, numbers a colour scale.").optional(),
|
|
24
|
+
colour_type: z
|
|
25
|
+
.enum(COLOUR_TYPES)
|
|
26
|
+
.optional()
|
|
27
|
+
.describe('Overrides what the colouring column\'s values imply (colour, or a map region\'s value), e.g. "categorical" for numbered years.'),
|
|
28
|
+
};
|
|
29
|
+
|
|
30
|
+
/** The scales, written for an error: "linear", "log" or "quantile". */
|
|
31
|
+
const COLOUR_SCALE_CHOICES = `${COLOUR_SCALES.slice(0, -1).map((scale) => `"${scale}"`).join(", ")} or "${COLOUR_SCALES.at(-1)}"`;
|
|
32
|
+
|
|
33
|
+
/** The field of a plot or layer that can colour by a number. */
|
|
34
|
+
export const COLOUR_SCALE_FIELDS = {
|
|
35
|
+
colour_scale: z
|
|
36
|
+
.enum(COLOUR_SCALES, { error: (issue) => `${COLOUR_SCALE_CHOICES}; got ${JSON.stringify(issue.input)}.` })
|
|
37
|
+
// No schema default: a scale sent where colour is not a scale is refused, which needs "not sent" apart from "linear".
|
|
38
|
+
.optional()
|
|
39
|
+
.describe("How numbers map to colour: evenly, by order of magnitude, or by rank so each step holds as many marks. Default: linear. Only with a colour of numbers."),
|
|
40
|
+
};
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fields that name a column of the table. Every one is made by
|
|
3
|
+
* defineColumnField, which records it, so validation finds a plot's column
|
|
4
|
+
* fields from its schema instead of a list kept by hand beside it.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { z } from "zod";
|
|
8
|
+
|
|
9
|
+
/** Every column field's schema, so validation can tell which fields name columns. */
|
|
10
|
+
export const COLUMN_FIELD_SCHEMAS: Set<z.ZodType> = new Set();
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Define a field that names a column, and record it as one.
|
|
14
|
+
*
|
|
15
|
+
* @param description - What the column is for, shown to agents in the tool schema.
|
|
16
|
+
* @returns The field's schema.
|
|
17
|
+
*/
|
|
18
|
+
export function defineColumnField(description: string): z.ZodString {
|
|
19
|
+
const field = z.string().min(1).describe(description);
|
|
20
|
+
COLUMN_FIELD_SCHEMAS.add(field);
|
|
21
|
+
return field;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** The x column, shared by every plot that has one. */
|
|
25
|
+
export const X_FIELD = defineColumnField("The column along the x axis.");
|
|
26
|
+
/** The y column, shared by every plot that has one. */
|
|
27
|
+
export const Y_FIELD = defineColumnField("The column along the y axis.");
|
|
28
|
+
/** The value column, shared by heatmap, pie and the regions map layer. */
|
|
29
|
+
export const VALUE_FIELD = defineColumnField(
|
|
30
|
+
"The column each mark shows: a pie slice's size or a heatmap cell's colour (numbers), or a map region's colour (numbers for a scale, text for categories).",
|
|
31
|
+
);
|
|
32
|
+
/** The column naming each mark, shared by pie and the map's points and lines. */
|
|
33
|
+
export const LABEL_FIELD = defineColumnField("The column that names each mark: a pie slice, a map point, a map line.");
|
|
34
|
+
/** The column sizing each point, shared by scatter and the map's points. */
|
|
35
|
+
export const SIZE_FIELD = defineColumnField("A column of numbers that sizes each point.");
|
|
36
|
+
|
|
37
|
+
/** The columns a chart's row must have to become a mark: present ones, and ones holding a number. */
|
|
38
|
+
export type MarkColumns = { present: string[]; numeric: string[] };
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* List the columns a chart's row needs to become a mark, so validation and
|
|
42
|
+
* the model agree on which rows are drawn: x (and, on a heatmap, y) present,
|
|
43
|
+
* y (or a heatmap's value) a number, and a category in every column the plot
|
|
44
|
+
* groups by (line_type, marker_shape, and colour when it is categorical).
|
|
45
|
+
* A histogram or density draws x itself, so its x must be a number.
|
|
46
|
+
*
|
|
47
|
+
* @param plot - The plot's column fields and type.
|
|
48
|
+
* @param options - Whether its colour is by category, so a row needs one.
|
|
49
|
+
* @returns The columns, by what each must hold.
|
|
50
|
+
*/
|
|
51
|
+
export function listMarkColumns(
|
|
52
|
+
plot: { type: string; x?: string; y?: string; value?: string; line_type?: string; marker_shape?: string; colour?: string },
|
|
53
|
+
options: { isColourCategorical: boolean },
|
|
54
|
+
): MarkColumns {
|
|
55
|
+
const grouping = [plot.line_type, plot.marker_shape, options.isColourCategorical ? plot.colour : undefined];
|
|
56
|
+
const isDistribution = plot.type === "histogram" || plot.type === "density";
|
|
57
|
+
const present = plot.type === "heatmap" ? [plot.x, plot.y] : isDistribution ? grouping : [plot.x, ...grouping];
|
|
58
|
+
const numeric = plot.type === "heatmap" ? [plot.value] : isDistribution ? [plot.x] : [plot.y];
|
|
59
|
+
return {
|
|
60
|
+
present: present.filter((column): column is string => column !== undefined),
|
|
61
|
+
numeric: numeric.filter((column): column is string => column !== undefined),
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/** The fields every plot has. */
|
|
2
|
+
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
import { DATA_TABLE_SCHEMA } from "../table/data_table";
|
|
5
|
+
|
|
6
|
+
/** A plot's or map layer's own table: one definition, so both mean the same. */
|
|
7
|
+
export const DATA_FIELD = DATA_TABLE_SCHEMA.optional().describe("Its own table, used instead of the figure's.");
|
|
8
|
+
|
|
9
|
+
/** The fields every plot has: its own title and, optionally, its own table. */
|
|
10
|
+
export const COMMON_FIELDS = {
|
|
11
|
+
title: z.string().min(1).optional().describe("The plot's own title."),
|
|
12
|
+
data: DATA_FIELD,
|
|
13
|
+
};
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which axes a plot has, and of what kind and scale. One rule, read by the
|
|
3
|
+
* model to build each axis and by validation to judge shared axes, so a
|
|
4
|
+
* figure is never refused or accepted on axes the model would not draw.
|
|
5
|
+
* It sits in `fields`, below both `figure` and `model`, as `listMarkColumns` does.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import { findColumn, type DataTable } from "../table/data_table";
|
|
9
|
+
import { DEFAULT_AXIS_SCALE, type AxisScale } from "./axis_fields";
|
|
10
|
+
|
|
11
|
+
/** How an axis places values: spaced numbers, named categories, or dates. */
|
|
12
|
+
export type AxisKind = "value" | "category" | "time";
|
|
13
|
+
|
|
14
|
+
/** An axis's kind and scale: what decides whether two axes can be linked. */
|
|
15
|
+
export type PlotAxis = { kind: AxisKind; scale: AxisScale };
|
|
16
|
+
|
|
17
|
+
/** A plot's axes; null where it has none (a pie, a map). */
|
|
18
|
+
export type PlotAxes = { x: PlotAxis | null; y: PlotAxis | null };
|
|
19
|
+
|
|
20
|
+
/** A date, or a date and time, as ISO 8601 writes it (2025-01-01, 2025-01-01T08:30Z). */
|
|
21
|
+
const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}([T ][\d:.]+(Z|[+-]\d{2}:?\d{2})?)?$/;
|
|
22
|
+
|
|
23
|
+
/** A category axis spaces nothing, so its scale is always the default. */
|
|
24
|
+
const CATEGORY_AXIS: PlotAxis = { kind: "category", scale: DEFAULT_AXIS_SCALE };
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Decide an axis's kind from the values of its column: numbers are a value
|
|
28
|
+
* axis, ISO dates a time axis, anything else categories.
|
|
29
|
+
*
|
|
30
|
+
* @param values - The column's values.
|
|
31
|
+
* @returns The axis kind.
|
|
32
|
+
*/
|
|
33
|
+
export function decideAxisKind(values: readonly (number | string | null)[]): AxisKind {
|
|
34
|
+
const present = values.filter((value) => value !== null);
|
|
35
|
+
if (present.every((value) => typeof value === "number")) return "value";
|
|
36
|
+
if (present.every((value) => typeof value === "string" && ISO_DATE_PATTERN.test(value))) return "time";
|
|
37
|
+
return "category";
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Decide a plot's axes. Bars, boxes and heatmaps put categories on their
|
|
42
|
+
* category axis (a horizontal bar's is y); histograms and densities count
|
|
43
|
+
* numbers in x; lines and scatters take x's kind from its column.
|
|
44
|
+
*
|
|
45
|
+
* @param plot - The plot's type and its axis fields.
|
|
46
|
+
* @param options - The table the plot draws from.
|
|
47
|
+
* @returns Its x and y axes, null where it has none.
|
|
48
|
+
*/
|
|
49
|
+
export function decidePlotAxes(
|
|
50
|
+
plot: { type: string; x?: string; x_scale?: AxisScale; y_scale?: AxisScale; orientation?: string },
|
|
51
|
+
options: { table: DataTable },
|
|
52
|
+
): PlotAxes {
|
|
53
|
+
const xScale = plot.x_scale ?? DEFAULT_AXIS_SCALE;
|
|
54
|
+
const yScale = plot.y_scale ?? DEFAULT_AXIS_SCALE;
|
|
55
|
+
const valueY: PlotAxis = { kind: "value", scale: yScale };
|
|
56
|
+
switch (plot.type) {
|
|
57
|
+
case "line":
|
|
58
|
+
case "scatter": {
|
|
59
|
+
const xValues = plot.x === undefined ? [] : (findColumn(options.table, { column: plot.x }) ?? []);
|
|
60
|
+
return { x: { kind: decideAxisKind(xValues), scale: xScale }, y: valueY };
|
|
61
|
+
}
|
|
62
|
+
case "bar":
|
|
63
|
+
return plot.orientation === "horizontal" ? { x: valueY, y: CATEGORY_AXIS } : { x: CATEGORY_AXIS, y: valueY };
|
|
64
|
+
case "box":
|
|
65
|
+
return { x: CATEGORY_AXIS, y: valueY };
|
|
66
|
+
case "histogram":
|
|
67
|
+
case "density":
|
|
68
|
+
return { x: { kind: "value", scale: xScale }, y: valueY };
|
|
69
|
+
case "heatmap":
|
|
70
|
+
return { x: CATEGORY_AXIS, y: CATEGORY_AXIS };
|
|
71
|
+
case "pie":
|
|
72
|
+
case "map":
|
|
73
|
+
return { x: null, y: null };
|
|
74
|
+
default:
|
|
75
|
+
throw new Error(`Expected a known plot type to decide its axes; got "${plot.type}".`);
|
|
76
|
+
}
|
|
77
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/** The field of plots that can draw a marker for each row of data. */
|
|
2
|
+
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
|
|
5
|
+
/** Markers when the agent sends none, except on a line coloured by a number. */
|
|
6
|
+
export const DEFAULT_SHOW_MARKERS = false;
|
|
7
|
+
|
|
8
|
+
/** The field of plots that can mark each row: line and box. */
|
|
9
|
+
export const MARKER_FIELDS = {
|
|
10
|
+
// No schema default: a line coloured by a number needs its markers to carry
|
|
11
|
+
// the colour, so the model tells "not sent" apart from false.
|
|
12
|
+
show_markers: z
|
|
13
|
+
.boolean()
|
|
14
|
+
.optional()
|
|
15
|
+
.describe("Draw a marker for each row of data. Default: off, except on a line coloured by a number, whose markers carry the colour."),
|
|
16
|
+
};
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The figure: one shared table and one or more plots in a grid. This is
|
|
3
|
+
* the whole shape a caller sends, and the one list of plot types.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import { z } from "zod";
|
|
7
|
+
import { BAR_NUMERIC_COLUMNS, BAR_PLOT_SCHEMA } from "../plots/bar_plot";
|
|
8
|
+
import { BOX_NUMERIC_COLUMNS, BOX_PLOT_SCHEMA } from "../plots/box_plot";
|
|
9
|
+
import { DENSITY_NUMERIC_COLUMNS, DENSITY_PLOT_SCHEMA } from "../plots/density_plot";
|
|
10
|
+
import { HEATMAP_NUMERIC_COLUMNS, HEATMAP_PLOT_SCHEMA } from "../plots/heatmap_plot";
|
|
11
|
+
import { HISTOGRAM_NUMERIC_COLUMNS, HISTOGRAM_PLOT_SCHEMA } from "../plots/histogram_plot";
|
|
12
|
+
import { LINE_NUMERIC_COLUMNS, LINE_PLOT_SCHEMA } from "../plots/line_plot";
|
|
13
|
+
import { MAP_NUMERIC_COLUMNS, MAP_PLOT_SCHEMA } from "../plots/map_plot";
|
|
14
|
+
import { PIE_NUMERIC_COLUMNS, PIE_PLOT_SCHEMA } from "../plots/pie_plot";
|
|
15
|
+
import { SCATTER_NUMERIC_COLUMNS, SCATTER_PLOT_SCHEMA } from "../plots/scatter_plot";
|
|
16
|
+
import { DATA_TABLE_SCHEMA } from "../table/data_table";
|
|
17
|
+
|
|
18
|
+
/** Every plot type's schema, in the order the catalogue lists them. */
|
|
19
|
+
export const PLOT_SCHEMAS = [
|
|
20
|
+
LINE_PLOT_SCHEMA, SCATTER_PLOT_SCHEMA, BAR_PLOT_SCHEMA, BOX_PLOT_SCHEMA,
|
|
21
|
+
HISTOGRAM_PLOT_SCHEMA, DENSITY_PLOT_SCHEMA, HEATMAP_PLOT_SCHEMA, PIE_PLOT_SCHEMA, MAP_PLOT_SCHEMA,
|
|
22
|
+
] as const;
|
|
23
|
+
|
|
24
|
+
/** Any one plot, told apart by its type. */
|
|
25
|
+
export const PLOT_SCHEMA = z.discriminatedUnion("type", PLOT_SCHEMAS);
|
|
26
|
+
|
|
27
|
+
/** Any one plot, through the schema. */
|
|
28
|
+
export type Plot = z.infer<typeof PLOT_SCHEMA>;
|
|
29
|
+
/** The name of a plot type. */
|
|
30
|
+
export type PlotType = Plot["type"];
|
|
31
|
+
|
|
32
|
+
/** Every plot but a map: the plots with x and y. */
|
|
33
|
+
export type ChartPlot = Exclude<Plot, { type: "map" }>;
|
|
34
|
+
|
|
35
|
+
/** Each plot type's column fields that must hold numbers. */
|
|
36
|
+
export const NUMERIC_COLUMNS: Readonly<Record<PlotType, readonly string[]>> = {
|
|
37
|
+
line: LINE_NUMERIC_COLUMNS, scatter: SCATTER_NUMERIC_COLUMNS, bar: BAR_NUMERIC_COLUMNS, box: BOX_NUMERIC_COLUMNS,
|
|
38
|
+
histogram: HISTOGRAM_NUMERIC_COLUMNS, density: DENSITY_NUMERIC_COLUMNS, heatmap: HEATMAP_NUMERIC_COLUMNS, pie: PIE_NUMERIC_COLUMNS, map: MAP_NUMERIC_COLUMNS,
|
|
39
|
+
};
|
|
40
|
+
|
|
41
|
+
/** The chart libraries a figure can be drawn with. */
|
|
42
|
+
export const RENDERERS = ["plotly", "echarts"] as const;
|
|
43
|
+
|
|
44
|
+
/** Whether panels share an axis when the agent does not say: no. */
|
|
45
|
+
export const DEFAULT_IS_AXIS_SHARED = false;
|
|
46
|
+
|
|
47
|
+
/** The whole figure an agent sends: one table and its plots. Its JSON Schema is what an agent reads. */
|
|
48
|
+
export const PLOT_FIGURE_SCHEMA = z.strictObject({
|
|
49
|
+
data: DATA_TABLE_SCHEMA.describe("The table the plots draw from, unless a plot brings its own."),
|
|
50
|
+
plots: z.array(PLOT_SCHEMA).min(1).describe("The plots, filling the grid row by row."),
|
|
51
|
+
grid: z
|
|
52
|
+
.strictObject({ rows: z.number().int().min(1), columns: z.number().int().min(1) })
|
|
53
|
+
.optional()
|
|
54
|
+
.describe("Rows and columns of plots. Default: one column, a row per plot."),
|
|
55
|
+
title: z.string().min(1).optional().describe("A title over the whole figure."),
|
|
56
|
+
// The host shows the caption under the chart; neither library draws it, so plotilla passes it through.
|
|
57
|
+
caption: z.string().min(1).optional().describe("A line the host shows under the figure: its source, or what to notice."),
|
|
58
|
+
renderer: z.enum(RENDERERS).optional().describe("The library that draws the figure. Default: the caller's."),
|
|
59
|
+
is_x_axis_shared: z.boolean().default(DEFAULT_IS_AXIS_SHARED).describe("Link the x axes of the plots that have one (pies and maps have none), so zooming one zooms all. Needs two or more, of one kind (numbers, categories or dates) and one scale."),
|
|
60
|
+
is_y_axis_shared: z.boolean().default(DEFAULT_IS_AXIS_SHARED).describe("Link the y axes of the plots that have one (pies and maps have none), so zooming one zooms all. Needs two or more, of one kind (numbers, categories or dates) and one scale."),
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
/** A figure through the schema, every default filled in: what the model draws. */
|
|
64
|
+
export type PlotFigure = z.output<typeof PLOT_FIGURE_SCHEMA>;
|
|
65
|
+
|
|
66
|
+
/** A figure as a caller writes it, defaults left out. */
|
|
67
|
+
export type PlotFigureInput = z.input<typeof PLOT_FIGURE_SCHEMA>;
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resolve a figure the way a host shows one: check it, load the outlines its
|
|
3
|
+
* map layers name, and build its model once so any problem surfaces now
|
|
4
|
+
* rather than as a broken chart (renderers build their own).
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { resolveBoundarySet, type BoundarySetLoader } from "../map/boundary_sets";
|
|
8
|
+
import { fetchRegionOutlines, type GeoJsonFetcher } from "../map/fetch_region_outlines";
|
|
9
|
+
import { computePanelRectangles, type FigureSize } from "../model/panel_layout";
|
|
10
|
+
import { buildFigureModel } from "../model/plot_model";
|
|
11
|
+
import type { PlotFigure } from "./plot_figure";
|
|
12
|
+
import { validatePlotFigure, validatePlotFigureBeforeOutlines, type PlotFigureLimits } from "./validate_plot_figure";
|
|
13
|
+
|
|
14
|
+
/** A figure checked and with its outlines loaded, and what the agent should be told about it. */
|
|
15
|
+
export type ResolvedPlotFigure = { figure: PlotFigure; notes: string[] };
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Resolve a figure.
|
|
19
|
+
*
|
|
20
|
+
* @param input - The figure as the caller sent it. Never changed: outlines go into a copy.
|
|
21
|
+
* @param options - The caller's limits, the size it draws at in pixels, how to load a built-in outline set, and how to fetch outlines from an address.
|
|
22
|
+
* @returns The figure, valid, defaults and outlines filled in, and notes for the agent (unmatched region names, what a renderer cannot draw).
|
|
23
|
+
*/
|
|
24
|
+
export async function resolvePlotFigure(
|
|
25
|
+
input: unknown,
|
|
26
|
+
options: { limits: PlotFigureLimits; size: FigureSize; loadBoundarySet: BoundarySetLoader; fetchGeoJson: GeoJsonFetcher },
|
|
27
|
+
): Promise<ResolvedPlotFigure> {
|
|
28
|
+
// Everything that needs no outlines first, so a figure that will be refused fetches nothing.
|
|
29
|
+
const figure = validatePlotFigureBeforeOutlines(input, { limits: options.limits });
|
|
30
|
+
const boundaryNotes: string[] = [];
|
|
31
|
+
for (const [index, plot] of figure.plots.entries()) {
|
|
32
|
+
if (plot.type !== "map") continue;
|
|
33
|
+
for (const [layerIndex, layer] of plot.layers.entries()) {
|
|
34
|
+
if (layer.type !== "regions" || layer.boundaries === undefined) continue;
|
|
35
|
+
const note = await resolveBoundarySet(layer, {
|
|
36
|
+
table: layer.data ?? plot.data ?? figure.data, where: `plots[${index}].layers[${layerIndex}]`, loadBoundarySet: options.loadBoundarySet,
|
|
37
|
+
});
|
|
38
|
+
if (note !== null) boundaryNotes.push(note);
|
|
39
|
+
}
|
|
40
|
+
await fetchRegionOutlines(plot.layers, { where: `plots[${index}]`, fetchGeoJson: options.fetchGeoJson });
|
|
41
|
+
}
|
|
42
|
+
const resolved = validatePlotFigure(figure, { limits: options.limits });
|
|
43
|
+
const model = buildFigureModel(resolved);
|
|
44
|
+
// Laid out once at the host's size, so a figure that cannot fit is refused now, not when drawn.
|
|
45
|
+
computePanelRectangles(model, { size: options.size });
|
|
46
|
+
return { figure: resolved, notes: [...boundaryNotes, ...model.notes] };
|
|
47
|
+
}
|