cubegenpy

Python successor to the IDL cube_generator — an IDL → Python translation map

What this page is

A single document that answers two questions for anyone reading the code:

1. For each .pro file in the IDL cube_generator — what’s the Python plan? Port, replace with a pre-existing pyuvis capability, drop because it’s GUI / IDL-specific, or defer to a later phase?
2. What does cubegenpy own vs. delegate? Specifically: data I/O is delegated to pyuvis, metadata and backplanes are provided as input by the upstream pipeline (Mark Showalter’s machinery), and SPICE kernel handling lives outside this tool.

Source of the IDL files being translated: ~/Dropbox/Documents/01_projects/uvis_pdart/code/tools/cube_generator/ (36 .pro files, 6649 LOC).

Note

Status: scaffolding only. No functional Python code yet — only the public API stub cubegenpy.build_cube(...) raising NotImplementedError. This document is the contract for what the implementation will look like.

Source-of-data delegation

cubegenpy does not re-implement things pyuvis already does well, and it does not compute geometry or manage SPICE kernels.

Concern	IDL home (cube_generator)	Python home
Read PDS3 DAT + LBL	cg_feuv_reader.pro, open_pds_file.pro	pyuvis.io.PDSReader, pyuvis.io.UVPDS
Wavelength table	uvis_wl.sav	pyuvis.io.UVPDS.wavelengths
HSP sensitivity	cg_get_fuv_red_patch.pro	pyuvis.hsp_sensitivity
Flat-fielding (AJS / Steffl)	cg_read_ajs_flf.pro, cg_bin_win_flatfield.pro	pyuvis.calib.steffl
Flat-fielding (Greg / Spica)	cg_read_spica_ff_data.pro	pyuvis.calib.greg
SCLK conversion	cg_convert_sclk.pro	spiceypy.sct2e (called by upstream geometry pipeline)
Geometry / Geometer engine	cg_geometer_engine.pro (external)	Provided as input — Mark’s pipeline
SPICE kernel mgmt	cassini_spice_kernel_list_v2.pro (external)	Provided as input — kernel list passed in, written into the KERNELS HDU verbatim
File fetch via PDS	cg_get_filename.pro, get_file_location.pro	planetarypy.catalog.fetch_product (via pyuvis)

IDL .pro → Python destination

Every file in the source IDL project, with the chosen disposition.

Algorithm core (port)

IDL file	LOC	Python target
cube_single.pro	1046	cubegenpy.build.build_cube — the algorithm core
cg_create_pass_struct.pro	203	cubegenpy.config.BuildConfig (frozen dataclass)
cg_settings_print.pro	94	BuildConfig.__repr__ / __str__
cg_init_structures_dp.pro	137	Replaced by FITS HDU builders in cubegenpy.fits_writer
cg_int1.pro	76	Inline helper in cubegenpy.utils if still needed

Small numerical / data utilities (port)

IDL file	Python target
cg_interpolate_nans.pro, cg_interpolate_nans2.pro	cubegenpy.utils.interpolate_nans (pick the better of the two)
cg_shrink.pro	cubegenpy.utils.shrink
cg_enlarg.pro	cubegenpy.utils.enlarge
cg_attget.pro	cubegenpy.utils.attr_get
cg_xerox.pro	cubegenpy.utils.xerox
cg_valstr.pro	cubegenpy.utils.validate_string
cg_get_uvis_modifier.pro	Inline helper if needed

Already exists in pyuvis (replaced)

IDL file	Replaced by
cg_feuv_reader.pro	pyuvis.io.PDSReader
open_pds_file.pro	pyuvis.io.PDSReader
cg_get_fuv_red_patch.pro	pyuvis.hsp_sensitivity
cg_read_ajs_flf.pro	pyuvis.calib.steffl
cg_bin_win_flatfield.pro	pyuvis.calib.steffl
cg_read_spica_ff_data.pro	pyuvis.calib.greg
cg_get_filename.pro, get_file_location.pro	planetarypy.catalog.fetch_product (via pyuvis)
cg_convert_sclk.pro	spiceypy.sct2e (upstream)
cg_nogui.pro	cubegenpy.build.build_cube is the no-GUI entry point

Dropped (GUI / obsolete output formats / IDL-specific)

Warning

