@mui/x-charts-premium 9.6.0 → 9.8.0

package/Map/MapImagePlot.js

@@ -0,0 +1,138 @@
+"use strict";
+'use client';
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MapImagePlot = MapImagePlot;
+var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
+var _objectWithoutPropertiesLoose2 = _interopRequireDefault(require("@babel/runtime/helpers/objectWithoutPropertiesLoose"));
+var React = _interopRequireWildcard(require("react"));
+var _propTypes = _interopRequireDefault(require("prop-types"));
+var _hooks = require("@mui/x-charts/hooks");
+var _useGeoPath = require("../hooks/useGeoPath");
+var _reprojectEquirectangularImage = require("./reprojectEquirectangularImage");
+var _jsxRuntime = require("react/jsx-runtime");
+const _excluded = ["href", "imageBounds", "onReady"];
+const FULL_GLOBE = [[-180, -90], [180, 90]];
+/**
+ * Renders a raster base map (for example a satellite mosaic) under the series,
+ * reprojected to match the chart's `projection` so it follows the geography
+ * instead of being a flat rectangle. Pixels outside the projection's visible
+ * footprint are left transparent.
+ *
+ * The source image is loaded only when `href` changes; changing the projection or
+ * resizing reuses the decoded image and only re-runs the (synchronous) canvas
+ * reprojection.
+ *
+ * The source image is assumed to be equirectangular; use `imageBounds` when it
+ * does not cover the whole globe. Any other SVG image attribute is forwarded to
+ * the underlying element.
+ */
+function MapImagePlot(props) {
+  const {
+      href,
+      imageBounds,
+      onReady
+    } = props,
+    other = (0, _objectWithoutPropertiesLoose2.default)(props, _excluded);
+  const path = (0, _useGeoPath.useGeoPath)();
+  const {
+    left,
+    top,
+    width,
+    height
+  } = (0, _hooks.useDrawingArea)();
+  const [image, setImage] = React.useState(null);
+  const [dataUrl, setDataUrl] = React.useState(null);
+  const projection = path?.projection?.();
+  const [[west, south], [east, north]] = imageBounds ?? FULL_GLOBE;
+
+  // Keep the latest `onReady` without making it a reprojection dependency.
+  const onReadyRef = React.useRef(onReady);
+  React.useEffect(() => {
+    onReadyRef.current = onReady;
+  });
+
+  // Load (decode) the source image only when `href` changes. Clearing the image
+  // first hides the now-stale raster until the new one is ready.
+  React.useEffect(() => {
+    setImage(null);
+    if (!href) {
+      return undefined;
+    }
+    let cancelled = false;
+    const nextImage = new Image();
+    nextImage.crossOrigin = 'anonymous';
+    nextImage.onload = () => {
+      if (!cancelled) {
+        setImage(nextImage);
+      }
+    };
+    nextImage.src = href;
+    return () => {
+      cancelled = true;
+    };
+  }, [href]);
+
+  // Reproject whenever the decoded image, projection, drawing area, or bounds
+  // change. This is synchronous, so switching projection does not reload `href`.
+  React.useEffect(() => {
+    if (!image || !projection || typeof projection.invert !== 'function' || width <= 0 || height <= 0) {
+      setDataUrl(null);
+      onReadyRef.current?.(null);
+      return;
+    }
+    const url = (0, _reprojectEquirectangularImage.reprojectEquirectangularImage)({
+      image,
+      projection,
+      area: {
+        left,
+        top,
+        width,
+        height
+      },
+      imageBounds: [[west, south], [east, north]]
+    });
+    setDataUrl(url);
+    onReadyRef.current?.(url);
+  }, [image, projection, left, top, width, height, west, south, east, north]);
+  if (!dataUrl) {
+    return null;
+  }
+
+  // Spread first so forwarded attributes can't override the computed geometry/href
+  // and break the alignment with the projection.
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)("image", (0, _extends2.default)({}, other, {
+    href: dataUrl,
+    x: left,
+    y: top,
+    width: width,
+    height: height
+  }));
+}
+process.env.NODE_ENV !== "production" ? MapImagePlot.propTypes /* remove-proptypes */ = {
+  // ----------------------------- Warning --------------------------------
+  // | These PropTypes are generated from the TypeScript type definitions |
+  // | To update them edit the TypeScript types and run "pnpm proptypes"  |
+  // ----------------------------------------------------------------------
+  /**
+   * URL of the image to render as the base map.
+   * Must be same-origin (or CORS-enabled) so it can be reprojected on a canvas.
+   */
+  href: _propTypes.default.string,
+  /**
+   * Geographic extent the source image covers, as `[[west, south], [east, north]]`.
+   * The image is assumed to be in the equirectangular (plate carrée) projection.
+   * If `west` is greater than `east`, the range wraps across the antimeridian.
+   * @default [[-180, -90], [180, 90]]
+   */
+  imageBounds: _propTypes.default.arrayOf(_propTypes.default.arrayOf(_propTypes.default.number.isRequired).isRequired),
+  /**
+   * Called after each reprojection.
+   * @param {string | null} dataUrl The reprojected raster as a data URL, or `null` when it could not be produced.
+   */
+  onReady: _propTypes.default.func
+} : void 0;

