---
title: "Using resmush"
bibliography: REFERENCES.bib
link-citations: true
vignette: >
  %\VignetteIndexEntry{resmush}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
tbl-cap-location: bottom
---

<!-- resmush.qmd is generated from resmush.qmd.orig. Please edit that file -->



**resmush** is an **R** package for optimizing and compressing images with
[**reSmush.it**](https://resmush.it/). **reSmush.it** is a [free
API]{.underline} for image optimization and is available through
[WordPress](https://wordpress.org/plugins/resmushit-image-optimizer/) and
[many other tools](https://resmush.it/tools/).

**reSmush.it** includes:

- Free image optimization with [no API key required]{.underline}.
- Support for local and online images.
- Support for `png`, `jpg/jpeg`, `gif`, `bmp` and `tiff` files.
- Maximum image size: 5 MB.
- Compression powered by several algorithms:
  - [**PNGQuant**](https://pngquant.org/): Removes unnecessary chunks 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.

## Example

Compress an online `jpg` 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, total size 178.7 Kb.
#> ✔ Optimized 1 URL: Size is now 45 Kb (was 178.7 Kb). Saved 133.7 Kb (74.82%).
#> Saved result in directory '.'.
```

::: {#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 compression quality for `jpg` files. Keep
this value above 90 to maintain good image quality.


``` r
# Use an extreme compression setting.
resmush_url(
  url,
  outfile = tempfile(fileext = ".jpg"),
  overwrite = TRUE,
  qlty = 3
)
#> ══ resmush summary ═════════════════════════════════════════════════════════════
#> ℹ Input: 1 URL, total size 178.7 Kb.
#> ✔ Optimized 1 URL: Size is now 2.2 Kb (was 178.7 Kb). Saved 176.4 Kb (98.74%).
#> Saved result in directory 'tempdir()'.
```

::: {#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.
:::

All optimization functions invisibly return a data frame that summarizes the
process. The following example shows this output when compressing a local 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
#>   <chr>    <chr>     <chr>          <chr>     <dbl>      <dbl>
#> 1 239.9 Kb 70.7 Kb   70.54%         OK       245618      72356
```

## Alternatives

Several other **R** packages also provide image optimization tools:

- The **xfun** package [@xfun], which includes:
  - `xfun::tinify()`: Similar to `resmush_file()` but uses
    [**TinyPNG**](https://tinypng.com/) and requires an API key.
  - `xfun::optipng()`: Compresses local files using **OptiPNG**, which must be
    installed locally.
- The [**tinieR**](https://jmablog.github.io/tinieR/) package by jmablog: An
  **R** interface to [**TinyPNG**](https://tinypng.com/).
- The **tinyimg** package [@tinyimg]: Optimizes local `png` and `jpg/jpeg` files
  using Rust libraries.
- The [**optout**](https://github.com/coolbutuseless/optout) package by
  [\@coolbutuseless](https://coolbutuseless.github.io/): Similar to
  `xfun::optipng()` but with more options. Requires additional local software.

::: {#tbl-opts}
| Tool | CRAN | Additional software | Online images | API key required | Limits |
|--------------|--------------|--------------|--------------|--------------|--------------|
| `xfun::tinify()` | Yes | No | Yes | Yes | 500 files/month (free tier) |
| `xfun::optipng()` | Yes | Yes | No | No | No |
| **tinieR** | No | No | Yes | Yes | 500 files/month (free tier) |
| **tinyimg** | Yes | Yes | No | No | No |
| **optout** | No | Yes | No | No | No |
| **resmush** | Yes | No | Yes | No | Maximum size: 5 MB |

**R** packages: comparison of image optimization alternatives.
:::

::: {#tbl-comp}
| Tool              | png | jpg | gif | bmp | tiff | webp | pdf |
|-------------------|-----|-----|-----|-----|------|------|-----|
| `xfun::tinify()`  | ✅  | ✅  | ❌  | ❌  | ❌   | ✅   | ❌  |
| `xfun::optipng()` | ✅  | ❌  | ❌  | ❌  | ❌   | ❌   | ❌  |
| **tinieR**        | ✅  | ✅  | ❌  | ❌  | ❌   | ✅   | ❌  |
| **tinyimg**       | ✅  | ✅  | ❌  | ❌  | ❌   | ❌   | ❌  |
| **optout**        | ✅  | ✅  | ❌  | ❌  | ❌   | ❌   | ✅  |
| **resmush**       | ✅  | ✅  | ✅  | ✅  | ✅   | ❌   | ❌  |

**R** packages: supported formats.
:::

## References