Export and Conversion

The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

Overview

cardargus provides two rendering engines for converting SVG to PNG/PDF:

Engine	Package	Fonts	Best For
rsvg	`rsvg`, `magick`	Embedded only	Speed, no Chrome dependency
Chrome	`chromote`	Web fonts + embedded	Perfect font rendering

Saving as SVG

The simplest way to save a card:

library(cardargus)

card <- svg_card(
  title = "PROJECT",
  badges_data = list(list(label = "Status", value = "Active")),
  fields = list(list(list(label = "Name", value = "Test"))),
  bg_color = "#3498db"
)

# Save to file (with embedded fonts)
save_svg(card, "my_card.svg")

Converting to PNG

Standard conversion (rsvg)

Uses librsvg/ImageMagick. Fast and reliable, but requires fonts to be embedded in the SVG:

# Convert SVG string to PNG
svg_to_png(card, "my_card.png")

# With custom DPI (default is 300)
svg_to_png(card, "my_card.png", dpi = 300)

Chrome-based conversion (recommended for fonts)

Uses headless Chrome via the chromote package. Provides perfect font rendering, including Google Fonts loaded via @import:

# Check if Chrome is available
if (chrome_available()) {
  # High-quality PNG with Chrome
  svg_to_png_chrome(card, "my_card.png", dpi = 300)
}

# Convert to PDF (vector output)
svg_to_pdf_chrome(card, "my_card.pdf")

Installing Chrome support

# Install chromote package
install.packages("chromote")

# Check if Chrome is available
chrome_available()

# If Chrome is not installed, download it automatically
ensure_chrome(download = TRUE)

# This downloads "Chrome for Testing" (~150MB) to your user cache
# No admin/root permissions required!

Background options

# Transparent background (preserves rounded corners)
svg_to_png(card, "card_transparent.png", dpi = 300)

# White background
svg_to_png(card, "card_white.png", dpi = 300, background = "white")

# Chrome also supports backgrounds
svg_to_png_chrome(card, "card_white.png", dpi = 300, background = "white")

PNG with margin

Add a margin around the card:

# Add 20px margin with white background
svg_to_png_with_margin(
  card,
  output_path = "card_with_margin.png",
  margin = 20,
  background = "white",
  dpi = 300
)

Multiple formats

Export to multiple formats at once:

# Export to SVG and PNG
svg_to_formats(
  card,
  output_base = "exports/my_card",  # Without extension
  formats = c("svg", "png"),
  dpi = 300
)
# Creates: exports/my_card.svg, exports/my_card.png

Batch processing

Convert multiple cards efficiently:

# Create multiple cards
cards <- list(
  svg_card(title = "Card 1", badges_data = list(), fields = list()),
  svg_card(title = "Card 2", badges_data = list(), fields = list()),
  svg_card(title = "Card 3", badges_data = list(), fields = list())
)

# Batch convert to PNG
batch_svg_to_png(
  svg_list = cards,
  output_dir = "output/cards",
  prefix = "card",
  dpi = 300,
  background = "white"
)
# Creates: output/cards/card_001.png, card_002.png, card_003.png

Displaying in R Markdown / Quarto

Choosing the rendering engine

All knitr functions support an engine parameter:

"auto" (default): Uses Chrome if available, otherwise rsvg
"chrome": Forces Chrome (errors if unavailable)
"rsvg": Forces rsvg/magick

Inline SVG display

# Display card directly in document (HTML only)
include_card(card)

# With custom width
include_card(card, width = "80%")

PNG display (better compatibility)

# Display as PNG with auto engine selection
include_card_png(card, dpi = 150)

# Force Chrome for best font rendering
include_card_png(card, dpi = 300, engine = "chrome")

# Force rsvg (faster, no Chrome dependency)
include_card_png(card, dpi = 300, engine = "rsvg")

Save for knitr

# Save and get path for knitr::include_graphics
path <- save_card_for_knitr(
  card, 
  filename = "my_card", 
  format = "png", 
  dpi = 300,
  engine = "chrome"  # or "auto", "rsvg"
)
knitr::include_graphics(path)

Custom knitr engine

# Register the cardargus engine
register_cardargus_knitr()

# Then in a chunk with engine='cardargus':
# ```{cardargus}
# svg_card(title = "Dynamic Card", ...)
# ```

Integration with grid/ggplot2

Convert cards to grobs for use with grid graphics:

library(grid)

# Convert card to grob (auto-selects best engine)
grob <- card_to_grob(card, dpi = 150)

# Force Chrome rendering
grob <- card_to_grob(card, dpi = 150, engine = "chrome")

# Draw in a grid viewport
grid.newpage()
grid.draw(grob)

Quality settings

DPI recommendations

Use Case	DPI	Notes
Screen/web	72-96	Smaller file size
Standard print	150	Good balance
High-quality print	300	Publication quality
Large format	300+	Posters, banners

DPI and Chrome scaling

Chrome uses 96 DPI as its base resolution. When you set dpi = 300, cardargus calculates a scale factor:

scale = dpi / 96 = 300 / 96 ≈ 3.125x

This means a 400×300 SVG becomes a 1250×938 PNG at 300 DPI.

File size considerations

# Smaller file (lower quality)
svg_to_png_chrome(card, "card_web.png", dpi = 96)

# Medium file (balanced)
svg_to_png_chrome(card, "card_standard.png", dpi = 150)

# Larger file (high quality)
svg_to_png_chrome(card, "card_print.png", dpi = 300)

Comparing engines

# Same card, different engines
svg_to_png(card, "card_rsvg.png", dpi = 300)
svg_to_png_chrome(card, "card_chrome.png", dpi = 300)

# Chrome generally produces better results for:
# - Google Fonts and custom web fonts
# - Complex CSS styling
# - Font weights and variants

Error handling

# Safe conversion with fallback
convert_card <- function(card, output_path, dpi = 300) {
  if (chrome_available()) {
    svg_to_png_chrome(card, output_path, dpi = dpi)
  } else {
    message("Chrome not available, using rsvg")
    svg_to_png(card, output_path, dpi = dpi)
  }
}

# With explicit error handling
tryCatch({
  svg_to_png_chrome(card, "output.png", dpi = 300)
  message("Conversion successful!")
}, error = function(e) {
  message("Chrome conversion failed: ", e$message)
  message("Falling back to rsvg...")
  svg_to_png(card, "output.png", dpi = 300)
})

Troubleshooting

Fonts not rendering correctly with rsvg

This is expected behavior. librsvg cannot:

Load fonts via @import url(...)
Make HTTP requests for web fonts

Solution: Use svg_to_png_chrome() or ensure fonts are embedded with save_svg().

Chrome not found

# Check Chrome availability
chrome_available()

# Option 1: Download Chrome for Testing automatically
ensure_chrome(download = TRUE)

# Option 2: Set path to existing Chrome manually
Sys.setenv(CHROMOTE_CHROME = "/path/to/chrome")

# Option 3: Find where Chrome is installed
find_chrome_path()

Slow Chrome conversion

Chrome has startup overhead. For batch processing, consider:

# For many cards, rsvg may be faster if fonts are embedded
svg_to_png(card, "output.png", dpi = 300)

# Or accept the Chrome overhead for perfect rendering
svg_to_png_chrome(card, "output.png", dpi = 300)

Timeout errors

# Increase timeout for complex SVGs
svg_to_png_chrome(card, "output.png", timeout = 60)  # 60 seconds

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.