Provided by: grass-doc_6.4.3-3_all bug

NAME  - Creates a vector map from ASCII points file or ASCII vector file.


       vector, import

SYNOPSIS help   [-zentbr]    [input=name]    output=name    [format=string]    [fs=character]
       [skip=integer]      [columns=string]       [x=integer]       [y=integer]       [z=integer]
       [cat=integer]   [--overwrite]  [--verbose]  [--quiet]

           Create 3D vector map

           Create a new empty vector map and exit. Nothing is read from input.

           Don't expect a header when reading in standard format

           Do not create table in points mode

           Do not build topology in points mode

           Only import points falling within current region (points mode)

           Allow output files to overwrite existing files

           Verbose module output

           Quiet module output

           ASCII file to be imported, if not given reads from standard input

           Name for output vector map

           Input file format
           Options: point,standard
           Default: point
           point: simple x,y[,z] list
           standard: GRASS vector ASCII format

           Field separator
           Special characters: newline, space, comma, tab
           Default: |

           Number of header lines to skip at top of input file (points mode)
           Default: 0

           Column definition in SQL style (points mode)
           For example: 'x double precision, y double precision, cat int, name varchar(10)'

           Number of column used as x coordinate (points mode)
           First column is 1
           Default: 1

           Number of column used as y coordinate (points mode)
           First column is 1
           Default: 2

           Number of column used as z coordinate (points mode)
           First column is 1. If 0, z coordinate is not used
           Default: 0

           Number of column used as category (points mode)
           First  column  is  1. If 0, unique category is assigned to each row and written to new
           column 'cat'
           Default: 0

