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.
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"
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:0Otherwise, 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.
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
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.imgThe 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 = IMAGETo 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 writtenIn 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 writtenIf 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.swapFor convenience, one can rename the file:
GRASS 4.1 > mv tg15n067.swap tg15n067Creating 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 = 16One 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.