技能使用指南

sunlight-analysis(阳光分析)Skill 是什么?如何安装使用?

阳光分析Skill 能一句话生成太阳轨迹图、模拟建筑阴影、统计全年日照时数、分析地形阴影并做热舒适度评估,覆盖太阳位置查询到焓湿图全流程,安装步骤、调用命令、竞品对比与常见问题一文讲清,建筑师与场地分析人员快速上手必备。

阳光分析Skillsunlight-analysis
8 个章节 约 15 分钟阅读 AI 智能生成

阳光分析Skill:一键生成太阳轨迹、建筑阴影与全年日照时数

  • 它是什么:一个面向建筑设计与场地环境分析的 AI 技能,基于 Python 计算太阳位置、绘制太阳轨迹图、模拟建筑阴影、统计全年日照时数,并给出热舒适度评估。
  • 核心能力:6 个独立脚本覆盖「太阳位置查询 → 轨迹可视化 → 2D 阴影 → 全年日照统计 → 地形阴影(DEM)→ 焓湿图舒适度」完整链路。
  • 调用方式:用自然语言向 AI 提需求(例如“上海冬至下午 2 点这栋楼的阴影”),技能会自动选择脚本、填好参数并执行,把图片发回对话。
  • 安装门槛:安装技能后需手动执行一次 pip install -r requirements.txt 补齐 6 个 Python 库,这是最容易卡住的一步。
  • 适合谁:建筑师、规划师、景观与场地分析人员,以及需要快速出日照/阴影示意图、但不想打开整套专业仿真软件的人。

该技能叫什么?如何下载安装 AI 技能提升开发效率?

基本信息

  • 中文名:阳光分析Skill
  • 英文名:sunlight-analysis
  • 技能 ID:14274
  • 版本:1.4.1
  • 作者:qrost
  • 权限:shell 执行(shell:exec)

它解决什么问题

传统流程里,算一个点的太阳高度角要查天文表,画太阳轨迹图要开专业软件,做建筑阴影和全年日照统计更是要建模、设材质、跑仿真,动辄几十分钟到几小时。而现实中大量问题其实很“轻”:这个房间冬至会不会被挡光?这块场地下午两点哪片区域在阴影里?某地今天太阳在哪个方位?

阳光分析Skill 把这些高频、轻量但计算明确的需求,压缩成一句自然语言 + 一条命令行。它会自己确定经纬度、时间、时区,调用对应脚本,最后把 PNG/JPG 图表直接发到对话里。

安装前提

  1. 技能需要运行在支持该技能的 AI 助手环境中(如 OpenClaw 类环境),并具备 shell 执行权限。
  2. 需要本地已安装 Python 3 环境。
  3. 需要 6 个 Python 依赖库:pysolar(太阳位置计算)、matplotlib(绘图)、pytz(时区处理)、shapely(阴影几何计算)、numpy(数学计算)、rasterio(地形/DEM 阴影分析,DEM 功能为可选项)。

安装步骤

  1. 安装技能本体:通过技能市场的安装入口完成安装,示例形式为 clawhub install sun-path(具体命令与入口以官方说明为准)。

  2. 补齐 Python 依赖:OpenClaw 不会自动帮你装 Python 包。安装技能后,请在技能目录中(或指定其路径)执行一次:

    pip install -r requirements.txt
    

    如果运行时出现 ModuleNotFoundError,按提示从上面的依赖列表或 requirements.txt 中补装缺失的包。

  3. 配置图片输出目录:消息工具只能发送允许目录下的文件,即 ~/.openclaw/media/、~/.openclaw/agents/ 或 /tmp。输出路径请始终指定到这三个位置之一(例如 --output ~/.openclaw/media/sunpath.png),不要写技能安装目录,否则图片发送会失败。

如何验证是否生效

跑一条最简单的太阳位置查询即可:

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

能正常返回方位角和高度角,说明依赖已装好、时区处理正常。若报 ModuleNotFoundError,回到第 2 步补包;若图片生成成功但发送失败,检查输出路径是否在允许目录内。

