Bricks from table vignette and other updates

2026-01-07 06:10:56 -06:00 · 2019-08-11 12:03:41 -04:00
parent 81bb136b76
commit 0806223993
6 changed files with 180 additions and 23 deletions
--- a/2
+++ b/2
@@ -1,6 +1,6 @@
 Package: brickr
 Title: Tools to emulate the LEGO&reg; System in R
-Version: 0.1.0.9011
+Version: 0.1.0.9012
 Authors@R: 
    person(given = "Ryan",
           family = "Timpe",
--- a/NEWS.md
+++ b/NEWS.md
@@ -4,11 +4,12 @@

 * **Breaking:** Data "lego_colors.rda" has been updated with more accurate RGB values and new `brickrID` numbers. This will impact previously created mosaics and 3D models.

-## Documentations
+## Documentation

 * pkgdown site
 * Vignettes:
    - Mosaics
+    - ggplot extension

 ## Mosaics

@@ -42,7 +43,6 @@
    - 3D models from tables
    - 3D models from coords
    - 3D modesl from mosaics + rayshader
-    - ggplot
    - IRL
 * Website
 * Check() breaks at the size check
--- a/README.Rmd
+++ b/README.Rmd
@@ -18,7 +18,7 @@ library(tidyverse)

 # brickr <img src='man/figures/logo.png' align="right" height="138" />
 <!--   <!-- badges: start -->
-  [![Lifecycle: maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://www.tidyverse.org/lifecycle/#maturing)
+  [![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)
 <!--   <!-- badges: end -->

 ## Overview
@@ -32,6 +32,14 @@ The package is divided into 3 separate systems:
  
 brickr also includes tools help users create the Mosaics and 3D model output using real LEGO&reg; elements.

+### What's the point?
+
+The goal of {brickr} is to provide a series of tools to integrate the LEGO&reg; 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 using publicly available information about LEGO&reg; products and is not officially affiliated with The LEGO Group*

 ## Installation
@@ -94,10 +102,7 @@ brick %>%
  bricks_from_table() %>% 
  build_bricks(brick_res = "uhd")

-rayshader::render_snapshot()
-```
-```{r, echo=FALSE}
- rgl::rgl.clear()
+rayshader::render_snapshot( clear = TRUE)
 ```

 ### Stacking bricks
@@ -141,10 +146,7 @@ my_first_model %>%
  bricks_from_table(brick_colors) %>% 
  build_bricks(theta = 210, brick_res = "hd")

-rayshader::render_snapshot()
-```
-```{r, echo=FALSE}
- rgl::rgl.clear()
+rayshader::render_snapshot(clear = TRUE)
 ```

 ### Programmatically build models
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ The LEGO® System in R
 <!--   <!-- badges: start -->

 [![Lifecycle:
-maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://www.tidyverse.org/lifecycle/#maturing)
+experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)
 <!--   <!-- badges: end -->

 ## Overview
@@ -26,8 +26,19 @@ The package is divided into 3 separate systems:
 brickr also includes tools help users create the Mosaics and 3D model
 output using real LEGO® elements.

+### 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 using publicly available information about LEGO®
-products and is not officially affliated with The LEGO Group*
+products and is not officially affiliated with The LEGO Group*

 ## Installation

@@ -100,11 +111,12 @@ Morgan-Wall](https://twitter.com/tylermorganwall)’s
    integer values, and `Color` columns, where each combination of x, y,
    & z is a point in 3-dimensional space. Color must be an official
    LEGO color name from `build_colors()`. This format is much more
-    flexible than `bricks_from_table()` and allows the programatic
+    flexible than `bricks_from_table()` and allows the programmatic
    development of 3D models.

-\-`bricks_from_mosaic()` & `bricks_from_image()` convert a 2D
-[mosaic](#mosaics) object or an image into 3D LEGO models, respectively.
+\-`bricks_from_mosaic()` converts a 2D [mosaic](#mosaics) object from an
+image into 3D LEGO models, respectively. `bricks_from_rayshader()`
+creates a LEGO model from the same input as `rayshader::plot_3d()`.

 Pass the output from any `bricks_from_*()` function to `build_bricks()`
 to see the 3D model. The `brick_res` option allows for higher resolution
@@ -230,11 +242,12 @@ be found at the links below.

 ## Charts

-brickr includes some elements for a [ggplot2]() extensions to convert
-ggplot bar charts into bricks and LEGO 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.
+brickr includes functions to render
+[ggplot2](https://ggplot2.tidyverse.org/) 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.

 ``` r
 df <- data.frame(trt = c("a", "b", "c"), outcome = c(2.3, 1.9, 3.2))
@@ -250,7 +263,7 @@ ggplot(df, aes(trt, outcome)) +
 ![](README_files/figure-gfm/geom_brick-1.png)<!-- -->

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

--- a/README_files/figure-gfm/geom_brick2-1.png
+++ b/README_files/figure-gfm/geom_brick2-1.png
--- a/vignettes/models-from-tables.Rmd
+++ b/vignettes/models-from-tables.Rmd
@@ -0,0 +1,142 @@
+---
+title: "3D models from tables"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{graphs}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+  
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+collapse = TRUE,
+comment = "#>"
+)
+```
+
+```{r setup, include = FALSE}
+library(brickr)
+```
+
+## Getting started
+
+The `bricks_from_*` series of functions creates 3D models of LEGO bricks from a variety of input formats. These models are rendered using [Tyler Morgan-Wall](https://twitter.com/tylermorganwall)'s [rayshader](https://www.rayshader.com/) package. This package must be installed.
+
+`bricks_from_table()` converts a matrix-shaped table of integers into LEGO bricks, where most columns are x-coordinates, rows are y-coordinates, and a special `Level` column denotes the elevation of the row. For simple models, this table can be made manually using `data.frame()` or `tibble::tribble()`. 
+
+For more advanced models, it's recommended you use MS Excel or a .csv file. `bricks_from_excel()` is a wrapper function to more easily build models designed using a Microsoft Excel template. Please see this repo: [brickr toybox](https://github.com/ryantimpe/brickr_toybox).
+
+Pass the output of any `bricks_from_*()` function to `build_bricks()` to render it as a 3D model.
+
+## Individual bricks
+
+Create a single 2x4 brick with a 2x4 data frame, with an additional column to specify the 'Level'. These can be letters or numbers.
+
+```{r bricks_1, echo=TRUE, warning=FALSE, message=FALSE, fig.width=3, fig.height=3}
+#This is a 2 (columns) x 4 (rows) brick
+(brick <- data.frame(
+  Level="A",
+  X1 = rep(3,4), #The number 3 is the brickrID for 'bright red'
+  X2 = rep(3,4)
+))
+
+brick %>% 
+  bricks_from_table() %>% 
+  build_bricks(brick_res = "hd") #Bricks available in standard def, high def, and ultra hd. 
+
+rayshader::render_snapshot( clear = TRUE)
+```
+
+Stack many bricks by changing the 'Level' value in the data frame. The script below uses `purrr::map_df()` to avoid copying and pasting. Changing the numeric values inside the data frame for each level creates different colors.
+
+```{r bricks_2, echo=TRUE, warning=FALSE, message=FALSE, fig.width=3, fig.height=3}
+1:10 %>% 
+  purrr::map_df(~dplyr::mutate(brick,
+                        Level = LETTERS[.x], 
+                        X1 = .x,
+                        X2 = .x)) %>% 
+  bricks_from_table() %>% 
+  build_bricks(brick_res = "hd")
+
+rayshader::render_snapshot( clear = TRUE)
+```
+
+## Full models
+
+The most direct way to create a 3D model is to manually create a data frame. Below, we create a data frame using `tibble::tribble()` so we can more easily see the structure as it's written.
+
+The data frame has 3 numbers as input (values of 0 are void spaces in the model). Rather than use the default brickr colors for the values of 1, 2, and 3, we define another data frame 'brick_colors' 
+
+```{r bricks_5, echo=TRUE, warning=FALSE, message=FALSE, fig.width=4, fig.height=4}
+tree_or_mushroom <- tibble::tribble(
+  ~Level, ~X1, ~X2, ~X3, ~X4, ~X5, ~X6,
+  "A", 1, 1, 1, 1, 1, 1, 
+  "A", 1, 1, 1, 1, 1, 1, 
+  "A", 1, 1, 1, 1, 1, 1, 
+  "A", 1, 1, 1, 1, 1, 1, 
+  "B", 0, 0, 0, 0, 0, 0, 
+  "B", 0, 0, 2, 2, 0, 0,
+  "B", 0, 0, 2, 2, 0, 0, 
+  "B", 0, 0, 0, 0, 0, 0, 
+  "C", 0, 0, 0, 0, 0, 0, 
+  "C", 0, 0, 2, 2, 0, 0,
+  "C", 0, 0, 2, 2, 0, 0, 
+  "C", 0, 0, 0, 0, 0, 0, 
+  "D", 0, 3, 3, 3, 3, 0, 
+  "D", 0, 3, 3, 3, 3, 0,
+  "D", 0, 3, 3, 3, 3, 0, 
+  "D", 0, 3, 3, 3, 3, 0,
+  "E", 0, 0, 3, 3, 0, 0, 
+  "E", 0, 3, 3, 3, 3, 0,
+  "E", 0, 3, 3, 3, 3, 0, 
+  "E", 0, 0, 3, 3, 0, 0,
+  "F", 0, 0, 0, 0, 0, 0, 
+  "F", 0, 0, 3, 3, 0, 0,
+  "F", 0, 0, 3, 3, 0, 0, 
+  "F", 0, 0, 0, 0, 0, 0,
+  "G", 0, 0, 0, 0, 0, 0, 
+  "G", 0, 0, 3, 0, 0, 0,
+  "G", 0, 0, 0, 3, 0, 0, 
+  "G", 0, 0, 0, 0, 0, 0
+)
+
+brick_colors <- tibble::tribble(
+  ~`.value`, ~Color,
+  1, "Bright green",
+  2, "Dark orange",
+  3, "Dark green"
+)
+  
+tree_or_mushroom %>% 
+  bricks_from_table(brick_colors) %>% 
+  build_bricks(theta = 210, phi = 20, brick_res = "hd")
+
+rayshader::render_snapshot(clear = TRUE)
+```
+
+### Plates instead of bricks
+
+That's clearly a tree, right? Why is the data frame called 'tree_or_mushroom'?
+
+Use the input 'brick_type="plate"' to render the 3D model using LEGO plates rather than bricks, which are 1/3 as tall.
+
+```{r bricks_5a, echo=TRUE, warning=FALSE, message=FALSE, fig.width=4, fig.height=4}
+brick_colors <- tibble::tribble(
+  ~`.value`, ~Color,
+  1, "Dark green",
+  2, "Light nougat",
+  3, "Bright red"
+)
+  
+tree_or_mushroom %>% 
+  bricks_from_table(brick_colors) %>% 
+  build_bricks(theta = 210, phi = 10, brick_res = "hd", brick_type="plate")
+
+rayshader::render_snapshot(clear = TRUE)
+```
+
+## Bricks from Excel
+
+When designing larger models, it is much easier to use a spreadsheet program to lay out the bricks for each level.  
+
+See [the brickr toybox](https://github.com/ryantimpe/brickr_toybox) GitHub repo for some examples and templates.