Debian Codegraph @

texmf-dist/doc/latex/pixelart/pixelart.tex

raw
1 \documentclass[
2 load-preamble-,
3 babel-options=english,
4 add-index=true,
5 ]{cnltx-doc}
6
7 \usepackage{pixelart}
8
9 \setcnltx{
10 name = pixelart,
11 title = \pixelartlogo,
12 version = v1.0.2,
13 date = 2023-02-20,
14 info = A \LaTeX{} package to draw pixel-art pictures ,
15 authors = Louis Paternault ,
16 email = spalax(at)gresille(dot)org ,
17 url = https://framagit.org/spalax/pixelart ,
18 abstract = {%
19 This package defines macros to draw pixel-art pictures using Lua\LaTeX{}.
20 } ,
21 index-setup = { othercode=\footnotesize,level=\section},
22 add-cmds = {
23 pixelart,
24 pixelartheart,
25 pixelartheartbw,
26 pixelartlogo,
27 pixelartlogobw,
28 pixelartname,
29 pixelartnamebw,
30 newpixelartcolors,
31 renewpixelartcolors,
32 setpixelartdefault,
33 setpixelartdebugon,
34 setpixelartdebugoff,
35 tikzpixelart,
36 },
37 add-frame-options = {
38 innerleftmargin=2em
39 }
40 }
41
42 \usepackage{booktabs}
43 \usepackage{csquotes}
44 \usepackage{graphicx}
45 \usepackage{markdown}
46 \usepackage{multicol}
47 \usepackage[autolanguage]{numprint}
48 \usepackage{siunitx}
49 \usepackage{subfigure}
50 \usepackage[inline]{enumitem}
51
52 \begin{document}
53
54 \part{Introduction}
55
56 Installation instruction are given in section \ref{sec:install}.
57 Documentation about how to use this package (and examples) is given in part \ref{part:usage}. Most of the examples has been gathered in appendix \ref{sec:examples}.
58
59 \section{Note to non-Lua\LaTeX{} users}
60
61 Unfortunately, package \pkg{pixelart} does not works with \LaTeX{} or Xe\LaTeX. If you cannot or don't want to use Lua\LaTeX{}, you can:
62 \begin{itemize}
63 \item use the previous, unmaintained version of \pkg{pixelart}, named \pkg{pixelart0}, and included with this package;
64 \item or, better, use \pkg{pxpic}.
65 \end{itemize}
66
67 \section{License}
68
69 This work may be distributed and/or modified under the conditions of the \LPPL, either version 1.3 of this license or (at your option) any later version.
70
71 \section{Installation}
72 \label{sec:install}
73
74 \subsection{\textsc{Gnu}/Linux Distribution}
75
76 If applicable, the easiest way to get \pkg{pixelart} working is by installing it by your distribution package. In Debian (and Ubuntu, and surely other distributions that inherit from Debian) it is packaged in \texttt{texlive-pictures} since version \texttt{2017.20180103-1}. So you can install it by running:
77
78 \begin{lstlisting}[language=sh]
79 sudo apt install texlive-pictures
80 \end{lstlisting}
81
82 \subsection{LaTeX distribution}
83
84 This package is included both in \TeX{}Live and MiK\TeX{}. It can be installed using their respective package managers.
85
86 \subsection{Manual installation}
87
88 \begin{itemize}
89 \item Download the lastest archive :
90 \begin{description}
91 \item[Stable version] \url{https://mirrors.ctan.org/graphics/pgf/contrib/pixelart.zip}
92 \item[Development version] \url{https://framagit.org/spalax/pixelart/repository/archive.zip?ref=main}
93 \end{description}
94 \item Unzip the archive.
95 \item Move files \texttt{pixelart.sty} and \texttt{pixelart.lua} into a \LaTeX{} path.
96 \end{itemize}
97
98 \part{Usage}
99 \label{part:usage}
100
101 \section{Package options}
102
103 The package accepts a single option.
104
105 \begin{options}
106 \opt{draft} Loading the package with this options is equivalent to using option \option{draft} on every single call of command \cs{pixelart} (or \cs{tikzpixelart}). If your document contains a lot of those commands, using this option can speed up compilation.
107 For instance, on my outdated computer, compilation of this document takes about 11 seconds with this option, and more than 16 seconds without.
108
109 See option \option*{draft} (page \pageref{option:draft}) for more information.
110 \end{options}
111
112
113 \section{Drawing pictures}
114
115 \begin{figure}
116 \begin{sidebyside}
117 I \pixelart[
118 tikz={
119 red,
120 scale=.05,
121 baseline=.3em,
122 }
123 ]{
124 ..11..11..
125 .11111111.
126 1111111111
127 1111111111
128 1111111111
129 .11111111.
130 ..111111..
131 ...1111...
132 ....11....
133 } \LaTeX
134 \end{sidebyside}
135 \caption{Basic example}
136 \label{fig:basic}
137 \end{figure}
138
139 \begin{commands}
140 \command{pixelart}[\oarg{options}{\marg{pixels}}]
141 This is the basic command to draw pixel-art. Its mandatory argument is a sequence of pixels, as characters which will be turned into colored squares (using a \env*{tikzpicture}, from Till Tantau's \pkg{TikZ}). Its basic usage is given in figure \ref{fig:basic} (page \pageref{fig:basic}).
142
143 In argument \marg{pixels}, dots \texttt{.} are converted to transparent pixels, spaces and line breaks delimit pixel rows, and any character defines a color, depending on option \option{colors}.
144
145 More information is given in section \ref{sec:pixels}.
146
147 \begin{options}
148 \opt{pixels} The art, as a list of pixels. See section \ref{sec:pixels}.
149
150 \keyval{colors}{options} Pixel colors. See section \ref{sec:colors}.
151
152 \keybool{draft}\label{option:draft} Disable rendering of \cs{pixelart} and \cs{tikzpixelart} commands: on documents containing a lot of thoses commands, this can speed up compilation. The pixel art is replaced by a dummy drawing, which takes the same space as the pixel art it replaces.
153
154 This option can be applied to every single \cs{pixelart} or \cs{tikzpixelart} of the document by using \verb+\usepackage[draft]{pixelart}+.
155
156 See an example in \ref{example:draft}.
157
158 \keyval-{margin}{length} Pixel-art pictures are \emph{enclosed} inside a \pkg*{tikz} \cs*{clip} command. Most of the time, you won't notice it, but when playing with options \option{style} or \option{tikz}, your picture might extend outside usual borders, and part of it might be clipped out. Use the \option*{margin} option to extend the clip area. See example \ref{example:margin}.
159
160 \opt{squares} If set, each pixel is drawn using a separate \cs*{fill} command (more in section \ref{sec:squares}). This option is incompatible with \option{stack} (see section \ref{sec:squaresstack}).
161
162 \opt{stack} If set, \pkg*{pixelart} will try to draw several adjacent pixels of the same color using a single \cs*{fill} command (more in section \ref{sec:stack}). This option is incompatible with \option{squares} (see section \ref{sec:squaresstack}).
163
164 \keyval-{style}{keyword}\Default{pixelart}\label{option:style} Pixels are drawn using \cs*{fill} commands in a \env*{tikzpicture} environment. Those \cs*{fill} commands are applied the \texttt{pixelart} style by default (as in: \verb+\fill[pixelart] (0, 0) rectangle (1, 1);+). You can set another style by using this command. See an example in \ref{example:style}.
165
166 \keyval{tikz}{options}\label{option:tikz} A pixel art is a bunch of \cs*{fill} commands in a \env*{tikzpicture}. Arguments to this option are passed as-is as optional arguments to the \env*{tikzpicture} environment. See examples in \ref{example:tikz}.
167
168 You will probably use this option to make the pixel art smaller (it is, by default, probably bigger than what you want), and to change the baseline. See figure \ref{fig:basic} for an example.
169
170 Note that a \cs*{clip} command, which does not accept arguments, is used to delimit the picture. So you might get an error if your \option*{tikz} option applies to \cs*{clip} commands (for instance, by using \texttt{every path/.style={bla bla bla}}, which would apply to the \cs*{clip} command, and would raise an error). In such cases, you might want to use option \option{style} instead (see page \pageref{option:style}).
171
172 \end{options}
173
174 \command{tikzpixelart}[\oarg{options}\marg{coord}\marg{pixels}]
175 Use this command if you want to draw pixel art pictures \emph{inside} a \env*{tikzpicture} environment.
176
177 The \oarg{options} and \marg{pixels} arguments have the same meaning as the corresponding arguments to the \cs{pixelart} command (excepted for \option{tikz}, which is passed as is as the argument of a \env*{scope} environment).
178 The \marg{coord} is the coordinate of the bottom left corner of the pixel art. It is passed as is in a \pkg*{TikZ} \env*{scope} environment (\verb+\begin{scope}[shift={<coord>}]+), so you can use anything that will be correctly parsed by \pkg*{TikZ}.
179
180 See examples in section \ref{example:tikzpixelart}.
181 \end{commands}
182
183 \subsection{Pixels}
184 \label{sec:pixels}
185
186 Pixels are defined as blocks of characters. Dots always represent transparent pixels, and spaces and line breaks always separate pixel rows. Then, other caracters encode different colors, depending on option \option{colors}.
187
188 Let us analyse the following example.
189
190 \begin{sidebyside}
191 \pixelart[
192 colors=RGB, tikz={scale=.4}
193 ]{
194 {yellow}GB
195 G.R
196 BR{}
197 }
198 \end{sidebyside}
199
200 \begin{itemize}
201 \item The first row \texttt{\{yellow\}GB} means: one yellow pixel, one green pixel, one blue pixel.
202 \item The second row \texttt{G.R} means: one green pixel, one transparent pixel, one red pixel.
203 \item The last row \texttt{BR\{\}} means: one blue pixel, one red pixel, one pixel using the default \pkg*{TikZ} color (that is, a \cs*{fill} command is used to draw this pixel, without any \option*{color} option, which means the default \pkg*{TikZ} color is used; see option \option{tikz}, page \ref{option:tikz}).
204 \end{itemize}
205
206 Note that:
207 \begin{itemize}
208 \item Line breaks and consecutive spaces are considered as a \emph{single} row separation. That is, the previous example could also have been written as \texttt{\{yellow\}B G.R\hspace{1cm}BR\{\}}.
209 \item New paragraph are not allowed inside a \marg{pixels} argument.
210 \item If rows do not have the same lenght (the same number of pixels), transparent pixels are added at the end of the small rows.
211 \end{itemize}
212
213 Examples for the previous corner cases are given in section \ref{sec:corner}.
214
215 Most of commands are expanded \emph{before} being passed as an argument to \cs*{pixelart}, so it is possible to use commands inside a \cs*{pixelart}\marg{pixels} argument. See section \ref{sec:commands} for an example.
216
217 \subsection{Colors}
218 \label{sec:colors}
219
220 In a \cs{pixelart} command, pixel colors can be defined explicitely, or using keys/values.
221
222 \begin{description}
223 \item[Explicit] Any text surrounded by braces is transmitted as-is to the underlying \env*{tikzpicture}. That way, you can use anything you would use with \pkg*{TikZ} (which itself uses \pkg{xcolor}): \texttt{red}, \texttt{red!20}, \texttt{red!20!purple}, any user-defined color, or \texttt{\{\}}, which does not give any \option*{color} argument to the \cs*{fill} command used to draw this pixel, thus using default \pkg*{TikZ} color (see option \option{tikz}, page \pageref{option:tikz}).
224 \item[Key/Value] Any alphanumeric character (\texttt{a} to \texttt{z}, \texttt{A} to \texttt{Z}, \texttt{0} to \texttt{9}) not surrounded by braces is a key, which encodes the corresponding color defined in the \option{colors} argument. For instance, if \option{colors} is given as \texttt{colors=\{R=\{red\},G=\{green\}\}}, then, having \texttt{RG} in the \marg{pixels} argument is equivalent to \texttt{\{red\}\{green\}}.
225
226 Using non-alphanumeric characters as keys of \option{colors} is not supported: it might work, but it is an undefined behaviour.
227 \end{description}
228
229 The following examples illustrates this option.
230
231 \begin{itemize}
232 \item Key/values:
233 \begin{sidebyside}
234 \pixelart[
235 colors={R=red, G=green, B=blue}
236 ]{
237 RG
238 GB
239 }
240 \end{sidebyside}
241 \item Explicit:
242 \begin{sidebyside}
243 \pixelart{
244 {cyan}{magenta}
245 {yellow}{black}
246 }
247 \end{sidebyside}
248 \item Mix:
249 \begin{sidebyside}
250 \pixelart[
251 colors={R=red, G=green, B=blue}
252 ]{
253 RG
254 {yellow}B
255 }
256 \end{sidebyside}
257 \end{itemize}
258
259 If you use the same setting several times, you can define it once for all using \cs{newpixelartcolors}.
260
261 \begin{commands}
262 \command{newpixelartcolors}[\marg{name}\marg{key/value}]
263 Once a color set has been defined, to use it, simply use its name as an argument to \option{colors} instead of the whole keys/values. See an example in \ref{example:newpixelartcolors}.
264 \begin{options}
265 \opt*{name} Name of your color set.
266 \opt*{key/value} Your color set, as keys/values.
267 \end{options}
268 \command{renewpixelartcolors}[\marg{name}\marg{key/value}]
269 The previous command will fail if a color set \marg{name} is already defined. This command will always succeed, whether a color set \marg{name} already exists or not.
270 \end{commands}
271
272 The following key/value settings are predefined (examples are given in \ref{example:predefinedcolors}).
273
274 \begin{description}
275 \item[\texttt{explicit} :] No keys/values: pixel colors have to be explicitely defined.
276 \begin{sourcecode}
277 \newpixelartcolors{explicit}{}
278 \end{sourcecode}
279
280 \item[\texttt{RGB} :] Define the primary colors red, green, blue, as well as black and white.
281 \begin{sourcecode}
282 \newpixelartcolors{RGB}{
283 R=red,
284 G=green,
285 B=blue,
286 W=white,
287 K=black
288 }
289 \end{sourcecode}
290
291 \item[\texttt{BW} :] Black and white.
292 \begin{sourcecode}
293 \newpixelartcolors{BW}{
294 0=white,
295 1=black,
296 }
297 \end{sourcecode}
298
299 \item[\texttt{gray} :] Gray scale: \texttt{0} is white, \texttt{9} is black, and digits \texttt{0} to \texttt{9} are a gray scale from white to black.
300 \begin{sourcecode}
301 \newpixelartcolors{gray}{
302 0=white,
303 1=white!89!black,
304 2=white!78!black,
305 3=white!67!black,
306 4=white!56!black,
307 5=white!44!black,
308 6=white!33!black,
309 7=white!22!black,
310 8=white!11!black,
311 9=black,
312 }
313 \end{sourcecode}
314
315 \item[\texttt{mono} :] Monochromatic: any character encodes the default TikZ color (black by default, may be changed with options \option{tikz} or \option{style}).
316 \begin{sourcecode}
317 \newpixelartcolors{mono}{
318 a={},
319 b={},
320 c={},
321 % ...
322 9={},
323 }
324 \end{sourcecode}
325 \end{description}
326
327 \subsection{More about option \option*{squares}}
328 \label{sec:squares}
329
330 When using \option{squares}, each pixel is a separate colored square. Thus, artifacts can appear when viewing the document, as illustrated in figure \ref{fig:artifact}.
331
332 \begin{figure}
333 \centering
334 \includegraphics{artifacts}
335 \caption{Artifacts appearing with option \option*{squares} : the white lines should not exist.}
336 \label{fig:artifact}
337 \end{figure}
338
339 To remove those artifacts, you can
340 \begin{enumerate*}[label={(\arabic*)}]
341 \item use option \option{stack} instead (see section \ref{sec:stack}), or
342 \item use option \option{overlap}.
343 \end{enumerate*}
344
345 \begin{options}
346 \keyval-{overlap}{number} Assuming the square width is 1, \marg{number} is the size of the overlap: how much a square overlaps over the next one. With a positive number, the artifact (white line between two pixels) will disappear as the adjacent pixels are merged.
347
348 Note that using a negative value to \option{overlap} is also allowed, and will separate each pixel from its neighbour, giving a the look of a LCD screen.
349
350 See examples in section \ref{example:overlap}.
351 \end{options}
352
353 \subsection{More about option \option*{stack}}
354 \label{sec:stack}
355
356 If option \option{stack} is set, \pkg*{pixelart} tries to merge adjacent pixels of the same color, to draw them at once. Thus, it mostly remove the artifacts problem discussed with option \option*{squares} (although it may still occur).
357
358 Example in section \ref{example:stacksteps} shows how different color shapes are stacked onto each other to produce the pixel art.
359
360 \subsection{Which option: \option*{squares} or \option*{stack}?}
361 \label{sec:squaresstack}
362
363 Which option should you use: \option*{squares} or \option*{stack}?
364
365 To compare the different algorithms, three files have been compiled, each with one big pixel art command (see example \ref{example:benchmark}), with three different algorithms: outdated package \pkg*{pixelart0}, and options \option*{stack} and \option*{squares} of \pkg*{pixelart}. The result can be seen in figure \ref{fig:benchmark} (page \pageref{fig:benchmark}).
366
367 Unless you want to use option \option{overlap} of option \option{squares} (see section \ref{sec:squares}), you probably want to use option \option*{stack}:
368 \begin{itemize}
369 \item it is faster (see benchmark);
370 \item it produces smaller files (see benchmark);
371 \item it mostly remove artifacts.
372 \end{itemize}
373
374 Thus, the \option{stack} option is the default one used by \pkg*{pixelart}.
375
376 \begin{figure}
377 \centering
378
379 \subtable[File size (\si{kB})]{
380 \begin{tabular}{r*{3}{n{3}{1}}}
381 \toprule
382 &\multicolumn{3}{c}{Drawing}\\
383 & {mono} & {concentric} & {checker} \\
384 \midrule
385 \pkg*{pixelart0} & 243 & & \\
386 \pkg*{pixelart} \option*{stack} & 2.9 & 4.4 & 158 \\
387 \pkg*{pixelart} \option*{squares} & 245 & 263 & 252 \\
388 \bottomrule
389 \end{tabular}
390 }
391 \subtable[Compilation time (seconds)]{
392 \begin{tabular}{r*{3}{n{3}{1}}}
393 \toprule
394 &\multicolumn{3}{c}{Drawing}\\
395 & {mono} & {concentric} & {checker} \\
396 \midrule
397 \pkg*{pixelart0} & 38.7 & & \\
398 \pkg*{pixelart} \option*{stack} & 1.0 & 1.0 & 24.4 \\
399 \pkg*{pixelart} \option*{squares} & 19.9 & 28.3 & 27.1 \\
400 \bottomrule
401 \end{tabular}
402 }
403 \caption{Benchmark : \pkg*{pixelart0} vs. \option*{stack} vs \option*{squares}}
404 \label{fig:benchmark}
405 \end{figure}
406
407 \section{Default options}
408
409 You can use the following command to define options once for all.
410
411 \begin{commands}
412 \command{setpixelartdefault}[\marg{options}] Any options defined here will affect later \cs*{pixelart} or \cs*{tikzpixelart} commands, unless those options are explicitely set.
413
414 See example in section \ref{example:default}.
415 \end{commands}
416
417 \section{Logos}
418
419 If you want to credit \pkg*{pixelart} in a fancy way, you can use one of those logos. Apart from being gorgeous, they include a transparent text (so that they are searchable and copyable) and they scale with the current font size.
420
421 \begin{multicols}{2}
422 \begin{commands}
423 \command{pixelartlogo}
424 \pixelartlogo{}
425 Name and heart, in color.
426
427 \command{pixelartheart}
428 \pixelartheart{}
429 Heart only, in color.
430
431 \command{pixelartname}
432 \pixelartname{}
433 Name only, in color.
434
435 \command{pixelartlogobw}
436 \pixelartlogobw{}
437 Name and heart, black and white.
438
439 \command{pixelartheartbw}
440 \pixelartheartbw{}
441 Heart only, black and white
442
443 \command{pixelartnamebw}
444 \pixelartnamebw{}
445 Name only, black and white.
446 \end{commands}
447 \end{multicols}
448
449 Note that those logos are affected by \cs{setpixelartdefault}, so, if you have used this command in your document, you might want to call \cs*{setpixelartdefault}\marg{} to reset the default options before drawing any logo.
450
451 \section{Debugging}
452
453 What if drawing your pixel art throws an error?
454
455 \begin{enumerate}
456 \item Standard output prints one \texttt{\% pixelart 2, file ./foo.tex, input line 19} per \cs*{pixelart} or \cs*{tikzpixelart} command. If compilation failed right after this line, look at the given file: the \cs*{pixelart} command might be wrong.
457 \item If you do not see the problem, set debug mode on.
458
459 \begin{multicols}{2}
460 \begin{commands}
461 \command{setpixelartdebugon} Set debug on.
462 \command{setpixelartdebugoff} Set debug off.
463 \end{commands}
464 \end{multicols}
465
466 Using those commands, the following piece of information will be logged:
467
468 \begin{itemize}
469 \item the parsed options of \cs*{pixelart} and \cs*{tikzpixelart};
470 \item the \marg{pixels} argument of those commands;
471 \item the \pkg*{tikz} commands used to draw the picture;
472 \item and maybe some other stuff I forgot.
473 \end{itemize}
474
475 Note that you can have as many \cs*{setpixelartdebugon} and \cs*{setpixelartdebugoff} commands as you want, even if debug is already on or off.
476
477 A good idea is to copy the \pkg*{tikz} commands that are logged (those are the commands used to draw the pixel art), and paste them in a new file. Try to compile it. Are some of your arguments at fault? Bad value for the \option{tikz} option can produce faulty \pkg*{tikz} code.
478 \item Still no idea why your \cs*{pixelart} command fails? Seek help on your usual places, or report a bug.
479 \end{enumerate}
480
481 \appendix
482 \part{Appendix}
483
484 \section{Examples}
485 \label{sec:examples}
486
487 \subsection{Corner cases of \cs*{pixelart}\marg{pixels} argument}
488 \label{sec:corner}
489
490 \setpixelartdefault{tikz={scale=.3}}
491 \begin{itemize}
492 \item Line breaks and multiple spaces are considered as a \emph{single} row separation.
493 \begin{sidebyside}
494 \pixelart{
495 1.1
496 .1.
497 1.1
498 }
499 \pixelart{
500 1.1 .1.
501 1.1
502 }
503 \end{sidebyside}
504 \item Multiple line breaks (new paragraphs) are not supported: at best, they do not give the expected result; at worst, compilation will fail.
505 \begin{sidebyside}
506 \pixelart{
507 .1
508 1.
509 }
510 \pixelart{
511 .1
512
513 1.
514 }
515 \end{sidebyside}
516 \item Empty pixels are automatically added at the end of shorter lines.
517 \begin{sidebyside}
518 \pixelart{
519 1
520 .1
521 1.1
522 }
523 \pixelart{
524 1..
525 .1.
526 1.1
527 }
528 \end{sidebyside}
529 \end{itemize}
530
531 \subsection{Commands inside \cs*{pixelart}\marg{pixels} argument}
532 \label{sec:commands}
533
534 If we are too lazy to repeat every single pixel to draw a checker board, we can use commands.
535
536 \setpixelartdefault{tikz={scale=.2}}
537 \begin{enumerate}[label={Example \arabic*:}]
538 \item Each couple of lines is repetead four times.
539
540 \begin{sidebyside}
541 \newcommand{\twolines}{
542 .1.1.1.1 1.1.1.1.%
543 }
544 \pixelart{
545 \twolines
546 \twolines
547 \twolines
548 \twolines
549 }
550 \end{sidebyside}
551
552 \item \cs*{foreach} outside \cs*{pixelart}
553
554 \begin{sidebyside}
555 \gdef\board{}
556 \gdef\line{1}
557 \foreach \j in {1, ..., 3}{
558 \xdef\line{\line.1}
559 }
560 \foreach \i in {1, ..., 4}{
561 \xdef\board{%
562 \board
563 \line.
564 .\line.
565 }
566 }
567 \pixelart{\board}
568 \end{sidebyside}
569
570 \item I do not understand \LaTeX{} enough to explain why, however, \cs*{foreach} inside a \cs*{pixelart} does not work.
571
572 \begin{example}[code-only=true]
573 \pixelart{
574 \foreach \i in {1, ..., 8}{
575 1\foreach \j in {1, ..., 3}{.1}.
576 \foreach \j in {1, ..., 3}{.1}.1
577 }
578 }
579 \end{example}
580 \end{enumerate}
581
582 \subsection{Define new color sets: \cs*{newpixelartcolors}}
583 \label{example:newpixelartcolors}
584
585 \setpixelartdefault{tikz={scale=.3}}
586 \begin{itemize}
587 \item Colors may be defined in the \option{colors} option
588 \begin{example}
589 \definecolor{purple1}{RGB}{247, 176, 207}
590 \definecolor{purple2}{RGB}{238, 33, 120}
591 \definecolor{purple3}{RGB}{214, 45, 117}
592 \definecolor{purple4}{RGB}{217, 25, 92}
593 \definecolor{purple5}{RGB}{173, 29, 69}
594 \pixelart[colors={
595 1=purple1, 2=purple2, 3=purple3, 4=purple4, 5=purple5,
596 }]{
597 .54.43.
598 4224215
599 3445435
600 .52424.
601 ..434..
602 ...2...
603 }
604 \end{example}
605
606 \item Colors may be defined using \cs{newpixelartcolors}
607 \begin{example}
608 \definecolor{purple1}{RGB}{247, 176, 207}
609 \definecolor{purple2}{RGB}{238, 33, 120}
610 \definecolor{purple3}{RGB}{214, 45, 117}
611 \definecolor{purple4}{RGB}{217, 25, 92}
612 \definecolor{purple5}{RGB}{173, 29, 69}
613 \newpixelartcolors{purple}{
614 1=purple1, 2=purple2, 3=purple3, 4=purple4, 5=purple5,
615 }
616 \pixelart[colors=purple]{
617 .54.43.
618 4224215
619 3445435
620 .52424.
621 ..434..
622 ...2...
623 }
624 \end{example}
625 \end{itemize}
626
627 \subsection{Predefined color sets}
628 \label{example:predefinedcolors}
629
630 \begin{description}
631 \item[mono]~
632 \begin{sidebyside}
633 \pixelart[colors=mono, tikz={red, scale=.3}]{
634 ..01..23..
635 .456789ab.
636 cdefghijkl
637 mnopqrstuv
638 wxyzABCDEF
639 .GHIJKLMN.
640 ..OPQRST..
641 ...UVWX...
642 ....YZ....
643 }
644 \end{sidebyside}
645 \item[gray]~
646 \begin{sidebyside}
647 \pixelart[colors=gray, tikz={scale=.3}]{
648 987654
649 876543
650 765432
651 654321
652 543210
653 43210.
654 }
655 \end{sidebyside}
656 \item[BW]~
657 \begin{sidebyside}
658 \pixelart[colors=BW, tikz={scale=.3}]{
659 01010101
660 10101010
661 01010101
662 10101010
663 01010101
664 10101010
665 01010101
666 10101010
667 }
668 \end{sidebyside}
669 \item[RGB]~
670 \begin{sidebyside}
671 \pixelart[colors=RGB, tikz={scale=.1}]{
672 .....................KKKKKKK
673 .RRR...GG..BBB..K..K.KWKKKWK
674 .R..R.G..G.B..B.K.K..KWKKKWK
675 .RRR..G....BBB..KK...KWKKKWK
676 .R.R..G.GG.B..B.K.K..KWKWKWK
677 .R..R.G..G.B..B.K..K.KWKWKWK
678 .R..R..GG..BBB..K..K.KKWKWKK
679 .....................KKKKKKK
680 }
681 \end{sidebyside}
682 \end{description}
683
684 \subsection{Option \option*{draft}}
685 \label{example:draft}
686
687 \begin{sidebyside}
688 \setpixelartdefault{tikz={scale=.3}}
689 \pixelart[colors=RGB]{
690 ..RR..RR..
691 .RRRRRRRR.
692 RRRRRRRRRR
693 RRRRRRRRRR
694 RRRRRRRRRR
695 .RRRRRRRR.
696 ..RRRRRR..
697 ...RRRR...
698 ....RR....
699 }
700
701 \pixelart[colors=RGB, draft]{
702 ..RR..RR..
703 .RRRRRRRR.
704 RRRRRRRRRR
705 RRRRRRRRRR
706 RRRRRRRRRR
707 .RRRRRRRR.
708 ..RRRRRR..
709 ...RRRR...
710 ....RR....
711 }
712 \end{sidebyside}
713
714 \subsection{Option \option*{style}}
715 \label{example:style}
716
717 \setpixelartdefault{colors=mono}
718
719 \begin{sidebyside}
720 \pixelart{
721 .1
722 1.
723 }
724 \end{sidebyside}
725
726 \begin{sidebyside}
727 \pixelart[tikz={pixelart/.style={red}}]{
728 .1
729 1.
730 }
731 \end{sidebyside}
732
733 \begin{sidebyside}
734 \tikzset{pixelart/.style={blue, draw=orange, very thick, rounded corners=5}}
735 \pixelart{
736 .1
737 1.
738 }
739 \end{sidebyside}
740
741 \begin{sidebyside}
742 \pixelart[tikz={pixelart/.style={green}}]{
743 .1
744 1.
745 }
746 \end{sidebyside}
747
748 \begin{sidebyside}
749 \tikzset{myfancystyle/.style={yellow}}
750 \pixelart[style=myfancystyle]{
751 .1
752 1.
753 }
754 \end{sidebyside}
755
756 A more complex example.
757
758 \begin{sidebyside}
759 \tikzset{pixelart/.style={cyan, very thick, draw=black, rounded corners=5}}
760 \pixelart[squares={overlap=-.2}, colors=mono, tikz={scale=.5}, margin=.1]{
761 1..1.1..1
762 1..1....1
763 1111.1..1
764 1..1.1...
765 1..1.1..1
766 }
767 \end{sidebyside}
768
769 \subsection{Option \option*{tikz}}
770 \label{example:tikz}
771
772 \begin{sidebyside}
773 \pixelart[stack, colors={Y=yellow, K=black}, tikz={scale=.5, rounded corners=5}]{
774 ..YYYY..
775 .YYYYYY.
776 YYKYYKYY
777 YYYYYYYY
778 YKYYYYKY
779 YYKKKKYY
780 .YYYYYY.
781 ..YYYY..
782 }
783 \end{sidebyside}
784
785 \subsection{Drawing steps with the \option*{stack} option}
786 \label{example:stacksteps}
787
788 Here is how an image is built with the \option{stack} option: each of the following steps is a \cs*{fill} command with carefully crafted shape. Those filled area are \enquote{stacked} on each other, to produce the expected result.
789
790 Line per line, the algorithm checks if the pixels have been drawn yet. In the following steps, the gray cross marks the first pixel that was not drawn yet, that triggered a new \cs*{fill} command.
791
792 \centering
793 %\pixelart[stack, colors=RGB]{
794 % BBBBBBBBBBBBB
795 % BRRRBRRRBRRRB
796 % BRBRBRBRBRBBB
797 % BRRRBRRRBRBBB
798 % BRBRBRBRBRBBB
799 % BRBRBRRRBRRRB
800 % BBBBBBBBBBBBB
801 %}
802 \begin{tabular}{*{3}{c}}
803 \begin{tikzpicture}[scale=0.3]
804 \fill[color=blue] (1, 1) -- (1, 8) -- (14, 8) -- (14, 1) -- cycle ;
805 \draw[very thick, gray] (1.1, 1.1) -- (1.9, 1.9) (1.1, 1.9) -- (1.9, 1.1);
806 \end{tikzpicture}&
807 \begin{tikzpicture}[scale=0.3]
808 \fill[color=blue] (1, 1) -- (1, 8) -- (14, 8) -- (14, 1) -- cycle ;
809 \fill[color=red] (2, 2) -- (2, 7) -- (5, 7) -- (5, 2) -- (4, 2) -- (4, 4) -- (3, 4) -- (3, 2) -- cycle ;
810 \draw[very thick, gray] (2.1, 2.1) -- (2.9, 2.9) (2.1, 2.9) -- (2.9, 2.1);
811 \end{tikzpicture}&
812 \begin{tikzpicture}[scale=0.3]
813 \fill[color=blue] (1, 1) -- (1, 8) -- (14, 8) -- (14, 1) -- cycle ;
814 \fill[color=red] (2, 2) -- (2, 7) -- (5, 7) -- (5, 2) -- (4, 2) -- (4, 4) -- (3, 4) -- (3, 2) -- cycle ;
815 \fill[color=red] (6, 2) -- (6, 7) -- (9, 7) -- (9, 2) -- cycle ;
816 \draw[very thick, gray] (6.1, 2.1) -- (6.9, 2.9) (6.1, 2.9) -- (6.9, 2.1);
817 \end{tikzpicture}\\
818 Step 1&Step 2&Step 3\\
819 \midrule
820 \begin{tikzpicture}[scale=0.3]
821 \fill[color=blue] (1, 1) -- (1, 8) -- (14, 8) -- (14, 1) -- cycle ;
822 \fill[color=red] (2, 2) -- (2, 7) -- (5, 7) -- (5, 2) -- (4, 2) -- (4, 4) -- (3, 4) -- (3, 2) -- cycle ;
823 \fill[color=red] (6, 2) -- (6, 7) -- (9, 7) -- (9, 2) -- cycle ;
824 \fill[color=red] (10, 2) -- (10, 7) -- (13, 7) -- (13, 6) -- (11, 6) -- (11, 3) -- (13, 3) -- (13, 2) -- cycle ;
825 \draw[very thick, gray] (10.1, 2.1) -- (10.9, 2.9) (10.1, 2.9) -- (10.9, 2.1);
826 \end{tikzpicture}&
827 \begin{tikzpicture}[scale=0.3]
828 \fill[color=blue] (1, 1) -- (1, 8) -- (14, 8) -- (14, 1) -- cycle ;
829 \fill[color=red] (2, 2) -- (2, 7) -- (5, 7) -- (5, 2) -- (4, 2) -- (4, 4) -- (3, 4) -- (3, 2) -- cycle ;
830 \fill[color=red] (6, 2) -- (6, 7) -- (9, 7) -- (9, 2) -- cycle ;
831 \fill[color=red] (10, 2) -- (10, 7) -- (13, 7) -- (13, 6) -- (11, 6) -- (11, 3) -- (13, 3) -- (13, 2) -- cycle ;
832 \fill[color=blue] (7, 3) -- (7, 4) -- (8, 4) -- (8, 3) -- cycle ;
833 \draw[very thick, gray] (7.1, 3.1) -- (7.9, 3.9) (7.1, 3.9) -- (7.9, 3.1);
834 \end{tikzpicture}&
835 \begin{tikzpicture}[scale=0.3]
836 \fill[color=blue] (1, 1) -- (1, 8) -- (14, 8) -- (14, 1) -- cycle ;
837 \fill[color=red] (2, 2) -- (2, 7) -- (5, 7) -- (5, 2) -- (4, 2) -- (4, 4) -- (3, 4) -- (3, 2) -- cycle ;
838 \fill[color=red] (6, 2) -- (6, 7) -- (9, 7) -- (9, 2) -- cycle ;
839 \fill[color=red] (10, 2) -- (10, 7) -- (13, 7) -- (13, 6) -- (11, 6) -- (11, 3) -- (13, 3) -- (13, 2) -- cycle ;
840 \fill[color=blue] (7, 3) -- (7, 4) -- (8, 4) -- (8, 3) -- cycle ;
841 \fill[color=blue] (3, 5) -- (3, 6) -- (4, 6) -- (4, 5) -- cycle ;
842 \draw[very thick, gray] (3.1, 5.1) -- (3.9, 5.9) (3.1, 5.9) -- (3.9, 5.1);
843 \end{tikzpicture}\\
844 Step 4&Step 5&Step 6\\
845 \begin{tikzpicture}[scale=0.3]
846 \fill[color=blue] (1, 1) -- (1, 8) -- (14, 8) -- (14, 1) -- cycle ;
847 \fill[color=red] (2, 2) -- (2, 7) -- (5, 7) -- (5, 2) -- (4, 2) -- (4, 4) -- (3, 4) -- (3, 2) -- cycle ;
848 \fill[color=red] (6, 2) -- (6, 7) -- (9, 7) -- (9, 2) -- cycle ;
849 \fill[color=red] (10, 2) -- (10, 7) -- (13, 7) -- (13, 6) -- (11, 6) -- (11, 3) -- (13, 3) -- (13, 2) -- cycle ;
850 \fill[color=blue] (7, 3) -- (7, 4) -- (8, 4) -- (8, 3) -- cycle ;
851 \fill[color=blue] (3, 5) -- (3, 6) -- (4, 6) -- (4, 5) -- cycle ;
852 \fill[color=blue] (7, 5) -- (7, 6) -- (8, 6) -- (8, 5) -- cycle ;
853 \draw[very thick, gray] (7.1, 5.1) -- (7.9, 5.9) (7.1, 5.9) -- (7.9, 5.1);
854 \end{tikzpicture}\\
855 Step 7\\
856 \bottomrule
857 \end{tabular}
858
859 \subsection{Option \option*{overlap}}
860 \label{example:overlap}
861
862 \begin{sidebyside}
863 \setpixelartdefault{tikz={scale=.3}}
864 \newcommand{\three}{
865 .111.
866 11.11
867 ...11
868 ...11
869 ..11.
870 ...11
871 ...11
872 11.11
873 .111.
874 }
875 \pixelart[squares={overlap=.1}]{
876 \three
877 }
878 \pixelart[squares={overlap=0}]{
879 \three
880 }
881 \pixelart[squares={overlap=-.1}]{
882 \three
883 }
884 \end{sidebyside}
885
886 \subsection{Command \cs*{tikzpixelart}}
887 \label{example:tikzpixelart}
888
889 \begin{sidebyside}
890 \begin{tikzpicture}
891 \fill[red] (0, 0) circle (1);
892 \tikzpixelart[tikz={color=green}]{(-1, -1)}{
893 1
894 .1
895 1.1
896 }
897 \end{tikzpicture}
898 \end{sidebyside}
899
900 \subsection{Pictures used for the benchmark}
901 \label{example:benchmark}
902
903 The benchmark discussed in section \ref{sec:squaresstack} (page \pageref{sec:squaresstack}) uses three files with three big \cs*{pixelart} commands. A small version of those commands is shown below.
904
905 \setpixelartdefault{colors=RGB, tikz={scale=.3}}
906 \begin{description}
907 \item[mono] Every single pixel of the same color.
908 \begin{sidebyside}
909 \pixelart{
910 KKKKKKKK
911 KKKKKKKK
912 KKKKKKKK
913 KKKKKKKK
914 KKKKKKKK
915 KKKKKKKK
916 KKKKKKKK
917 KKKKKKKK
918 }
919 \end{sidebyside}
920
921 \item[concentric] Cencentric squares, that is, several area with adjacent pixels of the same color.
922 \begin{sidebyside}
923 \pixelart{
924 GGGGGGGG
925 GKKKKKKG
926 GKGGGGKG
927 GKGRRGKG
928 GKGRRGKG
929 GKGGGGKG
930 GKKKKKKG
931 GGGGGGGG
932 }
933 \end{sidebyside}
934
935 \item[checker] A (kind of) checker board, where no two adjacent pixels have the same color.
936 \begin{sidebyside}
937 \pixelart{
938 RGRGRGRG
939 BKBKBKBK
940 RGRGRGRG
941 BKBKBKBK
942 RGRGRGRG
943 BKBKBKBK
944 RGRGRGRG
945 BKBKBKBK
946 }
947 \end{sidebyside}
948 \end{description}
949
950 \subsection{Default options}
951 \label{example:default}
952
953 \begin{sidebyside}
954 \setpixelartdefault{colors=mono, tikz={scale=.2, red}}
955
956 From now on, pixel art pictures will be small, and red:
957 \pixelart{1. .1}.
958
959 Excepted this one:
960 \pixelart[
961 tikz={scale=.4, blue}
962 ]{1. .1}.
963
964 Back to normal:
965 \pixelart{1. .1}.
966 \end{sidebyside}
967
968 \subsection{Option \option*{margin}}
969 \label{example:margin}
970
971 In the first picture, you can see that part of the orange line has been clipped away. In the second one, with option \option{margin} correctly set, it is not clipped away.
972
973 \begin{sidebyside}
974 \setpixelartdefault{squares}
975 \tikzset{pixelart/.style={
976 draw=orange,
977 rounded corners=5,
978 line width=5,
979 }}
980
981 \pixelart{11 11}
982
983 \pixelart[margin=.1]{11 11}
984 \end{sidebyside}
985
986 \section{Change History}
987
988 This is a raw copy of the \href{https://framagit.org/spalax/pixelart/-/blob/main/CHANGELOG.md}{\textsl{CHANGELOG.md}} file that can be found in the git repository of \pkg*{pixelart}.
989
990 \markdownInput{CHANGELOG.md}
991
992 \end{document}