From caef6e970a6417c1643a81def03ecfaf4bfaa54e Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 25 Dec 2024 23:29:46 +0800 Subject: [PATCH 1/8] Figure.plot: Improve the docstring for 'straight_line' --- pygmt/src/plot.py | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/pygmt/src/plot.py b/pygmt/src/plot.py index ebfb2f22f3c..1020645af72 100644 --- a/pygmt/src/plot.py +++ b/pygmt/src/plot.py @@ -2,6 +2,8 @@ plot - Plot in two dimensions. """ +from typing import Literal + from pygmt.clib import Session from pygmt.exceptions import GMTInvalidInput from pygmt.helpers import ( @@ -49,7 +51,15 @@ ) @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence") def plot( - self, data=None, x=None, y=None, size=None, symbol=None, direction=None, **kwargs + self, + data=None, + x=None, + y=None, + size=None, + symbol=None, + direction=None, + straight_line: bool | Literal["x", "y"] = False, # noqa: ARG001 + **kwargs, ): r""" Plot lines, polygons, and symbols in 2-D. @@ -98,18 +108,18 @@ def plot( depending on the style options chosen. {projection} {region} - straight_line : bool or str - [**m**\|\ **p**\|\ **x**\|\ **y**]. - By default, geographic line segments are drawn as great circle - arcs. To draw them as straight lines, use - ``straight_line=True``. - Alternatively, add **m** to draw the line by first following a - meridian, then a parallel. Or append **p** to start following a - parallel, then a meridian. (This can be practical to draw a line - along parallels, for example). For Cartesian data, points are - simply connected, unless you append **x** or **y** to draw - stair-case curves that whose first move is along *x* or *y*, - respectively. + straight_line + By default, geographic line segments are drawn as great circle arcs by + resampling coarse input data along such arcs. To draw them as straight lines, + use ``straight_line=True``. Alternatively, setting it to ``"x"`` or ``"y"`` will + draw the line by first along *x*, then along *y*. + + Here, *x* and *y* have following meanings: + + - For Cartesian coordinate systems, *x* and *y* are the X- and Y-axes, + respectively + - For gragraphic projections, *x* and *y* are parallels and meridians + - For polar projections, *x* and *y* are theta and radius {frame} {cmap} offset : str From 13616025e20f2067e3aaa4cb1f3ae4a235b0cb18 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 27 Dec 2024 11:51:12 +0800 Subject: [PATCH 2/8] Rephrase again --- pygmt/src/plot.py | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/pygmt/src/plot.py b/pygmt/src/plot.py index 1020645af72..85765d64326 100644 --- a/pygmt/src/plot.py +++ b/pygmt/src/plot.py @@ -109,17 +109,23 @@ def plot( {projection} {region} straight_line - By default, geographic line segments are drawn as great circle arcs by - resampling coarse input data along such arcs. To draw them as straight lines, - use ``straight_line=True``. Alternatively, setting it to ``"x"`` or ``"y"`` will - draw the line by first along *x*, then along *y*. + By default, line segments are drawn as straight lines in the Cartesian and polar + coordinate systems, and as great circle arcs (by resampling coarse input data + along such arcs) in the geographic coordinate system. - Here, *x* and *y* have following meanings: + The ``straight_line`` parameter can control the drawing of line segments. Valid + values are: + + - ``True``: Draw line segments as straight lines in geographic projections. + - ``"x"``: Draw line segments by first along *x*, then along *y*. + - ``"y"``: Draw line segments by first along *y*, then along *x*. + + Here, *x* and *y* have different meanings depending on the coordinate system: + + - **Cartesian coordinate system**: *x* and *y* are the X- and Y-axes. + - **Polar coordinate system**: *x* and *y* are theta and radius. + - **Gragraphic coordinate system**: *x* and *y* are parallels and meridians. - - For Cartesian coordinate systems, *x* and *y* are the X- and Y-axes, - respectively - - For gragraphic projections, *x* and *y* are parallels and meridians - - For polar projections, *x* and *y* are theta and radius {frame} {cmap} offset : str From d3071a335d33e367b4eccd6c5d0c8cf542d4611e Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 27 Dec 2024 14:51:30 +0800 Subject: [PATCH 3/8] Fix formatting --- pygmt/src/plot.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pygmt/src/plot.py b/pygmt/src/plot.py index 85765d64326..724114ab349 100644 --- a/pygmt/src/plot.py +++ b/pygmt/src/plot.py @@ -122,9 +122,9 @@ def plot( Here, *x* and *y* have different meanings depending on the coordinate system: - - **Cartesian coordinate system**: *x* and *y* are the X- and Y-axes. - - **Polar coordinate system**: *x* and *y* are theta and radius. - - **Gragraphic coordinate system**: *x* and *y* are parallels and meridians. + - **Cartesian** coordinate system: *x* and *y* are the X- and Y-axes. + - **Polar** coordinate system: *x* and *y* are theta and radius. + - **Gragraphic** coordinate system: *x* and *y* are parallels and meridians. {frame} {cmap} From 98d195e081a034c7e44620d258190c1ee779af41 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 28 Dec 2024 00:10:17 +0800 Subject: [PATCH 4/8] One more fix --- pygmt/src/plot.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/pygmt/src/plot.py b/pygmt/src/plot.py index 724114ab349..c6cd1d523dd 100644 --- a/pygmt/src/plot.py +++ b/pygmt/src/plot.py @@ -111,10 +111,8 @@ def plot( straight_line By default, line segments are drawn as straight lines in the Cartesian and polar coordinate systems, and as great circle arcs (by resampling coarse input data - along such arcs) in the geographic coordinate system. - - The ``straight_line`` parameter can control the drawing of line segments. Valid - values are: + along such arcs) in the geographic coordinate system. The ``straight_line`` + parameter can control the drawing of line segments. Valid values are: - ``True``: Draw line segments as straight lines in geographic projections. - ``"x"``: Draw line segments by first along *x*, then along *y*. From 3c3c52a675f2afcefc37b44152cb973016ddd0f7 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Tue, 31 Dec 2024 14:48:19 +0800 Subject: [PATCH 5/8] Fix a typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com> --- pygmt/src/plot.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/src/plot.py b/pygmt/src/plot.py index c6cd1d523dd..8c6d014952a 100644 --- a/pygmt/src/plot.py +++ b/pygmt/src/plot.py @@ -122,7 +122,7 @@ def plot( - **Cartesian** coordinate system: *x* and *y* are the X- and Y-axes. - **Polar** coordinate system: *x* and *y* are theta and radius. - - **Gragraphic** coordinate system: *x* and *y* are parallels and meridians. + - **Geographic** coordinate system: *x* and *y* are parallels and meridians. {frame} {cmap} From 9aa8f97fde9d028a8d85e80085509e91a88ea5b8 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Thu, 2 Jan 2025 18:57:31 +0800 Subject: [PATCH 6/8] Add a note about the bug in GMT<=6.5.0 --- pygmt/src/plot.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/pygmt/src/plot.py b/pygmt/src/plot.py index 8c6d014952a..23c5bde12fd 100644 --- a/pygmt/src/plot.py +++ b/pygmt/src/plot.py @@ -114,7 +114,8 @@ def plot( along such arcs) in the geographic coordinate system. The ``straight_line`` parameter can control the drawing of line segments. Valid values are: - - ``True``: Draw line segments as straight lines in geographic projections. + - ``True``: Draw line segments as straight lines in geographic coordinate + systems. - ``"x"``: Draw line segments by first along *x*, then along *y*. - ``"y"``: Draw line segments by first along *y*, then along *x*. @@ -124,6 +125,12 @@ def plot( - **Polar** coordinate system: *x* and *y* are theta and radius. - **Geographic** coordinate system: *x* and *y* are parallels and meridians. + .. attention:: + + There exits a bug in GMT<=6.5.0 that, in geographic coordinate systems, the + meaning of *x* and *y* is reversed, i.e., *x* means meridians and *y* means + parallels. The bug is fixed by upstream + `PR #8648 `__. {frame} {cmap} offset : str @@ -220,6 +227,8 @@ def plot( ``x``/``y``. {wrap} """ + # TODO(GMT>6.5.0): Remove the note for the upstream bug of the "straight_line" + # parameter. kwargs = self._preprocess(**kwargs) kind = data_kind(data) From 7009972edd1fd771ae910937c87180ab2d7db6b7 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sun, 5 Jan 2025 12:00:27 +0800 Subject: [PATCH 7/8] Apply the same changes to plot3d --- pygmt/src/plot3d.py | 40 ++++++++++++++++++++++++++++------------ 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/pygmt/src/plot3d.py b/pygmt/src/plot3d.py index f7f2b08290a..6967a9943d8 100644 --- a/pygmt/src/plot3d.py +++ b/pygmt/src/plot3d.py @@ -2,6 +2,8 @@ plot3d - Plot in three dimensions. """ +from typing import Literal + from pygmt.clib import Session from pygmt.exceptions import GMTInvalidInput from pygmt.helpers import ( @@ -58,6 +60,7 @@ def plot3d( size=None, symbol=None, direction=None, + straight_line: bool | Literal["x", "y"] = False, # noqa: ARG001 **kwargs, ): r""" @@ -108,18 +111,29 @@ def plot3d( zscale/zsize : float or str Set z-axis scaling or z-axis size. {region} - straight_line : bool or str - [**m**\|\ **p**\|\ **x**\|\ **y**]. - By default, geographic line segments are drawn as great circle - arcs. To draw them as straight lines, use ``straight_line``. - Alternatively, add **m** to draw the line by first following a - meridian, then a parallel. Or append **p** to start following a - parallel, then a meridian. (This can be practical to draw a line - along parallels, for example). For Cartesian data, points are - simply connected, unless you append **x** or **y** to draw - stair-case curves that whose first move is along *x* or *y*, - respectively. **Note**: The ``straight_line`` parameter requires - constant *z*-coordinates. + straight_line + By default, line segments are drawn as straight lines in the Cartesian and polar + coordinate systems, and as great circle arcs (by resampling coarse input data + along such arcs) in the geographic coordinate system. The ``straight_line`` + parameter can control the drawing of line segments. Valid values are: + + - ``True``: Draw line segments as straight lines in geographic coordinate + systems. + - ``"x"``: Draw line segments by first along *x*, then along *y*. + - ``"y"``: Draw line segments by first along *y*, then along *x*. + + Here, *x* and *y* have different meanings depending on the coordinate system: + + - **Cartesian** coordinate system: *x* and *y* are the X- and Y-axes. + - **Polar** coordinate system: *x* and *y* are theta and radius. + - **Geographic** coordinate system: *x* and *y* are parallels and meridians. + + .. attention:: + + There exits a bug in GMT<=6.5.0 that, in geographic coordinate systems, the + meaning of *x* and *y* is reversed, i.e., *x* means meridians and *y* means + parallels. The bug is fixed by upstream + `PR #8648 `__. {frame} {cmap} offset : str @@ -189,6 +203,8 @@ def plot3d( ``x``/``y``/``z``. {wrap} """ + # TODO(GMT>6.5.0): Remove the note for the upstream bug of the "straight_line" + # parameter. kwargs = self._preprocess(**kwargs) kind = data_kind(data) From 9c148cf4afd321e04fbced407a63c3c605a4d548 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sun, 5 Jan 2025 12:01:45 +0800 Subject: [PATCH 8/8] One extra note for plot3d --- pygmt/src/plot3d.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pygmt/src/plot3d.py b/pygmt/src/plot3d.py index 6967a9943d8..e8e75382d74 100644 --- a/pygmt/src/plot3d.py +++ b/pygmt/src/plot3d.py @@ -128,6 +128,8 @@ def plot3d( - **Polar** coordinate system: *x* and *y* are theta and radius. - **Geographic** coordinate system: *x* and *y* are parallels and meridians. + **NOTE**: The ``straight_line`` parameter requires constant *z*-coordinates. + .. attention:: There exits a bug in GMT<=6.5.0 that, in geographic coordinate systems, the