{"id":13423467,"url":"https://github.com/yixuan/showtext","last_synced_at":"2025-04-08T02:42:57.228Z","repository":{"id":12404515,"uuid":"15057921","full_name":"yixuan/showtext","owner":"yixuan","description":"Using Fonts More Easily in R Graphs","archived":false,"fork":false,"pushed_at":"2024-03-02T02:17:09.000Z","size":5004,"stargazers_count":489,"open_issues_count":19,"forks_count":38,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-04-01T01:41:15.133Z","etag":null,"topics":["font","graphics","graphics-device","r-graphics"],"latest_commit_sha":null,"homepage":"http://cran.r-project.org/web/packages/showtext/index.html","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"atombrenner/my-hubot","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yixuan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-12-09T20:14:39.000Z","updated_at":"2025-03-29T18:52:29.000Z","dependencies_parsed_at":"2024-05-02T07:58:13.396Z","dependency_job_id":"97eefb52-d343-4c9d-9811-041a90d1c912","html_url":"https://github.com/yixuan/showtext","commit_stats":{"total_commits":275,"total_committers":3,"mean_commits":91.66666666666667,"dds":"0.26909090909090905","last_synced_commit":"38e7b53c40b6bc11a7482acb382b1c4d5411dd3a"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yixuan%2Fshowtext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yixuan%2Fshowtext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yixuan%2Fshowtext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yixuan%2Fshowtext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yixuan","download_url":"https://codeload.github.com/yixuan/showtext/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247767232,"owners_count":20992538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["font","graphics","graphics-device","r-graphics"],"created_at":"2024-07-31T00:00:35.263Z","updated_at":"2025-04-08T02:42:57.202Z","avatar_url":"https://github.com/yixuan.png","language":"C","funding_links":[],"categories":["C","Graphic Displays","Presentation, composition and scales"],"sub_categories":[],"readme":"## showtext\u003cimg src=\"https://statr.me/images/sticker-showtext.png\" alt=\"showtext\" height=\"150px\" align=\"right\" /\u003e\n\n### What's this package all about?\n\n**showtext** makes it easy to use various types of fonts (TrueType, OpenType,\nType 1, web fonts, etc.) in R plots. The motivation to develop this package\nis that using non-standard fonts in R plots (especially for PDF device)\nis not straightforward, for example, when creating PDF with Chinese characters.\nThis is because most of the standard fonts used by `pdf()` do not contain\nChinese character glyphs, and users could hardly use system fonts in R.\n\nThe [extrafont](https://github.com/wch/extrafont) package developed by\n[Winston Chang](https://github.com/wch) is one nice solution to this problem,\nwhich mainly focuses on using TrueType fonts (`.ttf`) in PDF graphics device.\nNow **showtext** is able to support more font formats and more graphics devices,\nand avoids using external software such as Ghostscript.\n\n### A quick example\n\n```r\nlibrary(showtext)\n## Loading Google fonts (https://fonts.google.com/)\nfont_add_google(\"Gochi Hand\", \"gochi\")\nfont_add_google(\"Schoolbell\", \"bell\")\nfont_add_google(\"Covered By Your Grace\", \"grace\")\nfont_add_google(\"Rock Salt\", \"rock\")\n\n## Automatically use showtext to render text for future devices\nshowtext_auto()\n\n## Tell showtext the resolution of the device,\n## only needed for bitmap graphics. Default is 96\nshowtext_opts(dpi = 96)\n\nset.seed(123)\nx = rnorm(10)\ny = 1 + x + rnorm(10, sd = 0.2)\ny[1] = 5\nmod = lm(y ~ x)\n\nop = par(cex.lab = 2, cex.axis = 1.5, cex.main = 2)\nplot(x, y, pch = 16, col = \"steelblue\",\n     xlab = \"X variable\", ylab = \"Y variable\", family = \"gochi\")\ngrid()\ntitle(\"Draw Plots Before You Fit A Regression\", family = \"bell\")\ntext(-0.5, 4.5, \"This is the outlier\", cex = 2, col = \"steelblue\",\n     family = \"grace\")\nabline(coef(mod))\nabline(1, 1, col = \"red\")\npar(family = \"rock\")\ntext(1, 1, expression(paste(\"True model: \", y == x + 1)),\n     cex = 1.5, col = \"red\", srt = 20)\ntext(0, 2, expression(paste(\"OLS: \", hat(y) == 0.79 * x + 1.49)),\n     cex = 1.5, srt = 15)\nlegend(\"topright\", legend = c(\"Truth\", \"OLS\"), col = c(\"red\", \"black\"), lty = 1)\n\npar(op)\n```\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://i.imgur.com/7dmcchI.png\" alt=\"quick_example\" /\u003e\n\u003c/div\u003e\n\nIn this example we first load some fonts that are available online\nthrough [Google Fonts](https://fonts.google.com/), and then tell R\nto render text using **showtext** by calling the `showtext_auto()`\nfunction. All the remaining part is exactly the same as the usual plotting\ncommands.\n\nThis example should work on most graphics devices, including `pdf()`,\n`png()`, `postscript()`, and on-screen devices such as `windows()` on\nWindows and `x11()` on Linux.\n\n### How **showtext** works\n\nLet me first explain a little bit how `pdf()` works.\n\nTo my best knowledge, the default PDF device in R does not \"draw\" the text,\nbut actually \"describes\" the text in the PDF file.\nThat is to say, instead of drawing lines and curves of the actual glyph,\nit only embeds information about the text, for example what characters\nit has, which font it uses, etc.\n\nHowever, the text with declared font may be displayed differently in\ndifferent OS, which means that the appearance of graph created by `pdf()` is\nsystem dependent. If you unfortunately do not have the declared font\nin your system, you may not be able to see the text correctly at all. \n\nIn comparison, **showtext** package tries to solve this problem by\nconverting text into color-filled polygonal outlines (for vector graphics)\nor raster images (for bitmap and on-screen graphics), thus having the\nsame appearance under all platforms. People who view this graph do not\nneed to install the font that creates the graph. It provides convenience to\nboth graph makers and graph viewers.\n\nMore importantly, **showtext** can use system font files, so you can\nshow text in the graph with your favourite font face, as long as it\nis supported by FreeType. See section **Loading fonts** below.\n\n### The usage\n\nTo create a graph using a specified font, you simply do the following:\n\n- (\\*) Load the font to be used by **showtext**\n- Open the graphics device\n- (\\*) Claim that you want to use **showtext** to draw the text\n- Plot\n- Close the device\n\nOnly the steps marked with (\\*) are new. If you want to use\n**showtext** globally, you can call the function `showtext_auto()`\nonce, and then all the devices after that will automatically use\n**showtext** to render text, as the example in the beginning shows.\n\nIf you want to have finer control on which part of the code should use\n**showtext**, functions `showtext_begin()` and `showtext_end()` will help.\nOnly plotting functions enclosed by this pair of calls will use **showtext**,\nand others not. For example, to change the title font only, we can do:\n\n```r\nlibrary(showtext)\nfont_add_google(\"Schoolbell\", \"bell\")\n\n## By default the automatic call of showtext is disabled\n## You can manually turn it off using the line below\n## showtext_auto(enable = FALSE)\n\n## To use showtext_begin() and showtext_end() you need to\n## explicitly open a graphics device\npng(\"demo.png\", 700, 600, res = 96)\nset.seed(123)\nx = rnorm(10)\ny = 1 + x + rnorm(10, sd = 0.2)\ny[1] = 5\nmod = lm(y ~ x)\n\nop = par(cex.lab = 1.5, cex.axis = 1.5, cex.main = 2)\nplot(x, y, pch = 16, col = \"steelblue\",\n     xlab = \"X variable\", ylab = \"Y variable\")\ngrid()\n\n## Use showtext only for this part\nshowtext_begin()\ntitle(\"Draw Plots Before You Fit A Regression\", family = \"bell\")\nshowtext_end()\n\ntext(-0.5, 4.5, \"This is the outlier\", cex = 2, col = \"steelblue\")\nabline(coef(mod))\nabline(1, 1, col = \"red\")\ntext(1, 1, expression(paste(\"True model: \", y == x + 1)),\n     cex = 1.5, col = \"red\", srt = 20)\ntext(0, 2, expression(paste(\"OLS: \", hat(y) == 0.79 * x + 1.49)),\n     cex = 1.5, srt = 15)\nlegend(\"topright\", legend = c(\"Truth\", \"OLS\"), col = c(\"red\", \"black\"), lty = 1)\n\npar(op)\ndev.off()\n```\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://i.imgur.com/uZAJafE.png\" alt=\"demo-2\" /\u003e\n\u003c/div\u003e\n\n### Loading fonts\n\nLoading font is actually done by package **sysfonts**.\n\nThe easy way to load font into **showtext** is by calling `font_add(family, regular)`,\nwhere `family` is the name that you assign to that font (so that later you can\ncall `par(family = ...)` to use this font in plotting), and `regular` is the\npath to the font file. That is to say, only knowing the \"font name\" is not\nenough, since they are usually system dependent. On the contrary, font file\nis the entity that actually provides the character glyphs.\n\nUsually the font files are located in some \"standard\" directories in the system \n(for example on Windows it is typically `C:\\Windows\\Fonts`).\nYou can use `font_paths()` to check the current search path or add a new one,\nand use `font_files()` to list available font files in the search path.\n`font_files()` also lists some other useful information, for example the family\nname that you usually use to specify a font, and the font face for different\nvariants. Below is an example to show the results on my machine:\n\n```r\nhead(font_files())\n\n##                     path                           file               family\n## 1 ***/.local/share/fonts            Flavors-Regular.ttf              Flavors\n## 2 ***/.local/share/fonts FrederickatheGreat-Regular.ttf Fredericka the Great\n## 3 ***/.local/share/fonts           GandhiSerif-Bold.otf         Gandhi Serif\n## 4 ***/.local/share/fonts     GandhiSerif-BoldItalic.otf         Gandhi Serif\n## 5 ***/.local/share/fonts         GandhiSerif-Italic.otf         Gandhi Serif\n## 6 ***/.local/share/fonts        GandhiSerif-Regular.otf         Gandhi Serif\n##\n##          face       version                    ps_name\n## 1     Regular Version 1.001            Flavors-Regular\n## 2     Regular Version 1.001 FrederickatheGreat-Regular\n## 3        Bold Version 1.001           GandhiSerif-Bold\n## 4 Bold Italic Version 1.001     GandhiSerif-BoldItalic\n## 5      Italic Version 1.001         GandhiSerif-Italic\n## 6     Regular Version 1.001        GandhiSerif-Regular\n```\n\nAnd the code below demonstrates how to load and use system fonts on Windows:\n\n```r\nlibrary(showtext)\n## Add fonts that are available on Windows\nfont_add(\"heiti\", \"simhei.ttf\")\nfont_add(\"constan\", \"constan.ttf\", italic = \"constani.ttf\")\n\nlibrary(ggplot2)\np = ggplot(NULL, aes(x = 1, y = 1)) + ylim(0.8, 1.2) +\n    theme(axis.title = element_blank(), axis.ticks = element_blank(),\n          axis.text = element_blank()) +\n    annotate(\"text\", 1, 1.1, family = \"heiti\", size = 15,\n             label = \"\\u4F60\\u597D\\uFF0C\\u4E16\\u754C\") +\n    annotate(\"text\", 1, 0.9, label = 'Chinese for \"Hello, world!\"',\n             family = \"constan\", fontface = \"italic\", size = 12)\n\n## Automatically use showtext for new devices\nshowtext_auto()\n\n## On-screen device\nx11()\nprint(p)\ndev.off()\n\n## PDF device\npdf(\"showtext-example-3.pdf\", 7, 4)\nprint(p)\ndev.off()\n\n## PNG device\nggsave(\"showtext-example-4.png\", width = 7, height = 4, dpi = 96)\n\n## Turn off if no longer needed\nshowtext_auto(FALSE)\n```\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://i.imgur.com/Z3r9sg2.png\" alt=\"example1\" /\u003e\n\u003c/div\u003e\n\nFor other OS, you may not have the `simhei.ttf` font file, but there is no\ndifficulty in using something else. At present `font_add()` supports TrueType\nfonts(\\*.ttf/\\*.ttc) and OpenType fonts(\\*.otf), and adding new\nfont type is trivial as long as FreeType supports it.\n\nAlso, there are many free fonts available and accessible on the web, for instance\nthe Google Fonts project ([https://fonts.google.com/](https://fonts.google.com/)).\n**sysfonts** provides an interface to automatically download and register those fonts\nthrough the function `font_add_google()`, as the example below shows.\n\n```r\nlibrary(showtext)\nfont_add_google(\"Lobster\", \"lobster\")\n\nshowtext_auto()\n\nplot(1, pch = 16, cex = 3)\ntext(1, 1.1, \"A fancy dot\", family = \"lobster\", col = \"steelblue\", cex = 3)\n```\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://i.imgur.com/pO87LFy.png\" alt=\"example2\" /\u003e\n\u003c/div\u003e\n\n### CJK fonts\n\n**showtext** includes an open source CJK (Chinese, Japanese, and Korean) font\n[WenQuanYi Micro Hei](http://wenq.org/wqy2/index.cgi?MicroHei%28en%29).\nIf you just want to show CJK text in your graph, simply specify the `wqy-microhei`\nfamily name in plotting functions.\n\nAnother option is to install the\n[Source Han Sans](https://github.com/adobe-fonts/source-han-sans)/[Serif](https://github.com/adobe-fonts/source-han-serif)\nfonts locally using the following code:\n\n```r\nlibrary(showtext)\nfont_install(source_han_serif())\nfont_families()\n## [1] \"sans\"                \"serif\"               \"mono\"                \"wqy-microhei\"       \n## [5] \"source-han-serif-cn\"\n```\n\nSee `?font_install` and `?source_han` for more details.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://i.imgur.com/oOejBrI.png\" alt=\"source han\" /\u003e\n\u003c/div\u003e\n\n### The internals of **showtext**\n\nEvery graphics device in R implements some functions to draw specific graphical\nelements, e.g., `path()` and `polygon()` to draw polygons, `raster()` to display\nbitmap images, `text()` or `textUTF8()` to show text, etc. What `showtext` does\nis to override their own text rendering functions and replace them by hooks\nprovided in **showtext** that will further call the device's `path()` or `raster()`\nfunctions to draw the character glyphs.\n\nThis action is done only when you call `showtext_begin()` and won't modify the\ngraphics device if you call `showtext_end()` to restore the original device functions back.\n\n### Compatibility with RStudio\n\nStarting from version 0.9, **showtext** can work well with the RStudio graphics\ndevice (RStudioGD). Simply call `showtext_auto()` in the RStudio session and then\nthe plots will be displayed correctly.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyixuan%2Fshowtext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyixuan%2Fshowtext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyixuan%2Fshowtext/lists"}