Generate OIS Obstacle Data (Aviation)

Available with Aviation Airports license.

Available with Aviation Charting license.

Summary

Generates a JSON string that is stored in the OBSTACLEJSON field on the input Obstruction Identification Surface (OIS) multipatch feature class. This class contains the data necessary to depict obstacles to safety of flight within the approach surfaces (in the form of points, lines, or polygons) in the Terrain and Obstacle Profile layout element.

For each runway feature, the tool identifies each approach surface associated with that runway. For each approach surface, the tool uses the underlying elevation models and input obstacle features to determine the highest elevations and heights of those obstacle features that intersect the approach surfaces extent. The resulting 3D points, representing the highest-point cross section of each affected obstacle, are created and stored in JSON format and saved in the corresponding approach OIS feature.

The following table lists the values that are populated in the OBSTACLEJSON output message. They are given per input obstacle feature if they planimetrically intersect an input approach surface multipatch feature.

FieldExamplePopulated with

Type_Code

"Type_Code": "Stack"

Input Obstacle Features Type_Code field. It is given as the description for its coded domain value or as Unknown if no domain value is found or if the input is null.

HACCM

"HACCM": 0.304801

Input Obstacle Features HORIZACC_VAL field, converted to meters. It is given as -1.0 if the input is null.

VACCM

"VACCM": 0.304801

Input Obstacle Features VERTACC_VAL field, converted to meters. It is given as -1.0 if the input is null.

Height

"Height": 16.664848

The Input Obstacle Height parameter value (feature geometry or input field), converted to meters.

GNDElev

"GNDElev": 335.647491

The ground elevation at the input obstacle's location from the Elevation Source value—a digital elevation model (DEM) or input field—converted to meters.

NormalDist

"NormalDist": 946.035675

The distance, in meters, between the obstacle and the nearest point on the runway centerline.

Offset

"Offset": 143.128218

The distance, in meters, between the obstacle and the nearest point on the extended runway centerline.

X

"X": -95.953753

The x-coordinate of the obstacle in WGS84 decimal degrees.

Y

"Y": 45.550517

The y-coordinate of the obstacle in WGS84 decimal degrees.

ZVMC

"ZVMC": 352.31234

The elevation of the top of the obstacle (Height + GNDElev) in meters.

OIS

"OIS": 384.942139

The z-value of the OIS at the obstacle's location.

Penetrates

"Penetrates": false

A value of true if ZVMC is greater than or equal to OIS; otherwise, false.

Label

"Label": "362"

The value of the Obstacle Labels input parameter.

Shadowing

"Shadowed": false

A value of false for shadowing obstacles and a value of true for an obstacle that is shadowed by another.