package/Map/MapImagePlot.mjs

@@ -0,0 +1,132 @@
+'use client';
+
+import _extends from "@babel/runtime/helpers/esm/extends";
+import _objectWithoutPropertiesLoose from "@babel/runtime/helpers/esm/objectWithoutPropertiesLoose";
+const _excluded = ["href", "imageBounds", "onReady"];
+import * as React from 'react';
+import PropTypes from 'prop-types';
+import { useDrawingArea } from '@mui/x-charts/hooks';
+import { useGeoPath } from "../hooks/useGeoPath.mjs";
+import { reprojectEquirectangularImage } from "./reprojectEquirectangularImage.mjs";
+import { jsx as _jsx } from "react/jsx-runtime";
+const FULL_GLOBE = [[-180, -90], [180, 90]];
+/**
+ * Renders a raster base map (for example a satellite mosaic) under the series,
+ * reprojected to match the chart's `projection` so it follows the geography
+ * instead of being a flat rectangle. Pixels outside the projection's visible
+ * footprint are left transparent.
+ *
+ * The source image is loaded only when `href` changes; changing the projection or
+ * resizing reuses the decoded image and only re-runs the (synchronous) canvas
+ * reprojection.
+ *
+ * The source image is assumed to be equirectangular; use `imageBounds` when it
+ * does not cover the whole globe. Any other SVG image attribute is forwarded to
+ * the underlying element.
+ */
+function MapImagePlot(props) {
+  const {
+      href,
+      imageBounds,
+      onReady
+    } = props,
+    other = _objectWithoutPropertiesLoose(props, _excluded);
+  const path = useGeoPath();
+  const {
+    left,
+    top,
+    width,
+    height
+  } = useDrawingArea();
+  const [image, setImage] = React.useState(null);
+  const [dataUrl, setDataUrl] = React.useState(null);
+  const projection = path?.projection?.();
+  const [[west, south], [east, north]] = imageBounds ?? FULL_GLOBE;
+
+  // Keep the latest `onReady` without making it a reprojection dependency.
+  const onReadyRef = React.useRef(onReady);
+  React.useEffect(() => {
+    onReadyRef.current = onReady;
+  });
+
+  // Load (decode) the source image only when `href` changes. Clearing the image
+  // first hides the now-stale raster until the new one is ready.
+  React.useEffect(() => {
+    setImage(null);
+    if (!href) {
+      return undefined;
+    }
+    let cancelled = false;
+    const nextImage = new Image();
+    nextImage.crossOrigin = 'anonymous';
+    nextImage.onload = () => {
+      if (!cancelled) {
+        setImage(nextImage);
+      }
+    };
+    nextImage.src = href;
+    return () => {
+      cancelled = true;
+    };
+  }, [href]);
+
+  // Reproject whenever the decoded image, projection, drawing area, or bounds
+  // change. This is synchronous, so switching projection does not reload `href`.
+  React.useEffect(() => {
+    if (!image || !projection || typeof projection.invert !== 'function' || width <= 0 || height <= 0) {
+      setDataUrl(null);
+      onReadyRef.current?.(null);
+      return;
+    }
+    const url = reprojectEquirectangularImage({
+      image,
+      projection,
+      area: {
+        left,
+        top,
+        width,
+        height
+      },
+      imageBounds: [[west, south], [east, north]]
+    });
+    setDataUrl(url);
+    onReadyRef.current?.(url);
+  }, [image, projection, left, top, width, height, west, south, east, north]);
+  if (!dataUrl) {
+    return null;
+  }
+
+  // Spread first so forwarded attributes can't override the computed geometry/href
+  // and break the alignment with the projection.
+  return /*#__PURE__*/_jsx("image", _extends({}, other, {
+    href: dataUrl,
+    x: left,
+    y: top,
+    width: width,
+    height: height
+  }));
+}
+process.env.NODE_ENV !== "production" ? MapImagePlot.propTypes /* remove-proptypes */ = {
+  // ----------------------------- Warning --------------------------------
+  // | These PropTypes are generated from the TypeScript type definitions |
+  // | To update them edit the TypeScript types and run "pnpm proptypes"  |
+  // ----------------------------------------------------------------------
+  /**
+   * URL of the image to render as the base map.
+   * Must be same-origin (or CORS-enabled) so it can be reprojected on a canvas.
+   */
+  href: PropTypes.string,
+  /**
+   * Geographic extent the source image covers, as `[[west, south], [east, north]]`.
+   * The image is assumed to be in the equirectangular (plate carrée) projection.
+   * If `west` is greater than `east`, the range wraps across the antimeridian.
+   * @default [[-180, -90], [180, 90]]
+   */
+  imageBounds: PropTypes.arrayOf(PropTypes.arrayOf(PropTypes.number.isRequired).isRequired),
+  /**
+   * Called after each reprojection.
+   * @param {string | null} dataUrl The reprojected raster as a data URL, or `null` when it could not be produced.
+   */
+  onReady: PropTypes.func
+} : void 0;
+export { MapImagePlot };

