-
Notifications
You must be signed in to change notification settings - Fork 29
/
README.sb
232 lines (194 loc) · 12.2 KB
/
README.sb
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
\h1 \PyGLM\ h1\
\h2 \OpenGL Mathematics (GLM) library for Python\ h2\
\b \GLSL + Optional features + Python = PyGLM\ b\
\b \A mathematics library for graphics programming.\ b\
\b \PyGLM\ b\ is a Python extension written in \b \C++\ b\.
By using \url https://glm.g-truc.net \GLM by G-Truc\ url\ under the hood, it manages to bring \b \glm's features\ b\ to Python.
Some features are unsupported (such as most unstable extensions).
If you encounter any issues or want to request a feature, please create an issue on the \url https://github.com/Zuzu-Typ/PyGLM/issues \issue tracker\ url\.
\b\For a complete reference of the types and functions, please take a look at the \url https://github.com/Zuzu-Typ/PyGLM/wiki \wiki\ url\\b\.
\h2 \Tiny Documentation\ h2\
\h3 \Why PyGLM?\ h3\
Besides the obvious - being mostly compatible with \b \GLM\ b\ - PyGLM offers a variety of features for \b \vector\ b\ and \b \matrix manipulation\ b\.
It has a lot of possible use cases, including \b \3D-Graphics\ b\ (OpenGL, DirectX, ...), \b \Physics\ b\ and more.
At the same time, it has \b \great performance\ b\, usually being \b \a lot faster than numpy!\ b\ (see \url #speed-comparison-to-numpy \end of page\ url\)
(\i \depending on the individual function\ i\)
\h3 \Installation\ h3\
\b \PyGLM\ b\ supports \b \Windows\ b\, \b \Linux\ b\, \b \MacOS\ b\ and other operating systems.
It can be installed from the \url https://pypi.python.org/pypi/PyGLM \PyPI\ url\ using \url https://pip.pypa.io/en/stable/ \pip\ url\:
\code batch\
pip install PyGLM
\ code\
And finally imported and used:
\code python \
from PyGLM import glm
\ code\
\i\Changed in version 2.8\i\
When using PyGLM version \i \2.7.3\ i\ or earlier, use
\code python \
try:
from PyGLM import glm
except ImportError:
import glm
\ code\
\b \Attention: Using \code \import glm\ code\ will be deprecated in PyGLM 3.0.\ b\
\h3 \Using PyGLM\ h3\
PyGLM's syntax is very similar to the original GLM's syntax.
The module \code \glm\ code\ contains all of PyGLM's types and functions.
\url https://github.com/esoma/pyglm-typing \Typing stubs\ url\ by \url https://github.com/esoma \@esoma\ url\ are available in the \code \glm_typing\ code\ module.
For more information, take a look at the \url https://github.com/Zuzu-Typ/PyGLM/wiki \wiki\ url\.
\h4 \License requirements\ h4\
Please make sure to \b \include COPYING\ b\ in your project when you use PyGLM!
(this is especially relevant for \b \binary distributions\ b\, e.g. *.exe)
You can do so by copying the \code \COPYING\ code\ file (or it's contents) to your project.
\h4 \Differences to glm\ h4\
Instead of using double colons (\b \::\ b\) for namespaces, periods (\b \.\ b\) are used, so
\code \glm::vec2\ code\ becomes \code \glm.vec2\ code\.
PyGLM supports the \url https://docs.python.org/3/c-api/buffer.html \buffer protocol\ url\, meaning its compitible to other objects that support the buffer protocol,
such as \code \bytes\ code\ or \code \numpy.array\ code\
(for example you can convert a glm matrix to a numpy array and vice versa).
PyGLM is also capable of interpreting iterables (such as tuples) as vectors, so e.g. the following equasion is possible:
\code python \
result = glm.vec2(1) * (2, 3)
\ code\
\i\Note: This feature might not or only partially be available in PyGLM versions prior to 2.0.0\i\
PyGLM doesn't support precision qualifiers. All types use the default precision (\code \packed_highp\ code\).
If a glm function normally accepts \code \float\ code\ and \code \double\ code\ arguments, the higher precision (\code \double\ code\) is used.
There is no way to set preprocessor definitions (macros).
If - for example - you need to use the left handed coordinate system, you have to use \b \*LH\ b\, so
\code \glm.perspective\ code\ becomes \code \glm.perspectiveLH\ code\.
All types are initialized by default to avoid memory access violations.
(i.e. the macro \code \GLM_FORCE_CTOR_INIT\ code\ is defined)
In case you need the size of a PyGLM datatype, you can use
\code python \
glm.sizeof(<type>)
\ code\
The function \code \glm.identity\ code\ requires a matrix type as it's argument.
The function \code \glm.frexp(x, exp)\ code\ returns a tuple \code \(m, e)\ code\, if the input arguments are numerical.
This function may issue a \code \UserWarning\ code\. You can silence this warning using \code \glm.silence(1)\ code\.
The function \code \glm.value_ptr(x)\ code\ returns a ctypes pointer of the respective type.
I.e. if the datatype of \code \x\ code\ is \code \float\ code\, then a \code \c_float\ code\ pointer will be returned.
Likewise the reverse-functions (such as \code \make_vec2(ptr)\ code\) will take a ctypes pointer as their argument
and return (in this case) a 2 component vector of the pointers underlying type.
\code \glm.silence(ID)\ code\ can be used to silence specific warnings.
Supplying an id of 0 will silence all warnings.
\h3\FAQ\h3\
\h4\How to pass the matrices generated by PyGLM to OpenGL functions?\h4\
You will find an overview on the [\url https://github.com/Zuzu-Typ/PyGLM/wiki/Passing-data-to-external-libs/ \Passing data to external libs\ url\] page.
\h4\Types and functions are not available after installing from the PyPI using \code \pip install glm\ code\\h4\
Most likely you've installed \url https://pypi.org/project/glm/ \glm\ url\, a JSON parser and not \url https://pypi.org/project/PyGLM/ \PyGLM\ url\ (or a very early version of PyGLM).
The correct install command is:
\code batch \
pip install PyGLM
\ code\
\h4\Why is \i\<experimental extension name here>\i\ not supported?\h4\
I prefer not to add too many experimental extensions to PyGLM, especially as they might change or be removed in the future and it is simply too much effort for me to keep up with all that.
If you \b\need a specific experimental extension\b\, feel free to \b\submit a feature request\b\ on the \url https://github.com/Zuzu-Typ/PyGLM/issues \issue tracker\ url\.
I try adding them on a one-by-one basis.
\h3 \Short example\ h3\
\code Python \
from PyGLM import glm
# Create a 3D vector
v1 = glm.vec3(1, 2, 3)
v2 = glm.vec3(4, 5, 6)
# Vector addition
v3 = v1 + v2
print(f"Vector addition: {v3}")
# Vector addition: vec3( 5, 7, 9 )
# Vector cross product
# -> The resulting vector is perpendicular to v1 and v2.
cross_product = glm.cross(v1, v2)
print(f"Cross product: {cross_product}")
# Cross product: vec3( -3, 6, -3 )
# Vector dot product
# -> If the dot product is equal to 0, the two inputs are perpendicular.
dot_product = glm.dot(v1, cross_product)
print(f"Dot product: {dot_product}")
# Dot product: 0.0
# Create a 4x4 identity matrix
matrix = glm.mat4()
print(f"Identity matrix:\\n{matrix}")
# Identity matrix:
# [ 1 ][ 0 ][ 0 ][ 0 ]
# [ 0 ][ 1 ][ 0 ][ 0 ]
# [ 0 ][ 0 ][ 1 ][ 0 ]
# [ 0 ][ 0 ][ 0 ][ 1 ]
# Rotate the matrix around the Z-axis
angle_in_radians = glm.radians(45) # Convert 45 degrees to radians
rotation_matrix = glm.rotate(matrix, angle_in_radians, glm.vec3(0, 0, 1))
print(f"Rotation matrix (45 degrees around Z-axis):\\n{rotation_matrix}")
# Rotation matrix (45 degrees around Z-axis):
# [ 0.707107 ][ -0.707107 ][ 0 ][ 0 ]
# [ 0.707107 ][ 0.707107 ][ 0 ][ 0 ]
# [ 0 ][ 0 ][ 1 ][ 0 ]
# [ 0 ][ 0 ][ 0 ][ 1 ]
# Apply the rotation to a vector
# -> We use a vec4 with the w-component (given vec4(x, y, z, w)) set to 1,
# to put v1 into homogenous coordinates.
rotated_vector = rotation_matrix * glm.vec4(v1, 1)
print(f"Rotated vector: {rotated_vector}")
# Rotated vector: vec4( -0.707107, 2.12132, 3, 1 )
\ code\
\h3\PyGLM in action\h3\
Want to see what PyGLM can do?
Take a look at the \url https://github.com/Zuzu-Typ/LearnOpenGL-Python\examples\ url\ from the popular LearnOpenGL tutorials by Joey De Vries running in Python using PyGLM.
\raw\\raw\
\h3 \Speed comparison to numpy\ h3\
The following is the output generated by \url https://github.com/Zuzu-Typ/PyGLM/blob/master/test/PyGLM_vs_NumPy.py \test/PyGLM vs Numpy.py\ url\
\code \
Evaluating performance of PyGLM compared to NumPy.
Running on platform 'win32'.
Python version:
3.13.0 (tags/v3.13.0:60403a5, Oct 7 2024, 09:38:07) [MSC v.1941 64 bit (AMD64)]
Comparing the following module versions:
PyGLM (DEFAULT) version 2.7.2
vs
NumPy version 2.1.2
________________________________________________________________________________
The following table shows information about a task to be achieved and the time
it took when using the given module. Lower time is better.
Each task is repeated ten times per module, only showing the best (i.e. lowest)
value.
+----------------------------------------+------------+------------+-----------+
| Description | PyGLM time | NumPy time | ratio |
+----------------------------------------+------------+------------+-----------+
| 3 component vector creation | | | |
| (100,000 times) | 8ms | 30ms | 3.78x |
+----------------------------------------+------------+------------+-----------+
| 3 component vector creation with | | | |
| custom components | | | |
| (50,000 times) | 8ms | 33ms | 4.05x |
+----------------------------------------+------------+------------+-----------+
| dot product | | | |
| (50,000 times) | 3ms | 46ms | 13.53x |
+----------------------------------------+------------+------------+-----------+
| cross product | | | |
| (25,000 times) | 2ms | 523ms | 288.77x |
+----------------------------------------+------------+------------+-----------+
| L2-Norm of 3 component vector | | | |
| (100,000 times) | 5ms | 249ms | 49.05x |
+----------------------------------------+------------+------------+-----------+
| 4x4 matrix creation | | | |
| (50,000 times) | 5ms | 15ms | 3.03x |
+----------------------------------------+------------+------------+-----------+
| 4x4 identity matrix creation | | | |
| (100,000 times) | 6ms | 222ms | 36.61x |
+----------------------------------------+------------+------------+-----------+
| 4x4 matrix transposition | | | |
| (50,000 times) | 3ms | 23ms | 6.73x |
+----------------------------------------+------------+------------+-----------+
| 4x4 multiplicative inverse | | | |
| (50,000 times) | 4ms | 336ms | 90.30x |
+----------------------------------------+------------+------------+-----------+
| 3 component vector addition | | | |
| (100,000 times) | 5ms | 52ms | 10.11x |
+----------------------------------------+------------+------------+-----------+
| 4x4 matrix multiplication | | | |
| (100,000 times) | 8ms | 55ms | 6.85x |
+----------------------------------------+------------+------------+-----------+
| 4x4 matrix x vector multiplication | | | |
| (100,000 times) | 6ms | 152ms | 23.39x |
+----------------------------------------+------------+------------+-----------+
| TOTAL | 0.06s | 1.74s | 26.97x |
+----------------------------------------+------------+------------+-----------+
\ code\