Merge pull request #37 from matt-dray/36-pixeltrix-class

Add pixeltrix class

Author: matt-dray

DESCRIPTION

@@ -1,21 +1,22 @@
 Package: pixeltrix
-Title: Simple Interactive Pixel Art
-Version: 0.2.1.9000
+Title: A Simple Interactive Pixel Art Editor
+Version: 0.2.2
 Authors@R: 
     person("Matt", "Dray", , "[email protected]", role = c("aut", "cre"))
 Description: A very simple 'pixel art' tool that lets you click squares
-    interactively in a plot window and returns your final image as a matrix. 
-    Provide multiple frames to create an animated gif.
+    interactively in a plot window and returns your final image as a
+    matrix.  Provide multiple frames to create an animated gif.
 License: MIT + file LICENSE
-URL: https://github.com/matt-dray/pixeltrix, https://matt-dray.github.io/pixeltrix
+URL: https://github.com/matt-dray/pixeltrix,
+    https://matt-dray.github.io/pixeltrix
 BugReports: https://github.com/matt-dray/pixeltrix/issues
-Encoding: UTF-8
-Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.1.2
+Depends: 
+    R (>= 2.10)
 Suggests: 
     gifski,
     testthat (>= 3.0.0)
 Config/testthat/edition: 3
-Depends: 
-    R (>= 2.10)
+Encoding: UTF-8
 LazyData: true
+Roxygen: list(markdown = TRUE)
+RoxygenNote: 7.3.1

NAMESPACE

@@ -1,7 +1,9 @@
 # Generated by roxygen2: do not edit by hand
 
+export(as_pixeltrix)
 export(click_pixels)
 export(draw_pixels)
 export(edit_pixels)
 export(frame_pixels)
 export(gif_pixels)
+export(is_pixeltrix)

NEWS.md

@@ -1,10 +1,11 @@
-# pixeltrix 0.2.1.9000
+# pixeltrix 0.2.2
 
