Figure.savefig: Add the 'worldfile' parameter to write a companion world file for raster images

pygmt/figure.py

@@ -252,7 +252,14 @@ def psconvert(self, **kwargs):
             )
 
     def savefig(
-        self, fname, transparent=False, crop=True, anti_alias=True, show=False, **kwargs
+        self,
+        fname,
+        transparent=False,
+        crop=True,
+        anti_alias=True,
+        show=False,
+        worldfile=False,
+        **kwargs,
     ):
         """
         Save the figure to a file.
@@ -289,8 +296,16 @@ def savefig(
             the arguments ``"t2"`` and ``"g2"`` to the ``anti_aliasing``
             parameter of :meth:`pygmt.Figure.psconvert`. Ignored if creating
             vector graphics.
-        show: bool
+        show : bool
             If ``True``, will open the figure in an external viewer.
+        worldfile : bool
+            If ``True``, will create a companion
+            `world file <https://en.wikipedia.org/wiki/World_file>`__ for the
+            figure. The world file will have the same name as the figure file
+            but with different extension (e.g. tfw for tif). See
+            https://en.wikipedia.org/wiki/World_file#Filename_extension
+            for the convention of world file extensions.
+            This parameter does not work for KML and GeoTIFF formats.
         dpi : int
             Set raster resolution in dpi [Default is ``720`` for PDF, ``300``
             for others].
@@ -299,6 +314,7 @@ def savefig(
             :meth:`pygmt.Figure.psconvert`. Valid parameters are ``gs_path``,
             ``gs_option``, ``resize``, ``bb_style``, and ``verbose``.
         """
+        # pylint: disable=too-many-branches
         # All supported formats
         fmts = {
             "png": "g",
@@ -340,6 +356,13 @@ def savefig(
             kwargs["Qt"] = 2
             kwargs["Qg"] = 2
 
+        if worldfile:
+            if ext in ["kml", "tiff"]:
+                raise GMTInvalidInput(
+                    f"Saving a world file is not supported for '{ext}' format."
+                )
+            kwargs["W"] = True
+
         self.psconvert(prefix=prefix, fmt=fmt, crop=crop, **kwargs)
 
         # Remove the .pgw world file if exists

pygmt/tests/test_figure.py

@@ -292,6 +292,33 @@ def mock_psconvert(*args, **kwargs):  # pylint: disable=unused-argument
     }
 
 
+@pytest.mark.parametrize("fmt", [".png", ".pdf", ".jpg", ".tif"])
+def test_figure_savefig_worldfile(fmt):
+    """
+    Check if a world file is created when requested.
+    """
+    fig = Figure()
+    fig.basemap(region=[0, 1, 0, 1], projection="X1c/1c", frame=True)
+    with GMTTempFile(prefix="pygmt-worldfile", suffix=fmt) as imgfile:
+        fig.savefig(fname=imgfile.name, worldfile=True)
+        assert Path(imgfile.name).stat().st_size > 0
+        worldfile_suffix = "." + fmt[1] + fmt[3] + "w"
+        assert Path(imgfile.name).with_suffix(worldfile_suffix).stat().st_size > 0
+
+
+@pytest.mark.parametrize("fmt", [".tiff", ".kml"])
+def test_figure_savefig_worldfile_unsupported_format(fmt):
+    """
+    Figure.savefig should raise an error when a world file is requested for
+    an unsupported format.
+    """
+    fig = Figure()
+    fig.basemap(region=[0, 1, 0, 1], projection="X1c/1c", frame=True)
+    with GMTTempFile(prefix="pygmt-worldfile", suffix=fmt) as imgfile:
+        with pytest.raises(GMTInvalidInput):
+            fig.savefig(fname=imgfile.name, worldfile=True)
+
+
 @pytest.mark.skipif(IPython is None, reason="run when IPython is installed")
 def test_figure_show():
     """