rsplot 0.2.3__tar.gz → 0.2.5__tar.gz

{rsplot-0.2.3 → rsplot-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rsplot
-Version: 0.2.3
+Version: 0.2.5
 Summary: CLI tool for plotting Remote Sensing data, designed for Agent.
 Project-URL: Repository, https://git.lug.ustc.edu.cn/yaoyhu/rsplot
 Project-URL: GitHub, https://github.com/yaoyhu/rsplot
@@ -258,16 +258,61 @@ uv run rsplot --help
 
 ## Configuration
 
-For satellite basemaps, set a TianDiTu API key:
+`rsplot` does not ship site-specific data paths. Configure local satellite,
+station, boundary, and font paths with a TOML file:
+
+```bash
+mkdir -p ~/.config/rsplot
+cp config.example.toml ~/.config/rsplot/config.toml
+```
+
+Then edit `~/.config/rsplot/config.toml`:
+
+```toml
+[paths]
+geojson_dir = "/path/to/geojson"
+font_dir = "/path/to/fonts"
+# hcho_cmap_file = "/path/to/256x3_rgb_table.txt"
+
+[paths.data_dirs]
+no2 = "/path/to/NO2"
+o3 = "/path/to/O3"
+o3pr = "/path/to/O3PR"
+hcho = "/path/to/HCHO"
+guokong = "/path/to/guokong_combine"
+
+# Optional satellite basemap key. Leave commented unless you have a real key.
+# [tianditu]
+# api_key = "your-real-key"
+```
+
+You can also point to a different config file:
+
+```bash
+export RSPLOT_CONFIG="/path/to/rsplot.toml"
+```
+
+Environment variables override TOML values:
 
 ```bash
 export TIANDITU_API_KEY="your-key"
+export RSPLOT_GEOJSON_DIR="/path/to/geojson"
+export RSPLOT_FONT_DIR="/path/to/fonts"
+export RSPLOT_DATA_DIR_NO2="/path/to/NO2"
+export RSPLOT_DATA_DIR_O3="/path/to/O3"
+export RSPLOT_DATA_DIR_O3PR="/path/to/O3PR"
+export RSPLOT_DATA_DIR_HCHO="/path/to/HCHO"
+export RSPLOT_DATA_DIR_GUOKONG="/path/to/guokong_combine"
+export RSPLOT_HCHO_CMAP_FILE="/path/to/256x3_rgb_table.txt"
 ```
 
+Command-line directory options, such as `--data-dir`, take precedence for the
+command being run. If no TianDiTu API key is configured, use `--basemap none`
+to avoid requesting satellite tiles.
+
 ## Usage
 
-The examples below assume the command is running on a USTC server or in an
-environment with equivalent data paths configured.
+The examples below assume data paths are configured and readable.
 
 ```bash
 # Show available commands and options.
@@ -296,6 +341,9 @@ rsplot fnr 合肥 20260114 -o fnr_hefei.png
 
 # Plot an FNR regime map with an explicit date range.
 rsplot fnr 长三角 20260101-20260130 -o fnr_yrd_202601.png
+
+# Override FNR regime thresholds for agent-driven sensitivity tests.
+rsplot fnr 合肥 20260114 --voc-threshold 0.8 --nox-threshold 1.8 --display-max 5 -o fnr_hefei_sensitivity.png
 ```
 
 When `-o/--output` is provided, `rsplot` writes the image to that path and also

{rsplot-0.2.3 → rsplot-0.2.5}/README.md

@@ -31,16 +31,61 @@ uv run rsplot --help
 
 ## Configuration
 
-For satellite basemaps, set a TianDiTu API key:
+`rsplot` does not ship site-specific data paths. Configure local satellite,
+station, boundary, and font paths with a TOML file:
+
+```bash
+mkdir -p ~/.config/rsplot
+cp config.example.toml ~/.config/rsplot/config.toml
+```
+
+Then edit `~/.config/rsplot/config.toml`:
+
+```toml
+[paths]
+geojson_dir = "/path/to/geojson"
+font_dir = "/path/to/fonts"
+# hcho_cmap_file = "/path/to/256x3_rgb_table.txt"
+
+[paths.data_dirs]
+no2 = "/path/to/NO2"
+o3 = "/path/to/O3"
+o3pr = "/path/to/O3PR"
+hcho = "/path/to/HCHO"
+guokong = "/path/to/guokong_combine"
+
+# Optional satellite basemap key. Leave commented unless you have a real key.
+# [tianditu]
+# api_key = "your-real-key"
+```
+
+You can also point to a different config file:
+
+```bash
+export RSPLOT_CONFIG="/path/to/rsplot.toml"
+```
+
+Environment variables override TOML values:
 
 ```bash
 export TIANDITU_API_KEY="your-key"
+export RSPLOT_GEOJSON_DIR="/path/to/geojson"
+export RSPLOT_FONT_DIR="/path/to/fonts"
+export RSPLOT_DATA_DIR_NO2="/path/to/NO2"
+export RSPLOT_DATA_DIR_O3="/path/to/O3"
+export RSPLOT_DATA_DIR_O3PR="/path/to/O3PR"
+export RSPLOT_DATA_DIR_HCHO="/path/to/HCHO"
+export RSPLOT_DATA_DIR_GUOKONG="/path/to/guokong_combine"
+export RSPLOT_HCHO_CMAP_FILE="/path/to/256x3_rgb_table.txt"
 ```
 
+Command-line directory options, such as `--data-dir`, take precedence for the
+command being run. If no TianDiTu API key is configured, use `--basemap none`
+to avoid requesting satellite tiles.
+
 ## Usage
 
-The examples below assume the command is running on a USTC server or in an
-environment with equivalent data paths configured.
+The examples below assume data paths are configured and readable.
 
 ```bash
 # Show available commands and options.
@@ -69,6 +114,9 @@ rsplot fnr 合肥 20260114 -o fnr_hefei.png
 
 # Plot an FNR regime map with an explicit date range.
 rsplot fnr 长三角 20260101-20260130 -o fnr_yrd_202601.png
+
+# Override FNR regime thresholds for agent-driven sensitivity tests.
+rsplot fnr 合肥 20260114 --voc-threshold 0.8 --nox-threshold 1.8 --display-max 5 -o fnr_hefei_sensitivity.png
 ```
 
 When `-o/--output` is provided, `rsplot` writes the image to that path and also

{rsplot-0.2.3 → rsplot-0.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rsplot"
-version = "0.2.3"
+version = "0.2.5"
 description = "CLI tool for plotting Remote Sensing data, designed for Agent."
 authors = [
     { name = "Yaoyao Hu", email = "yaoyhu@mail.ustc.edu.cn" },

{rsplot-0.2.3 → rsplot-0.2.5}/src/rsplot/cli.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
-from importlib.metadata import PackageNotFoundError, version
 import math
+from importlib.metadata import PackageNotFoundError, version
 from typing import Any
 
 import numpy as np
@@ -47,17 +47,20 @@ def _default_raster_n_min(product: str, window_n: int) -> int:
         return max(3, math.ceil(window_n * 0.25))
     return max(3, window_n // 2)
 
+
 def _get_version() -> str:
     try:
         return version("rsplot")
     except PackageNotFoundError:
         return "unknown"
 
+
 def _version_callback(value: bool) -> None:
     if value:
         console.print(f"rsplot {_get_version()}")
         raise typer.Exit()
 
+
 @app.callback()
 def _callback(
     show_version: bool = typer.Option(
@@ -326,9 +329,7 @@ def raster(
         coverage_days = {
             "min": int(covered.min()) if len(covered) else 0,
             "max": int(covered.max()) if len(covered) else 0,
-            "mean": (
-                round(float(covered.mean()), 1) if len(covered) else 0.0
-            ),
+            "mean": (round(float(covered.mean()), 1) if len(covered) else 0.0),
         }
         if len(covered):
             coverage_days.update(
@@ -390,9 +391,7 @@ def raster(
     # --- 7. Plot ---
     if output is None:
         if window_mode:
-            output = (
-                f"/tmp/rsplot_{info.name}_{dates[0]}_{dates[-1]}.png"
-            )
+            output = f"/tmp/rsplot_{info.name}_{dates[0]}_{dates[-1]}.png"
         else:
             output = f"/tmp/rsplot_{info.name}_{dates[0]}.png"
 
@@ -414,6 +413,7 @@ def raster(
         vmax=use_vmax,
         basemap=use_basemap,
         tianditu_key=cfg.tianditu_key,
+        hcho_cmap_file=cfg.hcho_cmap_file,
         title=title,
         output=output,
         colorbar_label=colorbar_label,
@@ -533,17 +533,17 @@ def station(
     if resolved_dt != datetime_str:
         console.print(f"  → 自动选择最新时次: [cyan]{resolved_dt}[/cyan]")
     console.print(
-        f"  → [green]{data.n_valid}[/green] 有效站点 "
-        f"(共 {data.n_stations} 站)"
+        f"  → [green]{data.n_valid}[/green] 有效站点 (共 {data.n_stations} 站)"
     )
 
     # --- 5. Exceedance threshold ---
     threshold = get_exceedance_threshold(var)
     if threshold is not None:
-        n_exceed = int(np.sum(data.values[np.isfinite(data.values)] > threshold))
+        n_exceed = int(
+            np.sum(data.values[np.isfinite(data.values)] > threshold)
+        )
         console.print(
-            f"  → 超标阈值: {threshold}, "
-            f"超标站点: [red]{n_exceed}[/red]"
+            f"  → 超标阈值: {threshold}, 超标站点: [red]{n_exceed}[/red]"
         )
 
     # --- 6. Plot ---
@@ -590,7 +590,7 @@ def station(
         datetime_str=resolved_dt,
         threshold=threshold,
         unit=unit,
-        cities_gdf=_load_city(cfg.geojson_dir),
+        cities_gdf=_load_city(cfg.require_geojson_dir()),
         output=output,
     )
     emit_result(result, output)
@@ -662,8 +662,12 @@ def overlay(
         "-b",
         help="底图控制: satellite / none (覆盖级别默认)",
     ),
-    vmin: float | None = typer.Option(None, "--vmin", help="卫星 colorbar 最小值"),
-    vmax: float | None = typer.Option(None, "--vmax", help="卫星 colorbar 最大值"),
+    vmin: float | None = typer.Option(
+        None, "--vmin", help="卫星 colorbar 最小值"
+    ),
+    vmax: float | None = typer.Option(
+        None, "--vmax", help="卫星 colorbar 最大值"
+    ),
     cmap: str | None = typer.Option(None, "--cmap", help="卫星 colormap 名称"),
     smooth: float | None = typer.Option(
         None, "--smooth", help="高斯平滑 sigma"
@@ -771,7 +775,9 @@ def overlay(
         info.extent[2] - buf,
         info.extent[3] + buf,
     )
-    console.print(f"\n[bold]读取卫星数据:[/bold] {use_raster_dir} (产品: {product})")
+    console.print(
+        f"\n[bold]读取卫星数据:[/bold] {use_raster_dir} (产品: {product})"
+    )
     console.print(f"  日期: {date}, QA > {use_qa}")
     swath = reader.read(use_raster_dir, date, read_extent, qa_threshold=use_qa)
     console.print(
@@ -826,23 +832,22 @@ def overlay(
     if resolved_dt != datetime_str:
         console.print(f"  → 自动选择最新时次: [cyan]{resolved_dt}[/cyan]")
     console.print(
-        f"  → [green]{data.n_valid}[/green] 有效站点 "
-        f"(共 {data.n_stations} 站)"
+        f"  → [green]{data.n_valid}[/green] 有效站点 (共 {data.n_stations} 站)"
     )
 
     # --- 10. Exceedance threshold ---
     threshold = get_exceedance_threshold(var)
     if threshold is not None:
-        n_exceed = int(np.sum(data.values[np.isfinite(data.values)] > threshold))
+        n_exceed = int(
+            np.sum(data.values[np.isfinite(data.values)] > threshold)
+        )
         console.print(
             f"  → 超标阈值: {threshold}, 超标站点: [red]{n_exceed}[/red]"
         )
 
     # --- 11. Plot ---
     if output is None:
-        output = (
-            f"/tmp/rsplot_overlay_{info.name}_{product}_{resolved_dt}.png"
-        )
+        output = f"/tmp/rsplot_overlay_{info.name}_{product}_{resolved_dt}.png"
 
     unit = STATION_VAR_META[var][0]
     station_label = f"{var} ({unit})" if unit else var
@@ -863,6 +868,7 @@ def overlay(
         dpi=use_dpi,
         basemap=use_basemap,
         tianditu_key=cfg.tianditu_key,
+        hcho_cmap_file=cfg.hcho_cmap_file,
         title=title,
         output=output,
     )
@@ -891,7 +897,7 @@ def overlay(
         datetime_str=resolved_dt,
         threshold=threshold,
         unit=unit,
-        cities_gdf=_load_city(cfg.geojson_dir),
+        cities_gdf=_load_city(cfg.require_geojson_dir()),
         output=output,
     )
     emit_result(result, output)
@@ -1047,9 +1053,7 @@ def recent(
             data_dir if data_dir is not None else cfg.get_data_dir("guokong")
         )
         unit = STATION_VAR_META[var][0]
-        console.print(
-            f"\n[bold]统计站点:[/bold] {use_data_dir} (变量: {var})"
-        )
+        console.print(f"\n[bold]统计站点:[/bold] {use_data_dir} (变量: {var})")
         daily = summarize_recent_station(
             region=info,
             data_dir=use_data_dir,
@@ -1104,6 +1108,21 @@ def fnr(
         help="最小平均 NO2 柱浓度阈值 (x10^15 molec/cm2)；"
         "低于此值的像元 FNR 不可信，输出为 NaN",
     ),
+    voc_threshold: float = typer.Option(
+        1.0,
+        "--voc-threshold",
+        help="VOC-limited 分级阈值：FNR 小于该值判为 VOC-limited",
+    ),
+    nox_threshold: float = typer.Option(
+        2.0,
+        "--nox-threshold",
+        help="NOx-limited 分级阈值：FNR 大于该值判为 NOx-limited",
+    ),
+    display_max: float = typer.Option(
+        6.0,
+        "--display-max",
+        help="FNR 图例显示上限，必须大于 --nox-threshold",
+    ),
     # --- overrides ---
     level: str | None = typer.Option(
         None,
@@ -1155,7 +1174,11 @@ def fnr(
         rsplot fnr 安徽   20260131 --days 30      (30日窗口)
         rsplot fnr 长三角 20260101-20260130       (显式范围)
     """
-    from rsplot.fnr import compute_fnr, parse_date_window
+    from rsplot.fnr import (
+        compute_fnr,
+        parse_date_window,
+        validate_fnr_thresholds,
+    )
     from rsplot.geo.boundaries import resolve_region
     from rsplot.plotting.fnr import plot_fnr
     from rsplot.plotting.styles import setup_fonts
@@ -1179,11 +1202,27 @@ def fnr(
             f"[red]--n-min ({use_n_min}) 大于窗口天数 ({window_n})[/red]"
         )
         raise typer.Exit(1)
+    try:
+        use_voc_threshold, use_nox_threshold, use_display_max = (
+            validate_fnr_thresholds(
+                voc_threshold=voc_threshold,
+                nox_threshold=nox_threshold,
+                display_max=display_max,
+            )
+        )
+    except ValueError as e:
+        console.print(f"[red]FNR 阈值错误: {e}[/red]")
+        raise typer.Exit(1) from e
 
     console.print(
         f"[bold]时间窗口:[/bold] {dates[0]} ~ {dates[-1]} "
         f"({window_n} 天，每像元至少 {use_n_min} 天有效)"
     )
+    console.print(
+        f"[bold]FNR 分级:[/bold] VOC<{use_voc_threshold:g}, "
+        f"transition {use_voc_threshold:g}~{use_nox_threshold:g}, "
+        f"NOx>{use_nox_threshold:g}"
+    )
 
     # --- 3. Resolve region ---
     console.print(f"[bold]解析区域:[/bold] {region}")
@@ -1209,14 +1248,16 @@ def fnr(
 
     # --- 5. Resolve data dirs ---
     use_no2_dir = (
-        raster_dir_no2 if raster_dir_no2 is not None else cfg.get_data_dir("no2")
+        raster_dir_no2
+        if raster_dir_no2 is not None
+        else cfg.get_data_dir("no2")
     )
     use_hcho_dir = (
         raster_dir_hcho
         if raster_dir_hcho is not None
         else cfg.get_data_dir("hcho")
     )
-    console.print(f"\n[bold]读取数据:[/bold]")
+    console.print("\n[bold]读取数据:[/bold]")
     console.print(f"  NO2 : {use_no2_dir}")
     console.print(f"  HCHO: {use_hcho_dir}")
 
@@ -1239,12 +1280,10 @@ def fnr(
     n_found_no2 = len(fnr_out.dates_found_no2)
     n_found_hcho = len(fnr_out.dates_found_hcho)
     console.print(
-        f"  → NO2 有效天数 {n_found_no2}/{window_n} "
-        f"(失败 {n_fail_no2})"
+        f"  → NO2 有效天数 {n_found_no2}/{window_n} (失败 {n_fail_no2})"
     )
     console.print(
-        f"  → HCHO 有效天数 {n_found_hcho}/{window_n} "
-        f"(失败 {n_fail_hcho})"
+        f"  → HCHO 有效天数 {n_found_hcho}/{window_n} (失败 {n_fail_hcho})"
     )
     if use_n_min > min(n_found_no2, n_found_hcho):
         console.print(
@@ -1270,7 +1309,12 @@ def fnr(
     )
 
     from rsplot.fnr import regime_percentages
-    pct = regime_percentages(fnr_out.fnr)
+
+    pct = regime_percentages(
+        fnr_out.fnr,
+        voc_threshold=use_voc_threshold,
+        nox_threshold=use_nox_threshold,
+    )
     console.print(
         f"  → Regime: [red]VOC-limited {pct['voc_limited']}%[/red] | "
         f"[yellow]transition {pct['transition']}%[/yellow] | "
@@ -1279,9 +1323,7 @@ def fnr(
 
     # --- 7. Plot ---
     if output is None:
-        output = (
-            f"/tmp/rsplot_fnr_{info.name}_{dates[0]}_{dates[-1]}.png"
-        )
+        output = f"/tmp/rsplot_fnr_{info.name}_{dates[0]}_{dates[-1]}.png"
 
     subtitle = (
         f"{dates[0]}~{dates[-1]}  ·  N_days={window_n} "
@@ -1300,6 +1342,9 @@ def fnr(
         title=title,
         output=output,
         subtitle=subtitle,
+        voc_threshold=use_voc_threshold,
+        nox_threshold=use_nox_threshold,
+        display_max=use_display_max,
     )
     console.print(f"\n[bold green]✓ 已保存:[/bold green] {output}")
 
@@ -1309,6 +1354,9 @@ def fnr(
         fnr_out=fnr_out,
         res=use_res,
         output=output,
+        voc_threshold=use_voc_threshold,
+        nox_threshold=use_nox_threshold,
+        display_max=use_display_max,
     )
     emit_result(result, output)
 

{rsplot-0.2.3 → rsplot-0.2.5}/src/rsplot/config.py

@@ -1,7 +1,8 @@
 """Configuration management for rsplot.
 
-# TODO: Loads defaults from ~/.config/rsplot/config.toml if present,
-CLI arguments override everything.
+Runtime paths are intentionally configured outside the package. The loader
+merges safe built-in defaults, TOML config files, environment variables, and
+finally CLI overrides handled by command functions.
 """
 
 from __future__ import annotations
@@ -19,21 +20,20 @@ else:
 
 
 # ---------------------------------------------------------------------------
-# Default paths
+# Safe built-in path defaults
 # ---------------------------------------------------------------------------
-DEFAULT_DATA_DIRS: dict[str, str] = {
-    "no2": "/satellite/exports2/yaoyhu/NO2",
-    "o3": "/satellite/exports2/yaoyhu/O3",
-    "o3pr": "/satellite/exports2/yaoyhu/O3PR",
-    "hcho": "/satellite/exports2/yaoyhu/HCHO",
-    "guokong": "/home/zzgsg/data/guokong_combine",
-}
-DEFAULT_GEOJSON_DIR = "/satellite/d4/yaoyhu/tiandi"
-DEFAULT_FONT_DIR = "/satellite/d4/yaoyhu/fonts"
+KNOWN_DATA_PRODUCTS = ("no2", "o3", "o3pr", "hcho", "guokong")
+
+DEFAULT_DATA_DIRS: dict[str, str] = {}
+DEFAULT_GEOJSON_DIR = None
+DEFAULT_FONT_DIR = None
+DEFAULT_HCHO_CMAP_FILE = None
 DEFAULT_TIANDITU_KEY = None
 
 
 CONFIG_PATH = Path.home() / ".config" / "rsplot" / "config.toml"
+CONFIG_ENV_VAR = "RSPLOT_CONFIG"
+HCHO_CMAP_FILE_ENV = "RSPLOT_HCHO_CMAP_FILE"
 
 
 # ---------------------------------------------------------------------------
@@ -146,15 +146,17 @@ DEFAULT_KEY_REGIONS: dict[str, list[str]] = {
 # ---------------------------------------------------------------------------
 @dataclass
 class AppConfig:
-    """Merged configuration (file defaults + CLI overrides)."""
+    """Merged configuration from files and environment variables."""
 
     # paths (per-product data directories)
     data_dirs: dict[str, str] = field(
         default_factory=lambda: dict(DEFAULT_DATA_DIRS)
     )
-    geojson_dir: str = DEFAULT_GEOJSON_DIR
-    font_dir: str = DEFAULT_FONT_DIR
+    geojson_dir: str | None = DEFAULT_GEOJSON_DIR
+    font_dir: str | None = DEFAULT_FONT_DIR
+    hcho_cmap_file: str | None = DEFAULT_HCHO_CMAP_FILE
     tianditu_key: str | None = DEFAULT_TIANDITU_KEY
+    config_files: list[str] = field(default_factory=list)
 
     # plotting defaults
     dpi: int = 300
@@ -167,43 +169,82 @@ class AppConfig:
 
     @classmethod
     def load(cls) -> AppConfig:
-        """Load config from TOML file, falling back to defaults."""
+        """Load config from TOML files and environment variables.
+
+        Merge order:
+        1. safe built-in defaults
+        2. ~/.config/rsplot/config.toml, if present
+        3. RSPLOT_CONFIG, if set
+        4. environment variable path/API-key overrides
+        """
         cfg = cls()
-        if CONFIG_PATH.exists():
-            with open(CONFIG_PATH, "rb") as f:
+        for path in _config_paths():
+            with open(path, "rb") as f:
                 data = tomllib.load(f)
             cfg._apply_toml(data)
-        # Environment variable overrides (per-product: RSPLOT_DATA_DIR_NO2, etc.)
-        for product in list(cfg.data_dirs):
+            cfg.config_files.append(str(path))
+
+        cfg._apply_env()
+        return cfg
+
+    def _apply_env(self) -> None:
+        """Apply environment variable overrides."""
+        products = set(KNOWN_DATA_PRODUCTS) | set(self.data_dirs)
+        for product in sorted(products):
             env_key = f"RSPLOT_DATA_DIR_{product.upper()}"
             if v := os.environ.get(env_key):
-                cfg.data_dirs[product] = v
+                self.data_dirs[product] = _normalize_path(v)
         if v := os.environ.get("RSPLOT_GEOJSON_DIR"):
-            cfg.geojson_dir = v
+            self.geojson_dir = _normalize_path(v)
+        if v := os.environ.get("RSPLOT_FONT_DIR"):
+            self.font_dir = _normalize_path(v)
+        if v := os.environ.get(HCHO_CMAP_FILE_ENV):
+            self.hcho_cmap_file = _normalize_path(v)
         if v := os.environ.get("TIANDITU_API_KEY"):
-            cfg.tianditu_key = v
-        return cfg
+            self.tianditu_key = v
 
     def get_data_dir(self, product: str) -> str:
         """Return data directory for a product, or raise if not configured."""
         key = product.lower()
-        if key in self.data_dirs:
-            return self.data_dirs[key]
-        available = ", ".join(self.data_dirs)
+        dir_path = self.data_dirs.get(key)
+        if dir_path:
+            return dir_path
+
+        configured = (
+            ", ".join(sorted(k for k, v in self.data_dirs.items() if v))
+            or "none"
+        )
         raise ValueError(
             f"No data directory configured for product '{product}'. "
-            f"Available: {available}"
+            f"Set [paths.data_dirs].{key} in {CONFIG_PATH}, set "
+            f"RSPLOT_DATA_DIR_{key.upper()}, point {CONFIG_ENV_VAR} to a "
+            "TOML config file, or pass the command-specific data directory "
+            f"option. Known products: {', '.join(KNOWN_DATA_PRODUCTS)}. "
+            f"Configured products: {configured}."
+        )
+
+    def require_geojson_dir(self) -> str:
+        """Return the boundary GeoJSON directory, or raise with guidance."""
+        if self.geojson_dir:
+            return self.geojson_dir
+        raise ValueError(
+            "GeoJSON boundary directory is not configured. Set "
+            f"[paths].geojson_dir in {CONFIG_PATH}, set RSPLOT_GEOJSON_DIR, "
+            f"or point {CONFIG_ENV_VAR} to a TOML config file."
         )
 
     def _apply_toml(self, data: dict[str, Any]) -> None:
         paths = data.get("paths", {})
         data_dirs = paths.get("data_dirs", {})
         for product, dir_path in data_dirs.items():
-            self.data_dirs[product.lower()] = dir_path
+            if dir_path:
+                self.data_dirs[product.lower()] = _normalize_path(dir_path)
         if v := paths.get("geojson_dir"):
-            self.geojson_dir = v
+            self.geojson_dir = _normalize_path(v)
         if v := paths.get("font_dir"):
-            self.font_dir = v
+            self.font_dir = _normalize_path(v)
+        if v := paths.get("hcho_cmap_file"):
+            self.hcho_cmap_file = _normalize_path(v)
 
         td = data.get("tianditu", {})
         if v := td.get("api_key"):
@@ -220,6 +261,33 @@ class AppConfig:
             self.key_regions[name] = provinces
 
 
+def _config_paths() -> list[Path]:
+    """Return config files to load in priority order."""
+    paths: list[Path] = []
+    if CONFIG_PATH.exists():
+        paths.append(CONFIG_PATH)
+
+    if raw := os.environ.get(CONFIG_ENV_VAR):
+        path = Path(_normalize_path(raw))
+        if not path.exists():
+            raise FileNotFoundError(
+                f"{CONFIG_ENV_VAR} points to a missing config file: {path}"
+            )
+        try:
+            already_loaded = path.resolve() in {p.resolve() for p in paths}
+        except OSError:
+            already_loaded = path in paths
+        if not already_loaded:
+            paths.append(path)
+
+    return paths
+
+
+def _normalize_path(value: Any) -> str:
+    """Expand ~ and environment variables in configured path values."""
+    return os.path.expanduser(os.path.expandvars(str(value)))
+
+
 # ---------------------------------------------------------------------------
 # GB 3095-2026 Air Quality Limits (transitional phase, grade II)
 # ---------------------------------------------------------------------------
@@ -241,7 +309,7 @@ AQ_LIMITS_2026: dict[str, dict[str, float]] = {
 # ---------------------------------------------------------------------------
 AQI_COLORS: list[tuple[int, str]] = [
     # (upper bound, hex color)
-    (50, "#00e400"),   # 优 / green
+    (50, "#00e400"),  # 优 / green
     (100, "#ffff00"),  # 良 / yellow
     (150, "#ff7e00"),  # 轻度污染 / orange
     (200, "#ff0000"),  # 中度污染 / red