docs: be more explicit for errors (widget reduced + widget not ready) (…

…#107)

* 🐛 Fix WCS recovering when widget is out of sight

* 🥅 Add error when exporting the WCS while the widget is reduced when hidden

* 🥅 Add ready decorator to prevent certains actions before Aladin Lite is ready

* maint: upgrade aladin lite version (lighter package)

* docs: be extra explicit about widget readiness and widget reduced errors

---------

Co-authored-by: MARCHAND MANON <[email protected]>

CHANGELOG.md

@@ -32,7 +32,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- Upgrade Aladin Lite version to 3.4.5-beta (#96)
+- Upgrade Aladin Lite version to 3.5.1-alpha (#96)
 
 ## [0.4.0]
 

README.md

@@ -60,7 +60,7 @@ Correspondence table between ipyaladin versions and Aladin Lite versions:
 
 | ipyaladin  | Aladin-Lite |
 | ---------- | ----------- |
-| Unreleased | 3.4.5       |
+| Unreleased | 3.5.1-alpha |
 | 0.4.0      | 3.4.4-beta  |
 | 0.3.0      | 3.3.3-dev   |
 

docs/user_documentation/init_options.csv

@@ -9,14 +9,14 @@ samp;False;Wether to allow sending data via the SAMP protocol.
 show_catalog;True;Whether to show the catalog.
 show_context_menu;True;Whether the right click should start the contextual menu.
 show_coo_grid;False;Whether the coordinates grid should be shown at startup.
-show_coo_grid_control;True;Whether to show the coordinate grid control toolbar. 
+show_coo_grid_control;True;Whether to show the coordinate grid control toolbar.
 show_coo_location;True;Whether to show the coordinates bar.
 show_fov;True;Whether to show the field of view indicator.
 show_frame;True;Whether to show the viewport frame.
 show_fullscreen_control;True;Whether to show the fullscreen control toolbar.
 show_layers_control;True;Whether to show the layers control button.
 show_projection_control;True;Whether to show the coordinate location indicator.
-show_reticle;True;Wether to show the reticle in the middle of the view.
+show_reticle;True;Whether to show the reticle in the middle of the view.
 show_settings_control;True;Whether to show the settings control toolbar.
 show_share_control;False;Whether to show the share control toolbar.
 show_simbad_pointer_control;True;Whether to show the Simbad pointer control toolbar.

docs/user_documentation/user_documentation.rst

@@ -41,6 +41,32 @@ Retrieving information from the current widget view
 .. nbgallery::
     ../_collections/notebooks/11_Extracting_information_from_the_view.ipynb
 
+Note about the WCS
+==================
+
+To calculate the WCS, ``ipyaladin`` needs to know its ows size. However, to optimize the
+speed of the rendering of notebooks, Jupyter reduces the size of the output of the cells
+that are outside of the view. This causes ``ipyaladin`` to calculate WCS with the wrong 
+field of view. We raise a ``WidgetReducedError`` in this case. Here are a few
+workarounds for this issue:
+
+1. Detaching the widget from the notebook and keeping it on the side of the notebook
+------------------------------------------------------------------------------------
+
+In Jupyter notebook, you can right click on the cell where ``ipyaladin`` is displayed,
+then chose ``Create new view for cell output`` in the menu. This way, it is never out of
+the view (we also find it very practical) and the returned WCS will correspond to the 
+view on the side.
+
+.. image:: ../_static/gifs/pop_out_widget.gif
+
+2. Disabling the optimization in the notebook parameters
+--------------------------------------------------------
+
+To disable the option that reduces the widget when it is out of the view, you can go to
+``Settings``, ``Settings Editor``, ``Notebook``, and set ``Windowing mode`` to ``none``.
+This can make your notebook slower if you have a lot of cells.
+
 ************
 Advanced use
 ************
@@ -53,4 +79,3 @@ interactive cell outputs.
     ../_collections/notebooks/07_on-click-callback
     ../_collections/notebooks/08_Rectangular-selection
     ../_collections/notebooks/10_Advanced-GUI
-

examples/11_Extracting_information_from_the_view.ipynb

@@ -9,7 +9,7 @@
     "\n",
     "So far, we've seen how to send information (tables, MOCs, ...) into the widget. The other way also works! This notebook contains a list of methods to extract diverse information about the current view. However, here are several information about retrieving data from the widget:\n",
     "\n",
-    "- when the view is modified programmatically (*i.e.* not by clicking on the buttons), the update of its properties is done between cell execution. This means that you'll see a `WidgetCommunicationError` when you try to modify the view and retrieve information about it in the **same** cell. Simply switch the property-reading to the next cell and everything will work as intended!\n",
+    "- when the view is modified programmatically (*i.e.* not by clicking on the buttons), the update of its properties is done between cell execution. This means that you'll see a `WidgetNotReadyError` when you try to modify the view and retrieve information about it in the **same** cell. Simply switch the property-reading to the next cell and everything will work as intended!\n",
     "- if you generate different views of the same `Aladin()` instances -- either by calling `display` multiple times, or by using the `Create new view for cell output` button in Jupyter, the information contained in `wcs` and `fov_xy` will always correspond to the **most recently** created view."
    ]
   },
@@ -299,9 +299,8 @@
    "source": [
     "img = plt.imread(\"./crab.png\")\n",
     "plt.subplot(projection=screenshot_wcs)\n",
-    "plt.imshow(\n",
-    "    np.flipud(img)\n",
-    ")  # in FITS, the lines of pixels are flipped, so we have to mimic this"
+    "# in FITS, the lines of pixels are flipped, so we have to mimic this\n",
+    "plt.imshow(np.flipud(img))"
    ]
   }
  ],

