ENH: Image rotation via WCS-only layers

CHANGES.rst

@@ -13,6 +13,7 @@ New Features
 
 Cubeviz
 ^^^^^^^
+
 - Calculated moments can now be output in velocity units. [#2584, #2588, #2665]
 
 - Added functionality to Collapse and Spectral Extraction plugins to save results to FITS file. [#2586]
@@ -24,6 +25,9 @@ Cubeviz
 Imviz
 ^^^^^
 
+- There is now option for image rotation in Orientation (was Links Control) plugin.
+  This feature requires WCS linking. [#2179]
+
 Mosviz
 ^^^^^^
 
@@ -48,6 +52,16 @@ Cubeviz
 Imviz
 ^^^^^
 
+- Links Control plugin is now called Orientation. [#2179]
+
+- Linking by WCS will now always generate a hidden reference data layer
+  without distortion. As a result, when WCS linked, the first loaded data
+  is no longer the reference data. Additionally, if data is distorted,
+  its distortion will show when linked by WCS. If there is also data without WCS,
+  it can no longer be displayed when WCS linked. [#2179]
+
+- ``imviz.link_data()`` inputs and behaviors are now consistent with the Orientation plugin. [#2179]
+
 Mosviz
 ^^^^^^
 

docs/imviz/displayimages.rst

@@ -117,7 +117,7 @@ Pan/Zoom and Linked Pan/Zoom
 Linked Pan/Zoom is an Imviz-specific feature enabled only when there are multiple viewers that
 allows the user to pan and zoom images in multiple different viewers simultaneously. This works by matching images
 based on the way they are linked together. Images are linked by pixels on load time,
-but you can re-link them via WCS using :ref:`imviz-link-control`.
+but you can re-link them via WCS using :ref:`imviz-orientation`.
 
 Single-viewer Pan/Zoom is also available and is used in a similar way as in
 other Jdaviz tools. To access this option when there are multiple viewers, right-click on the
@@ -216,7 +216,7 @@ section above in the same way you would with the other subset selection
 tools.
 
 When you have multiple images loaded and linked by WCS
-(see :ref:`imviz-link-control`), the region defined is with respect to
+(see :ref:`imviz-orientation`), the region defined is with respect to
 the reference image, which might not be the image you are viewing.
 
 .. warning::

docs/imviz/plugins.rst

@@ -99,13 +99,16 @@ To export the table into the notebook via the API, call
 :meth:`~jdaviz.core.template_mixin.TableMixin.export_table`
 (see :ref:`plugin-apis`).
 
-.. _imviz-link-control:
+.. _imviz-orientation:
 
-Link Control
-============
+Orientation
+===========
+
+.. note::
 
-This plugin is used to re-link images by pixels or WCS using
-:func:`~jdaviz.configs.imviz.helper.link_image_data`.
+    This plugin was previous called "Links Control".
+
+This plugin is used to align image layers by pixels or sky (WCS).
 All images are automatically linked by pixels on load but you can use
 it to re-link by pixels or WCS as needed.
 
@@ -115,6 +118,13 @@ performant at the cost of accuracy but should be accurate to within a pixel
 for most cases. If approximation fails, WCS linking still automatically
 falls back to full transformation.
 
+Since Jdaviz v3.9, when linking by WCS, a hidden reference data layer
+without distortion (labeled "Default orientation") will be created and all the data would be linked to
+it instead of the first loaded data. As a result, working in pixel
+space when linked by WCS is not recommended. Additionally, any data
+with distorted WCS would show as distorted on the display. Furthermore,
+any data without WCS can no longer be shown in WCS linking mode.
+
 For the best experience, it is recommended that you decide what kind of
 link you want and set it at the beginning of your Imviz session,
 rather than later.
@@ -130,6 +140,21 @@ From the API within the Jupyter notebook (if linking by WCS):
 
     imviz.link_data(link_type='wcs')
 
+.. _imviz-orientation-rotation:
+
+Orientation: Image Rotation
+===========================
+
+When linked by WCS, sky rotation is also possible. You can choose from
+presets (N-up, E-left/right) or provide your own sky angle.
+
+.. warning::
+
+    Each rotation request created a new reference data layer in the background.
+    Just as in :ref:`imviz-import-data`, the performance would be impacted by
+    the number of active rotation layers you have; Only keep the desired rotation layer.
+    Note that the "default orientation" layer cannot be removed.
+
 .. _imviz-compass:
 
 Compass
@@ -348,6 +373,11 @@ To import a regions file or object from the API:
 Canvas Rotation
 ===============
 
+.. note::
+
+    This plugin is deprecated in favor of rotation via :ref:`imviz-orientation` and will be removed
+    in a future release.
+
 The canvas rotation plugin allows rotating and horizontally flipping the image to any arbitrary 
 value by rotating the canvas axes themselves.  Note that this does not affect the underlying data, and
 exporting data to the notebook via the API will therefore not exhibit the same rotation.

docs/reference/api_plugins.rst

@@ -66,7 +66,7 @@ Plugins API
 .. automodapi:: jdaviz.configs.imviz.plugins.line_profile_xy.line_profile_xy
    :no-inheritance-diagram:
 
-.. automodapi:: jdaviz.configs.imviz.plugins.links_control.links_control
+.. automodapi:: jdaviz.configs.imviz.plugins.orientation.orientation
    :no-inheritance-diagram:
 
 .. automodapi:: jdaviz.configs.imviz.plugins.rotate_canvas.rotate_canvas