-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathREADME.Rmd
135 lines (93 loc) · 5.63 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
---
title: "LEGO Mosaics in R"
output:
github_document:
fig_width: 7.5
fig_height: 6
html_preview: false
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
rgl::setupKnitr()
library(brickr)
library(jpeg)
library(tidyverse)
```
# brickr Toy Box <img src='man/figures/logo.png' align="right" height="138" />
<!-- <!-- badges: start -->
[](https://CRAN.R-project.org/package=brickr)
[](https://cran.r-project.org/package=brickr)
[](https://www.tidyverse.org/lifecycle/#experimental)
[](https://travis-ci.org/ryantimpe/brickr)
<!-- <!-- badges: end -->
## Overview
**brickr** is a package for bringing the LEGO® experience into the R and [tidyverse](https://www.tidyverse.org/) ecosystem.
The package is divided into 2 systems:
- [**Mosaics**](#mosaics): Convert image files into mosaics that could be built using LEGO bricks.
- [**3D Models**](#3d-models): Build 3D LEGO models from data tables using [rgl](https://CRAN.R-project.org/package=rgl).
brickr also includes tools help users create the Mosaics and 3D model output using real LEGO elements.
Check out [brickr.org](http://brickr.org) 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.
- Embracing pure novelty.
*brickr is developed under the [Fair Play](https://www.lego.com/en-us/legal/notices-and-policies/fair-play/) policy using publicly available information about LEGO products. brickr is not affiliated with The LEGO Group.*
## Installation
``` r
# Install from CRAN
install.packages("brickr")
# To install the latest development version from Github:
# install.packages("remotes")
remotes::install_github("ryantimpe/brickr")
```
## Starter Kit
<img src='man/figures/StarterKit.JPG' align="center" height="400" />
The Excel file "brickr_StartKit.xlsx" provides templates, as well as a How-To manual and examples, for laying out models in Excel and then rendering them as 3D models in R using brickr.
- Lay out a model and the color key in Excel using one of the template or examples provided in the file.
- Import the Excel sheet into R as a data frame using [Jenny Bryan](https://twitter.com/JennyBryan)'s [readxl](https://readxl.tidyverse.org/) package.
- Convert this data frame into a brickr object using `bricks_from_excel()`.
```{r penguin_fake, echo=FALSE, fig.height=0.1, fig.width=5, message=FALSE, warning=FALSE, dev='png', rgl=TRUE}
#FOR SOME REASON THE FIRST RGL IMAGE DOESNT SHOW UP
# SO HERES A FAKE ONE
penguin <- readxl::read_xlsx("brickr_StarterKit.xlsx", sheet = "Penguin")
penguin %>%
bricks_from_excel() %>%
build_bricks()
#Rotate the default view for a better snapshot
rgl::par3d(userMatrix = rgl::rotate3d(rgl::par3d("userMatrix"), 0.9*pi, 0, 0 ,1),
zoom = 0.7)
```
```{r penguin, rgl=TRUE, dev='png', echo=TRUE, warning=FALSE, message=FALSE, fig.width=5, fig.height=5}
penguin <- readxl::read_xlsx("brickr_StarterKit.xlsx", sheet = "Penguin")
penguin %>%
bricks_from_excel() %>%
build_bricks(background_color = "#99e7ff")
#Rotate the default view for a better snapshot
rgl::par3d(userMatrix = rgl::rotate3d(rgl::par3d("userMatrix"), 0.9*pi, 0, 0 ,1),
zoom = 0.7)
```
## Advanced models
The penguin model is made completely of standard LEGO bricks placed at regularly heights. Once comfortable with building these simple models, you can build more advanced models with two additional features.
- Include a 2nd table in the `piece_table` argument to tell R to render certain bricks as different shapes. See [this vignette](http://brickr.org/articles/models-piece-type.html) for more information about shapes.
- Add a `mid_level` column to the right of `Level` in the Excel tables to place bricks in between levels. Without this, all bricks are placed on mid_level = 0, which is the bottom of the Level. Use mid_level=1 for the middle of the Level, and mid_level = 2 for the top. This is valuable when using other piece shapes, such as plate, which are 1/3 as tall as a brick.
```{r castle, rgl=TRUE, dev='png', echo=TRUE, warning=FALSE, message=FALSE, fig.width=5, fig.height=5}
sandcastle_colors <- readxl::read_xlsx("brickr_StarterKit.xlsx",
sheet = "SandCastle_colors")
sandcastle_bricks <- readxl::read_xlsx("brickr_StarterKit.xlsx",
sheet = "SandCastle_bricks")
sandcastle_colors %>%
bricks_from_excel(
piece_table = sandcastle_bricks,
) %>%
build_bricks(background_color = "#fd5e53")
#Rotate the default view for a better snapshot
rgl::par3d(userMatrix = rgl::rotate3d(rgl::par3d("userMatrix"), 0.1, 0, 0 ,1),
zoom = 0.7)
```
## Contribute
Please feel free to contribute your own examples into any of the "Examples_" folders by submitting a pull request!
## Other Examples
More examples using `bricks_from_table()` and `bricks_from_coords()` can be found at the links below.
- [**Baby Yoda**](https://gist.github.com/ryantimpe/3893fdd0f94138d027bae35bf38b57c7) example using `bricks_from_excel()` with an animation.
- [**brickr 0.3 release video**](https://gist.github.com/ryantimpe/b685caaa7f6c001a9a227f48bf9a5852) with a static model and `bricks_from_excel()`.