i.tape.tm3(1)		      Grass User's Manual		 i.tape.tm3(1)



NNAAMMEE
       _i_._t_a_p_e_._t_m_3 - Import Landsat thematic mapper imagery.

       _(_G_R_A_S_S _I_m_a_g_e _P_r_o_c_e_s_s_i_n_g _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       ii..ttaappee..ttmm33 --ee [iinnppuutt_=_n_a_m_e] [bblloocckkssiizzee_=_b_l_o_c_k_s_i_z_e]

       ii..ttaappee..ttmm33     [--ppqq]	[iinnppuutt_=_n_a_m_e]	 ggrroouupp_=_n_a_m_e    [oouuttppuutt_=_p_r_e_f_i_x]
       bbaannddss_=_b_a_n_d_[_,_b_a_n_d_,_._._._]   [bblloocckkssiizzee_=_b_l_o_c_k_s_i_z_e]   [rroowwss_=_f_i_r_s_t_r_o_w_,_l_a_s_t_r_o_w]
       [ccoollss_=_f_i_r_s_t_c_o_l_,_l_a_s_t_c_o_l] [ttiittllee_=_t_i_t_l_e]

DDEESSCCRRIIPPTTIIOONN
       _i_._t_a_p_e_._t_m_3  is a successor to _i_._t_a_p_e_._t_m.  _i_._t_a_p_e_._t_m_3 can import Landsat
       Thematic Mapper imagery in fast format, full scene, and quadrant  scene
       formats.  Imports may be done from 1600 BPI and 6250 BPI 9-track tapes,
       QIC 150 tape, 8mm tape, or from disk files.  _i_._t_a_p_e_._t_m_3	is  completely
       command-line  driven,  although	the  usual GRASS parser may be used if
       command line options are not given.  During the import, the program may
       also prompt for filenames to use and tapes to be mounted.


       _i_._t_a_p_e_._t_m_3  must  be  run  in  a location with an x,y coordinate system
       (i.e., a coordinate system with a projection 0.)  Refer to the  imagery
       manual entry.

   FFllaaggss::
       --ee     Examine  tape  or  files.   A  summary  of  information from the
	      scene's headers is printed.  No bands  are  imported.   If  this
	      option  is  given,  all other options except input and blocksize
	      are ignored.

       --pp     Display the percentage of work  done.   By  default,  _i_._t_a_p_e_._t_m_3
	      displays	the number of lines for each band that it has imported
	      so far.

       --qq     Run quietly.  Error messages  are  still	printed  but  messages
	      about the import's progress are not.


   PPaarraammeetteerrss::
       iinnppuutt==nnaammee
	      The  name of the device or file to extract imagery from.	If not
	      given, _i_._t_a_p_e_._t_m_3 will assume the import is from disk files  and
	      will prompt for file names.

       ggrroouupp==nnaammee
	      The  name  of  the  group to store imported bands in.  The group
	      will be created if it does not already exist.

       oouuttppuutt==pprreeffiixx
	      The prefix with which to name the  raster  maps  for  each  band
	      imported.   The  band  number  of each raster map is appended to
	      this prefix.  If omitted, the group name is used as the  prefix.

       bbaannddss==bbaanndd[[,,bbaanndd,,......]]
	      The  list  of  bands  to import.	Band numbers range from 1 to 7
	      inclusive.  Band numbers may be specified  in  any  order.   For
	      fast format imagery, a band number of "P" may be used to specify
	      the panchromatic band.

       bblloocckkssiizzee==bblloocckkssiizzee
	      The blocksize to use for reading tapes.  For QIC-150 tapes, this
	      value must be a multiple of 512.	The default is 32768.

       rroowwss==ffiirrssttrrooww,,llaassttrrooww
	      The  range  of  rows  within  each  band	to  import.  Must have
	      firstrow <= lastrow.  Row numbers increase from top  to  bottom.
	      The topmost, or northernmost, row of each band is row 1.

       ccoollss==ffiirrssttccooll,,llaassttccooll
	      The  range  of  columns  within  each band to import.  Must have
	      firstcol <= lastcol.   Column  numbers  increase	from  left  to
	      right.   The  leftmost,  or  westernmost, column of each band is
	      column 1.

       ttiittllee==ttiittllee
	      The title to give each extracted band.  The default is  "Landsat
	      TM Imagery"


   UUSSAAGGEE
       _i_._t_a_p_e_._t_m_3  can import Landsat TM imagery in three formats: full scene,
       quadrant scene, and fast format.  Full scene and  quadrant  scene  file
       formats	are very similar, and differ only in the size of the image.  A
       quadrant scene corresponds to one quarter of a full scene of  the  same
       area.  _i_._t_a_p_e_._t_m_3 can read fast format imagery in its A and B versions.
       See the references for file format documents.


       Information about a TM scene can be obtained by using  the  _-_e  option.
       It  is useful to use this option before importing imagery.  This option
       will examine the files on tape or disk and print important  information
       about the scene.  Fields printed include the file format, size of image
       in pixels, scene ID, and date of creation.  Coordinates for  the  scene
       center  or  corners  are  given depending on the file format.  For full
       scene and quarter scene formats, the  _-_e  option  requires  the	volume
       directory  file	and a leader and imagery file from a single band.  For
       the fast format, the _-_e option requires only a header file.


       _i_._t_a_p_e_._t_m_3 allows the block size to be specified.  This is  the	number
       of  bytes  to  read from a tape at a time.  The block size is optional;
       specifying it may or may not make the import run faster.   The  default
       is  32768.   Look  on  the  tape's  label  to find the block size.  For
       QIC-150 tapes, the block size must be a multiple of 512 or  the	import
       will  fail.   The  maximum allowable block size is one megabyte (1024 *
       1024 = 1048576 bytes.)  The block size is not used when importing  from
       disk files.


       The following sections describe the tape file formats and how to import
       from disk files.  If you are copying imagery between tapes or to  disk,
       it  is  necessary  to  understand how the files are arranged on tape so
       that _i_._t_a_p_e_._t_m_3 will be able to import from copied tapes correctly.  If
       you  are  importing from the original tapes or exact copies there is no
       need to be concerned with the tape formats.

   FFUULLLL SSCCEENNEE AANNDD QQUUAADDRRAANNTT SSCCEENNEE FFIILLEE FFOORRMMAATTSS
       For full scene and quadrant scene formats, it may require more than one
       tape  to  store	the seven bands of a single Landsat scene.  The set of
       tapes containing imagery for a single scene is  called  a  volume  set.
       Each  tape in a set has the same format.  The first file on the tape is
       a volume directory file.  This is followed by a	leader	file,  imagery
       file, and trailer file for each band on the tape.  There may be supple-
       mental files after the the bands, but these are not used by _i_._t_a_p_e_._t_m_3.
       For  example,  a  tape containing bands 1-3 of Landsat imagery contains
       these files:

	      Volume Directory File
	      Band 1 Leader File
	      Band 1 Imagery File
	      Band 1 Trailer File
	      Band 2 Leader File
	      Band 2 Imagery File
	      Band 2 Trailer File
	      Band 3 Leader File
	      Band 3 Imagery File
	      Band 3 Trailer File
	      Supplemental File

       When importing from tape, the program will prompt  the  user  to  mount
       each  tape  needed.  Tapes may be mounted in any order.	Only the tapes
       that contain the bands to be imported need be mounted.	Be  sure  that
       tapes are rewound or positioned correctly before mounting them.

   IIMMPPOORRTT FFRROOMM DDIISSKK FFIILLEESS
       _i_._t_a_p_e_._t_m_3  can	import	imagery from disk files.  The volume directory
       must be copied from tape to disk, as well as the leader,  imagery,  and
       trailer	files for each band to import.	To speed the import, the file-
       names should all have the same prefix and have a .ls# suffix,  where  #
       is an integer that increases sequentially from zero.  The prefix may be
       any name.  For example, if you wanted to import bands  2  and  3  of  a
       quadrant  scene from disk files, you would copy the files from tape and
       give them names like this:

	      Volume Directory File	  landsat.ls0
	      Band 2 Leader File	  landsat.ls1
	      Band 2 Imagery File	  landsat.ls2
	      Band 2 Trailer File	  landsat.ls3
	      Band 3 Leader File	  landsat.ls4
	      Band 3 Imagery File	  landsat.ls5
	      Band 3 Trailer File	  landsat.ls6

       The volume directory file must have the .ls0 suffix.  Only the  leader,
       imagery,  and trailer files for the bands to be imported need be copied
       to disk.  The prefix "landsat" is used here, but any name can be  used.
       Each  file  must  have a .ls# suffix, though.  By naming the files this
       way, _i_._t_a_p_e_._t_m_3 can easily read the files in the correct  order.   Once
       these files are on disk, they may be imported with a command like this:


       _i_._t_a_p_e_._t_m_3 _i_n_p_u_t_=_l_a_n_d_s_a_t _g_r_o_u_p_=_l_a_n_d_s_a_t _b_a_n_d_s_=_1_,_2_,_3


       The input option specifies the prefix to use for the file  names.   The
       .ls#  suffix  should  not  be included in the input option.  _i_._t_a_p_e_._t_m_3
       will automatically append the .ls# suffix to each file in turn.


       Naming the imagery files in this fashion is the easiest way  to	import
       from  disk.   However,  _i_._t_a_p_e_._t_m_3  can import from files that have any
       names.  The program will prompt for filenames.  Enter the filenames  at
       each prompt in the order that the files would be read from tape in.  To
       import this way, omit the input option in the command, like this:


       _i_._t_a_p_e_._t_m_3 _g_r_o_u_p_=_l_a_n_d_s_a_t _b_a_n_d_s_=_1_,_2_,_3


       If you are importing from disk files with  .ls#	filenames,  _i_._t_a_p_e_._t_m_3
       will  prompt  for  a  filename at any time that it cannot find the next
       file to read.

   FFAASSTT FFOORRMMAATT TTMM IIMMAAGGEERRYY
       Like full scenes and quadrant scenes, imagery in fast format  may  come
       on multiple tapes, depending on the amount of data.  The file format is
       very simple, consisting of a header file followed by imagery files  for
       each of the bands.  The imagery files are flat data files; they have no
       header information within them.	For example, a set of seven bands  for
       a  scene  in  fast format may come on three 9-track tapes and look like
       this:

	      Tape 1	     Tape 2Tape 3
	      Header File    Header FileHeader File
	      Band 1	     Band 4Band 7
	      Band 2	     Band 5
	      Band 3	     Band 6

       Because the band files have no header information in them, the only way
       _i_._t_a_p_e_._t_m_3  can tell which band is which is by the order the files come
       in their header file.  If fast format imagery is ever copied  to  other
       tapes be sure the files are kept in the same order as they came.


       To  import  fast format imagery from disk files, copy the files to disk
       using the same naming convention used for  quadrant  and  full  scenes.
       The  header  file  must have a .ls0 extension.  The band 1 imagery file
       should have a .ls1 extension, band 2  a	.ls2  extension,  etc.	 If  a
       panchromatic band is available, give it a .ls8 extension, for lack of a
       better name.


       If you are importing only spectral bands, the header file from any tape
       may  be	used  as the .ls0 file.  But if you are importing the panchro-
       matic band, use the header file from its tape.	The  headers  for  the
       spectral bands and the panchromatic band are different; be sure to copy
       the right one to the .ls0 file before importing.


       When importing the panchromatic band from fast format imagery,  specify
       the band number as "P", like this:


       _i_._t_a_p_e_._t_m_3 _i_n_p_u_t_=_l_a_n_d_s_a_t _g_r_o_u_p_=_l_a_n_d_s_a_t _b_a_n_d_s_=_P


       If  the input option is omitted, of if the program cannot find the file
       for a band asked for, it will prompt for a filename to be entered.

   RROOWW AANNDD CCOOLLUUMMNN EEXXTTRRAACCTTIIOONN
       _i_._t_a_p_e_._t_m_3 can extract an entire image or a rectangular	region	within
       an  image.  Use the rows and cols options to specify the ranges of rows
       and columns to import.  Before importing the imagery, use the _-_e option
       to display the number of rows and columns in the image.	Row and column
       numbers begin at 1.  Row numbers increase from top  (north)  to	bottom
       (south).  Column numbers increase from left (west) to right (east).  If
       either option is omitted the full range is used.  The  program  ignores
       the  current geographic region when importing.  When the import is com-
       plete, the current region is set to the region extracted.

NNOOTTEESS
       Raster files created will overwrite exiting files with the  same  names
       without warning.


       Use  the dd(1) command to copy files to tapes.  When copying to 9-track
       and 8mm tapes, just use the if and of options with a  large  blocksize.
       Use  caution when copying data to QIC-150 tapes.  QIC-150 tapes require
       all files to use record lengths that are multiples of 512.  Files whose
       lengths	are not multiples of 512 must be padded.  Always use dddd with
       the "sync" option when copying files to QIC-150 tape, like this:

		 dd if=filename of=/dev/rst0 obs=32768 conv=sync

       obs is the output block size; use any multiple of 512.  The larger  the
       block size the faster the copy will be done. When Landsat imagery files
       are copied this way they will be padded at the end, making them	longer
       than  they  originally  were.   _i_._t_a_p_e_._t_m_3 will have no problem reading
       padded files, but other programs may.

RREEFFEERREENNCCEESS
       Format for Thematic Mapper Computer Compatible  Tape,  Quadrant	Scene,
       Jan 1, 1990

       Format for Thematic Mapper Computer Compatible Tape, Full Scene, Jan 1,
       1990

       Fast Format Document for TM Digital Products, Version A, Mar 1, 1990

       Fast Format Document for TM Digital Products, Version B, Oct 1, 1991


       These documents describe the  file  formats  that  _i_._t_a_p_e_._t_m_3  imports.
       They are available from EOSAT, 4300 Forbes Blvd., Lanham, MD 20706 USA.

AAUUTTHHOORR
       Christopher Lesher, DBA Systems, Inc.

       Michael Shapiro, U. S. Army Construction Engineering  Research  Labora-
       tory

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_3_/_0_1 _0_0_:_2_7_:_4_5 _$



GRASS 5.0							 i.tape.tm3(1)
