Summary
Creates line features that represent sight lines from one or more observer points to features in a target feature class.
Illustration
Usage
Sight lines are sampled from the perimeter of target lines and polygons based on the value specified in the Sampling Distance parameter. The Sampling Distance units should be given in the x-y units of the output feature class.
A join field is used to specify one or more targets for a given observer. If no join field is used, all points will be connected to all targets.
A three-dimensional output will be generated if a height source is specified for both observer and target features. The height source of the observer and target features defaults to the first field name encountered in this list:
- Shape.Z (only available for features that are Z-enabled)
- Spot
- Z
- Z_Value
- Height
- Elev
- Elevation
- Contour
If no suitable height field exists, the <None> keyword will be used to indicate the features have no Z-values.
If the desired height field does not have a higher priority in the default field selection, the desired field will need to be explicitly specified. Similarly, if a height field is not desired but the feature class contains one of the fields in the default selection list, the <None> keyword will need to be specified.
The following fields will be added to the output feature class that contains the sight lines:
- OID_OBSERV—The OID of the observer point
- OID_TARGET—The OID of the target feature
- DIST_ALONG—The distance along the target feature if it is a line or polygon
When the Output The Directions parameter is enabled, the output sight lines will have two additional attribute fields:
- AZIMUTH—Degrees from due north where values increase clockwise
- VERT_ANGLE—Vertical angle in degrees from horizon where 90° is directly overhead and -90° is directly below. Vertical angle will only be relevant when a height field is specified.
Syntax
ConstructSightLines_3d (in_observer_points, in_target_features, out_line_feature_class, {observer_height_field}, {target_height_field}, {join_field}, {sample_distance}, {output_the_direction})| Parameter | Explanation | Data Type |
in_observer_points | The single-point features that represent observer points. Multipoint features are not supported. | Feature Layer |
in_target_features | The target features (points, multipoints, lines, and polygons). | Feature Layer |
out_line_feature_class | The output feature class containing the sight lines. | Feature Class |
observer_height_field (Optional) | The source of the height values for the observer points obtained from its attribute table. A default Observer Height Field field is selected from among the options listed below by order of priority. If multiple fields exist, and the desired field does not have a higher priority in the default field selection, the desired field will need to be specified.
| String |
target_height_field (Optional) | The height field for the target. A default Target Height Field field is selected from among the options listed below by order of priority. If multiple fields exist, and the desired field does not have a higher priority in the default field selection, the desired field will need to be specified.
| String |
join_field (Optional) | The join field is used to match observers to specific targets. | String |
sample_distance (Optional) | The distance between samples when the target is either a line or polygon feature class. The Sampling Distance units are interpreted in the XY units of the output feature class. | Double |
output_the_direction (Optional) |
Adds direction attributes to the output sight lines. Two additional fields will be added and populated to indicate direction: AZIMUTH and VERT_ANGLE (vertical angle).
| Boolean |
Code Sample
ConstructSightLines example 1 (Python window)
The following sample demonstrates the use of this tool in the Python window.
arcpy.CheckOutExtension('3D')
arcpy.env.workspace = 'C:/data'
arcpy.ConstructSightLines_3d('observer_pt.shp', 'target.shp', 'sightlines.shp',
'BASEHEIGHT', 'TOP_HEIGHT', 'NAME', 1)
ConstructSightLines example 2 (stand-alone script)
The following sample demonstrates the use of this tool in a stand-alone Python script.
'''*********************************************************************
Name: Sight Line Visibility of Parade Path
Description: This script demonstrates how to create a sight line feature class
from a pair of observer and target points.
*********************************************************************'''
# Import system modules
import arcpy
import exceptions, sys, traceback
from arcpy import env
try:
# Checking out 3D Analyst Extension:
arcpy.CheckOutExtension('3D')
# Set Local Variables:
env.workspace = 'C:/data'
# Setting up input and output variables:
obs = "observer_pts.shp"
tar = "parade_path.shp"
sightlines = "output_sightlines.shp"
height = "<None>"
join_field = "#"
sampling = 0.5
direction = "OUTPUT_THE_DIRECTION"
surface = 'elevation.tif'
bldgs = 'buildings.shp'
arcpy.AddMessage("Building sightlines...")
arcpy.ddd.ConstructSightLines(obs, tar, sightlines, height, height,
join_field, sampling, direction)
arcpy.ddd.LineOfSight(surface, sightlines, "Parade_LOS.shp",
"Obstructions.shp", in_features=bldgs)
arcpy.GetMessages(0)
arcpy.CheckInExtension("3D")
except arcpy.ExecuteError:
print arcpy.GetMessages()
except:
# Get the traceback object
tb = sys.exc_info()[2]
tbinfo = traceback.format_tb(tb)[0]
# Concatenate error information into message string
pymsg = 'PYTHON ERRORS:\nTraceback info:\n{0}\nError Info:\n{1}'\
.format(tbinfo, str(sys.exc_info()[1]))
msgs = 'ArcPy ERRORS:\n {0}\n'.format(arcpy.GetMessages(2))
# Return python error messages for script tool or Python Window
arcpy.AddError(pymsg)
arcpy.AddError(msgs)
Environments
Licensing Information
- ArcGIS for Desktop Basic: Requires 3D Analyst
- ArcGIS for Desktop Standard: Requires 3D Analyst
- ArcGIS for Desktop Advanced: Requires 3D Analyst