rename method to save_view_as_image

.gitignore

@@ -36,4 +36,7 @@ conda-recipe/ipyaladin
 
 # Documentation
 docs/_build/
-docs/_collections/
+docs/_collections/
+
+# Examples
+examples/*.png

CHANGELOG.md

@@ -24,7 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - New way to make a selection on the view with `selection` method (#100)
 - Add selected sources export as `astropy.Table` list with property `selected_objects` (#100)
 - Add function `get_view_as_fits` to export the view as a `astropy.io.fits.HDUList` (#86)
-- Add function `export_view_as_image` to save the view as an image file (#108)
+- Add function `save_view_as_image` to save the view as an image file (#108)
 
 ### Deprecated
 

examples/03_Functions.ipynb

@@ -140,12 +140,10 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "help(aladin_bis.get_JPEG_thumbnail)"
+    "Save the view as an image"
    ]
   },
   {
@@ -154,42 +152,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "aladin_bis.get_JPEG_thumbnail()"
-   ]
-  },
-  {
-   "attachments": {},
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Check that your browser didn't block the popup window if you don't see the thumbnail. This will not work in VSCode or other notebooks editors that are not working in a browser."
+    "aladin_bis.save_view_as_image(\"4Sgr.png\")"
    ]
   }
  ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "base",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.11.8"
-  },
-  "vscode": {
-   "interpreter": {
-    "hash": "85bb43f988bdbdc027a50b6d744a62eda8a76617af1f4f9b115d38242716dbac"
-   }
-  }
- },
+ "metadata": {},
  "nbformat": 4,
  "nbformat_minor": 4
 }

examples/11_Extracting_information_from_the_view.ipynb

@@ -66,7 +66,7 @@
    "id": "998def1f-3963-405b-8be2-6d4ef4012634",
    "metadata": {},
    "source": [
-    "If you edit the view either by modifiing the widget through its interface, or programmatically: "
+    "If you edit the view either by modifiing the widget through its interface, or programmatically:"
    ]
   },
   {
@@ -106,7 +106,7 @@
    "id": "f5add3a2-be30-488e-86df-426338b98f5d",
    "metadata": {},
    "source": [
-    "If you try to recover the value in the **same cell**, you'll get a `WidgetCommunicationError` error. This is because the calculation of the WCS is done by Aladin Lite *between* cell executions. \n",
+    "If you try to recover the value in the **same cell**, you'll get a `WidgetCommunicationError` error. This is because the calculation of the WCS is done by Aladin Lite *between* cell executions.\n",
     "\n",
     "## Getting the field of view\n",
     "\n",
@@ -204,7 +204,7 @@
    "metadata": {},
    "source": [
     "## Getting the view as a fits file\n",
-    "The following method allow you to retrieve the current view as a fits file. If a `path` is given as a second argument, the fits file will be saved."
+    "The following method allow you to retrieve the current view as a fits file."
    ]
   },
   {
@@ -247,6 +247,26 @@
     "plt.subplot(projection=wcs)\n",
     "plt.imshow(fits[0].data, cmap=\"binary_r\", norm=\"asinh\", vmin=0.001)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c64190a2757b707",
+   "metadata": {},
+   "source": [
+    "## Saving the view as an image file\n",
+    "\n",
+    "In `save_view_as_image`, the first argument is the path to the file, the second is the format (\"png\", \"jpeg\", \"webp\"), and the third is a boolean to indicate if you want to include the Aladin Lite logo in the image."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "85f40dc5e6af3ae1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "aladin.save_view_as_image(path=\"./crab.png\", image_format=\"png\", with_logo=True)"
+   ]
   }
  ],
  "metadata": {

js/models/event_handler.js

@@ -261,7 +261,7 @@ export default class EventHandler {
     this.eventHandlers = {
       change_fov: this.messageHandler.handleChangeFoV,
       goto_ra_dec: this.messageHandler.handleGotoRaDec,
-      export_view_as_image: this.messageHandler.handleExportViewAsImage,
+      save_view_as_image: this.messageHandler.handleSaveViewAsImage,
       add_fits: this.messageHandler.handleAddFits,
       add_catalog_from_URL: this.messageHandler.handleAddCatalogFromURL,
       add_MOC_from_URL: this.messageHandler.handleAddMOCFromURL,

js/models/message_handler.js

@@ -17,7 +17,7 @@ export default class MessageHandler {
     this.aladin.gotoRaDec(msg["ra"], msg["dec"]);
   }
 
-  async handleExportViewAsImage(msg) {
+  async handleSaveViewAsImage(msg) {
     const path = msg["path"];
     const format = msg["format"];
     const withLogo = msg["with_logo"];
@@ -28,7 +28,7 @@ export default class MessageHandler {
     );
     this.model.send(
       {
-        event_type: "export_view_as_image",
+        event_type: "save_view_as_image",
         path: path,
       },
       null,

src/ipyaladin/widget.py

@@ -162,7 +162,7 @@ class Aladin(anywidget.AnyWidget):
     )
     # reticle
     show_reticle = Bool(
-        True, help="Wether to show the reticle in the middle of the view."
+        True, help="Whether to show the reticle in the middle of the view."
     ).tag(sync=True, init_option=True, only_init=True)
     reticle_color = Unicode("rgb(178, 50, 178)", help="The color of the reticle.").tag(
         sync=True, init_option=True, only_init=True
@@ -175,7 +175,7 @@ class Aladin(anywidget.AnyWidget):
         False, help="Whether the coordinates grid should be shown at startup."
     ).tag(sync=True, init_option=True, only_init=True)
     show_coo_grid_control = Bool(
-        True, help="Whether to show the coordinate grid control toolbar. "
+        True, help="Whether to show the coordinate grid control toolbar."
     ).tag(sync=True, init_option=True, only_init=True)
     grid_color = Unicode(
         "rgb(178, 50, 178)",
@@ -208,7 +208,7 @@ class Aladin(anywidget.AnyWidget):
     overlay_survey_opacity = Float(0.0).tag(sync=True, init_option=True)
     _base_layer_last_view = Unicode(
         survey.default_value,
-        help="The last view of the base layer. It is used "
+        help="A private trait for the base layer of the last view. It is useful "
         "to convert the view to an astropy.HDUList",
     ).tag(sync=True)
 
@@ -241,7 +241,7 @@ def _handle_custom_message(self, _: any, message: dict, buffers: any) -> None:
             self.listener_callback["click"](message["content"])
         elif event_type == "select" and "select" in self.listener_callback:
             self.listener_callback["select"](message["content"])
-        elif event_type == "export_view_as_image":
+        elif event_type == "save_view_as_image":
             self._save_file(message["path"], buffers[0])
 
     @property
@@ -292,7 +292,8 @@ def wcs(self) -> WCS:
         """
         if self._wcs == {}:
             raise WidgetCommunicationError(
-                "The world coordinate system is not available. "
+                "The world coordinate system is not available. This often happens when "
+                "the WCS is modified and read in the same cell. "
                 "Please recover it from another cell."
             )
         if "RADECSYS" in self._wcs:  # RADECSYS keyword is deprecated for astropy.WCS
@@ -311,7 +312,8 @@ def fov_xy(self) -> Tuple[Angle, Angle]:
         """
         if self._fov_xy == {}:
             raise WidgetCommunicationError(
-                "The field of view along the two axes is not available. "
+                "The field of view along the two axes is not available. This often "
+                "happens when the FOV is modified and read in the same cell. "
                 "Please recover it from another cell."
             )
         return (
@@ -331,6 +333,10 @@ def fov(self) -> Angle:
         astropy.coordinates.Angle
             An astropy.coordinates.Angle object representing the field of view.
 
+        See Also
+        --------
+        fov_xy
+
         """
         return Angle(self._fov, unit="deg")
 
@@ -397,10 +403,10 @@ def _save_file(self, path: str, buffer: bytes) -> None:
         with Path(path).open("wb") as file:
             file.write(buffer)
 
-    def export_view_as_image(
+    def save_view_as_image(
         self, path: Union[str, Path], image_format: str = "png", with_logo: bool = True
     ) -> None:
-        """Export the current view of the widget as an image.
+        """Save the current view of the widget as an image file.
 
         Parameters
         ----------
@@ -411,12 +417,16 @@ def export_view_as_image(
         with_logo : bool
             Whether to include the Aladin Lite logo in the image.
 
+        See Also
+        --------
+        get_view_as_fits
+
         """
         if image_format not in {"png", "jpeg", "webp"}:
             raise ValueError("image_format must be 'png', 'jpeg' or 'webp")
         self.send(
             {
-                "event_name": "export_view_as_image",
+                "event_name": "save_view_as_image",
                 "path": str(path),
                 "format": image_format,
                 "with_logo": with_logo,
@@ -435,6 +445,10 @@ def get_view_as_fits(self) -> HDUList:
         astropy.io.fits.HDUList
             The FITS object containing the image.
 
+        See Also
+        --------
+        save_view_as_image
+
         """
         try:
             from astroquery.hips2fits import hips2fits
@@ -456,6 +470,19 @@ def get_view_as_fits(self) -> HDUList:
             ) from e
         return fits
 
+    def get_JPEG_thumbnail(self) -> None:
+        """Create a new tab with the current Aladin view.
+
+        This method will only work if you are running a notebook in a browser (for
+        example, it won't do anything in VSCode).
+
+        See Also
+        --------
+        save_view_as_image: will save the image on disk instead
+
+        """
+        self.send({"event_name": "get_JPG_thumbnail"})
+
     def add_catalog_from_URL(
         self, votable_URL: str, votable_options: Optional[dict] = None
     ) -> None:
@@ -767,14 +794,6 @@ def add_graphic_overlay_from_stcs(
             }
         )
 
-    def get_JPEG_thumbnail(self) -> None:
-        """Create a popup window with the current Aladin view.
-
-        This method will only work if you are running a notebook in a browser (for
-        example, it won't do anything in VSCode).
-        """
-        self.send({"event_name": "get_JPG_thumbnail"})
-
     def set_color_map(self, color_map_name: str) -> None:
         """Change the color map of the Aladin Lite widget.