IMPORT_ASCII

The IMPORT_ASCII command imports data from a generic ASCII text file for later use. The following parameters are supported by the command. In addition, all of the option parameters for the IMPORT command are also supported for this command.

  • FILENAME - full path to file to load the data from
  • TYPE - type of import that we're doing
    • POINT_ONLY - all lines with coordinate data will result in a new point object begin created
    • POINT_AND_LINE - both point and line features (and optionally areas) will be created from coordinate data in the file. Line features will be created when coordinate data lines are back to back in the file. All individual coordinate lines will result in a point object being created
    • AREA_ONLY - only closed area features will be created from the sequences of coordinates.
    • ELEVATION - all lines in the file with 3 coordinate values (x,y, and elevation) will be used to create an elevation grid. The data will be triangulated and gridded automatically, resulting in a fully usable elevation grid that can be exported to any of the supported elevation data formats.
    • LIDAR - all 3D points in the file are added to a Lidar point cloud. You can load a .xyzi file to also add the intensity. Use the LIDAR_CLASS parameter to specify a numeric classification to apply to all points, like LIDAR_CLASS=2 to assign as ground shot points.
    • DIST_BEARING - all lines contain a distance and bearing from some other point location provided using the START_POS parameter. This will create point features. You should also provide a COORD_ORDER parameter with a custom definition for the column locations. The distances should be in meters and the bearings in degrees relative to north.
    • DIST_BEARING_LINE - all lines contain a distance and bearing for a segment of a line. The line starts at the point location provided using the START_POS parameter. This will create a single line feature. You should also provide a COORD_ORDER parameter with a custom definition for the column locations. The distances should be in meters and the bearings in degrees relative to north.
    • DIST_BEARING_SEGS - all lines contain a distance and bearing for a segment of a line. For each line in the file, a line will be created that starts at the point location provided using the START_POS parameter. You should also provide a COORD_ORDER parameter with a custom definition for the column locations. The distances should be in meters and the bearings in degrees relative to north.
  • COORD_DELIM - specifies the delimiter between coordinates in coordinate lines

    • AUTO - automatically detect the delimiter type (default)
    • WHITESPACE - coordinates are separated with one or more space and/ or tab characters
    • COMMA - coordinates are separated by commas
    • SEMICOLON - coordinates are separated by semicolons
    • TAB - coordinates are separated by tabs
  • COORD_FORMAT - specifies the format of the coordinate values. The default is DECIMAL.
    • DECIMAL - standard numerical value. No extra values are packed into one.
    • DDMMSS - degree coordinates are stored as the number of degrees times 10,000 plus the minutes times 100 plus the seconds. So for example 35 deg 15 min and 12.3 seconds would look like 351512.3.
    • DDMM - degree coordinates are stored as the number of degrees times 100 plus the minutes. So for example 35 deg 15.2 min would look like 3515.2.
    • DD_MMSS - degree coordinates are stored as DD.MMSS (i.e. degrees + ( minutes / 100 ) + ( seconds / 10000 ). So for example 35 deg 15 min and 12.3 seconds would look like 35.15123.
    • ECEF - the XYZ coordinates represent ECEF (Earth-Centered Earth-Fixed) coordinates. They actual values are the same as the DECIMAL format. The ECEF coordinates will be converted to lat/lon degrees using the ellipsoid implied by the projection datum, then converted to whatever projection is specified.
  • COORD_ORDER specifies the order of the coordinates in coordinate lines
    • X_FIRST - x coordinates (i.e. easting or longitude) come first, followed by y coordinates (i.e. northing or latitude) (default)
    • Y_FIRST - y coordinates (i.e. northing or latitude) come first, followed by x coordinates (i.e. easting or longitude)
    • WKT - coordinate string in WKT (well-known-text format). This allows single line representations of areas, lines, and points.
    • MGRS - MGRS (military grid reference system) coordinate string
    • CUSTOM - specifies a custom column layer. The columns are specified as 1-based numbers (i.e. first column is 1, not 0). The values should be specified as "CUSTOM,x_col,y_col[,z_col][,time_col]", or for DIST_BEARING as "CUSTOM,dist_col,bearing_col[,z_col]". So for example if the X/longitude is in column 3, the Y/latitude in column 4, and the Z in the first column, use "CUSTOM,3,4,1". If you need to specify that an optional colulmn isn't present, use -1 for that column. For example if you have an X,Y,time file, use "CUSTOM,1,2,-1,3".
  • COORD_PREFIX - if present, this line is used to specify what special character sequence coordinate lines start with. For example, if the coordinate lines in the file started with the character sequence "XY,", you should use COORD_PREF="XY,". By default no coordinate prefix is assumed.
  • INC_COORD_LINE_ATTRS - set the value of this parameter to YES if you wish to use any leftover text at the end of coordinate lines as attributes for the feature the coordinates are in. This could be useful if elevation data is present at the end of the lines. By default, the value of this attribute is NO.
  • INC_ELEV_COORDS - this parameter controls whether or not the value right after the 2nd coordinate column (if there is one) will be treated as an elevation value. Use INC_ELEV_COORDS=YES or INC_ELEV_COORDS=NO to enable (the default) or disable this behavior.
  • NO_DATA_VAL - specifies what Z value to treat as 'no data' when loading and gridding data with a Z component. If not specified, a default of -999999 will be used. This value should be specified in the native units of the file.
  • VOID_ELEV - specifies a value to replace any void / no data pixels with when loading as a grid. This will give no data values the specified numeric value, instead of treating them as null. For example VOID_ELEV=0 will replace no data values (default value of -999999, or otherwise specified with NO_DATA_VAL parameter) with a pixel value of 0.
  • COL_HEADERS - controls whether or not the first line of the file should be used as column headers for coordinate line attributes later in the file. Setting this to YES is useful for things like CSV files with column headers in the first row, otherwise set it to NO (the default).
  • SKIP_COLUMNS - specifies the number of columns (fields) to skip at the start of a coordinate line before trying to read the coordinates. For example, if the X and Y coordinates of a line were in the 3rd and 4th columns of the coordinate line, you'd use a value of SKIP_COLUMNS=2. The default value is 0, meaning that coordinates must be in the first two columns.
  • SKIP_ROWS - specifies the number of rows to skip at the start of a file before trying to read any data. For example, if your file has a fixed header of 20 lines, you would use SKIP_ROWS=20 to skip those header rows.
  • COORD_PAIRS_PER_ROW - specifies the number of coordinate pairs (XY + optional Z and time) that are on each line of the file. If specified the value must be at least 1. Use this to load line or area features from files that have 2 or more coordinate pairs on each line of the file. The pairs are assumed to be sequential, so if you have 3 XYZ coordinate pairs on a line and the first 2 fields are attributes, use SKIP_COLUMNS=2 COORD_PAIRS_PER_ROW=3 to get a triangle from each line in the format attr1,attr2,x1,y1,z1,x2,y2,z2,x3,y3,z3.
  • BREAK_COL_IDX - specifies the 1-based index of the column to break features at if the value in that column changes.
  • BREAK_COL_PEN_UP - specifies that the "break on change column" from the BREAK_COL_IDX parameter is actually a pen up/down field and new features should be started when a 1 is encountered in the field. Use BREAK_COL_PEN_UP=YES to enable.
  • CREATE_AREAS_FROM_LINES - controls whether or not area features will be created from closed line features (first and last point the same) if no CLOSED attribute was specifically provided for the feature.
  • COORD_OFFSET - specifies the offset to apply to any coordinates read in from the file. This offset will be added to each coordinate read in from the file. The offset should be specified as a comma-delimited list of the X, Y, and Z offsets, such as COORD_OFFSET=100000.0,200000.0,0.0
  • COORD_SCALE - specifies the scale factor to apply to any coordinates read in from the file. Each coordinate will be multiplied by these scale factor after being read in from the file. The scale factors should be specified as a comma-delimited list of the X, Y, and Z scale factors, such as COORD_SCALE=0.1,0.1,1.0
  • NO_DATA_DIST_MULT - specifies how far from an actual data point a grid cell has to be before it is treated as a no data value. This number is given as a multiple of the diagonal size of a single grid cell as nominally determined by the gridding algorithm or specified with the SPATIAL_RES parameter. A value of 0 means that all points should be considered as valid.
  • SPATIAL_RES - specifies spatial resolution to use when generating an elevation grid from the data. Defaults to a good value for maintaining the full spatial resolution of the provided point data if not specified. Should be formatted as x_resolution,y_resolution. The units are the units of the projection specified for the file. For example, if UTM with meter units was the file projection and you wanted to export at 30 meter spacing, the parameter/value pair would look like SPATIAL_RES=30.0,30.0.
  • SPATIAL_RES_METERS - specifies spatial resolution to use in meters. The value in meters will automatically be converted to the curent view/export projection units. For example, to do an export at 2.0 meter spacing (or as close as you can get to that in the current units), use SPATIAL_RES_METERS=2.0, or to do an export at 1.0 meters in X by 1.5 meters in Y, use SPATIAL_RES_METERS="1.0,1.5".
  • SHEET_NAME - when loading an Excel format file, specifies the name of the sheet to load. If not provided, the first sheet in the file will be loaded

Distance-Bearing Type Parameters

The following parameters are applicable when loading a file set as TYPE=DIST_BEARING , TYPE=DIST_BEARING_LINE or TYPE=DIST_BEARING_SEGS

  • START_POS - specifies the start position for distance-bearing files. The coordinates must be given in the coordinate system of the layer. For example, if UTM if the current projection, you might specify and easting/northing as follows: START_POS="480000,4310000". You can also specify START_POS="SELECTED" to use the location of a point feature selected with the Digitizer Tool as the position.
  • DIST_BEARING_REL_TO- indicates the basis for the bearing angle. Valid values are: TRUE_NORTH, MAG_NORTH, and GRID_NORTH. If this parameter is not specified, the default is TRUE_NORTH.
  • DIST_BEARING_UNIT- specifies the linear unit for the distance values. Both the full name and abbreviation are valid. If this parameter is not specified, the default is meters.

Shared Import Parameters

These parameters are shared across import and layer options commands to set layer properties.

  • HIDDEN - set to YES to cause this overlay to be hidden from view after it is loaded. The default is to show the overlay.
  • LAYER_DESC - specifies a description to use for the layer when displaying it in the Overlay Control Center. This overrides the default description based on the filename or other information within the file.
  • LAYER_GROUP - specifies the name of the group for the layer in the Control Center. To include multiple layers of grouping put the string <sub> in between levels. For example to make a group with 2 levels of nesting, use LAYER_GROUP="Top Level<sub>Next Level".
  • ALLOW_SELECTION - set to NO to disable selection of features from this layer using either the Feature Info or Digitizer Tools.
  • ALLOW_EXPORT - set to NO to disable export from this layer.
  • LOAD_FLAGS - contains flags for any import options that you were prompted for when loading the file, such as if you have a .tif file that you were prompted to select as elevation or raster. Also things like the coverages and tile sets for VPF layers. To see how to set these if you are writing a script, load a file with the settings that you want in the main user interface and then save a workspace, then examine the IMPORT command in the .gmw file for that file and see how the LOAD_FLAGS were set.
  • METADATA_FILENAME - specifies full path and filename of a file to display the contents of on the Metadata dialog for a layer. The file can be any simple displayable text format, including text and XML.
  • METADATA_URL - specifies a URL to a displayable web file (including HTML web page or XML document) to show on the Metadata dialog for a layer.
  • CODE_PAGE- specifies the code page to use when interpreting text from this layer. By default if the file doesn't specify a code page the current system code page will be used. Use the code page number, or the text UTF-8 (number 65001).
  • ALT_MODE (vector only) - altitude mode specifies how the 3D viewer should interpret z-values in the vector features of an layer, relative to terrain. Altitude mode may also be set in an individual feature, in which case it overrides the layer setting. The following values are supported:
    • UNSPECIFIED - Altitude mode is determined by either the setting in the feature, or if unspecified, the setting in the 3D viewer
    • ABSOLUTE - treat z-values as absolute elevations, ignoring any terrain
    • RELATIVE_TO_GROUND - treat z-values as distances above the terrain
    • RELATIVE_TO_SEA_FLOOR - treat z-values as distances above the sea floor (currently implemented as RELATIVE_TO_GROUND)
    • CLAMP_TO_GROUND - ignore z-values, and clamp the feature to the terrain
    • CLAMP_TO_SEA_FLOOR - ignore z-values, and clamp the feature to the sea floor (currently implemented as CLAMP_TO_GROUND)
    • DEPTH - treat z-values as absolute depths, ignoring any terrain
  • ZOOM_DISPLAY - specifies when the map should be displayed and when it should be hidden based on the display zoom scale. This command will be formatted as a name from the list, below followed by 2 numeric paramters. For example, use ZOOM_DISPLAY="SCALE,25000,0" to have a map display only when zoomed in below 1:25000 scale.
    • ALWAYS - always display the map. The numeric parameters are ignored.
    • PERCENT - display the map when the map bounding box is a certain percentage of the screen size. For example, use ZOOM_DISPLAY="PERCENT,0.10,0" to display the map when its bounding box is at least 10% of the screen size.
    • PIXEL_SIZE - display the map when each display pixel is less than some number of meters in size. For example, use PIXEL_SIZE="SCALE,10,0" to display the map when the current display resolution is 10 meters per pixel (or less/higher resolution).
    • SCALE - display the map when the current display is at or below a certain scale. For example, use ZOOM_DISPLAY="SCALE,25000,0" to display the map when the current draw scale is at or below 1:25000.
    • SCALE_RANGE - display the map when the current display is below a range of scale value. For example, use ZOOM_DISPLAY="SCALE_RANGE,25000,100000" to display the map when the current draw scale is between 1:25000 and 1:100000.
  • PROJ - special Projection Specification type of parameter that specifies the projection to use for the file. This will override any projection information stored in the file.
  • PROJ_NAME (DEPRECATED use PROJ instead) - specifies the name of the projection to use for this file (this will override any projection information stored in the file). This name must have been defined with a prior DEFINE_PROJ command.
  • PROJ_FILENAME (DEPRECATED use PROJ instead)- specifies the name of the projection (.prj) file to use for this file (this will override any projection information stored in the file).
  • PROJ_EPSG_CODE (DEPRECATED use PROJ instead) - specifies the numeric EPSG projection code that defines the projection for this file (this will override any projection information stored in the file). For example, use PROJ_EPSG_CODE=26715 to define a UTM zone 15 projection with NAD27 as the datum and meters as the units.
  • PROMPT_IF_PROJ_UNKNOWN - set to NO if you don't want the user to be prompted to select a projection if the projection of the file cannot be automatically determined.
  • USE_DEFAULT_PROJ - specifies that if no projection can be automatically determined for a layer that the default projection selection should be used rather than prompting the user. Use USE_DEFAULT_PROJ=YES to enable. The default projection uses the first valid option from the following, including a check for linear versus angular numeric ranges:
    • Projection of any files loaded from the same folder
    • Last projection user selected on a projection dialog in this session
    • Current view projection
    • Projection from default.prj in global_mapper.exe path
    • Projection from default.prj in User Settings File path
    • Last projection user selected on a projection dialog in previous session of GM
    • Default UTM/15N/NAD83 projection
  • USE_DEFAULT_POS - specifies that if no position data for a raster layer can be automatically determined that a default position should be chosen so that it displays. Use USE_DEFAULT_POS=YES to enable.
  • PICTURE_POS - specifies that the image should be loaded as a 'picture point' that displays the image when you select the point with the Feature Info Tool. The value should contain the X and Y coordinates (in the projection specified for the layer). For example to place the value at 30N 95W with the projection set as PROJ_EPSG_CODE=4326 you can use PICTURE_POS="-95.0,30.0".
  • LOAD_HIDDEN_PDF_LAYERS - for PDF import, specifies that if no layer prompt is provided that hidden layers should be loaded automatically. Use LOAD_HIDDEN_PDF_LAYERS=YES to enable.

Vector Parameters

  • VIDEO_FILENAME - specifies the full path and filename or URL for a video file to associate with the layer. This video can then be displayed for selected point or line features with a video timestamp.
  • LAYER_FLAGS - specifies various options for the layer (like mesh/3D model display options). This is a bit-mask field that can be specified as an integer or hex number (i.e. 0x3). To build the value, simply add each of the numeric options for the flags you want and then store that number (or convert to hex notation - 0xXXX):
    • 1 - Mesh Display - Wireframe Only - If 1 is added to the value, display textured or colored mesh (3D model) features only using a wireframe (i.e. do not fill them).
    • 2 - Mesh Display - No Wireframe on Zoom - If 2 is added to the value, textured/filled mesh (3D model) features will NOT display a wireframe over the color display when zoomed in far enough that the triangles are large.
    • 4 - Mesh Display - Don't Interpolate Textures - If 4 is added to the value, nearest neighbor rather than bilinear interpolation will be used when sampling the texture for a mesh (3D model). This is slightly faster, but will result in pixelated display when zoomed in.

Vector Label Parameters

The parameters below allow specifying how to create display labels for vector layers.

  • LABEL_FIELD - specifies the name of the attribute field to use as the label attribute for the features in the file. By default the attribute-based labeling will only be applied to those features that don't already have a label, but if the LABEL_FIELD_FORCE_OVERWRITE attribute is set to YES then all features will have their labels replaced. If you want to build the label from multiple attributes, separate them with '>+<' in the file, like LABEL_FIELD='RD_PREFIX>+<RD_NAME>+<RD_SUFFIX'.
  • LABEL_FIELD_SEP - specifies the attribute separator to use when building a label from multiple attributes. This can be any character(s). For example LABEL_FIELD_SEP='-' will insert a dash between each attribute. Use hex codes to add any non-printable characters, such as LABEL_FIELD_SEP='0x20' to add a space.
  • LABEL_CUSTOM_DEF - specifies a custom free-form string describing how to form the display labels for this layer. This can include embedded attribute values as %ATTR_NAME%.
  • LABEL_FIELD_FORCE_OVERWRITE - specifies that the LABEL_FIELD or LABEL_CUSTOM_DEF attribute value should be applied to all feature labels, not just those that don't already have labels. Use LABEL_FIELD_FORCE_OVERWRITE=YES to enable.
  • SHOW_LABELS - specifies whether or not labels are shown for features in this layer, assuming they would be otherwise shown. The default is SHOW_LABELS=YES. Use SHOW_LABELS=NO to disable the display of labels for this layer regardless of other settings.
  • LABEL_PREFIX - specifies the prefix to prepend to attribute-based labels
  • LABEL_SUFFIX - specifies the suffix to append to attribute-based labels
  • LABEL_FORMAT_NUMBERS - specifies whether or not numeric attribute values should automatically have formatting applied to them. This is enabled by default. Use LABEL_FORMAT_NUMBERS=NO to disable numeric formatting and keep numeric values exactly as they are in the attribute list.
  • LABEL_PRECISION - value is an integer indicating the number of decimal digits to use. This applies to numeric labels.
  • LABEL_REMOVE_TRAILING_ZEROS - This removes the trailing zeros to the right of the decimal place in numeric labels. This can be specified by listing the parameter alone, or accepts boolean values.
  • LABEL_USE_SCIENTIFIC_NOTATION - Display the number in scientific notation. This accepts boolean values, or can be called by listing the parameter alone.

SAMPLE

IMPORT_ASCII FILENAME="C:\data\ASCII Files\usvi_landmark.asc" \
	TYPE=POINT_AND_LINE COORD_DELIM=AUTO COORD_ORDER=X_FIRST \	
	COORD_PREFIX="XY,"INC_COORD_LINE_ATTRS=NO PROJ=