[Previous]
[Next]
NAME:
EarthSky3DLoc
PURPOSE:
Returns the 3D positions for all segments along a collection of lines
of sight. The lines of sight either form a grid for a 2D sky map, or
are explicitly input.
CATEGORY:
sat/idl/util
CALLING SEQUENCE:
FUNCTION EarthSky3DLoc, UT , $
cv2carrington=cv2carrington, $
nra = nra , $
nde = nde , $
nrr = nrr , $
drr = drr , $
equator = equator , $
degrees = degrees , $
ra = ra , $
dec = dec , $
zero_point = zero_point, $
zero_phase = zero_phase, $
zero_shift = zero_shift, $
rr_earth = rr_earth , $
ut_earth = tt , $
pa_earth = pa_earth , $
elo_earth = elo_earth , $
elo_sun = elo_sun , $
center = center , $
_extra = _extra
INPUTS:
UT scalar; type: standard time structure
time when skymap is required
OPTIONAL INPUT PARAMETERS:
/degrees if set then all in- and ouput angles are in degrees
(default: radians)
/equator by default the lines of sight are specified in ecliptic coordinates
(i.e. in a skymap the horizontal plane is the ecliptic).
If /equator is set then equatorial coordinates are assumed (i.e.
in a skymap the horizontal plane is Earth's equator)
/cv2carrington
CALLED BY:
vu_coronagraph, vu_earthskymap, vu_elotime, vu_lineofsight
NOTE: this only makes sense if keyword /to_heliographic is set !!
By default, the longitudinal (first) dimension in the output
R and rr_earth is a phase angle (longitude).
If heliographic coordinates are used then instead of an angle
a Carrington variable within 0.5 of the Carrington variable
corresponding to input time UT is returned.
zero_shift=zero_shift
scalar; type: float; default: 0.0
shifts the center of the sky grid. Instead of centering on the
Sun the grid is shifted to increasing RA or ecliptic longitude
by 'zero_shift'.
The units must be consistent with the setting of /degrees.
nrr scalar; type: int; default: 20
number of steps along lines of sight at each point in the sky
drr scalar; type: float; default: 0.1
step size along line of sight (AU)
Lines of sight are specified as sidereal location in the sky (either
RA/dec (/equator SET) or ecliptic longitude/latitude (/equator NOT set).
If nRA and nDE are set to non-zero values then a grid of lines of sight
covering the entire sky is created (see PROCEDURE):
nra scalar; type: int; default: 72
nr of points in skymap in longitudinal direction (either right
ascensions of ecliptic longitude)
If nra or nde is set to zero then ra and dec are used as input.
nde scalar; type: int; default: 36
nr of points in skymap in latitudinal direction (either declination
or ecliptic latitude)
Alternatively, set the product nra*nde=0 and specify lines of sight explicitly
through keywords ra,dec:
ra[nLOS]
scalar or array; right ascensions (/equator SET) or
ecliptic longitudes (/equator NOT set)
dec[nLOS]
scalar or array; declinations (/equator SET) or
ecliptic latitudes (/equator NOT set).
OUTPUTS:
Result array[3,nra,nde,nrr]; type: double
array[3,nlos,nrr]; type: float (if nra or nde is zero)
3D locations for all segments along all lines of sight. This is where
values need to obtained by interpolation on the 3D arrays.
The result is in spherical coordinates in the coordinates specified
as one of the /to_* keywords to CvSky.
R[0,*,*,*]: longitudes
If /to_heliographic and /cv2carrington are SET then
these are Carrington variables within 0.5 of Carrington(UT)
R[1,*,*,*]; latitudes
R[2,*,*,*]: heliocentric distances (AU)
OPTIONAL OUTPUT PARAMETERS:
Only if nra*nde not equal 0 on input:
ra array[nra]; type: float
right ascensions or ecliptic longitudes across sky
(with ra/longitude of Sun in center of array)
i.e. ra = (ra Sun at time UT) -pi+2*pi/nra*[0.5,1.5,...,nra-0.5]
dec array[nDE]; type: float
declination or ecliptic latitude across sky
(with decl/lat zero in center of array)
DE = -pi/2+pi/nDE*[0.5,1.5,...,nDE-0.5]
Depending on setting of /equator, RA and DEC define a regular grid in
equatorial or ecliptic sky coordinates for the centers of the boxes for the
lines of sight used to build the skymap with the position of the Sun
centered in the RA/longitudinal direction.
zero_phase=zero_phase
scalar; type: float
right ascension or ecliptic longitude of Sun (plus zero_shift)
if specified) at time UT, i.e. this is the value on which ra is centered
zero_point=zero_point
scalar; type: float
right ascension or ecliptic longitude of Sun (plus zero_shift)
at time UT (i.e. same as 'zero_phase'; should stay to ensure
that the values are consistent when fed e.g. to PlotEarthSkymap)
rr_earth
array[3]; type: float
heliocentric location Earth in heliographic coordinates
rr_earth[0]: longitude
If /to_heliographic and /cv2carrington are SET then
these is a Carrington variable within 0.5 of Carrington(UT)
rr_earth[1]; latitude
rr_earth[2]: heliocentric distance (AU)
pa_earth=pa_earth
array[nra,nde,nrr]; type: float
line of sight position angle measured counterclockwise
from ecliptic north
elo_earth=elo_earth
array[nra,nde,nrr]; type: float
line of sight elongations: angle (Sun-Earth-los segment)
elo_sun=elo_sun
array[nra,nde,nrr]; type: float
angle Earth-Sun-los segment
INCLUDE:
@compile_opt.pro ; On error, return to caller
SEE ALSO:
EarthTransit3DLoc, PlotEarthSkymap
CALLS: ***
AngleRange, Carrington, CvPointOnLos, CvSky, InitVar, SuperArray, SyncArgs, ToRadians
big_eph, gridgen, jpl_body
PROCEDURE:
> The sky map is build from nRA*nDE line of sight integrations through the
F3D array. The locations in the sky of the lines of sight are
ra/Lng = (ra/Lng Sun) -180 + (360./nra)*[0.5, 1.5, .. , nra-0.5 ]
Decl./Lat = - 90 + (180./nde)*[0.5, 1.5, .. , nde-0.5 ]
Dist along los = drr*[0.5,1.5,...,nrr-1]
Note that each line of sight is centered on a 'box' of 360/nra by 180/nde
degrees, and that all lines of sight together cover the entire sky.
MODIFICATION HISTORY:
AUG-1999, Paul Hick (UCSD/CASS)
OCT-2004, Paul Hick (UCSD/CASS)
Added zero_shift keyword.
APR-2006, Paul Hick (UCSD/CASS)
Added keyword /longitudes (the previous version always returned
heliographic longitudes). Add option to explictly specify lines of sight
in RA,DEC after setting nRA*nDE=0.
FEB-2007, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Replaced keyword /longitudes by keyword /cv2carrington
Added _extra keyword to be able to pass one of the /to_* keywords
to CvSky. This allows the return value to be in any one of the
coordinates supported by CvSky (instead of just heliographic coordinates)
[Previous]
[Next]
NAME:
EarthTransit3DLoc
PURPOSE:
Provides 3D heliographic coordinates for all lines of sight used for a 'transit sweep' across the sky
CATEGORY:
WWW: skymap
CALLING SEQUENCE:
FUNCTION EarthTransit3DLoc, UT, $
cv2carrington=cv2carrington, $
nra = nra , $
nde = nde , $
nrr = nrr , $
drr = drr , $
equator = equator , $
degrees = degrees , $
band = band , $
solar = solar , $
geolng = geolng , $
ra = ra , $
dec = dec , $
zero_phase = zero_phase, $
zero_point = zero_point, $
rr_earth = rr_earth , $
ut_earth = ut_earth , $
pa_earth = pa_earth , $
elo_earth = elo_earth , $
elo_sun = elo_sun , $
_extra = _extra
INPUTS:
UT scalar; type: time structure
universal time, UT
(usually UT corresponding to local noon at geographic longitude 'geolng')
OPTIONAL INPUT PARAMETERS:
/degrees if set then all in- and ouput angles are in degrees (default: radians)
Four parameters define the grid used to calculate the sky map (see PROCEDURE)
nra scalar; type: int; default: 36
# points in skymap in longitudinal direction (either right ascensions
of ecliptic longitude). Note that nRA may be modified if keyword
band is used.
nde scalar; type: int; default: 18
# points in skymap in latitudinal direction(either declination or
ecliptic latitude)
nrr scalar; type: int; default: 20
# steps along lines of sight at each point in the sky
drr scalar; type: float; default: 0.1
step size along line of sight (AU)
geolng=geolng
scalar; type: any; default: 0
geographic longitude of observing location
/equator
by default the local meridian is set up as a strip of sky centered on the
intersection with the ecliptic. This results in a sweep with the Sun
centered, and the ecliptic along the horizontal axis (but see RESTRICTIONS).
If /equator is set then the strip of sky is centered on the equator, i.e.
the strip covers the local meridian from equatorial north to equatorial south.\
This is a more strict interpretation of the concept of a 'transit sweep', but
has the disadvantage that the Sun is not at the center of the sky map.
band scalar; type: float
Width of strip to be processed (in hours)
If band is not set then meridian strips covering 24 hours centered
around UT are selected. Use this keyword to extract only a partial strip
of sky covering less than 24 hour.
/solar by default the meridian strips are centered around the meridian strip at time UT.
Setting /solar rearranges the strips, putting the meridian strip at noon in
the center (see PROCEDURE)
/cv2carrington
OUTPUTS:
R array[3,nra,nde,nrr]; type: float
3D locations (in heliographic coordinates) where values need to obtained
by interpolation on the 3D arrays.
nra scalar; type: integer
if keyword band is set then nra is set to the number of meridians
inside the RA range of width 'band'.
OPTIONAL OUTPUT PARAMETERS:
ra array[nra]; type: float
Right ascension for nra UT times covering 24 hours centered on UT
dec array[nde]; type: float
dec = -pi/2+pi/nde*[0.5,1.5,...,nde-0.5]
ra and dec define a regular grid in sky coordinates for the centers of
the boxes for the lines of sight used to sweep of the sky
zero_point=zero_point
scalar; type: float
/solar NOT set: RA angle for local meridian at 'geoloc' on time UT
/solar set : RA angle of Sun at time UT
zero_phase=zero_phase
/solar NOT set:
scalar, type: float
RA angle for local meridian at 'geoloc' on time UT
(i.e. same as zero_point)
/solar set :
array[nra]; type: float
RA angles of Sun for nRA UT times covering 24 hours centered
on UT (same times as used for output array RA).
(i.e. 'zero_point' is approximately centered in 'zero_phase')
pa_earth=pa_earth
array[nra,nde,nrr]; type: float
line of sight position angle measured counterclockwise
from ecliptic north
elo_earth=elo_earth
array[nra,nde,nrr]; type: float
line of sight elongations: angle (Sun-Earth-los segment)
elo_sun=elo_sun array[nra,nde,nrr]; type: float
angle (Earth-Sun-los segment)
rr_earth=rr_earth
array[3,nra]; type: float
heliocentric locations Earth in heliographic coordinates
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
Carrington, CvPointOnLos, CvSky, InitVar, IsType, SuperArray, TimeGST, TimeOp, TimeSet
TimeUnit, ToRadians, big_eph, gridgen, jpl_body
CALLED BY:
vu_earthskymap
RESTRICTIONS:
If /equator is NOT set then the ecliptic is put on the horizontal axis. This is
done using a kludge. Each meridian strip (-90 to +90 degrees in declination with
the equator in the center, is shifted vertically to put the ecliptic in the center.
The sweep across the sky covers 24 hours in UT. Since UT is a solar time, the sweep covers
a little more than 360 degree of sky. However, the RA array still covers exactly 360
degrees (RA is passed to PlotEarthSkyMap to make a Hammer-Aitoff or fish-eye map).
PROCEDURE:
> UT is used to set up an array of nRA equally spaced times covering UT-12h to UT+12h
TT = UT+((0.5+findgen(nra))/nra-0.5)*(24)
(if 'band' is specified then only UT +/- band/2 is used).
> The geographic longitude, together with GST, is used to calculate the RA
of the local meridian (hour angle zero) at times TT
> At each ra(TT) value nde equally spaced declinations are taken
dec = ((0.5+findgen(nde))/nde-0.5)*90
> The resulting strips along the local meridian patched together give
a (partial) sweep of the sky. The return array RA is a monotonic increasing
array inside [-180,+180].
> If /solar is NOT set then the return array zero_phase contains the right ascension
of the local meridian at time UT.
If /solar is set then the return array zero_phase contains the right ascension of
the sun at the times centered on UT used also to calculate RA.
The scalar 'zero_point' and array 'zero_phase' are used to center the proper
RA in a skymap by subtracting it from RA.
> The output array rr_earth gives the location of Earth at times TT
MODIFICATION HISTORY:
SEP-1999, Paul Hick (UCSD/CASS)
FEB-2007, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Replaced keyword /longitudes by keyword /cv2carrington
Added _extra keyword to be able to pass one of the /to_* keywords
to CvSky. This allows the return value to be in any one of the
coordinates supported by CvSky (instead of just heliographic coordinates)