34

Tutorial

This section is a tutorial for the following:

Before starting, you will first need an account on a machine with network accessibility to GRASS. machine name , machine name , and machine name have GRASS access (all 3 have visible binary executables). machine name in addition has documentation (see Resources: Documentation.) The System Administrator is name ( phone ). After obtaining permission from the Boss (the person who controls all the equipment), one can contact him/her for an account.

Space on machine name is limited, so accessing the GRASS system from another machine is advised (please see Section 1.5.3: Installation Size) for the size of the GRASS installation. The lab facilities have several SGI machines available ( machine names .)

The tutorial assumes that access is from the SGI machine called machine names . If you are not familiar with the SGI windowing environment, you should learn the SGI operating systems before attempting this tutorial. Alternatively, NASA has a site license for MACx, which lets you use GRASS on a Mac connected to the Local Applenet (Currently, this option is being developed - so we do not yet have complete instructions for this method.) This access is noticibly slower than from a SGI machine.

1.3.1 Logging on to the computer

At a SGI console, log on using your Login and Password. Please take notice of the message telling you of the Schedule. Make sure you are not interfering with any on- going experiment or demonstration.

Make grass accessible to your account by typing:

   set path=($path ~schwehr/grass  ~schwehr/bin) 
You may want to include this in your ".tcshrc" or your ".csrhrc"

1.3.2 - Starting up GRASS

Start up grass by typing:

   grass4.1

You will see a pre-filled form:

  
  GRASS     4.1
  
  LOCATION: This is the name of an available geographic
  location.
  MAPSET:   Every GRASS session runs under the name of a
  MAPSET.
  
  Associated with each MAPSET is a rectangular COORDINATE
  REGION and a list
  of any new maps created.
  
  DATABASE: This is the UNIX directory containing the
  geographic databases The REGION defaults to the entire area
  of the chosen LOCATION.
  
  You may change it later with the command: g.region
  
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  - - - - - -
  LOCATION:   spearfish_____(enter list for a list of
  locations)
  
  MAPSET:     schwehr_______(or mapsets within a location)
  
  DATABASE:
  /home/schwehr/grass/data__________________________
       AFTER COMPLETING ALL ANSWERS, HIT <ESC> TO CONTINUE

If you are accessing machine name via a remote login or telnet, you must set up a graphics window accessible to GRASS on your console; i.e.

   setenv DISPLAY mymachine.arc.nasa.gov:0
Otherwise, one can use a display on the machine console:
   
   GRASS  4.1 > setenv DISPLAY machine.arc.nasa.gov:0

To see what DISPLAY is set at use the UNIX command "printenv". Note that one can use the UNIX commands at the GRASS prompt. GRASS is a variation of a cshell with access from the command line. This gives you the ability to create GRASS scripts just as one is able to create shell scripts.

Creating a GRASS Database for use with the Mars data

Enter Grass and change the initial form as follows:

Change the Location to 'mars.tutor.xy':

Change the Mapset to your last name. In this tutorial, the name will be 'schwehr,' however you will see your name in the output because this step changes the name.

