Label | Explanation | Data Type |
Input Features
| The multipatch features that will be used to model shadows. | Feature Layer |
Start Date and Time
| The date and time from which sun positions will be determined. Both a date and a time must be provided, and only the times when the sun is above the horizon will produce an output shadow volume. | Date |
Output Feature Class | The multipatch feature class that will store the resulting shadow volumes. | Feature Class |
Adjusted for Daylight Savings Time (Optional) | Specifies whether the time value will be adjusted for daylight saving time (DST).
| Boolean |
Time Zone (Optional) | The time zone in which the participating input is located. The default setting is the time zone to which the operating system is set.
| String |
End Date and Time
(Optional) | The final date and time that will be used for calculating sun position. A time can be specified without a date, in which case the end date will be the same as the start date. If a date is provided, a time must also be given. Only the times at which the sun is above the horizon will produce an output shadow volume. | Date |
Iteration Interval
(Optional) | The value that will be used to define the iteration of time from the start date. | Double |
Iteration Unit
(Optional) | Specifies the unit that will define the iteration value applied to the Start Date and Time parameter value.
| String |
Summary
Creates closed volumes that model shadows cast by each feature using sunlight for a given date and time.
Usage
All input features should reside in the same locale, as relative sun position calculations are based on the position of the first feature in the first feature class.
Shadow volumes will not be produced if the sun is not visible for a given date and time or if the relative position of the sun is at a vertical angle of 90 degrees from the input features.
Shadows are modeled as closed multipatches created by extruding the input features in the direction of sunlight. Light rays are considered to be parallel and travel in the direction calculated for the relative position of the sun. Each shadow volume starts and ends at a vertical plane that is perpendicular to the horizontal projection of the sun's rays.
The following fields will be attributed to the shadow volume features:
- SOURCE—The name of the feature class casting the shadow volume.
- SOURCE_ID—The unique ID of the feature casting the shadow volume.
- DATE_TIME—The local date and time used to calculate sun position.
- AZIMUTH—The angle in degrees between true north and the perpendicular projection of the sun's relative position down to the earth's horizon. Values range from 0 to 360.
- VERT_ANGLE—The angle in degrees between the earth's horizon and the sun's relative position where the horizon defines 0 degrees and 90 degrees is directly above.
Note:
Typically, each shadow volume will appear to hug, or be cast tightly against, its originating feature. If a shadow cannot be generated in this manner, it will be created from the boundary of the feature's outer extent. When at least one shadow is created this way, a HUGS_FEATR field is included to indicate which shadows hug their corresponding features.
Parameters
arcpy.ddd.SunShadowVolume(in_features, start_date_and_time, out_feature_class, {adjusted_for_dst}, {time_zone}, {end_date_and_time}, {iteration_interval}, {iteration_unit})
Name | Explanation | Data Type |
in_features [in_features,...] | The multipatch features that will be used to model shadows. | Feature Layer |
start_date_and_time | The date and time from which sun positions will be determined. Both a date and a time must be provided, and only the times when the sun is above the horizon will produce an output shadow volume. | Date |
out_feature_class | The multipatch feature class that will store the resulting shadow volumes. | Feature Class |
adjusted_for_dst (Optional) | Specifies whether the time value will be adjusted for daylight saving time (DST).
| Boolean |
time_zone (Optional) | The time zone in which the participating input is located. The default setting is the time zone to which the operating system is set.
| String |
end_date_and_time (Optional) | The final date and time that will be used for calculating sun position. A time can be specified without a date, in which case the end date will be the same as the start date. If a date is provided, a time must also be given. Only the times at which the sun is above the horizon will produce an output shadow volume. | Date |
iteration_interval (Optional) | The value that will be used to define the iteration of time from the start date. | Double |
iteration_unit (Optional) | Specifies the unit that will define the iteration value applied to the start_date_and_time parameter value.
| String |
Code sample
The following sample demonstrates the use of this tool in the Python window:
arcpy.env.workspace = 'C:/data'
arcpy.ddd.SunShadowVolume('sample.fgdb/buildings',
start_date_and_time='12/25/2011 10:00 AM',
out_feature_class='shadows_dec25.shp',
adjusted_for_dst='ADJUSTED_FOR_DST',
time_zone='Eastern_Standard_Time',
end_date_and_time='12/25/2011 3:00 PM',
iteration_interval='HOURS', iteration_unit=1)
The following sample demonstrates the use of this tool in a stand-alone Python script:
'''*********************************************************************
Name: Model Shadows For GeoVRML Models
Description: Creates a model of the shadows cast by GeoVRML models
imported to a multipatch feature class for a range of dates
and times. A range of times from the start time and end
time can also be specified by setting the EnforceTimes
Boolean to True. This sample is designed to be used in a
script tool.
*********************************************************************'''
# Import system modules
import arcpy
from datetime import datetime, time, timedelta
#************************* Script Variables **************************
inFiles = arcpy.GetParameterAsText(0) # list of input features
spatialRef = arcpy.GetParameterAsText(1) # list of GeoVRML files
outFC = arcpy.GetParameterAsText(2) # multipatch from 3D files
inTimeZone = arcpy.GetParameterAsText(3) # time zone
startDate = arcpy.GetParameter(4) # starting date as datetime
endDate = arcpy.GetParameter(5) # ending date as datetime
dayInterval = arcpy.GetParameter(6) # day interval as long (0-365)
minInterval = arcpy.GetParameter(7) # minute interval as long (0-60)
enforceTime = arcpy.GetParameter(8) # minute interval as Boolean
outShadows = arcpy.GetParameterAsText(9) # output shadow models
outIntersection = arcpy.GetParameterAsText(10) # shadow & bldg intersection
# Function to find all possible date/time intervals for shadow modelling
def time_list():
dt_result = [startDate]
if dayInterval:
if endDate: #Defines behavior when end date is supplied
while startDate < endDate:
startDate += timedelta(days=dayInterval)
dt_result.append(startDate)
dt_result.append(endDate)
else: # Behavior when end date is not given
daymonthyear = datetime.date(startDate)
while startDate <= datetime(daymonthyear.year, 12, 31, 23, 59):
startDate += timedelta(days=dayInterval)
dt_result.append(startDate)
return dt_result
importFC = arcpy.CreateUniqueName('geovrml_import', 'in_memory')
# Import GeoVRML files to in-memory feature
arcpy.ddd.Import3DFiles(inFiles, importFC, 'ONE_FILE_ONE_FEATURE',
spatialRef, 'Z_IS_UP', 'wrl')
# Ensure that building models are closed
arcpy.ddd.EncloseMultiPatch(importFC, outFC, 0.05)
# Discard in-memory feature
arcpy.management.Delete(importFC)
dt_result = time_list()
for dt in dt_result:
if dt == dt_result[0]:
shadows = outShadows
else:
shadows = arcpy.CreateUniqueName('shadow', 'in_memory')
arcpy.ddd.SunShadowVolume(outFC, dt, shadows, 'ADJUST_FOR_DST',
inTimeZone, '', minInterval, 'MINUTES')
if dt is not dt_result[0]:
arcpy.management.Append(shadows, outShadows)
arcpy.management.Delete(shadows)
arcpy.ddd.Intersect3D(outFC, outIntersection, outShadows, 'SOLID')
Environments
Licensing information
- Basic: Requires 3D Analyst
- Standard: Requires 3D Analyst
- Advanced: Requires 3D Analyst