FASTRACK(1)



NAME

     fastrack - strategy module to create one or more time series
     of  maps  of  regions  tracked  in  heliographic coordinates
     extracted from a series of solar images


SYNOPSIS

     fastrack  [-clnvz] [argument= value ...]


DESCRIPTION

     fastrack extracts from a series  of  solar  images  multiple
     regions  fixed  in  co-moving  frames  at a set of initially
     specified heliographic coordinates.  The tracked regions are
     of  a  common specified size, and the same map projection is
     used, only the central  point  varying.   Depending  on  the
     nature  of the tracking, 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,  fastrack  will linearly interpolate in time
     across the gaps in the mapped output.   (Missing  images  at
     the  end  points  result in continuation backward or forward
     from the first or last valid map.)  Partial input images may
     produce missing values in the mapped images.

     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
     independently to each data set in the series.

     The -l flag sets a "lagrangian" tracking option, forcing the
     tracking  to  be at the differential rotation appropriate to
     the instantaneous latitude for each  point  in  the  region,
     rather than at a common rate for the whole region.

     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 -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 purposes
                         of  detrending.   If  not  supplied,  no
                         detrending  is performed.  Note that the
                         background image must  be  in  the  same
                         format  as  the  images.  If it is used,
                         all images in the input data set must be
                         in  or  reconstructable to the same for-
                         mat; detrending is performed before  the
                         images  are  mapped.   If the background
                         image   is   1-dimensional   (presumably
                         corresponding   to   MDI  crop  format),
                         detrending will be performed before  the
                         images are reconstructed.

     lat=real            The array of heliographic latitudes  (in
                         degrees)  of  the  centers of regions at
                         start of tracking.  (Default [0.0])

     lon=real            The array of heliographic longitudes (in
                         degrees)  of  the  centers of regions at
                         start  of  tracking.   (Default   [0.0])
                         Note:  if  multiple latitudes and longi-
                         tudes are requested, the  number  should
                         agree;  if  it doesn't, the longer array
                         is used and the unspecified latitude  or
                         longitude  center  values default to the
                         last one specified.

     map=string          Mapping  projection  option:  recognized
                         values   are  "rectangular",  "Postels",
                         "gnomonic",   "stereographic",   "ortho-
                         graphic", "Lambert", "cyleqa", "sineqa",
                         and "Mercator".  (Default: "Postels")

     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,
                         implying auto-scaling.

     map_pa=real         Position angle of the north direction on
                         the   output  image,  measured  positive
                         counterclockwise, in degrees.  (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.

     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)

     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  Car-
                         rington  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)

     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.

     imgscale=real       The plate scale to be assumed  for  each
                         image, in arcsec / pixel.  If specified,
                         this value overrides that found  in  the
                         input data.  (Default: Not specified)

     basename=name       If the basename  is  "lat",  the  output
                         maps  will  be  named  latBB.BN.fits  or
                         latBB.BS.fits  or  lat00.0.fits,   where
                         BB.B  is  the specified central latitude
                         of the map.  If the basename  is  "lon",
                         the    output   maps   will   be   named
                         lonLLL.L.fits, where LLL.L is  the  cen-
                         tral longitude (at start of tracking, of
                         course).  If the basename  is  "latlon",
                         the  output  map  names will combine the
                         above            forms,             e.g.
                         latBB.BNlonLLL.L.fits.   Otherwise,  the
                         files will  be  named  NNNN.fits,  where
                         NNNN  is  the  map number. (Default: Not
                         specified)


EXAMPLES

     fastrack                      -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]
     cols=   128   rows=   128   scale=   0.125   lat=   {-30.0,-
     15.0,0.0,15.0,30.0} lon= 60.0 basename= lat


FILES


SEE ALSO

     track_region(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
     very  slow.   Because it calculates the instantaneous longi-
     tude 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).

     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.

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

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

     Data quality selection via quality bitmasks or otherwise  is
     still  unimplemented; all input images are used uncondition-
     ally.


AUTHOR

     Rick Bogart


HISTORY

     2000-08-15     SOI Version 4.8