Feature Class Z To ASCII (3D Analyst)

Summary

Exports 3D features to ASCII text files storing GENERATE, XYZ, or profile data.

Usage

  • The Profile option writes a two-column ASCII file that converts 3D line features into records which can be used to generate line graphs. Each line from the source feature class will be written to a separate file whose name is appended with the line's unique ID. Each row in the ASCII file will contain the distance from the starting position of the line to the vertex (D) followed by the elevation at that vertex. When loading the resulting ASCII file into a graphing application, the first column would be used to define the x-axis and the second column would be used to define the y-axis.

    0 z1
    D1 z2
    D2 z3
    D3 z4
  • The XYZ option writes x-, y-, and z-coordinates as floating-point values, where each row represents a point record.

    x1 y1 z1
    x2 y2 z2
    x3 y3 z3
    x4 y4 z4
    Note:

    Point and multipoint features are written to the same file, whereas each polygon and polyline feature is written to a separate text file whose name is appended with the feature's ID. Each part of a multi-part feature is written to a separate file with its part number following the feature's ID in the file's name.

  • The GENERATE format does not support header lines, but it stores all input features in one file.

    • Point features are stored with their respective ID and XYZ coordinates, and the last line is denoted by the END keyword:
      id1 x1 y1 z1
      id2 x2 y2 z2
      id3 x3 y3 z3
      id4 x4 y4 z4END
      Note:

      Multipoint features that originate from the same record in the originating feature class will share the same ID.

    • Line and polygon features are separated by the END keyword, and two successive END keywords indicate the end of the file:
      id1
      x1 y1 z1
      x2 y2 z2
      x3 y3 z3
      x4 y4 z4
      END
      
      id2
      x1 y1 z1
      x2 y2 z2
      END
      
      END
      Note:

      The first and last XYZ coordinates for polygon features are always identical.

Syntax

arcpy.3d.FeatureClassZToASCII(in_feature_class, output_location, out_file, {format}, {delimiter}, {decimal_format}, {digits_after_decimal}, {decimal_separator})
ParameterExplanationData Type
in_feature_class

The 3D point, multipoint, polyline, or polygon feature class that will be exported to an ASCII file.

Feature Layer
output_location

The folder to which output files will be written.

Folder
out_file

The name of the resulting ASCII file.

If a line or polygon feature class is exported to XYZ format, the file name is used as a base name. Each feature will have a unique file output, since the XYZ format only supports one line or polygon per file. Multipart features will also have each part written to a separate file. The file name will be appended with the OID of each feature, as well as any additional characters needed to make each file name unique.

String
format
(Optional)

Specifies the format of the ASCII file being created.

  • GENERATEWrites output in the GENERATE format. This is the default.
  • XYZWrites XYZ information of input features. One file will be created for each line or polygon in the input feature.
  • PROFILEWrites profile information for line features that can be used in external graphing applications.
String
delimiter
(Optional)

Specifies the delimiter that will indicate the separation of entries in the columns of the text file table.

  • SPACEA space will be used to delimit field values. This is the default.
  • COMMAA comma will be used to delimit field values. This option is not applicable if the decimal separator is also a comma.
String
decimal_format
(Optional)

Specifies the method that will determine the number of significant digits stored in the output files.

  • AUTOMATICThe number of significant digits needed to preserve the available precision, while removing unnecessary trailing zeros, is automatically determined. This is the default.
  • FIXEDThe number of significant digits is defined in the Digits after Decimal parameter.
String
digits_after_decimal
(Optional)

The number of digits written after the decimal for floating-point values written to the output files. This parameter is used when the Decimal Notation parameter is set to Specified Number (decimal_format=FIXED in Python).

Long
decimal_separator
(Optional)

Specifies the decimal character that will differentiate the integer of a number from its fractional part.

  • DECIMAL_POINTA point is used as the decimal character. This is the default.
  • DECIMAL_COMMAA comma is used as the decimal character.
String

Derived Output

NameExplanationData Type
derived_output

The folder to which output files will be written.

Folder; File

Code sample

FeatureClassZToASCII example 1 (Python window)

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

arcpy.env.workspace = "C:/data"
arcpy.FeatureClassZToASCII_3d("LidarPts.shp", "", "ASCII_LidarPts.txt",
                            "GENERATE", "COMMA", "FIXED", 6, "DECIMAL_POINT")
FeatureClassZToASCII example 2 (stand-alone script)

The following sample demonstrates the use of this tool in a stand-alone Python script.

'''****************************************************************************
Name: FeatureClassZToASCII Example
Description: This script demonstrates how to use the
             FeatureClassZToASCII tool to create generate files for all
             z-aware point features in a given workspace.
****************************************************************************'''
import arcpy

try:
    # Set environment settings
    arcpy.env.workspace = 'C:/data'
    # List all points in the target workspace
    fcList = arcpy.ListFeatureClasses("*", "POINT")
    if fcList:
        # Set Local Variables
        outFolder = "C:/output"
        outFormat = "GENERATE"
        delimeter = "SPACE"
        decimal = "FIXED"
        digits = 3
        dec_sep = "DECIMAL_POINT"
        for fc in fcList:
            # Use Describe method to evaluate whether the feature class is z-aware
            desc = arcpy.Describe(fc)
            if desc.hasZ == True:
                # Define the output file name by replacing '.shp' with _ascii.txt
                outName = fc.replace('.shp', '') + "_ascii.txt"
                #Execute FeatureClassZToASCII_3d
                arcpy.FeatureClassZToASCII_3d(fc, outFolder, outName, outFormat, delimeter, decimal, digits, dec_sep)
    else:
        print("There are no feature classes in the " + env.workspace + " directory.")

except arcpy.ExecuteError:
    print(arcpy.GetMessages())
except Exception as err:
    print(err)

Licensing information

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

Related topics