Description

This routine searches the SPICE catalog to find observations where the specified pointing falls within the SPICE field-of-view at the specified date/time or range.

Syntax

Result = SPICE_FIND_OBSERVATIONS( Date, SolarX, SolarY [, count=count] [, catfile=catfile] [, /carrington] [, /stonyhurst] [, /earth] [, dateref=dateref] [, margin=margin] [, errmsg=errmsg] )

Return value

The result of the function is a list of filenames matching the search criteria. If no matches are found, the null string is passed.

Arguments

DATE

Date/time to search. Can be a single value, or a range of values. Note that if only the date is passed, the time is assumed to be '00:00:00'. See the example above for how this affects searching over a range of dates.

SolarX, SolarY

Location in arcseconds of the feature to be searched for.

Optional Input

CATFILE

Name of the catalog file to read in. Defaults to $SPICE_DATA/spice_catalog.csv.

MARGIN

Margin in arcseconds to apply to the SPICE raster values. Default is no margin.

DATEREF

Reference date/time for the STONYHURST and EARTH options. If not passed, then the central time given by the DATE parameter is used.

Optional Output

COUNT

Returns the number of matching files found.

ERRMSG

If defined and passed, then any error messages will be returned to the user in this parameter rather than being handled by the IDL MESSAGE utility. If no errors are encountered, then a null string is returned. In order to use this feature, the string ERRMSG must be defined first, e.g.,

ERRMSG = ''
RESULT = SPICE_FIND_OBSERVATIONS(ERRMSG=ERRMSG, ... )
IF ERRMSG NE '' THEN ...

Keywords

CARRINGTON

If set, then the pointing parameters to check are Carrington longitudes and latitudes instead of arcseconds.

STONYHURST

If set, then the pointing parameters to check are heliographic longitude (relative to the central meridian) and latitude. Overrides /CARRINGTON.

EARTH

If set, then the pointing parameters to check are arcseconds as seen from Earth. (Uses Carrington option.) Overrides /STONYHURST or /CARRINGTON.

Note that the /CARRINGTON, /STONYHURST, or /EARTH options can be slow when searching over large time periods.

Restrictions

Requires the file $SPICE_DATA/spice_catalog.csv. Only Level 2 files are returned.

The /CARRINGTON, /STONYHURST, and /EARTH options requires the SunSPICE package, and the ephemeris software and data in the $SSW/so/gen tree.

Side effects

There is a delay the first time this routine is called to read in the catalog. Subsequent calls will be much faster.

Examples

Date = '2022-03-07T11:05'               ;Single date/time
Result = SPICE_FIND_OBSERVATIONS(Date, 2000.0, 0.0)

Date = ['2022-03-07T11', '2022-03-07T12']       ;One hour
Result = SPICE_FIND_OBSERVATIONS(Date, 2000.0, 0.0)

Date = ['2022-03-07', '2022-03-08']             ;One day
Result = SPICE_FIND_OBSERVATIONS(Date, 2000.0, 0.0)