--- title: "Using resmush" bibliography: REFERENCES.bib link-citations: true vignette: > %\VignetteIndexEntry{resmush} %\VignetteEngine{quarto::html} %\VignetteEncoding{UTF-8} tbl-cap-location: bottom --- **resmush** is an **R** package for optimizing local and online image files, individually or in entire directories, with the [**reSmush.it** API](https://resmush.it/api/). The API is free for personal use and does not require an API key. **reSmush.it** is also available through [WordPress](https://wordpress.org/plugins/resmushit-image-optimizer/) and [other tools](https://resmush.it/tools/). The **reSmush.it** API provides: - Optimization without an API key. - Support for PNG, JPEG, GIF, BMP and TIFF files. - A file size limit of less than 5 MB. - Compression powered by several algorithms: - [**pngquant**](https://pngquant.org/): Removes unnecessary data from PNG files while preserving full alpha transparency. - [**jpegoptim**](https://github.com/tjko/jpegoptim): Lossless optimization based on Huffman table optimization. - [**OptiPNG**](https://optipng.sourceforge.net/): A PNG optimizer used by several online compression tools. ## Examples Optimize and download an online JPEG image with `resmush_url()`: ``` r library(resmush) url <- "https://dieghernan.github.io/resmush/img/jpg_example_original.jpg" resmush_url(url, outfile = "jpg_example_compress.jpg", overwrite = TRUE) #> ══ resmush summary ═══════════════════════════════════════════════════════════════════════ #> ℹ Input: 1 URL, 178.7 Kb total. #> ✔ Optimized 1 URL: size is now 45 Kb (was 178.7 Kb). Saved 133.7 Kb (74.82%). #> Saved result in directory 'C:/user/john_doe/AppData/Local/Temp/'. ``` ::: {#fig-comp layout-ncol="2"} [![](https://dieghernan.github.io/resmush/img/jpg_example_original.jpg){#fig-orig alt="Original uncompressed JPEG image" width="100%"}](https://dieghernan.github.io/resmush/img/jpg_example_original.jpg) [![](https://dieghernan.github.io/resmush/reference/figures/jpg_example_compress.jpg){#fig-new alt="Optimized JPEG image" width="100%"}](https://dieghernan.github.io/resmush/reference/figures/jpg_example_compress.jpg) Original image @fig-orig: 178.7 KB, optimized image @fig-new: 45 KB (compression: 74.8%). Click to enlarge. ::: Use the `qlty` argument to adjust the JPEG quality level. For best results, use values above `90`. ``` r # Use a low JPEG quality level. resmush_url( url, outfile = tempfile(fileext = ".jpg"), overwrite = TRUE, qlty = 3 ) #> ══ resmush summary ═══════════════════════════════════════════════════════════════════════ #> ℹ Input: 1 URL, 178.7 Kb total. #> ✔ Optimized 1 URL: size is now 2.2 Kb (was 178.7 Kb). Saved 176.4 Kb (98.74%). #> Saved result in directory 'C:/user/john_doe/AppData/Local/Temp/'. ``` ::: {#fig-compresslow} [![](https://dieghernan.github.io/resmush/reference/figures/jpg_example_compress_low.jpg){alt="JPEG image with visible compression artifacts" width="100%"}](https://dieghernan.github.io/resmush/reference/figures/jpg_example_compress_low.jpg) Image with visible compression artifacts caused by high compression (`qlty = 3`), compared with @fig-new. ::: When results are available, all optimization functions invisibly return a data frame with one row per result and columns containing source and destination paths, formatted and raw file sizes, compression ratios and status notes. They return `NULL` otherwise. Successful API calls also write the optimized files to disk. The following example shows the result for a local image file: ``` r png_file <- system.file("extimg/example.png", package = "resmush") # Copy to a temporary file for this example. tmp_png <- tempfile(fileext = ".png") file.copy(png_file, tmp_png, overwrite = TRUE) #> [1] TRUE summary <- resmush_file(tmp_png, overwrite = TRUE) tibble::as_tibble(summary[, -c(1, 2)]) #> # A tibble: 1 × 6 #> src_size dest_size compress_ratio notes src_bytes dest_bytes #> #> 1 239.9 Kb 70.7 Kb 70.54% OK 245618 72356 ``` ## Alternatives Several other **R** packages provide image optimization tools: - The **xfun** package [@xfun] provides: - `xfun::tinify()`: Similar to `resmush_file()` but uses [**TinyPNG**](https://tinypng.com/) and requires an API key. - `xfun::optipng()`: Compresses local files using **OptiPNG**. The program must be installed locally. - The [**tinieR**](https://jmablog.github.io/tinieR/) package: An **R** interface to [**TinyPNG**](https://tinypng.com/). - The **tinyimg** package [@tinyimg]: Optimizes local PNG and JPEG files using Rust libraries. It supports lossless PNG optimization via **oxipng**, optional lossy PNG palette reduction and JPEG re-encoding via **mozjpeg**. - The [**optout**](https://github.com/coolbutuseless/optout) package: Similar to `xfun::optipng()` but with more options. It requires additional local software. ::: {#tbl-opts} | Tool | CRAN | Additional software | Online images | API key required | Limits | |----|----|----|----|----|----| | `xfun::tinify()` | Yes | No | Yes | Yes | 500 compressions per month (free tier) | | `xfun::optipng()` | Yes | Yes | No | No | None | | **tinieR** | No | No | Yes | Yes | 500 compressions per month (free tier) | | **tinyimg** | Yes | Yes (Rust toolchain) | No | No | None | | **optout** | No | Yes | No | No | None | | **resmush** | Yes | No | Yes | No | Personal use only. Files smaller than 5 MB. | **R** packages: comparison of image optimization alternatives. ::: ::: {#tbl-comp} | Tool | PNG | JPEG | GIF | BMP | TIFF | WebP | PDF | |-------------------|-----|------|-----|-----|------|------|-----| | `xfun::tinify()` | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | | `xfun::optipng()` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | **tinieR** | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | | **tinyimg** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | **optout** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | | **resmush** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | **R** packages: supported formats. ::: In practice, **resmush** is designed for quick image optimization with minimal setup, including support for online image files and formats such as GIF, BMP and TIFF. Packages such as **tinyimg** may be a better fit for fully local workflows focused on PNG and JPEG optimization and fine-grained control over compression settings. ## References