Continue by typing in the <ESC>. If the location already exists, you will enter GRASS, otherwise your next screen will be:

  
  LOCATION <mars.tutor.xy> - doesn't exist
  Available locations:
  ----------------------
  den.utm.z12                mars.in.xy
  denver.aea                 spearfish
  ----------------------
  Would you like to create location <mars.tutor.xy> ? (y/n) y
  
  To create a new LOCATION, you will need the following
  information:
  1. The coordinate system for the database
                      x,y (for imagery and other unreferenced data)
                      UTM
                      State Plane
                      Latitude-Longitude
                      other projection
  2. The zone for the database
                 (except for x,y and Latitude-Longitude databases)
  3. The coordinates of the area to become the default region
       and the grid resolution of this region
  4. A short, one-line description or title for the location
  
  Do you have all this information for location
  <mars.tutor.xy> ? (y/n) y
  
  Please specify the coordinate system for location
  <mars.tutor.xy>
            0 x,y
            1 UTM
            2 State Plane
            3 Latitude-Longitude
       99 Other
  RETURN to cancel
  >    0
  x,y coordinate system? (y/n) [y]
  
  Please enter a one line description for location
  <mars.tutor.targ>
  >    Mars Database for the grass   4.1 tutorial
  
  =====================================================
  Mars Database for the grass 4.1 tutorial
  =====================================================
  ok? (y/n) [y]
  
  
                                DEFINE THE DEFAULT REGION
  
                               ====== DEFAULT REGION =======
                              | NORTH EDGE:2000_______     |
                     WEST EDGE|                            |EAST EDGE
                   0__________|                            |2000_______
                              | SOUTH EDGE:0__________     |
                               ============================
  
          PROJECTION: 0 (x,y)                        ZONE: 0
  
                           GRID RESOLUTION
                              East-West:     1_________
                            North-South:     1_________
  
  
         AFTER COMPLETING ALL ANSWERS, HIT <ESC> TO CONTINUE
                            (OR <Ctrl-C> TO CANCEL)
  
       projection:   0 (x,y)
       zone:                 0
       north:               2000
       south:               0
       east:                2000
       west:                0
       e-w res:             1
       n-s res:             1
  
       total rows:             2000
       total cols:             2000
       total cells:       4,000,000
  
  Do you accept this region? (y/n) [y] > y
  
  LOCATION <mars.tutor.xy> created!
  Hit RETURN -->
  
  GRASS     4.1
  
  LOCATION: This is the name of an available geographic
  location.
  MAPSET:   Every GRASS session runs under the name of a
  MAPSET.
  
  Associated with each MAPSET is a rectangular COORDINATE
  REGION and a list
  of any new maps created.
  
  DATABASE: This is the unix directory containing the
  geographic databases The REGION defaults to the entire area
  of the chosen LOCATION.
  
  You may change it later with the command: g.region
  
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  - - - - - -
  LOCATION:   mars.tutor.xy__(enter list for a list of
  locations)
  
  MAPSET:     schwehr_______(or mapsets within a location)
  
  DATABASE:
  /home/schwehr/grass/data__________________________
       AFTER COMPLETING ALL ANSWERS, HIT <ESC> TO CONTINUE
  
  
  Welcome to GRASS 4.1 (Spring 1993) Update package 4
  Geographical Resources Analysis Support Systems (GRASS) is
  a Trademark of U.S. Army Construction Engineering Research
  Laboratories (USACERL)
  New releases of GRASS are coordinated and produced by the
  Office of GRASS Integration (OGI) located at USACERL, and
  incorporate software contributions from numerous sources
  
  This version running thru the C Shell (/bin/csh)
  Help is available with the command: g.help
  
  When ready to quit enter:             exit
  
  Mapset <schwehr> in Location <mars.tutor.xy> GRASS 4.1 >
  exit
  Mapset <schwehr> in Location <mars.tutor.xy> GRASS 4.1 >
  GRASS SESSION WRAPUP
  You have just finished working on mapset: <schwehr>
  There are no RASTER maps in this mapset
  There are no VECTOR maps in this mapset
  There are no SITES maps in this mapset
  Shall the mapset <schwehr> be saved? y/n [y]
  
       GOOD BYE from GRASS

Accessing Mars Data from the CD-ROM

The VPE facilities has an assortment of planetary data on CD- ROM; including Mars. The CD-ROM needed for this tutorial is:
  
  MARS: GLOBAL TOPOGRAPHY; VOLUME7
  Mission To Mars: Digital Topographic Map, prepared by
  USGS fo NASA 1993

This tutorial assumes that the CD-ROM is loaded on the computer which is running GRASS. Please ask the System Adminitrator to place the CD-ROM on the machine. Once accessible, go to the LOCATION directory:

   
   GRASS 4.1 > cd ~schwehr/grass/data/mars.tutor.xy Mapset>
If you do a listing you should see your name as the directory for your mapset:
  
   GRASS 4.1 > ls
  
  PERMANENT
   schwehr

Go to the Mapset directory. Here we will create a subdirectory called 'cell' where we will place the CD-ROM data of interest. For this example we will use the dataset called: tg15n067. The nomenclature is that of the Mars CD- ROM system where each image file has a unique name constructed according to the type of image file, resolution and its central latitude and longitude (See Section 1.5.4: Appendix: VOLINFO.TXT).

  
   GRASS 4.1 > cd schwehr
   GRASS 4.1 > mkdir cell
   GRASS 4.1 > cd cell
   GRASS 4.1 > cp /CDROM/tng15nxxx/tg15n067.img
The data comes with an ascii header file that must be removed in order to make it GRASS accessible. See Section 1.5.4 Appendix: VOLINFO.TXT) for a description of all the records of the header. You can see the header by using a unix listing command like 'more' or 'head :'
  
   GRASS 4.1 > more tg15n067.img
  
  CCSD3ZF0000100000001NJPL3IF0PDS200000001 = SFDU_LABEL
  
  /*          FILE FORMAT AND LENGTH */
  RECORD_TYPE    = FIXED_LENGTH
  RECORD_BYTES   = 1912
  FILE_RECORDS   = 962
  LABEL_RECORDS  = 2
  
  /*          POINTERS TO START RECORDS OF OBJECTS IN FILE */
  ^IMAGE               = 3
  
  /*          IMAGE DESCRIPTION */
  DATA_SET_ID    = "VO1/VO2-M-VIS-5-DTM-V1.0"
  SPACECRAFT_NAME     = {VIKING_ORBITER_1, VIKING_ORBITER_2}
  TARGET_NAME    = MARS
  IMAGE_ID  = TG15N067
  INSTRUMENT_NAME     = {VISUAL_IMAGING_SUBSYSTEM_CAMERA_A,
  VISUAL_IMAGING_SUBSYSTEM_CAMERA_B} NOTE = "DIGITAL TERRAIN
  MODEL, 1/64-DEGREE PER PIXEL"
  
  /*          DESCRIPTION OF OBJECTS CONTAINED IN FILE */
  OBJECT    = IMAGE
  LINES     = 960
  LINE_SAMPLES   = 956
  SAMPLE_TYPE    = VAX_INTEGER
  SAMPLE_BITS    = 16
  CHECKSUM  = 128838457
  MINIMUM   = 2497
  MAXIMUM   = 4749
  
  /*        ELEVATION (METERS) = 2*DN - 6000, NULL DN VALUES = 0 */
  MISSING   = 0
  SCALING_FACTOR = 2
       OFFSET  = -6000END_OBJECT   = IMAGE
