INFO: Subset API audit 1/4 (creation, import, read)

[pllim]

subset_tools.import_region(): This is the new canonical API

jdaviz/jdaviz/configs/default/plugins/subset_tools/subset_tools.py

Lines 894 to 897 in 4ffc3a0

	def import_region(self, region, combination_mode=None, max_num_regions=None,
	refdata_label=None, return_bad_regions=False, **kwargs):
	"""
	Method for creating subsets from regions or region files.

data_menu.create_subset(): Tied directly to glue-jupyter GUI, so maybe we just leave this one alone?

jdaviz/jdaviz/configs/default/plugins/data_menu/data_menu.py

Lines 448 to 451 in 4ffc3a0

	def create_subset(self, subset_type):
	"""
	Interactively create a new subset in the viewer. This sets the app-wide subset
	selection to 'Create New' and selects the appropriate tool in this viewer's toolbar.

imviz.load_regions_from_file()/cubeviz.load_regions_from_file(): Can probably be replaced with subset_tools.import_region() but the latter has no way to set max_num_regions=20. The 20 max was originally added because Ori tried to load a giant regions file (thousands of regions) and crashed Imviz. How do we impose such a limit on subset_tools API?

jdaviz/jdaviz/core/helpers.py

Lines 574 to 578 in 4ffc3a0

	def load_regions_from_file(self, region_file, region_format='ds9', max_num_regions=20,
	**kwargs):
	"""Load regions defined in the given file.
	See :ref:`regions:regions_io` for supported file formats.
	See :meth:`load_regions` for how regions are loaded.

imviz.load_regions()/cubeviz.load_regions(): Can probably be replaced with subset_tools.import_region() and deprecated. But why didn't we? Were there blockers?

jdaviz/jdaviz/core/helpers.py

Lines 606 to 611 in 4ffc3a0

	def load_regions(self, regions, max_num_regions=None, refdata_label=None,
	return_bad_regions=False, **kwargs):
	"""Load given region(s) into the viewer.
	WCS-to-pixel translation and mask creation, if needed, is relative
	to the image defined by ``refdata_label``. Meanwhile, the rest of
	the Subset operations are based on reference image as defined by Glue.

imviz.load_data("something.reg"): This calls the canonical Subset API, so probably okay to keep since this allows importing regions from file in "standalone" mode.

jdaviz/jdaviz/configs/imviz/plugins/parsers.py

Lines 127 to 130 in 4ffc3a0

	elif file_obj_lower.endswith('.reg'):
	# This will load DS9 regions as Subset but only if there is already data.
	app.get_tray_item_from_name('g-subset-tools').import_region(file_obj,
	combination_mode='new')

imviz._apply_interactive_region()/cubeviz._apply_interactive_region(): Can probably be replaced using public Subset API now. Can be removed without deprecation.

https://github.com/spacetelescope/jdaviz/blob/4ffc3a03b475d45b9a56f20dfbf5e75f3d25b7d0/jdaviz/core/helpers.py#L841C11-L844

    def _apply_interactive_region(self, toolname, from_pix, to_pix):
        """Mimic interactive region drawing.
        This is for internal testing only.

🐱

[pllim]

Done. Open to comments.