Skyline Graph (3D Analyst)

Summary

Calculates the sky visibility ratio and generates an optional table and a polar graph.

Illustration

Skyline Graph tool illustration

Usage

  • This tool requires the line features created by the Skyline tool and generates a polar graph. The polar graph can be seen in the tool's message window and can be also be saved as an image. The output message also indicates the percent of visible sky above the horizon.

  • The azimuth and vertical angle from each observer point to each vertex in the skyline can be exported to a stand-alone table by specifying the Output Angles Table parameter value. The resulting table will contain the following fields:

    • HORIZ_ANG—The arithmetic horizontal angle expressed where 0° is due east and values increase in the counter-clockwise direction until 360°. The arithmetic horizontal angle is equal to 90 minus the azimuth.
    • ZENITH_ANG—The zenith angle where 0° is directly up along the z-axis, 90° is at the horizon, and 180° is directly down along the z-axis. The zenith angle is 90 minus the vertical angle from the horizon.
    • HOR_AN_GEO—The geographic horizontal angle where 0° is in the projection's north and values increase in the clockwise direction until 360°.
    • ZEN_AN_INV—The zenith angle where 0° is at the horizon, 90° is directly up along the z-axis, and -90° is directly down along the z-axis.

    If the Additional Fields parameter is checked, the output table will also contain the following fields:

    • FEATURE_ID—The unique ID of the feature defining the skyline. Rows where this value is -1 denote locations where the skyline is defined by a surface, whereas a value of -2 represents transitional lines that do not contribute to the skyline but are used to connect the segments that define the skyline.
    • 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 tool will report the minimum and maximum vertical angles of visibility to the sky along with the sky visibility ratio, which is expressed as a value from 0 to 1. A visibility ratio of 0.8 indicates that 80 percent of the sky is visible.

  • The percentage of visible sky will be included in the results. This value is equal to the area above the skyline, divided by the area above the Base Visibility Angle parameter value and is calculated only within the azimuth range of the skyline.

Parameters

LabelExplanationData Type
Input Observer Point Features

The input features containing one or more observer points.

Feature Layer
Input Line Features

The line features that represent the skyline.

Feature Layer
Base Visibility Angle
(Optional)

The baseline vertical angle that will be used to calculate the percentage of visible sky. Zero is the horizon, 90 is straight up, and -90 is straight down. The default is 0.

Double
Additional Fields
(Optional)

Specifies whether additional fields will be included in the angles table.

  • Unchecked—Additional fields will not be included. This is the default.
  • Checked—Additional fields will be included.
Boolean
Output Angles Table
(Optional)

The table that will be created for outputting the horizontal and vertical angles from the observer point to each of the vertices on the skyline.

Table
Output Graph Name
(Optional)

This parameter is not supported.

Graph
Output Graph Image
(Optional)

The image of the polar chart depicting the radial view of the visible skyline. The image can be created in PNG, JPG, JPEG, or SVG format.

File

Derived Output

LabelExplanationData Type
Visibility Ratio

The average percentage of visible sky for all observers. This value is expressed as a value from 0 to 1, in which 0.8 represents 80 percent visibility of the skyline.

Double

arcpy.ddd.SkylineGraph(in_observer_point_features, in_line_features, {base_visibility_angle}, {additional_fields}, {out_angles_table}, {out_graph}, {out_image_file})
NameExplanationData Type
in_observer_point_features

The input features containing one or more observer points.

Feature Layer
in_line_features

The line features that represent the skyline.

Feature Layer
base_visibility_angle
(Optional)

The baseline vertical angle that will be used to calculate the percentage of visible sky. Zero is the horizon, 90 is straight up, and -90 is straight down. The default is 0.

Double
additional_fields
(Optional)

Specifies whether additional fields will be included in the angles table.

  • NO_ADDITIONAL_FIELDSAdditional fields will not be included. This is the default.
  • ADDITIONAL_FIELDSAdditional fields will be included.
Boolean
out_angles_table
(Optional)

The table that will be created for outputting the horizontal and vertical angles from the observer point to each of the vertices on the skyline.

Table
out_graph
(Optional)

This parameter is not supported.

Graph
out_image_file
(Optional)

The image of the polar chart depicting the radial view of the visible skyline. The image can be created in PNG, JPG, JPEG, or SVG format.

File

Derived Output

NameExplanationData Type
out_visibility_ratio

The average percentage of visible sky for all observers. This value is expressed as a value from 0 to 1, in which 0.8 represents 80 percent visibility of the skyline.

Double

Code sample

SkylineGraph example 1 (Python window)

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

arcpy.env.workspace = "C:/data"
arcpy.ddd.SkylineGraph("observers.shp", "skyline_outline.shp", 0, 
                      "ADDITIONAL_FIELDS", "table.dbf")
SkylineGraph example 2 (stand-alone script)

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

# Set environment settings
arcpy.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.ddd.SkylineGraph(inPts, inLines, 0, "ADDITIONAL_FIELDS", outTable)

Licensing information

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

Related topics