# GLSLSyntax
This is a Python package that provides the syntax and objects to manipulate vectors and matrices like in GLSL.
## Installation
```bash
pip install glslsyntax
```
## Usage
Import everything to get the closest experience to GLSL.
```python
from glslsyntax import *
```
You can also import only vectors or matrices.
```python
from glslsyntax.vectors import *
from glslsyntax.matrices import *
```
## Features
### Vectors
#### Declaration
Vectors support integer and float values. They can be declared by typing `vec` followed by the number of dimensions. Up to 4 dimensions are supported. To declare the vector, you can pass the values as arguments or a single value to create a vector with all dimensions set to that value.
```python
# Classic declaration
u = vec2(1, 2.3)
v = vec3(1, 2, 3)
w = vec4(1, 2, 3, 4)
# Shorthand declaration
u2 = vec2(1) # (1, 1)
v2 = vec3(1.1) # (1.1, 1.1, 1.1)
w2 = vec4(1) # (1, 1, 1, 1)
```
You can also use other vectors to create a new one.
```python
u3 = vec4(vec2(1), vec2(3, 4)) # (1, 1, 3, 4)
v3 = vec3(1, vec2(2, 3.5)) # (1, 2, 3.5)
```
#### Attributes
All vectors have the following attributes:
- `x`, `y`, `z`, `w` to access the components of the vector. `x` and `y` are always available, `z` is available for 3D and 4D vectors, and `w` is available for 4D vectors.
- `r`, `g`, `b`, `a` are aliases for `x`, `y`, `z`, `w` and acts in the same way.
- `magnitude` to get the magnitude of the vector.
- `normal` to get the normalized vector. This doesn't modify the original vector.
- `size` to get the number of dimensions of the vector.
##### Swizzling
The `x`, `y`, `z`, `w` attributes can be used together to create a new vector with a number of dimensions equal to the number of attributes used. The order of the attributes will affect the order of the components in the new vector.
```python
u = vec3(1, 2, 3)
v = u.yzx # vec3(2, 3, 1)
w = u.zzz # vec3(3, 3, 3)
print(u.magnitude) # 3.7416573867739413
print(u.normal.x) # 0.2672612419124244
print(u.xz.size) # 2
```
The `x`, `y`, `z`, `w` attributes can be used to set the components of the vector.
```python
u = vec3(1, 2, 3)
u.x = 4
print(vec) # vec3(4, 2, 3)
```
#### Access values by index
For iteratives approaches, you can access the components of the vector by index.
Though, this can return only a single value, not a vector.
```python
u = vec3(1, 2, 3)
# Accessing by index
print(u[0]) # 1
print(u[1]) # 2
print(u[2]) # 3
# Modifying by index
u[0] = 4
print(u) # vec3(4, 2, 3)
```
This functionality exists for better matrix manipulations.
#### Methods
Some functions of GLSL have been implemented as methods of the vectors. They are:
- `dot(<vector>)` to get the dot product of two vectors.
- `cross(<vector>)` to get the cross product of two vectors. This is only available for 3D vectors.
- `distance(<vector>)` to get the distance between two vectors. This is equivalent to `(<current_vector> - <vector>).magnitude`. Note that in case of vectors with different dimensions, the distance will be calculated with the number of dimensions of the smallest vector.
- `normalize()` to normalize the vector. This modifies the original vector contrary to the `normal` attribute. Returns the normalized vector.
- `getArray()` to get the components of the vector as a list.
```python
u = vec3(1, 2, 3)
v = vec3(4, 5, 6)
print(u.dot(v)) # 32
print(u.cross(v)) # vec3(-3, 6, -3)
print(u.distance(v)) # 5.196152422706632
print(u.normalize()) # vec3(0.2672612419124244, 0.5345224838248488, 0.8017837257372732)
```
#### Operators
The following operators are available for vectors:
- `+` to add two vectors.
- `-` to subtract two vectors.
- `*` to multiply a vector by a scalar or to get the component-wise product of two vectors.
- `/` to divide a vector by a scalar or to get the component-wise division of two vectors.
> [!IMPORTANT]
> When using two vectors with different dimensions, the operation will be done with the number of dimensions of the smallest vector.
```python
u = vec3(1, 2, 3)
v = vec3(4, 5, 6)
print(u + v) # vec3(5, 7, 9)
print(u - v) # vec3(-3, -3, -3)
print(u * 2) # vec3(2, 4, 6)
print(u / 2) # vec3(0.5, 1, 1.5)
print(u * v) # vec3(4, 10, 18)
print(u / v) # vec3(0.25, 0.4, 0.5)
```
### Matrices
#### Declaration
Matrices can be declared by typing `mat` followed by the number of rows and columns. Up to 4x4 matrices are supported. To declare the matrix.
> [!INFO]
> The arguments format follows the [GLSL matrix declaration](https://registry.khronos.org/OpenGL/specs/es/3.0/GLSL_ES_Specification_3.00.pdf#page=70). That means that the first argument is the first **column**, the second argument is the second **column**, and so on.
Here are some examples of matrix declaration:
```python
# Diagonal matrix
m = mat2(1)
n = mat3(2)
# m is an identity matrix:
# | 1 0 |
# | 0 1 |
# n is a diagonal matrix:
# | 2 0 0 |
# | 0 2 0 |
# | 0 0 2 |
o = mat2(1, 2, # first column
3, 4) # second column
# o is a 2x2 matrix:
# | 1 3 |
# | 2 4 |
# but stored as:
# vec2(1, 2),
# vec2(3, 4)
p = mat3(vec3(1, 2, 3), # first column
vec3(4, 5, 6), # second column
vec3(7, 8, 9)) # third column
# p is a 3x3 matrix:
# | 1 4 7 |
# | 2 5 8 |
# | 3 6 9 |
# but stored as:
# vec3(1, 2, 3),
# vec3(4, 5, 6),
# vec3(7, 8, 9)
```
Additionally to the classic GLSL declaration, an extra feature of this package is the ability to input as arguments different types of vectors and matrices. If the arguments arn't vectors or matrices of the expected size but there are the right number of components, the package will try to create the matrix with the components of the arguments.
```python
u = vec2(1, 2)
v = vec2(3, 4)
w = vec3(5, 6, 7)
m = mat4(u, v, w, vec4(8, 9, 10, 11), vec4(12, 13, 14, 15), 16)
# m is a 4x4 matrix:
# | 1 5 9 13 |
# | 2 6 10 14 |
# | 3 7 11 15 |
# | 4 8 12 16 |
```
#### Attributes
All matrices have the following attributes:
- `size` returns a tuple with the number of columns (number of vectors) and raws of the matrix (size of the vectors).
- `T` returns the transpose of the matrix. This doesn't modify the original matrix.
- `Id` returns the identity matrix of the same size as the original matrix.
- `Inv` returns the inverse of the matrix. This doesn't modify the original matrix.
- `det` returns the determinant of the matrix.
#### Methods
- `getArray()` to get the components of the matrix as a list.
- `isSquare()` to check if the matrix is a square matrix.
- `isIdentity()` to check if the matrix is an identity matrix.
- `isDiagonal()` to check if the matrix is a diagonal matrix.
- `isSymmetric()` to check if the matrix is a symmetric matrix.
- `isOrthogonal()` to check if the matrix is an orthogonal matrix.
- `fprint()` to print the matrix in a formatted way.
#### Operators
The following operators are available for matrices:
- `+` to add two matrices of the same size or to add a scalar to each component of the matrix.
- `-` to subtract two matrices of the same size or to subtract a scalar to each component of the matrix.
- `*` to multiply a matrix by a scalar or to get the matrix product of two matrices.
- `/` to divide a matrix by a scalar or to divide a matrix by another matrix component-wise. The two matrices must have the same size.
#### Examples
```python
m = mat2(1, 2,
3, 4)
n = mat2(5, 6,
7, 8)
print(m + n) # mat2(6, 8, 10, 12)
print(m - n) # mat2(-4, -4, -4, -4)
print(m * 2) # mat2(2, 4, 6, 8)
print(m / 2) # mat2(0.5, 1, 1.5, 2)
print(m * n) # mat2(19, 22, 43, 50)
print(m.T) # mat2(1, 3, 2, 4)
print(m.Id) # mat2(1, 0, 0, 1)
print(m.Inv) # mat2(-2, 1, 1.5, -0.5)
print(m.det) # -2
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [GLSL](https://www.khronos.org/opengl/wiki/Core_Language_(GLSL)) for the inspiration.
## Upcoming features
- [x] Matrices
- [ ] Multiply matrices by vectors and other matrices of different sizes
- [ ] Modifying multiple components at once (eg. `vec.xz = vec2(1, 2)`)
- [x] Supoort lists as declaration arguments
Raw data
{
"_id": null,
"home_page": "https://github.com/Neylz/GlslSyntax",
"name": "glslsyntax",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "GLSL,VECTORS,VECTOR,MATRIX,MATRICES",
"author": "Neylz",
"author_email": "contact@neylz.dev",
"download_url": "https://files.pythonhosted.org/packages/70/d0/7eace08bba719d6c3858ed20b209fe6c38b171f1fa9d2743b5d38bb7806a/glslsyntax-1.0.0.tar.gz",
"platform": null,
"description": "# GLSLSyntax\n\nThis is a Python package that provides the syntax and objects to manipulate vectors and matrices like in GLSL.\n\n## Installation\n\n```bash\npip install glslsyntax\n```\n\n## Usage\n\nImport everything to get the closest experience to GLSL.\n```python\nfrom glslsyntax import *\n```\n\nYou can also import only vectors or matrices.\n```python\nfrom glslsyntax.vectors import *\nfrom glslsyntax.matrices import *\n```\n\n## Features\n\n### Vectors\n\n#### Declaration\nVectors support integer and float values. They can be declared by typing `vec` followed by the number of dimensions. Up to 4 dimensions are supported. To declare the vector, you can pass the values as arguments or a single value to create a vector with all dimensions set to that value.\n```python\n# Classic declaration\nu = vec2(1, 2.3)\nv = vec3(1, 2, 3)\nw = vec4(1, 2, 3, 4)\n\n# Shorthand declaration\nu2 = vec2(1) # (1, 1)\nv2 = vec3(1.1) # (1.1, 1.1, 1.1)\nw2 = vec4(1) # (1, 1, 1, 1)\n```\n\nYou can also use other vectors to create a new one.\n```python\nu3 = vec4(vec2(1), vec2(3, 4)) # (1, 1, 3, 4)\nv3 = vec3(1, vec2(2, 3.5)) # (1, 2, 3.5)\n```\n\n#### Attributes\n\nAll vectors have the following attributes:\n- `x`, `y`, `z`, `w` to access the components of the vector. `x` and `y` are always available, `z` is available for 3D and 4D vectors, and `w` is available for 4D vectors.\n- `r`, `g`, `b`, `a` are aliases for `x`, `y`, `z`, `w` and acts in the same way.\n- `magnitude` to get the magnitude of the vector.\n- `normal` to get the normalized vector. This doesn't modify the original vector.\n- `size` to get the number of dimensions of the vector.\n\n##### Swizzling\n\nThe `x`, `y`, `z`, `w` attributes can be used together to create a new vector with a number of dimensions equal to the number of attributes used. The order of the attributes will affect the order of the components in the new vector.\n```python\nu = vec3(1, 2, 3)\n\nv = u.yzx # vec3(2, 3, 1)\nw = u.zzz # vec3(3, 3, 3)\n\nprint(u.magnitude) # 3.7416573867739413\nprint(u.normal.x) # 0.2672612419124244\nprint(u.xz.size) # 2\n```\n\n\nThe `x`, `y`, `z`, `w` attributes can be used to set the components of the vector.\n\n```python\nu = vec3(1, 2, 3)\nu.x = 4\n\nprint(vec) # vec3(4, 2, 3)\n```\n\n#### Access values by index\nFor iteratives approaches, you can access the components of the vector by index.\nThough, this can return only a single value, not a vector.\n\n```python\nu = vec3(1, 2, 3)\n\n# Accessing by index\nprint(u[0]) # 1\nprint(u[1]) # 2\nprint(u[2]) # 3\n\n# Modifying by index\nu[0] = 4\nprint(u) # vec3(4, 2, 3)\n```\nThis functionality exists for better matrix manipulations.\n\n\n#### Methods\n\nSome functions of GLSL have been implemented as methods of the vectors. They are:\n- `dot(<vector>)` to get the dot product of two vectors.\n- `cross(<vector>)` to get the cross product of two vectors. This is only available for 3D vectors.\n- `distance(<vector>)` to get the distance between two vectors. This is equivalent to `(<current_vector> - <vector>).magnitude`. Note that in case of vectors with different dimensions, the distance will be calculated with the number of dimensions of the smallest vector.\n- `normalize()` to normalize the vector. This modifies the original vector contrary to the `normal` attribute. Returns the normalized vector.\n- `getArray()` to get the components of the vector as a list.\n\n```python\nu = vec3(1, 2, 3)\nv = vec3(4, 5, 6)\n\nprint(u.dot(v)) # 32\nprint(u.cross(v)) # vec3(-3, 6, -3)\n\nprint(u.distance(v)) # 5.196152422706632\nprint(u.normalize()) # vec3(0.2672612419124244, 0.5345224838248488, 0.8017837257372732)\n```\n\n#### Operators\n\nThe following operators are available for vectors:\n- `+` to add two vectors.\n- `-` to subtract two vectors.\n- `*` to multiply a vector by a scalar or to get the component-wise product of two vectors.\n- `/` to divide a vector by a scalar or to get the component-wise division of two vectors.\n\n> [!IMPORTANT]\n> When using two vectors with different dimensions, the operation will be done with the number of dimensions of the smallest vector.\n\n```python\nu = vec3(1, 2, 3)\nv = vec3(4, 5, 6)\n\nprint(u + v) # vec3(5, 7, 9)\nprint(u - v) # vec3(-3, -3, -3)\nprint(u * 2) # vec3(2, 4, 6)\nprint(u / 2) # vec3(0.5, 1, 1.5)\nprint(u * v) # vec3(4, 10, 18)\nprint(u / v) # vec3(0.25, 0.4, 0.5)\n```\n\n\n### Matrices\n\n#### Declaration\n\nMatrices can be declared by typing `mat` followed by the number of rows and columns. Up to 4x4 matrices are supported. To declare the matrix.\n> [!INFO]\n> The arguments format follows the [GLSL matrix declaration](https://registry.khronos.org/OpenGL/specs/es/3.0/GLSL_ES_Specification_3.00.pdf#page=70). That means that the first argument is the first **column**, the second argument is the second **column**, and so on.\n\nHere are some examples of matrix declaration:\n```python\n# Diagonal matrix\nm = mat2(1) \nn = mat3(2)\n\n# m is an identity matrix: \n# | 1 0 |\n# | 0 1 |\n\n# n is a diagonal matrix:\n# | 2 0 0 |\n# | 0 2 0 |\n# | 0 0 2 |\n\no = mat2(1, 2, # first column\n 3, 4) # second column\n# o is a 2x2 matrix:\n# | 1 3 |\n# | 2 4 |\n# but stored as:\n# vec2(1, 2),\n# vec2(3, 4)\n\np = mat3(vec3(1, 2, 3), # first column\n vec3(4, 5, 6), # second column\n vec3(7, 8, 9)) # third column\n# p is a 3x3 matrix:\n# | 1 4 7 |\n# | 2 5 8 |\n# | 3 6 9 |\n# but stored as:\n# vec3(1, 2, 3),\n# vec3(4, 5, 6),\n# vec3(7, 8, 9)\n```\n\nAdditionally to the classic GLSL declaration, an extra feature of this package is the ability to input as arguments different types of vectors and matrices. If the arguments arn't vectors or matrices of the expected size but there are the right number of components, the package will try to create the matrix with the components of the arguments.\n\n```python\nu = vec2(1, 2)\nv = vec2(3, 4)\nw = vec3(5, 6, 7)\n\nm = mat4(u, v, w, vec4(8, 9, 10, 11), vec4(12, 13, 14, 15), 16)\n# m is a 4x4 matrix:\n# | 1 5 9 13 |\n# | 2 6 10 14 |\n# | 3 7 11 15 |\n# | 4 8 12 16 |\n```\n\n#### Attributes\n\nAll matrices have the following attributes:\n- `size` returns a tuple with the number of columns (number of vectors) and raws of the matrix (size of the vectors).\n- `T` returns the transpose of the matrix. This doesn't modify the original matrix.\n- `Id` returns the identity matrix of the same size as the original matrix.\n- `Inv` returns the inverse of the matrix. This doesn't modify the original matrix.\n- `det` returns the determinant of the matrix.\n\n#### Methods\n- `getArray()` to get the components of the matrix as a list.\n- `isSquare()` to check if the matrix is a square matrix.\n- `isIdentity()` to check if the matrix is an identity matrix.\n- `isDiagonal()` to check if the matrix is a diagonal matrix.\n- `isSymmetric()` to check if the matrix is a symmetric matrix.\n- `isOrthogonal()` to check if the matrix is an orthogonal matrix.\n- `fprint()` to print the matrix in a formatted way.\n\n#### Operators\n\nThe following operators are available for matrices:\n- `+` to add two matrices of the same size or to add a scalar to each component of the matrix.\n- `-` to subtract two matrices of the same size or to subtract a scalar to each component of the matrix.\n- `*` to multiply a matrix by a scalar or to get the matrix product of two matrices.\n- `/` to divide a matrix by a scalar or to divide a matrix by another matrix component-wise. The two matrices must have the same size.\n\n#### Examples\n\n```python\nm = mat2(1, 2,\n 3, 4)\n\nn = mat2(5, 6,\n 7, 8)\n\nprint(m + n) # mat2(6, 8, 10, 12)\nprint(m - n) # mat2(-4, -4, -4, -4)\nprint(m * 2) # mat2(2, 4, 6, 8)\nprint(m / 2) # mat2(0.5, 1, 1.5, 2)\nprint(m * n) # mat2(19, 22, 43, 50)\n\nprint(m.T) # mat2(1, 3, 2, 4)\nprint(m.Id) # mat2(1, 0, 0, 1)\nprint(m.Inv) # mat2(-2, 1, 1.5, -0.5)\nprint(m.det) # -2\n```\n\n\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [GLSL](https://www.khronos.org/opengl/wiki/Core_Language_(GLSL)) for the inspiration.\n\n## Upcoming features\n\n- [x] Matrices\n- [ ] Multiply matrices by vectors and other matrices of different sizes\n- [ ] Modifying multiple components at once (eg. `vec.xz = vec2(1, 2)`)\n- [x] Supoort lists as declaration arguments\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Imports GLSL Vector and Matrix notations in python with somme extra features.",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/Neylz/GlslSyntax/issues",
"Homepage": "https://github.com/Neylz/GlslSyntax"
},
"split_keywords": [
"glsl",
"vectors",
"vector",
"matrix",
"matrices"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f674e88edfd7406895fe126ceabac851c297f640bf67898242b61af8b5947804",
"md5": "2cf17316d91015157c90639a8150f7d4",
"sha256": "90182a73445875047a13d3960eb74c8c5235a41c61b6f38be4d0ed559837d732"
},
"downloads": -1,
"filename": "glslsyntax-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2cf17316d91015157c90639a8150f7d4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9166,
"upload_time": "2024-02-19T22:29:34",
"upload_time_iso_8601": "2024-02-19T22:29:34.849806Z",
"url": "https://files.pythonhosted.org/packages/f6/74/e88edfd7406895fe126ceabac851c297f640bf67898242b61af8b5947804/glslsyntax-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "70d07eace08bba719d6c3858ed20b209fe6c38b171f1fa9d2743b5d38bb7806a",
"md5": "00ddbafa87cbc561928e79c91b2df13d",
"sha256": "e151ebd833f309f286d3dd1d7a45e1fe2e434e629073276fe79444c10527fe7c"
},
"downloads": -1,
"filename": "glslsyntax-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "00ddbafa87cbc561928e79c91b2df13d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 12677,
"upload_time": "2024-02-19T22:29:36",
"upload_time_iso_8601": "2024-02-19T22:29:36.451770Z",
"url": "https://files.pythonhosted.org/packages/70/d0/7eace08bba719d6c3858ed20b209fe6c38b171f1fa9d2743b5d38bb7806a/glslsyntax-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-19 22:29:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Neylz",
"github_project": "GlslSyntax",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "glslsyntax"
}
JSON
