First round of documentation edits for 0.3.1 CRAN review

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: brickr
 Title: Emulate LEGO Bricks in 2D and 3D
-Version: 0.3.1
+Version: 0.3.2
 Authors@R: 
     person(given = "Ryan",
            family = "Timpe",

NEWS.md

@@ -1,4 +1,4 @@
-# brickr 0.3.1
+# brickr 0.3.2
 
 * An overall leaner package to ensure optimal performance and remove experimental features.
 

R/bricks-from-tables.R

@@ -5,7 +5,7 @@
 #' @param matrix_table A data frame of a 3D brick model design. Left-most column is level/height/z dimension, with rows as Y axis and columns as X axis. See example. Use \code{\link[tibble]{tribble}} for ease.
 #' @param color_guide A data frame linking numeric \code{.value} in \code{matrix_table} to official LEGO color names. Defaults to data frame 'lego_colors'.
 #' @param piece_matrix A data frame in same shape as \code{matrix_table} with piece shape IDs.
-#' @param use_bricks Array of brick sizes to use in mosaic. Defaults to \code{c('4x2', '2x2', '3x1', '2x1', '1x1')}`.
+#' @param use_bricks Array of brick sizes to use in mosaic. Defaults to \code{c('4x2', '2x2', '3x1', '2x1', '1x1')}`. '1x1' will always be considered.
 #' @param .re_level Logical to reassign the Level/z dimension to layers in alphanumeric order. Set to FALSE to explicitly provide levels.
 #' @param increment_level Default '0'. Use in animations. Shift  Level/z dimension by an integer.
 #' @param min_level Default '1'. Use in animations. Any Level/z values below this value will be cut off.
@@ -58,8 +58,25 @@
 #'  build_bricks()
 #'  
 #'  rgl::clear3d()
-
-
+#'  
+#' #Provide a custom table of colors 
+#' custom_colors <- data.frame(
+#' .value = c(3, 4),
+#' Color = c("Bright orange", "Dark green")
+#' )
+#' 
+#'brick %>% 
+#'  bricks_from_table(color_guide  = custom_colors) %>% 
+#'  build_bricks()
+#'  
+#'  rgl::clear3d()
+#'  
+#'#Limit the size of bricks used in the model with use_bricks
+#'brick %>% 
+#'  bricks_from_table(use_bricks = "2x1") %>% #Only use 2x1 bricks.
+#'  build_bricks()
+#'  
+#'  rgl::clear3d()
 
 bricks_from_table <- function(matrix_table, color_guide = brickr::lego_colors, 
                               piece_matrix = NULL,
@@ -218,9 +235,10 @@ bricks_from_table <- function(matrix_table, color_guide = brickr::lego_colors,
 
 #' Convert an Excel 'brickr' template into a 3D object
 #' 
-#' Convert am Excel template file into a 3D brick object.
+#' Build a 3D model from an Excel template. A single data frame includes both the instructions and the color guides.
 #' 
-#' @param excel_table Sheet imported from a brickr Excel template to build model. Contains stud placement and colors.
+#' @param excel_table Sheet imported from a brickr Excel template to build model. 
+#' This differs slightly from \code{\link{bricks_from_table}} because a single data frame has both the brick coordinates and color table.
 #' @param piece_table Sheet identical in shape to \code{excel_table} with piece shape IDs.
 #' @param use_bricks Array of brick sizes to use in mosaic. Defaults to \code{c('4x2', '3x2', '2x2', '3x1', '2x1', '1x1')}`.
 #' @param repeat_levels How many times to repeat a level. Can save time in model planning. Default is 1.
@@ -228,21 +246,33 @@ bricks_from_table <- function(matrix_table, color_guide = brickr::lego_colors,
 #' @return A list with elements \code{Img_lego} to pass to \code{\link{build_bricks}}.
 #' @family 3D Models
 #' @export 
-#' @examples \donttest{
+#' @examples
 #' #Demo table in same format as Excel template
 #' #This creates a 1x3 red brick.
-#'brick <- tibble::tribble(
+#'demo_excel <- tibble::tribble(
 #' ~Level, ~"1", ~"2", ~"3", ~user_color, ~LEGO_color,
 #'  "A",  1,  1,  1,           1, "Bright red" 
 #' )
 #'
-#'brick %>% 
+#'demo_excel %>% 
 #'  bricks_from_excel() %>% 
 #'  build_bricks()
 #'  
 #'  rgl::clear3d()
-#' }
-#'
+#'  
+#' #To change the pieces, import a second table in the same shape, but with piece IDs.
+#' demo_pieces <- tibble::tribble(
+#' ~Level, ~"1", ~"2", ~"3",
+#'  "A",  "w4",  "c1",  "w2"    
+#' )
+#' 
+#'demo_excel %>% 
+#'  bricks_from_excel(piece_table = demo_pieces) %>% 
+#'  build_bricks()
+#'  
+#'  rgl::clear3d()
+#'  
+
 bricks_from_excel <- function(excel_table, 
                               piece_table = NULL,
                               use_bricks = NULL,
@@ -356,7 +386,7 @@ bricks_from_excel <- function(excel_table,
 #' @return A list with elements \code{Img_lego} to pass to \code{\link{build_bricks}}.
 #' @family 3D Models
 #' @export 
-#' @examples \donttest{
+#' @examples 
 #' #This is a 1x4 yellow brick
 #' brick <- data.frame(
 #'         x = 1:4,
@@ -377,15 +407,23 @@ bricks_from_excel <- function(excel_table,
 #' z = 1:3)
 #' 
 #' #Color them in sets of these 3 options
-#' bricks$color <- rep(rep(c("Bright yellow", "Bright red", "Dark green"), each=4), 8)
+#' bricks$color <- rep(rep(c("Bright yellow", "Bright red", "Tr. green"), each=4), 8)
 #' 
 #' bricks %>% 
 #'   bricks_from_coords() %>% 
 #'   build_bricks()
 #'   
 #'   rgl::clear3d()
+#'   
+#'#Use different brick shapes by added a 'piece_type' column
+#'bricks$piece_type <- "c1" #Make all the pieces cylinders
+#'
+#'bricks %>% 
+#'   bricks_from_coords() %>% 
+#'   build_bricks()
+#'   
+#'   rgl::clear3d()
 #' 
-#' }
 bricks_from_coords <- function(coord_table, 
                                use_bricks = NULL,
                                increment_level = 0, min_level = 1, max_level = Inf,

R/build-instructions.R

@@ -1,6 +1,6 @@
-#' Create instruction manual
+#' Create instruction manual for a 2D mosaic or 3D model
 #' 
-#' Render faceted plot of instructions for 2D mosacis or 3D model objects.
+#' Render faceted plot of instructions for 2D mosacis or 3D model objects. For mosaics, can specify the number of steps.
 #' 
 #' Instructions for 2D mosaics are split into sections beginning at the bottom of the image.
 #' This makes it easier to follow each row when building an actual brick mosaic.

R/build-mosaic.R

@@ -7,15 +7,14 @@
 #' @return A single plot object to display 2D mosaic.
 #' @family Mosaics
 #' @export 
-#' @examples \donttest{
-#' # Create a random 24x24 'image'. 
-#' # Otherwise, use a jpeg or png
-#'  demo_image = array(scales::rescale(runif(24*24*3), c(0, 1)), dim=c(24, 24, 3))
+#' @examples 
+#' 
+#' # Import a jpeg or png
+#'  demo_image = system.file("extdata", "demo_img.jpg", package = "brickr", mustWork = TRUE)
 #'
-#' demo_image %>% 
-#'  image_to_mosaic(img_size = 24) %>% 
+#' jpeg::readJPEG(demo_image) %>% 
+#'  image_to_mosaic() %>% 
 #'  build_mosaic()
-#'}
 
 build_mosaic <- function(brick_obj, title=NULL){
   in_list <- brick_obj

man/bricks_from_coords.Rd

@@ -50,7 +50,6 @@ A list with elements \code{Img_lego} to pass to \code{\link{build_bricks}}.
 Convert a data frame with x, y, z & Color columns into a 3D object
 }
 \examples{
-\donttest{
 #This is a 1x4 yellow brick
 brick <- data.frame(
         x = 1:4,
@@ -71,7 +70,16 @@ y = 1:4,
 z = 1:3)
 
 #Color them in sets of these 3 options
-bricks$color <- rep(rep(c("Bright yellow", "Bright red", "Dark green"), each=4), 8)
+bricks$color <- rep(rep(c("Bright yellow", "Bright red", "Tr. green"), each=4), 8)
+
+bricks \%>\% 
+  bricks_from_coords() \%>\% 
+  build_bricks()
+  
+  rgl::clear3d()
+  
+#Use different brick shapes by added a 'piece_type' column
+bricks$piece_type <- "c1" #Make all the pieces cylinders
 
 bricks \%>\% 
   bricks_from_coords() \%>\% 
@@ -79,7 +87,6 @@ bricks \%>\%
   
   rgl::clear3d()
 
-}
 }
 \seealso{
 Other 3D Models: 

man/bricks_from_excel.Rd

@@ -21,7 +21,8 @@ bricks_from_excel(
 )
 }
 \arguments{
-\item{excel_table}{Sheet imported from a brickr Excel template to build model. Contains stud placement and colors.}
+\item{excel_table}{Sheet imported from a brickr Excel template to build model.
+This differs slightly from \code{\link{bricks_from_table}} because a single data frame has both the brick coordinates and color table.}
 
 \item{piece_table}{Sheet identical in shape to \code{excel_table} with piece shape IDs.}
 
@@ -51,24 +52,34 @@ bricks_from_excel(
 A list with elements \code{Img_lego} to pass to \code{\link{build_bricks}}.
 }
 \description{
-Convert am Excel template file into a 3D brick object.
+Build a 3D model from an Excel template. A single data frame includes both the instructions and the color guides.
 }
 \examples{
-\donttest{
 #Demo table in same format as Excel template
 #This creates a 1x3 red brick.
-brick <- tibble::tribble(
+demo_excel <- tibble::tribble(
 ~Level, ~"1", ~"2", ~"3", ~user_color, ~LEGO_color,
  "A",  1,  1,  1,           1, "Bright red" 
 )
 
-brick \%>\% 
+demo_excel \%>\% 
  bricks_from_excel() \%>\% 
  build_bricks()
  
  rgl::clear3d()
-}
+ 
+#To change the pieces, import a second table in the same shape, but with piece IDs.
+demo_pieces <- tibble::tribble(
+~Level, ~"1", ~"2", ~"3",
+ "A",  "w4",  "c1",  "w2"    
+)
 
+demo_excel \%>\% 
+ bricks_from_excel(piece_table = demo_pieces) \%>\% 
+ build_bricks()
+ 
+ rgl::clear3d()
+ 
 }
 \seealso{
 Other 3D Models: 

man/bricks_from_table.Rd

@@ -2,7 +2,7 @@
 % Please edit documentation in R/bricks-from-tables.R
 \name{bricks_from_table}
 \alias{bricks_from_table}
-\title{Convert a matrix table into a 'brickr' 3D object}
+\title{Convert a table into a 'brickr' 3D object}
 \usage{
 bricks_from_table(
   matrix_table,
@@ -28,7 +28,7 @@ bricks_from_table(
 
 \item{piece_matrix}{A data frame in same shape as \code{matrix_table} with piece shape IDs.}
 
-\item{use_bricks}{Array of brick sizes to use in mosaic. Defaults to \code{c('4x2', '3x2', '2x2', '3x1', '2x1', '1x1')}`.}
+\item{use_bricks}{Array of brick sizes to use in mosaic. Defaults to \code{c('4x2', '2x2', '3x1', '2x1', '1x1')}`. '1x1' will always be considered.}
 
 \item{.re_level}{Logical to reassign the Level/z dimension to layers in alphanumeric order. Set to FALSE to explicitly provide levels.}
 
@@ -54,11 +54,10 @@ bricks_from_table(
 A list with elements \code{Img_lego} to pass to \code{\link{build_bricks}}.
 }
 \description{
-Convert a data frame into a 3D brick object.
+Create a 3D brick object from a data frame. Left-most column is level/height/z dimension, with rows as Y axis and columns as X axis.
 }
 \examples{
-\donttest{
-#This is a brick
+#This is a 4x2 brick. One level high, 2 x-values (columns), 4 y-values (rows).
 brick <- data.frame(
  Level="A",
  X1 = rep(3,4), #The number 3 is the brickrID for 'bright red'
@@ -70,7 +69,51 @@ brick \%>\%
  build_bricks()
  
  rgl::clear3d()
-}
+ 
+#Build on top of each other by changing the Level value.
+#This example builds a blue 2x2 brick on top of a red 2x2
+brick <- data.frame(
+ Level=c("A", "A", "B", "B"),
+ X1 = c(3, 3, 4, 4), #3 is red, 4 is blue
+ X2 = c(3, 3, 4, 4)
+)
+
+brick \%>\% 
+ bricks_from_table() \%>\% 
+ build_bricks()
+ 
+ rgl::clear3d()
+
+#Provide an additional piece_matrix  argument to change the default brick shape.
+pieces <- data.frame(
+ Level=c("A", "A", "B", "B"),
+ X1 = c("b", "b", "p", "p"), #b is brick (default), p is plate
+ X2 = c("b", "b", "p", "p")
+)
+brick \%>\% 
+ bricks_from_table(piece_matrix=pieces) \%>\% 
+ build_bricks()
+ 
+ rgl::clear3d()
+ 
+#Provide a custom table of colors 
+custom_colors <- data.frame(
+.value = c(3, 4),
+Color = c("Bright orange", "Dark green")
+)
+
+brick \%>\% 
+ bricks_from_table(color_guide  = custom_colors) \%>\% 
+ build_bricks()
+ 
+ rgl::clear3d()
+ 
+#Limit the size of bricks used in the model with use_bricks
+brick \%>\% 
+ bricks_from_table(use_bricks = "2x1") \%>\% #Only use 2x1 bricks.
+ build_bricks()
+ 
+ rgl::clear3d()
 }
 \seealso{
 Other 3D Models: 

man/build_instructions.Rd

@@ -2,7 +2,7 @@
 % Please edit documentation in R/build-instructions.R
 \name{build_instructions}
 \alias{build_instructions}
-\title{Create instruction manual}
+\title{Create instruction manual for a 2D mosaic or 3D model}
 \usage{
 build_instructions(brickr_obj, num_steps = 6)
 }
@@ -15,7 +15,7 @@ build_instructions(brickr_obj, num_steps = 6)
 A single plot object of steps to build brickr model or mosaic.
 }
 \description{
-Render faceted plot of instructions for 2D mosacis or 3D model objects.
+Render faceted plot of instructions for 2D mosacis or 3D model objects. For mosaics, can specify the number of steps.
 }
 \details{
 Instructions for 2D mosaics are split into sections beginning at the bottom of the image.

man/build_mosaic.Rd

@@ -18,16 +18,14 @@ A single plot object to display 2D mosaic.
 Render a plot image of the 2D brick mosaic with optional title.
 }
 \examples{
-\donttest{
-# Create a random 24x24 'image'. 
-# Otherwise, use a jpeg or png
- demo_image = array(scales::rescale(runif(24*24*3), c(0, 1)), dim=c(24, 24, 3))
 
-demo_image \%>\% 
- image_to_mosaic(img_size = 24) \%>\% 
+# Import a jpeg or png
+ demo_image = system.file("extdata", "demo_img.jpg", package = "brickr", mustWork = TRUE)
+
+jpeg::readJPEG(demo_image) \%>\% 
+ image_to_mosaic() \%>\% 
  build_mosaic()
 }
-}
 \seealso{
 Other Mosaics: 
 \code{\link{image_to_mosaic}()}