@buildcanada/charts 0.1.0

package/src/grapher/mapCharts/GeoFeatures.ts

@@ -0,0 +1,184 @@
+import * as topojson from "topojson-client"
+import {
+    GeoFeature,
+    GlobeRenderFeature,
+    MapRenderFeature,
+    RenderFeatureType,
+} from "./MapChartConstants"
+import { Bounds, lazy, MapRegionName, PointVector } from "../../utils/index.js"
+import { CanadaTopology } from "./CanadaTopology"
+import { MapTopology } from "./MapTopology"
+import { geoBounds, geoCentroid, geoPath } from "d3-geo"
+import { MAP_PROJECTIONS } from "./MapProjections"
+
+// Get the underlying geographical topology elements we're going to display
+export const GeoFeatures: GeoFeature[] = (
+    topojson.feature(
+        MapTopology as any,
+        MapTopology.objects.world as any
+    ) as any
+).features
+
+export const GeoFeaturesById = new Map(
+    GeoFeatures.map((feature) => [feature.id, feature])
+)
+
+// Canadian province features
+export const CanadaGeoFeatures: GeoFeature[] = (
+    topojson.feature(
+        CanadaTopology as any,
+        CanadaTopology.objects.canada as any
+    ) as any
+).features
+
+export const CanadaGeoFeaturesById = new Map(
+    CanadaGeoFeatures.map((feature) => [feature.id, feature])
+)
+
+// Get the svg path specification string for every feature
+const geoPathCache = new Map<MapRegionName, string[]>()
+const geoPathsFor = (regionName: MapRegionName): string[] => {
+    if (geoPathCache.has(regionName)) return geoPathCache.get(regionName)!
+
+    const projectionGeo = geoPath()
+        .digits(1)
+        .projection(MAP_PROJECTIONS[regionName])
+    const strs = GeoFeatures.map((feature) => projectionGeo(feature) ?? "")
+
+    geoPathCache.set(regionName, strs)
+    return geoPathCache.get(regionName)!
+}
+
+// Get the bounding box for every geographical feature
+const geoBoundsCache = new Map<MapRegionName, Bounds[]>()
+const geoBoundsFor = (regionName: MapRegionName): Bounds[] => {
+    if (geoBoundsCache.has(regionName)) return geoBoundsCache.get(regionName)!
+
+    const projectionGeo = geoPath().projection(MAP_PROJECTIONS[regionName])
+    const bounds = GeoFeatures.map((feature) => {
+        const corners = projectionGeo.bounds(feature)
+
+        const bounds = Bounds.fromCorners(
+            new PointVector(...corners[0]),
+            new PointVector(...corners[1])
+        )
+
+        // HACK (Mispy): The path generator calculates weird bounds for Fiji (probably it wraps around the map)
+        if (feature.id === "Fiji")
+            return bounds.set({
+                x: bounds.right - bounds.height,
+                width: bounds.height,
+            })
+
+        return bounds
+    })
+
+    geoBoundsCache.set(regionName, bounds)
+    return geoBoundsCache.get(regionName)!
+}
+
+const geoCentroidsForFeatures = GeoFeatures.map((feature) =>
+    geoCentroid(feature.geometry)
+)
+
+const geoBoundsForFeatures = GeoFeatures.map((feature) => {
+    const corners = geoBounds(feature)
+    return Bounds.fromCorners(
+        new PointVector(...corners[0]),
+        new PointVector(...corners[1])
+    )
+})
+
+// Canada-specific computed values
+const canadaGeoCentroidsForFeatures = CanadaGeoFeatures.map((feature) =>
+    geoCentroid(feature.geometry)
+)
+
+const canadaGeoBoundsForFeatures = CanadaGeoFeatures.map((feature) => {
+    const corners = geoBounds(feature)
+    return Bounds.fromCorners(
+        new PointVector(...corners[0]),
+        new PointVector(...corners[1])
+    )
+})
+
+// Canada-specific path and bounds functions
+const canadaGeoPathsFor = (): string[] => {
+    const projectionGeo = geoPath()
+        .digits(1)
+        .projection(MAP_PROJECTIONS[MapRegionName.Canada])
+    return CanadaGeoFeatures.map((feature) => projectionGeo(feature) ?? "")
+}
+
+const canadaGeoBoundsFor = (): Bounds[] => {
+    const projectionGeo = geoPath().projection(MAP_PROJECTIONS[MapRegionName.Canada])
+    return CanadaGeoFeatures.map((feature) => {
+        const corners = projectionGeo.bounds(feature)
+        return Bounds.fromCorners(
+            new PointVector(...corners[0]),
+            new PointVector(...corners[1])
+        )
+    })
+}
+
+const geoFeaturesForMapCache = new Map<MapRegionName, MapRenderFeature[]>()
+export const getGeoFeaturesForMap = (
+    regionName: MapRegionName
+): MapRenderFeature[] => {
+    if (geoFeaturesForMapCache.has(regionName))
+        return geoFeaturesForMapCache.get(regionName)!
+
+    // Handle Canada region separately using Canadian province features
+    if (regionName === MapRegionName.Canada) {
+        const projBounds = canadaGeoBoundsFor()
+        const projPaths = canadaGeoPathsFor()
+
+        const features = CanadaGeoFeatures.map((geo, index) => ({
+            type: RenderFeatureType.Map,
+            id: geo.id as string,
+            geo: geo,
+            projBounds: projBounds[index],
+            geoBounds: canadaGeoBoundsForFeatures[index],
+            geoCentroid: canadaGeoCentroidsForFeatures[index],
+            path: projPaths[index],
+        })) satisfies MapRenderFeature[]
+
+        geoFeaturesForMapCache.set(regionName, features)
+        return geoFeaturesForMapCache.get(regionName)!
+    }
+
+    const projBounds = geoBoundsFor(regionName)
+    const projPaths = geoPathsFor(regionName)
+
+    const features = (
+        GeoFeatures.map((geo, index) => ({
+            type: RenderFeatureType.Map,
+            id: geo.id as string,
+            geo: geo,
+            projBounds: projBounds[index], // projected
+            geoBounds: geoBoundsForFeatures[index], // unprojected
+            geoCentroid: geoCentroidsForFeatures[index], // unprojected
+            path: projPaths[index],
+        })) satisfies MapRenderFeature[]
+    ).filter((feature) => feature.id !== "Antarctica") // exclude Antarctica since it's distorted and uses up too much space
+
+    geoFeaturesForMapCache.set(regionName, features)
+    return geoFeaturesForMapCache.get(regionName)!
+}
+
+export const getGeoFeaturesForGlobe = lazy((): GlobeRenderFeature[] => {
+    return GeoFeatures.map((geo, index) => {
+        const corners = geoBounds(geo)
+        const bounds = Bounds.fromCorners(
+            new PointVector(...corners[0]),
+            new PointVector(...corners[1])
+        )
+        return {
+            type: RenderFeatureType.Globe,
+            id: geo.id as string,
+            geo: geo,
+            geoCentroid: geoCentroidsForFeatures[index],
+            geoBounds: bounds,
+        }
+    }) satisfies GlobeRenderFeature[]
+})

