rsplot 0.3.1.dev3__py3-none-any.whl → 0.3.2.dev4__py3-none-any.whl

rsplot/geo/footprints.py

@@ -0,0 +1,202 @@
+"""Area-overlap remapping and stable display support for gridded fields."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from shapely.geometry.base import BaseGeometry
+
+
+def inferred_corner_grid(centers: np.ndarray) -> np.ndarray:
+    """Estimate shared corners from the unfiltered 2-D native center lattice.
+
+    Midpoints use adjacent native rows/columns, never adjacent QA survivors.
+    Outer edges are linearly extrapolated. Missing geolocation stays missing.
+    """
+    if centers.ndim != 2 or min(centers.shape) < 2:
+        raise ValueError("估算像元边界需要至少 2×2 的原始定位网格。")
+    padded = np.pad(centers.astype(float), 1, mode="edge")
+    padded[0, 1:-1] = 2 * centers[0] - centers[1]
+    padded[-1, 1:-1] = 2 * centers[-1] - centers[-2]
+    padded[:, 0] = 2 * padded[:, 1] - padded[:, 2]
+    padded[:, -1] = 2 * padded[:, -2] - padded[:, -3]
+    return (
+        padded[:-1, :-1] + padded[1:, :-1] + padded[1:, 1:] + padded[:-1, 1:]
+    ) / 4
+
+
+def pixel_corners(corners: np.ndarray) -> np.ndarray:
+    """Convert a shared (ny+1, nx+1) corner grid to (ny, nx, 4)."""
+    return np.stack(
+        [
+            corners[:-1, :-1],
+            corners[:-1, 1:],
+            corners[1:, 1:],
+            corners[1:, :-1],
+        ],
+        axis=-1,
+    )
+
+
+def regular_grid(
+    extent: tuple[float, float, float, float],
+    res: float,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Build globally aligned cell centers covering an extent."""
+    west, east, south, north = extent
+    x = (np.arange(np.floor(west / res), np.ceil(east / res)) + 0.5) * res
+    y = (np.arange(np.floor(south / res), np.ceil(north / res)) + 0.5) * res
+    return np.meshgrid(x, y)
+
+
+def grid_edges(centers: np.ndarray, res: float) -> np.ndarray:
+    return np.concatenate((centers - res / 2, centers[-1:] + res / 2))
+
+
+def rectangle_corners(
+    lon: np.ndarray,
+    lat: np.ndarray,
+    res: float,
+) -> tuple[np.ndarray, np.ndarray]:
+    x = grid_edges(lon[0], res)
+    y = grid_edges(lat[:, 0], res)
+    xx, yy = np.meshgrid(x, y)
+    return pixel_corners(xx).reshape(-1, 4), pixel_corners(yy).reshape(-1, 4)
+
+
+def overlap_mean(
+    corner_lon: np.ndarray,
+    corner_lat: np.ndarray,
+    values: np.ndarray,
+    lon: np.ndarray,
+    lat: np.ndarray,
+    res: float,
+) -> np.ndarray:
+    """Remap valid source polygons with overlap-area weights in EPSG:6933.
+
+    No extrapolation: a target needs positive-area overlap with a valid source.
+    Chunked queries bound temporary target/intersection geometry allocations.
+    """
+    from pyproj import Transformer
+    from shapely import STRtree, area, intersection, is_valid, polygons
+
+    result = np.full(lon.size, np.nan)
+    if not len(values):
+        return result.reshape(lon.shape)
+    transform = Transformer.from_crs(4326, 6933, always_xy=True)
+    x, y = transform.transform(corner_lon, corner_lat)
+    finite = (
+        np.isfinite(values)
+        & np.isfinite(x).all(axis=1)
+        & np.isfinite(y).all(axis=1)
+    )
+    source = polygons(np.stack([x[finite], y[finite]], axis=-1))
+    source_values = values[finite]
+    valid = is_valid(source) & (area(source) > 0)
+    source, source_values = source[valid], source_values[valid]
+    if not len(source):
+        return result.reshape(lon.shape)
+    tree = STRtree(source)
+    xcorners, ycorners = rectangle_corners(lon, lat, res)
+    for start in range(0, lon.size, 8192):
+        stop = min(start + 8192, lon.size)
+        x, y = transform.transform(xcorners[start:stop], ycorners[start:stop])
+        target = polygons(np.stack([x, y], axis=-1))
+        ti, si = tree.query(target, predicate="intersects")
+        if not len(ti):
+            continue
+        weights = area(intersection(target[ti], source[si]))
+        # Shared edges can differ by a few floating-point ulps after projection.
+        # Exclude numerical slivers, without extending support to empty cells.
+        threshold = 1e-10 * np.minimum(area(target[ti]), area(source[si]))
+        weights = np.where(weights > threshold, weights, 0.0)
+        # Boundary-only touches do not supply an observation.
+        sums = np.bincount(
+            ti, weights=weights * source_values[si], minlength=len(target)
+        )
+        weight_sum = np.bincount(ti, weights=weights, minlength=len(target))
+        np.divide(
+            sums, weight_sum, out=result[start:stop], where=weight_sum > 0
+        )
+    return result.reshape(lon.shape)
+
+
+def valid_grid_geometry(
+    lon: np.ndarray,
+    lat: np.ndarray,
+    valid: np.ndarray,
+    res: float,
+) -> BaseGeometry:
+    """Union valid analysis cells using row runs, preserving missing cells."""
+    from shapely import box, union_all
+
+    x = grid_edges(lon[0], res)
+    y = grid_edges(lat[:, 0], res)
+    rectangles = []
+    for row, mask in enumerate(valid):
+        changes = np.diff(np.r_[False, mask, False].astype(np.int8))
+        starts, stops = (
+            np.flatnonzero(changes == 1),
+            np.flatnonzero(changes == -1),
+        )
+        rectangles.extend(box(x[starts], y[row], x[stops], y[row + 1]))
+    return union_all(rectangles)
+
+
+@dataclass
+class FootprintDisplay:
+    lon: np.ndarray
+    lat: np.ndarray
+    values: np.ndarray
+    support: BaseGeometry
+
+
+def prepare_footprint_display(
+    lon: np.ndarray,
+    lat: np.ndarray,
+    values: np.ndarray,
+    geometry: BaseGeometry,
+    *,
+    analysis_res: float,
+    display_res: float,
+    smooth_sigma: float | None = None,
+) -> FootprintDisplay:
+    """Resample a fixed field and return its invariant clipping geometry.
+
+    The renderer must clip the colored layer to ``support``. Coarse display
+    cells may span analysis holes; finite display values alone do not describe
+    valid coverage. Analysis spacing is supplied by the caller.
+    """
+    from rsplot.geo.processing import prepare_display_grid, region_cell_mask
+
+    finite = np.isfinite(values)
+    support = valid_grid_geometry(lon, lat, finite, analysis_res).intersection(
+        geometry
+    )
+    # Smooth only within the fixed analysis lattice, retaining QA/data holes.
+    prepared = prepare_display_grid(
+        lon, lat, values, geometry, smooth_sigma=smooth_sigma
+    )
+    x = grid_edges(lon[0], analysis_res)
+    y = grid_edges(lat[:, 0], analysis_res)
+    display_lon, display_lat = regular_grid(
+        (x[0], x[-1], y[0], y[-1]), display_res
+    )
+    cx, cy = rectangle_corners(lon, lat, analysis_res)
+    finite = np.isfinite(prepared).ravel()
+    display = overlap_mean(
+        cx[finite],
+        cy[finite],
+        prepared.ravel()[finite],
+        display_lon,
+        display_lat,
+        display_res,
+    )
+    display = np.where(
+        region_cell_mask(display_lon, display_lat, geometry), display, np.nan
+    )
+    return FootprintDisplay(display_lon, display_lat, display, support)

