PyNGL

This is the code for the full python version of NGL the ncca graphics library.

More details soon as this is work in progress.

Test

use

uv run pytest

To run tests,

uv run pytest --cov=src --cov-report=term-missing

For coverage reports.

Classes

abstract_vao.py

• VertexData: A simple data structure to hold vertex data for a VAO. It stores the data as a numpy array, the size of the data, and the drawing mode.
• AbstractVAO: An abstract base class for Vertex Array Objects (VAOs). It defines the interface for different VAO implementations, including methods for binding, drawing, setting data, and managing the VAO's lifecycle.

base_mesh.py

• Face: A simple data structure for a mesh face, holding indices for vertices, UVs, and normals.
• BaseMesh: A base class for mesh geometry. It provides storage for vertices, normals, UVs, and faces, and includes methods for creating a VAO from the mesh data, calculating dimensions, and drawing the mesh.

bbox.py

• BBox: Represents a 3D bounding box. It stores the center, dimensions, and extents of the box, and provides methods to calculate these values and retrieve the box's vertices and normals.

bezier_curve.py

• BezierCurve: A class for creating and evaluating Bézier curves. It stores control points and knots, and can calculate points on the curve using the Cox-de Boor algorithm.

first_person_camera.py

• FirstPersonCamera: Implements a first-person camera with movement, rotation, and projection matrix calculation. It handles mouse and keyboard input for camera control.

image.py

• Image: A class for loading, saving, and manipulating images. It uses the Pillow library to handle different image formats and stores image data as a NumPy array.

log.py

• ColoredFormatter: A custom logging formatter that adds color to log messages based on their severity level.
• setup_logger: A function to set up a logger with both file and console handlers.

mat2.py

• Mat2: A 2x2 matrix class with support for identity, multiplication (matrix-matrix and matrix-vector), and conversion to a NumPy array.

mat3.py

• Mat3: A 3x3 matrix class for 3D transformations. It includes methods for identity, zero, scale, rotation, transpose, inverse, and matrix multiplication.

mat4.py

• Mat4: A 4x4 matrix class for 3D transformations. It supports creation of identity, zero, scale, translation, and rotation matrices, as well as matrix multiplication and inversion.

multi_buffer_vao.py

• MultiBufferVAO: A VAO implementation that can manage multiple vertex buffers. This is useful for separating different types of vertex attributes (e.g., positions, colors, normals) into different buffers.

obj.py

• Obj: A class for loading and saving Wavefront OBJ files. It extends BaseMesh and handles parsing of vertices, normals, UVs, and faces from an OBJ file, including support for negative indices.

plane.py

• Plane: Represents a mathematical plane in 3D space. It can be defined by three points or a normal and a point, and can calculate the distance from a point to the plane.

prim_data.py

• Prims: An enum of available primitive types.
• PrimData: A class that provides static methods to generate vertex data for various geometric primitives like spheres, cubes, and tori.

primitives.py

• Primitives: A static class for creating and drawing pre-defined geometric primitives. It uses PrimData to generate the vertex data and VAOFactory to create VAOs for rendering.

pyside_event_handling_mixin.py

• PySideEventHandlingMixin: A mixin class for PySide6 applications that provides common event handling for mouse-based camera control (rotation, translation, zoom) and keyboard shortcuts.

quaternion.py

• Quaternion: A class for representing rotations using quaternions. It includes methods for converting from a rotation matrix, multiplication, normalization, and applying the rotation to a vector.

random.py

• Random: A static class for generating random numbers and vectors. It provides methods to get random floats, integers, and vectors of different dimensions.

shader.py

• Shader: Represents a single OpenGL shader object (e.g., vertex, fragment). It handles loading source from a file, compiling the shader, and checking for errors.

shader_lib.py

• ShaderLib: A singleton class that manages a library of shader programs. It provides a global point of access for loading, compiling, linking, and using shaders, as well as for setting uniform variables.

shader_program.py

• ShaderProgram: A wrapper for an OpenGL shader program. It manages attaching shaders, linking the program, and provides an interface for setting uniform variables.

simple_index_vao.py

• SimpleIndexVAO: A VAO implementation that uses an index buffer for indexed drawing. This is more efficient for meshes where vertices are shared between multiple faces.

simple_vao.py

• SimpleVAO: A basic VAO implementation that uses a single buffer for non-indexed drawing.

text.py

• Text: A class for rendering text in OpenGL. It uses freetype-py to create a texture atlas of font glyphs and renders text using a geometry shader to create quads for each character.

texture.py

• Texture: A class for loading image files and creating OpenGL textures from them.

transform.py

• Transform: A class to represent a 3D transformation with position, rotation, and scale components. It can generate a transformation matrix based on a specified rotation order.

util.py

• util.py: This module contains various utility functions for 3D math, including lookAt, perspective, ortho, and frustum matrix generation, as well as clamp and lerp functions.

vao_factory.py

• VAOFactory: A factory class for creating different types of VAOs. It allows for registering custom VAO creators and creating VAO instances by name.

vec2.py, vec3.py, vec4.py

• Vec2, Vec3, Vec4: Classes for 2D, 3D, and 4D vectors, respectively. They provide standard vector operations such as addition, subtraction, dot product, cross product, normalization, and length calculation.

vec2_array.py, vec3_array.py, vec4_array.py

• Vec2Array, Vec3Array, Vec4Array: Container classes that act like std::vector for Vec2, Vec3, and Vec4 objects, respectively. They provide methods for appending, extending, and converting the data to flat lists or NumPy arrays.