com.esri.arcgis.geoprocessing.tools.spatialanalysttools
Class AreaSolarRadiation
java.lang.Object
com.esri.arcgis.geoprocessing.AbstractGPTool
com.esri.arcgis.geoprocessing.tools.spatialanalysttools.AreaSolarRadiation
- All Implemented Interfaces:
- GPTool
- public class AreaSolarRadiation
- extends AbstractGPTool
Derives incoming solar radiation from a raster surface.
The Area Solar Radiation tool is contained in the Spatial Analyst Tools tool box.
Software restrictions: none
Usage tips:
- Because insolation calculations can be time consuming, it is important to be sure all parameters are correct. Calculation for a large digital elevation model (DEM) can take hours, and a very large DEM could take days.
- The output radiation rasters will always be floating-point type and have units of watt hours per square meter (WH/m). The direct duration raster output will be integer with unit hours.
- The analysis is designed for local landscape scales, therefore, it is recommended to use one latitude value for the whole DEM. With large datasets (i.e., states, countries or continents), the insolation results will differ significantly at different latitudes (greater than 1 degree). For broader geographic regions, it is necessary to divide the study area into zones with different latitudes.
- For multi-day 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. 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.
- For within-day time configurations, the maximum range of time is one day (24 hours). Calculations will not be performed across days (for instance, from 12:00 p.m. to 12:00 p.m. the next day). The start time must be less than the end time.
- For within-day time configurations, the start and end times are displayed as solar time (units: decimal hours). Use the time conversion dialog window to convert the local standard time and local solar time (HMS). When converting local standard time to solar time, the program accounts for equation of 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. To get accurate results, the z units should be the same as the x,y ground units. If they are not the same, use a z-factor to convert z units to x,y units. For example, if your x,y units are meters and your z units are feet, you could specify a z-factor of 0.3048 to convert feet to meters.
- It is recommended to have your data in a projection coordinate system (units meters). However if you choose to run the analysis with a spherical coordinated system you will need to specify an appropriate z-factor for that latitude. If your x,y units are decimal degrees and your z units are meters, some appropriate z-factors for particular latitudes are: Latitude Z-factor; 0 000000898; 10 000000912; 20 000000956; 30 000001036; 40 000001171; 50 000001395; 60 000001792; 70 000002619; 80 000005156;
- 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.
- For input surface rasters with a defined spatial reference, the mean latitude is automatically calculated; otherwise latitude will default to 45 degrees. When using an input layer, the spatial reference of the data frame is used.
- Skysize is the resolution of the viewshed, skymap, and sunmap rasters which 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 cooridinate system. These grids are square (equal number of rows and columns).
- Increasing skysize increases calculation accuracy but also increases calculation time considerably.
- When the "day interval" setting is small (e.g. < 14days) a larger skysize should be used. During analysis the sunmap (determined by the skysize) is used to represent sun positions (tracks) for particular time periods to calculate direct radiation. With smaller day intervals, if the skysize 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 skysize value is 4000. A value of 200 is default and is sufficient for whole DEMs with large day intervals (eg. > 14 days). Skysize value of 512 is sufficient for calculations at point locations where calculation time is less of an issue. At smaller day intervals (e.g. < 14 days) it is recommended to use higher values. For example, to calculate insolation for a location at the equator with day interval = 1, it is recommended to use a skysize of 2800 or more.
- Day intervals greater than 3 are recommended as sun tracks within three days typically overlap, depending on skysize and time of year. For calculations of the whole year with monthly interval, day interval is disabled and the program internally 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, whereas 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 30M resolution is usually quite smooth so fewer directions are sufficient for most situations (16 or 32). With finer DEMs, and particularly with man-made structures incorporated in the DEMs, the number of directions needs to increase. Increasing the number of directions will increase accuracy but will also increase calculation time.
- The Create outputs for each interval check box provides 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 box will create hourly insolation values; otherwise, insolation integrated for the entire day is calculated.
- The For each interval checkbox parameter affects the format and number of output radiation files. For area analysis, always verify that sufficient disk space is available before initiating calculations, because it creates multiple outputs. When checked, the default output format is an ESRI GRID stack containing multiple bands that correspond to the radiation or duration values for each time interval (hour interval when time configuration is less than one day, or day interval when multiple days).
- The diffuse proportion is the fraction of global normal radiation flux that is diffuse. Values range from 0 to 1. This value should be set according to atmospheric conditions. Typical values are 0.2 for very clear sky conditions and 0.3 for generally clear sky conditions.
- The solar radiation transmitted through the atmosphere is a fraction of the solar radiation outside the atmosphere. Transmittivity is a property of the atmosphere and is the ratio of solar radiation outside the atmosphere to that reaching the earth's surface (averaged over all wavelengths) for the shortest path (in the direction of the zenith). Values range from 0 (no transmission) to 1 (complete transmission). Typical values are 0.6 or 0.7 for very clear sky conditions and 0.5 for a generally clear sky. Because the analysis corrects for elevation effects, transmittivity should always be given for sea level. Transmittivity has an inverse relation with the diffuse proportion parameter.
|
Constructor Summary |
AreaSolarRadiation()
Creates the Area Solar Radiation tool with defaults. |
AreaSolarRadiation(java.lang.Object inSurfaceRaster,
java.lang.Object outGlobalRadiationRaster)
Creates the Area Solar Radiation tool with the required parameters. |
|
Method Summary |
int |
getAzimuthDivisions()
Returns the Azimuth divisions parameter of this tool . |
int |
getCalculationDirections()
Returns the Calculation directions parameter of this tool . |
int |
getDayInterval()
Returns the Day interval parameter of this tool . |
java.lang.String |
getDiffuseModelType()
Returns the Diffuse model type parameter of this tool . |
double |
getDiffuseProportion()
Returns the Diffuse proportion parameter of this tool . |
java.lang.String |
getEachInterval()
Returns the Create outputs for each interval parameter of this tool . |
double |
getHourInterval()
Returns the Hour interval parameter of this tool . |
java.lang.Object |
getInSurfaceRaster()
Returns the Input raster parameter of this tool . |
double |
getLatitude()
Returns the Latitude parameter of this tool . |
java.lang.Object |
getOutDiffuseRadiationRaster()
Returns the Output diffuse radiation raster parameter of this tool . |
java.lang.Object |
getOutDirectDurationRaster()
Returns the Output direct duration raster parameter of this tool . |
java.lang.Object |
getOutDirectRadiationRaster()
Returns the Output direct radiation raster parameter of this tool . |
java.lang.Object |
getOutGlobalRadiationRaster()
Returns the Output global radiation raster parameter of this tool . |
int |
getSkySize()
Returns the Sky size / Resolution parameter of this tool . |
java.lang.String |
getSlopeAspectInputType()
Returns the Slope and aspect input type parameter of this tool . |
java.lang.Object |
getTimeConfiguration()
Returns the Time configuration parameter of this tool . |
java.lang.String |
getToolboxAlias()
Returns the alias of the tool box containing this tool. |
java.lang.String |
getToolboxName()
Returns the name of the tool box containing this tool. |
java.lang.String |
getToolName()
Returns the name of this tool. |
double |
getTransmittivity()
Returns the Transmittivity parameter of this tool . |
int |
getZenithDivisions()
Returns the Zenith divisions parameter of this tool . |
double |
getZFactor()
Returns the Z factor parameter of this tool . |
void |
setAzimuthDivisions(int azimuthDivisions)
Sets the Azimuth divisions parameter of this tool . |
void |
setCalculationDirections(int calculationDirections)
Sets the Calculation directions parameter of this tool . |
void |
setDayInterval(int dayInterval)
Sets the Day interval parameter of this tool . |
void |
setDiffuseModelType(java.lang.String diffuseModelType)
Sets the Diffuse model type parameter of this tool . |
void |
setDiffuseProportion(double diffuseProportion)
Sets the Diffuse proportion parameter of this tool . |
void |
setEachInterval(java.lang.String eachInterval)
Sets the Create outputs for each interval parameter of this tool . |
void |
setHourInterval(double hourInterval)
Sets the Hour interval parameter of this tool . |
void |
setInSurfaceRaster(java.lang.Object inSurfaceRaster)
Sets the Input raster parameter of this tool . |
void |
setLatitude(double latitude)
Sets the Latitude parameter of this tool . |
void |
setOutDiffuseRadiationRaster(java.lang.Object outDiffuseRadiationRaster)
Sets the Output diffuse radiation raster parameter of this tool . |
void |
setOutDirectDurationRaster(java.lang.Object outDirectDurationRaster)
Sets the Output direct duration raster parameter of this tool . |
void |
setOutDirectRadiationRaster(java.lang.Object outDirectRadiationRaster)
Sets the Output direct radiation raster parameter of this tool . |
void |
setOutGlobalRadiationRaster(java.lang.Object outGlobalRadiationRaster)
Sets the Output global radiation raster parameter of this tool . |
void |
setSkySize(int skySize)
Sets the Sky size / Resolution parameter of this tool . |
void |
setSlopeAspectInputType(java.lang.String slopeAspectInputType)
Sets the Slope and aspect input type parameter of this tool . |
void |
setTimeConfiguration(java.lang.Object timeConfiguration)
Sets the Time configuration parameter of this tool . |
void |
setTransmittivity(double transmittivity)
Sets the Transmittivity parameter of this tool . |
void |
setZenithDivisions(int zenithDivisions)
Sets the Zenith divisions parameter of this tool . |
void |
setZFactor(double zFactor)
Sets the Z factor parameter of this tool . |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
AreaSolarRadiation
public AreaSolarRadiation()
- Creates the Area Solar Radiation tool with defaults.
Initializes the array of tool parameters with the default values specified when the tool was created.
AreaSolarRadiation
public AreaSolarRadiation(java.lang.Object inSurfaceRaster,
java.lang.Object outGlobalRadiationRaster)
- Creates the Area Solar Radiation tool with the required parameters.
Initializes the array of tool parameters with the values as specified for the required parameters and with the default values for the other parameters.
- Parameters:
inSurfaceRaster - Composite Geodataset, input DEM surface raster.outGlobalRadiationRaster - Raster Dataset, ).
getInSurfaceRaster
public java.lang.Object getInSurfaceRaster()
- Returns the Input raster parameter of this tool .
This parameter is Composite Geodataset, input DEM surface raster.
This is a required parameter.
- Returns:
- the Input raster
setInSurfaceRaster
public void setInSurfaceRaster(java.lang.Object inSurfaceRaster)
- Sets the Input raster parameter of this tool .
This parameter is Composite Geodataset, input DEM surface raster.
This is a required parameter.
- Parameters:
inSurfaceRaster - Composite Geodataset, input DEM surface raster.
getOutGlobalRadiationRaster
public java.lang.Object getOutGlobalRadiationRaster()
- Returns the Output global radiation raster parameter of this tool .
This parameter is Raster Dataset, ).
This is a required parameter.
- Returns:
- the Output global radiation raster
setOutGlobalRadiationRaster
public void setOutGlobalRadiationRaster(java.lang.Object outGlobalRadiationRaster)
- Sets the Output global radiation raster parameter of this tool .
This parameter is Raster Dataset, ).
This is a required parameter.
- Parameters:
outGlobalRadiationRaster - Raster Dataset, ).
getLatitude
public double getLatitude()
- Returns the Latitude parameter of this tool .
This parameter is Double, for input surface rasters containing a spatial reference, the mean latitude is automatically calculated; otherwise, latitude will default to 45 degrees.
This is an optional parameter.
- Returns:
- the Latitude
setLatitude
public void setLatitude(double latitude)
- Sets the Latitude parameter of this tool .
This parameter is Double, for input surface rasters containing a spatial reference, the mean latitude is automatically calculated; otherwise, latitude will default to 45 degrees.
This is an optional parameter.
- Parameters:
latitude - Double, for input surface rasters containing a spatial reference, the mean latitude is automatically calculated; otherwise, latitude will default to 45 degrees.
getSkySize
public int getSkySize()
- Returns the Sky size / Resolution parameter of this tool .
This parameter is Long, the resolution or skysize for the viewshed, skymap, and sunmap grids (units: cells).
The default creates a raster of 200 x 200 cells.
This is an optional parameter.
- Returns:
- the Sky size / Resolution
setSkySize
public void setSkySize(int skySize)
- Sets the Sky size / Resolution parameter of this tool .
This parameter is Long, the resolution or skysize for the viewshed, skymap, and sunmap grids (units: cells).
The default creates a raster of 200 x 200 cells.
This is an optional parameter.
- Parameters:
skySize - Long, the resolution or skysize for the viewshed, skymap, and sunmap grids (units: cells).
The default creates a raster of 200 x 200 cells.
getTimeConfiguration
public java.lang.Object getTimeConfiguration()
- Returns the Time configuration parameter of this tool .
This parameter is Time configuration, specifies the time period used for calculations.
This is an optional parameter.
- Returns:
- the Time configuration
setTimeConfiguration
public void setTimeConfiguration(java.lang.Object timeConfiguration)
- Sets the Time configuration parameter of this tool .
This parameter is Time configuration, specifies the time period used for calculations.
This is an optional parameter.
- Parameters:
timeConfiguration - Time configuration, specifies the time period used for calculations.-
Within a day — Performs calculations for a specified time period within one day. Select Julian Day, enter start time and end time.
-
Special Days — Calculates solar insolation for summer solstice/equinox/winter solstice days.
-
Multiple days in a year — Performs calculations for a specific multiple-day period within a year. Specify the start day, start year, end day, within year interval, and within day interval. When the end day is smaller than the start day, the end day is considered to be in the following year. This is the default time configuration.
-
Whole year — Performs calculations for an entire year using monthly intervals for calculations. If the Create outputs for each interval option is checked, output files will be created for each month. Otherwise, a single output will be created for the whole year.
getDayInterval
public int getDayInterval()
- Returns the Day interval parameter of this tool .
This parameter is Long, the default value is 14 (biweekly).
This is an optional parameter.
- Returns:
- the Day interval
setDayInterval
public void setDayInterval(int dayInterval)
- Sets the Day interval parameter of this tool .
This parameter is Long, the default value is 14 (biweekly).
This is an optional parameter.
- Parameters:
dayInterval - Long, the default value is 14 (biweekly).
getHourInterval
public double getHourInterval()
- Returns the Hour interval parameter of this tool .
This parameter is Double, the default value is 0.5.
This is an optional parameter.
- Returns:
- the Hour interval
setHourInterval
public void setHourInterval(double hourInterval)
- Sets the Hour interval parameter of this tool .
This parameter is Double, the default value is 0.5.
This is an optional parameter.
- Parameters:
hourInterval - Double, the default value is 0.5.
getEachInterval
public java.lang.String getEachInterval()
- Returns the Create outputs for each interval parameter of this tool .
This parameter is String, specifies whether to calculate a single total insolation output raster or multiple output rasters for the specified hour and day interval.
The default is NOINTERVAL.
For example, when INTERVAL is specified for a whole year with monthly intervals, the result will contain 12 output radiation rasters. Otherwise, only a single total radiation raster will be calculated.
This is an optional parameter.
- Returns:
- the Create outputs for each interval
setEachInterval
public void setEachInterval(java.lang.String eachInterval)
- Sets the Create outputs for each interval parameter of this tool .
This parameter is String, specifies whether to calculate a single total insolation output raster or multiple output rasters for the specified hour and day interval.
The default is NOINTERVAL.
For example, when INTERVAL is specified for a whole year with monthly intervals, the result will contain 12 output radiation rasters. Otherwise, only a single total radiation raster will be calculated.
This is an optional parameter.
- Parameters:
eachInterval - String, specifies whether to calculate a single total insolation output raster or multiple output rasters for the specified hour and day interval.
The default is NOINTERVAL.
For example, when INTERVAL is specified for a whole year with monthly intervals, the result will contain 12 output radiation rasters. Otherwise, only a single total radiation raster will be calculated.
getZFactor
public double getZFactor()
- Returns the Z factor parameter of this tool .
This parameter is Double, for example, if your z units are feet and your x,y units are meters, you would use a z-factor of 0.3048 to convert your z units from feet to meters (1 foot = 0.3048 meter).
This is an optional parameter.
- Returns:
- the Z factor
setZFactor
public void setZFactor(double zFactor)
- Sets the Z factor parameter of this tool .
This parameter is Double, for example, if your z units are feet and your x,y units are meters, you would use a z-factor of 0.3048 to convert your z units from feet to meters (1 foot = 0.3048 meter).
This is an optional parameter.
- Parameters:
zFactor - Double, for example, if your z units are feet and your x,y units are meters, you would use a z-factor of 0.3048 to convert your z units from feet to meters (1 foot = 0.3048 meter).
getSlopeAspectInputType
public java.lang.String getSlopeAspectInputType()
- Returns the Slope and aspect input type parameter of this tool .
This parameter is String, how slope and aspect information are derived for analysis.
This is an optional parameter.
- Returns:
- the Slope and aspect input type
setSlopeAspectInputType
public void setSlopeAspectInputType(java.lang.String slopeAspectInputType)
- Sets the Slope and aspect input type parameter of this tool .
This parameter is String, how slope and aspect information are derived for analysis.
This is an optional parameter.
- Parameters:
slopeAspectInputType - String, how slope and aspect information are derived for analysis.-
FROM_DEM — The slope and aspect grids are calculated from the input surface raster. This is the default.
-
FLAT_SURFACE — Constant values of zero are used for slope and aspect.
getCalculationDirections
public int getCalculationDirections()
- Returns the Calculation directions parameter of this tool .
This parameter is Long, 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.
This is an optional parameter.
- Returns:
- the Calculation directions
setCalculationDirections
public void setCalculationDirections(int calculationDirections)
- Sets the Calculation directions parameter of this tool .
This parameter is Long, 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.
This is an optional parameter.
- Parameters:
calculationDirections - Long, 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.
getZenithDivisions
public int getZenithDivisions()
- Returns the Zenith divisions parameter of this tool .
This parameter is Long, the default is eight divisions (relative to zenith).
This is an optional parameter.
- Returns:
- the Zenith divisions
setZenithDivisions
public void setZenithDivisions(int zenithDivisions)
- Sets the Zenith divisions parameter of this tool .
This parameter is Long, the default is eight divisions (relative to zenith).
This is an optional parameter.
- Parameters:
zenithDivisions - Long, the default is eight divisions (relative to zenith).
getAzimuthDivisions
public int getAzimuthDivisions()
- Returns the Azimuth divisions parameter of this tool .
This parameter is Long, the default is eight divisions (relative to north).
This is an optional parameter.
- Returns:
- the Azimuth divisions
setAzimuthDivisions
public void setAzimuthDivisions(int azimuthDivisions)
- Sets the Azimuth divisions parameter of this tool .
This parameter is Long, the default is eight divisions (relative to north).
This is an optional parameter.
- Parameters:
azimuthDivisions - Long, the default is eight divisions (relative to north).
getDiffuseModelType
public java.lang.String getDiffuseModelType()
- Returns the Diffuse model type parameter of this tool .
This parameter is String, type of diffuse radiation model.
This is an optional parameter.
- Returns:
- the Diffuse model type
setDiffuseModelType
public void setDiffuseModelType(java.lang.String diffuseModelType)
- Sets the Diffuse model type parameter of this tool .
This parameter is String, type of diffuse radiation model.
This is an optional parameter.
- Parameters:
diffuseModelType - String, type of diffuse radiation model.-
UNIFORM_SKY — Uniform diffuse model. The incoming diffuse radiation is the same from all sky directions. This is the default.
-
STANDARD_OVERCAST_SKY — Standard overcast diffuse model. The incoming diffuse radiation flux varies with zenith angle.
getDiffuseProportion
public double getDiffuseProportion()
- Returns the Diffuse proportion parameter of this tool .
This parameter is Double, this value should be set according to atmospheric conditions. The default value is 0.3 for generally clear sky conditions.
This is an optional parameter.
- Returns:
- the Diffuse proportion
setDiffuseProportion
public void setDiffuseProportion(double diffuseProportion)
- Sets the Diffuse proportion parameter of this tool .
This parameter is Double, this value should be set according to atmospheric conditions. The default value is 0.3 for generally clear sky conditions.
This is an optional parameter.
- Parameters:
diffuseProportion - Double, this value should be set according to atmospheric conditions. The default value is 0.3 for generally clear sky conditions.
getTransmittivity
public double getTransmittivity()
- Returns the Transmittivity parameter of this tool .
This parameter is Double, the default is 0.5 for a generally clear sky.
This is an optional parameter.
- Returns:
- the Transmittivity
setTransmittivity
public void setTransmittivity(double transmittivity)
- Sets the Transmittivity parameter of this tool .
This parameter is Double, the default is 0.5 for a generally clear sky.
This is an optional parameter.
- Parameters:
transmittivity - Double, the default is 0.5 for a generally clear sky.
getOutDirectRadiationRaster
public java.lang.Object getOutDirectRadiationRaster()
- Returns the Output direct radiation raster parameter of this tool .
This parameter is Raster Dataset, ).
This is an optional parameter.
- Returns:
- the Output direct radiation raster
setOutDirectRadiationRaster
public void setOutDirectRadiationRaster(java.lang.Object outDirectRadiationRaster)
- Sets the Output direct radiation raster parameter of this tool .
This parameter is Raster Dataset, ).
This is an optional parameter.
- Parameters:
outDirectRadiationRaster - Raster Dataset, ).
getOutDiffuseRadiationRaster
public java.lang.Object getOutDiffuseRadiationRaster()
- Returns the Output diffuse radiation raster parameter of this tool .
This parameter is Raster Dataset, the output has units of watt hours per square meter (WH/m2).
This is an optional parameter.
- Returns:
- the Output diffuse radiation raster
setOutDiffuseRadiationRaster
public void setOutDiffuseRadiationRaster(java.lang.Object outDiffuseRadiationRaster)
- Sets the Output diffuse radiation raster parameter of this tool .
This parameter is Raster Dataset, the output has units of watt hours per square meter (WH/m2).
This is an optional parameter.
- Parameters:
outDiffuseRadiationRaster - Raster Dataset, the output has units of watt hours per square meter (WH/m2).
getOutDirectDurationRaster
public java.lang.Object getOutDirectDurationRaster()
- Returns the Output direct duration raster parameter of this tool .
This parameter is Raster Dataset, the output has units of hours.
This is an optional parameter.
- Returns:
- the Output direct duration raster
setOutDirectDurationRaster
public void setOutDirectDurationRaster(java.lang.Object outDirectDurationRaster)
- Sets the Output direct duration raster parameter of this tool .
This parameter is Raster Dataset, the output has units of hours.
This is an optional parameter.
- Parameters:
outDirectDurationRaster - Raster Dataset, the output has units of hours.
getToolName
public java.lang.String getToolName()
- Returns the name of this tool.
- Returns:
- the tool name
getToolboxName
public java.lang.String getToolboxName()
- Returns the name of the tool box containing this tool.
- Returns:
- the tool box name
getToolboxAlias
public java.lang.String getToolboxAlias()
- Returns the alias of the tool box containing this tool.
- Returns:
- the tool box alias