Skyline Graph (3D Analyst)
Summary
Calculates sky visibility and generates an optional table and polar graph.
The table and graph represent the horizontal and vertical angles going from the observer point to each of the vertices on the skyline.
Illustration
Usage
- An observer point and a skyline (3D line) are required as input.
- The azimuth and vertical angle from the observer point to each vertex is calculated.
- The tool always returns the ratio of visible sky (between 0 and 1; for example, 0.8 if the sky is 80 percent visible).
- The tool can optionally output a table of angles. If the table is output, then a polar graph can also optionally be output.
- The tool always displays in the Results window (or in the Results information, if the window is not displayed) the percentage of visible sky, along with the minimum and maximum vertical angles.
- If a table is output, it will contain rows of two or more double-precision numbers. Each row contains at least an arithmetic horizontal angle and a zenith angle, both of which are in degrees.
- If Additional Fields is selected, then additional columns will be generated, including information, such as the source of the edge that follows the vertex in the skyline (FEATURE_ID), the distance from the observer point to the vertex, and the coordinates of the vertex. (The source might be the FID of the feature that participates in the skyline or a code to indicate that the skyline is on the surface.)
The fields that will always appear in the table are:
- HORIZ_ANG—The horizontal angle.
- ZENITH_ANG—The zenith angle.
The additional fields are:
- VERTEX_X—The X coordinate of the vertex.
- VERTEX_Y—The Y coordinate of the vertex.
- VERTEX_Z—The Z coordinate of the vertex.
- DIST_2D—The horizontal distance from the observer to the vertex.
- DIST_3D—The slope distance from the observer to the vertex.
The additional fields are not necessary for generating the graph.
The arithmetic horizontal angle is equal to 90 minus the azimuth, and the zenith angle is 90 minus the vertical angle. (An arithmetic horizontal angle of 0 is due east, and 90 is due north; a zenith angle of 90 is horizontal, and 0 is straight up.)
- The optional graph is a polar graph, which appears as if the skyline (3D polyline) were projected onto the surface of a sphere, and the observer of the graph were looking down from high above the center of the sphere (the center of the sphere is at the observer point).
- The polar graph is linear as you go out from its center, meaning that the ring/circle representing the equator has twice the radius of the ring representing an angle of elevation of 45 degrees, assuming that the center of the graph represents an angle of elevation of 90 degrees (zenith angle of zero).
- The percentage of visible sky is always listed in the results. This value is equal to the area above the skyline, divided by the area above the base visible angle (one of the parameters, with a default of zero, meaning at the same elevation as the observer), and is calculated only within the azimuth range of the skyline.
The graph option will only display a graph with an ArcGIS Desktop installation.
Syntax
| Parameter | Explanation | Data Type |
in_observer_point_features |
The input features containing one or more observer points. | Feature Layer |
in_line_features |
The line feature class representing the skyline. | Feature Layer |
base_visibility_angle (Optional) |
The vertical angle which is used as the baseline for calculating percentage of visible sky; 0 is the horizon, 90 is straight up; -90 is straight down. The default is 0. | Double |
additional_fields (Optional) |
Determines whether to output additional fields to the table, rather than just the two angle values.
| Boolean |
out_angles_table (Optional) |
The table to be created for outputting the angles. The default is blank, meaning no table. | Table |
out_graph (Optional) |
The name of the optional graph. A table has to be generated in order for the graph to be made. The graph will be displayed and can be saved and/or edited. The default is blank, meaning no graph. | Graph |
Code Sample
The following sample demonstrates the use of this tool in the Python window:
import arcpy
from arcpy import env
arcpy.CheckOutExtension("3D")
env.workspace = "C:/data"
arcpy.SkylineGraph_3d("observers.shp", "skyline_outline.shp", 0, "ADDITIONAL_FIELDS", "table.dbf")
The following sample demonstrates the use of this tool in a stand-alone Python script:
'''****************************************************************************
Name: Skyline Example
Description: This script demonstrates how to use the
Skyline tool.
****************************************************************************'''
# Import system modules
import arcpy
import exceptions, sys, traceback
from arcpy import env
try:
# Obtain a license for the ArcGIS 3D Analyst extension
arcpy.CheckOutExtension('3D')
# Set environment settings
env.workspace = 'C:/data'
# Set Local Variables
inPts = "observers.shp"
inLines = "skyline_outline.shp"
baseVisibility = 25
# Ensure output table has unique name
outTable = arcpy.CreateUniqueName("angles_table.dbf")
#Execute SkylineGraph
arcpy.SkylineGraph_3d(inPts, inLines, 0, "ADDITIONAL_FIELDS", outTable)
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)