This guide describes the opus-seti
python package to use the API that drives OPUS, an outer planets data search tool produced by the NASA PDS Rings Node. Any search that can be performed in OPUS can also be requested as an API call. Below are several examples.
A command line intergration
(CLI) is also available, and examples can be found here.
(The source code of this python package can be found on github. Contributions and feedbacks are welcome.)
IMPORTANT: I have no current affiliation with NASA or SETI. This package is provided as is, use at your own risk.
from opus import api
## Get result count for the number of `Images` taken by the `CASSINI-VIMS`
## instrument targeting `TITAN` with at least 2 pixels width/length.
count = api.count(
instrumentid = 'Cassini+VIMS',
target = 'TITAN',
COVIMSswathlength1 = 2,
COVIMSswathwidth1 = 2
)
print('Number of Image/Cube found:', count)
Number of Image/Cube found: 68173
## Get the first 10 cubes (sorted by time) and retreiving:
# - the intended target name
# - Saturn orbit number
# - the observation start time (int UTC)
# - the primary file specification
# - the channel (VIS/IR)
cubes = api.data(
instrumentid = 'Cassini+VIMS',
target = 'TITAN',
COVIMSswathlength1 = 2,
COVIMSswathwidth1 = 2,
order = 'time1',
cols = 'opusid,target,revno,time1,primaryfilespec',
limit = 10,
page = 1
)
print(cubes)
OPUS API Data objects (with 10 elements): - COVIMS_0004-2004136T030633_2004143T032556-v1463887830_1_IR - COVIMS_0004-2004136T030633_2004143T032556-v1463887830_1_VIS - COVIMS_0004-2004136T030633_2004143T032556-v1463887846_1_IR - COVIMS_0004-2004136T030633_2004143T032556-v1463887846_1_VIS - COVIMS_0004-2004136T030633_2004143T032556-v1463887879_1_IR - COVIMS_0004-2004136T030633_2004143T032556-v1463887879_1_VIS - COVIMS_0004-2004136T030633_2004143T032556-v1463887895_1_IR - COVIMS_0004-2004136T030633_2004143T032556-v1463887895_1_VIS - COVIMS_0004-2004136T030633_2004143T032556-v1463887928_1_IR - COVIMS_0004-2004136T030633_2004143T032556-v1463887928_1_VIS
Note: If limit
parameter is set to None
the query will retreive all the cubes found.
## Show a single cube from the previous query:
cubes['COVIMS_0004-2004136T030633_2004143T032556-v1463887830_1_IR']
OPUS ID: COVIMS_0004-2004136T030633_2004143T032556-v1463887830_1_IR - Intended Target Name: Titan - Saturn Orbit Number: 000 - Observation Start Time (UTC): 2004-05-22T03:06:38.211 - Primary File Spec: COVIMS_0004/data/2004136T030633_2004143T032556/v1463887830_1.qub
## Get all the metadata for a knwon `Ring Observation ID`:
meta = api.metadata('COVIMS_0004-2004136T030633_2004143T032556-v1463887830_1_IR')
print(meta)
OPUS API Metadata Ring observation: COVIMS_0004-2004136T030633_2004143T032556-v1463887830_1_IR => GENERAL constraints - planet: Saturn - target: Titan - targetclass: Regular Satellite - mission: Cassini - insthost: Cassini - instrument: Cassini VIMS - time1: 2004-05-22 03:06:38.211000 - time2: 2004-05-22 03:06:41.934000 - timesec1: 138510430.211 - timesec2: 138510433.934 - observationduration: 3.7229999899864197 - spatialsampling: 2-D - wavelengthsampling: Yes - quantity: Reflectivity - rightasc1: 33.597013 - rightasc2: 33.781802 - declination1: 9.564464 - declination2: 9.746636 - opusid: COVIMS_0004-2004136T030633_2004143T032556-v1463887830_1_IR - ringobsid: S_CUBE_CO_VIMS_1463887830_IR => PDS constraints - volumeid: COVIMS_0004 - datasetid: CO-E/V/J/S-VIMS-2-QUBE-V1.0 - productid: 1/1463887830_1 - productcreationtime: 2018-04-26 16:00:00 - productcreationtimesec: 578073637.0 - primaryfilespec: COVIMS_0004/data/2004136T030633_2004143T032556/v1463887830_1.qub => IMAGE constraints - duration: 0.08 - greaterpixelsize: 6 - lesserpixelsize: 6 - levels: 4096 - imagetype: Raster Scan => WAVELENGTH constraints - wavelength1: 0.8842 - wavelength2: 5.1225 - waveres1: 0.01662 - waveres2: 0.01662 - waveno1: 1952.1717911176186 - waveno2: 11309.658448314862 - wavenores1: 6.3338399547827855 - wavenores2: 212.583717949551 - specflag: Yes - specsize: 256 - polarizationtype: None => SATURN_SURFACE_GEOMETRY constraints - SURFACEGEOsaturnsubsolarplanetographiclatitude: -29.543 - SURFACEGEOsaturnsubobserverplanetographiclatitude: -19.825 - SURFACEGEOsaturnsubsolarplanetocentriclatitude: -24.757 - SURFACEGEOsaturnsubobserverplanetocentriclatitude: -16.348 - SURFACEGEOsaturnsubsolarIAUlongitude: 42.915 - SURFACEGEOsaturnsubobserverIAUlongitude: 115.068 - SURFACEGEOsaturncenterdistance: 21435312.517 - SURFACEGEOsaturncenterresolution: 10610.0 - SURFACEGEOsaturncenterphaseangle: 67.361 => TITAN_SURFACE_GEOMETRY constraints - SURFACEGEOtitansubsolarplanetographiclatitude: -24.699 - SURFACEGEOtitansubobserverplanetographiclatitude: -16.231 - SURFACEGEOtitansubsolarplanetocentriclatitude: -24.699 - SURFACEGEOtitansubobserverplanetocentriclatitude: -16.231 - SURFACEGEOtitansubsolarIAUlongitude: 209.735 - SURFACEGEOtitansubobserverIAUlongitude: 285.075 - SURFACEGEOtitancenterdistance: 21722296.753 - SURFACEGEOtitancenterresolution: 10753.0 - SURFACEGEOtitancenterphaseangle: 70.272 => RING_GEOMETRY constraints - RINGGEOringradius1: 1155776.141 - RINGGEOringradius2: 1269499.724 - RINGGEOJ2000longitude1: 317.627 - RINGGEOJ2000longitude2: 328.377 - RINGGEOsubsolarringlong: 288.83 - RINGGEOsolarhourangle1: 208.797 - RINGGEOsolarhourangle2: 219.547 - RINGGEOsubobserverringlong: 216.677 - RINGGEOlongitudeWRTobserver1: 100.95 - RINGGEOlongitudeWRTobserver2: 111.7 - RINGGEOringazimuthWRTobserver1: 104.075 - RINGGEOringazimuthWRTobserver2: 114.909 - RINGGEOrangetoringintercept1: 21675806.237 - RINGGEOringcenterdistance: 21435312.517 - RINGGEOrangetoringintercept2: 21917939.068 - RINGGEOresolution1: 10730.0 - RINGGEOresolution2: 10849.0 - RINGGEOprojectedradialresolution1: 14007.0 - RINGGEOprojectedradialresolution2: 19298.0 - RINGGEOphase1: 70.199 - RINGGEOphase2: 70.344 - RINGGEOincidence1: 65.224 - RINGGEOincidence2: 65.226 - RINGGEOemission1: 73.838 - RINGGEOemission2: 74.022 - RINGGEOnorthbasedincidence1: 114.774 - RINGGEOnorthbasedincidence2: 114.776 - RINGGEOnorthbasedemission1: 105.978 - RINGGEOnorthbasedemission2: 106.162 - RINGGEOsolarringelev1: -24.776 - RINGGEOsolarringelev2: -24.774 - RINGGEOobserverringelevation1: -16.162 - RINGGEOobserverringelevation2: -15.978 - RINGGEOringcenterphase: 67.361 - RINGGEOringcenterincidence: 65.243 - RINGGEOringcenteremission: 73.652 - RINGGEOringcenternorthbasedincidence: 114.757 - RINGGEOringcenternorthbasedemission: 106.348 - RINGGEOsolarringopeningangle: -24.757 - RINGGEOobserverringopeningangle: -16.348 - RINGGEOedgeonradius1: 1102060.665 - RINGGEOedgeonradius2: 1170445.679 - RINGGEOedgeonJ2000longitude1: 303.414 - RINGGEOedgeonJ2000longitude2: 303.605 - RINGGEOedgeonsolarhourangle1: 194.584 - RINGGEOedgeonsolarhourangle2: 194.774 - RINGGEOrangetoedgeonpoint1: 21361720.688 - RINGGEOrangetoedgeonpoint2: 21383145.545 - RINGGEOedgeonradialresolution1: 10574.0 - RINGGEOedgeonradialresolution2: 10585.0 - RINGGEOedgeonaltitude1: -153111.275 - RINGGEOedgeonaltitude2: -81461.096 => CASSINI_MISSION constraints - CASSINIobsname: VIMS_000TI_LIGHTC065 - CASSINIactivityname: LIGHTC - CASSINImissionphasename: Approach Science - CASSINItargetcode: TI (Titan) - CASSINIrevno: 000 - CASSINIrevnoint: -1 - CASSINIprimeinst: VIMS - CASSINIisprime: Yes - CASSINIsequenceid: S01 - CASSINIspacecraftclockcount1: 1/1463887830.223 - CASSINIspacecraftclockcount2: 1/1463887834.153 - CASSINIspacecraftclockcountdec1: 1463887830.8710938 - CASSINIspacecraftclockcountdec2: 1463887834.5976562 => CASSINI_VIMS constraints - COVIMSchannel: IR - COVIMSvissamplingmode: Normal - COVIMSvisexposure: 480.0 - COVIMSirsamplingmode: Normal - COVIMSirexposure: 80.0 - COVIMSswathwidth: 6 - COVIMSswathlength: 6 - COVIMSspectralsumming: No - COVIMSspectralediting: No - COVIMSinstrumentmode: IMAGE - COVIMSstartracking: Off
# Extract only the `General` constraints:
meta['GENERAL']
=> GENERAL constraints - planet: Saturn - target: Titan - targetclass: Regular Satellite - mission: Cassini - insthost: Cassini - instrument: Cassini VIMS - time1: 2004-05-22 03:06:38.211000 - time2: 2004-05-22 03:06:41.934000 - timesec1: 138510430.211 - timesec2: 138510433.934 - observationduration: 3.7229999899864197 - spatialsampling: 2-D - wavelengthsampling: Yes - quantity: Reflectivity - rightasc1: 33.597013 - rightasc2: 33.781802 - declination1: 9.564464 - declination2: 9.746636 - opusid: COVIMS_0004-2004136T030633_2004143T032556-v1463887830_1_IR - ringobsid: S_CUBE_CO_VIMS_1463887830_IR
# Extract the starting time of the observation:
meta['GENERAL']['time1']
datetime.datetime(2004, 5, 22, 3, 6, 38, 211000)
## Get image previews for a single observation (`size`: thumb, small, med, full)
preview = api.image('COISS_2001-1459551663_1459568594-N1459551972_1', size='med')
preview
OPUS API Image object: COISS_2001-1459551663_1459568594-N1459551972_1
# Get the url on the OPUS website:
preview.url
'https://pds-rings.seti.org/holdings/previews/COISS_2xxx/COISS_2001/data/1459551663_1459568594/N1459551972_1_med.jpg'
# Download the preview:
preview.download(out='../tests/data/N1459551972_1_med.jpg')
'../tests/data/N1459551972_1_med.jpg'
## Get all the previews for a specic query:
previews = api.images(planet='Saturn', target='pan', size='med', limit=10)
print(previews)
OPUS API Image objects (with 10 med images): - COISS_2008-1479919543_1480697632-N1480614021_1 - COISS_2009-1488178711_1488202381-N1488190255_1 - COISS_2010-1488210352_1488278467-N1488273311_4 - COISS_2010-1488302267_1488638384-N1488368442_1 - COISS_2010-1488302267_1488638384-N1488485562_1 - COISS_2010-1488302267_1488638384-N1488551713_1 - COISS_2010-1488638456_1488792254-N1488711044_1 - COISS_2010-1488638456_1488792254-N1488745124_1 - COISS_2010-1488792273_1488818205-N1488812400_1 - COISS_2010-1488818242_1488893120-N1488826725_1
## Show a single image from the previous query:
previews['COISS_2008-1479919543_1480697632-N1480614021_1']
OPUS API Image object: COISS_2008-1479919543_1480697632-N1480614021_1
## Get the files (previews, raw, calibrated data if availables) for a single observation:
file = api.file('COISS_2001-1459551663_1459568594-N1459551972_1')
file
OPUS API Files for observation: COISS_2001-1459551663_1459568594-N1459551972_1 => FULL-SIZE - full: https://pds-rings.seti.org/holdings/previews/COISS_2xxx/COISS_2001/data/1459551663_1459568594/N1459551972_1_full.jpg => MEDIUM - med: https://pds-rings.seti.org/holdings/previews/COISS_2xxx/COISS_2001/data/1459551663_1459568594/N1459551972_1_med.jpg => SMALL - small: https://pds-rings.seti.org/holdings/previews/COISS_2xxx/COISS_2001/data/1459551663_1459568594/N1459551972_1_small.jpg => THUMBNAIL - thumb: https://pds-rings.seti.org/holdings/previews/COISS_2xxx/COISS_2001/data/1459551663_1459568594/N1459551972_1_thumb.jpg => CALIBRATED_DATA - IMG: https://pds-rings.seti.org/holdings/calibrated/COISS_2xxx/COISS_2001/data/1459551663_1459568594/N1459551972_1_CALIB.IMG - LBL: https://pds-rings.seti.org/holdings/calibrated/COISS_2xxx/COISS_2001/data/1459551663_1459568594/N1459551972_1_CALIB.LBL => PLANET_GEOMETRY_INDEX - TAB: https://pds-rings.seti.org/holdings/metadata/COISS_2xxx/COISS_2001/COISS_2001_saturn_summary.tab - LBL: https://pds-rings.seti.org/holdings/metadata/COISS_2xxx/COISS_2001/COISS_2001_saturn_summary.lbl => RAW_DATA - IMG: https://pds-rings.seti.org/holdings/volumes/COISS_2xxx/COISS_2001/data/1459551663_1459568594/N1459551972_1.IMG - LBL: https://pds-rings.seti.org/holdings/volumes/COISS_2xxx/COISS_2001/data/1459551663_1459568594/N1459551972_1.LBL - prefix2: https://pds-rings.seti.org/holdings/volumes/COISS_2xxx/COISS_2001/label/prefix2.fmt - tlmtab: https://pds-rings.seti.org/holdings/volumes/COISS_2xxx/COISS_2001/label/tlmtab.fmt => RING_GEOMETRY_INDEX - TAB: https://pds-rings.seti.org/holdings/metadata/COISS_2xxx/COISS_2001/COISS_2001_ring_summary.tab - LBL: https://pds-rings.seti.org/holdings/metadata/COISS_2xxx/COISS_2001/COISS_2001_ring_summary.lbl => SATELLITE_GEOMETRY_INDEX - TAB: https://pds-rings.seti.org/holdings/metadata/COISS_2xxx/COISS_2001/COISS_2001_moon_summary.tab - LBL: https://pds-rings.seti.org/holdings/metadata/COISS_2xxx/COISS_2001/COISS_2001_moon_summary.lbl => TARGET_BODY_INVENTORY - TAB: https://pds-rings.seti.org/holdings/metadata/COISS_2xxx/COISS_2001/COISS_2001_inventory.tab - LBL: https://pds-rings.seti.org/holdings/metadata/COISS_2xxx/COISS_2001/COISS_2001_inventory.lbl
# List of the calibrated images:
file['CALIBRATED_DATA']
- IMG: https://pds-rings.seti.org/holdings/calibrated/COISS_2xxx/COISS_2001/data/1459551663_1459568594/N1459551972_1_CALIB.IMG - LBL: https://pds-rings.seti.org/holdings/calibrated/COISS_2xxx/COISS_2001/data/1459551663_1459568594/N1459551972_1_CALIB.LBL
# Download the raw label file (`LBL`):
file['RAW_DATA']['LBL'].download(out='../tests/data/')
'../tests/data/N1459551972_1.LBL'
## Get all files for a search:
files = api.files(planet='Saturn', target='pan', limit=10)
print(files)
OPUS API File objects (with 10 files): - COISS_2008-1479919543_1480697632-N1480614021_1 - COISS_2009-1488178711_1488202381-N1488190255_1 - COISS_2010-1488210352_1488278467-N1488273311_4 - COISS_2010-1488302267_1488638384-N1488368442_1 - COISS_2010-1488302267_1488638384-N1488485562_1 - COISS_2010-1488302267_1488638384-N1488551713_1 - COISS_2010-1488638456_1488792254-N1488711044_1 - COISS_2010-1488638456_1488792254-N1488745124_1 - COISS_2010-1488792273_1488818205-N1488812400_1 - COISS_2010-1488818242_1488893120-N1488826725_1
## Show a single image from the previous query:
files['COISS_2008-1479919543_1480697632-N1480614021_1']
OPUS API Files for observation: COISS_2008-1479919543_1480697632-N1480614021_1 => FULL-SIZE - full: https://pds-rings.seti.org/holdings/previews/COISS_2xxx/COISS_2008/data/1479919543_1480697632/N1480614021_1_full.jpg => MEDIUM - med: https://pds-rings.seti.org/holdings/previews/COISS_2xxx/COISS_2008/data/1479919543_1480697632/N1480614021_1_med.jpg => SMALL - small: https://pds-rings.seti.org/holdings/previews/COISS_2xxx/COISS_2008/data/1479919543_1480697632/N1480614021_1_small.jpg => THUMBNAIL - thumb: https://pds-rings.seti.org/holdings/previews/COISS_2xxx/COISS_2008/data/1479919543_1480697632/N1480614021_1_thumb.jpg => CALIBRATED_DATA - IMG: https://pds-rings.seti.org/holdings/calibrated/COISS_2xxx/COISS_2008/data/1479919543_1480697632/N1480614021_1_CALIB.IMG - LBL: https://pds-rings.seti.org/holdings/calibrated/COISS_2xxx/COISS_2008/data/1479919543_1480697632/N1480614021_1_CALIB.LBL => PLANET_GEOMETRY_INDEX - TAB: https://pds-rings.seti.org/holdings/metadata/COISS_2xxx/COISS_2008/COISS_2008_saturn_summary.tab - LBL: https://pds-rings.seti.org/holdings/metadata/COISS_2xxx/COISS_2008/COISS_2008_saturn_summary.lbl => RAW_DATA - IMG: https://pds-rings.seti.org/holdings/volumes/COISS_2xxx/COISS_2008/data/1479919543_1480697632/N1480614021_1.IMG - LBL: https://pds-rings.seti.org/holdings/volumes/COISS_2xxx/COISS_2008/data/1479919543_1480697632/N1480614021_1.LBL - prefix2: https://pds-rings.seti.org/holdings/volumes/COISS_2xxx/COISS_2008/label/prefix2.fmt - tlmtab: https://pds-rings.seti.org/holdings/volumes/COISS_2xxx/COISS_2008/label/tlmtab.fmt => RING_GEOMETRY_INDEX - TAB: https://pds-rings.seti.org/holdings/metadata/COISS_2xxx/COISS_2008/COISS_2008_ring_summary.tab - LBL: https://pds-rings.seti.org/holdings/metadata/COISS_2xxx/COISS_2008/COISS_2008_ring_summary.lbl => SATELLITE_GEOMETRY_INDEX - TAB: https://pds-rings.seti.org/holdings/metadata/COISS_2xxx/COISS_2008/COISS_2008_moon_summary.tab - LBL: https://pds-rings.seti.org/holdings/metadata/COISS_2xxx/COISS_2008/COISS_2008_moon_summary.lbl => TARGET_BODY_INVENTORY - TAB: https://pds-rings.seti.org/holdings/metadata/COISS_2xxx/COISS_2008/COISS_2008_inventory.tab - LBL: https://pds-rings.seti.org/holdings/metadata/COISS_2xxx/COISS_2008/COISS_2008_inventory.lbl
## Returns all possible values for a given multiple choice field, given a search, and the result count for each value:
targets = api.mults('target', planet='Saturn')
print(targets)
OPUS API Multiple choice for field: `target` - Aegaeon : 1389 - Albiorix : 3426 - Anthe : 1684 - Atlas : 1649 - Bebhionn : 2204 - Bergelmir : 582 - Bestla : 2076 - Calibration : 1073 - Calypso : 1173 - Daphnis : 958 - Dark : 358 - Dione : 17550 - Dust : 176 - Enceladus : 45158 - Epimetheus : 2245 - Erriapus : 3080 - Fornjot : 951 - Greip : 563 - Hati : 704 - Helene : 2260 - Hyperion : 6495 - Hyrrokkin : 1271 - Iapetus : 16682 - Ijiraq : 3678 - Interstellar Medium : 3 - Io : 70 - Janus : 2977 - Jarnsaxa : 82 - Kari : 155 - Kiviuq : 5231 - Loge : 838 - Methone : 1496 - Mimas : 9292 - Mundilfari : 106 - Narvi : 511 - Other : 4 - Paaliaq : 3757 - Pallene : 1293 - Pan : 1636 - Pandora : 1829 - Phoebe : 3246 - Pluto : 65 - Polydeuces : 966 - Prometheus : 4185 - Rhea : 21576 - S Rings : 284282 - S/2004 S 12 : 145 - S/2004 S 13 : 13 - Saturn : 395306 - Siarnaq : 1878 - Skathi : 2403 - Skoll : 795 - Sky : 106917 - Solar Wind : 19822 - Star : 2760 - Sun : 81137 - Surtur : 491 - Suttungr : 403 - System : 112 - Tarqeq : 3737 - Tarvos : 2122 - Telesto : 1224 - Tethys : 14978 - Thrymr : 2678 - Titan : 179474 - Unknown : 13478 - Ymir : 1818
# Get the count of targets on `TITAN`.
print('Number of Image/Cube found on TITAN:', targets['Titan'])
Number of Image/Cube found on TITAN: 179474
## Get range endpoints for a field, given a search
api.range('RINGGEOringradius1', target='Saturn')
OPUS API Range endpoints for field: `RINGGEOringradius1` - min : 90.707 - max : 12900000.0 - null : 125531
## Get information about a particular field
api.field('opusid')
OPUS ID (opusid): => Category General Constraints / Slug: opusid
## Get list of all fields available
fields = api.fields()
print('Number of field categories available:', len(fields))
Number of field categories available: 247
# Global fields:
fields['opusid']
OPUS ID (opusid): => Category General Constraints / Slug: opusid
# Find a field:
fields.find('res')
['coisscompressiontype', 'couviscompressiontype', 'gossicompressiontype', 'nhlorriinstrumentcompressiontype', 'nhmvicinstrumentcompressiontype', 'ringgeoresolution1', 'ringgeoresolution2', 'ringgeoprojectedradialresolution1', 'ringgeoprojectedradialresolution2', 'ringgeoedgeonradialresolution1', 'ringgeoedgeonradialresolution2', 'surfacegeo<target>finestresolution1', 'surfacegeo<target>finestresolution2', 'surfacegeo<target>coarsestresolution1', 'surfacegeo<target>coarsestresolution2', 'surfacegeo<target>centerresolution', 'waveres1', 'waveres2', 'wavenores1', 'wavenores2']
## List category names:
api.categories()
OPUS API list of all categories (5): - General Constraints (obs_general) - PDS Constraints (obs_pds) - Image Constraints (obs_type_image) - Wavelength Constraints (obs_wavelength) - Ring Geometry Constraints (obs_ring_geometry)
# Get all fields categories:
api.categories()
OPUS API list of all categories (5): - General Constraints (obs_general) - PDS Constraints (obs_pds) - Image Constraints (obs_type_image) - Wavelength Constraints (obs_wavelength) - Ring Geometry Constraints (obs_ring_geometry)