js/aladin_lite.js

@@ -1,3 +1,3 @@
-import A from "https://esm.sh/aladin-lite@3.4.5";
+import A from "https://esm.sh/aladin-lite@3.5.1-alpha";
 
 export default A;

js/models/event_handler.js

@@ -158,9 +158,16 @@ export default class EventHandler {
       this.model.save_changes();
     });
 
-    this.aladin.on("resizeChanged", () => {
+    this.aladin.on("resizeChanged", (width, height) => {
+      // Skip resize event when the div is hidden
+      if (width === 1 && height === 1) {
+        this.model.set("_is_reduced", true);
+        this.model.save_changes();
+        return;
+      } else this.model.set("_is_reduced", false);
       this.updateWCS();
       this.update2AxisFoV();
+      this.model.set("_height", height);
       this.model.save_changes();
     });
 

js/widget.js

@@ -16,6 +16,7 @@ function initAladinLite(model, el) {
 
   aladinDiv.id = `aladin-lite-div-${divNumber}`;
   let aladin = new A.aladin(aladinDiv, initOptions);
+  el.appendChild(aladinDiv);
 
   // Set the target again after the initialization to be sure that the target is set
   // from icrs coordinates because of the use of gotoObject in the Aladin Lite API
@@ -29,9 +30,9 @@ function initAladinLite(model, el) {
     y: twoAxisFoV[1],
   });
   model.set("_wcs", aladin.getViewWCS());
+  model.set("_is_loaded", true);
   model.save_changes();
 
-  el.appendChild(aladinDiv);
   return { aladin, aladinDiv };
 }
 

src/ipyaladin/utils/exceptions.py

@@ -1,6 +1,14 @@
-class WidgetCommunicationError(OSError):
-    """Error raised when there is a communication error with the widget."""
+class WidgetReducedError(ValueError):
+    """Error raised when a widget is reduced to a point when hidden."""
 
     def __init__(self, message: str) -> None:
         self.message = message
-        super(WidgetCommunicationError, self).__init__(message)
+        super(WidgetReducedError, self).__init__(message)
+
+
+class WidgetNotReadyError(OSError):
+    """Error raised when the widget is not ready."""
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super(WidgetNotReadyError, self).__init__(message)