diff --git a/examples/gallery/images/image.py b/examples/gallery/images/image.py index 49f0fe757fa..5aecbbfc465 100644 --- a/examples/gallery/images/image.py +++ b/examples/gallery/images/image.py @@ -6,23 +6,25 @@ many formats (e.g., png, jpg, eps, pdf) on a figure. We must specify the filename via the ``imagefile`` parameter or simply use the filename as the first argument. You can also use a full URL pointing to your desired image. The ``position`` parameter allows -us to set a reference point on the map for the image. +us to place the image at a specific location on the plot. """ # %% from pathlib import Path import pygmt +from pygmt.params import Position fig = pygmt.Figure() fig.basemap(region=[0, 2, 0, 2], projection="X10c", frame=True) -# Place and center ("+jCM") the image "needle.jpg" provided by GMT to the position -# ("+g") 1/1 on the current plot, scale it to a width of 8 centimeters ("+w") and draw -# a rectangular border around it +# Place the center of the image "needle.jpg" provided by GMT to the position (1, 1) on +# the current plot, scale it to a width of 8 centimeters and draw a rectangular border +# around it. fig.image( imagefile="https://oceania.generic-mapping-tools.org/cache/needle.jpg", - position="g1/1+w8c+jCM", + position=Position((1, 1), cstype="mapcoords", anchor="MC"), + width="8c", box=True, ) diff --git a/pygmt/src/image.py b/pygmt/src/image.py index d389e7477d9..808ecdb13e8 100644 --- a/pygmt/src/image.py +++ b/pygmt/src/image.py @@ -9,18 +9,23 @@ from pygmt.alias import Alias, AliasSystem from pygmt.clib import Session from pygmt.helpers import build_arg_list, fmt_docstring, use_alias -from pygmt.params import Box +from pygmt.params import Box, Position @fmt_docstring -@use_alias(D="position", G="bitcolor") -def image( +@use_alias(G="bitcolor") +def image( # noqa: PLR0913 self, imagefile: PathLike, - projection: str | None = None, - region: Sequence[float | str] | str | None = None, + position: Position | None = None, + height: float | str | None = None, + width: float | str | None = None, + replicate: int | tuple[int, int] | None = None, + dpi: float | str | None = None, box: Box | bool = False, monochrome: bool = False, + projection: str | None = None, + region: Sequence[float | str] | str | None = None, verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"] | bool = False, panel: int | Sequence[int] | bool = False, @@ -31,8 +36,8 @@ def image( r""" Plot raster or EPS images. - Reads Encapsulated PostScript (EPS) or raster image files and plots them. The - image can be scaled arbitrarily, and 1-bit raster images can be: + Reads an Encapsulated PostScript file or a raster image file and plot it on a map. + The image can be scaled arbitrarily, and 1-bit raster images can be: - inverted, i.e., black pixels (on) becomes white (off) and vice versa. - colorized, by assigning different foreground and background colors. @@ -47,6 +52,7 @@ def image( Full GMT docs at :gmt-docs:`image.html`. $aliases + - D = position, **+w**: width/height, **+n**: replicate, **+r**: dpi - F = box - J = projection - M = monochrome @@ -62,13 +68,25 @@ def image( An Encapsulated PostScript (EPS) file or a raster image file. An EPS file must contain an appropriate BoundingBox. A raster file can have a depth of 1, 8, 24, or 32 bits and is read via GDAL. - $projection - $region - position : str - [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\ **+r**\ *dpi*\ - **+w**\ [**-**]\ *width*\ [/*height*]\ [**+j**\ *justify*]\ - [**+n**\ *nx*\ [/*ny*]]\ [**+o**\ *dx*\ [/*dy*]]. - Set reference point on the map for the image. + position + Specify the position of the image on the plot. See + :class:`pygmt.params.Position` for details. + width + height + Width (and height) of the image in plot coordinates (inches, cm, etc.). If + **height** (or **width**) is set to 0, then the original aspect ratio of the + image is maintained. If **width** (or **height**) is negative, the absolute + value is used to interpolate image to the device resolution using the PostScript + image operator. If neither dimensions nor dpi are set then revert to the default + dpi [:gmt-term:`GMT_GRAPHICS_DPU`]. + dpi + Specify dpi to set the dpi of the image in dots per inch, or append **c** to + indicate this is dots per cm. + replicate + *nx* or (*nx*, *ny*). + Replicate the (scaled) image *nx* times in the horizontal direction, and *ny* + times in the vertical direction. If a single integer *nx* is given, *ny* = *nx*. + [Default is (1, 1)]. box Draw a background box behind the image. If set to ``True``, a simple rectangular box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box appearance, @@ -85,6 +103,8 @@ def image( monochrome Convert color image to monochrome grayshades using the (television) YIQ-transformation. + $projection + $region $verbose $panel $perspective @@ -93,6 +113,13 @@ def image( self._activate_figure() aliasdict = AliasSystem( + D=[ + Alias(position, name="position"), + Alias(width, name="width", prefix="+w"), + Alias(height, name="height", prefix="/"), + Alias(replicate, name="replicate", prefix="+n", sep="/", size=2), + Alias(dpi, name="dpi", prefix="+r"), + ], F=Alias(box, name="box"), M=Alias(monochrome, name="monochrome"), ).add_common( diff --git a/pygmt/tests/test_grdview.py b/pygmt/tests/test_grdview.py index a1e8fd6735f..dc659ec3860 100644 --- a/pygmt/tests/test_grdview.py +++ b/pygmt/tests/test_grdview.py @@ -179,7 +179,9 @@ def test_grdview_surface_plot_styled_with_contourpen(xrgrid): surface plot. """ fig = Figure() - fig.grdview(grid=xrgrid, cmap="relief", surftype="s", contour_pen="0.5p,black,dashed") + fig.grdview( + grid=xrgrid, cmap="relief", surftype="s", contour_pen="0.5p,black,dashed" + ) return fig diff --git a/pygmt/tests/test_image.py b/pygmt/tests/test_image.py index e69a8d71938..8a109e57e04 100644 --- a/pygmt/tests/test_image.py +++ b/pygmt/tests/test_image.py @@ -4,7 +4,7 @@ import pytest from pygmt import Figure -from pygmt.params import Box +from pygmt.params import Box, Position @pytest.mark.mpl_image_compare @@ -13,5 +13,10 @@ def test_image(): Place images on map. """ fig = Figure() - fig.image(imagefile="@circuit.png", position="x0/0+w2c", box=Box(pen="thin,blue")) + fig.image( + imagefile="@circuit.png", + position=Position((0, 0)), + width="2c", + box=Box(pen="thin,blue"), + ) return fig