TRACK_REGION(1)



NAME

     track_region - strategy module to create a  time  series  of
     maps   of  a  region  tracked  in  heliographic  coordinates
     extracted from a series of solar images


SYNOPSIS

     track_region  [-cnvz] [argument= value ...]


DESCRIPTION

     Note: this module has been largely supplanted by the  module
     fastrack (q.v.) and is no longer being maintained.

     track_region extracts up to 16 regions fixed in some set  of
     heliographic coordinates from a series of solar images.  The
     tracked regions are specified  by  a  common  size  and  the
     heliographic  coordinates  of a set of individual locations.
     On output, sets of maps of regions centered on  these  loca-
     tions  are  produced.  Depending on the nature of the track-
     ing, the heliographic coordinates of the map centers will be
     continuously  adjusted  as  functions  of time, matching the
     specified coordinates only at  the  start.   If  a  tracking
     matching  the  Carrington rate is selected, the heliographic
     coordinates of all map locations will by  definition  remain
     fixed.

     If images are missing from the input data series  or  other-
     wise  rejected,  track_region  will  linearly interpolate in
     time across the gaps in the mapped output.  (Missing  images
     at  the end point result in continuation from the last valid
     map.)  Partial images have their missing values set  to  the
     appropriate  per  pixel values from the background image, or
     0, before the mapping.

     The input data series is normally assumned to be continuous,
     so  if  an  image selection range is made (...,series:XXX[I-
     J],sel:[M-N]) the first selector (M)is assumed to apply only
     to  the first data set (I) and the last selector (N)to apply
     only to the last data set (J); all  intervening  images  are
     accepted.   The  -c flag forces the image selection to apply
     inependently to each data set in the series.

     The -n option "turns off" tracking in  the  sense  that  the
     images  are  tracked at minus the Carrington rate.  There is
     no correction for observer motion in the latitudinal  direc-
     tion,  so  this  is  not  quite the same as mapping to fixed
     heliocentric coordinates.

     The "lagrangian" tracking option forces the tracking  to  be
     at  the differential rotation appropriate to the instantane-
     ous latitude for each point in the region, rather than at  a
     common rate for the whole region.

     The -z flag directs the output maps to be organized in polar
     coordinates,  with  azimuthal angle the most rapidly varying
     coordinate, (columns)  and  radial  distance  from  the  map
     center  the  next (rows).  The length of the angle dimension
     in that case will not be a power of 2 unless set by the cols
     value.

     If the verbose option (-v)  is  set,  one  line  of  history
     information will be produced per input image.

     The mapped data sets are placed in one or more 3-dimensional
     FITS  files, with time (image serial number) the most slowly
     varying axis.


ARGUMENTS

     in=Dataset
          The input dataset name.  The input dataset is  expected
          to  be  a series of calibrated images of all or part of
          the solar disc in a  "plate"  coordinate  system.   The
          dataset is assumed to include in its ancillary data the
          parameters required for  heliographic  mapping,  namely
          the  observation  time  and  heliographic location.  NO
          DEFAULT

     out=Dataset
          The output dataset name.  NO DEFAULT

     bckgn=name          The file name of a background  image  to
                         be subtracted from the data for detrend-
                         ing.  If not supplied no  detrending  is
                         performed.

     mskip=int           The threshold number of  missing  values
                         in an image, above which the whole image
                         is treated as  if  it  is  unacceptable.
                         (Default -1, in which case the threshold
                         is the maximum number of values  in  the
                         image)

     maps=int            The desired  number  of  tracked  output
                         series, up to 16.  (Default 1)

     latX=real           The heliographic latitude  (in  degrees)
                         of  the  center  of region X (0 - 15) at
                         start of tracking.  (Default 0.0)

     lonX=real           The heliographic longitude (in  degrees)
                         of  the  center  of region X (0 - 15) at
                         start of tracking.  (Default 0.0)

     radius=real         The  desired  minimum  radius   of   all
                         tracked    regions,    in   heliographic
                         degrees.   This  is  advisory  only;  if
                         used, the maps will be squares of length
                         equal to the smallest power  of  two  at
                         the   chosen   map  scale  necessary  to
                         include  the  minimum   radius,   unless
                         over-ridden  by  the rows and cols argu-
                         ments (see below).  For a typical  scale
                         of  0.12,  a  radius  of  about  15  deg
                         corresponds to a 128*128 map.   If  both
                         rows  and  cols are non-zero, this argu-
                         ment is ignored.

     scale=real          Scale of maps (in heliographic degrees /
                         pixel) at a location appropriate for the
                         selected  mapping  option;  a  0   value
                         implies  autoscaling  to  best  scale of
                         image.  Typical values  would  be  about
                         0.057  * resolution [arcsec / pixel] for
                         solar radii of  1000  arcsec,  or  about
                         0.12  for SOI full-disc images (or HiDHN
                         or HLH or TON images).  (Default 0.0)

     cols=int

     rows=int            The desired number of columns (rows)  in
                         the  mapped  images;  if  non-zero, each
                         over-rides the corresponding auto-scaled
                         dimension   appropriate  to  the  radius
                         paremeter. (Default 0)

     map=string          Mapping option:  recognized  values  are
                         "rectangular",   "Postels",  "gnomonic",
                         "stereographic",  "orthographic",  "Lam-
                         bert",  "cyleqa",  "sineqa", and "Merca-
                         tor".  Default: "Postels".

     map_pa=real         Position angle of the north direction on
                         the   output  image,  measured  positive
                         counterclockwise, in  degrees.  (Default
                         0.0)

     track=string        Tracking option: recognized  values  are
                         "eulerian"  and  "lagrangian".  Default:
                         "eulerian".

     a0=real

     a2=real

     a4=real             a0, a2, and a4 are the coefficients in a
                         sin^2  (latitude)  expansion of the dif-
                         ferential  rotation  rate,   minus   the
                         Carrington  rotation,  in  microradian /
                         sec.  Thus, if they  are  all  0,  rigid
                         Carrington  rotation  is  assumed.   The
                         default values, a0  =  -0.02893,   a2  =
                         -0.3441, a4 = -0.5037, correspond to the
                         Mt Wilson 1982/84 differential  rotation
                         rate  determined  by Snodgrass.  Ignored
                         if the -n flag is set.

     merid_v=real        Meridional  velocity  to  be  used   for
                         tracking, in microradian / sec, positive
                         northward.  (Any anomalous  zonal  velo-
                         city  must  be included in a0.)  Ignored
                         if the -n flag is set. (Default 0.0)

     platform=string     Observing  platform,  used  for  keyword
                         interpretation  and/or  observer  ephem-
                         eris;  recognized  values  are   "SOHO",
                         "GONG",  "HLH",  "MtWilson_60", "SPole",
                         and "TON".  For SOHO and multi-site net-
                         works,  the  ephemeris  data are assumed
                         contained in the data.  (Default "SOHO")

     xscale=real         (Defaults 0.0)

     yscale=real         "xscale" and "yscale" are the horizontal
                         and  vertical  scale of each image, both
                         in arcsec / pixel  to  be  used  in  the
                         absence  of  appropriate keywords in the
                         data.  If either is 0, default values of
                         1.977864  or  2.0 are supplied depending
                         on whether the  platform  is  "SOHO"  or
                         not.   These  values  are  used  in  the
                         automatic sizing of the maps, a bug.

     obstime=time        Not Used

     xc=float            (Defaults 0.0)

     yc=float            If non-zero, specify the coordinates  of
                         the  solar  disc  center  of each image,
                         overriding whatever the appropriate data
                         keywords  provide.   The  locations  are
                         assumed to  be  specified  in  units  of
                         image pixels measured from (0, 0) at the
                         center of the first image pixel.

     solar_radius=float  If non-zero, specifies the constant true
                         semi-diameter of the solar image in pix-
                         els, overriding the  value  supplied  by
                         the  appropriate  data  keyword for each
                         image.  (Default 0.0)

     basename=name       If the basename  is  "lat",  the  output
                         maps  will  be named latBBN or latBBS or
                         latBB, where fINN is the specified  cen-
                         tral   latitude  of  the  map.   If  the
                         basename is "lon",  the output maps will
                         be  named  lonLLL, where LLL is the cen-
                         tral longitude (at start of tracking  of
                         course).   Otherwise,  the files will be
                         named NNNN.fits, where NNNN is  the  map
                         number.


