diff --git a/doc/techref/justification_codes.md b/doc/techref/justification_codes.md index 0dccd539360..15566aa9e77 100644 --- a/doc/techref/justification_codes.md +++ b/doc/techref/justification_codes.md @@ -25,6 +25,7 @@ tags: [remove-input] Script showing the justification codes used in GMT / PyGMT. """ import pygmt +from pygmt.params import Position size = 5 x1 = [-size, 0, size, size, size, 0, -size, -size, 0] @@ -105,7 +106,14 @@ Script showing justification codes for plot embellishments, e.g., a colorbar. fig = pygmt.Figure() fig.basemap(projection="X10c/2c", region=[-size, size, -size, size], frame=0) -fig.colorbar(cmap="SCM/buda", frame=0, position="jMC+w10c/2c+h") +fig.colorbar( + cmap="SCM/buda", + frame=0, + position="MC", + length=10, + width=2, + orientation="horizontal" +) for code in codes: fig.text( diff --git a/examples/gallery/3d_plots/grdview_surface.py b/examples/gallery/3d_plots/grdview_surface.py index cfbeca1f5a0..b01b16c5185 100644 --- a/examples/gallery/3d_plots/grdview_surface.py +++ b/examples/gallery/3d_plots/grdview_surface.py @@ -18,6 +18,7 @@ import numpy as np import pygmt import xarray as xr +from pygmt.params import Position # Define an interesting function of two variables, see: @@ -46,8 +47,7 @@ def ackley(x, y): SCALE = 0.5 # in centimeters fig.grdview( data, - # Set annotations and gridlines in steps of five, and - # tick marks in steps of one + # Set annotations and gridlines in steps of five, and tick marks in steps of one frame=["a5f1g5", "za5f1g5"], projection=f"x{SCALE}c", zscale=f"{SCALE}c", @@ -57,10 +57,7 @@ def ackley(x, y): shading="+a45", ) -# Add colorbar for gridded data -fig.colorbar( - frame="a2f1", # Set annotations in steps of two, tick marks in steps of one - position="JMR", # Place colorbar in the Middle Right (MR) corner -) +# Add colorbar for gridded data in the Middle Right corner. +fig.colorbar(frame="a2f1", position=Position("MR", cstype="outside")) fig.show() diff --git a/examples/gallery/basemaps/ternary.py b/examples/gallery/basemaps/ternary.py index 7b225618154..91da1586837 100644 --- a/examples/gallery/basemaps/ternary.py +++ b/examples/gallery/basemaps/ternary.py @@ -14,6 +14,7 @@ # %% import pygmt +from pygmt.params import Position fig = pygmt.Figure() @@ -40,7 +41,8 @@ ], ) -# Add a colorbar indicating the values given in the fourth column of -# the input dataset -fig.colorbar(position="JBC+o0c/1.5c", frame="x+lPermittivity") +# Add a colorbar indicating the values given in the fourth column of the input dataset +fig.colorbar( + position=Position("BC", cstype="outside", offset=(0, 1.5)), frame="x+lPermittivity" +) fig.show() diff --git a/examples/gallery/embellishments/colorbar.py b/examples/gallery/embellishments/colorbar.py index 24bcd304129..595e3c7625f 100644 --- a/examples/gallery/embellishments/colorbar.py +++ b/examples/gallery/embellishments/colorbar.py @@ -2,30 +2,18 @@ Colorbar ======== -The :meth:`pygmt.Figure.colorbar` method creates a color scalebar. -The colormap is set via the ``cmap`` parameter. A full list of available -color palette tables can be found at :gmt-docs:`reference/cpts.html`. -Use the ``frame`` parameter to add labels to the **x** and **y** axes -of the colorbar by appending **+l** followed by the desired text. To add -and adjust the annotations (**a**) and ticks (**f**) append the letter -followed by the desired interval. The placement of the colorbar is set -via the ``position`` parameter. There are the following options: - -- **j/J**: placed inside/outside the plot bounding box using a - :doc:`2-character justification code `, e.g., - ``position="jTR"`` for Top Right. -- **g**: using map coordinates, e.g. ``position="g170/-45"`` for longitude - 170° East, latitude 45° South. -- **x**: using paper coordinates, e.g. ``position="x5c/7c"`` for 5 cm, 7 cm - from anchor point. -- **n**: using normalized (0-1) coordinates, e.g. ``position="n0.4/0.8"``. - -Note that the anchor point defaults to Bottom Left (**BL**). Append ``+h`` to -``position`` to get a horizontal colorbar instead of a vertical one (``+v``). +The :meth:`pygmt.Figure.colorbar` method creates a color scalebar. The colormap is set +via the ``cmap`` parameter. A full list of available color palette tables can be found +at :gmt-docs:`reference/cpts.html`. Use the ``frame`` parameter to add labels to the +**x** and **y** axes of the colorbar by appending **+l** followed by the desired text. +To add and adjust the annotations (**a**) and ticks (**f**) append the letter followed +by the desired interval. The placement of the colorbar is set by passing a +:class:`pygmt.params.Position` object to the ``position`` parameter. """ # %% import pygmt +from pygmt.params import Position fig = pygmt.Figure() fig.basemap(region=[0, 3, 6, 9], projection="x3c", frame=["af", "WSne+tColorbars"]) @@ -41,9 +29,12 @@ # Create a colorbar showing the scientific rainbow - batlow fig.colorbar( cmap="SCM/batlow", - # Colorbar positioned at map coordinates (g) longitude/latitude 0.3/8.7, - # with a length/width (+w) of 4 cm by 0.5 cm, and plotted horizontally (+h) - position="g0.3/8.7+w4c/0.5c+h", + # A horizontal colorbar positioned at map coordinates (0.3, 8.7), with a + # length of 4 cm and a width of 0.5 cm. + position=Position((0.3, 8.7), cstype="mapcoords"), + length=4, + width=0.5, + orientation="horizontal", box=True, frame=["x+lTemperature", "y+l°C"], scale=100, @@ -53,13 +44,17 @@ # Create a colorbar suitable for surface topography - oleron fig.colorbar( cmap="SCM/oleron", - # Colorbar placed outside the plot bounding box (J) at Middle Right (MR), - # offset (+o) by 1 cm horizontally and 0 cm vertically from anchor point, - # with a length/width (+w) of 7 cm by 0.5 cm and a box for NaN values (+n) - position="JMR+o1c/0c+w7c/0.5c+n+mc", + # Colorbar placed at Middle Right (MR) outside the plot bounding box, offset by 1 cm + # horizontally and 0 cm vertically from anchor point, with a length of 7 cm and + # width of 0.5 cm, and a rectangle for NaN values. # Note that the label 'Elevation' is moved to the opposite side and plotted - # vertically as a column of text using '+mc' in the position parameter - # above + # vertically as a column of text. + position=Position("MR", cstype="outside", offset=(1, 0)), + length=7, + width=0.5, + nan=True, + move_text=["annotations", "label"], + label_as_column=True, frame=["x+lElevation", "y+lm"], scale=10, ) @@ -76,10 +71,11 @@ # Plot the colorbar fig.colorbar( cmap=True, # Use colormap set up above - # Colorbar placed inside the plot bounding box (j) in the Bottom Left (BL) corner, - # with an offset (+o) by 0.5 cm horizontally and 0.8 cm vertically from the anchor - # point, and plotted horizontally (+h) - position="jBL+o0.5c/0.8c+h", + # Colorbar placed in the Bottom Left (BL) corner inside the plot bounding box, with + # an offset by 0.5 cm horizontally and 0.8 cm vertically from the anchor point, and + # plotted horizontally. + position=Position("BL", offset=(0.5, 0.8)), + orientation="horizontal", box=True, # Divide colorbar into equal-sized rectangles equalsize=0.5, diff --git a/examples/gallery/images/cross_section.py b/examples/gallery/images/cross_section.py index d55f68574e1..053b1ba6bd3 100644 --- a/examples/gallery/images/cross_section.py +++ b/examples/gallery/images/cross_section.py @@ -14,7 +14,7 @@ # %% import pygmt -from pygmt.params import Box +from pygmt.params import Box, Position # Define region of study area # lon_min, lon_max, lat_min, lat_max in degrees East and North @@ -41,10 +41,14 @@ # Add a colorbar for the elevation fig.colorbar( - # Place the colorbar inside the plot (lowercase "j") in the Bottom Right (BR) - # corner with an offset ("+o") of 0.7 centimeters and 0.3 centimeters in x- or y- - # directions, respectively; move the x-label above the horizontal colorbar ("+ml") - position="jBR+o0.7c/0.8c+h+w5c/0.3c+ml", + # Place the colorbar inside the plot in the Bottom Right (BR) corner with an offset + # of 0.7 centimeters and 0.3 centimeters in x- or y-directions, respectively; + # move the x-label above the horizontal colorbar. + position=Position("BR", offset=(0.7, 0.8)), + length=5, + width=0.3, + orientation="horizontal", + move_text="label", # Add a box around the colobar, filled in white and a 30 % transparency, with a # 0.8-point thick, black, outline. box=Box(pen="0.8p,black", fill="white@30"), diff --git a/examples/gallery/images/grdclip.py b/examples/gallery/images/grdclip.py index b034c20223a..522e6e3dba0 100644 --- a/examples/gallery/images/grdclip.py +++ b/examples/gallery/images/grdclip.py @@ -2,14 +2,15 @@ Clipping grid values ==================== -The :func:`pygmt.grdclip` function allows to clip defined ranges of grid -values. In the example shown below we set all elevation values (grid points) -smaller than 0 m (in general the bathymetric part of the grid) to a common -value of -2000 m via the ``below`` parameter. +The :func:`pygmt.grdclip` function allows to clip defined ranges of grid values. In the +example shown below we set all elevation values (grid points) smaller than 0 m (in +general the bathymetric part of the grid) to a common value of -2000 m via the ``below`` +parameter. """ # %% import pygmt +from pygmt.params.position import Position fig = pygmt.Figure() @@ -41,6 +42,10 @@ frame=["wSne+tclipped grid", "xa5f1", "ya2f1"], ) fig.grdimage(grid=grid) -fig.colorbar(frame=["x+lElevation", "y+lm"], position="JMR+o0.5c/0c+w8c") +fig.colorbar( + frame=["x+lElevation", "y+lm"], + position=Position("MR", cstype="outside", offset=(0.5, 0)), + length=8, +) fig.show() diff --git a/examples/gallery/images/grdgradient.py b/examples/gallery/images/grdgradient.py index 89ded87ca46..8fd4976eeb6 100644 --- a/examples/gallery/images/grdgradient.py +++ b/examples/gallery/images/grdgradient.py @@ -13,6 +13,7 @@ # %% import pygmt +from pygmt.params import Position # Define region of interest around Yosemite valley region = [-119.825, -119.4, 37.6, 37.825] @@ -37,8 +38,12 @@ frame=["WSrt+tOriginal Data Elevation Model", "xa0.1", "ya0.1"], cmap=True, ) - -fig.colorbar(position="JML+o1.4c/0c+w7c/0.5c", frame=["xa1000f500+lElevation", "y+lm"]) +fig.colorbar( + position=Position("ML", cstype="outside", offset=(1.4, 0)), + length=7, + width=0.5, + frame=["xa1000f500+lElevation", "y+lm"], +) # --------------- plotting the hillshade map ----------- diff --git a/examples/gallery/images/grdgradient_shading.py b/examples/gallery/images/grdgradient_shading.py index 1763f9ee7f1..3845c546d44 100644 --- a/examples/gallery/images/grdgradient_shading.py +++ b/examples/gallery/images/grdgradient_shading.py @@ -20,6 +20,7 @@ # %% import pygmt +from pygmt.params import Position # Load the 3 arc-minutes global relief grid in the target area around Caucasus grid = pygmt.datasets.load_earth_relief(resolution="03m", region=[35, 50, 35, 45]) @@ -59,6 +60,12 @@ panel=True, ) -fig.colorbar(position="JBC+w10c/0.25c+h", frame="xa2000f500+lElevation (m)") +fig.colorbar( + position=Position("BC", cstype="outside"), + length=10, + width=0.25, + orientation="horizontal", + frame="xa2000f500+lElevation (m)", +) fig.show() diff --git a/examples/gallery/images/grdlandmask.py b/examples/gallery/images/grdlandmask.py index 323b00392c9..808c2375aa8 100644 --- a/examples/gallery/images/grdlandmask.py +++ b/examples/gallery/images/grdlandmask.py @@ -8,6 +8,7 @@ # %% import pygmt +from pygmt.params import Position fig = pygmt.Figure() @@ -33,6 +34,6 @@ pygmt.makecpt(cmap="SCM/batlow", series=(0, 1, 1), color_model="+cwater,land") fig.grdimage(grid=grid, cmap=True) -fig.colorbar(position="JMR+o0.5c/0c+w8c") +fig.colorbar(position=Position("MR", cstype="outside", offset=(0.5, 0)), length=8) fig.show() diff --git a/examples/gallery/maps/choropleth_map.py b/examples/gallery/maps/choropleth_map.py index 9eb3b05bece..32221d41ae1 100644 --- a/examples/gallery/maps/choropleth_map.py +++ b/examples/gallery/maps/choropleth_map.py @@ -16,6 +16,7 @@ # %% import geopandas as gpd import pygmt +from pygmt.params.position import Position provider = "https://naciscdn.org/naturalearth" world = gpd.read_file(f"{provider}/110m/cultural/ne_110m_admin_0_countries.zip") @@ -36,6 +37,13 @@ fig.plot(data=africa, pen="0.8p,gray50", fill="+z", cmap=True, aspatial="Z=POP_EST") # Add colorbar legend. -fig.colorbar(frame="x+lPopulation (millions)", position="jML+o2c/-2.5c+w5c+ef0.2c+ml") +fig.colorbar( + frame="x+lPopulation (millions)", + position=Position("ML", offset=(2, -2.5)), + length=5, + fg_triangle=True, + triangle_height=0.2, + move_text="label", +) fig.show() diff --git a/examples/tutorials/advanced/draping_on_3d_surface.py b/examples/tutorials/advanced/draping_on_3d_surface.py index 31e82c47a29..c30f1046d48 100644 --- a/examples/tutorials/advanced/draping_on_3d_surface.py +++ b/examples/tutorials/advanced/draping_on_3d_surface.py @@ -70,7 +70,7 @@ ) # Add colorbar for the crustal age -fig.colorbar(frame=["x+lseafloor crustal age", "y+lMyr"], position="+n") +fig.colorbar(frame=["x+lseafloor crustal age", "y+lMyr"], nan=True) fig.show() diff --git a/examples/tutorials/advanced/grid_equalization.py b/examples/tutorials/advanced/grid_equalization.py index 8ded7692c28..4017d49f4b7 100644 --- a/examples/tutorials/advanced/grid_equalization.py +++ b/examples/tutorials/advanced/grid_equalization.py @@ -8,6 +8,7 @@ # %% import pygmt +from pygmt.params import Position # %% # Load sample data @@ -56,7 +57,12 @@ histtype=1, pen="1p,black", ) - fig.colorbar(position="JMR+o1.5c/0c+w3c/0.3c", frame=True) + fig.colorbar( + position=Position("MR", cstype="outside", offset=(1.5, 0)), + length=3, + width=0.3, + frame=True, + ) fig.show() @@ -125,7 +131,12 @@ pen="1p,black", center=True, ) - fig.colorbar(position="JMR+o1.5c/0c+w3c/0.3c", frame=True) + fig.colorbar( + position=Position("MR", cstype="outside", offset=(1.5, 0)), + length=3, + width=0.3, + frame=True, + ) fig.show() @@ -174,7 +185,12 @@ histtype=1, pen="1p,black", ) - fig.colorbar(position="JMR+o1.5c/0c+w3c/0.3c", frame=True) + fig.colorbar( + position=Position("MR", cstype="outside", offset=(1.5, 0)), + length=3, + width=0.3, + frame=True, + ) fig.show() @@ -239,7 +255,12 @@ pen="1p,black", center=True, ) - fig.colorbar(position="JMR+o1.5c/0c+w3c/0.3c", frame=True) + fig.colorbar( + position=Position("MR", cstype="outside", offset=(1.5, 0)), + length=3, + width=0.3, + frame=True, + ) fig.show() # sphinx_gallery_thumbnail_number = 3