API Proposal: Importing/loading spatial and spectral regions

[pllim]

Scope: Propose API to import/load spatial and spectral regions.

Out of scope:

• Importing/loading composite/masked subsets/regions.
• Exporting any region.

🐱

Spatial Regions

Existing API

These work in Cubeviz and Imviz.

viz_helper.load_regions_from_file()

https://github.com/spacetelescope/jdaviz/blob/069834a4ac8e47565bf359011178af812e72a03e/jdaviz/core/helpers.py#L643-L644

viz_helper.load_regions()

https://github.com/spacetelescope/jdaviz/blob/069834a4ac8e47565bf359011178af812e72a03e/jdaviz/core/helpers.py#L675-L676

To export

viz.app.get_subsets()

https://github.com/spacetelescope/jdaviz/blob/069834a4ac8e47565bf359011178af812e72a03e/jdaviz/app.py#L949-L952

viz.get_interactive_regions()

https://github.com/spacetelescope/jdaviz/blob/f985a7fe0bd3119db88013ce7f4b4aa7a4283fff/jdaviz/core/helpers.py#L861

Proposed API

No change; same as Existing API. One could argue to absorb load_regions_from_file into load_regions but both have existed for a while now and no one complained about it, so no motivation for extra churn.

Spectral Regions

Existing API

This theoretically works on any viz with a spectrum viewer.

from glue.core.roi import XRangeROI
sv = specviz_helper.app.get_viewer('spectrum-viewer')
sv.apply_roi(XRangeROI(6500, 7400))
viz_helper.app.state.drawer = True

To export

viz.app.get_subsets()

https://github.com/spacetelescope/jdaviz/blob/069834a4ac8e47565bf359011178af812e72a03e/jdaviz/app.py#L949-L952

Proposed API 1

Same as spatial regions:

• viz_helper.load_regions_from_file()
• viz_helper.load_regions()

Pros: Less API for user to remember.

Cons: Possibility of over-complicating the logic in those methods due to different usages and file formats between spatial and spectral regions.

Proposed API 2

Similar to spatial regions but not identical:

• viz_helper.load_spectral_regions_from_file()
• viz_helper.load_spectral_regions()

Pros: Cleanly separating out logic for spatial and spectral. User's intention is clear.

Cons: Possibility of code duplication where logic is shared between spatial and spectral regions. User has to remember to use different APIs for spatial vs spectral. Might have to rename spatial region methods by adding spatial to them.