brickr is a package for bringing the LEGO® experience into the R and tidyverse ecosystem.

The package is divided into 3 separate systems:

  • Mosaics: Convert image files into mosaics that could be built using LEGO® bricks.
  • 3D Models: Build 3D LEGO® models from data tables using rgl.
  • Charts: A ggplot2 extension to generate plots that resemble LEGO® bricks.

brickr also includes tools help users create the Mosaics and 3D model output using real LEGO® elements.

Check out for more detail!

What’s the point?

The goal of brickr is to provide a series of tools to integrate the LEGO® system with R by:

  • Enhancing a real world building experience with mosaics, generated instructions, and piece counts.
  • Generating interest in R and coding for new audiences with easy-to-create 3D models.
  • or just embracing pure novelty.

brickr is developed under the Fair Play policy using publicly available information about LEGO® products. brickr is not affiliated with The LEGO Group.


The mosaic functions renders an imported JPG or PNG file using LEGO colors and bricks.

demo_img = tempfile() 
download.file("", demo_img, mode="wb")

mosaic1 <- png::readPNG(demo_img) %>% 
  image_to_mosaic(img_size = 36) #Length of each side of mosaic in "bricks"

#Plot 2D mosaic
mosaic1 %>% build_mosaic()

In general, any brickr function that begins with build_ generates a graphical output from a brickr list object, generated from other functions.


image_to_mosaic() can take a few important arguments. See ?image_to_mosaic() for full detail.

  • img_size Providing a single value, such as 48, crops the image to a square. Inputting a 2-element array, c(56, 48), will output a rectangular image of c(width, height).

  • color_table & color_palette Options to limit the color of bricks used in mosaics, as not all colors produced by LEGO are readily available. Set color_palette to ‘universal’ or c('universal', 'generic') to limit colors to the most common ones. Use a subset of the data frame lego_colors as the color_table to specify a custom palette.

  • method Technique used to map image colors into the allowed brick colors. Defaults to ‘cie94`, but other options include ’cie2000’ and ‘euclidean’. Also includes the option ‘brickr_classic’, used in previous version of the package.

3D Models

The bricks_from_* series of functions creates 3D models of LEGO bricks from a variety of input formats.

Pass the output from any bricks_from_*() function to build_bricks() to see the 3D model. Models are currently rendered in rgl. Previous versions of brickr use Tyler Morgan-Wall’s rayshader package. This option is still available by passing the output from any bricks_from_*() function to build_bricks_rayshader(). Rayshader can still be used for saving snapshots and creating animations.


#This is a brick
brick <- data.frame(
  X1 = rep(3,4), #The number 3 is the brickrID for 'bright red'
  X2 = rep(3,4)

brick %>% 
  bricks_from_table() %>% 

#Rotate the default view for a better snapshot
rgl::par3d(userMatrix = rgl::rotate3d(rgl::par3d("userMatrix"), 0.75*pi, 0, 0 ,1))

Programmatically build models

Use bricks_from_coords() to programmatically build 3D LEGO models instead of manually drawing them in a spreadsheet or table. Here you must provide whole number coordinates for x, y, and z, along with an official LEGO color name for each point.

The option outline_bricks = TRUE adds a black outline around the edges of the bricks. Setting rgl_lit = FALSE turns off automated lighting effects from rgl. Changing these two inputs together renders bricks in a more cartoon fashion.


More examples using bricks_from_table() and bricks_from_coords() can be found at the links below.


brickr includes functions to render ggplot2 bar charts as bricks with LEGO color themes. The main function is geom_brick_col(), which is the brickr equivalent of geom_col(). Additional functions are highly recommended to ensure that proper the chart is rendered in the proper functions and proportions.

Both scale_fill_brick() and theme_brick() take an input ‘brick_theme’, which ensures all colors match official LEGO brick colors. See build_themes() for a sample of all available brick theme.

df <- data.frame(trt = letters[1:6], outcome = rnorm(6, mean = 5, sd = 2))

use_theme <- "hp"

ggplot(df, aes(trt, outcome)) +
  geom_brick_col(aes(fill = trt), two_knob = F) +
  scale_fill_brick(use_theme) +
  coord_brick_flip() +
  theme_brick(use_theme) +
  theme(legend.position = "none")


Additional functions assist in the translation of brickr objects into actual LEGO bricks.


Use build_instructions() to break the mosaics and 3D models into easier-to-read steps for building the set. This defaults to 6 steps, but passing any integer value will generate that many steps.

Piece list and count

Use build_pieces() to generate a graphic and count of all required plates or bricks (for stacked mosaics). These are sorted by color and size for easy purchase on’s Pick-a-Brick section using the advanced search option. Alternatively, use table_pieces() to produce a data frame table of all required bricks.