These files do not get a Python equivalent. The functionality is either bound to the IDL widget toolkit, or a deliberate choice was made in the 2026-02 PDART team meeting to drop the format.

IDL file	LOC	Reason
cube_generator.pro	1107	IDL widget GUI — out of scope; if any GUI is wanted later it would be Streamlit/Panel
cube_control.pro	308	GUI control flow
cg_write_save_new.pro	255	IDL .sav output replaced by FITS
cg_write_save_new_multi.pro	255	Same
cg_write_binary.pro	<100	Raw binary output replaced by FITS
cg_write_save_orig.pro	<100	Old IDL .sav writer
path_finder_*.txt, T-0.txt	text	Local-machine-specific paths; gone

Deferred to a later phase

IDL file	LOC	Phase	Notes
cube_multi.pro	1009	3	Multi-window batching with A/B suffixed sibling files (occurs in ~0.005% of products per the 2026-02 meeting notes)
cg_getstar.pro	<100	3	Star observation special case

Reference assets (preserved as-is, not ported)

File	Where it lands
Cube Generator.doc	Original IDL tutorial, kept in IDL tree
UVISImageCube.doc, UVISImageCube_descriptions.doc	Original IDL cube format spec — superseded by the new FITS layout (see refs/FITS-layout-proposal-MRS-2025-02-03.pdf)
cube_generator_tutorial.README	Original README; relevant pieces lifted into this doc
GeometerStars.txt, cg_defaults.txt	Original IDL defaults — values consulted as needed; not loaded at runtime
uvis_wl.sav, Spica_FF_data.sav, *.gif	Replaced (wavelengths from pyuvis; flatfield data lives with calibration code; gifs were GUI assets)

Planned Python module layout

src/cubegenpy/
  __init__.py          # re-exports build_cube, __version__
  build.py             # public API: build_cube() entry point
  config.py            # BuildConfig dataclass (replaces the IDL pass struct)
  fits_writer.py       # assembles the 9 HDUs per Mark's spec
  pds4_label.py        # emits the PDS4 XML label alongside the FITS
  geometry.py          # validates / normalises the input geometry dict
  utils.py             # small helpers ported from cg_*

FITS output layout

Per Mark Showalter’s 2026-02 proposal in refs/FITS-layout-proposal-MRS-2025-02-03.pdf:

HDU	Type	Content
PRIMARY	IMAGE float32	Calibrated cube (NX, NY, NZ)
RAW_COUNTS	IMAGE int16	Raw counts cube, same shape
CAL_FACTOR	IMAGE float32	2-D (NX, NY) calibration matrix
WAVELENGTH	IMAGE float32	Center wavelengths, length NX
SC_GEOM	BINTABLE	Spacecraft + sub-spacecraft geometry per body
BODY_GEOM	BINTABLE	Spatial backplanes per resolved body
GENERAL_GEOM	BINTABLE	RA, DEC, TIME_ET (body-independent)
RING_GEOM	BINTABLE	Ring backplanes
KERNELS	TABLE (ASCII)	SPICE kernels used to compute the geometry

The PDS4 XML label (sibling file <pid>.xml) describes every HDU and the product-level metadata.

Phase plan

Phase 1 — done

• Project skeleton (pyproject.toml, src layout, hatchling, bump-my-version, Python 3.12/13/14 supported)
• Public API stub cubegenpy.build_cube raising NotImplementedError
• This document
• Standalone git repo (git init inside code/cubegenpy/)
• refs/ preserves Mark’s FITS layout proposal and the team meeting notes

Phase 2 — next

• BuildConfig dataclass (port of cg_create_pass_struct)
• FITS HDU builders for all nine HDUs (Mark’s layout)
• PDS4 label generator (XML matching the FITS structure)
• Geometry input validation (shape + key checks against Mark’s column specs)
• Single-product build_cube end-to-end on a default Titan EUV file
• CI test workflow + smoke test
• Quarto docs site (this file becomes its index.qmd; quartodoc API ref under reference/)
• PyPI release of 0.2.0

Phase 3 — later

• Multi-window observations: A/B suffixed sibling files
• Background-subtraction HDU (planned in 2026-02 meeting; needs a time dimension)
• Geometry input format spec (when Mark’s actual files arrive — likely a separate FITS that we copy from)
• Star observation special case (cg_getstar)
• PDS4 label validation against the official schema