summaryrefslogtreecommitdiff
path: root/graphics/pgf/contrib/tikzbricks/tikzbricks-doc.tex
blob: f9b8d07b8bc1a7c674cc7f55e98a9a0801fd8c50 (plain)
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
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Documentation for the tikzbricks package
% A package to draw tikzbricks pieces with tikz
% Maintained by samcarter
%
% Project repository and bug tracker:
% https://github.com/samcarter/TikZbricks
%
% Released under the LaTeX Project Public License v1.3c or later
% See http://www.latex-project.org/lppl.txt
%
% Version 0.1
% Aug 10, 2021  
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass[parskip=half]{scrartcl}

% packages %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage[T1]{fontenc}	
\usepackage[utf8]{inputenc}		
\usepackage[english]{babel}
\usepackage[bitstream-charter]{mathdesign}
\usepackage{tikzbricks}
\usepackage[most]{tcolorbox}
\usepackage[paper=a4paper,margin=2.9cm]{geometry}
\usepackage{url}
\usepackage{xspace}
\usepackage{scrlayer-scrpage} 
\usepackage[hang,flushmargin,bottom]{footmisc}
\usepackage[colorlinks=true,breaklinks=true,urlcolor=duckblue,linkcolor=duckblue,citecolor=duckblue,filecolor=duckblue]{hyperref}

% macros %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newcommand{\CTAN}{\textsc{CTAN}\xspace}
\newcommand{\TikZ}{Ti\emph{k}Z\xspace}
\newcommand{\miktex}{MiK\TeX\xspace}
\newcommand{\texlive}{\TeX{}Live\xspace}
\newcommand{\tikzbrick}{Ti\emph{k}Zbrick\xspace}

% customisation %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\definecolor{duckblue}{RGB}{0,70,140}
\definecolor{marmotred}{RGB}{140,20,40}
\addtokomafont{sectioning}{\color{gray}}
\addtokomafont{date}{\normalsize}
\addtokomafont{author}{\normalsize}
\setlength{\footnotemargin}{0.7em}