Usage

  • The Input Runway Features parameter must be z-enabled and have projected horizontal and vertical coordinate systems defined. It must include a populated Runway Designator text field, which must be named as one of the following from the ArcGIS Aviation data models:

    • RWYDESG
    • RUNWAYDESIGNATORIDENTIFIER
    • DESIGNATOR_TXT
    Tip:

    Recommended input features are RunwayCenterline from the Airports data models (18B or 18C) or ADHPSurfaceLine from the AIS data model. For more information, see the respective schemas for attribute properties.

  • The Input Obstacle Features parameter value must be z-enabled and have projected horizontal and vertical coordinate systems defined.

    Tip:

    Recommended input features are VerticalStructurePoint, VerticalStructureLine, and VerticalStructurePolygon from the Airports 18B or 18C data models. For more information, see the respective schemas for the attribute properties.

  • Include a field for the Input Obstacle Features parameter value that represents the type of obstacle that is used by the tool to populate the "Type_Code" values in the OBSTACLEJSON field results. Null values in this field will be written as Unknown in the output. Permissible field names are the following:

    • TYPE_CODE
    • OBSTACLETY
    • OBSTACLETYPECODE
    • ObsType
    • OBJECTTYPECODE
    • OBJECTTYPE

  • The Input Obstacle Features parameter can include the fields listed below. If present, the values of these fields will contribute to the HACCM and VACCM fields in the output OBSTACLEJSON values:

    • HORIZACC_VAL
    • HORIZACC_UOM
    • VERTACC_VAL
    • VERTACC_UOM

  • The Target OIS Features parameter value must be a multipatch feature class with projected horizontal and vertical coordinate systems defined. It must contain approach features and include the following fields:

    • RWYDESG or LANDINGSTRIPDESIGIDENTIFIER or DESIGNATOR_TXT (populated with a runway designator, for example, '09/27')
    • NAME (populated with the value 'Approach Surface')
    • OBSTACLEJSON (populated by the tool)
      Tip:

      Recommended input features are ObstructionIdSurface_MP from the Airports 18B or 18C data models. The approach features can be generated with one of the tools from the Obstruction Identification Surfaces toolset.

      Note:

      The field length must be at least 50,000 characters. A warning appears if the JSON output exceeds the length of the OBSTACLEJSON field.

  • Input Obstacle Feature elevations are specified by the Obstacle Feature Height Type parameter. Use the Absolute Height (ABSOLUTE_HEIGHT in Python) option if the input data includes feature geometry or a numeric attribute field with the elevation value of the top of the obstacle above mean sea level. Use the Relative Height (RELATIVE_HEIGHT in Python) option if feature geometry or a numeric attribute field contains the value of the obstacle height above ground level.

    Obstacle Feature Height Type
  • This tool requires base elevation data to function correctly. That data can come from one or more underlying DEMs or from a numeric attribute field in the input obstacle feature class. One or the other must be provided, with the appropriate option specified using the Elevation Source parameter.

  • The tool will use a flight path ID field (PATHID, text, Nullable, or 255) for the Target OIS Features parameter to associate curved approach polylines with specific approach surfaces. This is required if you have an Input Flight Path Features parameter value. Use this value for the Target OIS Features parameter with the OBJECTID field of the corresponding Input Flight Path Features parameter value. This will be populated by the Create Curved Approach tool when creating the curved approach surface or surfaces.

  • If the tool is run repeatedly with different Input Obstacle Features parameter values, it will append the generated JSON data for each set of obstacles to each affected approach surface feature. Subsequently running the tool with an updated version of Input Obstacle Features values will selectively update the JSON data for those features without affecting the JSON data generated using other Input Obstacle Features values.

  • You can exclude obstacles in this tool's output that are shadowed by other obstacles. The following diagram shows how the Horizontal Distance and Slope parameters are used to generate these output features:

    Diagram showing how shadowed obstacles are calculated by this tool

    In this diagram, a value of 300 meters is given for the Horizontal Distance parameter. For obstacles 300 meters or less away from the end of the runway, the angle of the shadow will be considered horizontal. A slope of 1.2 is provided for the Slope parameter. For obstacles greater than 300 meters from the end of the runway, the shadow will be cast at an object behind the obstacle at a slope of 1.2 percent.

    Note:

    Output of shadowing obstacles is only supported with point obstacles.

Parameters

LabelExplanationData Type
Input Runway Features

The input runway dataset. The feature class must be z-enabled and contain polylines.

Feature Layer
Input Elevation Model
(Optional)

The DEMs covering the obstacles that will be used to derive base elevation values. This parameter is used if Elevation Source is set to Elevation DEM.

Raster Layer
Input Obstacle Features

The input obstacle features that will be analyzed. The feature class must be z-enabled.

Feature Layer
Target OIS Features

The multipatch features with defined airport data model schema. The feature class must be z-enabled.

Feature Layer
Obstacle Height
(Optional)

Specifies the field that will contain the height of the obstacle features or the keyword FEATURE_GEOMETRY to indicate obstacle feature geometry z-coordinate values.

  • Feature GeometryThe field that will contain the height of the obstacle features.
String
Unit
(Optional)

Specifies the obstacle height unit of measure that will be used.

  • KilometersThe unit will be kilometers.
  • MetersThe unit will be meters.
  • DecimetersThe unit will be decimeters.
  • CentimetersThe unit will be centimeters.
  • MillimetersThe unit will be millimeters.
  • Nautical MilesThe unit will be nautical miles.
  • MilesThe unit will be miles.
  • YardsThe unit will be yards.
  • FeetThe unit will be feet.
  • InchesThe unit will be inches
  • Decimal DegreesThe unit will be decimal degrees.
  • PointsThe unit will be points.
  • UnknownThe unit will be unknown.
String
Input Flight Path Features
(Optional)

The polyline features that will define curved approaches to the specified runways. If unspecified, all input features will be processed as straight approaches.

Feature Layer
Obstacle Labels
(Optional)

