SuperAPI AI Directory
Partner中文AI newsFavorites
Skillssunlight-analysis

sunlight-analysis

Design & creation

View repository

Updated 11-06 16:23

About this skill

Solar Path and Environmental Analysis

This skill provides comprehensive environmental analysis tools for architects and designers.

Dependencies

This skill requires Python and the following libraries:

  • pysolar(sun position calculation)
  • matplotlib(plotting)
  • pytz(timezone handling)
  • shapely(shadow geometry calculation)
  • numpy(mathematical calculation)
  • rasterio(terrain/DEM shadow analysis; DEM functionality is optional)

Installation: OpenClaw will not automatically install Python packages. After installing this skill (for example via clawhub install sun-path), please run once in the skill directory or specify its path:pip install -r requirements.txt. If the script reports a ModuleNotFoundError error when running, please install the missing packages from the above list or from requirements.txt .

Sending images to Telegram

Used in OpenClaw Telegram conversations. The script that generates images (plot_sunpath.py、shadow_calc.py、comfort_calc.py、annual_sun_hours.py --output、terrain_shadow.py --plot) will write PNG/JPG to the path you specify. When running the script, use the --output parameter (or --plot and use the script's default image path), then use the OpenClaw message/media toolto send that image fileto the user so that it is visible in the chat.

Paths allowed by OpenClaw: The message tool can only send files under allowed directories (~/.openclaw/media/、~/.openclaw/agents/ or /tmp). Always specify the output path as one of the above directories (for example --output ~/.openclaw/media/sunpath.png or /tmp/shadow.png); do not use the skill installation directory, otherwise sending will fail.

Agent behavior: When the user requests sun position, solar path diagrams, shadow analysis, annual sunshine hours charts, comfort charts, or terrain shadows,directly run the corresponding script(using exec), and specify the image output path under an allowed directory; then send the generated PNG/JPG to the user. No confirmation is needed; execute directly and return the image with a brief explanation.

Usage

1. Calculate sun position

Get the current azimuth and altitude angle for a specified location.

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

2. Generate solar path diagram

Create a polar chart showing the sun's path throughout the year.

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

3. Shadow analysis (2D)

Simulate the shadow projection of a simple building volume (rectangular cuboid) at a specified time.

Parameters:

  • --lat、--lon: location coordinates.
  • --time: date and time in ISO format (for example "2024-06-21T12:00:00") or "now".
  • --width、--depth: building plan dimensions (meters).
  • --height: building height (meters).
  • --rotation: angle rotated clockwise from true north.
  • --output: output image file name.
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. Annual sunshine/shadow hours calculation

Calculate the specified point's annualdirect sunlighthours,building shadowhours, ornighttime(the sun is below the horizon). Uses the same building cuboid and 2D shadow model as the shadow analysis; point positions are expressed in meters with the building center as the origin.

Parameters:

  • --lat、--lon: position coordinates.
  • --width、--depth、--height、--rotation: building dimensions and rotation angle (same as the shadow analysis).
  • --point-x、--point-y: position of the point to be evaluated (in meters with the building center as the origin; for example, when the rotation angle is 0, due north corresponds to a positive X value).
  • --year: year (default: current year).
  • --interval: sampling interval (minutes, default 60; smaller values are more accurate but slower to compute).
  • --timezone: time zone (e.g. Asia/Shanghai）。
  • --output: optional; save the monthly bar chart (sunlight/shade/night hours) to this file.
# 示例：建筑中心以北 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

Output: total sunlight hours, total shade hours, and total night hours, plus an optional monthly distribution chart.

5. Terrain shading (DEM)

Computes the terrain shadow distribution (sunlit vs. shaded) at a specified time from GeoTIFF DEM data. Uses solar position and a ray-tracing algorithm; suitable for medium-scale DEM data (with 1GB of memory, a grid of no more than about 2000×2000 is recommended, or process a smaller cropped area).

Parameters:

  • dem: path to the GeoTIFF DEM file.
  • --lat、--lon: latitude and longitude used to compute the solar position.
  • --time: time in ISO format or "now" (converted to UTC after parsing by --timezone ).
  • --timezone: time zone name (e.g. Asia/Shanghai）。
  • --output: output GeoTIFF path (default:terrain_shadow.tif）。
  • --plot: also save a PNG visualization.
  • --step: ray step in pixels (default 1; larger values are faster but less accurate).
# 示例：当地时间中午的阴影分析
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. Comfort analysis (psychrometric chart)

Visualizes the current temperature and humidity on a psychrometric chart to assess thermal comfort.

Parameters:

  • --temp: dry-bulb temperature (°C).
  • --rh: relative humidity (%).
  • --output: output image file name.
python3 scripts/comfort_calc.py --temp 28 --rh 60 --output comfort_chart.png

Examples

User: "What is the current sun position in Los Angeles?" Actions:

  1. Determine the coordinates of Los Angeles (latitude: 34.05, longitude: -118.24).
  2. Run sun_calc.py。
  3. to return the azimuth and altitude angles.

User: "Show the shadow of a 20-meter-high, 10×10-meter building in Shanghai at 2 PM on the winter solstice." Actions:

  1. Determine the coordinates (Shanghai: 31.23, 121.47).

  2. Determine the time (winter solstice: 2024-12-21 14:00).

  3. Run 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. to return the image.

User: "Is it comfortable in Singapore right now? Temperature 32°C, humidity 80%." Actions:

  1. Run comfort_calc.py：

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

  2. to return the image and analysis results.

User: "What are the annual sunlight and shade hours for this point? The building is 10×10×20 meters, and the point is 15 meters due north." Actions:

  1. Run annual_sun_hours.py, passing in the site latitude and longitude, building dimensions, and --point-x 15 --point-y 0。
  2. to return the printed summary (direct sunlight/shade/night hours); if --output is used, a monthly chart is also returned.

User: "Which parts of the terrain at this site are in shadow at 2 PM? I have DEM data." Actions:

  1. Run terrain_shadow.py, pass in the DEM path, site --lat/--lon、--time(e.g., local time 14:00),--timezone, as well as --output/--plot。
  2. Return the shadow raster and/or PNG image along with a brief description.