% from https://tex.stackexchange.com/a/147848
\def\beginlstdelim#1#2#3%
{%
    \def\endlstdelim{#2\egroup}%
    \ttfamily#1\bgroup\color{#3}\aftergroup\endlstdelim%
}

\lstdefinestyle{tikzbricksstyle}{%
	language={[latex]TeX},
	tabsize=2,
	breaklines,
	basicstyle=\footnotesize\ttfamily,
	commentstyle={\color{gray}\slshape}, 
	columns=fullflexible,
	texcsstyle=*\color{duckblue}\bfseries,
	keywordstyle=\color{red!60!black}\bfseries,
	morekeywords={tikzpicture,scope,wall},
	moretexcs={path,node,draw,clip,includegraphics,color,brick,tdplotsetmaincoords,wallbrick,newrow},
	delim ={[s][\ttfamily\color{green!50!black}]{$}{$}},
	moredelim=[is][\footnotesize\ttfamily\color{orange!70!black}]{|}{|},
	moredelim={[s][\color{gray}]{<}{>}},
%	moredelim = **[is][\beginlstdelim{\{}{\}}{orange!70!black}]{\{}{\}},
%	moredelim = **[is][\beginlstdelim{[}{]}{orange!70!black}]{[}{]},
}

\tcbset{%
	colframe=gray,
	arc=2mm,
	fonttitle=\bfseries,
	sidebyside,
	listing options={style=tikzbricksstyle},
	center lower,
	righthand width=5.7cm,
	bottom=0pt, 
	top=0pt,
	sidebyside gap=10pt
}

\lstset{style=tikzbricksstyle}

% meta %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\title{The \tikzbrick{}s package}
\subtitle{Drawing bricks with \TikZ}
\author{%
	\texorpdfstring{
		\begin{tikzpicture}
			 \brick[color=blue]{4}{2}
		\end{tikzpicture}\\[0.8em]		
		\texttt{samcarter}\\
		\url{https://github.com/samcarter/TikZbricks}\\
%		\url{https://www.ctan.org/pkg/tikzbricks}
	}{samcarter}}
\date{Version 0.1 -- \today}

\begin{document}
\maketitle

\section{Introduction}
\label{intro}

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 had a very cool collection of brick models in the background. % todo: link to video once this is available

The package allows to draw bricks with \TikZ. The user can modify their colour, shape and change the viewpoint. Internally the \texttt{tikz-3dplot} package is used for the 3D rendering. 

%The package is included in both \texlive and \miktex and available from \CTAN (\url{https://ctan.org/pkg/tikzbricks}). 
The development version of this package is located at \url{https://github.com/samcarter/TikZbricks}. If you have any problems, ideas or other feedback, please make constructive use of its bug tracker.

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 LaTeX project public licence, version 1.3c or later \url{http://www.latex-project.org/lppl.txt}.

\section{Basic usage}

An individual \tikzbrick can be drawn with

\begin{tcolorbox}[title={\tikzbrick}]
\begin{lstlisting}
\brick{4}{2}
\end{lstlisting}
\tcblower
\begin{tikzpicture}
	 \brick{4}{2}
\end{tikzpicture}
\end{tcolorbox}

in which the first argument specifies the length of the block and the second argument its width. In addition to this basic block, the user can customise the block via optional arguments.

\newpage

The package comes with a couple of build in options. First the user can adjust the colour:
\begin{tcblisting}{title={Colour}}
\begin{tikzpicture}
	 \brick[color=blue]{1}{3}
\end{tikzpicture}
\end{tcblisting}

It is also possible to change the default height of 1.3 to a custom value:
\begin{tcblisting}{title={Height}}
\begin{tikzpicture}
	 \brick[brickheight=0.3]{2}{1}
\end{tikzpicture}
\end{tcblisting}

And on top of the studs, a custom text can be added:
\begin{tcblisting}{title={Height}}
\begin{tikzpicture}
	 \brick[studtext={TikZ}]{2}{3}
\end{tikzpicture}
\end{tcblisting}

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 \lstinline|\tdplotsetmaincoords{70}{160}|, but this can be adjusted as desired:
\begin{tcblisting}{title={Viewport}}
\tdplotsetmaincoords{70}{110}
\begin{tikzpicture}
\brick{4}{2}
\end{tikzpicture}
\end{tcblisting}

In addition to these \tikzbrick specific options, one can also use all normal Ti\emph{k}Z options:
\begin{tcblisting}{title={Ti\emph{k}Z options}}
\begin{tikzpicture}
\brick[scale=1.5]{1}{1}
\brick[xshift=3cm]{2}{2}
\end{tikzpicture}
\end{tcblisting}

\section{Wall building}

So what to do with the \tikzbrick{}s? Like with any other building blocks, they are made to build things. Using the \lstinline|wall| environment one can place \lstinline|\wallbrick| besides each other. 

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 \lstinline|brickx|, \lstinline|bricky| and \lstinline|brickz| counters. 

Inside the \lstinline|wall| environment one can use \lstinline|\newrow| as a shortcut to go one row up and back to the start at the right hand side. 
\begin{tcblisting}{title={Wall building}}
\begin{wall}
  \wallbrick[color=blue]{2}{1}
  \wallbrick[color=red]{1}{1}
  \addtocounter{brickx}{1}
  \wallbrick[color=orange]{1}{1}
  \newrow
  \addtocounter{brickx}{1}{1}
  \wallbrick[color=cyan]{4}{1}
\end{wall}
\end{tcblisting}

\section{Example}

One example inspired by the documentation of the  \href{https://www.ctan.org/pkg/pxpic}{pxpic package}:

%\begin{tcblisting}{title={Brick Duck}}
\begin{center}
\begin{wall}[scale=0.5]
  \addtocounter{brickx}{3}
  \wallbrick[color=yellow!80!orange]{6}{2}
  \newrow
  \addtocounter{brickx}{2}
  \wallbrick[color=yellow!80!orange]{8}{2}   
  \newrow
  \addtocounter{brickx}{1}
  \wallbrick[color=yellow!80!orange]{3}{2} 
  \addtocounter{brickx}{4}
  \wallbrick[color=yellow!80!orange]{3}{2}  
  \newrow
  \addtocounter{brickx}{1}
  \wallbrick[color=yellow!80!orange]{2}{2} 
  \addtocounter{brickx}{1}
  \wallbrick[color=yellow!80!orange]{4}{2}      
  \addtocounter{brickx}{1}
  \wallbrick[color=yellow!80!orange]{3}{2}  
  \newrow
  \addtocounter{brickx}{1}
  \wallbrick[color=yellow!80!orange]{8}{2} 
  \addtocounter{brickx}{1}
  \wallbrick[color=yellow!80!orange]{2}{2}  
  \newrow
  \addtocounter{brickx}{2}
  \wallbrick[color=yellow!80!orange]{11}{2} 
  \newrow
  \addtocounter{brickx}{3}
  \wallbrick[color=yellow!80!orange]{7}{2} 
  \addtocounter{brickx}{1}
  \wallbrick[color=yellow!80!orange]{2}{2} 
  \newrow
  \addtocounter{brickx}{1}
  \wallbrick[color=orange]{3}{2} 
  \wallbrick[color=yellow!80!orange]{3}{2} 
  \addtocounter{brickx}{5}
  \wallbrick[color=yellow!80!orange]{1}{2}   
  \newrow
  \wallbrick[color=orange]{3}{2} 
  \wallbrick[color=yellow!80!orange]{5}{2}   
  \newrow
  \addtocounter{brickx}{2}
  \wallbrick[color=orange]{1}{2} 
  \wallbrick[color=yellow!80!orange]{1}{2} 
  \wallbrick[color=black]{1}{2} 
  \wallbrick[color=yellow!80!orange]{3}{2}   
  \newrow   
  \addtocounter{brickx}{2}
  \wallbrick[color=yellow!80!orange]{6}{2} 
  \newrow
  \addtocounter{brickx}{3}
  \wallbrick[color=yellow!80!orange]{4}{2}      
\end{wall}
\end{center}
%\end{tcblisting}

\end{document}