Sun Path & Environmental Analysis 是一个面向建筑师与设计师的环境分析技能，通过一组 Python 脚本提供日照、阴影与热舒适相关的计算和可视化能力。
用途 该技能用于建筑与环境设计中的日照分析，包括太阳位置计算、太阳轨迹图、建筑阴影模拟、全年日照小时统计、地形阴影计算以及热舒适评估。
依赖 该技能需要 Python 及以下库：pysolar（太阳计算）、matplotlib（绘图）、pytz（时区处理）、shapely（阴影几何计算）、numpy（数学运算）、rasterio（地形/DEM 阴影，DEM 功能可选）。OpenClaw 不会自动安装 Python 包。安装该技能（例如通过 clawhub install sun-path）后，需在技能目录中或指定其路径运行一次：pip install -r requirements.txt。若脚本报 ModuleNotFoundError，请从上述列表或 requirements.txt 中安装缺失的包。
向 Telegram 发送图片 该技能在 OpenClaw Telegram 对话中使用。生成图片的脚本（plot_sunpath.py、shadow_calc.py、comfort_calc.py、annual_sun_hours.py --output、terrain_shadow.py --plot）会将 PNG/JPG 写入你传入的路径。请使用 --output（或 --plot 并使用脚本默认图片路径）运行脚本，然后通过 OpenClaw 的 message/media 工具把该图片文件发送给用户，使其在聊天中可见。
OpenClaw 允许路径：message 工具只能发送允许目录（~/.openclaw/media/、~/.openclaw/agents/ 或 /tmp）中的文件。请始终传入这些目录下的输出路径（例如 --output ~/.openclaw/media/sunpath.png 或 /tmp/shadow.png）；不要使用技能安装目录，否则发送会失败。
智能体行为：当用户询问太阳位置、太阳轨迹图、阴影、全年日照小时图、舒适度图或地形阴影时，直接用 exec 运行对应脚本，并传入允许目录下的图片输出路径，然后把生成的 PNG/JPG 发送给用户。无需请求确认，直接执行并返回图片和简短摘要。
使用方式
-
计算太阳位置 获取指定位置当前的方位角与高度角。 python3 scripts/sun_calc.py --lat 34.05 --lon -118.24 --timezone "America/Los_Angeles"
-
生成太阳轨迹图 创建显示全年太阳路径的极坐标图。 python3 scripts/plot_sunpath.py --lat 34.05 --lon -118.24 --output sunpath.png
-
阴影分析（二维） 模拟简单建筑（长方体）在特定时刻投射的阴影。参数：--lat、--lon 为位置坐标；--time 为 ISO 格式日期/时间（如 "2024-06-21T12:00:00"）或 "now"；--width、--depth 为建筑底面尺寸（米）；--height 为建筑高度（米）；--rotation 为从北顺时针旋转角度；--output 为输出图片文件名。 python3 scripts/shadow_calc.py --lat 34.05 --lon -118.24 --time "2024-06-21T15:00:00" --width 15 --depth 10 --height 20 --rotation 45 --output shadow_analysis.png
-
某点全年日照/阴影小时数 计算某点每年处于直射阳光、建筑阴影或夜晚（太阳在地平线以下）的小时数。使用与阴影分析相同的长方体建筑和二维阴影模型；点以距建筑中心的米数给出。参数：--lat、--lon 为位置坐标；--width、--depth、--height、--rotation 为建筑尺寸与旋转（同阴影分析）；--point-x、--point-y 为待评估点（距建筑中心米数；例如旋转为 0 时，北为正 X）；--year 为年份（默认当前年）；--interval 为采样间隔分钟数（默认 60；越小越精确但越慢）；--timezone 为全年时区（如 Asia/Shanghai）；--output 可选，将月度柱状图（日照/阴影/夜晚小时）保存到该文件。
示例：建筑中心以北 15 米处，上海，2024 年
python3 scripts/annual_sun_hours.py --lat 31.23 --lon 121.47 --width 10 --depth 10 --height 20 --point-x 15 --point-y 0 --year 2024 --timezone Asia/Shanghai
带月度图表
python3 scripts/annual_sun_hours.py --lat 31.23 --lon 121.47 --width 10 --depth 10 --height 20 --point-x 15 --point-y 0 --year 2024 --timezone Asia/Shanghai --output annual_hours.png 输出：处于阳光、阴影和夜晚的总小时数，以及可选的月度细分图表。
- 地形阴影（DEM） 根据 GeoTIFF DEM 计算给定时刻地形上的二值阴影（阳光 vs 阴影）。使用太阳位置和光线投射；适合中等 DEM 尺寸（对于 1GB 内存，网格保持在约 2000×2000 以下或处理更小的裁剪区域）。参数：dem 为 GeoTIFF DEM 路径；--lat、--lon 为太阳位置经纬度；--time 为 ISO 格式时间或 "now"（先按 --timezone 解释再转换为 UTC）；--timezone 为时区名称（如 Asia/Shanghai）；--output 为输出 GeoTIFF 路径（默认 terrain_shadow.tif）；--plot 同时保存 PNG 可视化；--step 为光线步长（像素，默认 1；越大越快、精度越低）。
示例：当地正午阴影
python3 scripts/terrain_shadow.py /path/to/dem.tif --lat 31.23 --lon 121.47 --time "2024-06-21T12:00:00" --timezone Asia/Shanghai --output shadow.tif --plot
- 舒适度分析（焓湿图） 在焓湿图上可视化当前温度与湿度，以评估热舒适。参数：--temp 为干球温度（°C）；--rh 为相对湿度（%）；--output 为输出图片文件名。 python3 scripts/comfort_calc.py --temp 28 --rh 60 --output comfort_chart.png
示例 用户：“洛杉矶现在的太阳位置是什么？” 操作：确定洛杉矶坐标（纬度 34.05，经度 -118.24）；运行 sun_calc.py；返回方位角与高度角。
用户：“给我看上海冬至下午 2 点一栋 20 米高、10x10 米建筑的阴影。” 操作：确定坐标（上海：31.23，121.47）；确定时间（冬至：2024-12-21 14:00）；运行 shadow_calc.py： python3 scripts/shadow_calc.py --lat 31.23 --lon 121.47 --time "2024-12-21T14:00:00" --width 10 --depth 10 --height 20 --output shanghai_shadow.png 返回图片。
用户：“新加坡现在舒适吗？温度 32C，湿度 80%。” 操作：运行 comfort_calc.py： python3 scripts/comfort_calc.py --temp 32 --rh 80 --output singapore_comfort.png 返回图片和分析。
用户：“这个点每年有多少小时在阳光 vs 阴影下？建筑 10×10×20 米，点在北侧 15 米。” 操作：用场地经纬度、建筑尺寸和 --point-x 15 --point-y 0 运行 annual_sun_hours.py；返回打印摘要（直射阳光/阴影/夜晚小时），如使用了 --output 可选返回月度图表。
用户：“我有 DEM，这个场地下午 2 点地形哪里在阴影中？” 操作：用 DEM 路径、场地 --lat/--lon 和 --time（如当地 14:00）、--timezone 以及 --output/--plot 运行 terrain_shadow.py；返回阴影栅格和/或 PNG 及简短摘要。
适用场景 适用于建筑方案阶段的日照与阴影研究、场地全年日照条件评估、地形遮挡分析以及室内外热舒适初步判断。
限制 依赖 Python 及多个第三方库，需手动安装；地形阴影功能对 DEM 尺寸和内存有限制；阴影模型基于简单长方体建筑和二维模型；图片发送受 OpenClaw 允许目录限制。