sunlight-analysis

name	sunlight-analysis
version	1.4.1
description	生成太阳轨迹图，计算实时太阳位置，分析建筑阴影投射范围与全年日照时数，并提供热舒适度评估，适用于建筑设计与场地环境分析。当用户询问太阳位置、请求绘制太阳轨迹、分析建筑阴影、计算全年日照时间、评估热舒适度或进行地形阴影分析时触发。
author	qrost
permissions	["shell:exec"]

太阳轨迹与环境分析

本技能为建筑师和设计师提供全面的环境分析工具。

依赖项

本技能需要 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 消息/媒体工具将该图片文件发送给用户，使其在聊天中可见。

OpenClaw 允许的路径： 消息工具只能发送允许目录下的文件（~/.openclaw/media/、~/.openclaw/agents/ 或 /tmp）。输出路径请始终指定为上述目录之一（例如 --output ~/.openclaw/media/sunpath.png 或 /tmp/shadow.png）；不要使用技能安装目录，否则发送将失败。

Agent 行为： 当用户请求太阳位置、太阳轨迹图、阴影分析、全年日照时数图表、舒适度图表或地形阴影时，直接运行对应脚本（使用 exec），并将图片输出路径指定到允许目录下；然后将生成的 PNG/JPG 发送给用户。无需请求确认；直接执行并返回图片及简要说明。

使用方法

1. 计算太阳位置

获取指定位置的当前方位角和高度角。

python3 scripts/sun_calc.py --lat 34.05 --lon -118.24 --timezone "America/Los_Angeles"

2. 生成太阳轨迹图

创建极坐标图，展示太阳全年运行轨迹。

python3 scripts/plot_sunpath.py --lat 34.05 --lon -118.24 --output sunpath.png

3. 阴影分析（2D）

模拟指定时间下简单建筑体（长方体）的阴影投射。

参数：

• --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

4. 全年日照/阴影时数计算

计算指定点全年的直射阳光时数、建筑阴影时数或夜间（太阳位于地平线以下）时数。使用与阴影分析相同的建筑长方体和 2D 阴影模型；点的位置以建筑中心为原点、以米为单位表示。

参数：

• --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

输出：日照总时数、阴影总时数和夜间总时数，以及可选的月度分布图表。

5. 地形阴影（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

6. 舒适度分析（焓湿图）

在焓湿图上可视化当前温度和湿度，评估热舒适度。

参数：

• --temp：干球温度（°C）。
• --rh：相对湿度（%）。
• --output：输出图片文件名。

python3 scripts/comfort_calc.py --temp 28 --rh 60 --output comfort_chart.png

示例

用户： "洛杉矶现在的太阳位置是什么？" 操作：

1. 确定洛杉矶的坐标（纬度：34.05，经度：-118.24）。
2. 运行 sun_calc.py。
3. 返回方位角和高度角。

用户： "显示冬至日下午 2 点上海一栋 20 米高、10×10 米建筑的阴影。" 操作：

1. 确定坐标（上海：31.23, 121.47）。

2. 确定时间（冬至：2024-12-21 14:00）。

3. 运行 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
   

4. 返回图片。

用户： "新加坡现在舒适吗？温度 32°C，湿度 80%。" 操作：

1. 运行 comfort_calc.py：

   python3 scripts/comfort_calc.py --temp 32 --rh 80 --output singapore_comfort.png
   

2. 返回图片和分析结果。

用户： "这个点全年的日照和阴影时数是多少？建筑 10×10×20 米，点在正北 15 米处。" 操作：

1. 运行 annual_sun_hours.py，传入场地经纬度、建筑尺寸和 --point-x 15 --point-y 0。
2. 返回打印的摘要（直射日照/阴影/夜间时数），如果使用了 --output 则同时返回月度图表。

用户： "下午 2 点这个场地哪些地形处于阴影中？我有 DEM 数据。" 操作：

1. 运行 terrain_shadow.py，传入 DEM 路径、场地 --lat/--lon、--time（例如当地时间 14:00）、--timezone，以及 --output/--plot。
2. 返回阴影栅格和/或 PNG 图片及简要说明。