rsplot/geo/processing.py

@@ -30,6 +30,8 @@ class PreparedGrid:
     coverage_pct: float
     n_valid_region: int
     total_region_pixels: int
+    # Prepared source before administrative center masking, for display only.
+    unmasked_values: np.ndarray | None = None
 
 
 def buffered_extent(
@@ -58,6 +60,7 @@ def prepare_existing_grid(
     prepared = (
         fill_nan_gaps(lon, lat, values) if fill_gaps else np.asarray(values)
     )
+    unmasked_values = prepared
     region_mask = region_grid_mask(lon, lat, geometry)
     prepared = mask_to_region(
         lon,
@@ -89,6 +92,7 @@ def prepare_existing_grid(
         coverage_pct=coverage,
         n_valid_region=n_valid,
         total_region_pixels=total,
+        unmasked_values=unmasked_values,
     )
 
 
@@ -118,3 +122,81 @@ def prepare_swath_grid(
         fill_gaps=True,
         smooth_sigma=smooth_sigma,
     )
+
+
+def region_cell_mask(
+    lon: np.ndarray,
+    lat: np.ndarray,
+    geometry: BaseGeometry,
+) -> np.ndarray:
+    """Select rectilinear cells touching the region, including exterior centers.
+
+    Edges match pcolormesh's midpoint convention. A singleton axis has zero
+    width, matching the renderer when only one center is supplied.
+    """
+    from shapely import box, intersects
+
+    if lon.ndim != 2 or lat.shape != lon.shape:
+        raise ValueError("显示网格经纬度必须为同形状二维数组。")
+    if not (np.allclose(lon, lon[0:1, :]) and np.allclose(lat, lat[:, 0:1])):
+        raise ValueError("行政边界显示裁剪需要规则经纬度网格。")
+
+    def edges(centers: np.ndarray) -> np.ndarray:
+        if centers.size == 1:
+            return np.repeat(centers, 2)
+        half_steps = np.diff(centers) / 2
+        return np.concatenate(
+            (
+                centers[:1] - half_steps[:1],
+                centers[:-1] + half_steps,
+                centers[-1:] + half_steps[-1:],
+            )
+        )
+
+    x = edges(lon[0])
+    y = edges(lat[:, 0])
+    cells = box(x[:-1][None, :], y[:-1, None], x[1:][None, :], y[1:, None])
+    return intersects(geometry, cells)
+
+
+def prepare_display_grid(
+    lon: np.ndarray,
+    lat: np.ndarray,
+    values: np.ndarray,
+    geometry: BaseGeometry,
+    *,
+    smooth_sigma: float | None = None,
+) -> np.ndarray:
+    """Keep valid intersecting cells; exact geometry clipping is render-only.
+
+    Input must precede the administrative center mask. Smoothing can use the
+    surrounding buffer but cannot create newly valid cells. Statistics must
+    continue to use PreparedGrid.values, never this display array.
+    """
+    visible = region_cell_mask(lon, lat, geometry)
+    valid = np.isfinite(values)
+    display = np.asarray(values)
+    if smooth_sigma is not None and smooth_sigma > 0:
+        # Normalized convolution avoids NaN-gap warnings on sparse scans.
+        # This display-only operation does not change legacy statistics.
+        from scipy.ndimage import gaussian_filter
+
+        numerator = gaussian_filter(
+            np.where(valid, values, 0.0),
+            smooth_sigma,
+            mode="constant",
+            cval=0.0,
+        )
+        denominator = gaussian_filter(
+            valid.astype(float),
+            smooth_sigma,
+            mode="constant",
+            cval=0.0,
+        )
+        display = np.divide(
+            numerator,
+            denominator,
+            out=np.full(values.shape, np.nan),
+            where=denominator > 0,
+        )
+    return np.where(visible & valid, display, np.nan)

rsplot/plotting/map_frame.py

@@ -24,7 +24,9 @@ from rsplot.tiles.tianditu import TianDiTuTiles
 
 if TYPE_CHECKING:
     from cartopy.mpl.geoaxes import GeoAxes
+    from matplotlib.artist import Artist
     from matplotlib.figure import Figure
+    from shapely.geometry.base import BaseGeometry
 
     from rsplot.geo.boundaries import RegionInfo
 
@@ -90,13 +92,27 @@ def add_basemap_tiles(frame: MapFrame, region: RegionInfo) -> None:
 
 def add_region_boundaries(ax: GeoAxes, region: RegionInfo) -> None:
     """Draw detail, subdivision, and main boundaries in established order."""
+    selected = {
+        member.geometry.normalize().wkb
+        for member in getattr(region, "members", ())
+    }
+
+    def visible_geometries(frame):
+        if not selected:
+            return frame.geometry
+        return [
+            geometry
+            for geometry in frame.geometry
+            if geometry.normalize().wkb not in selected
+        ]
+
     if (
         region.detail_boundary_gdf is not None
         and len(region.detail_boundary_gdf) > 0
     ):
         ax.add_feature(
             ShapelyFeature(
-                region.detail_boundary_gdf.geometry,
+                visible_geometries(region.detail_boundary_gdf),
                 ccrs.PlateCarree(),
                 edgecolor="#aaa",
                 facecolor="none",
@@ -112,7 +128,7 @@ def add_region_boundaries(ax: GeoAxes, region: RegionInfo) -> None:
         is_county_sub = region.level == "city"
         ax.add_feature(
             ShapelyFeature(
-                region.sub_boundary_gdf.geometry,
+                visible_geometries(region.sub_boundary_gdf),
                 ccrs.PlateCarree(),
                 edgecolor="#888" if not is_county_sub else "#666",
                 facecolor="none",
@@ -133,6 +149,9 @@ def add_region_boundaries(ax: GeoAxes, region: RegionInfo) -> None:
             )
         )
 
+    if getattr(region, "members", ()):
+        add_member_labels(ax, region)
+
 
 def add_subdivision_labels(ax: GeoAxes, region: RegionInfo) -> None:
     """Add name labels for a region's subdivision features."""
@@ -143,7 +162,15 @@ def add_subdivision_labels(ax: GeoAxes, region: RegionInfo) -> None:
     name_field = region.sub_name_field
     fontsize = region.params.label_fontsize
 
+    selected_geometry = {
+        m.geometry.normalize().wkb for m in getattr(region, "members", ())
+    }
+    seen_labels = set()
     for _, row in gdf.iterrows():
+        key = row.geometry.normalize().wkb
+        if key in selected_geometry or (row[name_field], key) in seen_labels:
+            continue
+        seen_labels.add((row[name_field], key))
         point = row.geometry.representative_point()
         if region.level in (
             "key_region",
@@ -168,6 +195,31 @@ def add_subdivision_labels(ax: GeoAxes, region: RegionInfo) -> None:
         )
 
 
+def add_member_labels(ax: GeoAxes, region: RegionInfo) -> None:
+    """Label selections separately from subdivisions; qualify duplicate names."""
+    from collections import Counter
+
+    names = Counter(member.name for member in region.members)
+    for member in region.members:
+        point = member.geometry.representative_point()
+        label = (
+            (member.qualified_name or member.name)
+            if names[member.name] > 1
+            else member.name
+        )
+        ax.text(
+            point.x,
+            point.y,
+            label,
+            transform=ccrs.PlateCarree(),
+            fontsize=region.params.label_fontsize,
+            ha="center",
+            va="center",
+            color="#222",
+            path_effects=[pe.withStroke(linewidth=2, foreground="white")],
+        )
+
+
 def configure_map_axes(
     ax: GeoAxes,
     region: RegionInfo,
@@ -195,8 +247,12 @@ def configure_map_axes(
     gridlines.top_labels = gridlines.right_labels = False
     gridlines.xformatter = LONGITUDE_FORMATTER
     gridlines.yformatter = LATITUDE_FORMATTER
-    gridlines.xlocator = mticker.MultipleLocator(region.params.grid_step)
-    gridlines.ylocator = mticker.MultipleLocator(region.params.grid_step)
+    if getattr(region, "members", ()):
+        gridlines.xlocator = mticker.MaxNLocator(nbins=5)
+        gridlines.ylocator = mticker.MaxNLocator(nbins=5)
+    else:
+        gridlines.xlocator = mticker.MultipleLocator(region.params.grid_step)
+        gridlines.ylocator = mticker.MultipleLocator(region.params.grid_step)
 
 
 def finalize_map_figure(
@@ -218,3 +274,63 @@ def finalize_map_figure(
         plt.close(fig)
     else:
         plt.show()
+
+
+def clip_raster_to_region(
+    artist: Artist,
+    ax: GeoAxes,
+    region: RegionInfo,
+    *,
+    coverage_geometry: BaseGeometry | None = None,
+) -> None:
+    """Clip only the data layer, preserving holes and disconnected islands."""
+    import numpy as np
+    from matplotlib.path import Path as MplPath
+    from shapely.geometry import GeometryCollection, MultiPolygon
+    from shapely.geometry.polygon import orient
+
+    def orient_geometry(geometry: BaseGeometry) -> BaseGeometry:
+        if geometry.geom_type == "Polygon":
+            return orient(geometry, sign=1.0)
+        if geometry.geom_type == "MultiPolygon":
+            return MultiPolygon(
+                [orient(part, sign=1.0) for part in geometry.geoms]
+            )
+        if geometry.geom_type == "GeometryCollection":
+            return GeometryCollection(
+                [orient_geometry(part) for part in geometry.geoms]
+            )
+        return geometry
+
+    # Project the geometry into the axes coordinates before building a clip
+    # path, so both PlateCarree and satellite-basemap Mercator axes work.
+    clip_geometry = region.geometry
+    if coverage_geometry is not None:
+        clip_geometry = clip_geometry.intersection(coverage_geometry)
+    geometry = ax.projection.project_geometry(
+        orient_geometry(clip_geometry), ccrs.PlateCarree()
+    )
+    paths = []
+
+    def append_polygons(geometry: BaseGeometry) -> None:
+        if geometry.is_empty:
+            return
+        if geometry.geom_type == "Polygon":
+            polygon = orient(geometry, sign=1.0)
+            for ring in (polygon.exterior, *polygon.interiors):
+                vertices = np.asarray(ring.coords)[:, :2]
+                codes = np.full(len(vertices), MplPath.LINETO, dtype=np.uint8)
+                codes[0], codes[-1] = MplPath.MOVETO, MplPath.CLOSEPOLY
+                paths.append(MplPath(vertices, codes))
+        elif hasattr(geometry, "geoms"):
+            for part in geometry.geoms:
+                append_polygons(part)
+
+    append_polygons(geometry)
+    if not paths:
+        raise ValueError("行政区边界没有可用于裁剪的多边形。")
+    artist.set_clip_path(MplPath.make_compound_path(*paths), ax.transData)
+    # Cartopy can create an auxiliary collection for wrapped mesh cells.
+    wrapped = getattr(artist, "_wrapped_collection_fix", None)
+    if wrapped is not None:
+        wrapped.set_clip_path(MplPath.make_compound_path(*paths), ax.transData)

rsplot/plotting/overlay.py

@@ -19,6 +19,7 @@ from rsplot.plotting.colormaps import (
 from rsplot.plotting.map_frame import (
     add_basemap_tiles,
     add_region_boundaries,
+    clip_raster_to_region,
     configure_map_axes,
     create_map_frame,
     finalize_map_figure,
@@ -29,6 +30,8 @@ from rsplot.plotting.station import (
 )
 
 if TYPE_CHECKING:
+    from shapely.geometry.base import BaseGeometry
+
     from rsplot.geo.boundaries import RegionInfo
     from rsplot.readers.guokong import StationData
 
@@ -55,6 +58,7 @@ def plot_overlay(
     hcho_cmap_file: str | None = None,
     title: str | None = None,
     output: str | None = None,
+    coverage_geometry: BaseGeometry | None = None,
 ) -> None:
     """Draw satellite raster + station scatter on the same axes.
 
@@ -89,6 +93,7 @@ def plot_overlay(
         alpha=raster_alpha,
         zorder=1,
     )
+    clip_raster_to_region(im, ax, region, coverage_geometry=coverage_geometry)
 
     # --- Basemap tiles ---
     add_basemap_tiles(frame, region)

rsplot/plotting/raster.py

@@ -17,6 +17,7 @@ from rsplot.plotting.map_frame import (
     add_basemap_tiles,
     add_region_boundaries,
     add_subdivision_labels,
+    clip_raster_to_region,
     configure_map_axes,
     create_map_frame,
     figure_size_for_level,
@@ -24,6 +25,8 @@ from rsplot.plotting.map_frame import (
 )
 
 if TYPE_CHECKING:
+    from shapely.geometry.base import BaseGeometry
+
     from rsplot.geo.boundaries import RegionInfo
 
 
@@ -43,6 +46,7 @@ def plot_raster(
     hcho_cmap_file: str | None = None,
     title: str | None = None,
     output: str | None = None,
+    coverage_geometry: BaseGeometry | None = None,
     colorbar_label: str = "NO2 VCD (x10^15 molec/cm2)",
 ) -> None:
     """Draw a raster map for the given region.
@@ -79,6 +83,7 @@ def plot_raster(
         shading="auto",
         alpha=alpha,
     )
+    clip_raster_to_region(im, ax, region, coverage_geometry=coverage_geometry)
 
     # --- Basemap tiles (beneath boundaries, above raster) ---
     add_basemap_tiles(frame, region)

rsplot/readers/__init__.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import math
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 
 import numpy as np
 
@@ -40,6 +40,10 @@ class ProductInfo:
         default_factory=dict
     )
 
+    sensor: str = "tropomi"
+    data_key: str | None = None
+    quantity: str | None = None
+
     def defaults_for_level(self, level: str) -> ProductPlotDefaults:
         """Return product-specific defaults for an administrative level."""
         return self.level_defaults.get(level, ProductPlotDefaults())
@@ -91,15 +95,45 @@ PRODUCT_REGISTRY: dict[str, ProductInfo] = {
 }
 
 
-def get_product_info(product: str) -> ProductInfo:
-    """Return ProductInfo for a product name."""
+def get_product_info(product: str, *, sensor: str = "tropomi") -> ProductInfo:
+    """Resolve a product within a sensor, preserving legacy registry keys."""
     key = product.lower()
+    sensor = sensor.lower()
+    if sensor not in ("tropomi", "gems"):
+        raise ValueError(f"未知卫星来源 '{sensor}'，可用: tropomi / gems")
     if key not in PRODUCT_REGISTRY:
         available = ", ".join(PRODUCT_REGISTRY)
         raise ValueError(
             f"Unsupported product '{product}'. Available: {available}"
         )
-    return PRODUCT_REGISTRY[key]
+    if sensor == "tropomi":
+        return PRODUCT_REGISTRY[key]
+    from rsplot.readers.gems import (
+        GemsHCHOReader,
+        GemsNO2Reader,
+        GemsO3PRReader,
+        GemsO3Reader,
+    )
+
+    readers = {
+        "no2": GemsNO2Reader,
+        "hcho": GemsHCHOReader,
+        "o3": GemsO3Reader,
+        "o3pr": GemsO3PRReader,
+    }
+    quantities = {
+        "no2": "tropospheric_no2_column",
+        "hcho": "hcho_column",
+        "o3": "total_ozone_column",
+        "o3pr": "tropospheric_ozone_column",
+    }
+    return replace(
+        PRODUCT_REGISTRY[key],
+        reader_cls=readers[key],
+        sensor="gems",
+        data_key="gems_o3" if key == "o3pr" else f"gems_{key}",
+        quantity=quantities[key],
+    )
 
 
 def auto_vrange(

rsplot/readers/base.py

@@ -3,7 +3,9 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from dataclasses import dataclass
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from typing import Any
 
 import numpy as np
 import xarray as xr
@@ -19,11 +21,24 @@ class SwathData:
     n_pixels: int
     n_files: int
     n_broken: int
+    metadata: dict[str, Any] = field(default_factory=dict)
+    corner_lon: np.ndarray | None = None  # (n_pixels, 4)
+    corner_lat: np.ndarray | None = None  # (n_pixels, 4)
 
 
 class BaseReader(ABC):
     """Interface for reading a single-day satellite product."""
 
+    def iter_scans(
+        self,
+        data_dir: str,
+        date: str,
+        extent: tuple[float, float, float, float],
+        qa_threshold: float = 0.5,
+    ) -> Iterator[SwathData]:
+        """Yield temporal batches; legacy readers supply one daily batch."""
+        yield self.read(data_dir, date, extent, qa_threshold)
+
     @abstractmethod
     def read(
         self,