To strip the header use the split.pds.image command (Section 1.5.2: C Code Written During Installation):
   GRASS 4.1 > split.pds.image
  
  File to read from:tg15n067.img
  Img Output file:tg15n067
  Text Output file:tg15n067.lbl
  Text Header Size:3824 3824
  characters written 1835520 characters written
In addition to stripping the header, the binary file bye order must be swapped. The Mars DTM files from the USGS Viking CD-ROM lists the data type as 16 bit Vax_integers. IBM and Vaxes have a different byte order than MIPs (SGI) machines in that integers are longer than one byte. The symtom of the wrong byte order is to have unusual and rapidly varying values in small areas on the image. Use the swap.bytes command to change the file for the SGI machine. This program reads in each pair of bytes, swaps them, and writes them out to a different file (Appendix: C-Code):
   GRASS 4.1 > swap.bytes
  
  Swap bytes for a 16bit image file.
  File to read from:tg15n067 Img
  Output file:tg15n067.swap
  917760 characters written
If you do a listing you should see the following files:
   GRASS 4.1 > ls -l
  
  total 10771
  -rw-r--r-- 1 schwehr vpe 1835520   Aug 17  13:42  tg15n067
  -rw-r--r-- 1 schwehr vpe 1839344   Aug 17  13:38  tg15n067.img
  -rw-r--r-- 1 schwehr vpe 3824      Aug 17  13:42  tg15n067.lbl
  -rw-r--r-- 1 schwehr vpe 1835520   Aug 17  13:44  tg15n067.swap
For convenience, one can rename the file:
   GRASS 4.1 > mv tg15n067.swap tg15n067
Creating the GRASS header Support Files GRASS needs some support files called header files. The utility used is `r.support'.
   GRASS 4.1 > r.support
  
  Enter name of raster file for which you will create/modify
  support files
  Enter 'list' for a list of existing raster files
  Enter 'list -f' for a list with titles
  Hit RETURN to cancel request >
GRASS treats any file in a /<location>/<mapset>/cell/ directory as a binary raster image.
  list <list>
  
  ----------------------------------------------
   raster files available in mapset schwehr:
  tg15n067
  tg15n067.img
  tg15n067.lbl
  ----------------------------------------------
  
  Enter name of raster file for which you will create/modify
  support files
  Enter 'list' for a list of existing raster files
  Enter 'list -f' for a list with titles
  Hit RETURN to cancel request
  > tg15n067
  <tg15n067>
Since we are creating the header file, GRASS will indicate this and then allow us to create it. The input values are obtained from the header file of the raw data:
  LINES     = 960
  LINE_SAMPLES   = 956
  SAMPLE_TYPE    = VAX_INTEGER
  SAMPLE_BITS    = 16
One obtains the number of bytes per cell by dividing the SAMPLE_BITS by 8 (resulting in 2). The values are used as follows:
  WARNING: Can't open header file for [tg15n067 in schwehr]
  Edit the header for [tg15n067]? (y/n) [y] y
  Edit header for [tg15n067] cellhd
  compression: 0 3.0 compression not indicated
  pre 3.0 compression not indicated
  hit RETURN to continue -->
  
  Please enter the following information for [tg15n067]
  
  960__     Number of rows
  956__     Number of cols
  2____     Number of bytes per cell
  rows * cols * bytes per cell must be same as file size
  (1835520)
  If you need help figuring them out, just hit ESC
  AFTER COMPLETING ALL ANSWERS, HIT <ESC> TO CONTINUE (OR
  <Ctrl-C> TO CANCEL)
If you input the incorrect information, GRASS will attempt to assist you. For example suppose that you entered 957 instead of 956. Your ouput will show
  The product of the rows(960), cols(957) and bytes per
  cell(2) does not equal the file size (1835520)
  
  The following combinations will produce the correct file
  size
  
  2 bytes per cell
   1 * 917760   2 * 458880   3 * 305920   4 * 229440
   5 * 183552   6 * 152960   8 * 114720  10 * 91776
  12 * 76480   15 * 61184   16 * 57360   20 * 45888
  24 * 38240   30 * 30592   32 * 28680   40 * 22944
  48 * 19120   60 * 15296   64 * 14340   80 * 11472
  96 * 9560   120 * 7648   128 * 7170   160 * 5736
 192 * 4780   239 * 3840   240 * 3824   256 * 3585
 320 * 2868   384 * 2390   478 * 1920   480 * 1912
 640 * 1434   717 * 1280   768 * 1195   956 * 960
  hit RETURN to continue -->

Figure 5: tg15n067.first.gif.


[Prev] [Next]
Email to:
Kurt Schwehr schwehr@cs.stanford.edu -- Dan Delgado renata@eos.arc.nasa.gov

Tree Kurt's Homepage