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