Debian Codegraph @

texmf-dist/doc/latex/lua-tikz3dtools/lua-tikz3dtools-doc.tex

raw
1 \documentclass[letterpaper]{article}
2
3 \usepackage{microtype}
4 \usepackage{mathtools}
5 \usepackage{unicode-math}
6 \usepackage{booktabs}
7
8 \usepackage{lua-tikz3dtools}
9
10 \title{lua-tikz3dtools documentation v3.3.0}
11 \author{Jasper Nice}
12 \date{2026-05-24}
13
14 \begin{document}
15
16 \maketitle
17 \tableofcontents
18
19 \section{Introduction}
20
21 Hi! My name is Jasper, and before I get started with this manual,
22 I wanted to share a bit about where it came from, and where it is going.
23 This is because, like anyone, I make mistakes, and I made quite a few
24 here along the way. I want to acknowledge that openly, so no one is misled,
25 and so that people can have the greatest benefit from this.
26
27 Much of the mistakes were the byproduct of a premature release of the
28 software before it was complete. I have now finished what I believe are the
29 core components of the software. I'm sorry for having the incomplete work up for so long.
30
31 I'd really recommend taking a look at the packages luadraw, or Asymptore
32 if anyone is interested in a contemporary \LaTeX{} 3D illustration softwares.
33
34 This package---lua-tikz3dtools---is geared strongly towards expressing
35 everything in terms of parametric affine/projective algebra.
36 Sounds fancy, but it is really the backbone of a lot of seemingly incoherent
37 elements.
38
39 For instance, rotation, translation, perspective, shearing, and reflection
40 are all projective transformations. And they can be composed!
41
42 Of course, everything eventually boils down to affine algebra after the
43 transformations, as they map affine space onto itself, resulting in
44 affine-workable byproducts. This is a bit abstract, but it is the reason
45 you can look at a perspective picture on your screen, while your screen never
46 changes its basis (orientation, direction, size, and shape).
47
48 This package also takes care of occlusion and partitioning, with results
49 akin to those of a BSP tree.
50
51 \section{Command reference}
52
53 \subsection{ltdtappendlabel}
54 This command appends a label. Its keys are
55 \begin{itemize}
56 \item v: a homogeneous 3D vector (e.g.,
57 \verb|Vector:new{1,2,3,1}|).
58 \item text: a \LaTeX{} label (e.g., \verb|\LaTeX|).
59 \item transformation: A homogeneous 3D transformation matrix.
60 \item filter: A boolean on v.
61 \end{itemize}
62 \begin{figure}
63 \centering
64 \begin{tikzpicture}
65 \ltdtappendlabel[
66 v={return Vector:new{0,0,0,1}},
67 text={\LaTeX},
68 transformation={return Matrix.identity()},
69 filter={return A[1]<10}% true
70 ]
71 \draw (-1,-1) rectangle (1,1);
72 \ltdtdisplaysimplices
73 \end{tikzpicture}
74 \caption{ltdtappendlabel}
75 \end{figure}
76
77 \subsection{ltdtappendlight}
78 This command appends a light direction. I recommend using only one light
79 direction, unless you have a good reason not to.
80 \begin{itemize}
81 \item v: a homogeneous 3D vector
82 \end{itemize}
83 \begin{figure}
84 \centering
85 \begin{tikzpicture}
86 \ltdtappendlight[
87 v={return Vector:new{1,1,1,1}}
88 ]
89 \ltdtappendsurface[
90 v={return Vector.sphere(Vector:new{u,v,2})},
91 transformation={return Matrix.zyzrotation(Vector:new{pi/6,pi/3,pi/2})},
92 fill options={return "fill=ltdtbrightness,fill opacity=0.7"},
93 uparams={return Vector:new{0,tau,10}},
94 vparams={return Vector:new{0,pi,7}}
95 ]
96 \ltdtdisplaysimplices
97 \end{tikzpicture}
98 \caption{ltdtappendlight}
99 \end{figure}
100
101 \subsection{ltdtappendcurve}
102 This command appends a curve.
103 \begin{itemize}
104 \item uparams: A 3-vector of start, stop and step in u
105 \item v: a homogeneous 3D vector
106 \item transformation: A homogeneous 3D transformation matrix.
107 \item draw options: a string of Ti\textit{k}Z options for a path.
108 \item arrow tip: a string of Ti\textit{k}Z options for a path.
109 \item arrow scale: a number to change the arrow's size
110 \item filter: A boolean on v.
111 \end{itemize}
112 \begin{figure}
113 \centering
114 \begin{tikzpicture}
115 \ltdtappendcurve[
116 v={return Vector.sphere(Vector:new{u,u,2})},
117 transformation={return Matrix.zyzrotation(Vector:new{pi/6,pi/3,pi/2})},
118 draw options={return "draw"},
119 uparams={return Vector:new{0,tau,30}},
120 ]
121 \ltdtdisplaysimplices
122 \end{tikzpicture}
123 \caption{ltdtappendcurve}
124 \end{figure}
125
126 \subsection{ltdtappendsurface}
127 This command appends a surface.
128 \begin{itemize}
129 \item uparams: A 3-vector of start, stop and step in u
130 \item vparams: A 3-vector of start, stop and step in v
131 \item v: a homogeneous 3D vector
132 \item transformation: A homogeneous 3D transformation matrix.
133 \item fill options: a string of Ti\textit{k}Z options for a path.
134 \item filter: A boolean on v.
135 \item curve: If you know what you're doing, you can embed a table of UV
136 line segments within a surface's simplices. See the example below.
137 \end{itemize}
138 \begin{figure}
139 \centering
140 \begin{tikzpicture}
141 \ltdtappendlight[
142 v={return Vector:new{1,1,1,1}}
143 ]
144 \ltdtappendsurface[
145 v={return Vector.sphere(Vector:new{u,v,1}):hadd(Vector:new{2*cos(u),2*sin(u),0,1})},
146 transformation={return Matrix.zyzrotation(Vector:new{pi/6,pi/3,pi/2})},
147 fill options={return "fill=ltdtbrightness,fill opacity=0.7"},
148 uparams={return Vector:new{0,tau,10}},
149 vparams={return Vector:new{0,tau,7}},
150 curve={
151 local tab = {}
152 for i = 0, 60 do
153 table.insert(tab,
154 {
155 Vector:new{i/10, i/10},
156 Vector:new{(i+1)/10, (i+1)/10},
157 drawoptions="draw=green"
158 }
159 )
160 end
161 return tab
162 }
163 ]
164 \ltdtdisplaysimplices
165 \end{tikzpicture}
166 \caption{ltdtappendsurface}
167 \end{figure}
168
169 \subsection{ltdtappendtriangle}
170 This command appends a triangle.
171 \begin{itemize}
172 \item m: A 3-vector of start, stop and step in u
173 \item transformation: A homogeneous 3D transformation matrix.
174 \item fill options: a string of Ti\textit{k}Z options for a path.
175 \item filter: A boolean on m.
176 \end{itemize}
177 \begin{figure}
178 \centering
179 \begin{tikzpicture}
180 \ltdtappendtriangle[
181 m={return Matrix:new{
182 {1,1,1,1},
183 {0,0,0,1},
184 {-1,2,-2,1}
185 }},
186 fill options={return "fill=red"},
187 transformation={return Matrix.zyzrotation(Vector:new{pi/6,pi/3,pi/2})}
188 ]
189 \ltdtdisplaysimplices
190 \end{tikzpicture}
191 \caption{ltdtappendtriangle}
192 \end{figure}
193
194 \subsection{ltdtappendsolid}
195 This command appends the surface boundaries of a solid mapped from a cube.
196 \begin{itemize}
197 \item uparams: A 3-vector of start, stop and step in u
198 \item vparams: A 3-vector of start, stop and step in v
199 \item wparams: A 3-vector of start, stop and step in w
200 \item v: a homogeneous 3D vector
201 \item transformation: A homogeneous 3D transformation matrix.
202 \item fill options: a string of Ti\textit{k}Z options for a path.
203 \item filter: A boolean on v.
204 \end{itemize}
205 \begin{figure}
206 \centering
207 \begin{tikzpicture}
208 \ltdtappendlight[
209 v={return Vector:new{1,1,1,1}}
210 ]
211 \ltdtappendsolid[
212 v={return Vector:new{u,v,w-v}},
213 transformation={return Matrix.zyzrotation(Vector:new{pi/6,pi/3,pi/2})},
214 fill options={return "fill=ltdtbrightness,fill opacity=0.7"},
215 uparams={return Vector:new{0,1,10}},
216 vparams={return Vector:new{0,1,7}},
217 wparams={return Vector:new{0,1,7}}
218 ]
219 \ltdtdisplaysimplices
220 \end{tikzpicture}
221 \caption{ltdtappendsurface}
222 \end{figure}
223
224 \subsection{ltdtdisplaysimplices}
225 This command resolves the appended simplices, and displays the resulting
226 output.
227
228 \subsection{ltdtsetobject}
229 This command sets a lua object
230 \begin{itemize}
231 \item name: the lua name of the object.
232 \item object: the lua object (e.g., a function, or a matrix).
233 \end{itemize}
234
235 \end{document}