---
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 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 per-file size limit: files must be smaller 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, and optimized image @fig-new, 45 KB
(74.8% compression). 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
#>   <chr>    <chr>     <chr>          <chr>     <dbl>      <dbl>
#> 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 provides 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 is similar
  to `xfun::optipng()` but offers 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. |

Comparison of image optimization alternatives for **R** packages.
:::

::: {#tbl-comp}
| Tool              | PNG | JPEG | GIF | BMP | TIFF | WebP | PDF |
|-------------------|-----|------|-----|-----|------|------|-----|
| `xfun::tinify()`  | ✅  | ✅   | ❌  | ❌  | ❌   | ✅   | ❌  |
| `xfun::optipng()` | ✅  | ❌   | ❌  | ❌  | ❌   | ❌   | ❌  |
| **tinieR**        | ✅  | ✅   | ❌  | ❌  | ❌   | ✅   | ❌  |
| **tinyimg**       | ✅  | ✅   | ❌  | ❌  | ❌   | ❌   | ❌  |
| **optout**        | ✅  | ✅   | ❌  | ❌  | ❌   | ❌   | ✅  |
| **resmush**       | ✅  | ✅   | ✅  | ✅  | ✅   | ❌   | ❌  |

Supported formats for **R** packages.
:::

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
