[Previous]
[Next]
NAME:
c1_wsmsmooth
CALLING SEQUENCE:
pro C1_WSMSMOOTH,imn=imn,imset=imset,img=img
CALLS: ***
WRITEFITS
[Previous]
[Next]
NAME:
c3_j15b0dif
CALLING SEQUENCE:
pro C3_j15b0dif,imn=imn,imset=imset,img=img
CALLS: ***
WRITEFITS
[Previous]
[Next]
NAME:
Carrington
PURPOSE:
Get times when Earth was at Carrington variable XC, and v.v
CALLING SEQUENCE:
FUNCTION Carrington, xc_or_t , $
fraction = fraction , $
longitude = longitude , $
rotation = rotation , $
get_fraction = get_fraction , $
get_longitude = get_longitude , $
get_rotation = get_rotation , $
get_time = get_time , $
get_variable = get_variable , $
near_longitude = near_longitude, $
degrees = degrees
INPUTS:
xc_or_t array; type: any numerical type
if input is a Carrington variable, the
return value is the corresponding UT time
array; type: standard time structure
if input is a UT time, the return value
is a Carrington variable.
OPTIONAL INPUTS:
/get_fraction return fraction of rotation
/get_longitude return heliographic longitude
/get_rotation return integer rotation number
/get_time always return UT time (even if input already
is a UT time)
/get_variable always return Carrington variable (even if
input already is a Carrington variable)
near_longitude=near_longitude
heliographic longitude in [0,360]
If specified this heliographic longitude is
translated into a Carrington variable within half
a rotation from input Carrington variable/time
xc_or_t. Note that the rules for the return value
are the same as without the near_longitude, i.e.
if xc_or_t is a Carrington variable then the
return value is a time structure, unless one of the
get_* keywords is set.
OUTPUTS:
Result If no /get_* keywords are set:
array; type: standard time structure
array; type: double
/get_fraction : fraction of rotation
/get_longitude: heliographic longitude
/get_rotation : integer Carrington rotation nr.
/get_time : UT time
/get_variable : Carrington variable
OPTIONAL OUTPUTS:
fraction=fraction
array; type: double
positive fraction of a rotation
longitude=longitude
array; type: double
heliographic longitude
rotation=rotation
array; type: integer
integer Carrington rotation number
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
AngleRange, CvSky, IsTime, IsType, SubArray, TimeArray, TimeOp, TimeOrigin, TimeSet
TimeUnit, ToRadians, jpl_eph
CALLED BY:
EarthSky3DLoc, EarthTransit3DLoc, InSitu, InterpolateHeliosphere
PlotSynopticMap, RemoteView_Init_View, TimeGet, TimeSet, forecast, forecast_ice
mk_celias, nso_fe_plot, qRemoteView_ChangeCoordinates, qRemoteView_ChangeTimes
qRemoteView_Pick, qRemoteView_Time, qvu_draw, qvu_pick, vu_atlocation
vu_coronagraph, vu_earthskymap, vu_elotime, vu_extract, vu_filename, vu_get_page
vu_getdata, vu_gettime, vu_image, vu_insitu, vu_insitu_raw, vu_insitucurve
vu_linecut, vu_localskymap, vu_losmap, vu_mean, vu_movie, vu_nagoyasourcemap
vu_new_time, vu_planarcut, vu_quick_movie, vu_radialcut, vu_remoteview, vu_select
vu_set, vu_set_time_entry, vu_solardisk, vu_spherecut, vu_synopticmap
vu_timeseries, vu_update_marker, vu_vox_write, vu_whatis
PROCEDURE:
An estimate for the Carrington start time is set up first.
This is iteratively refined.
If keyword near_longitude is defined then
the difference in longitude between near_longitude and
xc_or_t is calculated. If the difference is less than
-180 deg then 360 deg is added; if greater than 180 deg
then 360 deg is subtracted.
MODIFICATION HISTORY:
SEP-1999, Paul Hick (UCSD/CASS)
JAN-2004, Paul Hick (UCSD/CASS)
Substantial rewrite to improve precision from several
minutes to about a milli-second, and avoid calls to
CarringtonT0
APR-2004, Paul Hick (UCSD/CASS)
Added code to prevent iteration loop to get stuck in
infinite loop
JUN=2006, Paul Hick (UCSD/CASS)
Bug fix (du was subscripted with n instead of nn)
JUL-2007, Paul Hick (UCSD/CASS)
Merged carringtonvar, carringtont, carringtonlng,
carringtonnr and arg_time into this procedure.
Merged CarringtonNear by adding keyword near_longitude.
AUG-2007, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Removed calls to scearth.
[Previous]
[Next]
NAME:
CenterOfMass
PURPOSE:
Calculate center of mass of a distribution of masses in n dimensions
CATEGORY:
gen/idl/toolbox
CALLING SEQUENCE:
FUNCTION CenterOfMass, mass_array, loc_array
INPUTS:
mass_array array of any structure; type: integer or float
OPTIONAL INPUT PARAMETERS:
loc_array array[n, size(mass_array,/dim)]
i.e. same structure as mass_array with one extra
leading dimension
OUTPUTS:
P scalar, or array[n]; double precision
coordinates of center of mass. In the one-dimensional
case (n=1) a scalar is returned.
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
SubArray, SyncDims
CALLED BY:
even_light, qImage_cw_ZEllipse, qImage_cw_ZUpdate, wedge_content
SIDE EFFECTS:
The center of mass calculation is done in double precision.
PROCEDURE:
Two separate cases are calculated:
> 1. Only the mass_array is specified as an n-dimensional array.
The center of mass is returned as an n-element array (scalar if n=1).
The array index in each dimension is used as the distance scale:
mass_array = [[1,2],[3,4]]
P = centerofmass(mass_array)
results in
P = [0.6,0.7]
> 2. If both mass_array and loc_array are specified then loc_array, with
leading dimension of n elements, specifies the n-dimensional locations
of the masses in mass_array, e.g. in the 3-dimensional case, if mass_array
is a 10x10 array then loc_array would be a 3x10x10 array, with
loc_array[0,*,*] the x-coordinate, loc_array[1,*,*] the y-coordinate and
loc_array[2,*,*] the z-ccordinate.
The above example again:
mass_array = [1,2,3,4]
loc_array = [[0,0],[1,0],[0,1],[1,1]]
P = centerofmass(mass_array)
results in
P = [0.6,0.7]
MODIFICATION HISTORY:
NOV-1999, Paul Hick (UCSD/CASS)
FEB-2000, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
internally the procedure converts the mass array to a normalized mass by
dividing by the total mass. This results in a divide by zero if the sum is
zero (presumably because all masses are zero). To avoid this one unit is
added to each mass.
[Previous]
[Next]
NAME:
CheckDir
PURPOSE:
Check whether a directory exists
CATEGORY:
Environment
CALLING SEQUENCE:
FUNCTION CheckDir, Name, LongName, stay=stay, silent=silent
INPUTS:
Name scalar string, the directory name
Name='' always returns status=1B with
LongName set to the current directory.
OPTIONAL INPUT PARAMETERS:
/stay if set then a 'cd' to the directory is made (if it exists)
OUTPUTS:
Status 0 : directory doesn't exist
1 : directory exists
OPTIONAL OUTPUT PARAMETERS:
LongName scalar string
Status=0 : null string
Status=1 : fully qualified directory name
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
FindAllSubDirs, IDL_postop_win, IDL_vm_startup, RemoteView_Display2D
RemoteView_Display3D, SetFileSpec, clean_loc_smei, forecast_html, forecast_ice
forecast_info, getipssources, getnagoyasources, getootyasources, getsmeisources
hide_env, mk_flick, nagoya_glevel, qImage_cw_SmeiMask, qView_FileFilter, skyd_cat
skyd_version, smei_base_testcase, smei_buf, smei_buf_get, smei_buf_getframe
smei_buf_mget, smei_buf_prep, smei_filepath, smei_frm_cp, smei_frm_findpoint
smei_frm_summary, smei_frm_write, smei_getfile, smei_hdr_get, smei_hdr_make
smei_hdr_plot, smei_mkcal_auto, smei_mkmask, smei_mkorb, smei_mksidereal
smei_orbit_stats, smei_sky_track, smei_star_fitone, smei_star_remove
smei_www_skymaps, smei_zld_remove [1], smei_zld_remove [2], smeidb_mounted
tolowcase, unhide_env, vu_get_page, vu_image, vu_movie, vu_quick_movie, www_help
www_help_rsi
RESTRICTIONS:
> No attempt is made to pre-process the input directory name
(such as translation of logicals/env. variables, etc.)
CALLS: ***
FILEPATH, InitVar, hide_env, who_am_i
PROCEDURE:
> CD is used to decide whether a directory exists, and is
used to retrieve the full directory name.
> filepath is called to make sure a trailing (back)slash is appended on
Unix and Windows systems.
MODIFICATION HISTORY:
DEC-1997, Paul Hick
SEP-2002, Paul Hick (UCSD/CASS)
Return zero if input spec contains wildcard.
FEB-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added name of calling routine to informational message.
[Previous]
[Next]
NAME:
clean
CALLING SEQUENCE:
pro clean
INCLUDE:
@compile_opt.pro
CALLS: ***
FILEPATH, FindAllFiles, FindAllSubDirs, GetFileSpec, SetFileSpec, do_file
where_common
[Previous]
[Next]
NAME:
clean_loc_smei
PURPOSE:
Removes selected files from backup copy of the SMEI tree
(which is accessible by anonymous ftp)
CATEGORY:
smei/pro/main
CALLING SEQUENCE:
idl clean_loc_smei.pro
CALLS:
CheckDir, FindAllFiles, do_file, txt_read
PROCEDURE:
The backup copy is located in subdirectory loc_smei located
in the anon ftp root.
MODIFICATION HISTORY:
DEC-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
CleanGlitchBox
PURPOSE:
Given that a glitch has been detected (specified as a single pixel,
check a neighbourhood of the pixel to decide whether the glitch
covers more than one pixel.
CATEGORY:
Avoidable ?
CALLING SEQUENCE:
FUNCTION CleanGlitchBox, Frames, Loc, spotwidth=SpotWidth, frac=frac
INPUTS:
Frames 3D-array, any type (float or double needed to use NaN option)
stack of 2D frames combined in 3D array; the last dimension counts
the number of frames
Frame elements set to the value !VALUES.F_NAN or D_NAN are ignored
Loc 1-dim array, type long integer
location of pixels already identified as part of glitches
specified as 1-dim indices into the Frames array.
OPTIONAL INPUT PARAMETERS:
spotwidth=SpotWidth
scalar, integer, default=1
should be an odd integer.
defines a neighbourhood of SpotWidth x Spotwidth pixels
!! If SpotWidth is not defined the procedure simply
returns the input Loc array unmodified.
frac=frac scalar, any type, default=1
Used in the criterion for deciding whether a pixel is part of
a glitch or not. See PROCEDURE.
OUTPUTS:
nLoc scalar, long integer
# elements in Loc (=n_elements(Loc))
Loc 1-dim array, type long integer
location of the glitches as 1-dim indices into the Frames array
The array will contain all the input values. Added are all pixels
that are identified as part of the glitch
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
ArrayLocation, BadValue, UNIQ
CALLED BY:
Find2DGlitch
PROCEDURE:
For each element in the Loc array a box of SpotWidth x SpotWidth in the
appropriate frame is processed. Minimum and median in the box are calculated
excluding the center of the box.
The difference between median and minimum is used to identify other pixels
in the box which are considered part of the central glitch. Any pixel more
than frac*(median-minimum) above the median is considered part of the glitch.
MODIFICATION HISTORY:
OCT-1998, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
clock
PURPOSE:
Display time of day (including day of year (DOY) and Julian day number (JD)
CATEGORY:
Totally unnecessary
CALLING SEQUENCE:
PRO clock
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
TimeGet, TimeSet
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
CMRESTORE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Restore variables from an IDL SAVE file.
CALLING SEQUENCE: (various)
CMRESTORE, filename (implicit)
CMRESTORE, filename, var1, var2, ..., [, NAMES=names]
CMRESTORE, filename, DATA=pointers, NAMES=names, PASS_METHOD='POINTER'
CMRESTORE, filename, DATA=handles, NAMES=names, PASS_METHOD='HANDLE'
CMRESTORE, filename, DATA=structure, PASS_METHOD='STRUCT'
DESCRIPTION:
CMRESTORE is a replacement for the built-in IDL procedure RESTORE.
It restores variables and data from an existing IDL SAVE file,
written either by SAVE or CMSAVE. The CMSV utility library must
be installed in your IDL path to use CMSAVE and CMRESTORE.
The primary advantage to CMRESTORE is the ability to selectively
restore only certain variables from the input file (based on
name). CMRESTORE provides a number of ways to pass the data
between routines, typically using a pointer or structure, which
avoids the unsafe practice of restoring variables in the caller's
namespace. However, CMRESTORE can restore variables into the
caller's namespace, but users should be aware that this capacity
is somewhat limited in IDL versions 5.2 and below.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
COMPATIBILITY:
-- File Format --
CMRESTORE should be able to read files written by SAVE and CMSAVE
from IDL version 4 to version 5.4.
CMRESTORE cannot restore objects, pointers, compressed files, or
data sets larger than 2 gigabytes.
Data types available in newer versions of IDL, such as pointers
and long integers, will not be readable in older versions of IDL
which do not have those data types.
-- Calling Interface --
For the most part, all capabilities of CMRESTORE are available to
the user. However, it should be noted that passing variables by
positional parameter is not available under IDL 4, unless NAMES is
used to name the variables explicitly. Also, under IDL versions
5.2 and previous, it is not possible for CMRESTORE to restore
variables into the caller's name space if they are not yet
defined.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
FILENAME - the name of the SAVE file.
Default: none, this parameter must be specified.
VAR{i} - The values to be restored. By default the save name is
taken from the named variables that are passed. These
default names can be overridden by using the NAMES
keyword.
If no variables are passed as positional parameters, they
can still be saved using the DATA keyword. By invoking
CMRESTORE without positional parameters or DATA,
CMRESTORE automatically will attempt to restore the
variables to the calling routine's name space (the
"implicit" technique).
NOTE: in IDL 5.2 and below, user routines are not
allowed to *CREATE* new variables in the caller's name
space. CMRESTORE may fail if the variable in
undefined in the caller. Therefore you must define it
before calling CMRESTORE. The safer practice is to
use the VAR{i} positional parameters, or the DATA
keyword.
KEYWORDS:
FILENAME - the name of the SAVE file. The positional FILENAME
parameter takes precedence over the keyword FILENAME
parameter.
NOTE that if you pass variables as positional
parameters, then the first parameter *must* be the file
name, and the FILENAME *keyword* will be ignored.
PASS_METHOD - a scalar string, describing the method of passing
data between the caller and CMRESTORE. The keyword
can take the value 'ARGUMENT', 'POINTER', 'HANDLE'
or 'STRUCT'. A value of 'ARGUMENT' indicates that
data values will be passed by command line argument,
and is the default. Other values are described
below.
DATA - A list of data elements to be restored from the output
file. The data elements can be one of the following,
depending on the value of PASS_METHOD. The means of
extracting the data, and the method of naming each
variable, are also indicated.
* PASS_METHOD='POINTER': An array of pointers to the variables
Data: pointed-to value Name: from NAMES keyword
* PASS_METHOD='HANDLE': An array of handles to the variables
Data: pointed-to value Name: from NAMES keyword
* PASS_METHOD='STRUCT': A structure containing data to be saved
Data: tag value Name: tag name
Data values are restored one by one, using the appropriate
name. Note that any variables passed as positional
parameters will cause the DATA keyword to be ignored.
CMRESTORE will allocate any pointer or handle resources.
The calling routine is responsible for deallocating any
pointer or handle resources.
NAMES - a string array, giving the names for each variable.
If the data are passed by positional parameters, the names
are assigned according to the position of the parameter in
the procedure call.
If the data are passed by an array of pointers or handles,
then the names are assigned according to the position of
the data in the array. In this case there is no other way
to supply the variable name. NAMES is required.
If the data are passed in a structure, then the names are
assigned according to the position of the data in the
structure. The values specified in the names keyword
override the tag names.
STATUS - upon return, an integer indicating the status of the
operation. A value of 1 indicates success, while 0
indicates failure. A failure condition does not
necessarily indicate that an individual variable could
not be restored; use the VARSTATUS keyword to detect such
situations.
VARSTATUS - upon return, an integer array indicating the status of
the restore operation for each variable. A value of 1
at position i in the array indicates success for the
ith variable, while a value of 0 indicates failure.
ERRMSG - upon return, a string indicating the status of the
operation. The empty string indicates success, while a
non-empty string indicates failure and describes the
error condition.
QUIET - if set, then the error message is returned to the calling
routine. By default an error condition causes execution
to stop and the message to be printed on the console.
VERBOSE - if set, then a short message is printed for each
variable.
EXAMPLE:
CMSAVE, VAR1, VAR2, FILENAME='test.sav'
CMSAVE, VAR1, VAR2, FILENAME='test.sav', NAMES=['A','B']
Save the data in VAR1 and VAR2 to the file test.sav. In the
first case the saved variable names will be VAR1 and VAR2. In
the second case the saved variable names will be A and B.
POINTERS = [ptr_new(VAR1), ptr_new(VAR2)]
CMSAVE, DATA=POINTERS, NAMES=['A','B'], FILENAME='test.sav'
Save the data in VAR1 and VAR2 to the file test.sav. The saved
variable names will be A and B.
STRUCTURE = {A: VAR1, B: VAR2}
CMSAVE, DATA=STRUCTURE, FILENAME='test.sav'
Save the data in VAR1 and VAR2 to the file test.sav. The saved
variable names will be A and B.
CALLS: ***
ARG_PRESENT, CMSVLIB, CMSV_OPEN, CMSV_RDATA, CMSV_RREC, CMSV_RVTYPE
SEE ALSO:
CMSAVE, RESTORE, SAVE
MODIFICATION HISTORY:
Written, 14 May 2000
Documented, 22 Sep 2000
Restore into caller's name space now permitted, 11 Jan 2001
Documented "implicit" restore a little better, w/ errors, 01 Mar 2001
Make version checks with correct precision, 19 Jul 2001, CM
Restore with no args automatically does ALL, is this right?,
CM, 20 Aug 2001
Added notification about RSI License, 13 May 2002, CM
Handle the case of CMRESTORE, FILENAME, X properly, 03 Sep 2008, CM
(thanks to Sergey Koposov for reporting)
Report CMSVLIB version number when /VERBOSE is set, 22 Nov 2009,
CM
Change to accomodate lack of GDL functionality when restoring
all variables, 22 Nov 2009, CM
$Id: cmrestore.pro,v 1.22 2009/11/22 23:31:00 craigm Exp $
[Previous]
[Next]
NAME:
CMSAVE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Save IDL variables to a file. (IDL v5 and greater)
CALLING SEQUENCE: (various)
CMSAVE, var1, var2, ..., FILENAME=filename [, NAMES=names]
CMSAVE, DATA=pointers, NAMES=names, FILENAME=filename
CMSAVE, DATA=handles, NAMES=names, FILENAME=filename
CMSAVE, DATA=structure, FILENAME=filename
DESCRIPTION:
CMSAVE is a replacement for the built-in IDL procedure SAVE, with
more flexibility and increased capabilities.
CMSAVE produces output files that are compatible with the standard
save format of IDL versions 4 and 5 (and perhaps greater).
Variables may be restored by using either the built-in procedure
RESTORE, or CMRESTORE. The CMSV utility library must be installed
in your IDL path to use CMSAVE and CMRESTORE.
The primary advantages to CMSAVE are the ability to append
additional variables to an existing SAVE file, and several
flexible ways to pass the data and variable names to be saved.
CMSAVE also attempts to run on all IDL versions.
To append variables to an existing file, simply specify the APPEND
keyword, and the filename of an existing writable SAVE file.
Variables will be appended to the end of the file. It is possible
to append a variable with the same name as an existing variable in
a file. Both data values are stored in the file. However the
results upon restore are undefined. There is also a limitation
that only one series of heap values -- pointed-to data -- may be
saved in a file.
By the normal convention of the built-in SAVE command, both the
data and variable names to be saved are passed as parameters on
the command line. Each parameter must be a named variable; both
the name and value are saved.
This convention may be used in invoking CMSAVE as well. However,
in addition to passing the data by positional parameter, the user
can pass the data using the DATA keyword. If the DATA keyword is
used, then an array of pointers or handles may be passed, or a
structure of values may be passed. (see below) If both are
passed, then the positional parameters take precedence.
It is also possible to explicitly rename the saved variables: the
saved name does not need to be the name of the named variable.
Use the NAMES keyword to override the default name. By default
the name is drawn from any named variables, or from the structure
tag names if the DATA keyword is used with a structure. The NAMES
keyword takes precedence over these values. NOTE: Values passed
by pointer or handle are not named by default, and so will not be
saved unless the NAMES keyword is used.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
COMPATIBILITY:
-- File Format --
Files written by CMSAVE should be readable with all known versions
of IDL at the time of this writing (version 4 - version 5.4). It
is expected that this compatibility will persist.
CMSAVE cannot write objects, compressed files, or data sets larger
than 2 gigabytes.
Data types available in newer versions of IDL, such as pointers
and long integers, will not be readable in older versions of IDL
which do not have those data types.
-- Calling Interface --
For the most part, all capabilities of CMSAVE are available to the
user. However, it should be noted that passing variables by
positional parameter is not available under IDL 4, unless NAMES is
used to name the variables explicitly.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
VAR{i} - The variables to be saved. By default the save name is
taken from the named variables that are passed. These
default names can be overridden by using the NAMES
keyword.
Variables can also be specified by passing an array of
handles or pointers in the DATA keyword.
If no variables are passed as positional parameters or
using DATA, then CMSAVE will assume that *all* variables
at the caller's level should be saved (this is similar
behavior to the built-in SAVE routine). Note that system
variables cannot be saved with CMSAVE.
KEYWORDS:
ALL - for compatibility with the built-in SAVE routine. Ignored.
Note that CMSAVE cannot save system variables.
FILENAME - the name of the output file.
Default: 'cmsave.sav'
DATA - A list of data elements to be saved to the output file.
The data elements can be one of the following. The means
of extracting the data, and the method of naming each
variable, are also indicated.
* An array of pointers to the variables
Data: pointed-to value Name: from NAMES keyword
* An array of handles to the variables
Data: pointed-to value Name: from NAMES keyword
* A 1-element structure containing data to be saved.
Data: tag value Name: tag name
Data values are saved one by one, using the appropriate
name. Note that any variables passed as positional
parameters will cause the DATA keyword to be ignored.
The calling routine is responsible for deallocating any
pointer or handle resources.
COMPATIBILITY - a string, which describes the format to be used in
the output file. Possible values are:
'IDL4' - format of IDL version 4;
'IDL5' - format of IDL versions 5.0-5.3;
'IDL6' - not supported yet, for versions 5.4-above;
'RIVAL1' - same as 'IDL5', plus a directory entry is
written to the file.
Note that files written in IDL5 format may still be
readable by IDL v.4.
Default: 'IDL5'
NAMES - a string array, giving the names for each variable.
If the data are passed by positional parameters, the names
are assigned according to the position of the parameter in
the procedure call. This can be especially useful to
rename local variables, and to give names to expressions.
If the data are passed by an array of pointers or handles,
then the names are assigned according to the position of
the data in the array. In this case there is no other way
to supply the variable name. NAMES is required.
If the data are passed in a structure, then the names are
assigned according to the position of the data in the
structure. The NAMES keyword values override the tag
names.
APPEND - if set, then the specified variables are appended to an
existing file.
Repeated variables will not cause an error, however they
may not be restored properly using the built-in RESTORE
procedure. It may also not be permitted to append
variables that contain heap pointers, to a save file
which already contains heap data.
STATUS - upon return, an integer indicating the status of the
operation. A value of 1 indicates success, while 0
indicates failure. A failure condition does not
necessarily indicate that an individual variable could
not be written; use the VARSTATUS keyword to detect such
situations.
VARSTATUS - upon return, an integer array indicating the status of
the save operation for each variable. A value of 1 at
position i in the array indicates success for the ith
variable, while a value of 0 indicates failure.
ERRMSG - upon return, a string indicating the status of the
operation. The empty string indicates success, while a
non-empty string indicates failure and describes the
error condition.
QUIET - if set, then the error message is returned to the calling
routine. By default an error condition causes execution
to stop and the message to be printed on the console.
VERBOSE - if set, then a short message is printed for each
variable.
XDR - for compatibility with the built-in SAVE routine. Ignored.
EXAMPLE:
CMSAVE, VAR1, VAR2, FILENAME='test.sav'
CMSAVE, VAR1, VAR2, FILENAME='test.sav', NAMES=['A','B']
Save the data in VAR1 and VAR2 to the file test.sav. In the
first case the saved variable names will be VAR1 and VAR2. In
the second case the saved variable names will be A and B.
POINTERS = [ptr_new(VAR1), ptr_new(VAR2)]
CMSAVE, DATA=POINTERS, NAMES=['A','B'], FILENAME='test.sav'
Save the data in VAR1 and VAR2 to the file test.sav. The saved
variable names will be A and B. Data are passed by pointer.
STRUCTURE = {A: VAR1, B: VAR2}
CMSAVE, DATA=STRUCTURE, FILENAME='test.sav'
Save the data in VAR1 and VAR2 to the file test.sav. The saved
variable names will be A and B. Data are passed by structure.
CALLS: ***
CMSAVE_HANDLE_VALUE, CMSVLIB, CMSV_OPEN, CMSV_PTRSUM, CMSV_RREC, CMSV_RVTYPE
CMSV_WREC, HELPFORM, RSTRPOS, TAGSIZE, UNIQ
SEE ALSO:
CMRESTORE, CMSVLIB, RESTORE, SAVE
MODIFICATION HISTORY:
Written, 14 May 2000
Documented, 22 Sep 2000
Made "more" compatible with SAVE; additional documentation, 11 Jan
2001, CM
Make version checks with correct precision, 19 Jul 2001, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsave.pro,v 1.16 2009/11/22 23:26:19 craigm Exp $
[Previous]
[Next]
NAME:
CMSAVEDIR
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Display a directory of the variables in an IDL SAVE file.
CALLING SEQUENCE:
CMSAVEDIR, filename [, /VERBOSE, /QUIET, ... ]
DESCRIPTION:
CMSAVEDIR will display a listing of the variables and other
objects stored in an IDL SAVE file.
For command-line users the primary function of CMSAVEDIR will be
to find out what data is stored in a file and when it was saved.
For that, they simply need to type: CMSAVEDIR, 'myfile.sav'
CMSAVEDIR also offers a number of features for programmers.
CMSAVEDIR essentially interrogates the save file and discovers the
numbers, names and types of each of the variables stored in the
file. Programmers can use that information to decide whether or
how to open a file using the other routines in the CMSVLIB.
Various keyword parameters are used return this information, as
documented below.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
COMPATIBILITY:
-- File Format --
CMSAVEDIR cannot examine compressed save files, or files larger
than 2 gigabytes.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
FILENAME - a scalar string, the name of the file to be examined.
KEYWORDS:
VERBOSE - if set, print more detailed information about the input file.
QUIET - if set, then do not print any output. Programmers can use
this keyword to allow CMSAVEDIR to return information
about the file silently.
STATUS - upon output, 1 for success, otherwise to indicate
failure.
ERRMSG - upon output, if a failure occurs, a message describing
the error condition.
N_VARIABLES - upon output, the number of variables in the file.
VAR_NAMES - upon output, contains a string array of the names of
the variables stored in the file.
TYPES - upon output, an 11xN_VARIABLES array containing the SIZE
information of each variable in the file.
N_PRO - upon output, the number of procedures stored in the file.
PRO_NAMES - upon output, the names of the procedures stored in the
file, as a string array.
N_FUNCTION - upon output, the number of functions stored in the
file.
FUNC_NAMES - upon output, the names of the functions stored in the
file, as a string array.
NAMED_STRUCTS - upon output, a string array listing any named
structures which appear in the SAVE file.
NAMED_CLASSES - upon output, a string array listing any named
class structures which appear in the SAVE file.
TIMESTAMP - upon output, contains the timestamp record information
in a structure. The fields of the structure are:
SAVE_DATE - string - date saved
SAVE_USER - string - user who saved file
SAVE_HOST - string - host name on which file
saved
VERSION - upon output, contains the version record information in
a structure. The fields of the structure are:
FORMAT_VERSION - integer - major format version
ARCH - string - saving host's !VERSION.ARCH
OS - string - saving host's !VERSION.OS
RELEASE - string - saving host's !VERSION.RELEASE
NOTICE - upon output, contains any textual notice included within
the file. The fields of the structure are:
TEXT - string - text of the notice
FORCE - if set, will force CMSAVEDIR to open the file even if it
detects a potential incompatibility.
EXAMPLE:
IDL> cmsavedir, 'int_str_intarr.sav'
** int_str_intarr.sav
** Sun Apr 9 20:28:25 2000 (craigm@beach.gsfc.nasa.gov)
** IDL v5.2 (linux)
A INT = 0
B STRING = 'hello'
C INT = Array[3]
** 3 variable(s), 0 heap value(s) and 0 procedure(s) in 1376 bytes
CALLS: ***
BINARYFORM_LONG, CMSVLIB, CMSV_OPEN, CMSV_RDATA, CMSV_RRAW, CMSV_RREC, CMSV_RVTYPE
HELPFORM
SEE ALSO:
CMRESTORE, CMSAVE, CMSVLIB, RESTORE, SAVE
MODIFICATION HISTORY:
Documented, 12 Jan 2001, CM
Added USAGE message, 09 Jun 2001, CM
Fixed bug in printing common variables, 17 Mar 2002, CM
Added notification about RSI License, 13 May 2002, CM
Added NOTICE record type, 09 Jun 2003, CM
$Id: cmsavedir.pro,v 1.17 2003/06/28 22:21:07 craigm Exp $
[Previous]
[Next]
NAME:
CMSV_OPEN
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Open IDL SAVE file for reading or writing
CALLING SEQUENCE:
CMSV_OPEN, UNIT, FILENAME, OFFSET, $
ACCESS=ACCESS, /FORCE, /GET_LUN, /REOPEN, $
COMPATIBILITY=COMPATIBILITY, $
STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
CMSV_OPEN opens an IDL SAVE-formatted file for reading or writing.
The mode of operation is controlled by the ACCESS keyword, which
may be either 'R' for reading, 'W' for writing, or 'RW' for
read/write access.
'R': In the case of reading, the specified file is opened with
read-only access, and the first bytes are examined to verify that
it is indeed a valid IDL SAVE file.
'W': In the case of writing, the specified file is opened with
write access, and the initial file signature is written.
'RW': In the case of read-write access, the file must already
exist as a valid SAVE file. Users are advised that every time
they switch between reading and writing operations, they must use
POINT_LUN to flush the file buffers.
The CMSVLIB routines do not support file sizes greater than 2 GB,
nor SAVE files created with the COMPRESS option.
Upon return, the file pointer is positioned at the start of the
first valid SAVE record. The file offset is returned in OFFSET.
The user is responsible for reading or writing the remainder of
the file with other library routines.
The file unit is determined based on the following criteria. This
behavior is similar to the OPEN family of procedures, except for
the REOPEN keyword.
* If REOPEN is set then it is assumed that UNIT is an
already-open file, and FILENAME is ignored.
* If GET_LUN is set then a file unit is allocated with GET_LUN,
and upon success this unit is returned in UNIT.
* Otherwise it is asssumed that UNIT is a valid but unopened
file unit. Upon successful return, UNIT is opened.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
UNIT - a logical unit number (a scalar). In the case of GET_LUN,
a file unit will be allocated and returned in UNIT. In the
default case, or REOPEN, UNIT must be a valid file unit
upon input. For REOPEN the corresponding file must be
seekable.
FILENAME - a scalar string specifying the filename path (ignored
for REOPEN).
OFFSET - upon return, the file offset of the next available SAVE
record.
KEYWORDS:
ACCESS - a scalar string, case insensitive:
'R' - read-only access
'W' - write access (new file)
'RW' - read-write access (existing file)
Default: 'R' - read-only
GET_LUN - if set, the file unit is allocated using GET_LUN
FORCE - if set, then the file is opened despite a detected file
format inconsistency.
REOPEN - if set, then an already-opened file is manipulated. The
valid file unit must be specified by UNIT, and FILENAME
is ignored.
COMPATIBILITY - a string, which describes the format to be used in
the output file. Possible values are:
'IDL4' - format of IDL version 4;
'IDL5' - format of IDL versions 5.0-5.3;
'IDL6' - not supported yet, for versions 5.4-above;
'RIVAL1' - same as 'IDL5', plus a directory entry is
written to the file.
Note that files written in IDL5 format may still be
readable by IDL v.4.
Default: 'IDL5'
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
CALLED BY:
CMRESTORE, CMSAVE, CMSAVEDIR, CMSVLIB, CMSVREAD, CMSVWRITE
EXAMPLE:
SEE ALSO:
CMRESTORE, CMSVLIB, RESTORE, SAVE
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Change BLOCK to STREAM to support VMS properly, 14 Feb 2001, CM
Added notification about RSI License, 13 May 2002, CM
NOTE: remember to modify CMSVLIB.PRO when changing library!
$Id: cmsv_open.pro,v 1.13 2009/11/22 22:50:49 craigm Exp $
[Previous]
[Next]
NAME:
CMSV_PTRSUM
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Construct an inventory of heap data accessible to a variable
CALLING SEQUENCE:
CMSV_PTRSUM, VAR, LIST
DESCRIPTION:
This procedure constructs an inventory of heap data that is
accessible to a single variable. It searches all array elements,
recursively through structure tags, and by dereferencing pointers.
Users can use this procedure to determine all heap variables that
need to be saved to disk.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
VAR - the variable to be examined
LIST - upon output, an array of pointers, each of which points to
a heap variable accessible to VAR. If there are no heap
data pointed to by VAR, then LIST returns a NULL value.
KEYWORDS:
NULL - if set, return the null value in LIST instead of the
pointer list. VAR is ignored.
HAS_OBJECTS - upon return, the value is 1 if VAR contains or
points to an object reference, and 0 if not.
CALLED BY:
CMSAVE, CMSVWRITE
EXAMPLE:
CALLS: ***
UNIQ
SEE ALSO:
CMRESTORE, CMSVLIB, RESTORE, SAVE
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Make version checks with correct precision, 19 Jul 2001, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_ptrsum.pro,v 1.7 2002/05/13 06:41:10 craigm Exp $
[Previous]
[Next]
NAME:
CMSV_RDATA
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Read SAVE-formatted data variable record from input block or file unit
CALLING SEQUENCE:
CMSV_RDATA, BLOCK, POINTER, SIZE, DATA, UNIT=UNIT, $
TEMPLATE=TEMPLATE, /TEMPORARY, PTR_INDEX=PTR_INDEX, $
PTR_CALLBACK=PTR_CALLBACK, PTR_OFFSETS=PTR_OFFSETS, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
CMSV_RDATA reads the data portion of an IDL SAVE variable record.
An IDL variable is stored in two components: the type descriptor
which describes the name, type, and dimensions of the variable;
and the data record, which contains the raw data of the variable.
This procedure reads the raw data and returns it to the user. The
initial type portion of the record must have already been read
using the CMSV_RVTYPE procedure.
CMSV_RDATA supports the following variable types:
BYTE(1),INT(2),LONG(3) - integer types
UINT(12),ULONG(13),LONG64(14),ULONG64(15) - integer types (IDL >5.2 only)
FLOAT(4),DOUBLE(5),COMPLEX(6),DCOMPLEX(9) - float types
STRING(7) - string type
STRUCT(8) - structure type
POINTER(10) - pointer type - SEE BELOW
NOT SUPPORTED - OBJ(11) - object reference type - NOT SUPPORTED
Arrays and structures containing any of the supported types are
supported (including structures within structures).
For scalars and arrays of numeric or string types, the caller must
only supply the SIZE parameter, which specifies the type and
dimensions of the variable to be read. This information can be
obtained from the CMSV_RVTYPE routine. The data is returned in the
output parameter DATA.
For structure data, in addition to specifying the SIZE array, the
user must also supply a "template" describing the structure into
which the data will be read. This template is simply a "blank"
form of the data structure, and is returned by CMSV_RVTYPE.
Thus, a simple way to read structure, numeric or string data is
the following code (with error checking removed)
CMSV_RVTYPE, block, pointer, name, size, template=template, unit=unit
CMSV_RDATA, block, pointer, size, data, template=template, unit=unit
[ This code assumes the record header has been read with
CMSV_RREC. ]
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
POINTER DATA
Pointer data stored in IDL SAVE files are particularly difficult
to manage, because the actual heap variables are stored in
separate records which *precede* the record of interest. Thus, if
your application requires the reading of pointer data, you must
perform special processing in your own code in order to support
it. In essence, you must maintain an inventory of heap variables
as they are encountered in the file.
If these procedures are not followed then pointer data will not be
read, and a LONG integer value appears in the pointers' places.
Under IDL 4, pointer data can never be read.
This is accomplished by placing some additional logic in your file
processing loop. There are four separate components to this: (1)
loop initialization; (2) reading a HEAP_INDEX record; (3) parsing
a HEAP_DATA record; and (4) passing extra arguments to CMSV_RDATA.
The additional state information is maintained in two variables
named PTR_INDEX, which keeps track of the heap variable numbers,
and PTR_OFFSETS, which stores the file location of each variable.
(1) Loop initialization: is quite simple, use the following code:
ptr_index = [0L]
ptr_offsets = [0L]
ptr_data = [ptr_new()]
(2) Reading HEAP_INDEX, which is an array of values indicating
the heap variable numbers of each heap variables. These
values are stored in PTR_INDEX:
CMSV_RHEAP, block, pointer, index, unit=unit
ptr_index = [ptr_index, index]
ptr_offsets = [ptr_offsets, lonarr(n_elements(index))]
ptr_data = [ptr_data, ptrarr(n_elements(index))]
(3) Parse the HEAP_DATA record. Here were are interested in the
heap variable number, and the file offset.
opointer = pointer
CMSV_RVTYPE, block, pointer, vindex, /heap, unit=unit
vindex = floor(vindex(0))
wh = where(ptr_index EQ vindex)
ptr_offsets(wh(0)) = offset + opointer
Keep in mind that the file offset is OFFSET+POINTER.
(4) Pass extra parameters to CMSV_RDATA. The user simply passes
these extra variables to the CMSV_RDATA procedure, which
automatically recognizes heap data and reads it from the
appropriate location.
CMSV_RVTYPE, block, pointer, name, size, unit=unit, template=tp
CMSV_RDATA, block, pointer, size, data, template=tp, $
unit=unit, ptr_offsets=ptr_offsets, $
ptr_index=ptr_index, ptr_data=ptr_data
If this technique is used properly, only those heap variables
which are needed are read. Thus, there are never any lost or
dangling pointers. Since each bit of heap data is stored in a
variable returned to the user, it is not necessary to
PTR_FREE(ptr_data); in fact, doing so would corrupt the input
data.
BLOCK, POINTER, OFFSET
This procedure can read data from a byte array, a file unit, or
both. In fact, this procedure is designed to implement "lazy"
reading from a file, which is to say, it normally reads from a
byte array of data. However, if the requested data goes beyond
the end of the byte array, more data is read from the file on
demand. This way the user gets the benefit of fast memory access
for small reads, but guaranteed file access for large reads.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
SIZE - an array of integers describing the type and dimensions of
the variable to be read, in the format returned by the
SIZE() routine. This parameter is required.
DATA - upon output, the data variable. If any heap data is read,
the user is ultimately responsible for freeing it.
KEYWORDS:
UNIT - a file unit. If a library routine reads to the end of
BLOCK, or if BLOCK is undefined, then this file UNIT will
be accessed for more data. If undefined, then BLOCK must
contain the entire file in memory.
TEMPLATE - for structure data (data type 8), a "blank" structure
containing the fields and data values to be read in.
This structure is returned by CMSV_RVTYPE.
This keyword is mandatory for structure data.
TEMPORARY - if set, BLOCK becomes undefined upon return.
PTR_OFFSETS - array of file offsets, as described above. Default:
pointer data is converted to an integer.
PTR_INDEX - array of heap variable indices, as described above.
Default: pointer data is converted to an integer.
PTR_DATA - array of pointers, as described above.
Default: pointer data is converted to an integer.
OFFSET - the file offset of byte zero of BLOCK. Default: 0
(OFFSET is used by this routine)
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
CALLED BY:
CMRESTORE, CMSAVEDIR, CMSVREAD
EXAMPLE:
SEE ALSO:
CMRESTORE, CMSVLIB, RESTORE, SAVE
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added UNDEFINED data type for IDL >5.3, CM, 21 Apr 2001
Fixed bug for pointers within structures, CM, 21 Apr 2001
Add support for IDL 4 byte-compiled strings, CM, 22 Apr 2001
Make version checks with correct precision, 19 Jul 2001, CM
Added notification about RSI License, 13 May 2002, CM
Clarify and speed some of the code, 22 Nov 2009, CM
NOTE: remember to modify CMSVLIB.PRO when changing library!
$Id: cmsv_rdata.pro,v 1.11 2009/11/22 23:04:43 craigm Exp $
[Previous]
[Next]
NAME:
CMSV_RRAW
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Read raw SAVE data from input block or file unit
CALLING SEQUENCE:
DATA = CMSV_RRAW( BLOCK, POINTER, NELT, UNIT=UNIT, $
STRING=STRING, LONG=LONG, BYTE=BYTE, TYPE=TYPE, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG )
DESCRIPTION:
This function reads raw integer or string data from an IDL SAVE
file. This is the lowest level reading function in the library,
intended for developers who are investigating new and existing
SAVE file formats.
The primary use of this function will be to read raw integer and
string data from the input. By default, a single value is read as
a scalar; however a vector of values can be read using the NELT
parameter. Special keywords are provided for the common data
types STRING, LONG and BYTE. Other integer types can be read
using the TYPE keyword. Users who want to read the data from an
IDL variable should use CMSV_RDATA, which can handle
multidimensional data, as well as floating point and structure
data.
A secondary use of this function is to buffer the data in BLOCK.
This will ensure that BLOCK contains enough data to convert NELT
integers without reading from disk. CMSV_RRAW itself does not
convert any values so the return value should be ignored.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
BLOCK, POINTER, OFFSET
This procedure can read data from a byte array, a file unit, or
both. In fact, this procedure is designed to implement "lazy"
reading from a file, which is to say, it normally reads from a
byte array of data. However, if the requested data goes beyond
the end of the byte array, more data is read from the file on
demand. This way the user gets the benefit of fast memory access
for small reads, but guaranteed file access for large reads.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
NELT - optional parameter specifying the number of values to read.
If unspecified, then a scalar value is read and returned.
If specified, then a vector of NELT values is read and
returned.
KEYWORDS:
BUFFER - if set, CMSV_RRAW will ensure that BLOCK contains at
least NELT values without converting them. The return
value should be ignored. This keyword is ignored for
strings.
LONG - if set, the values are converted as LONG integers.
BYTE - if set, the values are converted as BYTEs.
STRING - if set, the values are converted as STRINGs. Each string
may be of variable length.
TYPE - if none of the above keywords is set, then values of type
TYPE are read. TYPE should be a string, one of 'BYTE',
'FIX', 'LONG', 'ULONG', 'LONG64', or 'ULONG64'.
If no type is specified then BYTEs are read.
UNIT - a file unit. If a library routine reads to the end of
BLOCK, or if BLOCK is undefined, then this file UNIT will
be accessed for more data. If undefined, then BLOCK must
contain the entire file in memory.
OFFSET - the file offset of byte zero of BLOCK. Default: 0
(OFFSET is used by this routine)
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
CALLED BY:
CMSAVEDIR, CMSVLIB, CMSV_RREC
EXAMPLE:
SEE ALSO:
CMRESTORE, CMSVLIB, RESTORE, SAVE
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
NOTE: remember to modify CMSVLIB.PRO when changing library!
$Id: cmsv_rraw.pro,v 1.7 2009/11/22 22:50:49 craigm Exp $
[Previous]
[Next]
NAME:
CMSV_RREC
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Read SAVE-formatted record header from input block or file unit
CALLING SEQUENCE:
CMSV_RREC, BLOCK, POINTER, DATA, UNIT=UNIT, $
BLOCK_TYPE=BLOCK_TYPE, BLOCK_NAME=BLOCK_NAME, NEXT_BLOCK=NEXT_BLOCK, $
INITIALIZE=INITIALIZE, FULL=FULL, PROMOTE64=PROMOTE64, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
This procedure reads the header of an IDL SAVE record. The header
consists of four bytes at the beginning of each record which
indentifies the type and size of the record. This procedure also
additionally reads many full records as noted below.
Users can determine the block type by examining the values
returned in the BLOCK_TYPE and BLOCK_NAME keywords. The following
values are supported. Some record types contain additional data.
CMSV_RREC reads some of these record types automatically (those
entries below marked with [this procedure]). Other records do not
contain any additional data at all (those entries marked with an
[empty]), and thus require no further processing.
BLOCK_TYPE BLOCK_TYPE READ RECORD DATA WITH...
0 = 'START_MARKER' [empty]
1 = 'COMMON_BLOCK' [this procedure]
2 = 'VARIABLE' CMSV_RVTYPE / CMSV_RDATA
3 = 'SYSTEM_VARIABLE' CMSV_RVTYPE / CMSV_RDATA
6 = 'END_MARKER' [empty]
10 = 'TIMESTAMP' [this procedure]
12 = 'COMPILED' no published procedure
13 = 'IDENTIFICATION' [this procedure]
14 = 'VERSION' [this procedure]
15 = 'HEAP_INDEX' [this procedure]
16 = 'HEAP_DATA' CMSV_RVTYPE
17 = 'PROMOTE64' [empty]
19 = 'NOTICE' [this procedure]
For records that contain variable data, the external procedures
CMSV_RVTYPE and CMSV_RDATA must be used, as noted above.
Otherwise CMSV_RREC will read and convert the appropriate data
automatically and return it in the DATA positional parameter.
The offset of the next record is returned in the NEXT_BLOCK
keyword. For file input, the command, "POINT_LUN, UNIT,
NEXT_BLOCK" will position the file pointer to the next block.
Users should be aware that the SAVE files produced by IDL version
5.4 appear to have a different header format. The new header size
is five bytes, and is incompatible with the older format. In
order to activate the longer header size, the PROMOTE64 keyword
must be set.
By default the entire record is not read from the file at once.
Users that wish to operate on the entire record immediately should
set the FULL keyword.
After issuing a POINT_LUN the block cache in BLOCK must be reset
using the /INITIALIZE keyword.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
SPECIFIC RECORD TYPES
CMSV_RREC reads certain specific record types automatically and
returns the data in the positional parameter data. Users should
pass a named variable in this parameter to retrieve the return
value.
When a record of type 'VERSION' (14) is encountered, it is read,
and returned as a structure. The returned data are of the form:
{ FORMAT_VERSION: 0L, $ ; Format version number of file
ARCH: '', $ ; !VERSION.ARCH of creating host
OS: '', $ ; !VERSION.OS of creating host
RELEASE: '' } ; !VERSION.RELEASE of creating host
When a record of type 'TIMESTAMP' (10) is encountered, it is read,
and returned as a structure. The returned data are of the form:
{ SAVE_DATE: '', $ ; Date the save file was created
SAVE_USER: '', $ ; User name who created file
SAVE_HOST: '' } ; Host name that created file
Save files created by IDL version 4 do not contain a timestamp
record.
When a record of type 'IDENTIFICATION' (13) is encountered, it is
read, and returned as a structure. The returned data are of the
form:
{ AUTHOR: '', $ ; Author of SAVE file
TITLE: '', $ ; Title of SAVE file
IDCODE: '' } ; Identifying code for SAVE file
It appears that this record is not used in IDL version 5 or later.
When a record of type 'COMMON_BLOCK' (1) is encountered, it is
read and returned. A common block descriptor consists of an array
of strings whose first element is the common block name, and whose
remaining elements are the common block variable names. No
variable data are stored with the common block definition.
When a record of type 'HEAP_INDEX' (15) is encountered, it is read
and returned in DATA. The heap index specifies a list of which
heap variables are stored in the current save file. These indices
are simply numbers which identify each heap variable (i.e.,
"<PtrHeapVar2>" would have an index of 2). Users should note that
the heap index will not necessarily be sequentially increasing,
and may have gaps.
When a record of type 'NOTICE' (19) is encountered, it is read and
returned in DATA. It is a structure with one field: {TEXT: ''},
where TEXT is the text content of the notice.
Users should consult CMSV_RDATA for instructions on how to read
heap data.
BLOCK, POINTER, OFFSET
This procedure can read data from a byte array, a file unit, or
both. In fact, this procedure is designed to implement "lazy"
reading from a file, which is to say, it normally reads from a
byte array of data. However, if the requested data goes beyond
the end of the byte array, more data is read from the file on
demand. This way the user gets the benefit of fast memory access
for small reads, but guaranteed file access for large reads.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
KEYWORDS:
UNIT - a file unit. If a library routine reads to the end of
BLOCK, or if BLOCK is undefined, then this file UNIT will
be accessed for more data. If undefined, then BLOCK must
contain the entire file in memory.
OFFSET - the file offset of byte zero of BLOCK. Default: 0
(OFFSET is used by this routine)
BLOCK_TYPE - upon return, the numeric record type, as described
above.
BLOCK_NAME - upon return, a scalar string specifying the record
type, as specified above.
NEXT_BLOCK - upon return, file offset of the next record in the
file.
INITIALIZE - if set, then BLOCK and POINTER are initialized to a
pristine state. All data in these two variables is
lost before reading the next record.
FULL - if set, then the entire record will be read into BLOCK.
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
CALLED BY:
CMRESTORE, CMSAVE, CMSAVEDIR, CMSVREAD, CMSV_WREC
EXAMPLE:
CALLS: ***
CMSV_RCOMM, CMSV_RHEAP, CMSV_RIDENT, CMSV_RNOTICE, CMSV_RRAW, CMSV_RSTAMP
CMSV_RVERSION
SEE ALSO:
CMRESTORE, CMSVLIB, RESTORE, SAVE
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Fix typo for RHEAP call, CM, 21 Apr 2001
Added notification about RSI License, 13 May 2002, CM
Added NOTICE record type, 09 Jun 2003, CM
Read record header as ULONG, 26 Sep 2009, CM
Bug fix to previous change, 22 Nov 2009, CM
Support for newer IDL 64-bit files which use a
"standard" record header size and a previously unused
field, 11 Jan 2010, CM
NOTE: remember to modify CMSVLIB.PRO when changing library!
$Id: cmsv_rrec.pro,v 1.15 2010/01/11 08:58:13 craigm Exp $
[Previous]
[Next]
NAME:
CMSV_RVTYPE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Read variable type information from input block or file unit
CALLING SEQUENCE:
CMSV_RVTYPE, BLOCK, POINTER, NAME, SIZE, UNIT=UNIT, $
TEMPLATE=TEMPLATE, SUFFIX=SUFFIX, $
/NO_CREATE, /NO_TYPE, /HEAP, /SYSTEM, $
STRUCTURE_NAME=STNAME, $
NAMED_STRUCTS=STRUCTS, NAMED_CLASSES=CLASSES, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
CMSV_RVTYPE reads the type portion of an IDL SAVE variable record.
An IDL variable is stored in two components: the type descriptor
which describes the name, type, and dimensions of the variable;
and the data record, which contains the raw data of the variable.
This procedure reads the type descriptor returns it to the user.
This procedure can also determine the name of a variable; the heap
index number of a heap variable; and other important information.
Once the type of the data has been determined, the data portion
can be read using the CMSV_RDATA procedure.
CMSV_RVTYPE should recognize and correctly return type descriptor
information about all known IDL data types, as of this writing.
It should be noted that CMSV_RDATA will not necessarily be capable
of reading all of these data types, but the description of the
data should still be readable. Users can then use this
information to print a summary of the file contents for example.
The type information are normally returned in the SIZE parameter,
which gives the IDL variable type, and the dimensions of the
variable just as the IDL built-in function SIZE() would do.
However, in the case of structures, there is much more information
to convey. To assist the user a blank template structure is
returned in the keyword parameter TEMPLATE, which they can then
pass on to CMSV_RDATA.
Users should be aware of structure and class name clashes. The
problem arises because CMSV_RVTYPE must actually instantiate any
named structures or classes in the file. If these named
structures clash with the definitions of the structures on the
user's local computer, then an error will result. To prevent
this, the user can use the SUFFIX keyword. If the SUFFIX keyword
contains a string, then this string is appended to any structure
names discovered in the save file, before instantiation. Thus, as
long as the suffix is a unique string, there will be no clashes
with local structure definitions. Users are advised to pick a
different suffix for *each* save file that they open.
CMSV_RVTYPE also provides some diagnostic information about the
variable. Users can pass the NAMED_STRUCTS and NAMED_CLASSES
keywords in order to discover what named structures, classes and
superclasses are stored in the save file (this is especially
useful with the NO_TYPE keyword). Since the contents of
NAMED_STRUCTS and NAMED_CLASSES are not destroyed, but appended to
instead, users are advised to clear these variables when opening
each new file.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
BLOCK, POINTER, OFFSET
This procedure can read data from a byte array, a file unit, or
both. In fact, this procedure is designed to implement "lazy"
reading from a file, which is to say, it normally reads from a
byte array of data. However, if the requested data goes beyond
the end of the byte array, more data is read from the file on
demand. This way the user gets the benefit of fast memory access
for small reads, but guaranteed file access for large reads.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
NAME - upon return, the identifier of the variable. For named
variables, NAME is a string. For heap variables, NAME is
an integer heap index.
SIZE - upon return, an integers array describing the variable type
and size, in the same format as returned by the built-in
function SIZE.
KEYWORDS:
TEMPLATE - upon return, if the variable is a structure, TEMPLATE
will contain a single blank template structure, which
can be used in calls to CMSV_RDATA.
NO_CREATE - if set, then do not create any template structures
(saves execution time and structure name clashes).
NO_TYPE - if set, do not read type information. CMSV_RVTYPE
returns only the variable NAME or heap index.
HEAP - if set, then read the variable type assuming it is a heap
variable (a HEAP_DATA record).
SYSTEM - if set, then read the variable type assuming it is a
system variable (a SYSTEM_VARIABLE record).
SUFFIX - a scalar string, the suffix to be appended to any
structure names to force them to be unique.
STRUCTURE_NAME - upon return, if the variable is a named
structure, STRUCTURE_NAME will contain the name
of the structure as a string.
NAMED_CLASSES /
NAMED_STRUCTS - upon input, this keyword should contain an
undefined or a string array value.
If the variable contains any named structure/class
definitions, CMSV_RVTYPE will append those names
upon return, including any enclosed structures or
superclasses.
UNIT - a file unit. If a library routine reads to the end of
BLOCK, or if BLOCK is undefined, then this file UNIT will
be accessed for more data. If undefined, then BLOCK must
contain the entire file in memory.
OFFSET - the file offset of byte zero of BLOCK. Default: 0
(OFFSET is not used by this routine at this time)
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
CALLED BY:
CMRESTORE, CMSAVE, CMSAVEDIR, CMSVREAD
EXAMPLE:
SEE ALSO:
CMRESTORE, CMSVLIB, RESTORE, SAVE
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
Avoid using reserved word INHERITS, 07 Mar 2006, CM
NOTE: remember to modify CMSVLIB.PRO when changing library!
$Id: cmsv_rvtype.pro,v 1.13 2009/11/22 22:50:49 craigm Exp $
[Previous]
[Next]
NAME:
CMSV_TEST
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Test the CMSVLIB library
CALLING SEQUENCE:
CMSV_TEST, FILENAME, USER_VALUE=UVALUE
DESCRIPTION:
CMSV_TEST performs a standard test of the CMSVLIB library. It
reads and writes a save file using several different methods in an
attempt to test the different ways that the library can be used.
The test procedure can be used to verify that the library is
functioning properly.
By default, this procedure provides standard values to be written,
but the user can provide one of them with the USER_VALUE keyword.
If the user's data contains pointers, they must expect tests
listed under CMSVREAD and CMSVWRITE to fail.
By default the file is written in the current directory, but this
can be changed with the FILENAME parameter.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
FILENAME - a scalar string, the output path.
Default: 'CMSVTEST.SAV' in current directory
KEYWORDS:
USER_VALUE - any IDL variable to be saved, in place of variable
"C" in the test.
EXAMPLE:
SEE ALSO:
CMRESTORE, CMSVLIB, RESTORE, SAVE
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Resolve all routines at start, and add VMS keyword, 14 Feb 2001, CM
Make version checks with correct precision, 19 Jul 2001, CM
Added notification about RSI License, 13 May 2002, CM
Changed test so that 'DEADBEEF'XL is not used, which apparently
causes problems on 'FL', 01 Aug 2009
Add test for strings >127 characters (v1.7), 2012-04-05, CM
$Id: cmsv_test.pro,v 1.11 2012/04/05 20:43:09 cmarkwar Exp $
[Previous]
[Next]
NAME:
CMSV_WDATA
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Write SAVE-formatted data variable record to output block or file
CALLING SEQUENCE:
CMSV_WDATA, BLOCK, POINTER, DATA, UNIT=UNIT, TEMPORARY=TEMPORARY, $
PTR_INDEX=PTR_INDEX, PTR_DATA=PTR_DATA, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
CMSV_WDATA writes the data portion of an IDL SAVE variable record.
An IDL variable is stored in two components: the type descriptor
which describes the name, type, and dimensions of the variable;
and the data record, which contains the raw data of the variable.
This procedure writes the raw data to the output. The initial
type descriptor portion of the record must have already been
writtenusing the CMSV_WVTYPE procedure.
Under normal circumstances a user will write variable or heap data
using the CMSV_WREC procedure.
CMSV_WDATA supports the following variable types:
BYTE(1),INT(2),LONG(3) - integer types
UINT(12),ULONG(13),LONG64(14),ULONG64(15) - integer types (IDL >5.2 only)
FLOAT(4),DOUBLE(5),COMPLEX(6),DCOMPLEX(9) - float types
STRING(7) - string type
STRUCT(8) - structure type
POINTER(10) - pointer type - SEE BELOW
NOT SUPPORTED - OBJ(11) - object reference type - NOT SUPPORTED
Arrays and structures containing any of the supported types are
supported (including structures within structures).
The caller must specify in the DATA parameter, the data to be
written to output. The variable passed as DATA must have the same
type and dimensions as passed to CMSV_WVTYPE.
Unlike most of the other output routines, this procedure is able
to send its output to a file rather than to the BLOCK buffer. If
the UNIT keyword is specified then output is sent to that file
UNIT, after any pending BLOCK data is first sent. Users should
note that after such operations, the BLOCK POINTER and OFFSET
parameters may be modified (ie reset to new values).
See CMSV_WREC for instructions on how to write heap data.
[ This code assumes the record header and type descriptor have
been written with CMSV_WREC and CMSV_WVTYPE. ]
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
BLOCK, POINTER, OFFSET
This procedure writes data to a byte array or a file. If the UNIT
keyword is specified then file is sent to the specified unit
number rather than to the buffer BLOCK. However, the intent is
for users to accumulate a significant amount of data in a BLOCK
and then write it out with a single call to WRITEU. Users should
be aware that the block can be larger than the buffered data, so
they should use something like the following:
WRITEU, UNIT, BLOCK(0:POINTER-1)
When library routines do indeed write buffered BLOCK data to disk,
they will appropriately reset the BLOCK and POINTER. Namely,
BLOCK will be reset to empty, and POINTER will be reset to zero.
OFFSET will be advanced the according number of bytes.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN or writing the
block to disk.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
DATA - the data to be written, of any save-able data type.
KEYWORDS:
TEMPORARY - if set, then the input DATA are discarded after being
written, as a memory economy provision.
PTR_INDEX - a heap index array for the data being written, if any
heap data records have been written.
Default: no pointers are written
PTR_DATA - an array of pointers, pointing to the heap values being
written.
Default: no pointers are written
UNIT - a file unit. If specified then data are directed to the
file unit rather than to the buffer BLOCK.
OFFSET - the file offset of byte zero of BLOCK.
Upon output, if the file pointer is advanced, OFFSET will
also be changed.
(OFFSET is not currently used by this routine)
Default: 0
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
CALLED BY:
CMSV_WREC
EXAMPLE:
CALLS: ***
CMSV_WCONV, CMSV_WRAW
SEE ALSO:
CMRESTORE, CMSVLIB, RESTORE, SAVE
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
Added support for byte scalars and arrays (!), 27 Mar 2006, CM
Bug fix for multi-dimensional byte array, 2013-04-18, CM
NOTE: remember to modify CMSVLIB.PRO when changing library!
$Id: cmsv_wdata.pro,v 1.11 2013/04/18 19:14:08 cmarkwar Exp $
[Previous]
[Next]
NAME:
CMSV_WRAW
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Write raw SAVE data to output block
CALLING SEQUENCE:
CMSV_WRAW, BLOCK, POINTER, DATA, UNIT=UNIT, $
STRING=STRING, LONG=LONG, BYTE=BYTE, TYPE=TYPE, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
This procedure writes raw integer or string data to an IDL SAVE
block in memory. This is the lowest level writing function in the
library, intended for developers who are investigating new and
existing SAVE file formats.
The data to be written is specified by the DATA parameter. The
data must be of type BYTE, LONG or STRING, and the type is
determined automatically from the data itself. [ The mnemonic
STRING LONG and BYTE keywords are accepted for programming clarity
but ignored. ]
This procedure accepts but currently ignores the UNIT keyword. It
is the caller's responsibility to write the BLOCK data to disk
when appropriate.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
BLOCK, POINTER, OFFSET
This procedure writes data to a byte array only. The intent is
for users to accumulate a significant amount of data in a BLOCK
and then write it out with a single call to WRITEU. Users should
be aware that the block can be larger than the buffered data, so
they should use something like the following:
WRITEU, UNIT, BLOCK(0:POINTER-1)
When library routines do indeed write buffered BLOCK data to disk,
they will appropriately reset the BLOCK and POINTER. Namely,
BLOCK will be reset to empty, and POINTER will be reset to zero.
OFFSET will be advanced the according number of bytes.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be written is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN or writing the
block to disk.
POINTER - a long integer, a pointer to the next byte to be written
from BLOCK. CMSVLIB routines will automatically advance
the pointer.
DATA - the data to be written. Must of type STRING, BYTE or LONG.
KEYWORDS:
LONG - ignored (to be used for clarity)
BYTE - ignored (to be used for clarity)
STRING - ignored (to be used for clarity)
UNIT - a file unit. Currently ignored.
OFFSET - the file offset of byte zero of BLOCK.
Upon output, if the file pointer is advanced, OFFSET will
also be changed.
(OFFSET is not currently used by this routine)
Default: 0
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
CALLED BY:
CMSV_WDATA, CMSV_WREC, CMSV_WVTYPE
EXAMPLE:
CALLS: ***
CMSV_ENLARGE
SEE ALSO:
CMRESTORE, CMSVLIB, RESTORE, SAVE
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
Fixed bug in writing of empty strings, 28 Mar 2006, CM
Fixed bug when writing strings >128 characters, 2012-04-05, CM
NOTE: remember to modify CMSVLIB.PRO when changing library!
$Id: cmsv_wraw.pro,v 1.9 2012/04/05 20:43:09 cmarkwar Exp $
[Previous]
[Next]
NAME:
CMSV_WREC
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Write SAVE-formatted record header to output block or file
CALLING SEQUENCE:
CMSV_WDATA, BLOCK, POINTER, DATA, IDENT, UNIT=UNIT, $
INITIALIZE=INITIALIZE, NO_DATA=NO_DATA, $
NO_TYPE=NO_TYPE, COMPATIBILITY=COMPAT, $
BLOCK_TYPE=BLOCK_TYPE, BLOCK_NAME=BLOCK_NAME,
NEXT_BLOCK=NEXT_BLOCK, $
[ ... EXTRA KEYWORDS ... ]
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
This procedure writes most types of IDL SAVE record, including the
header and contents. The header consists of four bytes at the
beginning of each record which indentifies the type and size of
the record. This procedure also writes the contents of certain
records, as noted below.
Users can specify the block type by passing the BLOCK_TYPE or
BLOCK_NAME keywords. The values listed in the following table are
supported. CMSV_WREC writes the contents of essentially all
record types as well. Some records do not contain any contents at
all (those entries marked with an [empty]) and thus require no
further processing.
BLOCK_TYPE BLOCK_TYPE WRITE RECORD CONTENTS WITH...
0 = 'START_MARKER' [empty]
1 = 'COMMON_BLOCK' [this procedure]
2 = 'VARIABLE' [this procedure]
3 = 'SYSTEM_VARIABLE' [this procedure]
6 = 'END_MARKER' [empty]
10 = 'TIMESTAMP' [this procedure]
12 = 'COMPILED' no published procedure
13 = 'IDENTIFICATION' [this procedure]
14 = 'VERSION' [this procedure]
15 = 'HEAP_INDEX' [this procedure]
16 = 'HEAP_DATA' [this procedure]
17 = 'PROMOTE64' [empty]
19 = 'NOTICE' [this procedure]
For records that contain variable data, the external procedures
CMSV_WVTYPE and/or CMSV_WDATA may be used, however it is not
recommended, since the record header must finally be re-written by
the user. Users can write the entire record with this procedure.
After issuing a POINT_LUN, or after writing the BLOCK to disk, the
block cache in BLOCK must be reset using the /INITIALIZE keyword.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
SPECIFIC RECORD TYPES
CMSV_WREC reads certain specific record types automatically based
on data passed in the DATA parameter.
Records of type 'VARIABLE' (2), 'SYSTEM_VARIABLE' (3) and
'HEAP_DATA' (16) require both the DATA and IDENT parameters. For
the first two record types, the IDENT parameter is the name of the
variable, as a scalar string. Variable names should be valid IDL
variable names, uppercase, and have no embedded spaces. For the
'HEAP_DATA' record type, the IDENT parameter is the heap index
value, as described below. The DATA itself can be any supported
IDL variable type (as described in CMSV_WVTYPE).
For records that accept data in the form of a structure, as listed
below, the listed structure tag entries are optional. If the user
does not provide a value, then a suitable default will be computed
by this procedure (listed in parentheses).
A record of type 'VERSION' (14) has the following structure:
{ FORMAT_VERSION: 0L, $ ; Format version number of file (5)
ARCH: '', $ ; !VERSION.ARCH of creating host
OS: '', $ ; !VERSION.OS of creating host
RELEASE: '' } ; !VERSION.RELEASE of creating host
A record of type 'TIMESTAMP' (10) has the following structure:
{ SAVE_DATE: '', $ ; Date the save file was created (SYSTIME(0))
SAVE_USER: '', $ ; User name who created file ('UNKNOWN')
SAVE_HOST: '' } ; Host name that created file ('UNKNOWN')
Save files created by IDL version 4 do not contain a timestamp
record. Under Unix this procedure will attempt to discover the
user and host names automatically.
A record of type 'IDENTIFICATION' (13) has the following
structure:
{ AUTHOR: '', $ ; Author of SAVE file ('')
TITLE: '', $ ; Title of SAVE file ('')
IDCODE: '' } ; Identifying code for SAVE file ('')
It appears that this record is not used in IDL version 5 or later.
A record of type 'COMMON_BLOCK' (1) defines a named common block
and its variables. A common block descriptor consists of an array
of strings whose first element is the common block name, and whose
remaining elements are the common block variable names. Thus, a
common block descriptor must have at least two elements. No
variable data are stored with the common block definition.
When a record of type 'NOTICE' (19) defines a notice to be
included in the save file. It is a structure with one field:
{TEXT: ''}, where TEXT is the text content of the notice.
A record of type 'HEAP_INDEX' (15) defines the heap index in a
SAVE file. The heap index specifies a list of which heap
variables are stored in the current save file. These indices are
simply numbers which identify each heap variable (i.e.,
"<PtrHeapVar2>" would have an index of 2). The heap index can use
any numbers to identify the heap data; however it is required that
all index entries have corresponding heap data values.
WRITING HEAP DATA
If your data contains heap data and/or pointers, then users must
take special care in writing their data. Writing heap data is
actually more straightforward than reading it. There are several
steps involved which can be summarized as followed: (1) take
inventory of HEAP data; (2) write HEAP_INDEX record; (3) write one
HEAP_DATA record for each heap variable; and (4) write any other
variables using the heap index.
(1) Take inventory of heap data. Before writing any data to the
SAVE file, use the CMSV_PTRSUM procedure to discover all
pointer variables in the data set, like so:
cmsv_ptrsum, var, ptrlist
PTRLIST contains an array of any heap variables pointed to by
VAR (including structures or pointed-to variables). If
multiple variables are to be written, then the inventory must
contain the union of all heap variables.
(2) Write a HEAP_INDEX record. The heap index is an array of long
integers which identify the heap variables. In principle it
doesn't matter which integers are used, however there must be
a one-to-one correspondence between the entries in the heap
index and the heap identifiers used in the next step. In this
example a simple LINDGEN is used:
index = lindgen(n_elements(ptrlist))
cmsv_wrec, block, pointer, index, block_name='HEAP_INDEX', $
offset=offset
(3) Write one HEAP_DATA record for each heap variable. Issue one
CMSV_WREC call for each entry in PTRLIST, as follows for the
ith heap variable:
cmsv_wrec, block, pointer, ptrlist(i), block_name='HEAP_DATA', $
ptr_index=index, ptr_data=ptrlist, offset=offset
Note that the PTR_INDEX and PTR_DATA keywords are required
because heap data may itself contain pointers. The PTR_INDEX
and PTR_DATA keywords enable the CMSV_WREC procedure to write
appropriate descriptors when it encounters pointers.
(4) Write remaining data. For the ith variable, use:
cmsv_wrec, block, pointer, var(i), name(i), block_name='VARIABLE',$
ptr_index=index, ptr_data=ptrlist, offset=offset
As above, using the PTR_INDEX and PTR_DATA keywords will allow
the CMSV_WREC procedure to write the appropriate data.
BLOCK, POINTER, OFFSET
This procedure writes data to a byte array or a file. If the UNIT
keyword is specified then file is sent to the specified unit
number rather than to the buffer BLOCK. However, the intent is
for users to accumulate a significant amount of data in a BLOCK
and then write it out with a single call to WRITEU. Users should
be aware that the block can be larger than the buffered data, so
they should use something like the following:
WRITEU, UNIT, BLOCK(0:POINTER-1)
When library routines do indeed write buffered BLOCK data to disk,
they will appropriately reset the BLOCK and POINTER. Namely,
BLOCK will be reset to empty, and POINTER will be reset to zero.
OFFSET will be advanced the according number of bytes.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN or writing the
block to disk.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
DATA - the record contents to be written, as describe above.
IDENT - for record types 'VARIABLE' (2) and 'SYSTEM_VARIABLE' (3),
the name of the variable as a scalar string. For record
type 'HEAP_DATA' (16), the heap index identifier as a
scalar long integer.
KEYWORDS:
BLOCK_NAME - a scalar string specifying the record type, as
described above. The BLOCK_TYPE keyword takes
precedence over BLOCK_NAME.
BLOCK_TYPE - a scalar integer specifying the record type, as
described above.
NEXT_BLOCK - if specified, the file offset of the next record
location.
Default: the offset will be computed automatically.
INITIALIZE - if the keyword is set, then the BLOCK is emptied and
the POINTER is reset before any new data is written.
NO_TYPE - if set, no type descriptor or data are written for
variable records.
NO_DATA - if set, no data are written for variable records.
TEMPORARY - if set, then the input DATA are discarded after being
written, as a memory economy provision.
PTR_INDEX - a heap index array for the data being written, if any
heap data records have been written.
Default: no pointers are written
PTR_DATA - an array of pointers, pointing to the heap values being
written.
Default: no pointers are written
UNIT - a file unit. If specified then data are directed to the
file unit rather than to the buffer BLOCK.
OFFSET - the file offset of byte zero of BLOCK.
Upon output, if the file pointer is advanced, OFFSET will
also be changed.
(OFFSET is not currently used by this routine)
Default: 0
COMPATIBILITY - a string, which describes the format to be used in
the output file. Possible values are:
'IDL4' - format of IDL version 4;
'IDL5' - format of IDL versions 5.0-5.3;
'IDL6' - not supported yet, for versions 5.4-above;
'RIVAL1' - same as 'IDL5', plus a directory entry is
written to the file.
Note that files written in IDL5 format may still be
readable by IDL v.4.
Default: 'IDL5'
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
CALLED BY:
CMSAVE, CMSVWRITE
EXAMPLE:
CALLS: ***
CMSV_RREC, CMSV_WCOMM, CMSV_WDATA, CMSV_WHEAP, CMSV_WIDENT, CMSV_WNOTICE, CMSV_WRAW
CMSV_WSTAMP, CMSV_WVERSION, CMSV_WVTYPE
SEE ALSO:
CMRESTORE, CMSVLIB, RESTORE, SAVE
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
Added NOTICE record type, 09 Jun 2003, CM
NOTE: remember to modify CMSVLIB.PRO when changing library!
$Id: cmsv_wrec.pro,v 1.10 2009/11/22 22:50:49 craigm Exp $
[Previous]
[Next]
NAME:
CMSV_WVTYPE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Write variable type information to output block
CALLING SEQUENCE:
CMSV_WVTYPE, BLOCK, DATA, IDENT, $
HEAP=HEAP, SYSTEM=SYSTEM, UNIT=UNIT, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
CMSV_WVTYPE writes the type portion of an IDL SAVE variable
record. An IDL variable is stored in two components: the type
descriptor which describes the name, type, and dimensions of the
variable; and the data record, which contains the raw data of the
variable. This procedure writes the type descriptor based on a
variable passed by the user. Once the type descriptor has been
written, the data portion can be written using the CMSV_WDATA
procedure.
CMSV_WVTYPE should recognize and correctly output type descriptors
for all currently known IDL data types, except for object
references. Type information is inferred from the DATA parameter
passed by the user.
Heap data is a special case, since the data itself are stored
separately from the pointer in the SAVE file. Three steps must be
satisfied: a HEAP_INDEX record must be written; a valid HEAP_DATA
record must be written containing a type descriptor (written with
this procedure) and the heap data; and the named pointer itself
must be written.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
BLOCK, POINTER, OFFSET
This procedure writes data to a byte array only. The intent is
for users to accumulate a significant amount of data in a BLOCK
and then write it out with a single call to WRITEU. Users should
be aware that the block can be larger than the buffered data, so
they should use something like the following:
WRITEU, UNIT, BLOCK(0:POINTER-1)
When library routines do indeed write buffered BLOCK data to disk,
they will appropriately reset the BLOCK and POINTER. Namely,
BLOCK will be reset to empty, and POINTER will be reset to zero.
OFFSET will be advanced the according number of bytes.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be written is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN or writing the
block to disk.
POINTER - a long integer, a pointer to the next byte to be written
from BLOCK. CMSVLIB routines will automatically advance
the pointer.
DATA - the data to be written, of any save-able data type.
IDENT - for variables, the name of the variable as a string; for
heap data, the heap index as an integer.
KEYWORDS:
HEAP - if set, the data is treated as heap data, and IDENT must be
an integer heap index.
SYSTEM - if set, the data is assumed to be a system variable.
UNIT - a file unit. Currently ignored.
OFFSET - the file offset of byte zero of BLOCK.
Upon output, if the file pointer is advanced, OFFSET will
also be changed.
(OFFSET is not currently used by this routine)
Default: 0
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
CALLED BY:
CMSV_WREC
EXAMPLE:
CALLS: ***
CMSV_WARRDESC, CMSV_WRAW, CMSV_WSTRUCTDESC, TAGSIZE
SEE ALSO:
CMRESTORE, CMSVLIB, RESTORE, SAVE
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
NOTE: remember to modify CMSVLIB.PRO when changing library!
$Id: cmsv_wvtype.pro,v 1.14 2009/11/22 22:50:49 craigm Exp $
[Previous]
[Next]
NAME:
CMSVLIB
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Initialize the CMSVLIB save library
CALLING SEQUENCE:
VALUE = CMSVLIB(/QUERY, VERSION=version)
DESCRIPTION:
This function initializes the CMSVLIB library to read, write and
interrogate IDL save files. Use the QUERY keyword to determine
whether the full CMSVLIB library is present.
The VERSION keyword allows the user to query the version number of
the CMSVLIB library. The library version number will be returned
as a string of the form "X.Y" where X is the major version number
and Y is the minor version number. Callers can use this version
number to decide whether this particular version of the library is
compatible with their usage.
The procedures in the library are:
High-level
CMSAVE - save variables to a save file
CMRESTORE - restore variables from a save file
CMSAVEDIR - list contents of a save file
CMSVLIB (function) - this file
Mid-level
CMSV_OPEN - open a save file for reading or writing
CMSVREAD - read non-pointer data from file
CMSVWRITE - write non-pointer data to file
Low-level
CMSV_RREC - read record from save file
CMSV_RVTYPE - read variable type information from file
CMSV_RDATA - read variable data from file
CMSV_WREC - write record to save file
CMSV_WVTYPE - write variable type information to file
CMSV_WDATA - write variable data to file
Utility
CMSV_RRAW (function) - read raw integer or string data from file
CMSV_WRAW - write raw integer or string data to file
CMSV_PTRSUM - create a heap data inventory
CMSV_TEST - test the library
TAGSIZE (function) - determine the types of all tags in a structure
HELPFORM (function) - create HELP-like string describing a variable
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
None
KEYWORDS:
QUERY - if set, determine whether the CMSVLIB library is
installed. Function returns 1 upon success, 0 upon
failure.
VERSION - upon return, the VERSION keyword will be set to a string
describing the version number of the CMSVLIB library.
CALLED BY:
CMRESTORE, CMSAVE, CMSAVEDIR, CMSVREAD, CMSVWRITE
EXAMPLE:
CALLS: ***
CMSV_OPEN, CMSV_RRAW
SEE ALSO:
CMRESTORE, CMSVLIB, RESTORE, SAVE
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
Documented the VERSION keyword, 22 Nov 2009, CM
LIBRARY MODIFICATIONS
1.0 - initial release
1.1 - 2003-06-28 - CMSV_RREC - added NOTICE record type
1.2 - 2006-03-07 - CMSV_RVTYPE - avoid reserved word INHERITS
1.3 - 2006-03-27 - CMSV_WDATA - add support to write bytes & empty
strings
1.4 - 2009-11-16 - CMSV_RREC - NEXTREC field is ULONG
1.5 - 2009-11-22 - CMSV_RDATA - clarify & speed some code
1.6 - 2010-01-11 - CMSV_RREC - read 64-bit files
1.7 - 2012-04-05 - CMSV_WRAW - writing strings >128 fixed
1.8 - 2013-04-18 - CMSV_WDATA - bug fix multi-dimensional byte array
version = '1.8' ;; NOTE: modify this when incrementing version number
$Id: cmsvlib.pro,v 1.8 2013/04/18 19:14:09 cmarkwar Exp $
[Previous]
[Next]
NAME:
CMSVREAD
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Read a single variable from an open SAVE file
CALLING SEQUENCE:
CMSVREAD, UNIT, DATA [, NAME=NAME, /NO_DATA, VERSION=VERSION,
TIMESTAMP=TIMESTAMP ]
DESCRIPTION:
CMSVREAD reads a single IDL variable from an open IDL SAVE file.
The file should already have been opened as a normal file using
OPENR.
CMSVREAD is a simplified version of the CMSVLIB package, and as
such is not capable of reading heap data (pointers) or object
data. Strings, structures, and all array types are supported.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
UNIT - the open file unit.
DATA - a named variable, into which the new data is to be read.
KEYWORDS:
NAME - upon output, the name of the saved variable is returned in
this keyword. If a failure or end of file condition
occurs, name will be undefined upon return.
STRUCTURE_NAME - if the data to be read is a structure, upon
output, this keyword will contain the name of the
structure. A value of '' indicates an anonymous
structure.
SIZE - upon output, the SIZE type of the data is returned in this
keyword.
NO_DATA - if set, no data is read from the file, only the variable
name and type.
TIMESTAMP - after the first call to CMSVREAD on a newly opened
file, this keyword will contain the file timestamp
structure.
VERSION - after the first call to CMSVREAD on a newly opened file,
this keyword will contain the file version information,
if available.
QUIET - if set, error messages are not printed.
Default: an error causes errors to be printed with MESSAGE
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
Read all variables from a file, and print help on them.
openr, 50, 'test.sav'
name = ''
while n_elements(name) GT 0 do begin ;; EOF signalled by NAME undefined
cmsvread, 50, data, name=name
help, name, data
end
close, 50
CALLS: ***
CMSVLIB, CMSV_OPEN, CMSV_RDATA, CMSV_RREC, CMSV_RVTYPE
SEE ALSO:
CMRESTORE, CMSAVE, CMSVLIB, CMSVWRITE, RESTORE
MODIFICATION HISTORY:
Written and documented, 11 Jan 2001, CM
Added notification about RSI License, 13 May 2002, CM
Remove support for undocumented AUTOPROMOTE64 keyword,
11 Jan 2010, CM
NOTE: remember to modify CMSVLIB.PRO when changing library!
$Id: cmsvread.pro,v 1.9 2010/01/11 08:58:13 craigm Exp $
[Previous]
[Next]
NAME:
CMSVWRITE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Write a single variable to an open SAVE file
CALLING SEQUENCE:
CMSVWRITE, UNIT, DATA [ , NAME=NAME, COMPATIBILITY=COMPAT ]
DESCRIPTION:
CMSVWRITE writes a single IDL variable to an open IDL SAVE file.
The file should already have been opened for writing as a normal
file using OPENW or OPENU.
CMSVWRITE is a simplified version of the CMSVLIB package, and as
such is not capable of writing heap data (pointers) or object
data, or structures that contain them. Strings, structures, and
all array types are supported.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
UNIT - the open file unit.
DATA - the data to be written.
KEYWORDS:
NAME - the optional name of the variable to be written (must be a
valid variable name).
Default: CMSVWRITE automatically creates a valid name.
COMPATIBILITY - a string, which describes the format to be used in
the output file. Possible values are:
'IDL4' - format of IDL version 4;
'IDL5' - format of IDL versions 5.0-5.3;
'IDL6' - not supported yet, for versions 5.4-above;
'RIVAL1' - same as 'IDL5'
Note that files written in IDL5 format may still be
readable by IDL v.4.
Default: 'IDL5'
NO_END - a save file must terminate with an "end" record. By
default, CMSVWRITE will append such a record after the
variable is written, and then rewind the file pointer.
The end record must be written after the last variable,
but is optional otherwise. Set this keyword to disable
writing the end record (for performance reasons).
QUIET - if set, error messages are not printed.
Default: an error causes errors to be printed with MESSAGE
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
Write variables A, B, C and D to a file.
openw, 50, 'test.sav' ;; Add /STREAM under VMS !
cmsvwrite, 50, a, name='a'
cmsvwrite, 50, b, name='b'
cmsvwrite, 50, c, name='c'
close, 50
CALLS: ***
CMSVLIB, CMSV_OPEN, CMSV_PTRSUM, CMSV_WREC
SEE ALSO:
CMRESTORE, CMSAVE, CMSVLIB, CMSVREAD, SAVE
MODIFICATION HISTORY:
Written and documented, 11 Jan 2001, CM
Make version checks with correct precision, 19 Jul 2001, CM
Added notification about RSI License, 13 May 2002, CM
NOTE: remember to modify CMSVLIB.PRO when changing library!
$Id: cmsvwrite.pro,v 1.12 2009/11/22 22:50:49 craigm Exp $
[Previous]
[Next]
NAME:
ColorEloTimeBox
PURPOSE:
Draws a color display for a set of 'skyboxes' as defined by a grid
of time and elongation coordinates.
CALLING SEQUENCE:
PRO ColorEloTimeBox, time_grid, elo_grid, Color, $
dabg = dabg , $
degrees = degrees , $
black = black , $
void = void
INPUTS:
time_grid array[n [+1] ] or array[n [+1],m [+1] ]; type: float
Phase angle; 'longitude'
Dimension n and/or m is used to specify the center of
sky box n,m (the box edges will be calculated internally
Dimension n+1 and/or m+1 is used to specify the edges of
sky box n,m
elo_grid array[m [+1] ] or array[n [+1],m [+1] ]; type: float
Polar angle; 'colatitude'
Box center of box edge can be specified, as for 'Phase'
Color array[n,m]; type: integer
2D array with color indices
boxes with negative color indices are never colored in
boxes with index zero are colored only if keyword /black is set
OPTIONAL INPUTS:
dabg=dabg array[3]; type: float; default: [0,0,0]
Passed to FishEye and HammerAitoff
Determines the direction of the center of the plot
/degrees if set, all angles are in degrees (default: radians)
/black if set, then color index 0 (black) is drawn with a call to polyfill
By default color index 0 is not drawn (i.e. remains in the
background color).
/void if set, then negative color index is drawn using the foreground
color !p.color. By default these are not drawn (i.e. remain
in the background color).
OUTPUTS:
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, SuperArray, ToDegrees, ToRadians, WhatIs
CALLED BY:
PlotEloTimeMap
RESTRICTIONS:
> Color must be a 2D array with dimension [N,M]. The first dimension (N) is the
phase angle dimension; the second (M) is the polar angle dimension
> The Phase and Polar arrays can be 1-dim or 2-dim.
A 1-dim Phase array (n) is interpreted as a 2-dim array (n,m) with all m rows the same.
A 1-dim Polar array (m) is interpreted as a 2-dim array (n,m) with all n columns the same.
> The second dimension of Phase should be the same (n=N) or one larger (n=N+1) than for Color.
If n=N+1 then Phase contains the phase angles of the edges of sky boxes; if n=N it contains
the center phase angles, and the edges are calculated internally.
> The second dimension of Polar should be the same (m=M) or one larger (m=M+1) than for Color.
If m=M+1 then Polar contains the polar angles of the edges of sky boxes; if m=M it contains
the center polar angles, and the edges are calculated internally.
PROCEDURE:
> The color array indices contains color indices for NxM 'skyboxes'.
The corners of the boxes are stored in the Phase and Polar arrays
> Phase and Polar are spherical coordinates in a coordinate system where
the reference direction (e.g. the direction to the Sun) is the Z-axis.
> Synonyms:
phase angle = longitude, position angle
polar angle = colatitude, elongation
> The arrays Phase and Polar will usually be obtained by a call to EulerRotate
> The array color can be obtained by a call to GetColors [1]
> The boxes in the x-y plane of the plot are defined by connecting the
corners by straight lines (and using the appropriate color).
> Boxes with color index 0 (black) are skipped by default. If the keyword
'black' is set color index 0 is explicitly colored with polyfill
MODIFICATION HISTORY:
JAN-2009, Paul Hick (UCSD/CASS)
[Previous]
[Next]
NAME:
ColorPolarBox
PURPOSE:
Draws a color display for a set of 'skyboxes' as defined by a grid
of spherical coordinates. Draws either a rectangular map
(x=phase,y=polar), a fish-eye map or a Hammer-Aitoff map
CALLING SEQUENCE:
PRO ColorPolarBox, cosP, sinP, Color, $
skyedge = skyedge , $
zero_phase = zero_phase, $
dabg = dabg , $
degrees = degrees , $
black = black , $
void = void , $
fill2edge = fill2edge
INPUTS:
Phase array[n [+1] ] or array[n [+1],m [+1] ]; type: float
Phase angle; 'longitude'
Dimension n and/or m is used to specify the center of
sky box n,m (the box edges will be calculated internally
Dimension n+1 and/or m+1 is used to specify the edges of
sky box n,m
Polar array[m [+1] ] or array[n [+1],m [+1] ]; type: float
Polar angle; 'colatitude'
Box center of box edge can be specified, as for 'Phase'
Color array[n,m]; type: integer
2D array with color indices
boxes with negative color indices are never colored in
boxes with index zero are colored only if keyword /black is set
skyedge scalar; type: float
if set and positive, data are plotted as a 'fish-eye' map.
The value is used as cut-off for the range of polar angles
plotted (polar angles above 'skyedge' not plotted); if set and
negative, a Hammer-Aitoff projection is used; if not set or
zero, a rectangular map is drawn
OPTIONAL INPUTS:
zero_phase=zero_phase
scalar, or array with same structure as 'Phase'; type: float
Only used if Xp is a 1-dim array of box centers.
The input arrays Xp, Yp, Color are rearranged to put
zero_phase in the center of the map.
dabg=dabg array[3]; type: float; default: [0,0,0]
Passed to FishEye and HammerAitoff
Determines the direction of the center of the plot
/degrees if set, all angles are in degrees (default: radians)
/black if set, then color index 0 (black) is drawn with a call to polyfill
By default color index 0 is not drawn (i.e. remains in the
background color).
/void if set, then negative color index is drawn using the foreground
color !p.color. By default these are not drawn (i.e. remain
in the background color).
/fill2edge if set, then the phase angle boundaries of the outermost bins are set to
+/- 180 degrees. Only used if bin centers are specified for
the phase angles.
OUTPUTS:
skyedge scalar
updated only if positive and bigger than 170 deg
(returned value is 170 deg)
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, SuperArray, ToDegrees, ToRadians
RESTRICTIONS:
> Color must be a 2D array with dimension [N,M]. The first dimension (N) is the
phase angle dimension; the second (M) is the polar angle dimension
> The Phase and Polar arrays can be 1-dim or 2-dim.
A 1-dim Phase array (n) is interpreted as a 2-dim array (n,m) with all m rows the same.
A 1-dim Polar array (m) is interpreted as a 2-dim array (n,m) with all n columns the same.
> The second dimension of Phase should be the same (n=N) or one larger (n=N+1) than for Color.
If n=N+1 then Phase contains the phase angles of the edges of sky boxes; if n=N it contains
the center phase angles, and the edges are calculated internally.
> The second dimension of Polar should be the same (m=M) or one larger (m=M+1) than for Color.
If m=M+1 then Polar contains the polar angles of the edges of sky boxes; if m=M it contains
the center polar angles, and the edges are calculated internally.
> The value of 'skyedge' is changed to skyedge = (skyedge < 170).
The method of plotting the skyboxes (by connecting the corners by straight lines in
the x-y plane of the plot) does not work for large elongations. Problems are avoiding
by not permitting 'skyedge' to be larger than 170.
PROCEDURE:
> The color array indices contains color indices for NxM 'skyboxes'.
The corners of the boxes are stored in the Phase and Polar arrays
> Phase and Polar are spherical coordinates in a coordinate system where
the reference direction (e.g. the direction to the Sun) is the Z-axis.
> Synonyms:
phase angle = longitude, position angle
polar angle = colatitude, elongation
> The arrays Phase and Polar will usually be obtained by a call to EulerRotate
> The array color can be obtained by a call to GetColors [1]
> If the 'skyedge' keyword is set, then the angles Phase and Polar are plotted
on the screen as a 'fish-eye' view, interpreting the Polar angle
as 'radius' and the Phase angle as an phase angle in the x-y plane of
the plot, i.e. x = Polar*cos(Phase) and y = Polar*sin(Phase).
> The boxes in the x-y plane of the plot are defined by connecting the
corners by straight lines (and using the appropriate color).
> Boxes with color index 0 (black) are skipped by default. If the keyword
'black' is set color index 0 is explicitly colored with polyfill
MODIFICATION HISTORY:
AUG-1999, Paul Hick (UCSD/CASS)
added check for negative color indices, these are now ignored
(GetColors now checks for bad values using the 'finite' function and
sets corresponding boxes to a negative color index).
JAN-2002, Paul Hick (UCSD/CASS)
Improved tests to decide which sky boxes to plot in a fish-eye plot
at large polar angles.
APR-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added /fill2edge keyword.
[Previous]
[Next]
NAME:
ColorSkybox
PURPOSE:
Draws a color display for a set of 'skyboxes' as defined by a grid
of spherical coordinates. Draws either a rectangular map
(x=phase,y=latitude), a fish-eye map or a Hammer-Aitoff map
CALLING SEQUENCE:
PRO ColorSkybox, Phase, Latitude, Color, $
skyedge = skyedge , $
zero_phase = zero_phase, $
dabg = dabg , $
degrees = degrees , $
black = black , $
void = void , $
fill2edge = fill2edge , $
use_mask = use_mask , $
mask = mask , $
_extra = _extra
INPUTS:
Phase array[n [+1] ] or array[n [+1],m [+1] ]; type: float
Phase angle; 'longitude'
Dimension n and/or m is used to specify the center of
sky box n,m (the box edges will be calculated internally
Dimension n+1 and/or m+1 is used to specify the edges of
sky box n,m
Latitude array[m [+1] ] or array[n [+1],m [+1] ]; type: float
Latitude angle
Box center or box edge can be specified, as for 'Phase'
Color array[n,m]; type: integer
2D array with color indices
boxes with negative color indices are never colored in
boxes with index zero are colored only if keyword /black is set
skyedge scalar; type: float
if set and positive, data are plotted as a 'fish-eye' map.
The value is used as cut-off for the range of colatitude (polar)
angles plotted (polar angles above 'skyedge' not plotted);
if set and negative, a Hammer-Aitoff projection is used;
if not set or zero, a rectangular map is drawn
mask array[n,m]; type: float
array with same dimensions as Color.
Usually this is a "mask" identifying "good" and "bad" areas
in the Color map.
use_mask scalar or array; type: float
specifies contour levels in the "mask" array
These contour leves are overplotted on the color map
using the IDL contour function.
_extra=_extra can be used to pass keywords to IDL contour function
processing the mask and use_mask keywords
OPTIONAL INPUTS:
zero_phase=zero_phase
scalar, or array with same structure as 'Phase'; type: float
The input arrays Phase, Latitude, Color are rearranged to put
zero_phase in the center of the map.
dabg=dabg array[3]; type: float; default: [0,0,0]
Passed to FishEye and HammerAitoff
Determines the direction of the center of the plot
/degrees if set, all angles are in degrees (default: radians)
/black if set, then color index 0 (black) is drawn with a call to polyfill
By default color index 0 is not drawn (i.e. remains in the
background color).
/void if set, then negative color index is drawn using the foreground
color !p.color. By default these are not drawn (i.e. remain
in the background color).
/fill2edge if set, then the phase angle boundaries of the outermost bins are set to
+/- 180 degrees. Only used if bin centers are specified for
the phase angles.
OUTPUTS:
skyedge scalar
updated only if positive and bigger than 170 deg
(returned value is 170 deg)
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
AngleRange, FishEye, HammerAitoff, InitVar, IsType, SuperArray, ToDegrees, ToRadians
CALLED BY:
GetColors [2], GetColors [3], PlotCoronagraph, PlotEarthSkymap [1]
PlotEarthSkymap [2], PlotEarthSkymap [3], PlotEarthSkymap [4], PlotPolarSkymap
vu_thomson_antifish, vu_thomson_hammer
RESTRICTIONS:
> Color must be a 2D array with dimension [N,M]. The first dimension
(N) is the phase angle dimension; the second (M) is the latitude
angle dimension
> The Phase and Latitude arrays can be 1-dim or 2-dim.
A 1-dim Phase array (n) is interpreted as a 2-dim array (n,m) with
all m rows the same. A 1-dim Latitude array (m) is interpreted as
a 2-dim array (n,m) with all n columns the same.
> The second dimension of Phase should be the same (n=N) or one larger
(n=N+1) than for Color. If n=N+1 then Phase contains the phase angles
of the edges of sky boxes; if n=N it contains the center phase angles,
and the edges are calculated internally.
> The second dimension of Latitude should be the same (m=M) or one
larger (m=M+1) than for Color. If m=M+1 then Latitude contains the
latitude angles of the edges of sky boxes; if m=M it contains
the center latitude angles, and the edges are calculated internally.
> The value of 'skyedge' is changed to skyedge = (skyedge < 170).
The method of plotting the skyboxes (by connecting the corners by
straight lines in the x-y plane of the plot) does not work for large
elongations in the fish-eye maps. Problems are avoiding by not
permitting 'skyedge' to be larger than 170.
PROCEDURE:
> The color array indices contains color indices for NxM 'skyboxes'.
The corners of the boxes are stored in the Phase and Latitude arrays
> Phase and Latitude are usually equatorial (RA, dec) or ecliptic
coordinates
> The center of fish-eye and Hammer-Aitoff has phase angle zero_lng
and latitude 0.
> The arrays Phase and Latitude will usually be obtained by a call
to EulerRotate
> The array color can be obtained by a call to GetColors [1]
> If the 'skyedge' keyword is set, then the angles Phase and Latitude
are plotted on the screen as a 'fish-eye' view.
> The boxes in the x-y plane of the plot are defined by connecting the
corners by straight lines (and using the appropriate color).
> Boxes with color index 0 (black) are skipped by default. If the keyword
'black' is set color index 0 is explicitly colored with polyfill
MODIFICATION HISTORY:
AUG-1999, Paul Hick (UCSD/CASS)
added check for negative color indices, these are now ignored
(GetColors now checks for bad values using the 'finite'
function and sets corresponding boxes to a negative color
index).
JAN-2002, Paul Hick (UCSD/CASS)
Improved tests to decide which sky boxes to plot in a fish-eye
plot at large polar angles.
APR-2002, Paul Hick (UCSD/CASS)
Added /fill2edge keyword.
MAR-2011, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Dropped restriction on zero_phase being applied only if
Phase is 1-dim array.
[Previous]
[Next]
NAME:
CombineRotations
PURPOSE:
Combine two rotations, i.e. find the rotation resulting from
first applying one (R1), then another (R2) rotation.
CATEGORY:
gen/idl/toolbox/math
CALLING SEQUENCE:
FUNCTION CombineRotations, R1, R2, R3, R4, R5, $
quaternion = quaternion , $
euler_angles= euler_angles , $
dcm = dcm , $
geometric = geometric , $
degrees = degrees
INPUTS:
R1 array[3,n], array[4,n], array[3,3,n]; type: float
first rotation
R2 array[3,m], array[4,m], array[3,3,m]; type: float
second rotation
R1 and/or R2 can be a single rotation with the other
multiple rotations, i.e. n = 1 and m != 1; or n != 1
and m = 1. The single rotation will be combined with
each of the multiple rotations.
R3,R4,R5 Additional rotations. Up to 5 rotations can be combined
in a single call.
OPTIONAL INPUT PARAMETERS:
/quaternion input and output rotations are in quaternions;
/euler_angles in- and output rotations are in Euler angles triplets
/dcm in- and output rotations are in direction cosine matrices
/geometric in- and putput rotations are in geometic form
(unit vector, plua rotation around unit vector).
/degrees if set then all angles are in degrees (default: radians)
OUTPUTS:
R array[3,n > m]; type: same as input
combined rotation in same form as input
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
CvRotation, InitVar, IsType, SyncArgs
CALLED BY:
CvSky, CvSky_Galactic, quaternion, smei_cam_quaternion, smei_camera
smei_frm_where, smei_orient_test, vu_linecut, vu_planarcut, vu_spherecut
SEE ALSO:
EulerRotate
PROCEDURE:
See definition of quaternions in: Foley, van Dam, Feiner and Hughes
'Computer graphics, principles and practice', 2nd edition.
Addison-Wesley, 1992, page 1063
MODIFICATION HISTORY:
MAR-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
compile_opt
PURPOSE:
Controls default IDL error handler and special compiler options
CALLING SEQUENCE:
@compile_opt.pro
PROCEDURE:
Included in virtually all IDL procedures in the SSW_SMEI tree
MODIFICATION HISTORY:
JAN-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
compipsd
CALLING SEQUENCE:
pro compipsd
INCLUDE:
@compile_opt.pro
CALLS: ***
FILEPATH, GuessRecs, WhatIs, vu_select
[Previous]
[Next]
NAME:
cona
CALLING SEQUENCE:
pro cona
CALLS: ***
flt_read
[Previous]
[Next]
NAME:
convert_swoops
CALLING SEQUENCE:
pro convert_swoops
INCLUDE:
@compile_opt.pro
CALLS: ***
FILEPATH, flt_read
[Previous]
[Next]
NAME:
coord3to2
PURPOSE:
Convert a 3D position vector to a 2D 'screen location'
CATEGORY:
CALLING SEQUENCE:
result = coord3to2(p, [,/device, /normal])
INPUTS:
p array[3,*]; type: int or float
coordinates of 3d vectors
OPTIONAL INPUT PARAMETERS:
/data, /normal, /device
only one of these should be set
if set the input coordinates are assumed to be in data, normal
or device coordinates. If all are absent, then data coordinates are assumed
OUTPUTS:
p array[3,*]; same type as input
the converted 'screen location'
OPTIONAL OUTPUT PARAMETERS:
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, SyncDims
CALLED BY:
arrow3d, losgeometry, miscfig, plot3dtext
PROCEDURE:
If a 3D transformation (!p.t) is in effect than all 3D vector arguments supplied to IDL
plot functions while using the /t3d keyword are converted to a 'screen location' for actual plotting.
This function is my best guess as to how this works. The x,y coordinates of the returned
vector indicate where on the screen (inside the plotwindow) the point would be plotted, while
the z-coordinate provides the 'depth' dimension perpendicular to the screen.
MODIFICATION HISTORY:
AUG-1999, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
coriolis_map
CALLING SEQUENCE:
PRO coriolis_map, t, _extra=_extra, silent=silent, file=file
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
AngleRange, AngleUnits, CV_COORD, CvSky, InitVar, LOADCT, TimeGet, TimeOp, TimeSet
TimeSystem, TimeUnit, ToRadians, get_page, jpl_eph, map_set, set_page, sgp4_eph
sphere_distance, unitvectors
[Previous]
[Next]
NAME:
cv
CALLING SEQUENCE:
PRO cv
INCLUDE:
@compile_opt.pro
CALLS: ***
AngleRange, TimeSet, WhatIs, big_eph, ra_fictitious_sun, sgp4_orbit_axis
sphere_distance, txt_read
[Previous]
[Next]
NAME:
Cv2Grid
PURPOSE:
Generate function values in a regular grid of NX by NY points.
The input function values are specified on a set random points XP,YP
with function values ZP, or as a 2-D array ZP
CALLING SEQUENCE:
Z = Cv2Grid (ZP, nX,nY, dist=Dist, xp=XP, yp=YP, pos=pos, zflag=Zflag, noflag=NoFlag)
Z = Cv2Grid (ZP, nX,nY, dist=Dist, zflag=Zflag, noflag=NoFlag)
INPUTS:
ZP array[*] or array[*,*]; type:float
if array[*] : function values for a 'random' set of data points
if array[*,*]: any 2-dim array to be rebinned
nX scalar; type: integer
nY scalar: type: integer
size of regular output array
OPTIONAL INPUTS:
dist=Dist
scalar; type: float
data points closer than abs(Dist) grid
spacings from an output grid point are included
in the averaging
xp=XP array[*]; type: float
yp=YP array[*]; type: float
X/Y-coordinates of points in the random set in user-specified units
position=[XB,YB,XE,YE]
array[4]; type: float
XB,YB) X/Y-coordinates of grid point (0,0) in user units
XE,YE X/Y-coordinates of grid point (nX-1,nY-1) in user units
zflag=ZFlag
scalar; type: float; default: !values.f_nan
value used to identify invalid fnc-values in in- and output Z
/noflag if set, no fnc-values are flagged as 'bad'
OUTPUTS:
Z array[nX,nY]; type: float
grid function values.
If no function value was calculated for a particular grid point
the value Zflag is returned
RESTRICTIONS:
The user units for XB,XE,YB,YE should be the same as for XP and YP
PROCEDURE:
> If both keywords xp and yp are present, then zp is assumed to be 1-dim
array of 'random' points. Otherwise zp is assumed to be a 2-dim array.
> The output grid defines a regular grid of nX by nY squares.
> The function values Z are calculated by averaging over points ZP
inside a grid square.
MODIFICATION HISTORY:
JAN-1995, Paul Hick (UCSD); based on Fortran routine CONSTRUCT_GRID
[Previous]
[Next]
NAME:
cv_cr2crlf
CALLING SEQUENCE:
PRO cv_cr2crlf, infile, outfile
INCLUDE:
@compile_opt.pro ; On error, return to caller
[Previous]
[Next]
NAME:
cvequ
CALLING SEQUENCE:
PRO cvequ
INCLUDE:
@compile_opt.pro
CALLS: ***
FILEPATH, FXADDPAR, FXPAR, GetFileSpec, READFITS, WRITEFITS
[Previous]
[Next]
NAME:
cvgrd
CALLING SEQUENCE:
pro cvgrd
INCLUDE:
@compile_opt.pro ; On error return to caller
CALLS: ***
BadValue, FILEPATH, GetFileSpec, SetFileSpec, WhatIs, bin_write, flt_read
[Previous]
[Next]
NAME:
cvgrd_skymap
CALLING SEQUENCE:
pro cvgrd_skymap
INCLUDE:
@compile_opt.pro ; On error return to caller
CALLS: ***
BadValue, FILEPATH, GetFileSpec, STRSPLIT, SetFileSpec, WhatIs, bin_write, grd_read
[Previous]
[Next]
NAME:
cvmag_fig
CALLING SEQUENCE:
pro cvmag_fig, figure
INCLUDE:
@compile_opt.pro ; On error, return to caller
[Previous]
[Next]
NAME:
cvplot_figures
CALLING SEQUENCE:
pro cvplot_figures, figure
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
CVPLOT_DIAMOND, InitVar, plot3darc, plot3dcube, plot3dline, plot3dtext, setup3d, twin
[Previous]
[Next]
NAME:
CvPointOnLos
PURPOSE:
Converts from topocentric to heliocentric coordinates and v.v
CALLING SEQUENCE:
FUNCTION CvPointOnLos, RP,$
oldelo = ELOLD , $
oldphase= PHOLD , $
newelo = ELNEW , $
eorw = EorW , $
degrees = degrees
INPUTS: (either topocentric or heliocentric)
RP array[3,*]; type: float
RP[0,*] = longitude (0<=LNG<=360) and ...
RP[1,*] = latitude (-90<=LAT<=90) of line of sight
RP[2,*] = radial distance to point on los
(in units of the observer-Sun distance)
OPTIONAL INPUT PARAMETERS:
/degrees if set all in- and output angles are in degrees
(default is radians)
OUTPUTS: (either heliocentric or topocentric)
Result array[3,*]; type: float
RP[0,*] = longitude (0<=XLNG<=360) and ...
RP[1,*] = latitude (-90<=XLAT<=90) of line of sight
RP[2,*] = radial distance to point on los
(in units of the observer-Sun distance)
oldelo=OldElo array[*]; type: float
elongation in the old coordinate system; 0<=ELOLD<=180
oldphase=OldPhase array[*]; type: float
phase angle measured counterclockwise from the north
newelo=NewElo array[*]; type: float
elongation in the new coordinate system 0<=ELNEW<=180
EorW array[*]; type: integer
+1 or -1; indicates on which side (East or West) of
the Sun-Earth line the point is located
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
IsType, SubArray, SyncDims, ToRadians, boost
CALLED BY:
EarthSky3DLoc, EarthTransit3DLoc, ThomsonLOSDensity, lospos, nagoya_plotg2d
thomsonfig
RESTRICTIONS:
> There is no check for -90 <= XLAT <= 90
PROCEDURE:
> The topocentric coordinate system (with Earth in the origin)
has its X-axis pointing towards the Sun. Y and Z-axis are arbitrary
(usually the X-Y plane will be the ecliptic).
The topocentric longitude is measured in a positive sense, i.e.
counterclockwise as viewed from the positive Z-axis.
> The heliocentric coordinate system (with the Sun in the origin
has its X-axis pointing towards Earth.
The heliocentric longitude is measured in a positive sense.
> Spherical coordinates for both systems: longitude (deg), latitude
(deg) and radial distance (units of Sun-Earth distance).
> Input can be in topocentric or heliocentric coordinates. The output
will be in the other coordinate system (the calculation is symmetric).
> EorW is determined from the input elongation XLNG:
if 0<=XLNG<=180 then EorW = 1; if 180<XLNG<360 the EorW = -1
> If input is in topocentric coordinates then
- OldElo is the angle Sun-Earth-P
- NewElo is the angle Earth-Sun-P
- EorW = +1 if P is towards the east of the Sun (viewed from Earth)
- EorW = -1 if P is towards the west of the Sun (viewed from Earth)
> If input is in heliocentric coordinates then
- OldElo is the angle Earth-Sun-P
- NewElo is the angle Sun-Earth-P
- EorW = -1 if P is towards the east of the Sun (viewed from Earth)
- EorW = +1 if P is towards the west of the Sun (viewed from Earth)
> If RP is negative then the opposite direction (180+XLNG,-XLAT,-RP)
is used.
> The Sun is located at topocentric longitude 0 deg and latitude 0 deg
and radial distance 1.0
> The Earth is located at heliocentric longitude 0 deg and latitude
0 deg and radial distance 1.0
> Internal calculations are done in double precision
> The easiest way to check the equations is to work out the relations
between the x,y,z components of the vector to P in both coordinates
systems.
MODIFICATION HISTORY:
FEB-1990, Paul Hick (UCSD)
Adapted from the subroutine SC_ECLIP.FOR
JUN-1994, Paul Hick (UCSD)
Made the calculation symmetric so that it is valid also going
from heliocentric to topocentric.
[Previous]
[Next]
NAME:
CvPrecess
PURPOSE:
Converts equatorial or ecliptic coordinates for epoch UT1 to
epoch UT2, i.e. corrects for precession between the two epochs.
CATEGORY:
smei/gen/idl/ephem
CALLING SEQUENCE:
FUNCTION CvPrecess, UT1, UT2, pos , $
degrees = degrees , $
from_ecliptic = from_ecliptic , $
to_ecliptic = to_ecliptic , $
rectangular = rectangular
CALLS: ***
CvSky, CvSky_Precess, EulerRotate, InitVar, REVERSE
INPUTS:
UT array[n]; type: time structure
initial epoch
UT array[n]; type: time structure
final epoch
pos[2,n] or pos[3,n]
spherical coordinates at start epoch UT1
RA or longitude, declination or latitude, and, optional
the distance (the distance is not modified)
OPTIONAL INPUT PARAMETERS:
/degrees if set, all angles are in degrees
/from_ecliptic
/to_ecliptic
by default the input and output are assumed to be in
equatorial coordinates (RA and declination).
If /from_ecliptic is set then the input is assumed to be
in ecliptic coordinates (longitude and latitude)
If /to_ecliptic is set then the output is in ecliptic
coordinates
OUTPUTS:
pos[2,n] or pos[3,n]
spherical coordinates at final epoch UT2
RA or longitude, declination or latitude, and, optional
the distance (the distance is not modified)
INCLUDE:
@compile_opt.pro
CALLS: ***
CvSky, CvSky_Precess, EulerRotate, InitVar, REVERSE
CALLED BY:
PlotEarthSkymap [2], allsky [1], allsky [2], allsky [3], allsky_f, big_eph
getipssources, getnagoyasources, getootyasources, getsmeisources, jpl_eph
jpl_test, mpc_eph, mpc_orbit_eph, sgp4_eph, smei_sky, usno_eph, vu_los
PROCEDURE:
See R. Green, Spherical Astronomy, Cambridge UP, 1985, Sect. 9.5, p. 217
(1) First transform ecliptic longitude and latitude to equatorial right
ascension and declination (for initial epoch);
(2) Transform equatorial coordinates for initial epoch to epoch J2000.0;
(3) Calculate equatorial coordinates for epoch J2000.0 to final epoch;
(4) Transform back to ecliptic coordinates (for final epoch).
MODIFICATION HISTORY:
DEC-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Adapted from Fortran subroutine PRECESSION_ROT
[Previous]
[Next]
NAME:
CvRotation
PURPOSE:
Convert between several ways of specifying rotations
CATEGORY:
gen/idl/toolbox/math
CALLING SEQUENCE:
FUNCTION CvRotation, $
from_euler = from_euler , $
from_quaternion = from_quaternion , $
from_dcm = from_dcm , $
from_geometric = from_geometric , $
to_euler = to_euler , $
to_quaternion = to_quaternion , $
to_dcm = to_dcm , $
to_geometric = to_geometric , $
degrees = degrees
INPUTS:
OPTIONAL INPUT PARAMETERS:
Only one of the from_* keywords is specified:
from_euler=from_euler
array[3,n]; type: real
triplets of Euler angles
from_quaternion=from_quaternion
array[4,n]; type: real
unit quaternion quatruplets with the scalar in array[3,n]
(MUST be unit quanternion)
from_dcm array[3,3,n]; type: float
direction cosine matrices
from_geometric
array[3,n] or array[4,n]
unit vector, plus angle of rotation around unit vector.
array[3,n]: phase angle, latitude and angle of rotation
array[4,n]: rectangular coordinates and angle of rotation
Only one of the /to_* keywords is specified:
/to_euler if set then the output is an array[3,n] of Euler angles
/to_quaternion
if set then the output is an array[4,n] on unit quaternions
/to_dcm if set then direction cosine matrices array[3,3,n] are returned
/to_geometric
if set then a unit vector in rectangular coordinates and an
angle of rotation around the unit vector, array[4,n]
are returned.
/degrees if set, all angles are in degrees (default: radians)
OUTPUTS:
out array[3,n], array[4,n]; type: same as input
Euler angles, unit quaternion, direction cosine matrix
or unit vector with angle of rotation.
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
AngleRange, CV_COORD, InitVar, IsType, ToRadians, boost
CALLED BY:
CombineRotations, CvSky_Galactic, cvsmei, smei_ccd2sky, smei_frm_where
smei_orient_test, smei_sgp4_quat, smei_sky2cam
SEE ALSO:
EulerRotate
RESTRICTIONS:
The quaternion to Euler angle conversion may still have problems near qx = qy = 0
(rotations around the z-axis) and q0 = qz = 0 (rotations around axis in x-y plane.
The singularities themselves (strictly qx=qy=0 and strictly q0=qz=0) are dealt
with properly.
PROCEDURE:
The Euler angle triplets define rotation around z-axis, y-axis and
z-axis respectively.
A specific rotation can be specified by more then one set of Euler
angles or quaternions. For Euler angles [pi+alfa, -beta, pi+gamma] is the same
rotation as [alfa, beta, gamma]. For quaternions [-qx,-qy,-qz,-q0] is the same
rotation as [qx,qy,qz,q0]. If q = cos(phi/2)+sin(phi/2)*u and
-q = cos(chi/2)+sin(chi/2)*v (for unit vectors u and v), then v=-u and
chi/2=180-phi/2, i.e. chi=360-phi. So -q is a rotation over -phi after changing
the sign of the rotation vector.
The conversion /to_euler always returns a positive beta in [0,180].
MODIFICATION HISTORY:
FEB-2003, Paul Hick (UCSD/CASS)
MAR-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Rewrite. Moved scalar quaternion component from first to last position
Improved calculation of quaternions from DCM or Euler angles
(avoiding singularities for q0 close to zero).
[Previous]
[Next]
NAME:
CvSky
PURPOSE:
Converts between ecliptic, heliographic, equatorial and geographic
coordinates
CATEGORY:
smei/gen/idl/ephem
CALLING SEQUENCE:
FUNCTION CvSky, UT, fromvectors , $
from_ecliptic = from_ecliptic , $
from_centered_ecliptic = from_centered_ecliptic , $
from_equatorial = from_equatorial , $
from_galactic = from_galactic , $
from_heliographic = from_heliographic , $
from_centered_heliographic = from_centered_heliographic, $
from_geographic = from_geographic , $
from_gse = from_gse , $
from_gsm = from_gsm , $
from_rtn = from_rtn , $
from_ihg = from_ihg , $
from_solar_elopa = from_solar_elopa , $
to_ecliptic = to_ecliptic , $
to_centered_ecliptic = to_centered_ecliptic , $
to_equatorial = to_equatorial , $
to_galactic = to_galactic , $
to_heliographic = to_heliographic , $
to_centered_heliographic = to_centered_heliographic , $
to_geographic = to_geographic , $
to_rtn = to_rtn , $
to_gse = to_gse , $
to_gsm = to_gsm , $
to_ihg = to_ihg , $
to_solar_elopa = to_solar_elopa , $
heliocentric = heliocentric , $
bodycentric = bodycentric , $
degrees = degrees , $
rectangular = rectangular , $
euler_angles = euler_angles , $
euler_info = euler_info , $
silent = silent
INPUTS:
UT array; type: standard time structure
times (UT); Note that if /rectangular is set then UT
can only be an array[1]
(i.e. a single time must be specified) IS THIS STILL TRUE?
fromvectors array;
OPTIONAL INPUTS:
from_ecliptic = from_ecliptic
from_centered_ecliptic = from_centered_ecliptic
from_heliographic = from_heliographic
from_centered_heliographic = from_centered_heliographic
from_geographic = from_geographic
from_equatorial = from_equatorial
from_rtn = from_rtn
from_gse = from_gse
from_gsm = from_gsm
from_ihg = from_ihg
array [2,n] or array[3,n]
/rectangular NOT set: In[0,*] is longitude, In[1,*] is latitude;
In[2,*] (optional?) is radial distance
/rectangular set: rectangular (x,y,z) coordinates
Alternatively, fromvectors contains the input vectors and the
appropriate keyword /from* is SET.
/to_ecliptic conversion to ecliptic coordinates
/to_centered_ecliptic
conversion to sun-centered ecliptic coordinates
(/heliocentric NOT set) or earth-centered ecliptic
coordinates (/heliocentric SET)
/to_heliographic conversion to heliographic coordinates
/to_centered_heliographic
conversion to earth-centered heliographic coordinates
/to_geographic conversion to geographic coordinates
/to_equatorial conversion to equatorial ccordinates
/to_rtn conversion to magnetic RTN coordinates
/to_gse conversion to magnetic GSE coordinates
/to_gsm conversion to magnetic GSM coordinates
/to_ihg conversion to inertial heliographic coordinates
/heliocentric used in conjunction with from_centered_ecliptic and
to_centered_ecliptic keywords: sun-centered if /heliocentric
is NOT set; earth-centered if /heliocentric SET
/degrees input and output angles are in degrees
/rectangular input and output is in rectangular coordinates
silent=silent suppresses information messages
INPUTS/OUTPUTS:
Result array[2,*] or array[3,*]; type: double
output array according to selected /to... keyword
if /rectangular is set then the output array will be
in rectangular (x,y,z) coordinates; otherwise spherical
coordinates (longitude, latitude, and (optional) radial
distance is returned
OPTIONAL OUTPUTS:
euler_angles=euler_angles
array[3,*]; type: double
Euler angles applied to input coordinates.
euler_info=euler_info
scalar; type: string
descriptive string describing the transformation
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
CombineRotations, CvSky_Equatorial, CvSky_GSE, CvSky_GSM, CvSky_Galactic
CvSky_Geographic, CvSky_Heliographic, CvSky_IHG, CvSky_RTN, EulerRotate, InitVar
IsType, REVERSE, SuperArray, ToDegrees, big_eph, destroyvar, jpl_body, who_am_i
CALLED BY:
Carrington, CvPrecess, CvSky_GSM, CvSky_Solar_EloPa, EarthSky3DLoc
EarthTransit3DLoc, GetColors [2], GetColors [3], InsituTimeSeries
PlotCoronagraph, PlotEarthSkymap [1], PlotEarthSkymap [2], PlotEarthSkymap [3]
PlotEarthSkymap [4], PlotEloTimeMap, PlotPolarSkymap, RemoteView
RemoteView_BodyLoc, RemoteView_Display2D, RemoteView_FovTilt
RemoteView_Init_View, RemoteView_ZEclipticPlane, RotationMeasure
Sky_ColorView [1], Sky_ColorView [2], big_elongation, big_eph, big_orbit
coriolis_map, cvsmei, haystack_2006, ipsv [1], ipsv [2], ipsv [3], jpl_eph, jpl_test
losgeometry, lospos, mpc_eph, mpc_orbit_eph, qRemoteView_ChangeCoordinates
qRemoteView_Pick, smei_frm_where, smei_sky, smei_sky_getmask, smei_zld_model
smei_zld_remove [1], smei_zld_remove [2], ss_map, usno_eph, vu_coronagraph
vu_elotime, vu_extract, vu_linecut, vu_planarcut, vu_point_source, vu_spherecut
vu_thomson_antifish, vu_thomson_hammer, vu_timeseries, vu_vox_drawelatitude
vu_vox_drawelongitude, vu_vox_draworbit, vu_vox_write
PROCEDURE:
For the regular celestial coordinate frames see e.g.
R. Green, Spherical Astronomy, Cambridge UP, 1985, Section 17.7, p. 430.
For magnetic RTN,GSE and GSM coordinate frames, see
???
GSE used for magnetic measurements near Earth
x-axis towards Sun, z-axis towards ecliptic North pole
GSM variation on GSE
x-axis towards Sun, z-axis along projection of Earth's magnetic
dipole in plane perpendicular to x-axis. The y-z plane is the
same for GSE and GSM.
RTN used for magnetic field measurements in a heliographic reference
frame. x-axis (R-axis) points radially away from the Sun
The y-axis (T-axis) is the cross product of solar north (solar
rotations axis) and R-axis. The z-axis (N-axis) is the cross product
of R and T-axis.
For an observer in the solar equator the N-axis points toward solar North.
For an observer at Earth x(RTN) = - x(GSE) = -x(GSM), and
three magnetic coordinate frames share the same y-z plane)
IHG used for outer-heliospheric studies. z-axis is toward solar North.
x-axis is towards ascending node of solar equator on ecliptic.
HEEQ (heliocentric Earth equatorial)
z-axis parallel to the Sun's rotation axis; x- axis towards the
intersection of the solar equator and the solar central meridian
as seen from the Earth. Sometimes called heliocentric solar (HS).
In this frame the Earth is at longitude zero.
Not implemented explicitly, but can be reproduced using
from_centered_heliographic or to_centered_heliographic in conjunction
with /heliocentric.
MODIFICATION HISTORY:
MAR-1997, Paul Hick (UCSD/CASS)
adapted from FORTRAN version
MAR-1998, Paul Hick (UCSD/CASS)
now accepts multi-dim arrays
JAN-2001, Paul Hick (UCSD/CASS)
added /rectangular keyword
SEP-2001, Tamsen Dunn, Paul Hick (UCSD/CASS)
added transformations from/to magnetic frames RTN, GSE and GSM
SEP-2006, Paul Hick (UCSD/CASS)
Added fromvectors argument
Added from_centered_ecliptic and to_centered_ecliptic keywords
Added euler_angles and euler_info keywords
Added silent keyword
Added underscores to to* and from* keywords
OCT-2006, Paul Hick (UCSD/CASS)
Now accumulates all Euler angles and calls EulerRotate only once
to perform the coordinate transformation.
JUN-2008, Paul Hick (UCSD/CASS)
Added /to_ihg and from_ihg=from_ihg keywords.
DEC-2009, Paul Hick (UCSD/CASS)
Bugfix. If fromvectors is used, in combination with more than one
of the from_* keywords, routine would abort.
JUL-2012, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added from_centered_heliographic and to_centered_heliographic
[Previous]
[Next]
NAME:
CvSky_Equatorial
PURPOSE:
Euler angles for Ecliptic --> Equatorial conversion
CATEGORY:
smei/gen/idl/ephem
CALLING SEQUENCE:
abc = CvSky_Equatorial(UT [, /degrees)
INPUTS:
UT array[n]; type: time structure
OPTIONAL INPUT PARAMETERS:
/degrees if set, all angles are in degrees (default: radians)
OUTPUTS:
abc array[3,n]; type: double
Euler angles for converting from
ecliptic to equatorial coordinates
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
SubArray, SuperArray, TimeGet, ToDegrees
CALLED BY:
CvSky, CvSky_Galactic
PROCEDURE:
Angle ecliptic-equator as in:
Spherical Astronomy, R.M. Green, Cambridge UP, p. 220, eq 9.25
MODIFICATION HISTORY:
AUG-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
CvSky_Galactic
PURPOSE:
Euler angles for Ecliptic --> Galactic conversion
CATEGORY:
smei/gen/idl/ephem
CALLING SEQUENCE:
FUNCTION CvSky_Galactic, UT, degrees=Degrees
INPUTS:
UT array[n]; type: time structure
OPTIONAL INPUT PARAMETERS:
/degrees if set, all angles are in degrees (default: radians)
OUTPUTS:
abc array[3,n]; Euler angles for converting from
ecliptic to heliographic coordinates
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
CombineRotations, CvRotation, CvSky_Equatorial, CvSky_Precess, REVERSE, TimeSet
CALLED BY:
CvSky
PROCEDURE:
Angle ecliptic-equator as in:
Spherical Astronomy, R.M. Green, Cambridge UP, p. 41, eq 2.31
MODIFICATION HISTORY:
SEP-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
CvSky_Geographic
PURPOSE:
Euler angles for Ecliptic to Geographic conversion
CATEGORY:
smei/gen/idl/ephem
CALLING SEQUENCE:
FUNCTION CvSky_Geographic, UT, degrees=Degrees
INPUTS:
UT array[n]; type: time structure
OPTIONAL INPUT PARAMETERS:
/degrees if set all angles are in degrees (default: radians)
OUTPUTS:
abc array[3,n]; type: float
Euler angles
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
SubArray, SuperArray, TimeGet, ToDegrees
CALLED BY:
CvSky
PROCEDURE:
MODIFICATION HISTORY:
AUG-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
CvSky_GSE
PURPOSE:
Euler angles for Ecliptic to GSE conversion
CATEGORY:
smei/gen/idl/ephem
CALLING SEQUENCE:
FUNCTION CvSky_GSE, UT, degrees=degrees
INPUTS:
UT array[n]; type: time structure
OPTIONAL INPUT PARAMETERS:
/degrees if set all angles are in degrees (default: radians)
OUTPUTS:
Result array[3,n]; type: float
Euler angles
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
SubArray, big_eph, jpl_body
CALLED BY:
CvSky
PROCEDURE:
Geocentric Solar Ecliptic (GSE) coordinates:
x-axis points from Earth to Sun
y-axis is in the ecliptic plane opposing orbital motion
z-axis points to ecliptic north
MODIFICATION HISTORY:
AUG-2002, Paul Hick (UCSD/CASS)
OCT-2006, Pual Hick (UCSD/CASS; pphick@ucsd.edu)
Replaced NewcombSun by big_eph
[Previous]
[Next]
NAME:
CvSky_GSEQ
PURPOSE:
Euler angles for Ecliptic to GSEQ conversion
CATEGORY:
smei/gen/idl/ephem
CALLING SEQUENCE:
FUNCTION CvSky_GSEQ, UT, degrees=degrees
INPUTS:
UT array[n]; type: time structure
OPTIONAL INPUT PARAMETERS:
/degrees if set all angles are in degrees (default: radians)
OUTPUTS:
Result array[3,n]; type: float
Euler angles
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
SubArray, SuperArray, big_eph, jpl_body
PROCEDURE:
Geocentric Solar Equatorial (GSEQ) coordinates:
x-axis points from Earth to Sun
y-axis is parallel to Sun's equatorial plane pointing
east of the Sun
z-axis is pointing north and completes righthanded
coordinate frame
The Sun's rotation axis lies in the x-z plane.
MODIFICATION HISTORY:
OCT-2006, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
CvSky_GSM
PURPOSE:
Euler angles for Ecliptic to GSM conversion
CATEGORY:
smei/gen/idl/ephem
CALLING SEQUENCE:
FUNCTION CvSky_GSM, UT, degrees=degrees
INPUTS:
UT array[n]; type: time structure
OPTIONAL INPUT PARAMETERS:
/degrees if set all angles are in degrees (default: radians)
OUTPUTS:
Result array[3,n]; type: float
Euler angles
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
CvSky, SubArray, SuperArray, TimeGet, ToDegrees, ToRadians, big_eph, jpl_body
CALLED BY:
CvSky
PROCEDURE:
Geocentric Solar Magnetospheric (GSM) coordinates
x-axis points from Earth to Sun
z-axis is the northern magnetic pole, projected in plane perp to x-axis.
The difference between the GSM system and the GSE
and GSEQ is a rotation about the X-axis.
MODIFICATION HISTORY:
AUG-2002, Paul Hick (UCSD/CASS)
JUN-2007, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Bugfix. The conversion of UT to years since 2000 somehow
lost the subtraction of 2000.
[Previous]
[Next]
NAME:
CvSky_HEEQ
PURPOSE:
Euler angles for Ecliptic to Heliographic conversion
CATEGORY:
smei/gen/idl/ephem
CALLING SEQUENCE:
FUNCTION CvSky_HEEQ, UT, degrees=degrees, longitude=longitude
INPUTS:
UT array[n]; type: time structure
OPTIONAL INPUT PARAMETERS:
longitude array[n] or scalar; type: float; default: 0
heliographic longitude(s). See PROCEDURE.
/degrees if set all angles are in degrees (default: radians)
OUTPUTS:
abc array[3,n]; type: float
Euler angles for rotation from ecliptic to heliographic
coordinate frame
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
AngleRange, IsType, SubArray, SuperArray, TimeGet, TimeUnit, ToDegrees
SEE ALSO:
CvSky_IHG
PROCEDURE:
The ecliptic longitude for the ascending node and the inclination of
equator to ecliptic are from R. Green, "Spherical astronomy", p. 431
If keyword 'longitude' is specified than the Euler angles refer
to a rotation from an ecliptic reference frame to a
heliographic reference frame with longitude measured from the
heliographic meridian through 'longitude', instead of the
heliographic prime meridian (i.e. heliographic longitude zero).
This is useful, for instance, to set up 'earth-centered'
heliographic coordinates with heliographic longitude measured
from the heliographic longitude of Earth.
MODIFICATION HISTORY:
AUG-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
CvSky_Heliographic
PURPOSE:
Euler angles for Ecliptic to Heliographic conversion
CATEGORY:
smei/gen/idl/ephem
CALLING SEQUENCE:
FUNCTION CvSky_Heliographic, UT, degrees=degrees, longitude=longitude
INPUTS:
UT array[n]; type: time structure
OPTIONAL INPUT PARAMETERS:
longitude array[n] or scalar; type: float; default: 0
heliographic longitude(s). See PROCEDURE.
/degrees if set all angles are in degrees (default: radians)
OUTPUTS:
abc array[3,n]; type: float
Euler angles for rotation from ecliptic to heliographic
coordinate frame
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
AngleRange, IsType, SubArray, SuperArray, TimeGet, TimeUnit, ToDegrees
CALLED BY:
CvSky, vu_solardisk
SEE ALSO:
CvSky_IHG
PROCEDURE:
The ecliptic longitude for the ascending node and the inclination of
equator to ecliptic are from R. Green, "Spherical astronomy", p. 431
If keyword 'longitude' is specified than the Euler angles refer
to a rotation from an ecliptic reference frame to a
heliographic reference frame with longitude measured from the
heliographic meridian through 'longitude', instead of the
heliographic prime meridian (i.e. heliographic longitude zero).
This is useful, for instance, to set up 'earth-centered'
heliographic coordinates with heliographic longitude measured
from the heliographic longitude of Earth.
MODIFICATION HISTORY:
AUG-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
CvSky_IHG
PURPOSE:
Euler angles for Ecliptic to IHG conversion
CATEGORY:
smei/gen/idl/ephem
CALLING SEQUENCE:
FUNCTION CvSky_IHG, UT, degrees=degrees
INPUTS:
UT array[n]; type: time structure
OPTIONAL INPUT PARAMETERS:
/degrees if set all angles are in degrees (default: radians)
OUTPUTS:
abc array[3,n]; type: float
Euler angles
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
SubArray, SuperArray, TimeGet, TimeUnit, ToDegrees
CALLED BY:
CvSky
SEE ALSO:
CvSky_Heliographic
PROCEDURE:
The IHG z-axis is along the solar rotation axis (solar north).
The x-axis is toward the ascending node of the solar equator
on the ecliptic. See
http://nssdcftp.gsfc.nasa.gov/miscellaneous/documents/b46547.txt
and Burlaga, "MHD Processes in the Outer Heliosphere",
Space Sci. Rev. 39, 255-316, 1984.
Note that the nssdc website says:
"The X(IHG) axis drifts slowly with time, approximately one
degree per 72 years", while the Burlaga paper says (p. 260)
".. we shall take the X(IHG) axis along the direction of the
ascending node in 1900". I.e. the Burlaga paper seems to want
the X(IHG) axis fixed at epoch 1900.
Here we follow the description of the website.
The ecliptic longitude for the ascending node and the
inclination of equator to ecliptic are from
R. Green, "Spherical astronomy", p. 431
MODIFICATION HISTORY:
JUN-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
CvSky_Precess
PURPOSE:
Euler angles for precesion of equatorial coordinates from epoch UT to J2000
CATEGORY:
smei/gen/idl/ephem
CALLING SEQUENCE:
abc = CvSky_Precess(UT [, /degrees)
INPUTS:
UT array[n]; type: time structure
OPTIONAL INPUT PARAMETERS:
/degrees if set, all angles are in degrees (default: radians)
OUTPUTS:
abc array[3,n]; Euler angles for precession from epoch UT to J2000
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
SubArray, SuperArray, TimeGet, ToDegrees
CALLED BY:
CvPrecess, CvSky_Galactic
PROCEDURE:
Precession angles from:
Spherical Astronomy, R.M. Green, Cambridge UP, p. 219, eq 9.23
MODIFICATION HISTORY:
DEC-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
CvSky_RTN
PURPOSE:
Euler angles for Heliographic to RTN conversion at Earth
CATEGORY:
smei/gen/idl/ephem
CALLING SEQUENCE:
FUNCTION CvSky_RTN, UT_or_LOC, degrees=degrees
INPUTS:
UT_or_LOC array[3,n]; type: float
heliocentric locations in heliographic
coordinates (heliographic longitude, latitude and
distance)
array[n]; type: time structure
UT times; in this case the heliocentric locations
is assumed to be at Earth at the specified times
OPTIONAL INPUT PARAMETERS:
/degrees if set all angles are in degrees (default: radians)
OUTPUTS:
Result array[3,n]; type: float
Euler angles to rotate from heliographic
coordinates to RTN coordinates
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
IsTime, SubArray, big_eph, jpl_body
CALLED BY:
CvSky, RotationMeasure
PROCEDURE:
RTN (Radial, Tangential, Normal) coordinates at point P:
x-axis = radial direction
y-axis = in tangent plane, parallel to solar equator
z-axis = in tangent plane, pointing toward the solar north pole
MODIFICATION HISTORY:
AUG-2002, Paul Hick (UCSD/CASS)
OCT-2006, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added option to directly enter heliocentric locations
in addition to always using Earth's location.
[Previous]
[Next]
NAME:
CvSky_Solar_EloPa
PURPOSE:
Convert between solar elongation, and position angle
to one of the coordinate frames supported by CvSky
and v.v
CATEGORY:
smei/gen/idl/ephem
CALLING SEQUENCE:
FUNCTION CvSky_Solar_EloPa, UT, fromvectors , $
from_solar_elopa = from_solar_elopa , $
to_solar_elopa = to_solar_elopa , $
degrees = degrees , $
euler_angles = euler_angles , $
euler_info = euler_info , $
silent = silent , $
_extra = _extra
INPUTS:
UT array; type: standard time structure
times (UT); Note that if /rectangular is set then UT
can only be an array[1]
(i.e. a single time must be specified)
fromvectors array;
OPTIONAL INPUTS:
/degrees input and output angles are in degrees
silent=silent suppresses information messages
INPUTS/OUTPUTS:
Result array[2,*] or array[3,*]; type: double
output array according to selected /to... keyword
spherical coordinates (longitude, latitude, and
(optional) radial distance is returned
OPTIONAL OUTPUTS:
euler_angles=euler_angles
array[3,*]; type: double
Euler angles applied to input coordinates.
euler_info=euler_info
scalar; type: string
descriptive string describing the transformation
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
CvSky, InitVar, IsType, SubArray, ToDegrees
PROCEDURE:
MODIFICATION HISTORY:
APR-2015, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added from_centered_heliographic and to_centered_heliographic
[Previous]
[Next]
NAME:
cvsmei
PURPOSE:
Convert positions between various SMEI-related coordinate frames
CATEGORY:
camera/idl/toolbox
CALLING SEQUENCE:
FUNCTION cvsmei, $
camera = camera , $
quaternion = quaternion , $
mode = mode , $
from_mode = from_mode , $
to_mode = to_mode , $
from_ccd = from_ccd , $
from_camera = from_camera, $
from_equatorial = from_equatorial , $
from_helioecliptic = from_helioecliptic, $
from_map = from_map , $
time = time , $
rectangular = rectangular, $
degrees = degrees , $
force_unit = force_unit , $
to_ccd = to_ccd , $
to_camera = to_camera , $
to_equatorial = to_equatorial, $
to_helioecliptic = to_helioecliptic, $
to_map = to_map , $
inside = inside , $
boolean = boolean , $
ndim = ndim , $
silent = silent , $
count = count
INPUTS:
OPTIONAL INPUT PARAMETERS:
from_map array[2,n]; type: numerical
scalar; type: string
Pixel locations in a skymap, specified as a zero-base
array index (i.e. lower-left pixel is [0,0].
If set to string 'MAP' then the position of all
pixels in the skymap for the specified mode are used.
The type of map is set using keywords "mode" or "from_mode"
(see below)
from_equatorial array[2,n] or array[3,n]
positions in the sky as spherical or rectangular
equatorial coordinates.
/rect NOT SET: spherical coordinates
rvec[0,*] is RA;
rvec[1,*] is declination
rvec[3,*] (usually the distance)
/rect SET: rectangular coordinates
rvec[0,*] is x-coordinate (toward vernal equinox)
rvec[1,*] is y-coordinate
rvec[3,*] is z-coordinate (toward equatorial north)
from_helioecliptic
array[2,n] or array[3,n]
positions in the sky as spherical or rectangular
helioecliptic coordinates
/rect NOT SET: spherical coordinates
rvec[0,*] is helioecliptic (sun-centered) longitude;
rvec[1,*] is ecliptic longitude
rvec[3,*] (usually the distance)
/rect SET: rectangular coordinates
rvec[0,*] is x-coordinate (toward sun)
rvec[1,*] is y-coordinate
rvec[3,*] is z-coordinate (toward ecliptic north)
from_camera array[3,n]
positions in the sky as unit vectors in the
UCSD camera frame.
from_ccd array[2,n]; type: double
scalar; type: string
If set to string 'CCD' then the position of all
pixels in the image for the specified mode are used.
pixel locations on the CCD, specified as a zero-based
array index (i.e. lower-left pixel is [0,0])
The unit is the pixel size for mode 0.
Override this by explicitly setting the 'mode' keyword
(so set mode=0 for engineering mode pixels).
/to_map returns array[2,n]; type: double
output is in pixel coodinates in a sky map
selected with the "mode" or "to_mode" keywords
/to_equatorial returns array[3,n] or array[2,n]; type: double
output is in equatorial sky coordinates (rectangular
array[3,n ] if /rectangular is SET.
array[2,n] (RA and dec) if /rectangular NOT set.
/to_helioecliptic
returns array[3,n] or array[2,n]; type: double
output is in helioecliptic sky coordinates (rectangular
array[3,n ] if /rectangular is SET.
array[2,n] (helioecliptic (sun-centered) longitude and latitude
if /rectangular NOT set.
/to_camera returns array[3,n]; type: double
output is a unitvector in the UCSD camera frame
(with z-axis along camera optical axis)
/to_ccd returns array[2,n]; type: double
output is in pixel coordinates on the CCD
The units are mode-dependent.
/rectangular only used if 'from_equatorial' or /to_equatorial is set
if set then 'from_equatorial' is in rectangular
coordinates. The 1st dimension MUST be 3; if it is
not program execution halts.
If /to_equatorial is set then the output is in
rectangular coordinates.
/degrees only used if 'from_equatorial' or /to_equatorial is set
if set, all angles are in degrees (default: radians).
/force_unit only used if 'from_equatorial' or 'from_camera' are set
forces conversion of vectors to unit vectors
For 'from_equatorial' vectors converted to camera
coordinates must be unit vectors. By default only
vectors deviating from unit vectors by more than the
machine precision are explicitly scaled to unit vectors.
camera=camera scalar; type: integer; default: 1
camera number (1,2 or 3)
This determines the fixed S/C-to-camera quaternion for
conversions between camera and equatorial frames;
and CCD-related parameters (fov size, etc.) for
conversions between camera and ccd coordinates
quaternion=quaternion
array[4]; type: double
Coriolis S/C quaternion
Only needed for conversions between camera frame
and equatorial frame.
from_mode=from_mode
to_mode=to_mode
mode=mode scalar; type: integer or string; default: 0
If /to_ccd and/or /from_ccd are set:
mode number (0,1 or 2)
The 'from_mode' and 'to_mode' keyword are necessary only
when both 'from_ccd' and /to_ccd are used (i.e. when
converting CCD coordinates between different modes.
'from_mode' takes priority over 'mode' if from_ccd is set.
'to_mode' takes priority over 'mode' if /to_ccd is set.
If /to_map and/or /from_map are set:
mode string: "lores", "eqmap", "npmap", "spmap", or "eclsun".
"lores" (low-resolution skymap),
"eqmap" (high-resolution equatorial map),
"npmap" (hi-res map of north pole) or
"spmap" (hi-res map of south pole)
"eclsun" (lo-res sun-centered map)
The 'from_mode' and 'to_mode' keyword are necessary only
when both 'from_map' and /to_map are used (i.e. when
converting between different types of skymap.
/boolean only used for conversions between camera frame and
CCD coordinates.
if set then the output array 'inside' is a byte array of zeros
and ones indicating whether the corresponding vectory is
outside/inside the field of view (instead of a list of
indices from the IDL 'where' function identifying vectors
inside the field of view).
OUTPUTS:
R array[3,n]; type: float
output locations as specified by /to_equatorial, /to_camera
or /to_ccd keyword.
OPTIONAL OUTPUT PARAMETER:
inside=inside array[n]; type: long (/boolean NOT set) or byte (/boolean set).
Will only exist for conversion between CCD and sky coordinates
(either camera or equatorial)..
If /boolean is not set then 'inside' is a list of indices of
vectors inside field of view
If /boolean is set then 'inside' is a byte array with 0 for
vectors inside or 1 for vectors inside the field of view.
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
PRO bold, qImage_cw_DrawEphem, qImage_cw_Where, smei_findobj, smei_findpnt
smei_frm_cvhdr, smei_frm_where, smei_sky_atlocation, smei_sky_cleanedge_fix
smei_sky_cleanedge_sample, smei_sky_getmask, smei_sky_read, smei_sky_track
smei_star_fit, smei_star_remove, smei_zld_remove [1], smei_zld_weekly
stardistance
COMMON BLOCKS:
common cvsmei_save, map_modes, str_modes, cxy_modes, dpb_modes, dim_modes, $
from_maptype_save, to_maptype_save
CALLS: ***
AngleRange, BadValue, CV_COORD, CvRotation, CvSky, InitVar, Inside_Wedge, IsTime, IsType
SubArray, SyncDims, ToDegrees, ToRadians, boost, cvsmei_init, flt_string, gridgen
smei_cam_quaternion, smei_camera, smei_radial2theta, smei_theta2radial, who_am_i
PROCEDURE:
There are four groups of coordinate systems involved:
- CCD coordinates (for three different modes)
- The native camera coordinate frame
- The J2000 equatorial coordinate frame
- Skymap coordinates (for lores maps, and three different
hires maps: equator, north and south pole)
Conversions are done as follows:
CCD <---> Camera <---> J2000 Equatorial <---> Skymaps
Phase 1:
if CCD if /to_ccd then convert to CCD (m0)
if not /to_ccd then convert to Camera
if Camera do nothing
if J2000 do nothing
if Skymaps convert to J2000
After phase 1 we have Camera or J2000 coordinates
unless /to_ccd was set (then we have CCD m0 coordinates)
Phase 2:
if Camera if /to_map then convert to J2000
if J2000 if /to_ccd then convert to Camera
We now have coordinates that are at most one
conversion from the final frame.
Phase 3:
if /to_ccd convert from CCD (m0) or Camera
if /to_camera already in Camera or convert from J2000
if /to_equatorial already in J2000 or convert from Camera
if /to_map convert from J2000
Conversions between camera coordinates and equatorial
coordinates require a Coriolis quaternion and a camera
quaternion. This is provided by explicitly specifying a
camera number and Coriolis quaternion through keywords
'camera' and 'quaternion'
MODIFICATION HISTORY:
MAR-2005, Paul Hick (UCSD/CASS)
Extracted from smei_sky2ccd.
MAR-2008, Paul Hick (UCSD/CASS)
Bug fix in conversion from hires equat map to polar
maps. Force output for RA into [0,360]
APR-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Fairly substantial rewrite to incorporate conversions
from and to helioecliptic maps.
[Previous]
[Next]
NAME:
cvsmei_init
PURPOSE:
Set scaling parameters for cvsmei
CATEGORY:
camera/idl/toolbox
CALLING SEQUENCE:
PRO cvsmei_init , $
mode = mode , $
str = str , $
cxy = cxy , $
mpb = mpb , $
dim = dim , $
degrees = degrees , $
from_maptype = from_maptype , $
to_maptype = to_maptype , $
reset = reset , $
silent = silent , $
get = get
INPUTS:
OPTIONAL INPUT PARAMETERS:
mode = mode scalar; type: string
map type: one of 'lores','eqmap','npmap','spmap','eqfull','eclsun'
str = str scalar; type: string
cxy = cxy array[2]; type: any
mpb = mpb scalar; type: double
dim = dim array[2]; type: integer
/degrees if set, angular units are degrees (default: radians)
/get if set, retrieve settings
/reset if set, reset everything for standard full-sky maps
/silent suppress informational messages
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, ToDegrees, destroyvar
CALLED BY:
cvsmei, smei_findobj, smei_zld_remove [1]
COMMON BLOCKS:
common cvsmei_save, map_modes, str_modes, cxy_modes, dpb_modes, dim_modes, $
from_maptype_save, to_maptype_save
PROCEDURE:
Common block updates
MODIFICATION HISTORY:
FEB-2006, Paul Hick (UCSD/CASS)
APR-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added mode 'eclsun'
[Previous]
[Next]
NAME:
CvT3d
PURPOSE:
Implement three-dimensional transformation of coordinate systems.
!!! t3d provides a transformation matrix for transforming vectors in a
fixed coordinate frame. This routine provides a matrix for
transforming the coordinate frame, while keeping the vectors constant.
Accumulates one or more sequences of translation,
scaling, rotation, (perspective, and oblique) transformations
and returns the resulting 4x4 transformation matrix.
CATEGORY:
Number strangling
CALLING SEQUENCE:
pt = CvT3D(translate=T, scale=S, rotate=R, /degrees)
OPTIONAL INPUTS:
/degrees if set, all angles are assumed to be in degrees (default: radians)
matrix=Matrix float array[4,4]
Used as starting transformation matrix
if absent the identity matrix is used as starting point.
vector=Vector float array[3,*]
x,y,z coordinates in original coordinate frame.
If present, the transformation matrix is applied and the
result is returned, instead of the matrix itself.
All inputs to T3D are in the form of keywords. Any, all, or none of
the following keywords can be present in a call to T3D.
The transformation specified by each keyword is performed in the
order of their descriptions below (e.g., if both TRANSLATE and
SCALE are specified, the translation is done first):
Translate 3-element vector of the translations in the X, Y, and Z directions.
Scale 3-element vector of scale factors for the X, Y, and Z axes.
Rotate n-element vector of the rotations, about the X, Y, and Z axes.
The elements in Rotate are interpreted in sets of 3 for rotations
around X, Y, and Z axes.
XYexch exchange the X and Y axes.
XZexch exchange the X and Z axes.
YZexch exchange the Y and Z axes.
Not implemented
PERSPECTIVE Perspective transformation. This parameter is a scalar (p)
that indicates the Z distance of the center of the projection.
Objects are projected into the XY plane at Z=0, and the "eye"
is at point [0,0,p].
OBLIQUE: A two-element vector of oblique projection parameters.
Points are projected onto the XY plane at Z=0 as follows:
x' = x + z(d COS(a)), and y' = y + z(d SIN(a)).
where OBLIQUE[0] = d, and OBLIQUE[1] = a.
OUTPUTS:
If keyword vector is not specified, then the 4x4 transformation matrix is returned.
If keyword vertor is specified, then the transformation matrix is applied and
the result is returned as a float array[3,*]
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
ToRadians
CALLED BY:
EulerRotate, PlotSolarDisk, RemoteView_FOV_Cube, RemoteView_FOV_loc
RemoteView_FovTilt, qvu_draw, vu_solardisk
RESTRICTIONS:
This routine implements general rotations about the three axes.
PROCEDURE:
> See also IDL procedure t3d.pro
> If a set of vectors is given in the form x[3,*] (containing
x,y,z-coordinates in the original coordinate frame), then
T3DMatrix(..)#x is an array[3,*] with coordinates in the new
coordinate frame.
> Using the /xyexch, /yzexch or /zxexch keywords turns a
right-handed coordinate frame into a left-handed frame. This impacts
the interpretation of the rotation angles (positive rotations are
counter-clockwise in a right-handed coordinate frame), and is better
avoided. These exchange keywords are only useful as final
transformations to swap the corresponding vector coordinates.
MODIFICATION HISTORY:
DMS, Nov, 1987.
DMS, June 1990. Fixed bug that didn't scale or translate
matrices with perspective properly.
DMS, July, 1996. Added MATRIX keyword.
FEB-1998, Paul Hick (UCSD/CASS, pphick@ucsd.edu); based on T3D.pro
[Previous]
[Next]
NAME:
CW_FIELD
PURPOSE:
This widget cluster function manages a data entry field widget.
The field consists of a label and a text widget. CW_FIELD's can
be string fields, integer fields or floating-point fields. The
default is an editable string field.
CATEGORY:
Widget Clusters.
CALLING SEQUENCE:
Result = CW_FIELD(Parent)
INPUTS:
Parent: The widget ID of the widget to be the field's parent.
KEYWORD PARAMETERS:
TITLE: A string containing the text to be used as the label for the
field. The default is "Input Field:".
VALUE: The initial value in the text widget. This value is
automatically converted to the type set by the STRING,
INTEGER, and FLOATING keywords described below.
UVALUE: A user value to assign to the field cluster. This value
can be of any type.
UNAME: A user supplied string name to be stored in the
widget's user name field.
FRAME: The width, in pixels, of a frame to be drawn around the
entire field cluster. The default is no frame.
RETURN_EVENTS: Set this keyword to make cluster return an event when a
<CR> is pressed in a text field. The default is
not to return events. Note that the value of the text field
is always returned when the WIDGET_CONTROL, field, GET_VALUE=X
command is used.
ALL_EVENTS: Like RETURN_EVENTS but return an event whenever the
contents of a text field have changed.
COLUMN: Set this keyword to center the label above the text field.
The default is to position the label to the left of the text
field.
ROW: Set this keyword to position the label to the left of the text
field. This is the default.
XSIZE: An explicit horizontal size (in characters) for the text input
area. The default is to let the window manager size the
widget. Using the XSIZE keyword is not recommended.
YSIZE: An explicit vertical size (in lines) for the text input
area. The default is 1.
STRING: Set this keyword to have the field accept only string values.
Numbers entered in the field are converted to their string
equivalents. This is the default.
FLOATING: Set this keyword to have the field accept only floating-point
values. Any number or string entered is converted to its
floating-point equivalent.
INTEGER: Set this keyword to have the field accept only integer values.
Any number or string entered is converted to its integer
equivalent (using FIX). For example, if 12.5 is entered in
this type of field, it is converted to 12.
LONG: Set this keyword to have the field accept only long integer
values. Any number or string entered is converted to its
long integer equivalent (using LONG).
FONT: A string containing the name of the X Windows font to use
for the TITLE of the field.
FIELDFONT: A string containing the name of the X Windows font to use
for the TEXT part of the field.
NOEDIT: Normally, the value in the text field can be edited. Set this
keyword to make the field non-editable.
OUTPUTS:
This function returns the widget ID of the newly-created cluster.
CALLS: ***
CW_FIELD_EVENT, CW_FIELD_EXPONENT, CW_FIELD_FLOAT, CW_FIELD_GET, CW_FIELD_INT
CW_FIELD_SET, CW_FIELD_VALIDATE, CW_FIELD_VALUE
CALLED BY:
makemovie [1], makemovie [2], qBar, qEphem, qGlitch, qImage, qImage_cw, qImage_cw_SMEI
qLine, qLine_XBase, qLine_YBase, qRemoteView, qSave2File, qShow, qTool, qView, qnagoya
qset_page, qslider_cw, qsmei_sky, qvox, qvu
COMMON BLOCKS:
None.
PROCEDURE:
Create the widgets, set up the appropriate event handlers, and return
the widget ID of the newly-created cluster.
EXAMPLE:
The code below creates a main base with a field cluster attached
to it. The cluster accepts string input, has the title "Name:", and
has a frame around it:
base = WIDGET_BASE()
field = CW_FIELD(base, TITLE="Name:", /FRAME)
WIDGET_CONTROL, base, /REALIZE
MODIFICATION HISTORY:
Written by: Keith R. Crosley June 1992
KRC, January 1993 -- Added support for LONG
integers.
AB, 7 April 1993, Removed state caching.
JWG, August 1993, Completely rewritten to make
use of improved TEXT widget functionality
ACY, 25 March, 1994, fix usage of FRAME keyword
KDB, May 1994, Initial value =0 would result
in a null text field. Fixed
keyword check.
CT, RSI, March 2001: Pass keywords directly into WIDGET_BASE,
without assigning default values, since the defaults are
handled by WIDGET_BASE. Avoids assigning defaults if user passes
in undefined variables.
CT, RSI, July 2001: Fix bug in previous mod. If user passes in a
numeric VALUE but forgets to set the /FLOAT, we still need
to convert to a string before passing onto WIDGET_TEXT.
