plotilla 1.0.0 → 1.1.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/README.md +37 -11
- package/data/boundaries/world_countries.geojson +1 -1
- package/dist/colour/colour_scale.d.ts +55 -0
- package/dist/colour/colour_scale.js +80 -0
- package/dist/colour/palette.d.ts +176 -0
- package/dist/colour/palette.js +220 -0
- package/dist/fields/axis_fields.d.ts +56 -0
- package/dist/fields/axis_fields.js +46 -0
- package/dist/fields/colour_fields.d.ts +32 -0
- package/dist/fields/colour_fields.js +31 -0
- package/dist/fields/column_fields.d.ts +52 -0
- package/{src/fields/column_fields.ts → dist/fields/column_fields.js} +15 -29
- package/dist/fields/common_fields.d.ts +9 -0
- package/{src/fields/common_fields.ts → dist/fields/common_fields.js} +3 -6
- package/dist/fields/decide_plot_axes.d.ts +56 -0
- package/dist/fields/decide_plot_axes.js +71 -0
- package/dist/fields/marker_fields.d.ts +8 -0
- package/dist/fields/marker_fields.js +13 -0
- package/dist/fields/read_date_time.d.ts +85 -0
- package/dist/fields/read_date_time.js +199 -0
- package/dist/figure/check_axis_year_formats.d.ts +36 -0
- package/dist/figure/check_axis_year_formats.js +116 -0
- package/dist/figure/check_plot_category_limits.d.ts +128 -0
- package/dist/figure/check_plot_category_limits.js +284 -0
- package/dist/figure/plot_figure.d.ts +861 -0
- package/dist/figure/plot_figure.js +58 -0
- package/dist/figure/resolve_plot_figure.d.ts +28 -0
- package/dist/figure/resolve_plot_figure.js +41 -0
- package/dist/figure/validate_plot_figure.d.ts +50 -0
- package/dist/figure/validate_plot_figure.js +441 -0
- package/dist/map/assign_map_layer_hue_slots.d.ts +89 -0
- package/dist/map/assign_map_layer_hue_slots.js +146 -0
- package/dist/map/boundary_sets.d.ts +65 -0
- package/dist/map/boundary_sets.js +103 -0
- package/dist/map/build_world_outline_across_180.d.ts +21 -0
- package/dist/map/build_world_outline_across_180.js +23 -0
- package/dist/map/check_map_layers.d.ts +16 -0
- package/dist/map/check_map_layers.js +31 -0
- package/dist/map/fetch_region_outlines.d.ts +25 -0
- package/dist/map/fetch_region_outlines.js +39 -0
- package/dist/map/geojson.d.ts +150 -0
- package/dist/map/geojson.js +248 -0
- package/dist/map/join_region_rows.d.ts +40 -0
- package/dist/map/join_region_rows.js +45 -0
- package/dist/map/map_layers.d.ts +229 -0
- package/dist/map/map_layers.js +87 -0
- package/dist/model/find_panel_colour_scale.d.ts +25 -0
- package/dist/model/find_panel_colour_scale.js +27 -0
- package/dist/model/map_model.d.ts +30 -0
- package/dist/model/map_model.js +234 -0
- package/dist/model/panel_layout.d.ts +42 -0
- package/dist/model/panel_layout.js +154 -0
- package/dist/model/panel_model.d.ts +223 -0
- package/dist/model/panel_model.js +7 -0
- package/dist/model/plot_model.d.ts +28 -0
- package/dist/model/plot_model.js +431 -0
- package/dist/model/statistics.d.ts +83 -0
- package/dist/model/statistics.js +107 -0
- package/dist/plots/bar_plot.d.ts +46 -0
- package/dist/plots/bar_plot.js +30 -0
- package/dist/plots/box_plot.d.ts +30 -0
- package/dist/plots/box_plot.js +21 -0
- package/dist/plots/density_plot.d.ts +36 -0
- package/dist/plots/density_plot.js +23 -0
- package/dist/plots/heatmap_plot.d.ts +22 -0
- package/dist/plots/heatmap_plot.js +18 -0
- package/dist/plots/histogram_plot.d.ts +32 -0
- package/dist/plots/histogram_plot.js +24 -0
- package/dist/plots/line_plot.d.ts +44 -0
- package/dist/plots/line_plot.js +25 -0
- package/dist/plots/map_plot.d.ts +92 -0
- package/dist/plots/map_plot.js +35 -0
- package/dist/plots/pie_plot.d.ts +17 -0
- package/dist/plots/pie_plot.js +16 -0
- package/dist/plots/scatter_plot.d.ts +47 -0
- package/dist/plots/scatter_plot.js +27 -0
- package/dist/renderers/date_ticks.d.ts +37 -0
- package/dist/renderers/date_ticks.js +148 -0
- package/dist/renderers/echarts_map.d.ts +47 -0
- package/dist/renderers/echarts_map.js +492 -0
- package/dist/renderers/echarts_options.d.ts +30 -0
- package/dist/renderers/echarts_options.js +449 -0
- package/dist/renderers/echarts_pie_radius.d.ts +52 -0
- package/dist/renderers/echarts_pie_radius.js +158 -0
- package/dist/renderers/escape_html.d.ts +10 -0
- package/dist/renderers/escape_html.js +15 -0
- package/dist/renderers/line_colour_segments.d.ts +39 -0
- package/dist/renderers/line_colour_segments.js +41 -0
- package/dist/renderers/plotly_map.d.ts +48 -0
- package/dist/renderers/plotly_map.js +159 -0
- package/dist/renderers/plotly_options.d.ts +19 -0
- package/dist/renderers/plotly_options.js +345 -0
- package/dist/renderers/year_ticks.d.ts +27 -0
- package/dist/renderers/year_ticks.js +42 -0
- package/dist/table/check_column.d.ts +36 -0
- package/dist/table/check_column.js +46 -0
- package/dist/table/check_values_have_spread.d.ts +30 -0
- package/{src/table/check_values_have_spread.ts → dist/table/check_values_have_spread.js} +16 -17
- package/dist/table/compute_quantile.d.ts +16 -0
- package/dist/table/compute_quantile.js +23 -0
- package/dist/table/data_table.d.ts +59 -0
- package/dist/table/data_table.js +87 -0
- package/dist/table/density_bandwidth.d.ts +64 -0
- package/dist/table/density_bandwidth.js +88 -0
- package/dist/table/find_line_fit.d.ts +30 -0
- package/dist/table/find_line_fit.js +36 -0
- package/dist/table/get_number_range.d.ts +16 -0
- package/{src/table/get_number_range.ts → dist/table/get_number_range.js} +8 -8
- package/dist/table/group_rows.d.ts +40 -0
- package/dist/table/group_rows.js +67 -0
- package/dist/table/list_categories.d.ts +14 -0
- package/{src/table/list_categories.ts → dist/table/list_categories.js} +2 -3
- package/dist/table/read_number.d.ts +12 -0
- package/dist/table/read_number.js +14 -0
- package/package.json +28 -23
- package/src/colour/colour_scale.ts +0 -80
- package/src/colour/palette.ts +0 -220
- package/src/examples/example_figures.ts +0 -320
- package/src/fields/axis_fields.ts +0 -32
- package/src/fields/colour_fields.ts +0 -40
- package/src/fields/decide_plot_axes.ts +0 -77
- package/src/fields/marker_fields.ts +0 -16
- package/src/figure/plot_figure.ts +0 -67
- package/src/figure/resolve_plot_figure.ts +0 -47
- package/src/figure/validate_plot_figure.ts +0 -412
- package/src/map/boundary_sets.ts +0 -116
- package/src/map/check_map_layers.ts +0 -32
- package/src/map/fetch_region_outlines.ts +0 -48
- package/src/map/geojson.ts +0 -174
- package/src/map/map_layers.ts +0 -108
- package/src/model/check_axis_shows_years.ts +0 -58
- package/src/model/map_model.ts +0 -238
- package/src/model/panel_layout.ts +0 -171
- package/src/model/panel_model.ts +0 -85
- package/src/model/plot_model.ts +0 -347
- package/src/model/statistics.ts +0 -134
- package/src/plots/bar_plot.ts +0 -36
- package/src/plots/box_plot.ts +0 -26
- package/src/plots/density_plot.ts +0 -29
- package/src/plots/heatmap_plot.ts +0 -24
- package/src/plots/histogram_plot.ts +0 -29
- package/src/plots/line_plot.ts +0 -29
- package/src/plots/map_plot.ts +0 -46
- package/src/plots/pie_plot.ts +0 -23
- package/src/plots/scatter_plot.ts +0 -32
- package/src/renderers/echarts_map.ts +0 -194
- package/src/renderers/echarts_options.ts +0 -317
- package/src/renderers/plotly_map.ts +0 -170
- package/src/renderers/plotly_options.ts +0 -318
- package/src/table/check_column.ts +0 -34
- package/src/table/compute_quantile.ts +0 -23
- package/src/table/data_table.ts +0 -83
- package/src/table/density_bandwidth.ts +0 -94
- package/src/table/find_line_fit.ts +0 -44
- package/src/table/group_rows.ts +0 -71
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* GeoJSON the map needs: checking what agents send, the bounds of what is
|
|
3
|
+
* shown, and great-circle arcs for lines between places.
|
|
4
|
+
*/
|
|
5
|
+
/** A GeoJSON geometry, loosely typed: this package passes geometries through, only reading coordinates for bounds. */
|
|
6
|
+
export type Geometry = {
|
|
7
|
+
type: string;
|
|
8
|
+
coordinates?: unknown;
|
|
9
|
+
geometries?: Geometry[];
|
|
10
|
+
};
|
|
11
|
+
/** A GeoJSON feature. */
|
|
12
|
+
export type Feature = {
|
|
13
|
+
type: "Feature";
|
|
14
|
+
geometry: Geometry | null;
|
|
15
|
+
properties?: Record<string, unknown> | null;
|
|
16
|
+
id?: string | number;
|
|
17
|
+
};
|
|
18
|
+
/** A GeoJSON feature collection. */
|
|
19
|
+
export type FeatureCollection = {
|
|
20
|
+
type: "FeatureCollection";
|
|
21
|
+
features: Feature[];
|
|
22
|
+
};
|
|
23
|
+
/** [west, south, east, north] in degrees. */
|
|
24
|
+
export type Bounds = [number, number, number, number];
|
|
25
|
+
/** Points along a great-circle arc: enough for a smooth curve at any zoom. */
|
|
26
|
+
export declare const ARC_POINTS = 64;
|
|
27
|
+
/**
|
|
28
|
+
* Check a value is a GeoJSON FeatureCollection (or a single Feature, which is wrapped).
|
|
29
|
+
*
|
|
30
|
+
* @param value - Parsed JSON from the agent or a URL.
|
|
31
|
+
* @param options - Where it came from, for error messages.
|
|
32
|
+
* @returns The feature collection.
|
|
33
|
+
*/
|
|
34
|
+
export declare function readFeatureCollection(value: unknown, options: {
|
|
35
|
+
where: string;
|
|
36
|
+
}): FeatureCollection;
|
|
37
|
+
/**
|
|
38
|
+
* Find the bounds of a set of positions.
|
|
39
|
+
*
|
|
40
|
+
* @param positions - [longitude, latitude] pairs.
|
|
41
|
+
* @returns The bounds, or null when there are none.
|
|
42
|
+
*/
|
|
43
|
+
export declare function findBounds(positions: [number, number][]): Bounds | null;
|
|
44
|
+
/**
|
|
45
|
+
* Find the bounds to fit a view to, allowing for the 180° line: places that
|
|
46
|
+
* straddle it (Alaska's Aleutians, Russia's east, Fiji) span less when
|
|
47
|
+
* longitudes west of 0° are counted from 180° to 360°. That wrapped reading
|
|
48
|
+
* wins only when it is narrower than the plain one by more than
|
|
49
|
+
* WRAP_MINIMUM_SAVING_SHARE of the plain span; its east edge may then be past 180.
|
|
50
|
+
*
|
|
51
|
+
* @param positions - [longitude, latitude] pairs.
|
|
52
|
+
* @returns [west, south, east, north], or null if there are none.
|
|
53
|
+
*/
|
|
54
|
+
export declare function findFittingBounds(positions: [number, number][]): Bounds | null;
|
|
55
|
+
/**
|
|
56
|
+
* Bring a longitude back into -180…180.
|
|
57
|
+
*
|
|
58
|
+
* @param longitude - Any longitude, e.g. past 180 after a wrap-aware fit.
|
|
59
|
+
* @returns The same meridian, between -180 and 180.
|
|
60
|
+
*/
|
|
61
|
+
export declare function normaliseLongitude(longitude: number): number;
|
|
62
|
+
/**
|
|
63
|
+
* Place a longitude inside bounds that `findFittingBounds` built: a longitude
|
|
64
|
+
* west of them is a turn further east, where the wrapped reading counts it.
|
|
65
|
+
* Plain bounds hold every position already, so nothing moves.
|
|
66
|
+
*
|
|
67
|
+
* @param longitude - A longitude between -180 and 180, from the positions the bounds were built from.
|
|
68
|
+
* @param options - The bounds, [west, south, east, north]; east may be past 180.
|
|
69
|
+
* @returns The same meridian, inside the bounds.
|
|
70
|
+
*/
|
|
71
|
+
export declare function placeLongitudeInBounds(longitude: number, options: {
|
|
72
|
+
bounds: Bounds;
|
|
73
|
+
}): number;
|
|
74
|
+
/**
|
|
75
|
+
* Place a longitude on the copy of its meridian nearest a reference longitude,
|
|
76
|
+
* e.g. a view's centre beside the data it is drawn with, past 180 if need be.
|
|
77
|
+
*
|
|
78
|
+
* @param longitude - Any longitude.
|
|
79
|
+
* @param options - The reference longitude.
|
|
80
|
+
* @returns The same meridian, within half a turn of the reference.
|
|
81
|
+
*/
|
|
82
|
+
export declare function placeLongitudeNear(longitude: number, options: {
|
|
83
|
+
reference: number;
|
|
84
|
+
}): number;
|
|
85
|
+
/**
|
|
86
|
+
* Copy a feature collection with every position placed inside bounds that
|
|
87
|
+
* `findFittingBounds` built from it (see `placeLongitudeInBounds`), so an
|
|
88
|
+
* outline across the 180° line is drawn in one piece on a flat map.
|
|
89
|
+
*
|
|
90
|
+
* @param collection - The features.
|
|
91
|
+
* @param options - The bounds.
|
|
92
|
+
* @returns A new collection; the original is untouched.
|
|
93
|
+
*/
|
|
94
|
+
export declare function placeCollectionInBounds(collection: FeatureCollection, options: {
|
|
95
|
+
bounds: Bounds;
|
|
96
|
+
}): FeatureCollection;
|
|
97
|
+
/**
|
|
98
|
+
* Copy a feature collection with every position's longitude moved a whole
|
|
99
|
+
* number of turns east (west when negative), the same meridians on another
|
|
100
|
+
* copy of the world.
|
|
101
|
+
*
|
|
102
|
+
* @param collection - The features.
|
|
103
|
+
* @param options - How many turns to move: a whole number.
|
|
104
|
+
* @returns A new collection; the original is untouched.
|
|
105
|
+
* @throws Error when `turns` is not a whole number, since part of a turn
|
|
106
|
+
* would land on other meridians, not a copy of the same ones.
|
|
107
|
+
*/
|
|
108
|
+
export declare function moveCollectionByTurns(collection: FeatureCollection, options: {
|
|
109
|
+
turns: number;
|
|
110
|
+
}): FeatureCollection;
|
|
111
|
+
/**
|
|
112
|
+
* Copy a feature collection with every position's longitude passed through a function.
|
|
113
|
+
*
|
|
114
|
+
* @param collection - The features.
|
|
115
|
+
* @param options - `moveLongitude` gives each position's new longitude from its old one.
|
|
116
|
+
* @returns A new collection; the original is untouched.
|
|
117
|
+
*/
|
|
118
|
+
export declare function mapCollectionLongitudes(collection: FeatureCollection, options: {
|
|
119
|
+
moveLongitude: (longitude: number) => number;
|
|
120
|
+
}): FeatureCollection;
|
|
121
|
+
/**
|
|
122
|
+
* List every position in a feature collection.
|
|
123
|
+
*
|
|
124
|
+
* @param collection - The features.
|
|
125
|
+
* @returns [longitude, latitude] pairs.
|
|
126
|
+
*/
|
|
127
|
+
export declare function listPositions(collection: FeatureCollection): [number, number][];
|
|
128
|
+
/**
|
|
129
|
+
* Points along the great circle between two places, so a line follows the
|
|
130
|
+
* curve of the earth (it bends on a flat map, and hugs the globe).
|
|
131
|
+
*
|
|
132
|
+
* @param from - [longitude, latitude].
|
|
133
|
+
* @param options - Where it goes, and how many points to use.
|
|
134
|
+
* @returns The arc's positions, from start to end.
|
|
135
|
+
*/
|
|
136
|
+
export declare function buildGreatCircleArc(from: [number, number], options: {
|
|
137
|
+
to: [number, number];
|
|
138
|
+
pointCount?: number;
|
|
139
|
+
}): [number, number][];
|
|
140
|
+
/**
|
|
141
|
+
* Read a feature's property by name, among its own properties only: a
|
|
142
|
+
* property name like "constructor" would otherwise find Object's member.
|
|
143
|
+
*
|
|
144
|
+
* @param feature - The feature.
|
|
145
|
+
* @param options - The property's name.
|
|
146
|
+
* @returns Its value, or undefined when the feature has no such property.
|
|
147
|
+
*/
|
|
148
|
+
export declare function findFeatureProperty(feature: Feature, options: {
|
|
149
|
+
property: string;
|
|
150
|
+
}): unknown;
|
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* GeoJSON the map needs: checking what agents send, the bounds of what is
|
|
3
|
+
* shown, and great-circle arcs for lines between places.
|
|
4
|
+
*/
|
|
5
|
+
/** Points along a great-circle arc: enough for a smooth curve at any zoom. */
|
|
6
|
+
export const ARC_POINTS = 64;
|
|
7
|
+
const DEGREES_TO_RADIANS = Math.PI / 180;
|
|
8
|
+
/**
|
|
9
|
+
* Check a value is a GeoJSON FeatureCollection (or a single Feature, which is wrapped).
|
|
10
|
+
*
|
|
11
|
+
* @param value - Parsed JSON from the agent or a URL.
|
|
12
|
+
* @param options - Where it came from, for error messages.
|
|
13
|
+
* @returns The feature collection.
|
|
14
|
+
*/
|
|
15
|
+
export function readFeatureCollection(value, options) {
|
|
16
|
+
if (typeof value !== "object" || value === null)
|
|
17
|
+
throw new Error(`${options.where}: expected GeoJSON, got ${typeof value}.`);
|
|
18
|
+
const record = value;
|
|
19
|
+
if (record.type === "Feature")
|
|
20
|
+
return readFeatureCollection({ type: "FeatureCollection", features: [record] }, options);
|
|
21
|
+
if (record.type !== "FeatureCollection" || !Array.isArray(record.features)) {
|
|
22
|
+
throw new Error(`${options.where}: expected a GeoJSON FeatureCollection; got type "${String(record.type)}".`);
|
|
23
|
+
}
|
|
24
|
+
record.features.forEach((feature, index) => {
|
|
25
|
+
const item = feature;
|
|
26
|
+
if (typeof item !== "object" || item === null || item.type !== "Feature") {
|
|
27
|
+
throw new Error(`${options.where}: features[${index}] is not a GeoJSON Feature.`);
|
|
28
|
+
}
|
|
29
|
+
});
|
|
30
|
+
return value;
|
|
31
|
+
}
|
|
32
|
+
function collectPositions(coordinates, into) {
|
|
33
|
+
if (!Array.isArray(coordinates))
|
|
34
|
+
return;
|
|
35
|
+
if (typeof coordinates[0] === "number" && typeof coordinates[1] === "number") {
|
|
36
|
+
into.push([coordinates[0], coordinates[1]]);
|
|
37
|
+
return;
|
|
38
|
+
}
|
|
39
|
+
for (const part of coordinates)
|
|
40
|
+
collectPositions(part, into);
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Find the bounds of a set of positions.
|
|
44
|
+
*
|
|
45
|
+
* @param positions - [longitude, latitude] pairs.
|
|
46
|
+
* @returns The bounds, or null when there are none.
|
|
47
|
+
*/
|
|
48
|
+
export function findBounds(positions) {
|
|
49
|
+
if (positions.length === 0)
|
|
50
|
+
return null;
|
|
51
|
+
let [west, south, east, north] = [Infinity, Infinity, -Infinity, -Infinity];
|
|
52
|
+
for (const [longitude, latitude] of positions) {
|
|
53
|
+
west = Math.min(west, longitude);
|
|
54
|
+
east = Math.max(east, longitude);
|
|
55
|
+
south = Math.min(south, latitude);
|
|
56
|
+
north = Math.max(north, latitude);
|
|
57
|
+
}
|
|
58
|
+
return [west, south, east, north];
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Find the bounds to fit a view to, allowing for the 180° line: places that
|
|
62
|
+
* straddle it (Alaska's Aleutians, Russia's east, Fiji) span less when
|
|
63
|
+
* longitudes west of 0° are counted from 180° to 360°. That wrapped reading
|
|
64
|
+
* wins only when it is narrower than the plain one by more than
|
|
65
|
+
* WRAP_MINIMUM_SAVING_SHARE of the plain span; its east edge may then be past 180.
|
|
66
|
+
*
|
|
67
|
+
* @param positions - [longitude, latitude] pairs.
|
|
68
|
+
* @returns [west, south, east, north], or null if there are none.
|
|
69
|
+
*/
|
|
70
|
+
export function findFittingBounds(positions) {
|
|
71
|
+
const plain = findBounds(positions);
|
|
72
|
+
if (plain === null)
|
|
73
|
+
return null;
|
|
74
|
+
const shifted = findBounds(positions.map(([longitude, latitude]) => [longitude < 0 ? longitude + FULL_TURN_DEGREES : longitude, latitude]));
|
|
75
|
+
if (shifted === null)
|
|
76
|
+
return plain;
|
|
77
|
+
const plainSpan = plain[2] - plain[0];
|
|
78
|
+
// Only a real saving counts. The saving is the empty gap across 0° minus the one across 180°: outlines of the
|
|
79
|
+
// whole world have both gaps at rounding size, and points spread nearly all the way round have both small.
|
|
80
|
+
return plainSpan - (shifted[2] - shifted[0]) > plainSpan * WRAP_MINIMUM_SAVING_SHARE ? shifted : plain;
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* Share of the plain span the wrapped reading must save to win. A share, not degrees, because a view's zoom
|
|
84
|
+
* follows the log of its span: a saving under 10% moves zoom by at most about 0.15 levels, so either reading shows
|
|
85
|
+
* all the data at much the same size, and the conventional view near 0° stands (the centre can still differ by
|
|
86
|
+
* about 180° between the two readings). Measured savings sit far either side: the world outlines 0.02%,
|
|
87
|
+
* cities from -170° to 170° 2%, Niue and Vanuatu 94%, Fiji 99%.
|
|
88
|
+
*/
|
|
89
|
+
const WRAP_MINIMUM_SAVING_SHARE = 0.1;
|
|
90
|
+
/** Degrees in a full turn of longitude. */
|
|
91
|
+
const FULL_TURN_DEGREES = 360;
|
|
92
|
+
/**
|
|
93
|
+
* Bring a longitude back into -180…180.
|
|
94
|
+
*
|
|
95
|
+
* @param longitude - Any longitude, e.g. past 180 after a wrap-aware fit.
|
|
96
|
+
* @returns The same meridian, between -180 and 180.
|
|
97
|
+
*/
|
|
98
|
+
export function normaliseLongitude(longitude) {
|
|
99
|
+
return ((((longitude + FULL_TURN_DEGREES / 2) % FULL_TURN_DEGREES) + FULL_TURN_DEGREES) % FULL_TURN_DEGREES) - FULL_TURN_DEGREES / 2;
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* Place a longitude inside bounds that `findFittingBounds` built: a longitude
|
|
103
|
+
* west of them is a turn further east, where the wrapped reading counts it.
|
|
104
|
+
* Plain bounds hold every position already, so nothing moves.
|
|
105
|
+
*
|
|
106
|
+
* @param longitude - A longitude between -180 and 180, from the positions the bounds were built from.
|
|
107
|
+
* @param options - The bounds, [west, south, east, north]; east may be past 180.
|
|
108
|
+
* @returns The same meridian, inside the bounds.
|
|
109
|
+
*/
|
|
110
|
+
export function placeLongitudeInBounds(longitude, options) {
|
|
111
|
+
return longitude < options.bounds[0] ? longitude + FULL_TURN_DEGREES : longitude;
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* Place a longitude on the copy of its meridian nearest a reference longitude,
|
|
115
|
+
* e.g. a view's centre beside the data it is drawn with, past 180 if need be.
|
|
116
|
+
*
|
|
117
|
+
* @param longitude - Any longitude.
|
|
118
|
+
* @param options - The reference longitude.
|
|
119
|
+
* @returns The same meridian, within half a turn of the reference.
|
|
120
|
+
*/
|
|
121
|
+
export function placeLongitudeNear(longitude, options) {
|
|
122
|
+
return longitude + FULL_TURN_DEGREES * Math.round((options.reference - longitude) / FULL_TURN_DEGREES);
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Copy a feature collection with every position placed inside bounds that
|
|
126
|
+
* `findFittingBounds` built from it (see `placeLongitudeInBounds`), so an
|
|
127
|
+
* outline across the 180° line is drawn in one piece on a flat map.
|
|
128
|
+
*
|
|
129
|
+
* @param collection - The features.
|
|
130
|
+
* @param options - The bounds.
|
|
131
|
+
* @returns A new collection; the original is untouched.
|
|
132
|
+
*/
|
|
133
|
+
export function placeCollectionInBounds(collection, options) {
|
|
134
|
+
return mapCollectionLongitudes(collection, { moveLongitude: (longitude) => placeLongitudeInBounds(longitude, { bounds: options.bounds }) });
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* Copy a feature collection with every position's longitude moved a whole
|
|
138
|
+
* number of turns east (west when negative), the same meridians on another
|
|
139
|
+
* copy of the world.
|
|
140
|
+
*
|
|
141
|
+
* @param collection - The features.
|
|
142
|
+
* @param options - How many turns to move: a whole number.
|
|
143
|
+
* @returns A new collection; the original is untouched.
|
|
144
|
+
* @throws Error when `turns` is not a whole number, since part of a turn
|
|
145
|
+
* would land on other meridians, not a copy of the same ones.
|
|
146
|
+
*/
|
|
147
|
+
export function moveCollectionByTurns(collection, options) {
|
|
148
|
+
if (!Number.isInteger(options.turns)) {
|
|
149
|
+
throw new Error(`moveCollectionByTurns: expected turns to be a whole number, found ${options.turns}.`);
|
|
150
|
+
}
|
|
151
|
+
return mapCollectionLongitudes(collection, { moveLongitude: (longitude) => longitude + options.turns * FULL_TURN_DEGREES });
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* Copy a feature collection with every position's longitude passed through a function.
|
|
155
|
+
*
|
|
156
|
+
* @param collection - The features.
|
|
157
|
+
* @param options - `moveLongitude` gives each position's new longitude from its old one.
|
|
158
|
+
* @returns A new collection; the original is untouched.
|
|
159
|
+
*/
|
|
160
|
+
export function mapCollectionLongitudes(collection, options) {
|
|
161
|
+
const { moveLongitude } = options;
|
|
162
|
+
const moveCoordinates = (coordinates) => {
|
|
163
|
+
if (!Array.isArray(coordinates))
|
|
164
|
+
return coordinates;
|
|
165
|
+
if (typeof coordinates[0] === "number" && typeof coordinates[1] === "number") {
|
|
166
|
+
return [moveLongitude(coordinates[0]), ...coordinates.slice(1)];
|
|
167
|
+
}
|
|
168
|
+
return coordinates.map(moveCoordinates);
|
|
169
|
+
};
|
|
170
|
+
const moveGeometry = (geometry) => {
|
|
171
|
+
if (geometry === null)
|
|
172
|
+
return null;
|
|
173
|
+
if (geometry.type === "GeometryCollection") {
|
|
174
|
+
return { ...geometry, geometries: (geometry.geometries ?? []).map((part) => moveGeometry(part)) };
|
|
175
|
+
}
|
|
176
|
+
return { ...geometry, coordinates: moveCoordinates(geometry.coordinates) };
|
|
177
|
+
};
|
|
178
|
+
return { ...collection, features: collection.features.map((feature) => ({ ...feature, geometry: moveGeometry(feature.geometry) })) };
|
|
179
|
+
}
|
|
180
|
+
/**
|
|
181
|
+
* List every position in a feature collection.
|
|
182
|
+
*
|
|
183
|
+
* @param collection - The features.
|
|
184
|
+
* @returns [longitude, latitude] pairs.
|
|
185
|
+
*/
|
|
186
|
+
export function listPositions(collection) {
|
|
187
|
+
const positions = [];
|
|
188
|
+
const visit = (geometry) => {
|
|
189
|
+
if (geometry === null)
|
|
190
|
+
return;
|
|
191
|
+
if (geometry.type === "GeometryCollection")
|
|
192
|
+
for (const part of geometry.geometries ?? [])
|
|
193
|
+
visit(part);
|
|
194
|
+
else
|
|
195
|
+
collectPositions(geometry.coordinates, positions);
|
|
196
|
+
};
|
|
197
|
+
for (const feature of collection.features)
|
|
198
|
+
visit(feature.geometry);
|
|
199
|
+
return positions;
|
|
200
|
+
}
|
|
201
|
+
/**
|
|
202
|
+
* Points along the great circle between two places, so a line follows the
|
|
203
|
+
* curve of the earth (it bends on a flat map, and hugs the globe).
|
|
204
|
+
*
|
|
205
|
+
* @param from - [longitude, latitude].
|
|
206
|
+
* @param options - Where it goes, and how many points to use.
|
|
207
|
+
* @returns The arc's positions, from start to end.
|
|
208
|
+
*/
|
|
209
|
+
export function buildGreatCircleArc(from, options) {
|
|
210
|
+
const pointCount = options.pointCount ?? ARC_POINTS;
|
|
211
|
+
const [longitude1, latitude1] = from.map((degrees) => degrees * DEGREES_TO_RADIANS);
|
|
212
|
+
const [longitude2, latitude2] = options.to.map((degrees) => degrees * DEGREES_TO_RADIANS);
|
|
213
|
+
const distance = 2 * Math.asin(Math.sqrt(Math.sin((latitude2 - latitude1) / 2) ** 2 + Math.cos(latitude1) * Math.cos(latitude2) * Math.sin((longitude2 - longitude1) / 2) ** 2));
|
|
214
|
+
if (distance === 0)
|
|
215
|
+
return [from, options.to];
|
|
216
|
+
const positions = [];
|
|
217
|
+
for (let index = 0; index <= pointCount; index += 1) {
|
|
218
|
+
const fraction = index / pointCount;
|
|
219
|
+
const a = Math.sin((1 - fraction) * distance) / Math.sin(distance);
|
|
220
|
+
const b = Math.sin(fraction * distance) / Math.sin(distance);
|
|
221
|
+
const x = a * Math.cos(latitude1) * Math.cos(longitude1) + b * Math.cos(latitude2) * Math.cos(longitude2);
|
|
222
|
+
const y = a * Math.cos(latitude1) * Math.sin(longitude1) + b * Math.cos(latitude2) * Math.sin(longitude2);
|
|
223
|
+
const z = a * Math.sin(latitude1) + b * Math.sin(latitude2);
|
|
224
|
+
positions.push([Math.atan2(y, x) / DEGREES_TO_RADIANS, Math.atan2(z, Math.sqrt(x * x + y * y)) / DEGREES_TO_RADIANS]);
|
|
225
|
+
}
|
|
226
|
+
// Keep longitudes continuous across the antimeridian, so the line does not jump.
|
|
227
|
+
for (let index = 1; index < positions.length; index += 1) {
|
|
228
|
+
const previous = positions[index - 1][0];
|
|
229
|
+
const current = positions[index];
|
|
230
|
+
while (current[0] - previous > 180)
|
|
231
|
+
current[0] -= 360;
|
|
232
|
+
while (current[0] - previous < -180)
|
|
233
|
+
current[0] += 360;
|
|
234
|
+
}
|
|
235
|
+
return positions;
|
|
236
|
+
}
|
|
237
|
+
/**
|
|
238
|
+
* Read a feature's property by name, among its own properties only: a
|
|
239
|
+
* property name like "constructor" would otherwise find Object's member.
|
|
240
|
+
*
|
|
241
|
+
* @param feature - The feature.
|
|
242
|
+
* @param options - The property's name.
|
|
243
|
+
* @returns Its value, or undefined when the feature has no such property.
|
|
244
|
+
*/
|
|
245
|
+
export function findFeatureProperty(feature, options) {
|
|
246
|
+
const properties = feature.properties;
|
|
247
|
+
return properties !== null && properties !== undefined && Object.hasOwn(properties, options.property) ? properties[options.property] : undefined;
|
|
248
|
+
}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which table rows a regions layer's outlines join to. One rule, read by the
|
|
3
|
+
* map model to colour each outline and by validation to count the colour
|
|
4
|
+
* categories drawn, so a figure is never judged on rows the map would not draw.
|
|
5
|
+
*/
|
|
6
|
+
import { type Feature, type FeatureCollection } from "./geojson.ts";
|
|
7
|
+
/**
|
|
8
|
+
* Name an outline as the join reads it: its feature property, or its place when it has none.
|
|
9
|
+
*
|
|
10
|
+
* @param feature - The outline.
|
|
11
|
+
* @param options - The feature property that names regions, and the outline's index among the features.
|
|
12
|
+
* @returns The region's name.
|
|
13
|
+
*/
|
|
14
|
+
export declare function nameRegion(feature: Feature, options: {
|
|
15
|
+
featureProperty: string;
|
|
16
|
+
index: number;
|
|
17
|
+
}): string;
|
|
18
|
+
/**
|
|
19
|
+
* Turn a region name into the form the join matches on: trimmed, any case.
|
|
20
|
+
*
|
|
21
|
+
* @param name - A region name, from an outline or a key column.
|
|
22
|
+
* @returns The name to match on.
|
|
23
|
+
*/
|
|
24
|
+
export declare function trimAndLowerCaseRegionName(name: string): string;
|
|
25
|
+
/**
|
|
26
|
+
* Join a regions layer's key column to its outlines. Each outline joins to
|
|
27
|
+
* the last row naming it, so an earlier row repeating the name is never drawn.
|
|
28
|
+
*
|
|
29
|
+
* @param geojson - The outlines.
|
|
30
|
+
* @param options - The key column's values, and the feature property that names regions.
|
|
31
|
+
* @returns The outline names, the row each name joins to, and the rows drawn (those an outline joins to).
|
|
32
|
+
*/
|
|
33
|
+
export declare function joinRegionRows(geojson: FeatureCollection, options: {
|
|
34
|
+
keys: readonly (number | string | null)[];
|
|
35
|
+
featureProperty: string;
|
|
36
|
+
}): {
|
|
37
|
+
outlineNames: Set<string>;
|
|
38
|
+
rowByName: Map<string, number>;
|
|
39
|
+
joinedRows: Set<number>;
|
|
40
|
+
};
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which table rows a regions layer's outlines join to. One rule, read by the
|
|
3
|
+
* map model to colour each outline and by validation to count the colour
|
|
4
|
+
* categories drawn, so a figure is never judged on rows the map would not draw.
|
|
5
|
+
*/
|
|
6
|
+
import { findFeatureProperty } from "./geojson.js";
|
|
7
|
+
/**
|
|
8
|
+
* Name an outline as the join reads it: its feature property, or its place when it has none.
|
|
9
|
+
*
|
|
10
|
+
* @param feature - The outline.
|
|
11
|
+
* @param options - The feature property that names regions, and the outline's index among the features.
|
|
12
|
+
* @returns The region's name.
|
|
13
|
+
*/
|
|
14
|
+
export function nameRegion(feature, options) {
|
|
15
|
+
return String(findFeatureProperty(feature, { property: options.featureProperty }) ?? `region ${options.index + 1}`);
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Turn a region name into the form the join matches on: trimmed, any case.
|
|
19
|
+
*
|
|
20
|
+
* @param name - A region name, from an outline or a key column.
|
|
21
|
+
* @returns The name to match on.
|
|
22
|
+
*/
|
|
23
|
+
export function trimAndLowerCaseRegionName(name) {
|
|
24
|
+
return name.trim().toLowerCase();
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Join a regions layer's key column to its outlines. Each outline joins to
|
|
28
|
+
* the last row naming it, so an earlier row repeating the name is never drawn.
|
|
29
|
+
*
|
|
30
|
+
* @param geojson - The outlines.
|
|
31
|
+
* @param options - The key column's values, and the feature property that names regions.
|
|
32
|
+
* @returns The outline names, the row each name joins to, and the rows drawn (those an outline joins to).
|
|
33
|
+
*/
|
|
34
|
+
export function joinRegionRows(geojson, options) {
|
|
35
|
+
const outlineNames = new Set(geojson.features.map((feature, index) => trimAndLowerCaseRegionName(nameRegion(feature, { featureProperty: options.featureProperty, index }))));
|
|
36
|
+
const rowByName = new Map();
|
|
37
|
+
options.keys.forEach((key, row) => { if (key !== null && key !== undefined)
|
|
38
|
+
rowByName.set(trimAndLowerCaseRegionName(String(key)), row); });
|
|
39
|
+
const joinedRows = new Set();
|
|
40
|
+
for (const [name, row] of rowByName) {
|
|
41
|
+
if (outlineNames.has(name))
|
|
42
|
+
joinedRows.add(row);
|
|
43
|
+
}
|
|
44
|
+
return { outlineNames, rowByName, joinedRows };
|
|
45
|
+
}
|