Debian Codegraph @

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

raw
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %
3 % Documentation for the TikZbricks package
4 % A package to draw bricks with tikz
5 % Maintained by samcarter
6 %
7 % Project repository and bug tracker:
8 % https://github.com/samcarter/TikZbricks
9 %
10 % Released under the LaTeX Project Public License v1.3c or later
11 % See https://www.latex-project.org/lppl.txt
12 %
13 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
14 % arara: latexmk
15 \documentclass{scrartcl}
16
17 % meta %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18 \title{The \tikzbrick{}s package}
19 \subtitle{Drawing bricks with \TikZ}
20 \author{%
21 \texorpdfstring{
22 \begin{tikzpicture}
23 \brick[color=blue]{4}{2}
24 \end{tikzpicture}\\[0.8em]
25 \texttt{samcarter}\\
26 \url{https://github.com/samcarter/TikZbricks}\\
27 \url{https://www.ctan.org/pkg/tikzbricks}
28 }{samcarter}}
29 \date{Version v0.6 \textendash{} 2024/12/16}
30
31 \usepackage[
32 themecolor=samred
33 ]{\jobname-settings}
34
35 \colorlet{red}{samred}
36 \colorlet{blue}{samlblue}
37 \colorlet{orange}{samorange}
38 \colorlet{teal}{samteal}
39
40 \usepackage{tikzbricks}
41
42 % customisation %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
43 \setlength{\footheight}{50pt}
44 \pagestyle{scrheadings}
45 \pgfmathsetseed{10}
46 \cfoot{%
47 \pgfmathsetmacro{\R}{rnd}%
48 \pgfmathsetmacro{\G}{rnd}%
49 \pgfmathsetmacro{\B}{rnd}%
50 \definecolor{randomcol}{rgb}{\R,\G,\B}%
51 \begin{tikzpicture}[scale=0.5]
52 \brick[color=randomcol]{\thepage}{1}
53 \end{tikzpicture}
54 }
55
56 \begin{document}
57 \maketitle
58 \thispagestyle{scrheadings}
59
60 \section{Introduction}
61 \label{intro}
62
63 The idea for the \tikzbrick{}s package was born at the \href{https://tug.org/tug2021/}{TUG'21 conference}, at which one of the interviewees, John Hammersley, had a very cool collection of brick models in the background (\href{https://www.youtube.com/watch?v=-9_Iy5Fqr4E}{link to video}).
64
65 The package allows to draw bricks with \TikZ. The user can modify their colour, shape and change the viewpoint. Internally the \href{https://ctan.org/pkg/tikz-3dplot}{tikz-3dplot} package is used for the 3D rendering.
66
67 The package is included in both \texlive and \miktex and available from \CTAN (\url{https://ctan.org/pkg/tikzbricks}).
68 The development version of this package is located on github at \url{https://github.com/samcarter/TikZbricks}. If you have any problems, ideas or other feedback, please make constructive use of its bug tracker.
69
70 Copyright \raisebox{0.2em}{\tiny\fontfamily{cmr}\selectfont\textcopyright} \texttt{samcarter}. Permission is granted to copy, distribute and\slash or modify this software under the terms of the \href{https://www.latex-project.org/lppl.txt}{LaTeX project public licence, version 1.3c or later}.
71
72 \section{Basic usage}
73
74 An individual \tikzbrick can be drawn with
75 \begin{tcblisting}{title={\tikzbrick}}
76 \begin{tikzpicture}
77 \brick{4}{2}
78 \end{tikzpicture}
79 \end{tcblisting}
80 in which the first argument specifies the length of the block and the second argument its width.
81
82 In addition to this basic block, the user can customise the block via the following optional arguments (the value in parenthesis denotes the default value):
83 \begin{tcblisting}{title={Brick colour (red)}}
84 \begin{tikzpicture}
85 \brick[color=blue]{1}{3}
86 \end{tikzpicture}
87 \end{tcblisting}
88 \begin{tcblisting}{title={Front colour (color!60)}}
89 \begin{tikzpicture}
90 \brick[frontcolor=blue]{2}{1}
91 \end{tikzpicture}
92 \end{tcblisting}
93 \begin{tcblisting}{title={Top colour (color!40)}}
94 \begin{tikzpicture}
95 \brick[topcolor=blue]{2}{1}
96 \end{tikzpicture}
97 \end{tcblisting}
98 \begin{tcblisting}{title={Side colour (color)}}
99 \begin{tikzpicture}
100 \brick[sidecolor=blue]{2}{1}
101 \end{tikzpicture}
102 \end{tcblisting}
103 \begin{tcblisting}{title={Stud colour (color)}}
104 \begin{tikzpicture}
105 \brick[studcolor=blue]{2}{1}
106 \end{tikzpicture}
107 \end{tcblisting}
108 \begin{tcblisting}{title={Brick height (1.3)}}
109 \begin{tikzpicture}
110 \brick[brickheight=0.3]{2}{1}
111 \end{tikzpicture}
112 \end{tcblisting}
113 \begin{tcblisting}{title={Brick length (1)}}
114 \begin{tikzpicture}
115 \brick[bricklength=1.5]{2}{1}
116 \end{tikzpicture}
117 \end{tcblisting}
118 \begin{tcblisting}{title={Brick width (1)}}
119 \begin{tikzpicture}
120 \brick[brickwidth=2]{2}{1}
121 \end{tikzpicture}
122 \end{tcblisting}
123 \begin{tcblisting}{title={Stud radius (0.35)}}
124 \begin{tikzpicture}
125 \brick[studradius=0.2]{2}{1}
126 \end{tikzpicture}
127 \end{tcblisting}
128 \begin{tcblisting}{title={Stud height (0.3)}}
129 \begin{tikzpicture}
130 \brick[studheight=0.6]{2}{1}
131 \end{tikzpicture}
132 \end{tcblisting}
133 \begin{tcblisting}{title={Stud text ()}}
134 \begin{tikzpicture}
135 \brick[studtext={TikZ}]{2}{3}
136 \end{tikzpicture}
137 \end{tcblisting}
138 \begin{tcblisting}{title={Brick text ()}}
139 \begin{tikzpicture}
140 \brick[bricktext={TikZ}]{2}{3}
141 \end{tikzpicture}
142 \end{tcblisting}
143
144 All the above options are also available as package options to change the value for the whole document. The default colour can for example be specified like this:
145 \begin{tcolorbox}[title={Package options ()}]
146 \begin{samcode}
147 \documentclass{standalone}
148
149 \usepackage[color=blue]{tikzbricks}
150
151 \begin{document}
152
153 \begin{tikzpicture}
154 \brick{3}{2}
155 \end{tikzpicture}
156
157 \end{document}
158 \end{samcode}
159
160 \tcblower
161 \makeatletter
162 \def\brick@default@color{blue}
163 \makeatother
164 \begin{tikzpicture}
165 \brick{3}{2}
166 \end{tikzpicture}
167 \end{tcolorbox}
168
169 To change the viewpoint, one can make use of the fact, that the \texttt{tikz-3dplot} package is used internally. By default, the \tikzbrick{}s package uses \saminline|\tdplotsetmaincoords{70}{160}|, but this can be adjusted as desired:
170 \begin{tcblisting}{title={Viewpoint}}
171 \tdplotsetmaincoords{70}{110}
172 \begin{tikzpicture}
173 \brick{4}{2}
174 \end{tikzpicture}
175 \end{tcblisting}
176 Caveat: don't move away too far from the default viewpoint, otherwise the correct rendering of the brick is not guaranteed.
177
178 In addition to these \tikzbrick specific options, one can also use all normal Ti\emph{k}Z options:
179 \begin{tcblisting}{title={Ti\emph{k}Z options}}
180 \begin{tikzpicture}
181 \brick[scale=1.5]{1}{1}
182 \brick[xshift=3cm]{2}{2}
183 \end{tikzpicture}
184 \end{tcblisting}
185
186 \section{Wall building}
187
188 So what to do with the \tikzbrick{}s? Like with any other building blocks, they are made to build things. Using the \saminline|wall| environment one can place \saminline|\wallbrick| besides each other.
189
190 Due to the perspective and order of drawing, the wall is build from bottom to top and from right to left. To leave gaps or change into another layer, one can add to the \saminline|brickx|, \saminline|bricky| and \saminline|brickz| counters.
191
192 Inside the \saminline|wall| environment one can use \saminline|\newrow| as a shortcut to go one row up and back to the start at the right hand side.
193 \begin{tcblisting}{title={Wall building}}
194 \begin{wall}
195 \wallbrick[color=blue]{2}{1}
196 \wallbrick[color=red]{1}{1}
197 \addtocounter{brickx}{1}
198 \wallbrick[color=orange]{1}{1}
199 \newrow
200 \addtocounter{brickx}{1}{1}
201 \wallbrick[color=teal]{4}{1}
202 \end{wall}
203 \end{tcblisting}
204
205 \section{img2bricks (by @Scott Pakin)}
206
207 To make creating large structures easier, \href{https://github.com/spakin}{Scott Pakin} contributed the \saminline|img2bricks| python script, which converts image into \tikzbrick{}s. The script can be downloaded from \url{https://github.com/samcarter/TikZbricks/blob/main/img2bricks}.
208
209 The script can be executed with python:
210 \begin{tcolorbox}[righthand width=0cm,title={Usage}]
211 \begin{samcode}
212 python3 img2bricks image.png
213 \end{samcode}
214 \end{tcolorbox}
215
216 Additional options are
217 \begin{tcolorbox}[righthand width=0cm,title={Options}]
218 \begin{samcode}
219 -h, --help show an help message
220 --output LATEX-FILE, -o LATEX-FILE name of output file
221 --depth DEPTH depth of each brick
222 --widths NUM[,NUM] comma-separated list of allowable brick widths
223 \end{samcode}
224 \end{tcolorbox}
225
226 When preparing an image to convert into \tikzbrick{}s:
227 \begin{itemize}
228 \item consider using an image with transparent background so some of the edges of the bricks will be visible instead of just a solid wall
229 \item image formats like .png are best suitable to avoid artefacts from image compression
230 \item consider using small images with not too many pixels. Otherwise the resulting \tikzbrick wall gets very large and might not be compilable (Lua\TeX{} is a bit more lenient, but can't do wonders, either)
231 \end{itemize}
232
233 \section{Example}
234
235 One example inspired by the documentation of the \href{https://www.ctan.org/pkg/pxpic}{pxpic package}:
236
237 \begin{tcblisting}{
238 title={Brick Duck},
239 text above listing,
240 sidebyside=false,
241 breakable,
242 righthand width=0cm,
243 }
244 \begin{wall}[scale=0.5]
245 \addtocounter{brickx}{3}
246 \wallbrick[color=yellow!80!orange]{6}{2}
247 \newrow
248 \addtocounter{brickx}{2}
249 \wallbrick[color=yellow!80!orange]{8}{2}
250 \newrow
251 \addtocounter{brickx}{1}
252 \wallbrick[color=yellow!80!orange]{3}{2}
253 \addtocounter{brickx}{4}
254 \wallbrick[color=yellow!80!orange]{3}{2}
255 \newrow
256 \addtocounter{brickx}{1}
257 \wallbrick[color=yellow!80!orange]{2}{2}
258 \addtocounter{brickx}{1}
259 \wallbrick[color=yellow!80!orange]{4}{2}
260 \addtocounter{brickx}{1}
261 \wallbrick[color=yellow!80!orange]{3}{2}
262 \newrow
263 \addtocounter{brickx}{1}
264 \wallbrick[color=yellow!80!orange]{8}{2}
265 \addtocounter{brickx}{1}
266 \wallbrick[color=yellow!80!orange]{2}{2}
267 \newrow
268 \addtocounter{brickx}{2}
269 \wallbrick[color=yellow!80!orange]{11}{2}
270 \newrow
271 \addtocounter{brickx}{3}
272 \wallbrick[color=yellow!80!orange]{7}{2}
273 \addtocounter{brickx}{1}
274 \wallbrick[color=yellow!80!orange]{2}{2}
275 \newrow
276 \addtocounter{brickx}{1}
277 \wallbrick[color=orange]{3}{2}
278 \wallbrick[color=yellow!80!orange]{3}{2}
279 \addtocounter{brickx}{5}
280 \wallbrick[color=yellow!80!orange]{1}{2}
281 \newrow
282 \wallbrick[color=orange]{3}{2}
283 \wallbrick[color=yellow!80!orange]{5}{2}
284 \newrow
285 \addtocounter{brickx}{2}
286 \wallbrick[color=orange]{1}{2}
287 \wallbrick[color=yellow!80!orange]{1}{2}
288 \wallbrick[color=black]{1}{2}
289 \wallbrick[color=yellow!80!orange]{3}{2}
290 \newrow
291 \addtocounter{brickx}{2}
292 \wallbrick[color=yellow!80!orange]{6}{2}
293 \newrow
294 \addtocounter{brickx}{3}
295 \wallbrick[color=yellow!80!orange]{4}{2}
296 \end{wall}
297 \end{tcblisting}
298
299 \end{document}