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. This can also be the URL (http: or ftp for a file on a web site that you want Global Mapper to download and load). Wildcards ('*' or '?')can be included to load all files matching a particular mask.The name of a previously defined file from DEFINE_TEXT_FILE can also be used.
- SOURCE_URL - specifies the URL of the file on the server. If the file specified by FILENAME is not found and there is a SOURCE_URL, the file is downloaded from the URL and saved to the FILENAME location.
- 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 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
- FORCE_FULL_PROJ- specifies that reprojecting data should always do a full projection / datum shift rather than using a faster projection mesh for the conversion. This will improve precision (especially on data covering very large areas of the earth) at the expense of slower rendering times. Use FORCE_FULL_PROJ=YES to enable.
- 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.
Parameters for display and interpretation of elevation values in terrain layers. See also Raster Parameters below for additional shared parameters.
- ELEV_FIELD - specifies the name of the attribute field to use as the elevation value for the vector features in a file
- ELEV_UNITS - specify elevation units to use for this file if it contains gridded elevation data and also for vector feature elevations that don't have a unit embedded in the elevation value. Valid values are as follows:
- FEET - elevations in US feet
- DECIFEET - elevations in 10ths of US feet
- METERS - elevations in meters
- DECIMETERS - elevations in 10ths of meters
- CENTIMETERS - elevations in centimeters
- ELEV_OFFSET (elevation only) - specifies the offset in meters to apply to each elevation value in the layer. This allows you to vertically shift a layer to match other layers.
- ELEV_POWER (elevation only) - specifies the power value to apply to each elevation value in the layer. For example a value of 2.0 would square each elevation value before applying a scale and adding the offset. Default to 1.0 (no power).
- ELEV_SCALE (elevation only) - specifies the scale value to apply to each elevation value in the layer. This allows you to vertically scale a layer to match other layers. Default to 1.0 (no scaling).
- MIN_ELEV (elevation only) - specifies the minimum elevation (meters) to treat as valid when rendering this layer. Any elevations below this value will be treated as invalid and not be drawn or exported.
- MAX_ELEV (elevation only) - specifies the maximum elevation (meters) to treat as valid when rendering this layer. Any elevations above this value will be treated as invalid and not be drawn or exported.
- CLAMP_ELEVS (elevation only) - if a MIN_ELEV and /or MAX_ELEV value is specified, setting this to YES will make any valid elevation values outside of the specified range be clamped to the new range value rather than treated as invalid.
- VOID_ELEV (elevation only) - specifies the elevation (meters) to replace any void areas in the layer with. If not specified, the void areas will be transparent.
- SHADER_NAME (elevation only) - this sets the name of the shader to use when rendering the gridded elevation data for this layer. Use this to override use of the shared default shader just for this layer. This must be one of the names displayed in the shader drop down in Global Mapper, such as "Atlas Shader" or "Global Shader" or the name of a custom shader.
- BAND_RANGE - specifies the range of valid values found in a gridded layer. It can optionally also specify how and how to determine what values are no-data values. If not specified, these values will be automatically determined from the data. The format is a comma-delimited list of values like BAND_RANGE="min_valid,max_valid,band_validity_type,check_invalid_float,band_valid_val_1,band_valid_val_2". The _band_valid_val_1_ and _band_valid_val_2_ values are optional and depend on the _band_validity_type_ value. The individual values are:
- min_valid - minimum valid value for grid cell samples
- max_valid - maximum valid value for grid cell samples
- _band_validity_type -_ specifies how to determine if a cell value is valid. The following type names are recognized:
- ALL - all samples are valid
- NONE - no samples are valid
- GTE_MIN - values >= _band_valid_val_1_ are valid
- GT_MIN - value > _band_valid_val_1_ are valid
- NO_DATA - _band_valid_val_1_ is a specific no-data value
- LTE_MAX - values <= _band_valid_val_1_ are valid
- LT_MAX - values < _band_valid_val_1_ are valid
- RANGE_OPEN - values in open range (band_valid_val_1, band_valid_val_2) are valid
- RANGE_CLOSED - values in closed range [_band_valid_val_1, band_valid_val_2]_ are valid
- check_invalid_float - value is 1 if data should be checked for raw float samples for infinite values. 0 if is known no values like that exist.
- band_valid_val_1 - optional value based on _band_validity_type
- band_valid_val_2_ - optional value based on _band_validity_type
Parameters for display of imagery. Some of the below parameters are also supported for elevation layers.
- SAMPLING_METHOD (elevation and raster only) - specifies the sampling method to use when resampling this layer.
- NEAREST_NEIGHBOR - use the nearest neighbor sampling method
- BILINEAR - use bilinear interpolation
- BICUBIC - use bicubic interpolation
- BOX_2X2 - use a 2x2 box average
- BOX_3X3 - use a 3x3 box average
- BOX_4X4 - use a 4x4 box average
- BOX_5X5 - use a 5x5 box average
- BOX_6X6 - use a 6x6 box average
- BOX_7X7 - use a 7x7 box average
- BOX_8X8 - use a 8x8 box average
- BOX_9X9 - use a 9x9 box average
- MAX_2X2 - use maximum value found in 2x2 box (for image layers, use brightest color)
- MAX_3X3 - use maximum value found in 3x3 box (for image layers, use brightest color)
- MAX_4X4 - use maximum value found in 4x4 box (for image layers, use brightest color)
- MAX_5X5 - use maximum value found in 5x5 box (for image layers, use brightest color)
- MAX_6X6 - use maximum value found in 6x6 box (for image layers, use brightest color)
- MAX_7X7 - use maximum value found in 7x7 box (for image layers, use brightest color)
- MAX_8X8 - use maximum value found in 8x8 box (for image layers, use brightest color)
- MAX_9X9 - use maximum value found in 9x9 box(for image layers, use brightest color)
- MED_2X2 - use median value found in 2x2 box
- MED_3X3 - use median value found in 3x3 box
- MED_4X4 - use median value found in 4x4 box
- MED_5X5 - use median value found in 5x5 box
- MED_6X6 - use median value found in 6x6 box
- MED_7X7 - use median value found in 7x7 box
- MED_8X8 - use median value found in 8x8 box
- MED_9X9 - use median value found in 9x9 box
- MIN_2X2 - use minimum value found in 2x2 box (for image layers, use darkest color)
- MIN_3X3 - use minimum value found in 3x3 box (for image layers, use darkest color)
- MIN_4X4 - use minimum value found in 4x4 box (for image layers, use darkest color)
- MIN_5X5 - use minimum value found in 5x5 box (for image layers, use darkest color)
- MIN_6X6 - use minimum value found in 6x6 box (for image layers, use darkest color)
- MIN_7X7 - use minimum value found in 7x7 box (for image layers, use darkest color)
- MIN_8X8 - use minimum value found in 8x8 box (for image layers, use darkest color)
- MIN_9X9 - use minimum value found in 9x9 box (for image layers, use darkest color)
- BLUR_3X3 - perform a Gaussian Blur using 3x3 kernel
- BLUR_5X5 - perform a Gaussian Blur using 5x5 kernel
- BLUR_7X7 - perform a Gaussian Blur using 7x7 kernel
- ANTI_ALIAS [DEPRECATED - use SAMPLING_METHOD instead] (elevation and raster only) - specifies whether to remove jagged edges by making a subtle transition between pixels. Turning off this option helps maintain the hard edges of the pixels as they are rasterized. Use ANTI_ALIAS=YES to turn on. Anything else turns it off.
- TRANSLUCENCY (elevation and raster only) - specifies the level of translucency (i.e. how "see-through" the layer is). Value values range from 0 to 512, with 0 meaning the layer is completely transparent (i.e. invisible) and 512 meaning the layer is completely opaque (this is the default).
- IGNORE_ALPHA (raster only) - specifies that an embedded alpha channel in an image should be ignored. This is useful for images that have incorrect alpha channels. Use IGNORE_ALPHA=YES to enable.
- BLEND_MODE (elevation and raster only)- specify blend mode to use for combining this overlay and any previously loaded overlays
- NO_BLEND - no blending is done, this is the default
- MULTIPLY
- SCREEN
- OVERLAY
- HARD_LIGHT
- COLOR_BURN
- COLOR_DODGE
- DARKEN
- LIGHTEN
- DIFFERENCE
- EXCLUSION
- APPLY_COLOR
- APPLY_COLOR_REVERSE
- KEEP_RED
- KEEP_GREEN
- KEEP_BLUE
- SPOT_NATURAL_COLOR_SPOT_TO_NATURAL
- PSEUDO_NATURAL_COLOR_CIR_TO_NATURAL
- COLOR_TO_GRAYSCALE
- FEATHER_BLEND_EDGES (raster only) - specifies that the layer should be feature-blended around one or more ledges. This is a numeric bitfield value. Add (sum) the following values to enable blending on that edge:
- 1 - blend top edge
- 2 - blend bottom edge
- 4 - blend left edge
- 8 - blend right edge
- 32 - just crop to feather boundary rather than feathering
- 64 - feather outside polygon edge
For example, to blend all edges, use FEATHER_BLEND_EDGES=15. The FEATHER_BLEND_SIZE parameter is used to specify how many pixels to blend on each blended edge.
- FEATHER_BLEND_SIZE (raster only) - specifies the size in pixels to use for a blend boundary.
- FEATHER_BLEND_POLY (raster only) - specifies the name of a previously defined shape from The DEFINE_SHAPE command allows a multi-point shape (like a polygon) to be associated with a name. The shape name can then be used in later commands for things like cropping and feathering to polygonal boundaries. to feather too. You can also use FEATHER_BLEND_POLY=COVERAGE to calculate the polygonal coverage of the layer and feather blend to that automatically. To feather multiple shapes, also include the POLYGON_CROP_USE_EACH=YES parameter.
- FEATHER_BLEND_POLY_FILE (raster only) - specifies that the polygon boundary to feather blend this layer against should come from the specified file. To feather multiple shapes, also include the POLYGON_CROP_USE_EACH=YES parameter.
- BAND_SETUP (raster only) - specifies what bands of data from the raster file being loaded should be used to populate the red, green, and blue color channels when displaying the image. This is useful for multi-spectral imagery which may have more than 3 color bands. The default band setup will be to use the first three bands as follows: BAND_SETUP="0,1,2". Note that not all raster formats support specifying a non-default band setup.
- CONTRAST_MODE (raster only) - specifies the type of contrast adjustment to apply to the data.
- NONE - no contrast adjustment applied (this is the default)
- PERCENTAGE - apply a percentage contrast adjustment. The CONTRAST_STRETCH_SIZE parameter can be used to override the number of standard deviations from the mean to stretch to.
- MIN_MAX - apply a min/max contrast stretch, stretching the available range of values in each color band to the full range of 0-255. For imagery which contains both black and white, this will have no affect.
- CONTRAST_SHARED (raster only) - specifies whether or not the contrast adjustment for this layer will share the adjustment with other contrast-adjusted layers in order to ensure a consistent modification across layers. Use CONTRAST_SHARED=YES to enable contrast sharing.
- CONTRAST_STRETCH_SIZE (raster only) - specifies the number of standard deviations from the mean to use in a PERCENTAGE contrast adjustment. The default is 2.0.
- AUTO_CONTRAST (raster only) - DEPRECATED, use CONTRAST_MODE instead - specifies whether to automatically calculate and apply a 2 standard deviation contrast adjustment to the image. Use AUTO_CONTRAST=YES to turn on. Anything else turns it off.
- COLOR_INTENSITY(DEPRECATED use COLOR_INTENSITY_FULL parameter) (elevation and raster only). - specifies the color intensity to use when adjusting the brightness of pixels in the overlay. Valid values range from 0 to 20, with 0 being completely black, 10 being no alteration, and 20 being completely white. For example, to make an image slightly darker, you could use COLOR_INTENSITY=7.
- COLOR_INTENSITY_FULL (elevation and raster only) - specifies the color intensity to use when adjusting the brightness of pixels in the overlay. Valid values range from 0 to 512, with 0 being completely white, 256 being no alteration, and 512 being completely black. For example, to make an image slightly darker, you could use COLOR_INTENSITY=300. (NOTE: This parameter replaces the COLOR_INTENSITY parameter).
- TEXTURE_MAP (raster only) - specifies that this image should be draped over any elevation data loaded before it. Use TEXTURE_MAP=YES to turn on. Anything else turns it off.
- PALETTE_NAME (palette-based raster only) - specifies the filename of a recognized palette file to override the default colors in this layers palette or a palette previously defined with the DEFINE_PALETTE command. Use this to change the color interpretation of palette indices.
- TRANSPARENT_COLOR (elevation and raster only) - specifies the color to make transparent when rendering this overlay. The color should be specified as RGB(<red>,<green>,<blue>). For example, to make white the transparent color, use TRANSPARENT_COLOR=RGB(255,255,255). If you do not wish any color to be transparent, do not use this parameter. Optionally, if the image that you are making transparent uses a palette for the colors, you can specify a palette index in the following format: INDEX(<0-based palette index>). For example, to make the second color in the palette transparent, use TRANSPARENT_COLOR=INDEX(1).
- TRANSPARENT_COLOR_DIST - for layers that have specified a color to make transparent, this parameter allows you to specify how far a color in the layer has to be from the specified TRANSPARENT_COLOR value to be treated as transparent as well. The default value of 0 means that the colors have to exactly match for the pixel to be treated as transparent. Larger values (up to 256) allow larger distances between the layer color and the transparent color. This is useful for lossy formats, like JPEG.
- COLOR_GRADE (raster only) - specifies the color grading values to use for this layer (as configured on the Color Grade options dialog tab). This should be a comma-delimited list with the saturation value (from 0-1) first, then the input and output range for the red, green, and blue color channels, as follows: COLOR_GRADE=saturation,red_in_start,red_in_end,red_out_start,red_out_end,...,blue_out_end
- CLIP_COLLAR (raster only) - specifies whether to clip the collar off of the image. The following values are supported for cropping:
- NONE - no collar cropping is performed.
- AUTO - automatically remove a USGS DRG-style collar or a 3.75 DOQQ collar
- LAT_LON - crop the collar to a a specified set of bounds specified in arc degrees in the native datum of the layer. The bounds should be specified using the CLIP_COLLAR_BOUNDS parameter.
- NATIVE - crop the collar to a specified set of bounds specified in the native projection system and datum of the layer. The bounds should be specified using the CLIP_COLLAR_BOUNDS parameter.
- PIXELS - crop a given number of pixels off of each side of the layer. The number of pixels to remove from each side should be specified using the CLIP_COLLAR_BOUNDS parameter.
- SNAP_DEGREES - crop the collar by snapping each edge to a specified degree boundary specified in arc degrees in the native datum of the layer. The bounds should be specified using the CLIP_COLLAR_BOUNDS parameter. For example to crop the west and east edges to a half degree boundary and the north and south edges to a one degree boundary, use the following: CLIP_COLLAR_BOUNDS=0.5,1.0,0.5,1.0.
- POLY - crop to a polygon provided with the CLIP_COLLAR_POLY parameter.
- CLIP_COLLAR_BOUNDS (raster only) - specifies the bounds of the collar to be clipped off when the CLIP_COLLAR parameter is enabled. The coordinates should be specified in arc degrees, native layer coordinates, or pixel counts as a comma-delimited list going west,south,east,north. For example, CLIP_COLLAR_BOUNDS=34.25,-109.0,34.375,-108.875.
- CLIP_COLLAR_POLY (raster only) - specifies the name of the previously defined shape (with the DEFINE_SHAPE command) to crop the layer to when the CLIP_COLLAR=POLY parameter is used. The coordinates in the shape must have been defined in the native projection system of the layer being loaded. Unless you provide CLIP_COLLAR_POLY_SIMPLIFY=NO, the clip polygon will be simplified to 1/10th of a pixel resolution to reduce the size of the crop polygon for faster cropping without noticeably changing the shape.
- CLIP_COLLAR_POLY_EXCLUDE (raster only) - specifies that the crop to the polygon specified with CLIP_COLLAR_POLY should keep all parts of the layer outside the crop polygon(s) rather than what is inside the polygon(s). Add CLIP_COLLAR_POLY_EXCLUDE=YES to enable this behavior.
- CLIP_COLLAR_POLY_SIMPLIFY - specifies that the clip polygon will be simplified to 1/10th of a pixel resolution to reduce the size of the crop polygon for faster cropping without noticeably changing the shape. Enabled by default, use CLIP_COLLAR_POLY_SIMPLIFY=NO to disable.
- CLIP_COLLAR_POLY_PIXEL (raster only) - specifies that the coordinates in the crop polygon from the CLIP_COLLAR_POLY parameter are in pixel relative coordinates for the layer rather than in the native system of the layer. Use this if you need to crop a layer to a particular boundary in known pixel coordinates. The coordinates will convert to native layer coordinates on load.
- 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.
- USE_LEGACY_IMPORTER - For TYPE=DXF files only. If USE_LEGACY_IMPORTER=YES is specified the DXF file will be loaded using the legacy import method.
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.
The parameters below allow specifying options for working with Lidar data.
- LIDAR_DRAW_MODE - specifies how points in a Lidar point cloud layer should be drawn. The following values are supported:
- COLOR - if the points have an associated RGB color, use that. Otherwise color by elevation.
- ELEV - color by elevation of the point using the current elevation shader.
- INTENSITY - color as a grayscale image by the intensity
- LIDAR_INTEN_SHADER - Specify the terrain shader to be used to color intensity value when using the INTENSITY draw mode option. If this parameter is provided with an empty value the terrain shader selected on the main toolbar will be used.
- CLASS - color by the point classification
- RETURN - color by the return number
- HEIGHT_ABOVE_GROUND - color by the height above ground
- POINT_SOURCE_ID - color by the point source ID
- BY_LAYER - color the point cloud based on the source layer
- COLOR - Use this parameter to specify a custom color, format RGB(R,G,B), to use when using the BY_LAYER draw mode option. If not specified, automatic color assignment will be used when coloring by source layer.
- POINT_INDEX - color by the index of the point in the cloud
- RETURN_HEIGHT_DELTA - color by the difference in height between first and last return
- CIR - color as color infrared if NIR band present
- NDVI - color by calculated NDVI value if NIR band present
- NDWI - color by calculated NDWI value if NIR band present
- DENSITY - color by point density
- WITHHELD - color by withheld flag
- OVERLAP - color by overlap flag
- KEY_POINT - color by key point flag
- SORT_LIDAR - specifies if a Lidar point cloud format should spatially sort the data on load for better performance. This will override any sort settings from the LOAD_FLAGS parameter. The following values are supported
- AUTO - spatially sorts the point cloud data only if it is determined to be poorly sorted
- YES - always spatially sort the point cloud data.
- COLOR - do not spatially sort the point cloud data
- LIDAR_POINT_SIZE - specifies how large the points in a Lidar point cloud are drawn. The default value of 0 will automatically scale the points to be larger as you zoom in on them. Specify a fixed number to always draw them at a particular size in pixels.
- LIDAR_DRAW_QUALITY - specifies the quality setting (0-100) for drawing the Lidar point cloud. Larger values draw a larger fraction of the points when zoomed out, but the draw will take longer to complete.
- LIDAR_FILTER - specifies a comma-separated list of Lidar class numbers to enable or disable for load. Provide a minus sign (-) to remove the type from the filter rather than add it. The filter starts off with nothing in it if you provide a LIDAR_FILTER string, but you can add ALL to enable everything or NONE to clear the filter, then add or remove stuff after that. For example, to specify a class filter with only types 2 and 3 enabled, use LIDAR_FILTER="NONE,2,3". To get one with everything but classes 2 and 3, use LIDAR_FILTER="ALL,-2,-3".
- LIDAR_RETURN_FILTER - specifies a comma-separated list of Lidar return types to enable or disable for load. Provide a minus sign (-) to remove the type from the filter rather than add it. The filter starts off with loading everything, but you can add ALL to enable everything or NONE to clear the filter, then add or remove stuff after that. For example, to specify a return filter with only unknown and first returns, use LIDAR_RETURN_FILTER="NONE,0,1". To get one with everything but the first return, use LIDAR_RETURN_FILTER="ALL,-1". The numeric values have the following meanings:
- 0 - Unknown Returns
- 1 - First Return
- 2 - Second Return
- 3 - Last Return
- 4 - Single Return
- 5 - First of Many Returns
- 6 - Second of Many Returns
- 7 - Third of Many Returns
- 8 - Last of Many Returns
- LIDAR_USE_INTEN_FOR_NIR - specifies that we should treat the intensity value Lidar points as the NIR (near infrared) value if the point cloud has RGB colors but no NIR values of its own. Use LIDAR_USE_INTEN_FOR_NIR=YES to enable.
- LIDAR_INTEN_DRAW_MODE - specifies how intensity values will be colored when using the ‘Color Lidar by Intensity' draw mode for a point cloud layer. Supported values are:
- GRAY_W_BRIGHTNESS -(default value) the intensity values will be rendered as grayscale scaled to +/-2 standard deviations from the mean intensity value, with the minimum coloring as black and the maximum coloring as white. A brightness offset can be specified with LIDAR_BRIGHTNESS to skew values brighter or darker
- GRAY_MIN_MAX_STRETCH - the intensity values will be rendered as grayscale and scaled from black at the minimum intensity value to white at the maximum. The default min/max represent the full range of intensity value for the image, but typically you would use the LIDAR_INTEN_MIN_DRAW and LIDAR_INTEN_MAX_DRAW parameters to customize the range.
- SHADER - the intensity values will be rendered with a named shader provided with the LIDAR_INTEN_SHADER parameter. A blank value for that parameter means to use whatever the shared shader for all ‘terrain’ layers is
- LIDAR_INTEN_MIN_DRAW and LIDAR_INTEN_MAX_DRAW - specify the minimum and maximum intensity values to define a range to use when rendering intensity with the LIDAR_INTEN_DRAW_MODE=”GRAY_MIN_MAX_STRETCH” option.
-
LIDAR_INTEN_RANGE - specifies the valid range of intensity values to expect when loading a Lidar point cloud. Provided as LIDAR_INTEN_RANGE="min,max", like LIDAR_INTEN_RANGE="0.0,1.0" if intensities are in range 0-1. If provided, the raw intensity value from the file will be scaled from the specified range to the standard Lidar intensity range of [0,65535].
The parameters below allow defining a series of control points and rectification parameters for setting up a coordinate mapping from pixel space to real-world projection coordinates for the layer.
- HAS_3D_POINTS - If HAS_3D_POINTS=YES is used, then the control points will have a Z component after each XY value. If 3D control points are provided, they will shift Lidar, 3D vectors or 3D model layers using the best-fit 3D transform.
- GCP - specifies a single ground control point for use in rectifying a file. The GCP record consists of 5 comma-delimited fields, the control point name, the pixel X and Y coordinates, and the corresponding ground X and Y coordinates. A separate GCP parameter and value should be used for each control point used in the rectification. As an alternative, the GCP_FILENAME parameter (see below) can be used instead.
When HAS_3D_POINTS is used the expected values are like GCP="name,x_from,y_from,z_from,x_to,y_to,z_to" - GCP_FILENAME - specifies the name of a control point file used to rectify the file being imported. the expected format in the file when HAS_3D_POINTS is provided is: x_from,y_from,z_from,x_to,y_to,z_to,name. Note the name is optional.
- GCP_PROJ_NAME - specifies the name of the projection that the ground control points are provided in. This name must have been defined with a prior DEFINE_PROJ command. Use this if you want to specify control points in a projection other than what you want to define as the native projection for the file. Note that you must also explicitly specify the name projection of the file using either the PROJ, PROJ_NAME, PROJ_EPSG_CODE or PROJ_FILENAME parameters.
- TRANSFORM_FILENAME - specifies the name of a control point file used to transform the coordinates of the imported file. This is different than the GCP_FILENAME in that the file defines a mapping of world coordinates to a new set of world coordinates rather than pixel coordinates to world coordinates. Each line should be of the format: x_orig,y_orig,x_new_y_new
- GCP_PROJ_FILENAME - specifies the name of the projection (.prj) file that contains the projection definition for the projection that the ground control points are provided in. Use this if you want to specify control points in a projection other than what you want to define as the native projection for the file. Note that you must also explicitly specify the name projection of the file using either the PROJ, PROJ_NAME, PROJ_EPSG_CODE or PROJ_FILENAME parameters.
- GCP_PROJ_EPSG_CODE - specifies the EPSG code of the projection that the ground control points are provided in. Use this if you want to specify control points in a projection other than what you want to define as the native projection for the file. Note that you must also explicitly specify the name projection of the file using either the PROJ, PROJ_NAME, PROJ_EPSG_CODE or PROJ_FILENAME parameters.
- RECTIFY - specifies the rectification method to use for rectifying this file. Valid value are LINEAR, HELMERT, AFFINE, POLYNOMIAL, and TRIANGULATION. If you do not specify a rectification type but do provide at least two ground control points, the best rectification method will automatically be chosen based on the number of control points specified.
- RECTIFY_4_POINT_POLY_ONLY - specifies that if RECTIFY=POLYNOMIAL is used to specify the rectification method, the polynomial will always be a 1st degree polynomial and won't switch automatically to a 2nd degree polynomial at 6 or more points. By default, the 2nd degree polynomial will automatically be used
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=