package/Map/MapShape.d.mts

@@ -1,8 +1,8 @@
 import * as React from 'react';
-import { type SeriesId } from '@mui/x-charts/internals';
+import type { SeriesId } from '@mui/x-charts/internals';
 export type MapShapeProps = Omit<React.SVGProps<SVGPathElement>, 'ref'> & {
   seriesId: SeriesId;
-  dataIndex: number;
+  featureName: string;
   d: string;
   color: string;
 };

package/Map/MapShape.d.ts

@@ -1,8 +1,8 @@
 import * as React from 'react';
-import { type SeriesId } from '@mui/x-charts/internals';
+import type { SeriesId } from '@mui/x-charts/internals';
 export type MapShapeProps = Omit<React.SVGProps<SVGPathElement>, 'ref'> & {
   seriesId: SeriesId;
-  dataIndex: number;
+  featureName: string;
   d: string;
   color: string;
 };

package/Map/MapShape.js

@@ -15,7 +15,7 @@ var _styles = require("@mui/material/styles");
 var _internals = require("@mui/x-charts/internals");
 var _hooks = require("../hooks");
 var _jsxRuntime = require("react/jsx-runtime");
-const _excluded = ["seriesId", "dataIndex", "d", "color", "onClick"];
+const _excluded = ["seriesId", "featureName", "d", "color", "onClick"];
 const MapShapeRoot = (0, _styles.styled)('path', {
   name: 'MuiMapShape',
   slot: 'Root'
@@ -27,7 +27,7 @@ const MapShapeRoot = (0, _styles.styled)('path', {
 function MapShape(props) {
   const {
       seriesId,
-      dataIndex,
+      featureName,
       d,
       color,
       onClick
@@ -36,8 +36,8 @@ function MapShape(props) {
   const identifier = React.useMemo(() => ({
     type: 'mapShape',
     seriesId,
-    dataIndex
-  }), [seriesId, dataIndex]);
+    name: featureName
+  }), [seriesId, featureName]);
   const interactionProps = (0, _internals.useInteractionItemProps)(identifier);
   const highlightState = (0, _hooks.useItemHighlightState)(identifier);
   const isHighlighted = highlightState === 'highlighted';
@@ -47,7 +47,7 @@ function MapShape(props) {
     fill: color,
     onClick: onClick,
     cursor: onClick ? 'pointer' : 'unset',
-    "data-index": dataIndex,
+    "data-name": featureName,
     "data-highlighted": isHighlighted || undefined,
     "data-faded": isFaded || undefined,
     filter: isHighlighted ? 'brightness(120%)' : undefined,
@@ -59,6 +59,6 @@ process.env.NODE_ENV !== "production" ? MapShape.propTypes /* remove-proptypes *
   // | These PropTypes are generated from the TypeScript type definitions |
   // | To update them edit the TypeScript types and run "pnpm proptypes"  |
   // ----------------------------------------------------------------------
-  dataIndex: _propTypes.default.number.isRequired,
+  featureName: _propTypes.default.string.isRequired,
   seriesId: _propTypes.default.string.isRequired
 } : void 0;

package/Map/MapShape.mjs

@@ -2,7 +2,7 @@
 
 import _extends from "@babel/runtime/helpers/esm/extends";
 import _objectWithoutPropertiesLoose from "@babel/runtime/helpers/esm/objectWithoutPropertiesLoose";
-const _excluded = ["seriesId", "dataIndex", "d", "color", "onClick"];
+const _excluded = ["seriesId", "featureName", "d", "color", "onClick"];
 import * as React from 'react';
 import PropTypes from 'prop-types';
 import { styled } from '@mui/material/styles';
@@ -20,7 +20,7 @@ const MapShapeRoot = styled('path', {
 function MapShape(props) {
   const {
       seriesId,
-      dataIndex,
+      featureName,
       d,
       color,
       onClick
@@ -29,8 +29,8 @@ function MapShape(props) {
   const identifier = React.useMemo(() => ({
     type: 'mapShape',
     seriesId,
-    dataIndex
-  }), [seriesId, dataIndex]);
+    name: featureName
+  }), [seriesId, featureName]);
   const interactionProps = useInteractionItemProps(identifier);
   const highlightState = useItemHighlightState(identifier);
   const isHighlighted = highlightState === 'highlighted';
@@ -40,7 +40,7 @@ function MapShape(props) {
     fill: color,
     onClick: onClick,
     cursor: onClick ? 'pointer' : 'unset',
-    "data-index": dataIndex,
+    "data-name": featureName,
     "data-highlighted": isHighlighted || undefined,
     "data-faded": isFaded || undefined,
     filter: isHighlighted ? 'brightness(120%)' : undefined,
@@ -52,7 +52,7 @@ process.env.NODE_ENV !== "production" ? MapShape.propTypes /* remove-proptypes *
   // | These PropTypes are generated from the TypeScript type definitions |
   // | To update them edit the TypeScript types and run "pnpm proptypes"  |
   // ----------------------------------------------------------------------
-  dataIndex: PropTypes.number.isRequired,
+  featureName: PropTypes.string.isRequired,
   seriesId: PropTypes.string.isRequired
 } : void 0;
 export { MapShape };

package/Map/MapShapePlot.d.mts

@@ -1,4 +1,12 @@
+import * as React from 'react';
+import type { MapShapeItemIdentifier } from "../models/seriesType/mapShape.mjs";
 export interface MapShapePlotProps {
+  /**
+   * Callback fired when clicking on a map shape.
+   * @param {React.MouseEvent<SVGPathElement, MouseEvent>} event The event source of the callback.
+   * @param {MapShapeItemIdentifier} mapShapeItemIdentifier The identifier of the clicked map shape.
+   */
+  onItemClick?: (event: React.MouseEvent<SVGPathElement, MouseEvent>, mapShapeItemIdentifier: MapShapeItemIdentifier) => void;
   className?: string;
   /**
    * Fill color applied to every feature path. Overrides item and series colors.

package/Map/MapShapePlot.d.ts

@@ -1,4 +1,12 @@
+import * as React from 'react';
+import type { MapShapeItemIdentifier } from "../models/seriesType/mapShape.js";
 export interface MapShapePlotProps {
+  /**
+   * Callback fired when clicking on a map shape.
+   * @param {React.MouseEvent<SVGPathElement, MouseEvent>} event The event source of the callback.
+   * @param {MapShapeItemIdentifier} mapShapeItemIdentifier The identifier of the clicked map shape.
+   */
+  onItemClick?: (event: React.MouseEvent<SVGPathElement, MouseEvent>, mapShapeItemIdentifier: MapShapeItemIdentifier) => void;
   className?: string;
   /**
    * Fill color applied to every feature path. Overrides item and series colors.

package/Map/MapShapePlot.js

@@ -26,7 +26,8 @@ function MapShapePlot(props) {
     className,
     fill,
     stroke = 'none',
-    strokeWidth = 1
+    strokeWidth = 1,
+    onItemClick
   } = props;
   const geoData = (0, _useGeoData.useGeoData)();
   const path = (0, _useGeoPath.useGeoPath)();
@@ -56,7 +57,7 @@ function MapShapePlot(props) {
       const colorGetter = _seriesConfig.mapShapeSeriesConfig.colorProcessor(seriesItem, undefined, undefined, colorAxis);
       return /*#__PURE__*/(0, _jsxRuntime.jsx)("g", {
         "data-series": id,
-        children: data.map((item, dataIndex) => {
+        children: data.map(item => {
           if (item.hidden) {
             return null;
           }
@@ -68,17 +69,22 @@ function MapShapePlot(props) {
             children: featureIndexes.map(featureIndex => {
               const feature = geoData.features[featureIndex];
               const d = path(feature);
-              const color = fill ?? colorGetter(dataIndex);
+              const color = fill ?? colorGetter(item.name);
               if (!d || color === null) {
                 return null;
               }
               return /*#__PURE__*/(0, _jsxRuntime.jsx)(_MapShape.MapShape, {
                 seriesId: id,
-                dataIndex: dataIndex,
+                featureName: item.name,
                 d: d,
                 color: color,
                 stroke: stroke,
-                strokeWidth: strokeWidth
+                strokeWidth: strokeWidth,
+                onClick: onItemClick && (event => onItemClick(event, {
+                  type: 'mapShape',
+                  seriesId: id,
+                  name: item.name
+                }))
               }, featureIndex);
             })
           }, item.name);
@@ -97,6 +103,12 @@ process.env.NODE_ENV !== "production" ? MapShapePlot.propTypes /* remove-proptyp
    * Fill color applied to every feature path. Overrides item and series colors.
    */
   fill: _propTypes.default.string,
+  /**
+   * Callback fired when clicking on a map shape.
+   * @param {React.MouseEvent<SVGPathElement, MouseEvent>} event The event source of the callback.
+   * @param {MapShapeItemIdentifier} mapShapeItemIdentifier The identifier of the clicked map shape.
+   */
+  onItemClick: _propTypes.default.func,
   /**
    * Stroke color applied to every feature path.
    * @default 'none'

package/Map/MapShapePlot.mjs

@@ -19,7 +19,8 @@ function MapShapePlot(props) {
     className,
     fill,
     stroke = 'none',
-    strokeWidth = 1
+    strokeWidth = 1,
+    onItemClick
   } = props;
   const geoData = useGeoData();
   const path = useGeoPath();
@@ -49,7 +50,7 @@ function MapShapePlot(props) {
       const colorGetter = mapShapeSeriesConfig.colorProcessor(seriesItem, undefined, undefined, colorAxis);
       return /*#__PURE__*/_jsx("g", {
         "data-series": id,
-        children: data.map((item, dataIndex) => {
+        children: data.map(item => {
           if (item.hidden) {
             return null;
           }
@@ -61,17 +62,22 @@ function MapShapePlot(props) {
             children: featureIndexes.map(featureIndex => {
               const feature = geoData.features[featureIndex];
               const d = path(feature);
-              const color = fill ?? colorGetter(dataIndex);
+              const color = fill ?? colorGetter(item.name);
               if (!d || color === null) {
                 return null;
               }
               return /*#__PURE__*/_jsx(MapShape, {
                 seriesId: id,
-                dataIndex: dataIndex,
+                featureName: item.name,
                 d: d,
                 color: color,
                 stroke: stroke,
-                strokeWidth: strokeWidth
+                strokeWidth: strokeWidth,
+                onClick: onItemClick && (event => onItemClick(event, {
+                  type: 'mapShape',
+                  seriesId: id,
+                  name: item.name
+                }))
               }, featureIndex);
             })
           }, item.name);
@@ -90,6 +96,12 @@ process.env.NODE_ENV !== "production" ? MapShapePlot.propTypes /* remove-proptyp
    * Fill color applied to every feature path. Overrides item and series colors.
    */
   fill: PropTypes.string,
+  /**
+   * Callback fired when clicking on a map shape.
+   * @param {React.MouseEvent<SVGPathElement, MouseEvent>} event The event source of the callback.
+   * @param {MapShapeItemIdentifier} mapShapeItemIdentifier The identifier of the clicked map shape.
+   */
+  onItemClick: PropTypes.func,
   /**
    * Stroke color applied to every feature path.
    * @default 'none'

package/Map/index.d.mts

@@ -1,5 +1,6 @@
-import { type useGeoProjectionTypes } from '@mui/x-charts/internals';
+import type { useGeoProjectionTypes } from '@mui/x-charts/internals';
 export * from "./GeoDataPlot.mjs";
+export * from "./MapImagePlot.mjs";
 export * from "./MapShapePlot.mjs";
 export * from "./MapShape.mjs";
 export * from "./FocusedMapShape.mjs";

package/Map/index.d.ts

@@ -1,5 +1,6 @@
-import { type useGeoProjectionTypes } from '@mui/x-charts/internals';
+import type { useGeoProjectionTypes } from '@mui/x-charts/internals';
 export * from "./GeoDataPlot.js";
+export * from "./MapImagePlot.js";
 export * from "./MapShapePlot.js";
 export * from "./MapShape.js";
 export * from "./FocusedMapShape.js";

package/Map/index.js

@@ -14,6 +14,17 @@ Object.keys(_GeoDataPlot).forEach(function (key) {
     }
   });
 });
+var _MapImagePlot = require("./MapImagePlot");
+Object.keys(_MapImagePlot).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _MapImagePlot[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _MapImagePlot[key];
+    }
+  });
+});
 var _MapShapePlot = require("./MapShapePlot");
 Object.keys(_MapShapePlot).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;

package/Map/index.mjs

@@ -1,4 +1,5 @@
 export * from "./GeoDataPlot.mjs";
+export * from "./MapImagePlot.mjs";
 export * from "./MapShapePlot.mjs";
 export * from "./MapShape.mjs";
 export * from "./FocusedMapShape.mjs";

package/Map/reprojectEquirectangularImage.d.mts

@@ -0,0 +1,60 @@
+import type { GeoProjection } from '@mui/x-charts-vendor/d3-geo';
+export interface ReprojectEquirectangularImageParams {
+  /**
+   * A fully-loaded image whose pixels are in the equirectangular (plate carrée)
+   * projection — longitude maps linearly to x, latitude linearly to y.
+   */
+  image: HTMLImageElement;
+  /**
+   * The chart projection. Must expose `invert`; otherwise reprojection is impossible.
+   */
+  projection: GeoProjection;
+  /**
+   * The chart drawing area, in SVG coordinates. `left`/`top` are the offset of the
+   * drawing area inside the SVG, which the projection already accounts for.
+   */
+  area: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  };
+  /**
+   * Geographic extent the source image covers, as `[[west, south], [east, north]]`
+   * in degrees. `west > east` is allowed and means the range wraps across the antimeridian.
+   */
+  imageBounds: [[number, number], [number, number]];
+}
+/**
+ * Warps an equirectangular raster so it matches an arbitrary d3-geo `projection`,
+ * returning the result as a PNG data URL (or `null` when it cannot be produced).
+ *
+ * ### Why inverse mapping
+ *
+ * Forward-projecting each *source* pixel to the screen leaves holes and overlaps,
+ * because the mapping is non-linear and area-distorting. Instead we walk every
+ * *destination* pixel and pull the color it should show from the source — inverse
+ * (destination-to-source) resampling, which fills the output exactly once.
+ *
+ * ### Algorithm
+ *
+ * For each destination pixel `(px, py)` of the drawing area:
+ *
+ * 1. Convert it to SVG coordinates `(left + px, top + py)` and resolve it to a
+ *    `[lon, lat]` coordinate with {@link createVisibleCoordinate}, which returns
+ *    `null` for pixels outside the visible map (post-clip and the spherical
+ *    round-trip), leaving them transparent.
+ * 2. Discard coordinates outside `imageBounds` (no source data there).
+ * 3. Map `[lon, lat]` to a source pixel with nearest-neighbor sampling (the image
+ *    being equirectangular, both axes are linear) and copy its RGBA.
+ *
+ * ### Failure modes
+ *
+ * Returns `null` when a 2D canvas context is unavailable, or when reading the
+ * source pixels throws because a cross-origin image without CORS headers has
+ * tainted the canvas.
+ *
+ * Complexity is `O(width × height)`; callers should treat it as a per-resize
+ * computation rather than a per-frame one.
+ */
+export declare function reprojectEquirectangularImage(params: ReprojectEquirectangularImageParams): string | null;