Main data (cassini_upyp.uvisdata)#

This module contains the main data structures to process Cassini/UVIS PDS3 products.

Main classes#

Other classes#

class cassini_upyp.uvisdata.PDSRawData(filename, file2=None, no_extract=False)#

Raw PDS (Planetary Data System) data from the Cassini Ultraviolet Imaging Spectrograph (UVIS).

This class represents a single Cassini/UVIS observation stored in PDS3 format. It requires a binary data file (.DAT) containing the raw detector counts and a label file (.LBL) providing the associated metadata.

The object wraps:

  • the raw detector counts read from the .DAT file,

  • the parsed PDS label metadata from the .LBL file,

  • basic derived quantities such as the UVIS channel, slit state, pixel bandpass, slit ratio, and integration duration.

Parameters:

  • filename (str or pathlib.Path) – Either a base filename without extension (e.g. "FUV2006_015_14_47"), in which case <name>.DAT and <name>.LBL are used, or a path to a .DAT or .LBL file. In the latter case, file2 must be provided and point to the matching file.

  • file2 (str or pathlib.Path, optional) – Second file corresponding to filename when an explicit .DAT or .LBL file is provided. Default is None.

  • no_extract (bool, optional) – If False (default), the raw data cube is spatially and spectrally cropped according to the window boundaries and binning parameters defined in the PDS label. If True, the full data cube stored in the .DAT file is kept.

Raises:

ValueError – If the .DAT/.LBL pairing is invalid, if one of the files is missing, or if the data type defined by the CORE_ITEM_TYPE / CORE_ITEM_BYTES combination is not recognized.

Examples

Read a PDS file set by specifying the base filename without extension:

>>> data_pds = PDSRawData('example_file')

Read a PDS file set by specifying both the label and data files explicitly:

>>> data_pds = PDSRawData('data_file.DAT', 'label_file.LBL')
class cassini_upyp.uvisdata.Instrument(instrument_name, n_pixels=64)#

UVIS-like instrument geometry derived from SPICE kernels.

This class queries the SPICE instrument kernel (IK) for the requested instrument (UVIS and specific slit) and builds a simple field-of-view model based on the corresponding slit.

The pixel grid is modeled as a 1-D slit with n_pixels samples along the spatial direction. Pixel corner directions are computed in angular coordinates and converted to unit vectors expressed in the instrument frame.

Parameters:

  • instrument_name (str) – SPICE name of the instrument (e.g., a UVIS channel name resolvable by SPICE). This string is passed to SPICE to resolve the instrument ID (NAIF ID code).

  • n_pixels (int, optional) – Number of spatial pixels used to sample the slit. Default is 64.

Variables:

  • name (str) – Instrument name as provided by the user.

  • ID (int) – NAIF instrument ID code resolved from instrument_name.

  • shape (str) – FOV shape returned by SPICE (e.g., “RECTANGLE”).

  • frame (str) – Instrument frame name in which the FOV geometry is expressed.

  • bsight (numpy.ndarray) – Boresight direction (3-vector) in the instrument frame.

  • corners (numpy.ndarray) – FOV corner directions (vectors) (shape: (4, 3)) in the instrument frame.

  • fov_height (float) – Total FOV height in degrees.

  • fov_width (float) – Total FOV width in degrees.

  • n_pixels (int) – Number of spatial pixels along the slit, given in argument.

  • pixel_height (float) – Angular height of one pixel in degrees.

  • pixel_width (float) – Angular width of one pixel in degrees.

  • pixels_corners (numpy.ndarray) –

    Direction vectors for pixel center and corners in the instrument frame (shape: (n_pixels, 5, 3)).

    The second dimension uses the following order: center, bottom-left, bottom-right, upper-right, upper-left.

Notes

  • Angular quantities fov_height, fov_width, pixel_height, and pixel_width are expressed in degrees.

  • This initializer loads and unloads the instrument kernel (IK). Make sure the kernel file path is correctly set in env.toml config file.

Raises:

spiceypy.utils.exceptions.SpiceyError – If SPICE cannot resolve the instrument name, access the kernel pool variables, or compute the FOV geometry.

Examples

Create a 64-pixel slit model from SPICE IK:

>>> inst = Instrument("CASSINI_UVIS_FUV", n_pixels=64)
>>> inst.pixels_corners.shape
(64, 5, 3)
class cassini_upyp.uvisdata.AttrDict#

Dictionary with attribute-style access.

Keys can be accessed both as dictionary items and as attributes:

d[“KEY”] <-> d.KEY

This is mainly used for convenience when working with parsed PDS labels, where fields like TARGET_NAME or QUBE.AXES are accessed as attributes.

Module-level utilities#

cassini_upyp.uvisdata.pds_lbl(labelfile)#

Parse a PDS3-formatted LBL (Label) file and return its contents as a nested dictionary.

Parameters:

labelfile (str or pathlib.Path) – Path to the PDS3 .LBL file.

Returns:

Nested dictionary-like object with attribute access. Top-level keys are the main label fields; nested OBJECT blocks are stored as sub-AttrDicts.

Return type:

AttrDict

Examples

Load a label and access a top-level field and a nested object:

>>> lbl = pds_lbl("path/to/label.lbl")
>>> lbl.TARGET_NAME
'TITAN'
>>> lbl.QUBE.AXES
3

Notes

  • Unit strings in angle brackets (e.g. “<KM>”, “<DEGREE>”) are preserved as part of the string values.

  • Only a simple OBJECT / END_OBJECT nesting model is supported; this is sufficient for the UVIS labels used in this package.

cassini_upyp.uvisdata.pds_dat(filename_dat, data_dims, data_type, endian='big')#

Read a binary PDS (Planetary Data System) data file and return its contents as a NumPy array.

This function reads binary data from a PDS file and reshapes it into a data cube based on the specified dimensions. It handles the byte order (endianness) and data type to correctly interpret the binary data.

Parameters:

  • filename_dat (str or pathlib.Path) – Path to the binary PDS data file.

  • data_dims (tuple of int) –

    Dimensions of the data in the order (BAND, LINE, SAMPLE).

    • BAND : Number of spectral pixels

    • LINE : Number of spatial pixels

    • SAMPLE : Number of exposures

  • data_type (str or numpy.dtype) – Data type of the binary data (e.g. “float32”, “int16”).

  • endian ({"big", "little"}, optional) – Byte order of the data. Default is “big”.

Returns:

A NumPy array containing the data reshaped into a cube with dimensions (SAMPLE, LINE, BAND).

Return type:

numpy.ndarray

Notes

The dimensions should be provided in the order (BAND, LINE, SAMPLE), but the resulting array will have the shape (SAMPLE, LINE, BAND).

Examples

>>> cube = pds_dat("data.dat", (3, 64, 1024), "float32")
>>> cube.shape
(1024, 64, 3)
Raises:

  • FileNotFoundError – If the file does not exist.

  • ValueError – If the data cannot be reshaped to the requested dimensions.