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  com-
       pletely	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 file-
       names 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  coordi-
       nate  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 speci-
	      fied in any order.  For fast format imagery, a band
	      number  of  "P" may be used to specify the panchro-
	      matic 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 dif-
       fer only in the size of the image.  A quadrant scene  cor-
       responds  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 import-
       ing  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 vol-
       ume directory file.  This is followed by  a  leader  file,
       imagery	file, and trailer file for each band on the tape.
       There may be supplemental 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  filenames  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 for-
       mat 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 panchromatic 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 geo-
       graphic 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 copy-
       ing 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, Quad-
       rant 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 Laboratory

       _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)
