Points Solar Radiation (Spatial Analyst)

Summary

Derives incoming solar radiation for specific locations in a point feature class or location table.

Legacy:

This tool is deprecated and will be removed in a future release.

The Feature Solar Radiation tool provides enhanced functionality or performance.

Learn more about how solar radiation is calculated

Usage

  • The input locations can be a point feature class or a table of point coordinates. The table can be a geodatabase table, a .dbf file, an INFO table, or a text table file. The values can be of type long integer, float, or double.

  • When inputting locations by table, a list of locations must be specified with an x,y coordinate. Using an ASCII coordinate file, each line should contain an x,y pair separated by a comma, space, or tab. The following is a space-delimited example:

    X Y
    325541.218750 4314768.5
    325169.250000 4313907.0
    325874.031250 4313134.0
    325825.093750 4314181.5

    Alternatively, you can specify slope (degrees) and aspect in the location table. Along with the x,y coordinate, the file should contain the slope and aspect value for each location, in either order. The following is a comma-delimited example:

    x, y, slope, aspect
    325541.218750, 4314768.5, 15.84516716, 310.2363586
    325169.250000, 4313907.0, 39.39801788,   2.03503442
    325874.031250, 4313134.0, 16.10847282, 223.8308563
    325825.093750, 4314181.5,  8.89850712, 205.2011261
  • For multiday time configurations, the maximum range of days is a total of one year (365 days, or 366 days for leap years). If the start day is greater than the end day, the time calculations will proceed into the following year.

    For example, [start day, end day] = [365, 31] represents December 31 to January 31 of the following year. For the example of [1, 2], the time is inclusive for the first day from 0:00 hours (January 1) to 0:00 (January 2). The start day and end day cannot be equal.

  • The year value for time configuration is used to determine a leap year. It does not have any other influence on the solar radiation analysis, as the calculations are a function of the time period determined by Julian days.

  • For within-day time configurations, the maximum range of time is one day (24 hours). Calculations will not be performed across days (for example, from 12:00 p.m. to 12:00 p.m. the next day). The start time must be less than the end time.

  • The use of a z-factor is essential for correcting calculations when the surface z-units are expressed in units different from the ground x,y units. For accurate results, the z-units should be the same as the x,y ground units. If the units are not the same, use a z-factor to convert z-units to x,y units. For example, if the x,y units are meters and the z-units are feet, you can specify a z-factor of 0.3048 to convert feet to meters.

  • It is recommended that you have the data in a projected coordinate system with units of meters. If you run the analysis with a spherical coordinate system, you must specify an appropriate z-factor for that latitude. The following is a list of appropriate z-factors to use if the x,y units are decimal degrees and the z-units are meters:

        Latitude     Z-factor
           0         0.00000898
          10         0.00000912
          20         0.00000956
          30         0.00001036
          40         0.00001171
          50         0.00001395
          60         0.00001792
          70         0.00002619
          80         0.00005156
  • The height offset must be specified in meters.

  • The latitude for the site area (units: decimal degree, positive for the northern hemisphere and negative for the southern hemisphere) is used in calculations such as solar declination and solar position. Because the solar analysis is designed for landscape scales and local scales, it is acceptable to use one latitude value for the whole DEM. For broader geographic regions, you must divide the study area into zones with different latitudes.

  • For input surface rasters containing a spatial reference, the mean latitude is automatically calculated; otherwise, the latitude default is 45 degrees. When using an input layer, the spatial reference of the data frame is used.

  • Sky size is the resolution of the viewshed, sky map, and sun map rasters that are used in the radiation calculations (units: cells per side). These are upward-looking, hemispherical raster representations of the sky and do not have a geographic coordinate system. These rasters are square (equal number of rows and columns).

    The following are recommended sky size values when a time configuration of a whole year or multiple days is used:

    • For a 1 day interval, use a sky size of 1000 and above.
    • For a 0.25 day interval, use a sky size of 2000 and above.
    • For a 0.1 hour interval, use a sky size of 4000 and above.

    Increasing the sky size increases calculation accuracy but also increases calculation time considerably.

  • When the day interval setting is small (for example, < 14 days), use a larger sky size. During analysis, the sun map (determined by the sky size) is used to represent sun positions (tracks) for particular time periods to calculate direct radiation. With smaller day intervals, if the sky size resolution is not large enough, sun tracks may overlap, resulting in zero or lower radiation values for that track. Increasing the resolution provides a more accurate result.

  • The maximum sky size value is 10,000. A value of 200 is the default and is sufficient for whole DEMs with large day intervals (for example, > 14 days). A sky size value of 512 is sufficient for calculations at point locations where calculation time is less of an issue. At smaller day intervals (for example, < 14 days), it is recommended that you use higher values. For example, to calculate insolation for a location at the equator with day interval = 1, use a sky size of 2,800 or above.

  • Day intervals greater than 3 are recommended, as sun tracks within three days typically overlap, depending on sky size and time of year. For calculations of the whole year with monthly interval, day interval is disabled and the program uses calendar month intervals. The default value is 14.

  • Because the viewshed calculation can be highly intensive, horizon angles are only traced for the number of calculation directions specified. Valid values must be multiples of 8 (8, 16, 24, 32, and so on). Typically, a value of 8 or 16 is adequate for areas with gentle topography, and a value of 32 is adequate for complex topography. The default value is 32.

  • The number of calculation directions needed is related to the resolution of the input DEM. Natural terrain at 30-meters resolution is usually quite smooth, so fewer directions are sufficient for most situations (16 or 32). With finer DEMs, and particularly with human-made structures incorporated in the DEMs, the number of directions needs to increase. Increasing the number of directions increases accuracy but also increase calculation time.

  • The Create outputs for each interval parameter allows for the flexibility to calculate insolation integrated over a specified time period or insolation for each interval in a time series. For example, for the within-day time period with an hour interval of one, checking this parameter will create hourly insolation values; otherwise, insolation integrated for the entire day will be calculated.

  • The Create outputs for each interval parameter affects the number of attributes for output features. When checked for point radiation analysis, the output feature class includes additional attributes (t0, t1, t2, and so on), which indicate radiation or duration values for each time interval (hour interval when time configuration is less than one day, or day interval when multiple days). If, for example, start time = 0, then t0 will be sun rise and t1 will be at the next time increment after sun rise.

  • The amount of solar radiation received by the surface is only a portion of what would be received outside the atmosphere. Transmittivity is a property of the atmosphere that is expressed as the ratio of the energy (averaged overall wavelengths) reaching the earth's surface to that which is received at the upper limit of the atmosphere (extraterrestrial). Values range from 0 (no transmission) to 1 (complete transmission). Typically observed values are 0.6 or 0.7 for very clear sky conditions and 0.5 for a generally clear sky.

    The value for the energy received at the earth's surface is at the shortest path through the atmosphere (that is, the sun is at the zenith, or directly overhead) and for sea level. For areas beyond Tropic of Capricorn and Tropic of Cancer, the sun can never be at the exact zenith, even at noon; however, this value still refers to the moment when the sun is at the zenith. Because the algorithm corrects for elevation effects, transmittivity should always be given for sea level.

    Transmittivity has an inverse relation with the diffuse proportion parameter.

  • See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.

