diff --git a/pygmt/src/coast.py b/pygmt/src/coast.py index 280d1e69e0a..3c5bfef0719 100644 --- a/pygmt/src/coast.py +++ b/pygmt/src/coast.py @@ -14,6 +14,7 @@ kwargs_to_strings, use_alias, ) +from pygmt.params import Box __doctest_skip__ = ["coast"] @@ -24,7 +25,6 @@ B="frame", C="lakes", E="dcw", - F="box", G="land", I="rivers", L="map_scale", @@ -41,6 +41,7 @@ def coast( resolution: Literal[ "auto", "full", "high", "intermediate", "low", "crude", None ] = None, + box: Box | bool = False, verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"] | bool = False, panel: int | tuple[int, int] | bool = False, @@ -68,6 +69,7 @@ def coast( {aliases} - D = resolution + - F = box - J = projection - V = verbose - c = panel @@ -127,24 +129,11 @@ def coast( map_scale : str [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\ **+w**\ *length*. Draw a simple map scale centered on the reference point specified. - box : bool or str - [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\ - [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]]. - If set to ``True``, draw a rectangular border around the - map scale or rose. Alternatively, specify a different pen with - **+p**\ *pen*. Add **+g**\ *fill* to fill the scale panel [Default is - no fill]. Append **+c**\ *clearance* where *clearance* is either gap, - xgap/ygap, or lgap/rgap/bgap/tgap where these items are uniform, - separate x and y, or individual side spacings between scale and - border. Append **+i** to draw a secondary, inner border as well. - We use a uniform gap between borders of 2 points and the - :gmt-term:`MAP_DEFAULTS_PEN` unless other values are specified. Append - **+r** to draw rounded rectangular borders instead, with a 6-points - corner radius. You can override this radius by appending another value. - Finally, append **+s** to draw an offset background shaded region. - Here, *dx/dy* indicates the shift relative to the foreground frame - [Default is ``"4p/-4p"``] and shade sets the fill style to use for - shading [Default is ``"gray50"``]. + box + Draw a background box behind the map scale or rose. If set to ``True``, a simple + rectangular box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box + appearance, pass a :class:`pygmt.params.Box` object to control style, fill, pen, + and other box properties. borders : int, str, or list *border*\ [/*pen*]. Draw political boundaries. Specify the type of boundary and @@ -230,6 +219,7 @@ def coast( "crude": "c", }, ), + F=Alias(box, name="box"), ).add_common( J=projection, V=verbose, diff --git a/pygmt/src/colorbar.py b/pygmt/src/colorbar.py index 6e85db5ec76..c619712c7bc 100644 --- a/pygmt/src/colorbar.py +++ b/pygmt/src/colorbar.py @@ -4,9 +4,10 @@ from typing import Literal -from pygmt.alias import AliasSystem +from pygmt.alias import Alias, AliasSystem from pygmt.clib import Session from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias +from pygmt.params import Box __doctest_skip__ = ["colorbar"] @@ -16,7 +17,6 @@ B="frame", C="cmap", D="position", - F="box", G="truncate", I="shading", L="equalsize", @@ -30,6 +30,7 @@ def colorbar( self, projection=None, + box: Box | bool = False, verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"] | bool = False, panel: int | tuple[int, int] | bool = False, @@ -50,6 +51,7 @@ def colorbar( Full GMT docs at :gmt-docs:`colorbar.html`. {aliases} + - F = box - J = projection - V = verbose - c = panel @@ -82,23 +84,11 @@ def colorbar( be changed by appending **+j** followed by a :doc:`2-character justification code ` *justify*. - box : bool or str - [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\ - [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]]. - If set to ``True``, draw a rectangular border around the color scale. - Alternatively, specify a different pen with **+p**\ *pen*. Add - **+g**\ *fill* to fill the scale panel [Default is no fill]. Append - **+c**\ *clearance* where *clearance* is either gap, xgap/ygap, or - lgap/rgap/bgap/tgap where these items are uniform, separate in x- and - y-direction, or individual side spacings between scale and border. - Append **+i** to draw a secondary, inner border as well. We use a - uniform gap between borders of 2p and the :gmt-term:`MAP_DEFAULTS_PEN` - unless other values are specified. Append **+r** to draw rounded - rectangular borders instead, with a 6p corner radius. You can override - this radius by appending another value. Finally, append **+s** to draw - an offset background shaded region. Here, *dx/dy* indicates the shift - relative to the foreground frame [Default is ``"4p/-4p"``] and shade - sets the fill style to use for shading [Default is ``"gray50"``]. + box + Draw a background box behind the colorbar. If set to ``True``, a simple + rectangular box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box + appearance, pass a :class:`pygmt.params.Box` object to control style, fill, pen, + and other box properties. truncate : list or str *zlo*/*zhi*. Truncate the incoming CPT so that the lowest and highest z-levels are @@ -157,7 +147,9 @@ def colorbar( """ self._activate_figure() - aliasdict = AliasSystem().add_common( + aliasdict = AliasSystem( + F=Alias(box, name="box"), + ).add_common( J=projection, V=verbose, c=panel, diff --git a/pygmt/src/image.py b/pygmt/src/image.py index 621c3897004..f6fdfa71950 100644 --- a/pygmt/src/image.py +++ b/pygmt/src/image.py @@ -5,25 +5,20 @@ from typing import Literal from pygmt._typing import PathLike -from pygmt.alias import AliasSystem +from pygmt.alias import Alias, AliasSystem from pygmt.clib import Session from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias +from pygmt.params import Box @fmt_docstring -@use_alias( - D="position", - F="box", - G="bitcolor", - M="monochrome", - R="region", - p="perspective", -) +@use_alias(D="position", G="bitcolor", M="monochrome", R="region", p="perspective") @kwargs_to_strings(R="sequence", p="sequence") def image( self, imagefile: PathLike, projection=None, + box: Box | bool = False, verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"] | bool = False, panel: int | tuple[int, int] | bool = False, @@ -39,6 +34,7 @@ def image( Full GMT docs at :gmt-docs:`image.html`. {aliases} + - F = box - J = projection - V = verbose - c = panel @@ -59,11 +55,11 @@ def image( **+w**\ [**-**]\ *width*\ [/*height*]\ [**+j**\ *justify*]\ [**+n**\ *nx*\ [/*ny*]]\ [**+o**\ *dx*\ [/*dy*]]. Set reference point on the map for the image. - box : bool or str - [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\ - [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]]. - If set to ``True``, draw a rectangular border around the image - using :gmt-term:`MAP_FRAME_PEN`. + 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, + pass a :class:`pygmt.params.Box` object to control style, fill, pen, and other + box properties. bitcolor : str or list [*color*][**+b**\|\ **f**\|\ **t**]. Change certain pixel values to another color or make them transparent. @@ -82,7 +78,9 @@ def image( """ self._activate_figure() - aliasdict = AliasSystem().add_common( + aliasdict = AliasSystem( + F=Alias(box, name="box"), + ).add_common( J=projection, V=verbose, c=panel, diff --git a/pygmt/src/inset.py b/pygmt/src/inset.py index 030d7a26d0c..a36306210f6 100644 --- a/pygmt/src/inset.py +++ b/pygmt/src/inset.py @@ -5,26 +5,22 @@ import contextlib from typing import Literal -from pygmt.alias import AliasSystem +from pygmt.alias import Alias, AliasSystem from pygmt.clib import Session from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias +from pygmt.params import Box __doctest_skip__ = ["inset"] @fmt_docstring @contextlib.contextmanager -@use_alias( - D="position", - F="box", - M="margin", - N="no_clip", - R="region", -) +@use_alias(D="position", M="margin", N="no_clip", R="region") @kwargs_to_strings(D="sequence", M="sequence", R="sequence") def inset( self, projection=None, + box: Box | bool = False, verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"] | bool = False, **kwargs, @@ -39,6 +35,7 @@ def inset( Full GMT docs at :gmt-docs:`inset.html`. {aliases} + - F = box - J = projection - V = verbose @@ -83,27 +80,11 @@ def inset( as *refpoint*, if **J** is used then *justify* defaults to the mirror opposite of *refpoint*. Specify inset box attributes via the ``box`` parameter [Default is outline only]. - box : str or bool - [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ - *pen*]][**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ - [[*dx*/*dy*/][*shade*]]]. - If set to ``True``, draw a rectangular box around the map - inset using the default pen; specify a different pen - with **+p**\ *pen*. Add **+g**\ *fill* to fill the inset box - [Default is no fill]. - Append **+c**\ *clearance* where *clearance* is either - *gap*, *xgap*\ /\ *ygap*, or *lgap*\ /\ *rgap*\ /\ *bgap*\ /\ - *tgap* where these items are uniform, separate in x- and - y-directions, or individual side spacings between map embellishment - and border. Append **+i** to draw a secondary, inner border as well. - We use a uniform *gap* between borders of 2p and the default pen - unless other values are specified. Append **+r** to draw rounded - rectangular borders instead, with a 6p corner radius. You - can override this radius by appending another value. Append - **+s** to draw an offset background shaded region. Here, *dx*/*dy* - indicates the shift relative to the foreground frame [Default is - ``"4p/-4p"``] and *shade* sets the fill style to use for - shading [Default is ``"gray50"``]. + box + Draw a background box behind the inset. If set to ``True``, a simple rectangular + box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box appearance, + pass a :class:`pygmt.params.Box` object to control style, fill, pen, and other + box properties. margin : float, str, or list This is clearance that is added around the inside of the inset. Plotting will take place within the inner region only. The margins @@ -147,7 +128,9 @@ def inset( """ self._activate_figure() - aliasdict = AliasSystem().add_common( + aliasdict = AliasSystem( + F=Alias(box, name="box"), + ).add_common( J=projection, V=verbose, ) diff --git a/pygmt/src/legend.py b/pygmt/src/legend.py index 47901676aac..9e609197559 100644 --- a/pygmt/src/legend.py +++ b/pygmt/src/legend.py @@ -6,7 +6,7 @@ from typing import Literal from pygmt._typing import PathLike -from pygmt.alias import AliasSystem +from pygmt.alias import Alias, AliasSystem from pygmt.clib import Session from pygmt.exceptions import GMTTypeError from pygmt.helpers import ( @@ -17,22 +17,18 @@ kwargs_to_strings, use_alias, ) +from pygmt.params import Box @fmt_docstring -@use_alias( - R="region", - D="position", - F="box", - p="perspective", -) +@use_alias(R="region", D="position", p="perspective") @kwargs_to_strings(R="sequence", p="sequence") def legend( self, spec: PathLike | io.StringIO | None = None, projection=None, position="JTR+jTR+o0.2c", - box="+gwhite+p1p", + box: Box | bool = False, verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"] | bool = False, panel: int | tuple[int, int] | bool = False, @@ -51,6 +47,7 @@ def legend( Full GMT docs at :gmt-docs:`legend.html`. {aliases} + - F = box - J = projection - V = verbose - c = panel @@ -77,13 +74,11 @@ def legend( legend. By default, uses **JTR**\ **+jTR**\ **+o**\ 0.2c which places the legend at the top-right corner inside the map frame, with a 0.2 cm offset. - box : bool or str - [**+c**\ *clearances*][**+g**\ *fill*][**+i**\ [[*gap*/]\ *pen*]]\ - [**+p**\ [*pen*]][**+r**\ [*radius*]][**+s**\ [[*dx*/*dy*/][*shade*]]]. - If set to ``True``, draw a rectangular border around the legend - using :gmt-term:`MAP_FRAME_PEN`. By default, uses - **+g**\ white\ **+p**\ 1p which draws a box around the legend using a - 1p black pen and adds a white background. + box + Draw a background box behind the legend. If set to ``True``, a simple + rectangular box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box + appearance, pass a :class:`pygmt.params.Box` object to control style, fill, pen, + and other box properties. {verbose} {panel} {perspective} @@ -91,10 +86,11 @@ def legend( """ self._activate_figure() + # Default position and box when not specified. if kwargs.get("D") is None: kwargs["D"] = position - if kwargs.get("F") is None: - kwargs["F"] = box + if box is False and kwargs.get("F") is None: + box = Box(pen="1p", fill="white") # Default box kind = data_kind(spec) if kind not in {"empty", "file", "stringio"}: @@ -104,7 +100,9 @@ def legend( type(spec), reason="Only one legend specification file is allowed." ) - aliasdict = AliasSystem().add_common( + aliasdict = AliasSystem( + F=Alias(box, name="box"), + ).add_common( J=projection, V=verbose, c=panel, diff --git a/pygmt/src/logo.py b/pygmt/src/logo.py index f81b189bf61..224e511b703 100644 --- a/pygmt/src/logo.py +++ b/pygmt/src/logo.py @@ -4,22 +4,19 @@ from typing import Literal -from pygmt.alias import AliasSystem +from pygmt.alias import Alias, AliasSystem from pygmt.clib import Session from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias +from pygmt.params import Box @fmt_docstring -@use_alias( - R="region", - D="position", - F="box", - S="style", -) +@use_alias(R="region", D="position", S="style") @kwargs_to_strings(R="sequence", p="sequence") def logo( self, projection=None, + box: Box | bool = False, verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"] | bool = False, panel: int | tuple[int, int] | bool = False, @@ -37,6 +34,7 @@ def logo( Full GMT docs at :gmt-docs:`gmtlogo.html`. {aliases} + - F = box - J = projection - V = verbose - c = panel @@ -50,9 +48,11 @@ def logo( [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\ **+w**\ *width*\ [**+j**\ *justify*]\ [**+o**\ *dx*\ [/*dy*]]. Set reference point on the map for the image. - box : bool or str - If set to ``True``, draw a rectangular border around the - GMT logo. + box + Draw a background box behind the logo. If set to ``True``, a simple rectangular + box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box appearance, + pass a :class:`pygmt.params.Box` object to control style, fill, pen, and other + box properties. style : str [**l**\|\ **n**\|\ **u**]. Control what is written beneath the map portion of the logo. @@ -67,7 +67,9 @@ def logo( """ self._activate_figure() - aliasdict = AliasSystem().add_common( + aliasdict = AliasSystem( + F=Alias(box, name="box"), + ).add_common( J=projection, V=verbose, c=panel,