A field from the input obstacle feature class that will be used to label the obstacle. When an obstacle JSON generated by this tool is later used to create a Terrain and Obstacle Profile element in a layout, the data from the selected field will be used to label the input point obstacles in that element.

The Obstacle Labels parameter only applies when the Input Obstacle Features parameter values contain point features.

Note:

If no value is specified, the ObjectID will be applied by default.

String
Obstacle Feature Height Type
(Optional)

Specifies how obstacle height values will be measured.

  • Absolute height Obstacle heights will be measured from sea level.
  • Relative height Obstacle heights will be measured from ground level. This is the default.
String
Elevation Source
(Optional)

Specifies where obstacle base elevation heights will be found.

  • Elevation field Base elevation heights will be found in a numeric field of the obstacle feature class.
  • Elevation DEM Base elevation heights will be found by deriving them from one or more DEMs. This is the default.
String
Elevation Field
(Optional)

The field that will contain base elevation heights of the obstacle features.

This parameter is used if Elevation Source is set to Elevation field. The default is the first numeric field in the obstacle feature class.

String
Elevation Field Units
(Optional)

Specifies the linear unit that will be used for the base elevation values. This parameter is used if Elevation Source is set to Elevation field.

  • KilometersThe unit will be kilometers.
  • MetersThe unit will be meters. This is the default.
  • DecimetersThe unit will be decimeters.
  • CentimetersThe unit will be centimeters.
  • MillimetersThe unit will be millimeters.
  • Nautical milesThe unit will be nautical miles.
  • MilesThe unit will be miles.
  • YardsThe unit will be yards.
  • FeetThe unit will be feet.
  • InchesThe unit will be inches
  • Decimal degreesThe unit will be decimal degrees.
  • PointsThe unit will be points.
  • UnknownThe unit will be unknown.
String
Obstacle Output Method
(Optional)

Specifies the obstacles that will be included in the output feature class.

  • All obstaclesAll obstacles within the extent of the OIS will be included in the output.
  • Penetrating obstaclesOnly obstacles that penetrate the OIS will be included in the output.
  • Shadowing obstaclesOnly the obstacles that shadow other obstacles will be included in the output.
String
Horizontal Distance
(Optional)

The length of the approach surface in meters (calculated from the runway end) where shadows are considered horizontally aligned.

Double
Slope
(Optional)

The slope of the shadow that will be considered past the Horizontal Distanceparameter value.

Double

Derived Output

LabelExplanationData Type
Output OIS Features

The updated multipatch feature class.

Feature Layer

arcpy.aviation.GenerateOISObstacleData(in_runway_features, {in_dems}, in_obstacle_features, target_ois_features, {obstacle_height_field}, {obstacle_height_unit}, {in_flightpath_features}, {label_field}, {height_option}, {elevation_option}, {elevation_field}, {elevation_field_unit}, {obstacle_output_method}, {shadow_horizontal_distance}, {shadow_slope})
NameExplanationData Type
in_runway_features

The input runway dataset. The feature class must be z-enabled and contain polylines.

Feature Layer
in_dems
[in_dems,...]
(Optional)

The DEMs covering the obstacles that will be used to derive base elevation values. This parameter is used if elevation_option is set to ELEVATION_DEM.

Raster Layer
in_obstacle_features

The input obstacle features that will be analyzed. The feature class must be z-enabled.

Feature Layer
target_ois_features

The multipatch features with defined airport data model schema. The feature class must be z-enabled.

Feature Layer
obstacle_height_field
(Optional)

Specifies the field that will contain the height of the obstacle features or the keyword FEATURE_GEOMETRY to indicate obstacle feature geometry z-coordinate values.

  • FEATURE_GEOMETRYThe field that will contain the height of the obstacle features.
String
obstacle_height_unit
(Optional)

Specifies the obstacle height unit of measure that will be used.

  • KILOMETERSThe unit will be kilometers.
  • METERSThe unit will be meters.
  • DECIMETERSThe unit will be decimeters.
  • CENTIMETERSThe unit will be centimeters.
  • MILLIMETERSThe unit will be millimeters.
  • NAUTICAL_MILESThe unit will be nautical miles.
  • MILESThe unit will be miles.
  • YARDSThe unit will be yards.
  • FEETThe unit will be feet.
  • INCHESThe unit will be inches
  • DECIMAL_DEGREESThe unit will be decimal degrees.
  • POINTSThe unit will be points.
  • UNKNOWNThe unit will be unknown.
