diff --git a/examples/tutorials/advanced/non_ascii_text.py b/examples/tutorials/advanced/non_ascii_text.py new file mode 100644 index 00000000000..d51a8084281 --- /dev/null +++ b/examples/tutorials/advanced/non_ascii_text.py @@ -0,0 +1,77 @@ +# ruff: noqa: RUF001,RUF003 +""" +Typesetting non-ASCII text +-------------------------- + +In addition to ASCII printable characters, sometimes you may also want to typeset +non-ASCII characters on the plot, such as Greek letters, mathematical symbols, or +special characters. + +Due to the limitations of the underlying PostScript language, PyGMT doesn't support +all characters in the Unicode standard. Instead, PyGMT supports a limited set of +characters in the "Adobe Symbol", "Adobe ZapfDingbats", "Adobe ISOLatin1+", and +"ISO-8859-*x*" (*x* can be 1-11, 13-16) encodings. Refer to :doc:`/techref/encodings` +for the complete list of supported characters. + +In PyGMT, the supported (ASCII and non-ASCII) characters can be directly used in the +``text`` parameter of the :meth:`pygmt.Figure.text` method for typesetting text strings. +They can also be used in the arguments of other plotting functions (e.g., in the +``frame`` parameter to set the labels or title). + +In this example, we demonstrate how to typeset non-ASCII characters in PyGMT. +""" + +# %% +import pygmt + +fig = pygmt.Figure() +fig.basemap( + region=[0, 5, 0, 6], + projection="X14c/7c", + frame=["xaf+lDistance (°)", "yaf+lValue (‰)", "WSen+tTitle: α² ± β²"], +) + +fig.text( + x=[0.2, 0.2, 0.2, 0.2, 0.2], + y=[5, 4, 3, 2, 1], + text=["ASCII:", "ISOLatin1+:", "Symbol:", "ZapfDingbats:", "Mixed:"], + font="20p,Helvetica-Bold,red", + justify="LM", +) +fig.text( + x=[2, 2, 2, 2, 2], + y=[5, 4, 3, 2, 1], + text=[ + "ABCDE12345!#$:;<=>?", # ASCII only + "±°ÀÁÂÃÄÅÈÌÒÙàèìòù", # Non-ASCII characters from Adobe ISOLatin1+ + "αβγδεζηθ⊗⊕∅⊃⊇⊄⊂⊆", # Non-ASCII characters from Adobe Symbol + "✈♥♦♣♠❛❜❝❞❨❩❪❫❬❭❮❯→↔", # Non-ASCII characters from Adobe ZapfDingbats + "ABCD αβγδ ①②③ ➊➋➌", # Mix characters from ISOLatin1+, Symbol and ZapfDingbats + ], + font="18p,Helvetica", + justify="LM", +) + +fig.show() + +# %% +# Here are some important tips when using non-ASCII characters: +# +# - **Similar-looking characters**: Be cautious when using characters that appear +# visually similar but are distinct. For example, ``Ω`` (OHM SIGN) and ``Ω`` (GREEK +# CAPITAL LETTER OMEGA) may look alike, but PyGMT only supports the latter. Using the +# incorrect character can lead to unexpected results. To avoid this, it's recommended +# to copy and paste characters from the :doc:`/techref/encodings` documentation. +# - **Mix characters from different encodings**: As shown in the example above, you can +# mix characters from different encodings in the same text string. However, due to the +# limitations of the underlying PostScript language, you cannot mix characters from +# the "Adobe ISOLatin1+" and "ISO-8859-*x*" encodings in the same text string. For +# example, you cannot mix characters from "Adobe ISOLatin1+" and "ISO-8859-2". If +# you need to use characters from different encodings, you can use them in different +# PyGMT function/method calls. +# - **Non-ASCII characters in text files**: Non-ASCII characters are not supported if +# you have them in a text file and pass it to :meth:`pygmt.Figure.text`. In this case, +# you may want to load the text file into :class:`pandas.DataFrame` and then pass it +# to the ``text`` parameter. + +# sphinx_gallery_thumbnail_number = 1