package/src/grapher/mapCharts/GlobeController.ts

@@ -0,0 +1,496 @@
+import { FeatureCollection } from "geojson"
+import { geoInterpolate, geoOrthographic, geoPath } from "d3-geo"
+import { interpolateNumber } from "d3-interpolate"
+import { easeCubicOut } from "d3-ease"
+import * as R from "remeda"
+import { EntityName, GlobeConfig, GlobeRegionName } from "../../types/index.js"
+import {
+    Bounds,
+    excludeUndefined,
+    PartialBy,
+    PointVector,
+    checkIsOwidContinent,
+    getCountryNamesForRegion,
+    getRegionByName,
+    checkHasMembers,
+} from "../../utils/index.js"
+import { MapConfig } from "./MapConfig"
+import { getGeoFeaturesForGlobe } from "./GeoFeatures"
+import {
+    DEFAULT_GLOBE_ROTATION,
+    DEFAULT_GLOBE_ROTATIONS_FOR_TIME,
+    DEFAULT_GLOBE_SIZE,
+    GeoFeature,
+    GLOBE_COUNTRY_ZOOM,
+    GLOBE_LATITUDE_MAX,
+    GLOBE_LATITUDE_MIN,
+    GLOBE_MAX_ZOOM,
+    GLOBE_MIN_ZOOM,
+    GLOBE_VIEWPORTS,
+    GlobeRenderFeature,
+    MAP_REGION_NAMES,
+} from "./MapChartConstants"
+import { isPointPlacedOnVisibleHemisphere } from "./MapHelpers"
+import { ckmeans } from "simple-statistics"
+import { MapSelectionArray } from "../selection/MapSelectionArray"
+import { center } from "@turf/center"
+import { action } from "mobx"
+
+const geoFeaturesById = new Map<string, GlobeRenderFeature>(
+    getGeoFeaturesForGlobe().map((f: GlobeRenderFeature) => [f.id, f])
+)
+
+const LONGITUDE_OFFSET = 40
+const ANIMATION_DURATION = 600
+
+interface Target {
+    coords: [number, number]
+    zoom: number
+}
+
+interface GlobeControllerManager {
+    mapConfig: MapConfig
+}
+
+export class GlobeController {
+    private manager: GlobeControllerManager
+
+    constructor(manager: GlobeControllerManager) {
+        this.manager = manager
+    }
+
+    private get globeConfig(): GlobeConfig {
+        return this.manager.mapConfig.globe
+    }
+
+    @action.bound showGlobe(): void {
+        this.globeConfig.isActive = true
+    }
+
+    @action.bound hideGlobe(): void {
+        this.globeConfig.isActive = false
+    }
+
+    @action.bound toggleGlobe(): void {
+        this.globeConfig.isActive = !this.globeConfig.isActive
+    }
+
+    @action.bound resetGlobe(): void {
+        this.globeConfig.rotation = DEFAULT_GLOBE_ROTATION
+        this.globeConfig.zoom = 1
+        this.globeConfig.focusCountry = undefined
+    }
+
+    @action.bound setFocusCountry(country: EntityName): void {
+        this.globeConfig.focusCountry = country
+    }
+
+    @action.bound dismissCountryFocus(): void {
+        this.globeConfig.focusCountry = undefined
+    }
+
+    @action.bound private jumpTo(target: Partial<Target>): void {
+        if (target.coords) this.globeConfig.rotation = target.coords
+        if (target.zoom) this.globeConfig.zoom = target.zoom
+    }
+
+    private showGlobeAndRotateTo(target: Target): void {
+        // if the globe isn't currently shown, jump to the offset position
+        // before switching to it so that rotating is predictable
+        if (!this.globeConfig.isActive) {
+            this.jumpTo({ coords: addLongitudeOffset(target.coords) })
+            this.showGlobe()
+        }
+
+        void this.rotateTo(target)
+    }
+
+    jumpToOwidContinent(continent: GlobeRegionName): void {
+        const target = calculateTargetForOwidContinent(continent)
+        this.jumpTo(target)
+    }
+
+    rotateToCountry(country: EntityName, zoom?: number): void {
+        const target = calculateTargetForCountry(country, zoom)
+        if (target) this.showGlobeAndRotateTo(target)
+    }
+
+    rotateToOwidContinent(continent: GlobeRegionName): void {
+        const target = calculateTargetForOwidContinent(continent)
+        this.showGlobeAndRotateTo(target)
+    }
+
+    rotateToDefaultBasedOnTime(): void {
+        const target = calculateTargetBasedOnTime()
+        this.showGlobeAndRotateTo(target)
+    }
+
+    rotateToSelection(): void {
+        const target = calculateTargetForSelection(
+            this.manager.mapConfig.selection
+        )
+        if (target) this.showGlobeAndRotateTo(target)
+    }
+
+    rotateToRegion(regionName: string): void {
+        const target = calculateTargetForRegion(regionName)
+        if (target) this.showGlobeAndRotateTo(target)
+    }
+
+    private currentAnimation?: AbortController
+    private async rotateTo(target: PartialBy<Target, "zoom">): Promise<void> {
+        // cancel any ongoing rotation
+        if (this.currentAnimation) {
+            this.currentAnimation.abort()
+            this.currentAnimation = undefined
+        }
+
+        // set up a new abort controller
+        const controller = new AbortController()
+        this.currentAnimation = controller
+
+        try {
+            await this._rotateTo(controller.signal, target.coords, target.zoom)
+        } catch {
+            // aborted
+        } finally {
+            if (this.currentAnimation === controller) {
+                this.currentAnimation = undefined
+            }
+        }
+    }
+
+    private async _rotateTo(
+        signal: AbortSignal,
+        targetCoords: [number, number],
+        targetZoom?: number
+    ): Promise<void> {
+        const currentCoords = this.globeConfig.rotation
+        const animatedCoords = geoInterpolate(currentCoords, targetCoords)
+
+        const currentZoom = this.globeConfig.zoom
+        const animatedZoom =
+            targetZoom !== undefined
+                ? interpolateNumber(currentZoom, targetZoom)
+                : undefined
+
+        const animPromise = new Promise<void>((resolve, reject) => {
+            const now = Date.now()
+            const step = action((): void => {
+                const elapsed = Date.now() - now
+                const t = Math.min(1, elapsed / ANIMATION_DURATION)
+
+                // Check if the animation was canceled
+                if (signal.aborted) {
+                    reject()
+                    return
+                }
+
+                // animate globe rotation
+                this.globeConfig.rotation = animatedCoords(easeCubicOut(t))
+
+                // animate zoom
+                if (animatedZoom)
+                    this.globeConfig.zoom = animatedZoom(easeCubicOut(t))
+
+                if (t < 1) {
+                    requestAnimationFrame(step)
+                } else {
+                    resolve()
+                }
+            })
+            requestAnimationFrame(step)
+        })
+
+        await animPromise
+            .catch(() => {
+                // ignore
+            })
+            .then(
+                action(() => {
+                    // ensure we end exactly at the target values
+                    this.globeConfig.rotation = targetCoords
+                    if (targetZoom !== undefined)
+                        this.globeConfig.zoom = targetZoom
+                })
+            )
+    }
+}
+
+function calculateTargetForCountry(
+    country: EntityName,
+    zoom?: number
+): Target | undefined {
+    const geoFeature = geoFeaturesById.get(country)
+    if (!geoFeature) return
+
+    const coords: [number, number] = [
+        geoFeature.geoCentroid[0],
+        R.clamp(geoFeature.geoCentroid[1], {
+            min: GLOBE_LATITUDE_MIN,
+            max: GLOBE_LATITUDE_MAX,
+        }),
+    ]
+
+    // make sure the whole country is visible after zooming
+    const zoomToFit = calculateZoomToFitForGeoFeature(geoFeature.geo)
+    const targetZoom = Math.min(zoom ?? GLOBE_COUNTRY_ZOOM, zoomToFit)
+
+    return { coords, zoom: targetZoom }
+}
+
+function calculateZoomToFitForGeoFeature(geoFeature: GeoFeature): number {
+    const centerPoint = getCenterPoint(geoFeature)
+    const projection = geoOrthographic().rotate(negateCoords(centerPoint))
+
+    const corners = geoPath().projection(projection).bounds(geoFeature)
+    const bounds = Bounds.fromCorners(
+        new PointVector(...corners[0]),
+        new PointVector(...corners[1])
+    )
+
+    return calculateZoomToFitForBounds(bounds)
+}
+
+function calculateZoomToFitForBounds(bounds: Bounds): number {
+    // calculate the zoom needed for the bounds to be visible
+    let zoom = Math.min(
+        DEFAULT_GLOBE_SIZE / bounds.width,
+        DEFAULT_GLOBE_SIZE / bounds.height
+    )
+    if (Number.isNaN(zoom)) zoom = 1
+
+    // it's nicer to have a bit of padding around the zoomed-to area
+    zoom = zoom - 0.05
+
+    // clamp the zoom to the allowed range
+    zoom = R.clamp(zoom, { min: GLOBE_MIN_ZOOM, max: GLOBE_MAX_ZOOM })
+
+    return zoom
+}
+
+function calculateTargetForOwidContinent(continent: GlobeRegionName): Target {
+    const viewport = GLOBE_VIEWPORTS[continent]
+    return { coords: viewport.rotation, zoom: viewport.zoom }
+}
+
+function calculateTargetBasedOnTime(): Target {
+    const coords = getCoordsBasedOnTime()
+    return { coords, zoom: 1 }
+}
+
+function calculateTargetForRegion(regionName: string): Target | undefined {
+    const region = getRegionByName(regionName)
+    if (!region || !checkHasMembers(region)) return
+    const countryNames = getCountryNamesForRegion(region)
+    return calculateTargetForCountryCollection(countryNames)
+}
+
+function calculateTargetForSelection(
+    selection: MapSelectionArray
+): Target | undefined {
+    // if at least one country is selected, then rotate to the countries (and ignore the regions)
+    if (selection.selectedCountryNamesInForeground.length > 0) {
+        return calculateTargetForCountryCollection(
+            selection.selectedCountryNamesInForeground
+        )
+    }
+
+    // if a single owid continent is selected, then rotate to it
+    // (the hard-coded coords/zoom values are nicer than dynamically computing it)
+    if (
+        selection.selectedRegions.length === 1 &&
+        checkIsOwidContinent(selection.selectedRegions[0])
+    ) {
+        return calculateTargetForOwidContinent(
+            MAP_REGION_NAMES[
+                selection.selectedRegions[0].name
+            ] as GlobeRegionName
+        )
+    }
+
+    // rotate and zoom to all countries in the selected regions
+    const countryNames = [
+        ...selection.selectedCountryNamesInForeground,
+        ...selection.countryNamesForSelectedRegions,
+    ]
+    return calculateTargetForCountryCollection(countryNames)
+}
+
+function calculateTargetForCountryCollection(
+    countryNames: string[]
+): Target | undefined {
+    // early return if the selection is empty or a single country is selected
+    if (countryNames.length === 0) return
+    if (countryNames.length === 1) {
+        return calculateTargetForCountry(countryNames[0])
+    }
+
+    // find a subset of countries that can be shown on the globe,
+    // e.g. if 'Mexico', 'Guatemala' and 'Australia' are selected, then
+    // 'Australia' is dropped as it's on the opposite site from South America
+    const visibleCountries = findVisibleCountrySubset(countryNames)
+
+    // early return if no country or a single country is visible
+    if (visibleCountries.length === 0) return
+    if (visibleCountries.length === 1) {
+        return calculateTargetForCountry(visibleCountries[0])
+    }
+
+    // calculate target coords and zoom for two or more countries
+    return getCoordsAndZoomForCountryCollection(visibleCountries)
+}
+
+function getCoordsBasedOnTime(): [number, number] {
+    const date = new Date()
+    const hours = date.getUTCHours()
+
+    if (hours <= 7) {
+        return DEFAULT_GLOBE_ROTATIONS_FOR_TIME.UTC_MORNING
+    } else if (hours <= 15) {
+        return DEFAULT_GLOBE_ROTATIONS_FOR_TIME.UTC_MIDDAY
+    } else {
+        return DEFAULT_GLOBE_ROTATIONS_FOR_TIME.UTC_EVENING
+    }
+}
+
+function getCenterForCountryCollection(
+    countryNames: string[]
+): [number, number] {
+    const featureCollection = makeFeatureCollectionForCountries(countryNames)
+    return getCenterPoint(featureCollection)
+}
+
+function getCenterPoint(
+    geojson: GeoFeature | FeatureCollection
+): [number, number] {
+    const centerPoint = center(geojson)
+
+    return [
+        centerPoint.geometry.coordinates[0],
+        R.clamp(centerPoint.geometry.coordinates[1], {
+            min: GLOBE_LATITUDE_MIN,
+            max: GLOBE_LATITUDE_MAX,
+        }),
+    ]
+}
+
+function getCoordsAndZoomForCountryCollection(countryNames: string[]): {
+    coords: [number, number]
+    zoom: number
+} {
+    const centerPoint = getCenterForCountryCollection(countryNames)
+    const projection = geoOrthographic().rotate(negateCoords(centerPoint))
+
+    const bounds = excludeUndefined(
+        countryNames.map((countryName) => {
+            const feature = geoFeaturesById.get(countryName)
+            if (!feature) return
+            const corners = geoPath().projection(projection).bounds(feature.geo)
+            if (corners[0][0] === Number.POSITIVE_INFINITY) return
+            return Bounds.fromCorners(
+                new PointVector(...corners[0]),
+                new PointVector(...corners[1])
+            )
+        })
+    )
+
+    // merge bounds and calculate the zoom needed for the countries to be visible
+    const mergedBounds = Bounds.merge(bounds)
+    const zoom = calculateZoomToFitForBounds(mergedBounds)
+
+    return { coords: centerPoint, zoom }
+}
+
+function findVisibleCountrySubset(countryNames: string[]): string[] {
+    // rotate the globe to the center point of all given countries,
+    // and find all countries that are then visible on the globe
+    const centerPoint = getCenterForCountryCollection(countryNames)
+    const projection = geoOrthographic().rotate(negateCoords(centerPoint))
+    const visibleCountries = countryNames.filter((countryName) => {
+        const feature = geoFeaturesById.get(countryName)
+        if (!feature) return false
+
+        // check if the centroid is visible
+        const isCentroidVisible = isPointPlacedOnVisibleHemisphere(
+            feature.geoCentroid,
+            centerPoint
+        )
+        if (!isCentroidVisible) return false
+
+        // if the centroid is visible, then also check if the bounds are
+        // visible (if they're infinite, then they're not)
+        const corners = geoPath().projection(projection).bounds(feature.geo)
+        if (corners[0][0] === Number.POSITIVE_INFINITY) return false
+
+        return true
+    })
+
+    // it's possible for no country to be visible if the countries are on opposite
+    // sides from the globe. in that case, we need to drop a subset of countries
+    if (visibleCountries.length === 0) {
+        // cluster countries into two groups based on their centroid longitude
+        const clusters = clusterCountriesByCentroidLongitude(countryNames)
+
+        // keep the bigger cluster
+        // (if both clusters have the same number of countries, keep any)
+        return clusters[0].length > clusters[1].length
+            ? clusters[0]
+            : clusters[1]
+    }
+
+    return visibleCountries
+}
+
+function clusterCountriesByCentroidLongitude(
+    countryNames: string[]
+): string[][] {
+    const nameToLon: Record<string, number> = {}
+    const lonToName: Record<number, string> = {}
+
+    // map country names to their centroid's longitude and vice versa
+    // (assumes that no two countries have the same longitude)
+    countryNames.forEach((countryName) => {
+        const feature = geoFeaturesById.get(countryName)
+        if (!feature) return
+
+        const lon = R.round(feature.geoCentroid[0], 5)
+        nameToLon[countryName] = lon
+        lonToName[lon] = countryName
+    })
+
+    // cluster longitudes into two groups
+    const clusters = ckmeans(
+        excludeUndefined(countryNames.map((name) => nameToLon[name])),
+        2
+    )
+
+    // map longitudes back to country names
+    return clusters.map((cluster) =>
+        cluster.map((centroidLon) => lonToName[centroidLon])
+    )
+}
+
+function makeFeatureCollectionForCountries(
+    countryNames: string[]
+): FeatureCollection {
+    const features = excludeUndefined(
+        countryNames.map((name) => geoFeaturesById.get(name))
+    )
+
+    return {
+        type: "FeatureCollection",
+        features: features.map((feature) => feature.geo),
+    }
+}
+
+function addLongitudeOffset(
+    coords: [number, number],
+    offset = LONGITUDE_OFFSET
+): [number, number] {
+    return [coords[0] + offset, coords[1]]
+}
+
+function negateCoords(coords: [number, number]): [number, number] {
+    return [-coords[0], -coords[1]]
+}