ASCII 3D To Feature Class (3D Analyst)

Summary

Imports 3D features from one or more ASCII files stored in XYZ, XYZI, or GENERATE formats into a new feature class.

Illustration

ASCII 3D To Feature Class example

Usage

  • All input files must be of the same format and geometry type.

  • XYZ and XYZI formats support header lines and treat the first row that starts with three consecutive numbers as the beginning of the point records. Both formats can store points, lines, and polygons, but each file may only contain one single-part line or polygon feature. Polygon features must close, with the coordinates of the last vertex being identical to that of the first, and must not self-intersect.

  • XYZ files store x, y, and z coordinates as floating-point values, where each row represents a distinct point record. The XYZ coordinates can be followed by alphanumeric entries, but this information will not be transferred to the resulting feature class.

  • XYZI files store x, y, z, and intensity measures. Intensity values are stored in a binary large object (BLOB) field for multipatch outputs.

    Note:

    If the ASCII file is in XYZI format but the intensity measures are not desired, choose XYZ. This will skip the intensity value when reading the files.

  • The GENERATE format does not support header lines, but it provides an ID for each point along with XYZ coordinates, and the last line of the file is optionally noted using the END keyword:

    id x y z
    id x y z
    .
    .
    END
  • The GENERATE format supports multiple features per file. For lines and polygons, the END keyword signals the end of a feature, and each feature must be a single-part feature. Two END keywords in a row indicates the end of the file.

    id
    x y z
    x y z
    x y z
    END
    id
    x y z
    x y z
    END
    END
    Note:

    Polygons should be oriented clockwise, have no self-intersections, and be closed (that is, the last vertex is equal to the first). If one of these conditions is not met, the output polygon will not be valid. The Check Geometry tool can be used to validate the resulting features, and the Repair Geometry tool can be used to correct the errors.

Parameters

LabelExplanationData Type
ASCII 3D Data

The ASCII files or folders containing data in XYZ, XYZI (with lidar intensity), or 3D GENERATE format. All input files must be in the same format. If a folder is specified, the File Suffix parameter becomes required, and all the files that have the same extension as the specified suffix will be processed.

In the Geoprocessing pane, a folder can also be specified as an input by selecting the folder in File Explorer and dragging it onto the parameter's input box.

Folder; File
File Format

The format of the ASCII files that will be converted to a feature class.

  • XYZText file that contain geometry information stored as XYZ coordinates.
  • XYZIText files that contain XYZ coordinates alongside intensity measurements.
  • GenerateText files structured in the Generate format.
String
Output Feature Class

The feature class that will be produced.

Feature Class
Output Feature Class Type

The geometry type of the output feature class.

  • Multipoint featuresMultipoints are recommended the input data contains a large number of points and attributes per feature are not required.
  • Point featuresEach XYZ coordinate will produce one point feature.
  • Polyline featuresThe output will contain polyline features.
  • Polygon featuresThe output will contain polygon features.
String
Z Factor
(Optional)

The factor by which z-values will be multiplied. This is typically used to convert z linear units to match x,y linear units. The default is 1, which leaves elevation values unchanged. This parameter is not available if the spatial reference of the input surface has a z-datum with a specified linear unit.

Double
Coordinate System
(Optional)

The coordinate system of the input data. The default is an Unknown Coordinate System. If specified, the output may or may not be projected into a different coordinate system. This depends the whether the geoprocessing environment has a coordinate system defined for the location of the target feature class.

Coordinate System
Average Point Spacing
(Optional)

The average planimetric distance between points of the input. This parameter is only used when the output geometry is set to MULTIPOINT, and its function is to provide a means for grouping the points together. This value is used in conjunction with the points per shape limit to construct a virtual tile system used to group the points. The tile system's origin is based on the domain of the target feature class. Specify the spacing in the horizontal units of the target feature class.

Double
File Suffix
(Optional)

The suffix of the files that will be imported from an input folder. This parameter is required when a folder is specified as input.

String
Decimal Separator
(Optional)

The decimal character that will be used in the text file to differentiate the integer of a number from its fractional part.

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