-* Added warning to README and function docs about flickering and the bell (#31, #32, thanks @adrianadepalma)
+* Added 'pixeltrix' class to matrix objects output by `click_pixels()` and `edit_pixels()`, and included `is_pixeltrix()` and `as_pixeltrix()` to detect and coerce (#36, thanks @trevorld).
+* Added warning to README and function docs about flickering and the bell (#31, #32, thanks @adrianadepalma).
 
 # pixeltrix 0.2.1
 
-* Added additional input checks to check-utils.R.
+* Added additional input checks to `check-utils.R`.
 * `draw_pixels()` now finds `n_states` (#24).
 * Allow for an increased number of states in `edit_pixels()` (#25).
 
@@ -14,7 +15,7 @@
 * A named character vector of colours is now accepted as input to `click_pixels()`, `edit pixels()`, `draw_pixels()` and `frame_pixels()`.
 * Breaking: `blue` and `mario` demo datasets no longer available; `pkmn_sprite` and `mario_frames` replace them (#22).
 * Updated and expanded function documentation and README (#21).
-* Reused input checks have been generalised into 'R/utils-check.R'.
+* Reused input checks have been generalised into `R/utils-check.R`.
 * Expanded tests to cover argument input errors.
 
 # pixeltrix 0.1.3
@@ -45,7 +46,7 @@
 # pixeltrix 0.0.0.9004
 
 * Added an `edit_pixels()` function so that a matrix created with `click_pixels()` can be updated (#6).
-* Moved support functions to utils.R.
+* Moved support functions to `utils.R`.
 * Simplified the README and added a blog badge.
 
 # pixeltrix 0.0.0.9003
@@ -58,7 +59,7 @@
 # pixeltrix 0.0.0.9002
 
 * Went the non-Shiny route and used `locator()` and `image()` for interactivity in the `click_pixel()` function (#2).
-* Added GitHub Actions for R-CMD check, tests, {pkgdown} webbite.
+* Added GitHub Actions for R-CMD check, tests, {pkgdown} website.
 * This version was [previewed in a tweet](https://twitter.com/mattdray/status/1573053714788753408?s=20&t=0HzMLD0fjc5evjtCKqQY3g).
 
 # pixeltrix 0.0.0.9001

R/animate.R

@@ -40,14 +40,13 @@
 #' @export
 #'
 #' @examples \dontrun{
-#'     # Begin interactive sequence to create animation frames
-#'     my_frames <- frame_pixels(
-#'       n_rows   = 16L,
-#'       n_cols   = 16L,
-#'       n_states = 3L,
-#'       colours  = c("grey25", "green", "#0000FF")
-#'     )
-#' }
+#' # Begin interactive sequence to create animation frames
+#' my_frames <- frame_pixels(
+#'   n_rows   = 16L,
+#'   n_cols   = 16L,
+#'   n_states = 3L,
+#'   colours  = c("grey25", "green", "#0000FF")
+#' )}
 frame_pixels <- function(
     n_rows   = 8L,
     n_cols   = 8L,
@@ -115,21 +114,20 @@ frame_pixels <- function(
 #' @export
 #'
 #' @examples \dontrun{
-#'     # Begin interactive sequence to create animation frames
-#'     my_frames <- frame_pixels(
-#'       n_rows   = 16L,
-#'       n_cols   = 16L,
-#'       n_states = 3L,
-#'       colours  = c("grey25", "green", "#0000FF")
-#'     )
+#' # Begin interactive sequence to create animation frames
+#' my_frames <- frame_pixels(
+#'   n_rows   = 16L,
+#'   n_cols   = 16L,
+#'   n_states = 3L,
+#'   colours  = c("grey25", "green", "#0000FF")
+#' )
 #'
-#'     # Write list of matrices to gif (requires 'gifski' installation)
-#'     gif_pixels(
-#'       frames = my_frames,
-#'       file = "example.gif",  # location to write GIF
-#'       delay = 0.1            # passed to gifski::save_gif()
-#'     )
-#' }
+#' # Write list of matrices to gif (requires 'gifski' installation)
+#' gif_pixels(
+#'   frames = my_frames,
+#'   file = "example.gif",  # location to write GIF
+#'   delay = 0.1            # passed to gifski::save_gif()
+#' )}
 gif_pixels <- function(
     frames,
     colours = NULL,

R/click.R

@@ -29,22 +29,22 @@
 #'     bell sound on click, which you can disable by setting
 #'     `options(locatorBell = FALSE)`.
 #'
-#' @return A matrix. The zero-indexed values correspond to the state of each
-#'     pixel, which is determined by the number of clicks. Has an additional
-#'     attribute: a named character vector, 'colours', which maps the values in
-#'     the matrix to the colours provided by the user (or a gradated set of
-#'     greys provided by default when the 'colours' argument is NULL).
+#' @return A 'pixeltrix'-class matrix. The zero-indexed values correspond to the
+#'     state of each pixel, which is determined by the number of clicks a user
+#'     gave each pixel. Has a named character-vector attribute, 'colours', which
+#'     maps the matrix values to hex colours provided by the user (or a gradated
+#'     set of greys provided by default when the 'colours' argument is NULL).
 #'
 #' @export
 #'
 #' @examples \dontrun{
-#'     # Create a 16 x 16 pixel matrix with 3 possible pixel states
-#'     my_matrix <- click_pixels(
-#'       n_rows   = 16L,
-#'       n_cols   = 16L,
-#'       n_states = 3L,
-#'       colours  = c("blue", "#FF0000", "yellow")
-#'     )
+#' # Create a 16 x 16 pixel matrix with 3 possible pixel states
+#' my_matrix <- click_pixels(
+#'   n_rows   = 16L,
+#'   n_cols   = 16L,
+#'   n_states = 3L,
+#'   colours  = c("blue", "#FF0000", "yellow")
+#' )
 #' }
 click_pixels <- function(
     n_rows   = 8L,
@@ -79,7 +79,8 @@ click_pixels <- function(
   if (grid) .add_grid(m)
   m <- .repeat_loop(m, n_states, colours, grid)
 
-  # Add colours as an attribute to returned matrix
+  # Add class and colours as attributes to returned matrix
+  class(m) <- "pixeltrix"
   attr(m, "colours") <- stats::setNames(colours, seq(0, n_states - 1))
 
   m
@@ -121,29 +122,32 @@ click_pixels <- function(
 #'     bell sound on click, which you can disable by setting
 #'     `options(locatorBell = FALSE)`.
 #'
-#' @return A matrix.
+#' @return A 'pixeltrix'-class matrix. The zero-indexed values correspond to the
+#'     state of each pixel, which is determined by the number of clicks a user
+#'     gave each pixel. Has a named character-vector attribute, 'colours', which
+#'     maps the matrix values to hex colours provided by the user (or a gradated
+#'     set of greys provided by default when the 'colours' argument is NULL).
 #'
 #' @export
 #'
 #' @examples \dontrun{
-#'     # Create a 3 x 4 pixel matrix with 3 possible states to cycle through
-#'     my_matrix <- click_pixels(
-#'       n_rows   = 3L,
-#'       n_cols   = 4L,
-#'       n_states = 3L,
-#'       colours  = c("white", "red", "#0000FF")
-#'     )
-#'
-#'.    # Update the original matrix
-#'     my_matrix_edited <- edit_pixels(m = my_matrix)
-#'
-#'     # Update the original matrix with additional state, different colours
-#'     my_matrix_augmented <- edit_pixels(
-#'       m        = my_matrix,
-#'       n_states = 4L,  # one more than in the original
-#'       colours  = c("bisque3", "orchid", "chartreuse", "olivedrab")
-#'     )
-#' }
+#' # Create a 3 x 4 pixel matrix with 3 possible states to cycle through
+#' my_matrix <- click_pixels(
+#'   n_rows   = 3L,
+#'   n_cols   = 4L,
+#'   n_states = 3L,
+#'   colours  = c("white", "red", "#0000FF")
+#' )
+#'
+#'.# Update the original matrix
+#' my_matrix_edited <- edit_pixels(m = my_matrix)
+#'
+#' # Update the original matrix with additional state, different colours
+#' my_matrix_augmented <- edit_pixels(
+#'   m        = my_matrix,
+#'   n_states = 4L,  # one more than in the original
+#'   colours  = c("bisque3", "orchid", "chartreuse", "olivedrab")
+#' )}
 edit_pixels <- function(
     m,
     n_states = NULL,
@@ -182,9 +186,61 @@ edit_pixels <- function(
   if (grid) .add_grid(m)
   m <- .repeat_loop(m, n_states, colours, grid)
 
-  # Add colours as an attribute to returned matrix
+  # Add class and colours as attributes to returned matrix
+  class(m) <- "pixeltrix"
+  attr(m, "colours") <- stats::setNames(colours, seq(0, n_states - 1))
+
+  m
+
+}
+
+#' Coerce to a 'pixeltrix' Object
+#'
+#' Functions to check if an object is of 'pixeltrix' class, or coerce to it if
+#' possible.
+#'
+#' @param m A matrix of integers to coerce.
+#'
+#' @details To be successfully coerced, `m` must be a matrix composed only of
+#'     integers.
+#'
+#' @return \code{as_pixeltrix} returns an object of class 'pixeltrix' if
+#'     possible. \code{is_pixeltrix} returns \code{TRUE} if the object has class
+#'     'pixeltrix', otherwise \code{FALSE}. If coerced, a named character-vector
+#'     attribute, 'colours', is also added, which maps the matrix values to a
+#'     gradated palette of greys in hex form.
+#'
+#' @examples
+#' m <- matrix(c(0L, 1L, 1L, 0L), 2, 2)
+#' is_pixeltrix(m)
+#' m
+#'
+#' m <- as_pixeltrix(m)
+#' is_pixeltrix(m)
+#' m
+#'
+#' @export
+as_pixeltrix <- function(m) {
+
+  .check_matrix(m)
+
+  if (inherits(m, "pixeltrix")) {
+    return(m)
+  }
+
+  n_states <- max(unique(as.vector(m)) + 1L)
+  get_greys <- grDevices::colorRampPalette(c("white", "grey20"))
+  colours <- get_greys(n_states)
+
+  class(m) <- "pixeltrix"
   attr(m, "colours") <- stats::setNames(colours, seq(0, n_states - 1))
 
   m
 
 }
+
+#' @rdname as_pixeltrix
+#' @export
+is_pixeltrix <- function(m) {
+  inherits(m, "pixeltrix")
+}

R/data.R

@@ -5,11 +5,11 @@
 #' in a font with letters that are 3 by 3 pixels.
 #'
 #' @examples \dontrun{
-#'     # Plot the matrix as an image
-#'     draw_pixels(m = pixeltrix::logo)
-#' }
+#' # Plot the matrix as an image
+#' draw_pixels(m = pixeltrix::logo)}
 #'
-#' @format A matrix with 10 rows and 21 columns, taking integers from 0 to 2.
+#' @format A 'pixeltrix'-class matrix with 10 rows and 21 columns, taking
+#'     integers from 0 to 2.
 "logo"
 
 #' Example Sprite Matrix: Mario
@@ -19,16 +19,15 @@
 #' the walk cycle.
 #'
 #' @examples \dontrun{
-#'     # Write the list of matrices to a gif
-#'     gif_pixels(
-#'       frames = pixeltrix::mario_frames,
-#'       file = "mario.gif",
-#'       delay = 0.15  # passed to gifski::save_gif()
-#'     )
-#' }
+#' # Write the list of matrices to a gif
+#' gif_pixels(
+#'   frames = pixeltrix::mario_frames,
+#'   file = "mario.gif",
+#'   delay = 0.15  # passed to gifski::save_gif()
+#' )}
 #'
-#' @format A list of matrices, each with 16 rows and 16 columns, taking integers
-#'     from 0 to 2.
+#' @format A list of 'pixeltrix'-class matrices, each with 16 rows and 16
+#'     columns, taking integers from 0 to 2.
 #'
 #' @source Super Mario Bros (1983), Nintendo.
 "mario_frames"
@@ -39,14 +38,14 @@
 #' a player sprite from Pokémon.
 #'
 #' @examples \dontrun{
-#'     # Plot the matrix as an image
-#'     draw_pixels(
-#'       m = pixeltrix::pkmn_sprite,
-#'       colours = c("#9bbc0f", "#8bac0f", "#306230")
-#'     )
-#' }
-#'
-#' @format A matrix with 16 rows and 14 columns, taking integers from 0 to 2.
+#' # Plot the matrix as an image
+#' draw_pixels(
+#'   m = pixeltrix::pkmn_sprite,
+#'   colours = c("#9bbc0f", "#8bac0f", "#306230")
+#' )}
+#'
+#' @format A 'pixeltrix'-class matrix with 16 rows and 14 columns, taking
+#'     integers from 0 to 2.
 #'
 #' @source Hand-copied from Pokemon (1996), The Pokemon Company.
 "pkmn_sprite"

R/draw.R

@@ -18,9 +18,8 @@
 #' @export
 #'
 #' @examples \dontrun{
-#'   my_matrix <- click_pixels(n_states = 3L)
-#'   draw_pixels(my_matrix, c("black", "#0000FF", "green"))  # one colour per state
-#' }
+#' my_matrix <- click_pixels(n_states = 3L)
+#' draw_pixels(my_matrix, c("black", "#0000FF", "green"))  # a colour per state}
 draw_pixels <- function(m, colours = NULL) {
 
   .check_matrix(m)