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)