String
in_flightpath_features
(Optional)

The polyline features that will define curved approaches to the specified runways. If unspecified, all input features will be processed as straight approaches.

Feature Layer
label_field
(Optional)

A field from the input obstacle feature class that will be used to label the obstacle. When an obstacle JSON generated by this tool is later used to create a Terrain and Obstacle Profile element in a layout, the data from the selected field will be used to label the input point obstacles in that element.

The Obstacle Labels parameter only applies when the Input Obstacle Features parameter values contain point features.

Note:

If no value is specified, the ObjectID will be applied by default.

String
height_option
(Optional)

Specifies how obstacle height values will be measured.

  • ABSOLUTE_HEIGHT Obstacle heights will be measured from sea level.
  • RELATIVE_HEIGHT Obstacle heights will be measured from ground level. This is the default.
String
elevation_option
(Optional)

Specifies where obstacle base elevation heights will be found.

  • ELEVATION_FIELD Base elevation heights will be found in a numeric field of the obstacle feature class.
  • ELEVATION_DEM Base elevation heights will be found by deriving them from one or more DEMs. This is the default.
String
elevation_field
(Optional)

The field that will contain base elevation heights of the obstacle features.

This parameter is used if elevation_option is set to ELEVATION_FIELD. The default is the first numeric field in the obstacle feature class.

String
elevation_field_unit
(Optional)

Specifies the linear unit that will be used for the base elevation values. This parameter is used if elevation_option is set to ELEVATION_FIELD.

  • KILOMETERSThe unit will be kilometers.
  • METERSThe unit will be meters. This is the default.
  • DECIMETERSThe unit will be decimeters.
  • CENTIMETERSThe unit will be centimeters.
  • MILLIMETERSThe unit will be millimeters.
  • NAUTICAL_MILESThe unit will be nautical miles.
  • MILESThe unit will be miles.
  • YARDSThe unit will be yards.
  • FEETThe unit will be feet.
  • INCHESThe unit will be inches
  • DECIMAL_DEGREESThe unit will be decimal degrees.
  • POINTSThe unit will be points.
  • UNKNOWNThe unit will be unknown.
String
obstacle_output_method
(Optional)

Specifies the obstacles that will be included in the output feature class.

  • ALL_OBSTACLESAll obstacles within the extent of the OIS will be included in the output.
  • PENETRATING_OBSTACLESOnly obstacles that penetrate the OIS will be included in the output.
  • SHADOWING_OBSTACLESOnly the obstacles that shadow other obstacles will be included in the output.
String
shadow_horizontal_distance
(Optional)

The length of the approach surface in meters (calculated from the runway end) where shadows are considered horizontally aligned.

Double
shadow_slope
(Optional)

The slope of the shadow that will be considered past the shadow_horizontal_distanceparameter value.

Double

Derived Output

NameExplanationData Type
out_ois_features

The updated multipatch feature class.

Feature Layer

Code sample

GenerateOISObstacleData example (stand-alone script)

The following Python window script demonstrates how to use the GenerateOISObstacleData function.

import arcpy

# set gp environment
arcpy.CheckOutExtension("Airports")

# Input RunwayCenterline Feature Class
inRunwayFeatures = r"C:\data\ois.gdb\RunwayCenterlines"

# Input Terrain DEM Raster
inDEMRaster = [r"C:\data\ois.gdb\AirportFirstDEM",
               r"C:\data\ois.gdb\AirportSecondDEM"]

# Input Obstacle Feature Class
inOISObstacles = r"C:\data\ois.gdb\Obstacles"

# Input Obstruction Identification Surface Feature Class
targetOISFeatures = r"C:\data\ois.gdb\ObstructionIdSurface"

# Input Curved Approach Feature Class
inCurvedApproachFeatures = r"C:\data\ois.gdb\CurvedApproach"

# Processing GenerateOISObstacleData
arcpy.aviation.GenerateOISObstacleData(inRunwayFeatures, inDEMRaster,
                                       inOISObstacles, targetOISFeatures,
                                       "HEIGHT_VAL", "FEET", inCurvedApproachFeatures, "OBJECTID","RELATIVE_HEIGHT","ELEVATION_DEM")


arcpy.CheckInExtension("Airports")

Environments

Licensing information

  • Basic: No
  • Standard: Requires ArcGIS Aviation Charting
  • Advanced: Requires ArcGIS Aviation Charting

Related topics