Jeroen Ooms

Last week, version 1.0 of the
[magick](https://cran.r-project.org/web/packages/magick/index.html)
package appeared on CRAN: an ambitious effort to modernize and simplify
high quality image processing in R. This R package builds upon the
[Magick++ STL](https://www.imagemagick.org/Magick++/STL.html) which
exposes a powerful C++ API to the famous ImageMagick library.

![RStudio Screenshot](https://jeroen.github.io/images/magick.png)

The best place to start learning about magick is the
[vignette](https://cran.r-project.org/web/packages/magick/vignettes/intro.html)
which gives a brief overview of the overwhelming amount of functionality
in this package.

### Towards Release 1.0

Last year around this time rOpenSci
[announced](/blog/2016/08/23/z-magick-release) the first release of the
magick package: a new powerful toolkit for image reading, writing,
converting, editing, transformation, annotation, and animation in R.
Since the initial release there have been several updates with
additional functionality, and many useRs have started to discover the
power of this package to take visualization in R to the next level.

For example [Bob
Rudis](https://twitter.com/hrbrmstr/status/758304420224466944) uses
magick to visualize California drought data from the U.S. Drought
Monitor (click on the image to go find out more):

[![drought](https://jeroen.github.io/images/drought.gif)](https://rud.is/b/2016/07/27/u-s-drought-animations-with-the-witchs-brew-purrr-broom-magick/)

R-ladies [Lucy D'Agostino McGowan](https://www.lucymcgowan.com/) and
[Maëlle Salmon](https://masalmon.eu/) demonstrate how to make a
beautiful collage:

[![collage](https://livefreeordichotomize.com/images/we-r-ladies.jpeg)](https://livefreeordichotomize.com/2017/07/18/the-making-of-we-r-ladies/)

And [Daniel P.
Hadley](https://twitter.com/danielphadley/status/884845188979359744)
lets Vincent Vega explains Cars:

[![travolta](https://danielphadley.com/images/Cars_Travolta.gif)](https://danielphadley.com/ggplot-Logo/)

Now, 1 year later, the 1.0 release marks an important milestone: the
addition of a new native graphics device (which serves as a hybrid
between a magick image object and an R plot) bridges the gap between
graphics and image processing in R.

This blog post explains how the magick device allows you to seamlessly
combine graphing with image processing in R. You can either use it to
post-process your R graphics, or draw on imported images using the
native R plotting machinery. We hope that this unified interface will
make it easier to produce beautiful, reproducible images with R.

### Native Magick Graphics

The `image_graph()` function opens a new graphics device similar to e.g.
`png()` or `x11()`. It returns an image object to which the plot(s) will
be written. Each page in the plotting device will become a frame (layer)
in the image object.

::: {.highlight}
``` {.chroma tabindex="0"}
# Produce image using graphics devicefig <- image_graph(res = 96)ggplot2::qplot(mpg, wt, data = mtcars, colour = cyl)dev.off()
```
:::

The `fig` object now contains the image that we can easily post-process.
For example we can overlay another image:

::: {.highlight}
``` {.chroma tabindex="0"}
logo <- image_read("https://www.r-project.org/logo/Rlogo.png")out <- image_composite(fig, image_scale(logo, "x150"), offset = "+80+380")# Show previewimage_browse(out)# Write to fileimage_write(out, "myplot.png")
```
:::

![out](/assets/blog-images/2017-08-15-magick-10/out.png)

### Drawing Device

The `image_draw()` function opens a graphics device to draw on top of an
existing image using pixel coordinates.

::: {.highlight}
``` {.chroma tabindex="0"}
# Open a filelibrary(magick)frink <- image_read("https://jeroen.github.io/images/frink.png")drawing <- image_draw(frink)
```
:::

![frink](https://jeroen.github.io/images/frink.png)

We can now use R's native low-level graphics functions for drawing on
top of the image:

::: {.highlight}
``` {.chroma tabindex="0"}
rect(20, 20, 200, 100, border = "red", lty = "dashed", lwd = 5)abline(h = 300, col = 'blue', lwd = '10', lty = "dotted")text(10, 250, "Hoiven-Glaven", family = "courier", cex = 4, srt = 90)palette(rainbow(11, end = 0.9))symbols(rep(200, 11), seq(0, 400, 40), circles = runif(11, 5, 35),  bg = 1:11, inches = FALSE, add = TRUE)
```
:::

At any point you can inspect the current result:

``` {tabindex="0"}
image_browse(drawing)
```

![drawing](/assets/blog-images/2017-08-15-magick-10/drawing.png)

Once you are done you can close the device and save the result.

::: {.highlight}
``` {.chroma tabindex="0"}
dev.off()image_write(drawing, 'drawing.png')
```
:::

By default `image_draw()` sets all margins to 0 and uses graphics
coordinates to match image size in pixels (width x height) where (0,0)
is the top left corner. Note that this means the y axis increases from
top to bottom which is the opposite of typical graphics coordinates. You
can override all this by passing custom `xlim`, `ylim` or `mar` values
to `image_draw()`.

### Animated Graphics

The graphics device supports multiple frames which makes it easy to
create animated graphics. The example below shows how you would
implement the example from the very cool
[gganimate](https://github.com/dgrtwo/gganimate) package using the
magick.

::: {.highlight}
``` {.chroma tabindex="0"}
library(gapminder)library(ggplot2)library(magick)img <- image_graph(res = 96)datalist <- split(gapminder, gapminder$year)out <- lapply(datalist, function(data){  p <- ggplot(data, aes(gdpPercap, lifeExp, size = pop, color = continent)) +    scale_size("population", limits = range(gapminder$pop)) +    scale_x_log10(limits = range(gapminder$gdpPercap)) +    geom_point() + ylim(20, 90) +  ggtitle(data$year) + theme_classic()  print(p)})dev.off()animation <- image_animate(img, fps = 2)image_write(animation, "animation.gif")
```
:::

![animation](/assets/blog-images/2017-08-15-magick-10/animation.gif)

We hope that the magick package can provide a more robust back-end for
packages like gganimate to produce interactive graphics in R without
requiring the user to manually install external image editing software.

### Porting ImageMagick Commands to R

The magick 1.0 release now has the core image processing functionality
that you expect from an image processing package. But there is still a
lot of room for improvement to make magick *the* image processing
package in R.

A lot of R users and packages currently shell out to ImageMagick command
line tools for performing image manipulations. The goal is to support
all these operations in the magick package, so that the images can be
produced (and reproduced!) on any platform without requiring the user to
install additional software.

Note that ImageMagick library is over 26 years old and has accumulated
an enormous number of features in those years. Porting all of this to R
is quite a bit of work, for which feedback from users is important. If
there is an imagemagick operation that you like to do in R but you can't
figure out how, please [open an
issue](https://github.com/ropensci/magick/issues) on GitHub. If the
functionality is currently not supported yet, we will try to add it to
the next version.

### Image Analysis

Currently magick is focused on generating and editing images. There is
yet another entirely different set of features which we like to support
related to analyzing images. Image analysis can involve anything from
calculating color distributions to more sophisticated feature extraction
and vision tools. I am not very familiar with this field, so again we
could use suggestions from users and experts.

One feature that is already available is the `image_ocr()` function
which extracts text from the image using the rOpenSci
[tesseract](/blog/2016/11/16/tesseract) package. Another cool example of
using image analysis is the
[collage](https://github.com/ThinkRstat/collage) package which
calculates [color
histograms](https://github.com/ThinkRstat/collage#histograms) to select
appropriate tile images for creating a collage.

[![histogram](https://github.com/ThinkRstat/collage/raw/master/README-histograms-2.png)](https://github.com/ThinkRstat/collage#histograms)

As part of supporting supporting analysis tools we plan to extract the
bitmap (raster) classes into a separate package. This will enable
package authors to write R extensions to analyze and manipulate on the
raw image data, without necessarily depending on magick. Yet the user
can always rely on magick as a powerful toolkit to import/export images
and graphics into such low level bitmaps.

> The greatest achievement of my PhD so far: discovering the \'magick\'
> R package and adding gifs to my plots (thanks
> [@danielphadley](https://twitter.com/danielphadley?ref_src=twsrc%5Etfw)!)
> [\#rstats](https://twitter.com/hashtag/rstats?src=hash&ref_src=twsrc%5Etfw)
> [pic.twitter.com/gCEfKyWa9x](https://t.co/gCEfKyWa9x)
>
> --- George Bailey (@grbails) [July 13,
> 2017](https://twitter.com/grbails/status/885543687559811073?ref_src=twsrc%5Etfw)


Last week, version 1.0 of the magick package appeared on CRAN: an ambitious effort to modernize and simplify high quality image processing in R. This R package builds upon the Magick++ STL which exposes a powerful C++ API to the famous ImageMagick library.

Magick 1.0: 🎩 ✨🐇 Advanced Graphics and Image Processing in R

A new version of the ropensci
[magick](https://cran.r-project.org/package=magick) package has been
released to CRAN. Magick is a package for Advanced Image-Processing in
R. It wraps the ImageMagick STL which is perhaps the most comprehensive
open-source image processing library available today. Our [original
announcement](/blog/2016/08/23/z-magick-release) has more details.

## New features

This new version now includes a beautiful
[vignette](https://cloud.r-project.org/web/packages/magick/vignettes/intro.html)
which gives an overview of the main functionality to get you started! It
lists the various formats, transformations, effects, operations and much
more.

[![RStudio
Screenshot](/assets/blog-images/magick-vignette.png)](https://cloud.r-project.org/web/packages/magick/vignettes/intro.html)

The vignette also explains how to use magick with [raster
graphics](https://cloud.r-project.org/web/packages/magick/vignettes/intro.html#raster_graphics).
This new functionality makes it possible to overlay images on R's
graphics device.

## Installing and Updating

The package is most easily installed from CRAN:

::: {.highlight}
``` {.chroma tabindex="0"}
install.packages("magick")
```
:::

When installing from source make sure the Magick++ library is available
on your system.


A new version of the ropensci magick package has been released to CRAN. Magick is a package for Advanced Image-Processing in R. It wraps the ImageMagick STL which is perhaps the most comprehensive open-source image processing library available today. Our original announcement has more details.New features  This new version now includes a beautiful vignette which gives an overview of the main functionality to get you started!

New in Magick 0.3

The new
[magick](https://cran.r-project.org/web/packages/magick/index.html)
package is an ambitious effort to modernize and simplify high-quality
image processing in R. It wraps the [ImageMagick
STL](https://www.imagemagick.org/Magick++/STL.html) which is perhaps the
most comprehensive open-source image processing library available today.

The ImageMagick library has an overwhelming amount of functionality. The
current version of Magick exposes a decent chunk of it, but being a
first release, documentation is still sparse. This post briefly
introduces the most important concepts to get started. There will also
be an [rOpenSci community
call](https://ropensci.org/commcalls/2016-08-24/) on Wednesday in which
we demonstrate basic functionality.

## Installation

On Windows or OS-X the package is most easily installed via CRAN.

::: {.highlight}
``` {.chroma tabindex="0"}
install.packages("magick")
```
:::

On Linux you need to install the ImageMagick++ library: on Debian/Ubuntu
this is called
[libmagick++-dev](https://packages.debian.org/testing/libmagick++-dev):

``` {tabindex="0"}
sudo apt-get install libmagick++-dev
```

On Fedora or CentOS/RHEL we need
[ImageMagick-c++-devel](https://apps.fedoraproject.org/packages/ImageMagick-c++-devel):

``` {tabindex="0"}
sudo yum install ImageMagick-c++-devel
```

To install from source on OS-X you need `imagemagick` from homebrew.

``` {tabindex="0"}
brew install imagemagick --with-fontconfig --with-librsvg --with-fftw
```

The default imagemagick configuration on homebrew disables a bunch of
features. I recommend you install `--with-fontconfig` and
`--with-librsvg` to get high quality font / svg rendering (the CRAN OSX
binary package enables these as well).

::: {.highlight}
``` {.chroma tabindex="0"}
library(magick)magick_config()
```
:::

Use `magick_config` to see which features and formats are supported by
your version of ImageMagick.

## Reading and writing

Images can be read directly from a file path, URL, or raw vector with
image data. Similarly we can write images back to disk, or in memory by
setting `path=NULL`.

``` {tabindex="0"}
# Render svg to pngtiger <- image_read('https://upload.wikimedia.org/wikipedia/commons/f/fd/Ghostscript_Tiger.svg')image_write(tiger, path = "tiger.png", format = "png")
```

IDE's with a built-in web browser (such as RStudio) automatically
display magick images in the viewer. This results in a neat interactive
image editing environment.

![RStudio Screenshot](/assets/blog-images/magick-rstudio.png)

Alternatively, on Linux you can use `image_display` to preview the image
in an X11 window. Finally `image_browse` opens the image in your
system's default application for a given type.

::: {.highlight}
``` {.chroma tabindex="0"}
# X11 onlyimage_display(tiger)# System dependentimage_browse(tiger)
```
:::

There is some functionality to convert images to R raster graphics and
plot it on R's graphics display, but this doesn't always work too well
yet.

::: {.highlight}
``` {.chroma tabindex="0"}
frink <- image_read("https://jeroen.github.io/images/frink.png")raster <- as.raster(frink)plot(raster)
```
:::

Also the R graphics device is relatively slow for displaying bitmap
images.

## Transformations and effects

The best way to get a sense of available transformations is walk through
the examples in the `?transformations` help page in RStudio. Below a few
examples to get a sense of what is possible.

::: {.highlight}
``` {.chroma tabindex="0"}
# Example imagefrink <- image_read("https://jeroen.github.io/images/frink.png")# Trim marginsimage_trim(frink)# Passport picaimage_crop(frink, "100x150+50")# Resizeimage_scale(frink, "200x") # width: 200pximage_scale(frink, "x200") # height: 200px# Rotate or mirrorimage_rotate(frink, 45)image_flip(frink)image_flop(frink)# Set a background colorimage_background(frink, "pink", flatten = TRUE)# World-cup outfit (Flood fill)image_fill(frink, "orange", "+100+200", 30000)
```
:::

ImageMagick also has a bunch of standard effects that are worth checking
out.

::: {.highlight}
``` {.chroma tabindex="0"}
# Add randomnessimage_blur(frink, 10, 5)image_noise(frink)# Silly filtersimage_charcoal(frink)image_oilpaint(frink)image_emboss(frink)image_edge(frink)image_negate(frink)
```
:::

Finally it can be useful to print some text on top of images:

::: {.highlight}
``` {.chroma tabindex="0"}
# Add some textimage_annotate(frink, "I like R!", size = 50)# Customize textimage_annotate(frink, "CONFIDENTIAL", size = 30, color = "red", boxcolor = "pink",  degrees = 60, location = "+50+100")# Only works if ImageMagick has fontconfigimage_annotate(frink, "The quick brown fox", font = 'times-new-roman', size = 30)
```
:::

Maybe this is enough to get started.

## Layers and animation

The examples above concern single images. However all functions in
magick have been vectorized to support working with layers, compositions
or animation.

The standard base vector methods `[` `[[`, `$`, `c()` and `length()` are
used to manipulate sets of images which can then be treated as layers or
frames. This system is actually so extensive that we will do a separate
blog post about it later.

For now here is an example on how to generate the instant classic
dancing banana on R logo (which is probably why you are here):

::: {.highlight}
``` {.chroma tabindex="0"}
# Background imagelogo <- image_read("https://www.r-project.org/logo/Rlogo.png")background <- image_scale(logo, "400")# Foreground imagebanana <- image_read(system.file("banana.gif", package = "magick"))front <- image_scale(banana, "300")# Combine and flatten framesframes <- lapply(as.list(front), function(x) image_flatten(c(background, x)))# Turn frames into animationanimation <- image_animate(image_join(frames))print(animation)# Save as GIFimage_write(animation, "Rlogo-banana.gif")
```
:::

If time permits we will demonstrate more examples during our [community
call](https://ropensci.org/commcalls/2016-08-24/) on Wednesday!


The new magick package is an ambitious effort to modernize and simplify high-quality image processing in R. It wraps the ImageMagick STL which is perhaps the most comprehensive open-source image processing library available today. The ImageMagick library has an overwhelming amount of functionality. The current version of Magick exposes a decent chunk of it, but being a first release, documentation is still sparse.

Rogue Scholar Beiträge

Magick 1.0: 🎩 ✨🐇 Advanced Graphics and Image Processing in R

New in Magick 0.3

Advanced Image-Processing in R with Magick, Part I