Page may be moving soon

DBFAWK Tutorial

What's a dbfawk file for?

What's in a dbfawk file?

How are dbfawk files located and used?

What display functions can I tweak with dbfawk?

I have a new shapefile. How do I get it to display nicely in Xastir with DBFAWK enabled?

Given a shapefile and associated DBF file with attributes:

1. Use "dbfinfo" (it's part of the shapelib "contrib" directory, you need to build it separately from shapelib) to reveal the list of attributes in the DBF file. For example, I have a set of shapefiles converted from US Forest Service trails

       > dbfinfo /usr/local/share/xastir/maps/misc_vector/USFS_SandiaRD
   67 Columns,  544 Records in file
            FNODE_         integer  (11,0)
            TNODE_         integer  (11,0)
            LPOLY_         integer  (11,0)
            RPOLY_         integer  (11,0)
            LENGTH           float  (31,15)
            TRAIL_         integer  (11,0)
          TRAIL_ID         integer  (11,0)
              TYPE          string  (1,0)
              CODE          string  (2,0)
         CODE_MEMO          string  (80,0)
            METHOD          string  (2,0)
              MISC          string  (1,0)
           TE_UNIT          string  (1,0)
          EXISTVEG          string  (1,0)
            FS_OWN          string  (1,0)
             TRAIL          string  (1,0)
              ROAD          string  (1,0)
             WATER          string  (1,0)
            STREAM          string  (1,0)
              PLSS          string  (1,0)
          ADM_DIST          string  (1,0)
          ADM_UNIT          string  (1,0)
           PASTURE          string  (1,0)
          SPEC_MGT          string  (1,0)
          HRTGSRVY          string  (1,0)
         RD_RTE_NO          string  (35,0)
         TR_RTE_NO          string  (35,0)
         STRM_NAME          string  (80,0)
        SURVEY_NUM          string  (13,0)
              CFF1          string  (3,0)
              CFF2          string  (3,0)
              CFF3          string  (3,0)
              CFF4          string  (3,0)
              CFF5          string  (3,0)
              CFF6          string  (3,0)
              CFF7          string  (3,0)
              CFF8          string  (3,0)
              CFF9          string  (3,0)
             CFF10          string  (3,0)
            NUMBER          string  (35,0)
           NUMBER0          string  (35,0)
              LEVE          string  (20,0)
             TYPE0          string  (20,0)
         ROAD_TYPE          string  (20,0)
             LANES          string  (20,0)
           SURFACE          string  (20,0)
           PROBLEM          string  (20,0)
           CLOSURE          string  (20,0)
              DATE         integer  (8,0)
              TIME          string  (20,0)
          OPERATOR          string  (20,0)
          COMMENTS          string  (50,0)
          MAX_PDOP           float  (31,15)
          GPS_DATE         integer  (8,0)
          GPS_TIME          string  (20,0)
        GPS_LENGTH           float  (31,15)
         HORZ_PREC           float  (31,15)
         VERT_PREC           float  (31,15)
         HORZ_PRE0           float  (31,15)
         VERT_PRE0           float  (31,15)
          TRAIL_NO          string  (10,0)
            SOURCE          string  (10,0)
            MAPUSE          string  (25,0)
              NAME          string  (30,0)
            MILES2           float  (23,16)
             COOID          string  (10,0)
            STATUS         integer  (11,0)
   

   This list of attributes will be used in the DBFAWK file to recognize files to which the dbfawk file applies.

   It is also possible to use "testdbfawk" that is built in the xastir source tree when you compile xastir with DBFAWK enabled.

   Prior to CVS versions of 24 September 2008, "testdbfawk" was called "testawk" and the Xastir install process didn't install the program, leaving it built but uninstalled in the "src" directory. Users of these older versions of Xastir will have to build the code and execute testawk from its non-system location in the build directory.

     > testdbfawk -D /usr/local/share/xastir/config -d /usr/local/share/xastir/maps/misc_vector/USFS_SandiaRD
     67 Columns,  544 Records in file
   sig: FNODE_:TNODE_:LPOLY_:RPOLY_:LENGTH:TRAIL_:TRAIL_ID:TYPE:CODE:CODE_MEMO:METHOD:MISC:TE_UNIT:EXISTVEG:FS_OWN:TRAIL:ROAD:WATER:STREAM:PLSS:ADM_DIST:ADM_UNIT:PASTURE:SPEC_MGT:HRTGSRVY:RD_RTE_NO:TR_RTE_NO:STRM_NAME:SURVEY_NUM:CFF1:CFF2:CFF3:CFF4:CFF5:CFF6:CFF7:CFF8:CFF9:CFF10:NUMBER:NUMBER0:LEVE:TYPE0:ROAD_TYPE:LANES:SURFACE:PROBLEM:CLOSURE:DATE:TIME:OPERATOR:COMMENTS:MAX_PDOP:GPS_DATE:GPS_TIME:GPS_LENGTH:HORZ_PREC:VERT_PREC:HORZ_PRE0:VERT_PRE0:TRAIL_NO:SOURCE:MAPUSE:NAME:MILES2:COOID:STATUS
     [etc.]
   

2. Copy a dbfawk file for a type of map that is close (e.g. tgrlk.dbfawk is a reasonable starting point for line type shapefiles, but it is fairly complex and handles a lot of feature types).
3. Replace the contents of the "dbfinfo" variable with the fields you found in step 0. e.g., for my USFS shapefiles above, the dbfinfo variable is:

   dbfinfo="FNODE_:TNODE_:LPOLY_:RPOLY_:LENGTH:TRAIL_:TRAIL_ID:TYPE:CODE:CODE_MEMO:METHOD:MISC:TE_UNIT:EXISTVEG:FS_OWN:TRAIL:ROAD:WATER:STREAM:PLSS:ADM_DIST:ADM_UNIT:PASTURE:SPEC_MGT:HRTGSRVY:RD_RTE_NO:TR_RTE_NO:STRM_NAME:SURVEY_NUM:CFF1:CFF2:CFF3:CFF4:CFF5:CFF6:CFF7:CFF8:CFF9:CFF10:NUMBER:NUMBER0:LEVE:TYPE0:ROAD_TYPE:LANES:SURFACE:PROBLEM:CLOSURE:DATE:TIME:OPERATOR:COMMENTS:MAX_PDOP:GPS_DATE:GPS_TIME:GPS_LENGTH:HORZ_PREC:VERT_PREC:HORZ_PRE0:VERT_PRE0:TRAIL_NO:SOURCE:MAPUSE:NAME:MILES2:COOID:STATUS";
   

4. Figure out which of the godzillion attributes corresponds to the line names you want displayed. In my case it was a concatenation of the "NAME" and "TRAIL_NO" fields. You then make sure the "dbffields" variable has those fields in it (and few others, coz this is the variable that directs xastir to read the attributes from the file). In my case:

          dbffields="CFF1:NAME:TRAIL_NO";
   

   This selects the feature code (CFF), name and trail number.

   NOTE: THE SEMICOLON AT THE END OF DBFFIELDS IS REQUIRED due to a bug in the dbfawk parser. Leaving it off will cause dbfawk to mis-parse the dbffields variable to include all characters up to the closing brace in the BEGIN block. This bug is hidden if there *are* no characters between the closing quote and brace, but mysteriously shows up if there is a newline. So just put a semicolon at the end for correctness.

5. Create rules in your dbfawk file that match various patterns that can show up in the attributes. Here's where you set the "name" variable to the appropriate thing you want xastir to display as well as things like line type, color, label color, and how far out you can be zoomed and still see the labels. In my case, sometimes trails are listed in the dbf file as "UNK" and I don't want that name displayed, other times they're listed with a trail number only and I want it to show up as "Tr. #". So I do:

     # Use this rule to re-initialize variables between records.
     # These will be your defaults
     # My defaults are "1 lane, color brown, pattern "LineDoubleDash" (see the 
     #  XSetLineAttributes man page), always display the line, display labels if
     #  zoomed in to level 32 or smaller, black labels, large font) 
     # The defaults are overridden by specific rules below
     BEGIN_RECORD {key=""; lanes=1; color=4; name=""; filled=0; pattern=2; display_level=1; label_level=32; label_color=8; symbol=""; font_size=3}
   
   
     # hiking trails and unimproved roads
     # This sets the color of the line and pattern based on the feature type
     # We don't bother showing hiking trails if zoomed out farther than 128
     # brown for hiking trails
     /^CFF1=107$/ {lanes=2; color=69; pattern=1;display_level=128;}
     # dashed steel blue lines for class 4 unimproved roads.
     /^CFF1=106*$/ {lanes=2; color=26; pattern=1;display_level=128;}
     # Now look for a name number and/or trail number
     # Never display "UNK" as a trail name
     /^NAME=[uU][nN][kK]$/ {skip;}
     /^TRAIL_NO=[uU][nN][kK]$/ {skip;}
     # select the name given in the record
     /^NAME=(.+)$/ {name="$1";}
     # and append the trail number to the name
     /^TRAIL_NO=(.+)$/ {name="$name (Tr. $1)";}
   

   In this example I set most variables to some default at the beginning of each DBF record, and then look for particular patterns. The USFS maps have an attribute called "CFF1" (CFF stands for Cartographic Feature File) that contains an ID code for the feature type of the corresponding shape. CFF=107 means it's a hiking trail, so I set the zoom level at which the trail will show up to 128, the color to 69 (which is mapped to "brown1" in main.c), and 2 "lanes" that last seems odd, but I found that at zoom level 128 my background rasters always seemed to make "one lane" trails invisible.

6. Place your DBFAWK file somewhere where it'll be found. If you have a dbfawk file that applies to many shapefiles, name it something generic and put it in {base}/share/xastir/config. If it's specific to one shapefile, give it the same base name as the shapefile and a .dbfawk suffix and put it in the same directory as the shapefile.

Where do I find out what number corresponds to what color?