DESCRIPTION converts a vector map in ASCII format to a vector map  in  binary  format.  The
       module may import two formats:

                     standard contains all data types, each coordinate on one row

                     point (default) reads only points, each point defined on one row. Values are
                     separated by a user-definable  delimiter.  If  the  columns  option  is  not
                     defined,  default names are used. It is possible to specify the column order
                     for the x,y,z coordinates and category values.

       The v.out.ascii GRASS module performs the function of  in  reverse;  i.e.,  it
       converts  vector  maps  in binary format to ASCII format. These two companion programs are
       useful both for importing and exporting vector maps between GRASS and other software,  and
       for transferring data between machines.


       The input is read from the file specified by the input option or from standard input.

       The field separator may be a character, the word 'tab' (or '\t') for tab, 'space' (or ' ')
       for a blank, or 'comma' (or ',') for a comma.

       An attribute table is only created if it is needed,  i.e.  when  at  least  one  attribute
       column is present in the input file besides geometry columns. The attribute column will be
       auto-scanned for type, but may be explicitly declared  along  with  the  geometry  columns
       using the columns parameter.

       Latitude/Longitude  data  may  be  given  in  a  number  of ways.  Decimal degrees must be
       positive or negative instead of using a hemisphere letter. Mixed coordinates  must  use  a
       hemisphere  letter. Whole minutes and seconds must always contain two digits (example: use
       167:03:04.567; and not 167:3:4.567).
       Acceptable formats:
       key: D=Degrees; M=Minutes; S=Seconds; h=Hemisphere (N,S,E,W)

       Use the -z flag to convert ASCII data into a 3D vector map.

       In special cases of data import, such as the import of large LIDAR datasets  (millions  of
       data  points),  it  may  be necessary to disable topology support (creating a GRASS vector
       level 1 vector map) due to memory constraints.  This is done with the  -b  flag.  As  only
       very few vector modules support points data processing at vector level 1, usually topology
       is required (vector level 2). Therefore it is recommended  that  the  user  first  try  to
       import  the  data  without creating a database (the -t flag) or within a subregion (the -r
       flag) before resorting to the disabling of topology.

       A GRASS ASCII vector map (in standard  format  mode)  may  contain  a  mix  of  primitives
       including points, lines, boundaries, centroids, areas, faces, and kernels. The GRASS ASCII
       vector format may contain a header with various metadata (see example below).  The  header
       is not required if the -n flag is used.

       The  header  is similar as the head file of vector binary format but contains bounding box
       also. Key words are:
       MAP NAME
       MAP DATE
       MAP SCALE
       WEST EDGE
       EAST EDGE

       The body begins with the row:
        followed by records of primitives:
        X Y [Z]
        X Y [Z]
        Everything above in [ ] is optional.

       The primitive codes are as follows:

                     ’P': point

                     ’L': line

                     ’B': boundary

                     ’C': centroid

                     ’F': face (3D boundary)

                     ’K': kernel (3D centroid)

                     ’A': area (boundary) - better use 'B'; kept only for backward compatibility
       The coordinates are listed following the initial line containing the primitive  code,  the
       total  number of vectors in the series, and (optionally) the number of categories (1 for a
       single layer, higher for multiple layers).  Below  that  1  or  several  lines  follow  to
       indicate the layer number and the category number (ID).
       The order of coordinates is
         X Y [Z]
        In pre-GRASS 6 versions of the ASCII file, the order of coordinates is:
       Y X
         If  old  version  is  requested,  the  output  files  from  v.out.ascii is placed in the
       $LOCATION/$MAPSET/dig_ascii/ and $LOCATION/$MAPSET/dig_att directory.

   Import of files without category ID column
       If the input file does not contain a vector ID column, there is the possibility  to  auto-
       generate  these  IDs (categories).  To automatically add an additional column named 'cat',
       the cat parameter must be set to the virtual column number 0 (cat=0). This is the  default
       action if the cat parameter is not set.

   Importing from a spreadsheet
       Data  may  be imported from many spreadsheet programs by saving the spreadsheet as a comma
       separated variable (.csv) text file, and then using the fs=',' option with  in
       points  mode.   If  the input file contains any header lines, such as column headings, the
       skip parameter should be used. These skipped header lines will be  written  to  the  map's
       history  file  for  later  reference  (read with -h). The skip option only works in
       points mode.

       Any line starting with the hash character ('#') will be treated as a comment  and  skipped
       completely  if  located in the main data file. If located in the header, as defined by the
       skip parameter, it will be treated as a header line and written to the history file.

   Import of sexagesimal degree (degree, minutes, seconds, DMS)
       The import of DMS formatted degrees is supported (in  this  case  no  sign  but  N/S,  E/W
       characters  are  used  to  indicate  the hemispheres).  While the positions are internally
       translated into decimal degrees during the import, the original DMS values are  maintained
       in  the  attribute  table. This requires both the latitude and the longitude columns to be
       defined as varchars(), not as numbers.  A warning will be issued which can be ignored.

   Importing only selected columns
       Although doesn't have an option to specify which columns  should  be  imported,
       you can use a shell filter to achieve the same effect, e.g.:
       # Print out the column number for each field, supposing the file has a header
       head -1 input_file | tr '<the_field_separator_character>' '\n' | cat -n
       # From the listing, select the columns you want and feed them to
       # do not use the input= option
       cut  -d<the_field_separator_character>  -f<comma-separated_list_of_columns>  input_file  | <your_options>


   Example 1a) - standard format mode
       Sample ASCII polygon vector map for  'standard'  format  mode.   The  two  areas  will  be
       assigned categories 20 and 21.  The example can be tested in the Spearfish sample dataset:

       echo "ORGANIZATION: GRASS Development Team
       DIGIT DATE:   1/9/2005
       DIGIT NAME:   -
       MAP NAME:     test
       MAP DATE:     2005
       MAP SCALE:    10000
       OTHER INFO:   Test polygons
       ZONE:  0
       MAP THRESH:   0.500000
       B  6
        5958812.48844435 3400828.84221011
        5958957.29887089 3400877.11235229
        5959021.65906046 3400930.7458436
        5959048.47580612 3400973.65263665
        5959069.92920264 3401032.64947709
        5958812.48844435 3400828.84221011
       C  1 1
        5958952.42189184 3400918.23126419
        1 20
       B  4
        5959010.9323622 3401338.36037757
        5959096.7459483 3401370.54047235
        5959091.38259917 3401450.99070932
        5959010.9323622 3401338.36037757
       C  1 1
        5959063.08352122 3401386.98533277
        1 21" | format=standard output=test_polygons

   Example 1b) - standard format mode
       Sample ASCII 3D line vector map for 'standard' format mode with simplified input (note the
       space field separator).  Note the -z flag indicating 3D vector  input,  and  the  -n  flag
       indicating  no  vector  header should be expected from the input file.  The example can be
       tested in the Spearfish sample dataset:
       echo "L 5 1
       591336 4927369 1224
       594317 4925341 1292
       599356 4925162 1469
       602396 4926653 1235
       607524 4925431 1216
       1 321 " | -zn out=line3d format=standard
        This can be used to create a vector line of a GPS track: the GPS points have to be stored
       into a file with a preceding 'L' and the number of points (per line).

   Example 2 - point format mode
       Generate a 2D points vector map 'coords.txt' as ASCII file:

       Import into GRASS: input=coords.txt output=mymap
         As  the cat option is set to 0 by default, an extra column 'cat' containing the IDs will
       be auto-generated.

   Example 3 - point format mode
       Generate a 2D points vector map 'points.dat' as ASCII file:
       4|1663427|5105234|mysi dira
       5|1663709|5102614|mineralni pramen

       Import into GRASS:
       cat points.dat | out=mypoints x=2 y=3 cat=1 \
           columns='cat int, x double precision, y double precision, label varchar(20)'

       The module is reading from standard input, using the default '|' (pipe) delimiter.

   Example 4 - point format mode
       Generating a 3D points vector map from DBMS (idcol must be an integer column):

       echo "select east,north,elev,idcol from mytable" | -c | -z out=mymap
        The module is reading from standard input, using the default '|' (pipe) delimiter.
       The import works for 2D maps as well (no elev column and no '-z' flag).

   Example 5 - point format mode
       Generate a 3D points vector map 'points3d.dat' with attributes as ASCII file:
       590400.5|4922820.8|143.2|mysi dira|mouse hole
       593549.3|4925500.7|442.6|mineralni pramen|mineral spring
       600375.7|4925235.6|342.2|kozi stezka|goat path

       Import into GRASS:
       #As the 'cat' option is set to 0 by default, an extra column 'cat'
       #containing the IDs will be auto-generated (no need to define that):
       cat points3d.dat | -z z=3 cat=0 out=mypoints3D \
           columns='x double precision, y double precision, z double precision, \
           label_cz varchar(20), label_en varchar(20)' -c mypoints3D mypoints3D

   Example 6 - point format mode
       Generate points file by clicking onto the map:
       #For LatLong locations:
       d.where -d -l | awk '{printf "%f|%f|point\n", $1, $2}' | out=points \
           columns='x double precision, y double precision, label varchar(20)'
       #For other projections:
       d.where | awk '{printf "%f|%f|point\n", $1, $2}' | out=points \
           columns='x double precision, y double precision, label varchar(20)'
        The 'point' string (or some similar entry) is required  to  generate  a  database  table.
       When  simply  piping  the coordinates (and optionally height) without additional column(s)
       into, only the vector map geometry will be generated.

   Example 7 - point format mode
       Convert ground control points from i.points into vector points:
       cat $MAPSET/group/$GROUP/POINTS | out=$GROUP_gcp fs=space skip=3 \
           col='x double precision, y double precision, x_target double precision, \
           y_target double precision, ok int'


       SQL command notes for creating databases


        db.execute,,,,,  v.centroids,  v.clean,
       v.db.connect,, v.out.ascii,


       Michael Higgins, U.S.Army Construction Engineering Research Laboratory
       James Westervelt, U.S.Army Construction Engineering Research Laboratory
       Radim Blazek, ITC-Irst, Trento, Italy

       Last changed: $Date: 2013-05-03 12:47:09 -0700 (Fri, 03 May 2013) $

       Full index

       © 2003-2013 GRASS Development Team