-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
150 lines (109 loc) · 7.11 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
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
eval = FALSE,
collapse = TRUE,
comment = "#",
fig.path = "man/figures/README-",
out.width = "100%"
)
library(pixeltrix)
```
# pixeltrix <a href="https://github.com/matt-dray/pixeltrix"><img src="man/figures/logo.png" align="right" height="139" /></a>
<!-- badges: start -->
[](https://www.repostatus.org/#active)
[](https://github.com/matt-dray/tamRgo/actions)
[](https://app.codecov.io/gh/matt-dray/pixeltrix?branch=main)
[](https://www.rostrum.blog/tags/pixeltrix/)
<!-- badges: end -->
Create static and animated pixel art from an interactive plot window in R. Returns your image's 'blueprint' as a matrix. Pixel + matrix = {pixeltrix}.
## How to
You can install {pixeltrix} [from GitHub](https://github.com/matt-dray/pixeltrix). It has no dependencies unless you want to make gifs, which requires you to install [{gifski}](https://cloud.r-project.org/web/packages/gifski/index.html).
```{r eval=FALSE}
install.packages("remotes") # if not yet installed
remotes::install_github("matt-dray/pixeltrix")
library(pixeltrix)
```
Basic use:
1. Use `click_pixels()` to begin an interactive, clickable plot of squares ('pixels').
2. Click individual pixels repetitively to cycle through their states.
3. Press the <kbd>Esc</kbd> key when you're done, or the 'Finish' button in RStudio's plot window, to return a matrix that encodes your image.
You can also:
* draw your matrix to the plotting window as an image with `draw_pixels()`
* make changes by passing the matrix output from `click_pixels()` into `edit_pixels()`
* create animation frames (a list of matrices) with `frame_pixels()` and write them to a gif with `gif_pixels()`
## Limitations
This package does what I need it to do; it doesn't match the quality of a real pixel art editor. Some known limitations are that:
* you can only click one pixel at a time
* each click only increments the pixel state by 1
* you can't change the number of pixel states on the fly, nor the colour palette
If your editor opens a separate graphics window (i.e. not RStudio), each click may result in a brief flash as the image refreshes, while a resized window may return to its original dimensions. You may also hear a bell sound on click, which you can disable by setting `options(locatorBell = FALSE)`.
## Examples
### Static sprite
Let's create a sprite of the player character from _Pokémon_ (1996) using `click_pixels()`:
```{r}
pkmn_sprite <- click_pixels(
n_rows = 16,
n_cols = 14,
n_states = 3, # number of states that a pixel can take
colours = c("white", "#879afb", "grey20") # Pokémon Blue palette
)
# Click squares in the plot window. Press <Esc> to end.
```
This opens an interactive plot window. You can click to cycle the pixels through each of the three states. Here's how the finished version looks in RStudio:
<img src="man/figures/pkmn-rstudio.png" alt="An RStudio window. The console has run the function click_pixels(blue) and has printed the message 'click squares in the plot window, press Esc to end.' In the plot pane is a 16 by 14 pixel grid with a sprite of the main character from the first generation of Pokemon games for the Game Boy. The background is white, the outlines are dark grey and the highlights are light blue There's a black grid around the pixels." width="50%">
A matrix is returned when you've finished clicking and pressed <kbd>Esc</kbd>. Note that the values are zero-indexed and the corresponding colour palette is stored in a `colours` attribute. The object also gets the class 'pixeltrix'.
```{r eval=TRUE}
str(pkmn_sprite)
is_pixeltrix(pkmn_sprite)
```
The `pkmn_sprite` object is built-in to {pixeltrix} for demo purposes.
You can pass the 'pixeltrix' object to `edit_pixels()` to reopen the interactive plotting window to make adjustments. You can also increase `n_states` or change the colour palette. You could also create a matrix 'by hand' and use `as_pixeltrix()` to coerce it to a 'pixeltrix' object with a greyscale palette.
The `draw_pixels()` function simply plots your matrix, optionally with a new colour palette:
```{r eval=FALSE}
draw_pixels(
m = pkmn_sprite,
colours = c("#9bbc0f", "#8bac0f", "#306230") # Game Boy palette
)
```
<img src="man/figures/pkmn.png" alt="A 14 by 16 pixel grid with a sprite of the main character from the first generation of Pokemon games for the Game Boy. It's coloured using the green shades of the original Game Boy." width="33%">
### Animated sprite
You can create multiple animation frames with `frame_pixels()`. The prior frame is used as a template for the next.
Here's how it might look to recreate Mario's walk cycle from _Super Mario Brothers_ (1983), including an interactive prompt to add more frames as required:
```{r}
mario_frames <- frame_pixels(
n_rows = 16,
n_cols = 16,
n_states = 4,
colours = c("#8861FE", "#F6B95B", "#EF151A", "#7F6D14")
)
# Click squares in the plot window. Press <Esc> to end.
# Add a frame? y/n: y
# Click squares in the plot window. Press <Esc> to end.
# Current frame count: 2
# Add a frame? y/n: y
# Click squares in the plot window. Press <Esc> to end.
# Current frame count: 3
# Add a frame? y/n: n
# Final frame count: 3
```
The structure of the object is a list of matrices, where each matrix is a frame of the animation. This object is provided in {pixeltrix} as a demo dataset.
```{r eval=TRUE}
str(mario_frames)
```
You can then convert the frames to a gif with `gif_pixels()`.
```{r}
gif_pixels(
frames = mario_frames,
file = "mario.gif", # write location
delay = 0.15 # passed to gifski::save_gif()
)
# Inserting image 3 at 0.30s (100%)...
# Encoding to gif... done!
# [1] "mario.gif"
```
Which results in this:
<img src="man/figures/mario.gif" alt="An animated 16 by 16 pixel grid with a coloured sprite of Mario from the original Super Mario Bros for the NES. There are three frames that each show a step in Mario's walk cycle." width="33%">