Parameters

LabelExplanationData Type
Input raster

The input elevation surface raster.

Raster Layer
Input points feature or table

The input point feature class or table containing the locations where solar radiation will be analyzed.

Feature Layer; Table View
Output global radiation features

The output feature class representing the global radiation or amount of incoming solar insolation (direct + diffuse) calculated for each location.

The output has units of watt hours per square meter (WH/m2).

Feature Class
Height offset
(Optional)

The height (in meters) above the DEM surface for which calculations will be performed.

The height offset will be applied to all input locations.

Double
Latitude
(Optional)

The latitude for the site area. The units are decimal degrees with positive values for the northern hemisphere and negative values for the southern hemisphere.

For input surface rasters containing a spatial reference, the mean latitude is automatically calculated; otherwise, the latitude default is 45 degrees.

Double
Sky size / Resolution
(Optional)

The resolution or sky size for the viewshed, sky map, and sun map rasters. The units are cells.

The default is a raster of 200 by 200 cells.

Long
Time configuration
(Optional)

Specifies the time period that will be used for the calculations.

  • Special days—Solar insolation will be calculated for the solstice days (summer and winter) and the equinox days (when the insolation for both spring and fall equinox are the same).
  • Within day—Calculations will be performed for a specified time period within a single day.

    Select the Julian day and provide the start and end times. When the start time and the end time are the same, instantaneous insolation will be calculated. When the start time is before sunrise and the end time is after sunset, insolation will be calculated for the whole day.

    • To enter the correct day, use the calendar button to open the Calendar dialog box.
  • Multiple days—Calculations will be performed for a specific multiple-day period within a year.

    Specify the start year, start day, and end day. When the end day is smaller than the start day, the end day is considered to be in the following year. The default time configuration starts on day 5 and ends on day 160 of the current Julian year.

    • To enter the correct days, use the calendar button to open the Calendar dialog box.
  • Whole year—Calculations will be performed for an entire year using monthly intervals for calculations.

    If the Create outputs for each interval parameter is checked, output files will be created for each month; otherwise, a single output will be created for the whole year.