该技能的主要功能和特点

  • 实时太阳位置计算:给定经纬度与时区,输出指定时刻的太阳方位角与高度角,回答“太阳现在在哪”这类问题。
  • 太阳轨迹极坐标图:用一张图展示全年太阳运行轨迹,直观看出不同季节的日照角度变化。
  • 2D 建筑阴影模拟:以长方体建筑模型(宽、进深、高度、朝向旋转角)为基础,模拟指定时刻的阴影投射范围并出图。
  • 全年日照/阴影/夜间时数统计:针对建筑周边任意一个点(以建筑中心为原点、以米为单位定位),按指定年份与采样间隔,统计全年直射日照时数、建筑阴影时数、夜间时数,可选输出月度柱状图。
  • 地形阴影分析(DEM):读取 GeoTIFF 格式 DEM 数据,结合太阳位置与射线追踪算法,算出指定时刻地形上哪些区域处于日照、哪些处于阴影,可输出 GeoTIFF 结果栅格与 PNG 可视化图。
  • 热舒适度评估(焓湿图):输入干球温度与相对湿度,在焓湿图上标出当前状态点,快速判断体感是否舒适。
  • AI 自动编排:用户只需描述需求,技能会自动确定坐标、时间、时区、建筑尺寸等参数并直接执行脚本,无需反复确认,结果以图片 + 简要说明的形式回传。

和普通工具比强在哪:普通在线太阳位置查询工具只给一个角度数字;专业仿真软件功能强但门槛高。这个技能把“计算 + 出图 + 对话交付”串成一条链,用一句话完成一次完整分析,并且能顺手把图发到你正在聊天的窗口里。

如何使用该技能?

第 1 步:用自然语言提出需求

直接说出地点、时间、对象即可。技能会在识别到“太阳位置 / 太阳轨迹 / 阴影 / 全年日照 / 热舒适度 / 地形阴影”等意图时触发。

第 2 步:由 AI 补齐参数并执行

它会自行确定经纬度(如上海取 31.23, 121.47;洛杉矶取 34.05, -118.24)、时间与时区,然后直接运行脚本,无需你逐项确认。

第 3 步:按需求类型对应的典型调用

  • 太阳位置:

    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
    
  • 2D 阴影分析(示例:洛杉矶 2024 年夏至 15:00,15×10 米、高 20 米、朝北顺时针旋转 45° 的建筑):

    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
    
  • 全年日照时数(示例:上海,10×10×20 米建筑,评估点位于建筑中心正北 15 米处):

    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
    

    输出为直射日照总时数、阴影总时数、夜间总时数,若带 --output 还会附一张月度分布柱状图。--interval 控制采样间隔(默认 60 分钟,数值越小越精确但越慢)。

  • 地形阴影(DEM):

    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
    

    --step 为射线步进像素数(默认 1),调大速度更快但精度下降。

  • 舒适度分析:

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

第 4 步:获取结果

脚本把 PNG/JPG 写入你指定的路径(务必在 ~/.openclaw/media/、~/.openclaw/agents/ 或 /tmp 之下),随后由消息工具发送到对话中,并附简要说明。

输入输出小贴士

  • 时间参数支持 ISO 格式(如 "2024-12-21T14:00:00")或 "now"。
  • 建筑朝向 --rotation 为从正北起顺时针旋转的度数,评估点坐标会跟着这个朝向一起变化。
  • DEM 功能建议处理中等规模数据:1GB 内存下网格不超过约 2000×2000,或先裁剪出小区域。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
阳光分析Skill(sunlight-analysis) 对话式轻量环境分析技能 太阳位置、轨迹图、2D 阴影、全年日照统计、DEM 地形阴影、焓湿图舒适度 需 Python 环境 + 手动安装 6 个依赖库;使用靠一句话描述 方案前期的快速判断、场地日照速查、汇报级示意图 优势:自然语言驱动、计算到出图一体化、结果直接发进对话;不足:建筑模型仅支持长方体,不支持复杂形体与材质反射
专业建筑性能仿真软件(如参数化 + 日照插件组合) 工程级仿真 复杂形体建模、逐时全年仿真、辐射与眩光分析 门槛高,需建模能力与较长学习周期 正式施工图/报审阶段的日照合规论证 优势:精度高、模型自由;不足:重、慢、需要专门技能,轻量问题不划算
在线太阳位置/日照查询网站 查询工具 单点太阳方位角、高度角、日出日落时间 几乎零门槛,浏览器打开即可 快速查一个角度数值 优势:即开即用;不足:不出阴影图、不做全年点数统计、不考虑建筑遮挡
通用 GIS 阴影分析工具 空间分析平台 栅格地形阴影、山体阴影渲染 中等门槛,需理解栅格与坐标系 大范围地形日照与地貌分析 优势:地形处理成熟;不足:建筑尺度分析弱,交互重,难以用一句话得到结论

从上表可以看出,阳光分析Skill 的位置很清晰:它不替代工程级仿真,而是把“日常 80% 的轻量日照问题”从几十分钟压缩到几十秒。

该技能的典型应用场景与实际体验情况

