A Python package to access, download, view, and manipulate Cassini RADAR images in one place
NOTE: This is Beta quality software that is being actively developed, use at your own risk. This project is not supported or endorsed by either JPL or NASA. The code is provided “as is”, use at your own risk.
PyPi pip install at pypi.org/project/pydar/
pip install pydar
Cassini-Huygens was an orbiter around Saturn and its moons, originally launched in 1997. Cassini ran successfully for years before it was purposefully burned up in Saturn's upper atmosphere to avoid potential contamination of Saturn's moons . As the orbiter passed over Titan in dozens of flybys gigabits of data were recorded and sent back
All Cassini data for Titan is organized and retrieved based on flyby observation numbers or ID numbers. Pydar makes it easy to find and view relevant flybys based on a time range, latitude/longitude position, or a feature name
import pydar
feature_name_example = "ontario lacus"
flyby_ids = pydar.retrieveIDSByFeatureName(feature_name=feature_name_example)
Returns a dictionary of flyby IDs (and their relevant segments) that Ontario Lacus could be found from: {'T7': ['S01'], 'T36': ['S03'], 'T39': ['S06', 'S05', 'S01', 'S04'], 'T48': ['S04'], 'T49': ['S01'], 'T50': ['S02'], 'T55': ['S01', 'S03'], 'T56': ['S01'], 'T57': ['S01', 'S02'], 'T58': ['S01'], 'T59': ['S01'], 'T65': ['S04', 'S01', 'S05', 'S02', 'S03'], 'T71': ['S01'], 'T95': ['S03'], 'T98': ['S01', 'S04']}
The relevant data files can be downloaded for any combination of these flyby IDs and segment numbers. For example, flyby ID 'T65' and segment 'S01' at resolution 'D' for 8 pixels/degree
# Extract Flyby Data Files to pydar_results/ directory
pydar.extractFlybyDataImages(flyby_id='T65',
resolution='D',
segment_num="S01")
Note: extractFlybyDataImages() only needs to be run once for each flyby to retrieve new data but will take some time to download
# Display all Images in pydar_results/ directory
pydar.displayImages(image_directory="pydar_results/CORADR_0211_V03_S01")
For information on Cassini instrument specifics and acronyms refer to the Cassini Radar User Guide
The Cassini Radar data can be found at the PDS Imaging Node. The directory is organized by PDS standards. The file format are defined in the Small Body Node. The radar echo is stored originally as floating points in LBDR files. The SAR processors turn the LBDR files into BIDR image. The BIDR data is organized as follows:
Cassini RADAR Information (CORADR_xxxx_Vxx) where xxxx is the radar data take number and Vxx is the data version number
|_ AAREADME.txt
Information about observation xxxx (xxxx > 0035 for Titan flybys)
|_CALIB/
|_CATALOG/
BIDRDS.CAT: Information about the BIDR dataset
|_DATA/
| |_BIDR/
| |_ BIbcdeefggg_Dhhh_Tiii_Vnn.LBL: header information for observation < -------- MAIN DATA OF INTEREST'S LABEL
| |_ BIbcdeefggg_Dhhh_Tiii_Vnn.ZIP: IMG file compressed in zip file < -------- MAIN DATA OF INTEREST
| | | b = Kind and bit-type of data
| | | F = Primary dataset (incidence-
| | | angle-corrected sigma0) in
| | | 32-bit floating-point format
| | | (linear scale, not dB)
| | | B = Primary dataset in unsigned
| | | byte format (dB, normalized
| | | to [0, 255])
| | | U = Sigma0 without incidence angle
| | | correction in 32-bit floating-
| | | point format (linear scale,
| | | not dB)
| | | E = Incidence angle map, 32-bit
| | | floating-point values in degrees
| | | T = Latitude map, 32-bit floating-
| | | point values in degrees
| | | N = Longitude map, 32-bit floating-
| | | point values in degrees
| | | M = Beam mask map, 8-bit unsigned
| | | byte values
| | | L = Number of looks map, 32-bit
| | | integer values
| | | D = standard deviations of Synthetic Aperture Radar
| | | (SAR) normalized backscatter cross-section noise
| | | subtracted values w/o incidence angle correction.
| | | The values are physical scale (not in dB)
| | | S = Synthetic Aperture Radar (SAR) normalized backscatter cross-section values
| | | physical scale (not in dB) and have not been corrected for incidence-angle effects.
| | | Biases due to thermal and quantization noise have been removed.
| | | X = Noise equivalent sigma-0 values associated with Synthetic Aperture Radar (SAR)
| | | normalized backscatter cross-section noise subtracted values w/o incidence angle
| | | correction. The values are physical scale (not in dB)."
| | | c = Map projection
| | | Q = Oblique cylindrical
| | | d = Map resolution
| | | B = 2 pixels/degree
| | | D = 8 pixels/degree
| | | F = 32 pixels/degree
| | | G = 64 pixels/degree
| | | H = 128 pixels/degree
| | | I = 256 pixels/degree
| | | ee = Absolute value of latitude at
| | | center of file, rounded to
| | | nearest degree
| | | f = Hemisphere of center of file
| | | N = Northern
| | | S = Southern
| | | ggg = West longitude at center of
| | | file, rounded to nearest degree
| | | hhh = 3-digit data take ID
| | | (observation counter) from which
| | | data are included, left-padded
| | | with zeroes as needed
| | | iii = 3-digit index of Titan flyby
| | | from which data are included,
| | | left-padded with zeroes as
| | | needed. (Note: the index
| | | for the "Ta" flyby is "00A")
|_______ |________ | ____________________ nn = 2-digit version number
|
|_DOCUMENT/
|_ERRATA.txt
|_EXTRAS/
|_BIbcdeefggg_Dhhh_Tiii_Vnn.JPG: jpg of IMG files in DATA
|_INDEX/
|_SOFTWARE/
|_VOLDESC.CAT <--- VERSION INFORMATION LISTED HERE ('VOLUME_VERSION_ID' = "Version 1", "Version 2", "Version 3") and in filename
.IMG files can be viewed using the planetary images library or via pydar.displayImages()
Download time for data files vary when using pydar.extractFlybyDataImages() and depends on the number and size of files of interest. On average, most single feature downloads take between 5-30 minutes to download, but can be longer for higher resolution files.
(Cassini Radar Volume SIS, Version 2.1 Table 1, pg. 3)
The Titan flyby IDs (e.g. 'T65') are not used in the naming convention for the CORADR filenames. Instead, all files are referred to by their observation number (e.g. '0211'). The Titan flyby information is contained in the BIDR filenames and in the VOLDESC.CAT under 'Description' and can be found using the following cross-reference table: cassini_flyby.csv
To convert between a Titan Flyby ID and an observation number use either pydar.convertFlybyIDToObservationNumber(flyby_id) or pydar.convertObservationNumberToFlybyID(flyby_observation_num)
The data filename contains a lot of information about the observation
(EXAMPLE) Filename: "BIBQD05S184_D065_T008S03_V03"
Image file from BIBQD05S184_D065_T008S03_V03.JPG:
Some passes have multiple versions of the data, up to 3 different versions currently.
Only some Titan passes produced all of the version numbers.
TA-T25 : V01, V02, V03
$\gt$ T28: V02, V03
T108-T126: labeled only once as V02 but is actually V03
The version number is listed in the filename and in VOLDESC.CAT under the 'VOLUME_VERSION_ID'
Version 3 is currently the latest and preferred version and will be the version included when downloaded
Example:
Version 1 is named BIFQI48N071_D035_T00A_V01.IMG
Version 2 is named BIFQI49N071_D035_T00AS01_V02.IMG
Version 3 is named BIFQI49N071_D035_T00AS01_V03.IMG
A single flyby can produce multiple image segments (Sxx). S01 is the primary imaging segment with other segments referring to periods in the flyby when the instrument went to/from altimetry/SAR/HiSAR or weird pointing profiles.
Credit: Cassini Radar User Guide (Wall et al. 2019, pg.16)
Pydar includes multiple scripts to web scrape from relevant URLs to generate some of the backend data files
Changes in the relevant URLs are checked once a month via Github Actions to keep csv files up to date and any changes found will be bundled into the subsequent release
coradr_jpl_options.csv
Contains all the CORADR IDs and available data types from planetarydata.jpl.nasa.gov/img/data/cassini/cassini_orbiter/
Headers: ["CORADR ID", "Is a Titan Flyby", "Contains ABDR", "Contains ASUM", "Contains BIDR", "Contains LBDR", "Contains SBDR", "Contains STDR"]
View data file: coradr_jpl_options.csv
swath_coverage_by_time_position.csv
Contains all the information for .LBL files within all CORADR ID pages (for each segment and resolution file)
Collected from URLs matching: https://planetarydata.jpl.nasa.gov/img/data/cassini/cassini_orbiter/[CORADAR_ID]/DATA/BIDR/
Headers: ["CORADR ID", "FLYBY ID", "SEGMENT NUMBER", "FILENAME", "DATE TYPE SYMBOL", "DATE TYPE", "RESOLUTION (pixels/degrees)", "TARGET_NAME", "MAXIMUM_LATITUDE (Degrees)", "MINIMUM_LATITUDE (Degrees)", "EASTERNMOST_LONGITUDE (Degrees)", "WESTERNMOST_LONGITUDE (Degrees)", "START_TIME", "STOP_TIME"]
View data file: swath_coverage_by_time_position.csv
feature_name_details.csv
Contains all named features on Titan with their furthest latitude/longitude position and URL where information was collected from
Collected from the planetarynames.wr.usgs.gov
Headers: ["Feature Name", "Northmost Latitude", "Southmost Latitude", "Eastmost Longitude", "Westmost Longitude", "Center Latitude", "Center Longitude", "URL"]
View data file: feature_name_details.csv
cassini_flyby.csv
Reference for converting between a Titan Flyby ID (e.g. "T7") and its Observation Number (e.g. "059") (and back)
Headers: ["Titan flyby id", "Radar Data Take Number", "Sequence number", "Orbit Number/ID"]
View data file: cassini_flyby.csv
sar_swath_details.csv
Currently unused, but will potentially be used in the future for incidence angle, polarization, azimuth, SAR range resolution, SAR azimuth resolution, and number of looks
Converted to a static csv file from the Cassini User Guide (pg. 136-139)
View data file: sar_swath_details.csv
Note: "CORADR_0048", "CORADR_0186", "CORADR_0189", "CORADR_0209", "CORADR_0234" do not have associated BIDR values.
There are data gaps and problems from the original downlinking and satellite location
CORADR_0048 (T4) did not have SAR data, only scatterometry and radiometry because of telemetry reasons in the handbook
CORADR_0186 (T52) only have radiometry and compressed scatterometry
CORADR_0189 (T53) only has radiometry and compressed scatterometry because of what appears to be a downlink problem
CORADR_0209 (T63) only has scatterometry and radiometry
CORADR_0234 (T80) only has scatterometry and radiometry
Total width of the RADAR swath is created by combining the five individual sub-swaths, where the center beam is the highest gain
(The Cassini Huygens Mission: Orbiter Remote Sensing Observation 2004)
To collect flyby information and images for the latitude/longitude range of a named feature on Titan
Retrieve a list of flyby IDs with their associated segment numbers based on a feature name from Titan
retrieveIDSByFeatureName(feature_name=None)
Feature names are retrieved from feature_name_details.csv (if the feature has both latitude/longitude coordinates)
import pydar
pydar.retrieveIDSByFeatureName(feature_name="Ontario Lacus")
Output = {'T7': ['S01'], 'T36': ['S03'], 'T39': ['S06', 'S05', 'S01', 'S04'], 'T48': ['S04'], 'T49': ['S01'], 'T50': ['S02'], 'T55': ['S01', 'S03'], 'T56': ['S01'], 'T57': ['S01', 'S02'], 'T58': ['S01'], 'T59': ['S01'], 'T65': ['S04', 'S01', 'S05', 'S02', 'S03'], 'T71': ['S01'], 'T95': ['S03'], 'T98': ['S01', 'S04']}
Retrieve a list of flyby IDs with their associated segments based on specific latitude and longitude
retrieveIDSByLatitudeLongitude(latitude=None, longitude=None)
import pydar
pydar.retrieveIDSByLatitudeLongitude(latitude=-80, longitude=170)
Output = {'T39': ['S06', 'S05', 'S01'], 'T49': ['S01'], 'T50': ['S02'], 'T55': ['S03'], 'T56': ['S01'], 'T57': ['S01'], 'T58': ['S01'], 'T59': ['S01'], 'T65': ['S01'], 'T95': ['S03'], 'T98': ['S01', 'S04']}
Retrieve a list of flyby IDs with their associated segments based on range of latitudes and longitudes
retrieveIDSByLatitudeLongitudeRange(min_latitude=None,
max_latitude=None,
min_longitude=None,
max_longitude=None)
import pydar
pydar.retrieveIDSByLatitudeLongitudeRange(min_latitude=-82,
max_latitude=-72,
min_longitude=183,
max_longitude=185)
Output = {'T7': ['S01'], 'T36': ['S03'], 'T39': ['S06', 'S05', 'S01', 'S04'], 'T48': ['S04'], 'T49': ['S01'], 'T50': ['S02'], 'T55': ['S01', 'S03'], 'T56': ['S01'], 'T57': ['S01', 'S02'], 'T58': ['S01'], 'T59': ['S01'], 'T65': ['S04', 'S01', 'S05', 'S02', 'S03'], 'T71': ['S01'], 'T95': ['S03'], 'T98': ['S01', 'S04']}
Return a list of features found at a specific latitude/longitude position
retrieveFeaturesFromLatitudeLongitude(latitude=None, longitude=None)
import pydar
pydar.retrieveFeaturesFromLatitudeLongitude(latitude=-72, longitude=183)
Output = ['Ontario Lacus', 'Rossak Planitia']
Return a list of features found at a range of latitude/longitude positions
retrieveFeaturesFromLatitudeLongitudeRange(min_latitude=None,
max_latitude=None,
min_longitude=None,
max_longitude=None)
import pydar
pydar.retrieveFeaturesFromLatitudeLongitudeRange(min_latitude=-82,
max_latitude=-72,
min_longitude=183,
max_longitude=190)
Output = ['Crveno Lacus', 'Ontario Lacus', 'Romo Planitia', 'Rossak Planitia', 'Saraswati Flumen']
Retrieve a dictionary of flyby IDs and segment numbers based on a specific timestamp
retrieveIDSByTime(year=None,
doy=None,
hour=None,
minute=None,
second=None,
millisecond=None)
Where 2004 year, 300 doy, 15 hour, 30 minute, 7 second, 789 millisecond becomes 2004-300T15:30:07.789
import pydar
pydar.retrieveIDSByTime(year=2004,
doy=300,
hour=15,
minute=30,
second=7,
millisecond=789)
Output = {'Ta': ['S01']}
If hour, minute, second, or millisecond is left undefined, will search the entire range for all possible values and can find more possible ids
For a single day, some flybys have segments that are defined in one large range, but not within a smaller range
import pydar
pydar.retrieveIDSByTime(year=2005, doy=301)
Output for the entire day of 301 = {'T8': ['S02', 'S03', 'S01']}
import pydar
pydar.retrieveIDSByTime(year=2005, doy=301, hour=3)
Output for the day 301 but just for hour 3 = {'T8': ['S03', 'S01']} (does not include S02)
Retrieve a dictionary of flyby IDs and segment numbers based on a start and end datetime
retrieveIDSByTimeRange(start_year=None,
start_doy=None,
start_hour=None,
start_minute=None,
start_second=None,
start_millisecond=None,
end_year=None,
end_doy=None,
end_hour=None,
end_minute=None,
end_second=None,
end_millisecond=None)
import pydar
pydar.retrieveIDSByTimeRange(start_year=2004,
start_doy=299,
start_hour=2,
start_minute=15,
start_second=23,
start_millisecond=987,
end_year=2005,
end_doy=301,
end_hour=2,
end_minute=15,
end_second=23,
end_millisecond=987)
Output = {'Ta': ['S01'], 'T3': ['S01'], 'T7': ['S01']}
Converts a Titan Flyby ID (for example: 'T65') to an observation number with front padding ('T65' -> '0211')
convertFlybyIDToObservationNumber(flyby_id)
import pydar
observation_number = convertFlybyIDToObservationNumber(flyby_id='T65')
Output = 0211
Observation number based on the 'Radar Data Take Number' in the cassini_flyby.csv data file with front padding to ensure that all observation numbers are 4 digits long (0065 and 0211)
Converts a Titan Observation Number (for example: '211' or '0211') to an flyby id ('0211' -> 'T65')
convertObservationNumberToFlybyID(flyby_observation_num)
import pydar
flyby_id = pydar.convertObservationNumberToFlybyID(flyby_observation_num='211')
Output = T65
Flyby ids are based on the 'Radar Data Take Number' in the cassini_flyby.csv data file with front padding of 'T'
Requires each Titan flyby ID to be a valid flyby ID in cassini_flyby.csv
Downloads flyby data SBDR for a selected flyby observation number or flyby id: .FMT and .TAB files (for example: SBDR.FMT and SBDR_15_D087_V03.TAB)
Downloads flyby data BIDR for a selected flyby observation number or flyby id: .LBL and .ZIP files (for example: BIBQH80N051_D087_T016S01_V03.LBL and BIBQH80N051_D087_T016S01_V03.ZIP)
extractFlybyDataImages(flyby_observation_num=None,
flyby_id=None,
segment_num=None,
additional_data_types_to_download=[],
resolution='I',
top_x_resolutions=None)
Either a flyby_id (for example: 'T65') or a flyby_observation_num (for example: '0035') is required.
Note: a flyby_id will be translated into a flyby_observation_number to access on the backend and the results will be saved under the observation number. For example, 'T65' will become observation number '0211'
import pydar
pydar.extractFlybyDataImages(flyby_id='T65',
resolution='D',
segment_num="S01")
extractFlybyDataImages() will retrieve images from PDS website and saves results in a directory labeled 'pydar_results' with the flyby observation number, version number, and segment number in the title (for example pydar_results/CORADR_0065_V03_S01). Download time depends on file and resolution size but ranges from 5-30 minutes
Print AAREADME.TXT to console for viewing
readAAREADME(coradr_results_directory=None,
section_to_print=None,
print_to_console=True)
To see a list of all section_to_print options, see: returnAAREADMEOptions()
import pydar
pydar.readAAREADME(coradr_results_directory="pydar_results/CORADR_0065_V03_S01",
section_to_print="Volume")
Output = Volume CORADR_0065: Titan Flyby T8, Sequence S15, Oct 27, 2005
import pydar
pydar.returnAAREADMEOptions()
Output = ['PDS_VERSION_ID', 'RECORD_TYPE', 'INSTRUMENT_HOST_NAME', 'INSTRUMENT_NAME', 'PUBLICATION_DATE', 'NOTE', 'END_OBJECT', 'Volume', 'Introduction', 'Disk Format', 'File Formats', 'Volume Contents', 'Recommended DVD Drives and Driver Software', 'Errata and Disclaimer', 'Version Status', 'Contact Information']
Print .LBL README to console for viewing
readLBLREADME(coradr_results_directory=None,
section_to_print=None,
print_to_console=True)
To see a list of all section_to_print options, see: returnLBLOptions()
import pydar
pydar.readLBLREADME(coradr_results_directory="pydar_results/CORADR_0035_S01/",
section_to_print="OBLIQUE_PROJ_X_AXIS_VECTOR")
Output = (0.13498322,0.00221225,-0.99084542)
import pydar
pydar.returnLBLOptions()
Displays downloaded image .IMG files (unzipped from within the .ZIP files) and display all images in directory
displayImages(image_directory=None, fig_title=None, cmap="gray", figsize_n=6, fig_dpi=120)
import pydar
pydar.displayImages(image_directory="pydar_results/CORADR_0065_V03_S01")
Note: displayImages() will plt.show() all images in the saved results directory
COMING SOON: extractMetadata
Extract Metadata from .FMT and .TAB files
COMING SOON: Extract metadata from .TAB file (using .FMT as a reference)
To run or test against pydar github repo/fork, a development environment can be created via conda/miniconda
First, install Miniconda
Then, using the existing environment.yml, a new conda environment can be create to run/test scripts against
conda env create --file environment.yml
Once the environment has been built, activate the environment:
conda activate pydar
To run existing and new tests from the root directory:
python -m pytest
Feature Names collected from Gazetteer of Planetary Nomenclature
Instrument information and naming conventions collected from the Cassini Radar User Guide
This material is based upon work supported by the National Science Foundation Graduate Fellowship under Grant No. 2141064. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the authors and do not necessarily reflect the views of the National Science Foundation.
Please acknowledge the use of this software in any publications by citing:
Cassini RADAR data extraction software was provided by C. Y. Schneck and U. G. Schneck and is available at URL: https://github.com/unaschneck/pydar
Please send a copy of such publications to: cyschneck@gmail.com & ugschneck@gmail.com
Submit a bug fix, question, or feature request as a Github Issue or to ugschneck@gmail.com/cyschneck@gmail.com
FAQs
A Python package to access, download, view, and manipulate Cassini RADAR images
We found that pydar demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.