arcpy.ddd.ASCII3DToFeatureClass(input, in_file_type, out_feature_class, out_geometry_type, {z_factor}, {input_coordinate_system}, {average_point_spacing}, {file_suffix}, {decimal_separator})
NameExplanationData Type
input
[input,...]

The ASCII files or folders containing data in XYZ, XYZI (with lidar intensity), or 3D GENERATE format. All input files must be in the same format. If a folder is specified, the File Suffix parameter becomes required, and all the files that have the same extension as the specified suffix will be processed.

In the Geoprocessing pane, a folder can also be specified as an input by selecting the folder in File Explorer and dragging it onto the parameter's input box.

Folder; File
in_file_type

The format of the ASCII files that will be converted to a feature class.

  • XYZText file that contain geometry information stored as XYZ coordinates.
  • XYZIText files that contain XYZ coordinates alongside intensity measurements.
  • GENERATEText files structured in the Generate format.
String
out_feature_class

The feature class that will be produced.

Feature Class
out_geometry_type

The geometry type of the output feature class.

  • MULTIPOINTMultipoints are recommended the input data contains a large number of points and attributes per feature are not required.
  • POINTEach XYZ coordinate will produce one point feature.
  • POLYLINEThe output will contain polyline features.
  • POLYGONThe output will contain polygon features.
String
z_factor
(Optional)

The factor by which z-values will be multiplied. This is typically used to convert z linear units to match x,y linear units. The default is 1, which leaves elevation values unchanged. This parameter is not available if the spatial reference of the input surface has a z-datum with a specified linear unit.

Double
input_coordinate_system
(Optional)

The coordinate system of the input data. The default is an Unknown Coordinate System. If specified, the output may or may not be projected into a different coordinate system. This depends the whether the geoprocessing environment has a coordinate system defined for the location of the target feature class.

Coordinate System
average_point_spacing
(Optional)

The average planimetric distance between points of the input. This parameter is only used when the output geometry is set to MULTIPOINT, and its function is to provide a means for grouping the points together. This value is used in conjunction with the points per shape limit to construct a virtual tile system used to group the points. The tile system's origin is based on the domain of the target feature class. Specify the spacing in the horizontal units of the target feature class.

Double
file_suffix
(Optional)

The suffix of the files that will be imported from an input folder. This parameter is required when a folder is specified as input.

String
decimal_separator
(Optional)

The decimal character that will be used in the text file to differentiate the integer of a number from its fractional part.

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

Code sample

ASCII3DToFeatureClass example 1 (Python window)

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

arcpy.env.workspace = "C:/data"
#Create spatial reference object using WKID
sr = arcpy.SpatialReference(32136)
arcpy.ASCII3DToFeatureClass_3d("masspntz.gen", "GENERATE", "elevation_points.shp", 
                               "MULTIPOINT", z_factor=3.28, 
                               input_coordinate_system=sr, average_point_spacing=2.5)
ASCII3DToFeatureClass example 2 (stand-alone script)

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

'''****************************************************************************
Name: ASCII3D_to_Feature_Class Example
Description: Creates a TIN surface using XYZI files in a folder and breaklines
             imported from ASCII files.
****************************************************************************'''
# Import system modules
import arcpy

# Set environment settings
arcpy.env.workspace = "C:/data"

# Define the spatial reference using the name
sr = arcpy.SpatialReference("Hawaii Albers Equal Area Conic")

# Create the elevation points
arcpy.ddd.ASCII3DToFeatureClass("Elevation Points", "XYZI",
                               "elevation_points.shp",
                               "MULTIPOINT", z_factor=3.28,
                               input_coordinate_system=sr,
                               average_point_spacing=2.5,
                               file_suffix="XYZ")

# Create the break lines
arcpy.ddd.ASCII3DToFeatureClass("brklines.gen", "GENERATE",
                               "breaklines.shp",
                               "POLYLINE", z_factor=3.28,
                               input_coordinate_system=sr)

arcpy.ddd.CreateTin("elevation_tin", sr,
                    [["breaklines.shp", "Shape", "hardline"],
                    ["elevation_points.shp", "Shape", "masspoints"]],
                    "CONSTRAINED_DELAUNAY")

Related topics