Time configuration
Day interval
(Optional)

The time interval through the year (units: days) that will be used to calculate sky sectors for the sun map.

The default value is 14 (biweekly).

Long
Hour interval
(Optional)

The time interval through the day (units: hours) that will be used to calculate sky sectors for the sun map.

The default value is 0.5.

Double
Create outputs for each interval
(Optional)

Specifies whether a single total insolation value will be calculated for all locations or multiple values will be calculated for the specified hour and day interval.

  • Unchecked—A single total radiation value will be calculated for the entire time configuration. This is the default.
  • Checked—Multiple radiation values will be calculated for each time interval over the entire time configuration. The number of outputs depends on the hour or day interval. For example, for a whole year with monthly intervals, the result will contain 12 output radiation values for each location.
Boolean
Z factor
(Optional)

The number of ground x,y units in one surface z-unit.

The z-factor adjusts the units of measure for the z-units when they are different from the x,y units of the input surface. The z-values of the input surface are multiplied by the z-factor when calculating the final output surface.

If the x,y units and z-units are in the same units of measure, the z-factor is 1. This is the default.

If the x,y units and z-units are in different units of measure, the z-factor must be set to the appropriate factor or the results will be incorrect.

For example, if the z-units are feet and the x,y units are meters, use a z-factor of 0.3048 to convert the z-units from feet to meters (1 foot = 0.3048 meter).

Double
Slope and aspect input type
(Optional)

Specifies how slope and aspect information will be derived for analysis.

  • From the input surface rasterThe slope and aspect rasters will be calculated from the input surface raster. This is the default.
  • From a flat surfaceConstant values of zero will be used for slope and aspect.
  • From the input points tableThe slope and aspect values will be specified along with the x,y coordinates in the locations file.
String
Calculation directions
(Optional)

The number of azimuth directions that will be used when calculating the viewshed.

Valid values must be multiples of 8 (8, 16, 24, 32, and so on). The default value is 32 directions, which is adequate for complex topography.

Long
Zenith divisions
(Optional)

The number of zenith divisions that will be used to create sky sectors in the sky map.

The default is eight divisions (relative to zenith). Values must be greater than zero and less than half the sky size value.

Long
Azimuth divisions
(Optional)

The number of azimuth divisions that will be used to create sky sectors in the sky map.

The default is eight divisions (relative to north). Valid values must be multiples of 8. Values must be greater than zero and less than 160.

Long
Diffuse model type
(Optional)

Specifies the type of diffuse radiation model that will be used.

  • Uniform skyThe uniform diffuse model will be used. The incoming diffuse radiation is the same from all sky directions. This is the default.
  • Standard overcast skyThe standard overcast diffuse model will be used. The incoming diffuse radiation flux varies with the zenith angle.
String
Diffuse proportion
(Optional)

The proportion of global normal radiation flux that is diffuse. Values range from 0 to 1.

Set this value according to atmospheric conditions. The default value is 0.3 for generally clear sky conditions.

Double
Transmittivity
(Optional)

The fraction of radiation that passes through the atmosphere (averaged overall wavelengths). Values range from 0 (no transmission) to 1 (all transmission).

The default is 0.5 for a generally clear sky.

Double
Output direct radiation features
(Optional)

The output feature class representing the direct incoming solar radiation for each location.

The output has units of watt hours per square meter (WH/m2).