场景一:住宅户型采光可行性初判

  • 角色与痛点:购房者或地产前期策划人员,想知道冬至日某栋 20 米高楼会不会挡住相邻点位。
  • 使用方式:描述“上海(31.23, 121.47),10×10×20 米建筑,冬至 14:00 的阴影”,技能直接给出阴影图;再跑一次全年统计,得到该点全年直射日照时数与阴影时数。
  • 体验情况:上手难度极低,一句中文就出图。注意建筑面积参数只支持长方体,实际复杂立面需要拆成多个体块近似。

场景二:场地环境与总图前期分析

  • 角色与痛点:建筑师在方案初期需要判断太阳全年运行规律,以决定朝向与开口。
  • 使用方式:直接生成极坐标太阳轨迹图,配合不同季节的阴影图一起用于方案比选。
  • 体验情况:轨迹图可读性好,适合放进汇报材料。因为图形是脚本生成的静态图片,样式可调空间有限,不适合做高度定制的视觉稿。

场景三:山地/地形日照分析

  • 角色与痛点:景观或规划人员手上有 GeoTIFF 格式 DEM,想快速看某时刻哪些坡面处于阴影。
  • 使用方式:传入 DEM 路径、经纬度、时间与时区,用 --output 输出 GeoTIFF、--plot 输出 PNG。
  • 体验情况:这是最需要“注意资源”的功能,大范围 DEM 要先裁剪,否则内存吃紧;--step 调大能加速,但边界精度会下降。

场景四:室内热舒适度速查

  • 角色与痛点:设计师或物业人员想知道“32℃、80% 相对湿度”到底难不难受。
  • 使用方式:一条 comfort_calc.py 命令生成焓湿图,当前温湿度状态点落在图上的位置即为判断依据。
  • 体验情况:非常直观,适合对比不同参数组合。属于定性参考,替换不了完整的热舒适度标准计算。

该技能能为用户带来的价值

  • 效率提升:把“查资料 + 建简单模型 + 出图”的多步骤流程压缩成一次对话或一条命令,轻量问题的处理时间从数十分钟级缩短到分钟级甚至秒级。
  • 门槛降低:不需要掌握专业仿真软件的建模与参数体系,用日常语言描述地点、时间、建筑尺寸即可得到可视化结论。
  • 决策前置:在方案最早期就能拿到太阳轨迹、阴影范围与全年日照时数的量化结果,避免到后期才发现朝向或间距问题而返工。
  • 结果可交付:输出是标准 PNG/JPG 图片和 GeoTIFF 栅格,可直接贴进方案文本、汇报 PPT 或交给 GIS 流程继续处理。
  • 能力可叠加:作为 AI 技能,它能与其他技能组合使用——先做日照分析、再做文档或图表整理,形成一条自动化工作流,长期价值随使用频次累积。

常见问题 FAQ

Q1:这个技能怎么安装?装完为什么跑不起来?

A:先通过技能市场入口安装技能本体(示例形式 clawhub install sun-path,以官方说明为准),然后在技能目录中执行 pip install -r requirements.txt。绝大多数“跑不起来”都是因为只装了技能、没装 Python 依赖,报错形式通常是 ModuleNotFoundError,按缺失的包补装即可。

Q2:生成的图生成成功却发不到聊天窗口,是什么原因?

A:消息工具只能发送允许目录下的文件,即 ~/.openclaw/media/、~/.openclaw/agents/ 或 /tmp。请把 --output 指到这三个目录之一(例如 ~/.openclaw/media/sunpath.png),不要用技能安装目录。

Q3:收费吗?需要联网或高性能电脑吗?

A:技能本身的授权与计费方式以官方说明为准。计算依赖本地 Python 库完成,太阳位置、阴影、日照时数均由 pysolar、shapely、numpy 等库本地计算,一般不需要额外的在线地图服务。DEM 地形分析较吃内存,1GB 内存下建议网格不超过约 2000×2000。

Q4:它和专业建筑日照仿真软件怎么选?

A:看阶段和精度要求。方案初期、需要快速出结论和示意图、或者只是回答“太阳在哪、这块地方下午有没有阴影”,用这个技能最快;到了报审、需要复杂形体、材质反射或逐时全年辐射的正式论证,仍应交给专业仿真软件。

Q5:建筑模型只能是长方体吗?复杂建筑怎么办?

A:是的,当前的阴影与全年日照计算都基于长方体建筑模型(宽、进深、高度、旋转角)。处理复杂建筑时,可以把它拆成多个长方体分别计算,再人工综合判断,结果属于近似分析而非精确仿真。