EXAMPLES

     track_region                    -pad                     in=
     prog:mdi,level:lev1.4,series:fd_V_01h[29818-29843],sel:[7-
     42]                                                     out=
     prog:mdi,level:lev2_track,series:vtrack_07_015_01536[45836]
     radius= 7.5 scale= 0.12 maps=  5  lat0=  -30.0  lat1=  -15.0
     lat2=  0.0 lat3= 15.0 lat4= 30.0 lon0= 60.0 lon1= 60.0 lon2=
     60.0 lon3= 60.0 lon4= 60.0 basename= lat


FILES


SEE ALSO

     fastrack(1), project(1)


DIAGNOSTICS

     soi_errno is returned and also set as the abortflg value  in
     the results keylist.


BUGS

     The "lagrangian" tracking option is  untested  and  probably
     horribly  slow.   Because  it  calculates  the instantaneous
     longitude for each point from an  integrated  rotation  rate
     based on its current latitude, the use of this option with a
     non-zero meridional anomalous velocity is likely to  produce
     results that are at best difficult to interpret.

     Whether or not a mapped point is on the  visible  hemisphere
     (within  180 degrees of requested tracking center) is deter-
     mined once for all at the outset; if the  proper  motion  is
     very  large and the tracking time long, there could be wrap-
     ping around the limb, and mappable points  could  be  marked
     unmappable,  but this is only likely to happen if the region
     is very large (full disc for example).

     If there are missing or rejected images at the start of  the
     input data series, the output for those times is garbage.

     The meridional anomalous velocity  merid_v  is  expected  in
     microradians  per  sec.   The  zonal  anomalous  velocity is
     equivalent to a0 and must be added to the  equatorial  value
     for  the  differential rotation (minus the Carrington rate).
     It might be better to have these expressed  in  degrees  per
     day or meters per sec.  The rotation rate is expanded in the
     customary even  powers  of  sin  (latitude),  not  the  more
     rational Legendre function expansion.  Furthermore, the rate
     is sidereal, and the zero-order term in the argument rate is
     assumed  not  to  include  the Carrington rate (1 rotation /
     25.38 days =~ 2.8653291  urad/sec).   Thus  the  appropriate
     coefficients  to  use  for tracking under a rigid Carrington
     rotation model are all 0.  Tracking at fixed proper  motions
     requires  setting  a2  and  a4  to 0 and a0 (and merid_v) to
     0.0014368 * rate (m/s) urad/sec.

     Most options associated with platform recognition other than
     the  default  "SOHO" do not exist.  The output data sets are
     not SSSC conforming.

     If "lat" or "lon" basenames are selected, the  latitudes  or
     longitudes  of  centers must all differ by at least a degree
     from one another, otherwise files will be overwritten.

     Use of the pointing and scaling arguments should be avoided;
     they are left over from development.

     With polar coordinate output the map  scales  don't  mean  a
     lot.


AUTHORS

     Rick Bogart and Luiz Sa


HISTORY

     1997-08-08     SOI Version 2.5