Feature Class
Output diffuse radiation features
(Optional)

The output feature class representing the incoming solar radiation for each location that is diffuse.

The output has units of watt hours per square meter (WH/m2).

Feature Class
Output direct duration features
(Optional)

The output feature class representing the duration of direct incoming solar radiation.

The output has units of hours.

Feature Class

PointsSolarRadiation(in_surface_raster, in_points_feature_or_table, out_global_radiation_features, {height_offset}, {latitude}, {sky_size}, {time_configuration}, {day_interval}, {hour_interval}, {each_interval}, {z_factor}, {slope_aspect_input_type}, {calculation_directions}, {zenith_divisions}, {azimuth_divisions}, {diffuse_model_type}, {diffuse_proportion}, {transmittivity}, {out_direct_radiation_features}, {out_diffuse_radiation_features}, {out_direct_duration_features})
NameExplanationData Type
in_surface_raster

The input elevation surface raster.

Raster Layer
in_points_feature_or_table

The input point feature class or table containing the locations where solar radiation will be analyzed.

Feature Layer; Table View
out_global_radiation_features

The output feature class representing the global radiation or amount of incoming solar insolation (direct + diffuse) calculated for each location.

The output has units of watt hours per square meter (WH/m2).

Feature Class
height_offset
(Optional)

The height (in meters) above the DEM surface for which calculations will be performed.

The height offset will be applied to all input locations.

Double
latitude
(Optional)

The latitude for the site area. The units are decimal degrees with positive values for the northern hemisphere and negative values for the southern hemisphere.

For input surface rasters containing a spatial reference, the mean latitude is automatically calculated; otherwise, the latitude default is 45 degrees.

Double
sky_size
(Optional)

The resolution or sky size for the viewshed, sky map, and sun map rasters. The units are cells.

The default is a raster of 200 by 200 cells.

Long
time_configuration
(Optional)

Specifies the time configuration (period) that will be used for calculating solar radiation.

The Time class objects will be used to specify the time configuration.

The different types of time configurations available are TimeWithinDay, TimeMultipleDays, TimeSpecialDays, and TimeWholeYear.

The following are the forms:

  • TimeWithinDay({day},{startTime},{endTime})
  • TimeMultipleDays({year},{startDay},{endDay})
  • TimeSpecialDays()
  • TimeWholeYear({year})

The default time configuration is TimeMultipleDays with the startDay value of 5 and the endDay value of 160 for the current Julian year.

Time configuration
day_interval
(Optional)

The time interval through the year (units: days) that will be used to calculate sky sectors for the sun map.

The default value is 14 (biweekly).

Long
hour_interval
(Optional)

The time interval through the day (units: hours) that will be used to calculate sky sectors for the sun map.

The default value is 0.5.

Double
each_interval
(Optional)

Specifies whether a single total insolation value will be calculated for all locations or multiple values will be calculated for the specified hour and day interval.

  • NOINTERVALA single total radiation value will be calculated for the entire time configuration. This is the default.
  • INTERVALMultiple radiation values will be calculated for each time interval over the entire time configuration. The number of outputs depends on the hour or day interval. For example, for a whole year with monthly intervals, the result will contain 12 output radiation values for each location.
Boolean
z_factor
(Optional)

The number of ground x,y units in one surface z-unit.

The z-factor adjusts the units of measure for the z-units when they are different from the x,y units of the input surface. The z-values of the input surface are multiplied by the z-factor when calculating the final output surface.

If the x,y units and z-units are in the same units of measure, the z-factor is 1. This is the default.

If the x,y units and z-units are in different units of measure, the z-factor must be set to the appropriate factor or the results will be incorrect.

For example, if the z-units are feet and the x,y units are meters, use a z-factor of 0.3048 to convert the z-units from feet to meters (1 foot = 0.3048 meter).

Double
slope_aspect_input_type
(Optional)

Specifies how slope and aspect information will be derived for analysis.

  • FROM_DEMThe slope and aspect rasters will be calculated from the input surface raster. This is the default.
  • FLAT_SURFACEConstant values of zero will be used for slope and aspect.
  • FROM_POINTS_TABLEThe slope and aspect values will be specified along with the x,y coordinates in the locations file.
String
calculation_directions
(Optional)

