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

rsplot/cli.py

@@ -45,14 +45,18 @@ def _callback(
 @app.command()
 def raster(
     region: str = typer.Argument(
-        ..., help="区域名称，如 中国、安徽、合肥、YRD、合肥/蜀山"
+        ...,
+        help="区域名称；支持逗号分隔多个省市县街道，如 '中山市/东区街道,中山市/南区街道'，无需配置",
     ),
     date_arg: str = typer.Argument(
         ...,
-        help="单日 YYYYMMDD 走单日路径；带 --days 或写成 YYYYMMDD-YYYYMMDD "
+        help="GEMS: 北京时间 YYYYMMDDHHMM 精确扫描，YYYYMMDD 日均；单日 YYYYMMDD 走单日路径；带 --days 或写成 YYYYMMDD-YYYYMMDD "
         "时切换为窗口均值（HCHO 单日覆盖率低，月均更可读）",
     ),
     # --- optional overrides ---
+    sensor: str = typer.Option(
+        "tropomi", "--sensor", help="卫星来源: tropomi / gems"
+    ),
     product: str = typer.Option(
         "o3",
         "--product",
@@ -92,7 +96,11 @@ def raster(
         help="输出文件路径，不指定则弹窗显示。",
     ),
     dpi: int | None = typer.Option(300, "--dpi", help="输出 DPI"),
-    res: float | None = typer.Option(None, "--res", help="网格分辨率 (度)"),
+    res: float | None = typer.Option(
+        None,
+        "--res",
+        help="网格分辨率 (度)；GEMS 绘图仅控制显示，分析网格固定 0.05°",
+    ),
     basemap: str | None = typer.Option(
         None,
         "--basemap",
@@ -106,7 +114,9 @@ def raster(
         None, "--smooth", help="高斯平滑 sigma"
     ),
     title: str | None = typer.Option(None, "--title", help="自定义标题"),
-    qa: float | None = typer.Option(0.5, "--qa", help="QA 阈值 (0-1)"),
+    qa: float | None = typer.Option(
+        None, "--qa", help="TROPOMI QA 阈值 (0-1)，默认取配置；GEMS 不适用"
+    ),
     cf: float = typer.Option(
         0.5,
         "--cf",
@@ -128,6 +138,7 @@ def raster(
         region=region,
         date_arg=date_arg,
         product=product,
+        sensor=sensor,
         days=days,
         n_min=n_min,
         level=level,
@@ -620,20 +631,29 @@ def trend(
 @app.command()
 def overlay(
     region: str = typer.Argument(
-        ..., help="区域名称，如 中国、安徽、合肥、YRD、合肥/蜀山"
+        ...,
+        help="区域名称；支持逗号分隔多个省市县街道，如 '中山市/东区街道,中山市/南区街道'，无需配置",
     ),
     datetime_str: str = typer.Argument(
         ...,
-        help="YYYYMMDDHH (精确小时) 或 YYYYMMDD (自动取最新小时)；"
+        help="GEMS: 北京时间 YYYYMMDD 日均（需 --station-datetime），或 YYYYMMDDHHMM 精确扫描（自动匹配最近站点整点）；TROPOMI: YYYYMMDDHH (精确小时) 或 YYYYMMDD (自动取最新小时)；"
         "日期部分用于卫星，小时部分用于站点",
     ),
     # --- satellite product ---
+    sensor: str = typer.Option(
+        "tropomi", "--sensor", help="卫星来源: tropomi / gems"
+    ),
     product: str = typer.Option(
         "o3",
         "--product",
         "-p",
         help="卫星产品类型: no2 / o3 / o3pr / hcho",
     ),
+    station_datetime: str | None = typer.Option(
+        None,
+        "--station-datetime",
+        help="GEMS 叠加站点时间，北京时间 YYYYMMDDHH",
+    ),
     # --- station variable ---
     var: str | None = typer.Option(
         None,
@@ -665,7 +685,11 @@ def overlay(
         help="输出文件路径，不指定则弹窗显示。",
     ),
     dpi: int | None = typer.Option(300, "--dpi", help="输出 DPI"),
-    res: float | None = typer.Option(None, "--res", help="网格分辨率 (度)"),
+    res: float | None = typer.Option(
+        None,
+        "--res",
+        help="网格分辨率 (度)；GEMS 绘图仅控制显示，分析网格固定 0.05°",
+    ),
     basemap: str | None = typer.Option(
         None,
         "--basemap",
@@ -682,7 +706,9 @@ def overlay(
     smooth: float | None = typer.Option(
         None, "--smooth", help="高斯平滑 sigma"
     ),
-    qa: float | None = typer.Option(0.5, "--qa", help="QA 阈值 (0-1)"),
+    qa: float | None = typer.Option(
+        None, "--qa", help="TROPOMI QA 阈值 (0-1)，默认取配置；GEMS 不适用"
+    ),
     cf: float = typer.Option(
         0.5,
         "--cf",
@@ -708,7 +734,9 @@ def overlay(
     run_overlay(
         region=region,
         datetime_str=datetime_str,
+        station_datetime=station_datetime,
         product=product,
+        sensor=sensor,
         var=var,
         level=level,
         raster_dir=raster_dir,
@@ -746,6 +774,9 @@ def recent(
         "--source",
         help="数据源: raster / station",
     ),
+    sensor: str = typer.Option(
+        "tropomi", "--sensor", help="卫星来源: tropomi / gems"
+    ),
     product: str = typer.Option(
         "o3",
         "--product",
@@ -776,8 +807,14 @@ def recent(
         "-o",
         help="输出 JSON 路径",
     ),
-    res: float | None = typer.Option(None, "--res", help="网格分辨率 (度)"),
-    qa: float | None = typer.Option(0.5, "--qa", help="QA 阈值 (0-1)"),
+    res: float | None = typer.Option(
+        None,
+        "--res",
+        help="TROPOMI 网格分辨率 (度)；GEMS 统计固定使用 0.05°，忽略此选项",
+    ),
+    qa: float | None = typer.Option(
+        None, "--qa", help="TROPOMI QA 阈值 (0-1)，默认取配置；GEMS 不适用"
+    ),
     cf: float = typer.Option(
         0.5,
         "--cf",
@@ -800,6 +837,7 @@ def recent(
         days=days,
         source=source,
         product=product,
+        sensor=sensor,
         var=var,
         level=level,
         data_dir=data_dir,

rsplot/commands/common.py

@@ -3,13 +3,18 @@
 from __future__ import annotations
 
 import math
-from typing import TYPE_CHECKING
+from collections.abc import Callable
+from typing import TYPE_CHECKING, ParamSpec, TypeVar
+
+import typer
 
 if TYPE_CHECKING:
     import geopandas as gpd
     from rich.console import Console
 
+    from rsplot.config import AppConfig
     from rsplot.geo.boundaries import RegionInfo
+    from rsplot.readers import ProductInfo
 
 
 FORECAST_STATION_PAIR: dict[str, str] = {
@@ -110,3 +115,61 @@ def print_failed_dates(
         console.print(f"    - {date}: {message}")
     if len(items) > max_items:
         console.print(f"    ... 另有 {len(items) - max_items} 天")
+
+
+def resolve_satellite(
+    product: str,
+    sensor: str,
+    qa: float | None,
+    cfg: AppConfig,
+    console: Console,
+) -> tuple[ProductInfo, float]:
+    """Resolve source and QA policy before opening regional/data files."""
+    from rsplot.readers import get_product_info
+
+    try:
+        info = get_product_info(product, sensor=sensor)
+        if info.sensor == "gems" and qa is not None:
+            raise ValueError(
+                "--qa 仅用于 TROPOMI；GEMS 使用最终质量标记 = 0 "
+                "及 SZA/VZA < 70°，云量可通过 --cf 设置。"
+            )
+        threshold = (
+            0.5
+            if info.sensor == "gems"
+            else qa
+            if qa is not None
+            else cfg.qa_threshold
+        )
+        validate_unit_interval(threshold, "--qa")
+    except ValueError as error:
+        console.print(f"[red]{error}[/red]")
+        raise typer.Exit(1) from error
+    return info, threshold
+
+
+def satellite_filter_label(sensor: str, qa: float, cf: float) -> str:
+    """Describe the actual filter rather than a synthetic GEMS QA value."""
+    quality = (
+        "最终质量标记 = 0, SZA/VZA < 70°" if sensor == "gems" else f"QA > {qa}"
+    )
+    return f"{quality}, 云量 <= {cf}"
+
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+
+def satellite_errors(function: Callable[_P, _R]) -> Callable[_P, _R]:
+    """Render expected satellite input/data errors in the CLI's style."""
+    from functools import wraps
+
+    @wraps(function)
+    def wrapped(*args: _P.args, **kwargs: _P.kwargs) -> _R:
+        try:
+            return function(*args, **kwargs)
+        except (ValueError, FileNotFoundError, OSError) as error:
+            kwargs["console"].print(f"[red]{error}[/red]")
+            raise typer.Exit(1) from error
+
+    return wrapped

rsplot/commands/forecast.py

@@ -53,6 +53,7 @@ def run_forecast(
     from rsplot.geo.boundaries import resolve_region
     from rsplot.geo.processing import (
         buffered_extent,
+        prepare_display_grid,
         prepare_existing_grid,
     )
     from rsplot.plotting.colormaps import STATION_CONCENTRATION_CMAP
@@ -151,10 +152,22 @@ def run_forecast(
         info.geometry,
         fill_gaps=False,
     )
-    if not np.isfinite(prepared.values).any():
+    display_source = prepared.unmasked_values
+    display_grid = prepare_display_grid(
+        prepared.lon,
+        prepared.lat,
+        display_source,
+        info.geometry,
+        smooth_sigma=smooth,
+    )
+    if not np.isfinite(display_grid).any():
         console.print("[red]目标区域内没有有效预报网格。[/red]")
         raise typer.Exit(1)
-    if smooth is not None and smooth > 0:
+    if (
+        smooth is not None
+        and smooth > 0
+        and np.isfinite(prepared.values).any()
+    ):
         console.print(f"  → 高斯平滑 sigma={smooth}")
         prepared = prepare_existing_grid(
             prepared.lon,
@@ -170,7 +183,12 @@ def run_forecast(
         f"({prepared.n_valid_region}/{prepared.total_region_pixels})"
     )
 
-    auto_min, auto_max = auto_forecast_vrange(prepared.values, var_info)
+    auto_min, auto_max = auto_forecast_vrange(
+        prepared.values
+        if np.isfinite(prepared.values).any()
+        else display_grid,
+        var_info,
+    )
     use_vmin = vmin if vmin is not None else auto_min
     use_vmax = vmax if vmax is not None else auto_max
     try:
@@ -289,7 +307,7 @@ def run_forecast(
         plot_raster(
             prepared.lon,
             prepared.lat,
-            prepared.values,
+            display_grid,
             info,
             dpi=use_dpi,
             cmap=use_cmap,
@@ -306,7 +324,7 @@ def run_forecast(
         plot_overlay(
             prepared.lon,
             prepared.lat,
-            prepared.values,
+            display_grid,
             station_data,
             info,
             raster_cmap=use_cmap,
@@ -330,6 +348,7 @@ def run_forecast(
         LON=prepared.lon,
         LAT=prepared.lat,
         grid=prepared.values,
+        display_grid=display_grid,
         vmin=use_vmin,
         vmax=use_vmax,
         output=output,

rsplot/commands/overlay.py

@@ -10,6 +10,9 @@ import typer
 from rsplot.commands.common import (
     load_fallback_city_boundaries,
     parse_basemap,
+    resolve_satellite,
+    satellite_errors,
+    satellite_filter_label,
     validate_color_range,
     validate_non_negative,
     validate_positive,
@@ -29,11 +32,14 @@ PRODUCT_STATION_PAIR = {
 }
 
 
+@satellite_errors
 def run_overlay(
     *,
     region: str,
     datetime_str: str,
     product: str,
+    sensor: str = "tropomi",
+    station_datetime: str | None = None,
     var: str | None,
     level: str | None,
     raster_dir: str | None,
@@ -53,15 +59,34 @@ def run_overlay(
 ) -> None:
     """Execute satellite/station overlay orchestration."""
     from rsplot.config import STATION_VAR_META, get_exceedance_threshold
-    from rsplot.geo.boundaries import resolve_region
-    from rsplot.geo.processing import buffered_extent, prepare_swath_grid
+    from rsplot.geo.boundaries import resolve_regions
+    from rsplot.geo.processing import (
+        buffered_extent,
+        prepare_display_grid,
+        prepare_existing_grid,
+        prepare_swath_grid,
+    )
     from rsplot.plotting.overlay import plot_overlay
     from rsplot.plotting.styles import setup_fonts
-    from rsplot.readers import auto_vrange, get_product_info
+    from rsplot.readers import auto_vrange
     from rsplot.readers.guokong import mask_stations_to_region, read_stations
     from rsplot.results import build_overlay_result, emit_result
 
     cfg = AppConfig.load()
+    prod_info, use_qa = resolve_satellite(product, sensor, qa, cfg, console)
+    sensor = prod_info.sensor
+    pairing = None
+    station_request = datetime_str
+    if sensor == "gems":
+        from rsplot.readers.gems import match_station_hour
+
+        station_request, pairing = match_station_hour(
+            datetime_str, station_datetime
+        )
+        if product.lower() == "hcho" and var is None:
+            raise ValueError("GEMS HCHO 叠加需通过 --var 显式指定站点变量。")
+    elif station_datetime is not None:
+        raise ValueError("--station-datetime 在此命令中仅用于 GEMS。")
     setup_fonts(cfg.font_dir)
 
     if var is None:
@@ -71,7 +96,9 @@ def run_overlay(
         console.print(f"[red]未知站点变量 '{var}'[/red]。可用: {available}")
         raise typer.Exit(1)
 
-    if not datetime_str.isdigit() or len(datetime_str) not in (8, 10):
+    if sensor != "gems" and (
+        not datetime_str.isdigit() or len(datetime_str) not in (8, 10)
+    ):
         console.print(
             f"[red]datetime 参数 '{datetime_str}' 格式不正确[/red]，"
             "请使用 YYYYMMDD 或 YYYYMMDDHH。"
@@ -80,8 +107,15 @@ def run_overlay(
     date = datetime_str[:8]
 
     console.print(f"[bold]解析区域:[/bold] {region}")
-    info = resolve_region(region, cfg, level_override=level)
+    info = resolve_regions(region, cfg, level_override=level)
     console.print(f"  → [green]{info.name}[/green] (级别: {info.level})")
+    if info.members:
+        console.print(
+            "  → 成员: "
+            + "、".join(
+                member.qualified_name or member.name for member in info.members
+            )
+        )
     console.print(
         f"  → 范围: {info.extent[0]:.2f}°~{info.extent[1]:.2f}°E, "
         f"{info.extent[2]:.2f}°~{info.extent[3]:.2f}°N"
@@ -89,7 +123,6 @@ def run_overlay(
 
     params = info.params
     use_dpi = dpi if dpi is not None else cfg.dpi
-    prod_info = get_product_info(product)
     product_defaults = prod_info.defaults_for_level(info.level)
     use_res = (
         res
@@ -99,7 +132,6 @@ def run_overlay(
         else params.res
     )
     use_cmap = cmap if cmap is not None else prod_info.cmap
-    use_qa = qa if qa is not None else cfg.qa_threshold
     use_smooth = (
         smooth
         if smooth is not None
@@ -129,36 +161,117 @@ def run_overlay(
     )
 
     use_raster_dir = (
-        raster_dir if raster_dir is not None else cfg.get_data_dir(product)
+        raster_dir
+        if raster_dir is not None
+        else cfg.get_data_dir(prod_info.data_key or product)
     )
     reader = prod_info.reader_cls()
     reader.cloud_fraction_max = cf
+    analysis_res = use_res
+    if sensor == "gems":
+        from rsplot.readers.gems import GEMS_ANALYSIS_RESOLUTION
+
+        analysis_res = GEMS_ANALYSIS_RESOLUTION
+        console.print(
+            f"  → GEMS 分析网格 {analysis_res}°，显示网格 {use_res}°"
+        )
     read_extent = buffered_extent(info.extent, 1.0)
     console.print(
         f"\n[bold]读取卫星数据:[/bold] {use_raster_dir} (产品: {product})"
     )
-    console.print(f"  日期: {date}, QA > {use_qa}, CF <= {cf}")
-    swath = reader.read(
-        use_raster_dir,
-        date,
-        read_extent,
-        qa_threshold=use_qa,
-    )
     console.print(
-        f"  → [green]{swath.n_pixels}[/green] 有效像元 "
-        f"({swath.n_files} 文件, {swath.n_broken} 损坏)"
+        f"  时间: {datetime_str}, {satellite_filter_label(sensor, use_qa, cf)}"
     )
+    statistics_grid = None
+    if sensor == "gems":
+        from rsplot.temporal import read_scan_mean
 
-    console.print(f"\n[bold]网格化:[/bold] {use_res}° 分辨率")
-    prepared = prepare_swath_grid(
-        swath.lon,
-        swath.lat,
-        swath.values,
-        read_extent,
-        use_res,
-        info.geometry,
-        smooth_sigma=use_smooth,
-    )
+        batch = read_scan_mean(
+            reader=reader,
+            data_dir=use_raster_dir,
+            request=datetime_str,
+            extent=read_extent,
+            res=analysis_res,
+        )
+        prepared = prepare_existing_grid(
+            batch.LON,
+            batch.LAT,
+            batch.grid,
+            info.geometry,
+            fill_gaps=False,
+        )
+        display_source = prepared.unmasked_values
+        statistics_grid = prepared.values.copy()
+        swath_meta = {
+            "n_pixels": batch.n_pixels,
+            "n_files": batch.n_files,
+            "n_broken": batch.n_broken,
+            "resolution_deg": use_res,
+            "cloud_fraction_max": cf,
+            **batch.metadata,
+        }
+    else:
+        swath = reader.read(
+            use_raster_dir,
+            date,
+            read_extent,
+            qa_threshold=use_qa,
+        )
+        console.print(
+            f"  → [green]{swath.n_pixels}[/green] 有效像元 "
+            f"({swath.n_files} 文件, {swath.n_broken} 损坏)"
+        )
+
+        console.print(f"\n[bold]网格化:[/bold] {use_res}° 分辨率")
+        prepared = prepare_swath_grid(
+            swath.lon,
+            swath.lat,
+            swath.values,
+            read_extent,
+            use_res,
+            info.geometry,
+            smooth_sigma=use_smooth,
+        )
+        display_source = prepared.unmasked_values
+        swath_meta = {
+            "n_pixels": int(swath.n_pixels),
+            "n_files": int(swath.n_files),
+            "n_broken": int(swath.n_broken),
+            "qa_threshold": use_qa,
+            "cloud_fraction_max": cf,
+            "resolution_deg": use_res,
+        }
+    display_lon, display_lat = prepared.lon, prepared.lat
+    display_support = None
+    if sensor == "gems":
+        from rsplot.geo.footprints import prepare_footprint_display
+
+        display = prepare_footprint_display(
+            prepared.lon,
+            prepared.lat,
+            display_source,
+            info.geometry,
+            analysis_res=analysis_res,
+            display_res=use_res,
+            smooth_sigma=use_smooth,
+        )
+        display_lon, display_lat = display.lon, display.lat
+        display_grid, display_support = display.values, display.support
+        swath_meta["resolution_deg"] = analysis_res
+        swath_meta["analysis_resolution_deg"] = analysis_res
+        swath_meta["display_resolution_deg"] = use_res
+        swath_meta["display_support"] = "fixed_analysis_valid_cells"
+    else:
+        display_grid = prepare_display_grid(
+            prepared.lon,
+            prepared.lat,
+            display_source,
+            info.geometry,
+            smooth_sigma=use_smooth,
+        )
+    if not np.isfinite(display_grid).any():
+        console.print("[red]目标区域没有相交的有效卫星网格。[/red]")
+        raise typer.Exit(1)
     console.print(
         f"  → 网格 {prepared.values.shape}, "
         f"区域内覆盖率 {prepared.coverage_pct:.1f}% "
@@ -171,7 +284,12 @@ def run_overlay(
         use_vmin = vmin if vmin is not None else prod_info.vmin
         use_vmax = vmax if vmax is not None else prod_info.vmax
     else:
-        auto_min, auto_max = auto_vrange(prepared.values, prod_info)
+        auto_min, auto_max = auto_vrange(
+            prepared.values
+            if np.isfinite(prepared.values).any()
+            else display_grid,
+            prod_info,
+        )
         use_vmin = vmin if vmin is not None else auto_min
         use_vmax = vmax if vmax is not None else auto_max
     try:
@@ -185,16 +303,16 @@ def run_overlay(
         station_dir if station_dir is not None else cfg.get_data_dir("guokong")
     )
     console.print(f"\n[bold]读取站点数据:[/bold] {use_station_dir}")
-    console.print(f"  时间: {datetime_str}, 变量: {var}")
+    console.print(f"  时间: {station_request}, 变量: {var}")
     station_extent = buffered_extent(info.extent, 0.5)
     data, resolved_dt = read_stations(
         use_station_dir,
-        datetime_str,
+        station_request,
         var,
         extent=station_extent,
     )
     data = mask_stations_to_region(data, info.geometry)
-    if resolved_dt != datetime_str:
+    if resolved_dt != station_request:
         console.print(f"  → 自动选择最新时次: [cyan]{resolved_dt}[/cyan]")
     console.print(
         f"  → [green]{data.n_valid}[/green] 有效站点 (共 {data.n_stations} 站)"
@@ -209,6 +327,17 @@ def run_overlay(
             f"  → 超标阈值: {threshold}, 超标站点: [red]{n_exceed}[/red]"
         )
 
+    if output is None and sensor == "gems":
+        output = (
+            f"/tmp/rsplot_overlay_gems_{info.name}_{product}_"
+            f"{datetime_str}_{resolved_dt}.png"
+        )
+    if title is None and sensor == "gems":
+        period = "daily mean" if len(datetime_str) == 8 else "scan"
+        title = (
+            f"GEMS {product.upper()} {datetime_str} {period} CST + "
+            f"Station {var} {resolved_dt} CST - {info.name}"
+        )
     if output is None:
         output = f"/tmp/rsplot_overlay_{info.name}_{product}_{resolved_dt}.png"
     unit = STATION_VAR_META[var][0]
@@ -216,9 +345,9 @@ def run_overlay(
 
     console.print("\n[bold]绘图中...[/bold]")
     plot_overlay(
-        prepared.lon,
-        prepared.lat,
-        prepared.values,
+        display_lon,
+        display_lat,
+        display_grid,
         data,
         info,
         raster_cmap=use_cmap,
@@ -233,6 +362,7 @@ def run_overlay(
         hcho_cmap_file=cfg.hcho_cmap_file,
         title=title,
         output=output,
+        **({"coverage_geometry": display_support} if sensor == "gems" else {}),
     )
     console.print(f"\n[bold green]✓ 已保存:[/bold green] {output}")
 
@@ -243,15 +373,14 @@ def run_overlay(
         prod_info=prod_info,
         LON=prepared.lon,
         LAT=prepared.lat,
-        grid=prepared.values,
-        swath_meta={
-            "n_pixels": int(swath.n_pixels),
-            "n_files": int(swath.n_files),
-            "n_broken": int(swath.n_broken),
-            "qa_threshold": use_qa,
-            "cloud_fraction_max": cf,
-            "resolution_deg": use_res,
-        },
+        grid=statistics_grid
+        if statistics_grid is not None
+        else prepared.values,
+        swath_meta=swath_meta,
+        time_matching=pairing,
+        display_grid=display_grid,
+        display_lon=display_lon,
+        display_lat=display_lat,
         raster_vmin=use_vmin,
         raster_vmax=use_vmax,
         data=data,