Construct Sight Lines (3D Analyst)

Summary

Creates line features that represent sight lines from one or more observer points to features in a target feature class.

Illustration

Construct Sight Lines

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:

    1. Shape.Z (only available for features that are Z-enabled)
    2. Spot
    3. Z
    4. Z_Value
    5. Height
    6. Elev
    7. Elevation
    8. 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.

Parameters

LabelExplanationData Type
Observer Points

The single-point features that represent observer points. Multipoint features are not supported.

Feature Layer
Target Features

The target features (points, multipoints, lines, and polygons).

Feature Layer
Output

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.

  • No Height SourceNo Z values will be assigned to the resulting sight line features.
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.

  • No Height SourceNo Z values will be assigned to the resulting sight line features.
String
Join Field
(Optional)

The join field is used to match observers to specific targets.

  • No Join FieldNo Z values will be assigned to the resulting sight line features.
String
Sampling 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)

Specifies whether to add direction attributes to the output sight lines. Two additional fields will be added and populated to indicate direction: AZIMUTH and VERT_ANGLE (vertical angle).

  • Unchecked—No direction attributes will be added to the output sight lines. This is the default.
  • Checked—Two additional fields will be added and populated to indicate direction: azimuth and vertical angle.
Boolean
Sampling Method
(Optional)

Specifies how the sampling distance will be used to establish sight lines along the target feature.

  • 2D distanceThe distance will be evaluated in two-dimensional Cartesian space. This is the default.
  • 3D distanceThe distance will be evaluated in three-dimensional length.
String

arcpy.ddd.ConstructSightLines(in_observer_points, in_target_features, out_line_feature_class, {observer_height_field}, {target_height_field}, {join_field}, {sample_distance}, {output_the_direction}, {sampling_method})
NameExplanationData 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.

  • <None>No Z values will be assigned to the resulting sight line features.
  1. Shape.Z
  2. Spot
  3. Z
  4. Z_Value
  5. Height
  6. Elev
  7. Elevation
  8. Contour
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.

  • <None>No Z values will be assigned to the resulting sight line features.
  1. Shape.Z
  2. Spot
  3. Z
  4. Z_Value
  5. Height
  6. Elev
  7. Elevation
  8. Contour
String
join_field
(Optional)

The join field is used to match observers to specific targets.

  • <None>No Z values will be assigned to the resulting sight line features.
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)

Specifies whether to add direction attributes to the output sight lines. Two additional fields will be added and populated to indicate direction: AZIMUTH and VERT_ANGLE (vertical angle).

  • NOT_OUTPUT_THE_DIRECTION No direction attributes will be added to the output sight lines. This is the default.
  • OUTPUT_THE_DIRECTION Two additional fields will be added and populated to indicate direction: AZIMUTH and VERT_ANGLE (vertical angle).
Boolean
sampling_method
(Optional)

Specifies how the sampling distance will be used to establish sight lines along the target feature.

  • 2D_DISTANCEThe distance will be evaluated in two-dimensional Cartesian space. This is the default.
  • 3D_DISTANCEThe distance will be evaluated in three-dimensional length.
String

Code sample

ConstructSightLines example 1 (Python window)

The following sample demonstrates the use of this tool in the Python window.

arcpy.env.workspace = 'C:/data'
arcpy.ddd.ConstructSightLines('observer_pt.shp', 'target.shp', 'sightlines.shp', 'BASEHEIGHT', 'TOP_HEIGHT', 'NAME', "1", "OUTPUT_THE_DIRECTION")
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

# Set Local Variables:
arcpy.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.ddd.ConstructSightLines(obs, tar, sightlines, height, height,
                              join_field, sampling, direction)
arcpy.ddd.LineOfSight(surface, sightlines, "Parade_LOS.shp",
                      "Obstructions.shp", in_features=bldgs)

Licensing information

  • Basic: Requires 3D Analyst
  • Standard: Requires 3D Analyst
  • Advanced: Requires 3D Analyst

Related topics