The number of azimuth directions that will be used when calculating the viewshed.

Valid values must be multiples of 8 (8, 16, 24, 32, and so on). The default value is 32 directions, which is adequate for complex topography.

Long
zenith_divisions
(Optional)

The number of zenith divisions that will be used to create sky sectors in the sky map.

The default is eight divisions (relative to zenith). Values must be greater than zero and less than half the sky size value.

Long
azimuth_divisions
(Optional)

The number of azimuth divisions that will be used to create sky sectors in the sky map.

The default is eight divisions (relative to north). Valid values must be multiples of 8. Values must be greater than zero and less than 160.

Long
diffuse_model_type
(Optional)

Specifies the type of diffuse radiation model that will be used.

  • UNIFORM_SKYThe uniform diffuse model will be used. The incoming diffuse radiation is the same from all sky directions. This is the default.
  • STANDARD_OVERCAST_SKYThe standard overcast diffuse model will be used. The incoming diffuse radiation flux varies with the zenith angle.
String
diffuse_proportion
(Optional)

The proportion of global normal radiation flux that is diffuse. Values range from 0 to 1.

Set this value according to atmospheric conditions. The default value is 0.3 for generally clear sky conditions.

Double
transmittivity
(Optional)

The fraction of radiation that passes through the atmosphere (averaged overall wavelengths). Values range from 0 (no transmission) to 1 (all transmission).

The default is 0.5 for a generally clear sky.

Double
out_direct_radiation_features
(Optional)

The output feature class representing the direct incoming solar radiation for each location.

The output has units of watt hours per square meter (WH/m2).

Feature Class
out_diffuse_radiation_features
(Optional)

The output feature class representing the incoming solar radiation for each location that is diffuse.

The output has units of watt hours per square meter (WH/m2).

Feature Class
out_direct_duration_features
(Optional)

The output feature class representing the duration of direct incoming solar radiation.

The output has units of hours.

Feature Class

Code sample

PointsSolarRadiation example 1 (Python window)

The following Python window script demonstrates how to use this tool.

import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
PointsSolarRadiation("elevation", "observers.shp", 
                     "c:/sapyexamples/output/outglobalrad1.shp", "", 35, 200, 
                     TimeMultipleDays(2009, 91, 212), 14, 0.5,"NOINTERVAL", 
                     1, "FROM_DEM", 32, 8, 8,"STANDARD_OVERCAST_SKY", 0.3, 0.5, 
                     "c:/sapyexamples/output/outdirectrad1.shp", 
                     "c:/sapyexamples/output/outdiffuserad1.shp", 
                     "c:/sapyexamples/output/outduration1.shp")
PointsSolarRadiation example 2 (stand-alone script)

Calculate the amount of incoming solar radiation for specific point locations.

# PointsSolarRadiation_Example02.py
# Description: For all point locations, calculates total global, direct,
#    diffuse and direct duration solar radiation for a whole year.
# Requirements: Spatial Analyst Extension

# Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *

# Set environment settings
env.workspace = "C:/sapyexamples/data"

# Set local variables
inRaster = "elevation"
inPntFC = "observers.shp"
outFeatures = "c:/sapyexamples/output/outglobal1.shp"
latitude = 35.75
skySize = 200
timeConfig = TimeMultipleDays(2009, 91, 212)
dayInterval = 14
hourInterval = 0.5
zFactor = 0.3048
calcDirections = 32
zenithDivisions = 8
azimuthDivisions = 8
diffuseProp = 0.3
transmittivity = 0.5
outDirectRad = "C:/sapyexamples/output/outdirectrad1.shp"
outDiffuseRad = "C:/sapyexamples/output/outdiffuserad1.shp"
outDirectDur = "C:/sapyexamples/output/outduration1.shp"

# Execute PointsSolarRadiation...
PointsSolarRadiation(inRaster, inPntFC, outFeatures, "", latitude, skySize, 
                     timeConfig, dayInterval, hourInterval, "INTERVAL", 
                     zFactor, "FROM_DEM", calcDirections, zenithDivisions, 
                     azimuthDivisions,"STANDARD_OVERCAST_SKY", diffuseProp, 
                     transmittivity, outDirectRad, outDiffuseRad, outDirectDur)