Geo3d
Library for common 3d graphics vector and matrix operations
Installation
Add this line to your application's Gemfile:
gem 'geo3d'
And then execute:
$ bundle
Or install it yourself as:
$ gem install geo3d
Usage
a = Geo3d::Vector.point 1, 0, 0
b = Geo3d::Vector.point 0, 1, 0
sum = a + b # add them together
sum *= 2 #double the vector
m = Geo3d::Matrix.translation 0, 5, 0, #create a translation matrix that transforms a points 5 units on the y-axis
sum = m * sum #apply the transform to our vector
Vector
Describes a three dimensional point or direction. A vector has the following read/write attributes: x, y, z, w
Constructors
a = Geo3d::Vector.new #all attributes are initialized to zero
b = Geo3d::Vector.new x,y,z,w #initialize all attributes directly
c = Geo3d::Vector.new x,y,z #initialize x,y, and z directly and default w to zero
d = Geo3d::Vector.point x,y,z #initialize x,y, and z directly and default w to one
e = Geo3d::Vector.direction x,y,z #initialize x,y, and z directly and default w to zero
Vectors are overloaded with all of the basic math operations.
Addition
vec_a + vec_b
Subtraction
vec_a - vec_b
Multiplication
vec * scalar
Division
vec / scalar
Additional vector operations
Dot product
vec.dot
Cross product
vec_a.cross vec_b
Magnitude
vec.length
Squared Magnitude
vec.length_squared
Normalize
vec.normalize #returns a normalized version of the vector
vec.normalize! #normalizes the vector in place
Linear Interpolation
vec_a.lerp vec_b, 0.4 #returns a new vector which is the 40% linear interpolation between vec_a and vec_b
Screenspace projections
vec.project viewport, projection, view, world #transform an objectspace vertex to screenspace
vec.unproject viewport, projection, view, world #transform a screenspace vertex to objectspace
Reflections
vec.reflect normal, incident
Refractions
vec.refract normal, incident, index_of_refraction
Matrix
A 4x4 matrix used for transforming vectors. Elements can be read/written to with the double subscription operation. For instance, matrix[0,1] = 7 writes seven to the element in column zero and row one.
Matrices are overloaded with all of the basic math operations
Addition
mat_a + mat_b
Subtraction
mat_a - mat_b
Scalar Multiplication
mat * scalar
Scalar Division
mat / scalar
Matrix Multiplication
mat_a * mat_b
Matrix Vector Multiplication
mat * vec
Additional matrix operations
Inverse
mat.inverse #returns inverse of matrix
mat.inverse true #returns inverse of matrix along with its determinant
mat.determinant #returns the determinant
Transpose
mat.transpose
Common matrix constructors
Identity
Geo3d::Matrix.identity #returns the identity matrix
Translation
Geo3d::Matrix.translation x,y,z #returns a translation matrix
Scaling
Geo3d::Matrix.scaling x,y,z #returns a scaling matrix
Geo3d::Matrix.uniform_scaling scale #returns a uniform scaling matrix
Rotation
Geo3d::Matrix.rotation_x 0.44 #rotate .44 radians about x axis
Geo3d::Matrix.rotation_y 0.44 #rotate .44 radians about y axis
Geo3d::Matrix.rotation_z 0.44 #rotate .44 radians about z axis
axis = Geo3d::Vector.new 1,1,0
angle = 0.9
Geo3d::Matrix.rotation axis, angle #rotate about an arbitrary axis
Projection matrix constructors ala Direct3D (clip space of z coordinate has a range of 0 to 1)
Geo3d::Matrix.perspective_fov_rh fovy, aspect, z_near, z_far #returns a right handed perspective projection matrix
Geo3d::Matrix.perspective_fov_lh fovy, aspect, z_near, z_far #returns a left handed perspective projection matrix
Geo3d::Matrix.ortho_off_center_rh left, right, bottom, top, z_near, z_far #returns a right handed orthographic projection matrix
Geo3d::Matrix.ortho_off_center_lh left, right, bottom, top, z_near, z_far #returns a left handed orthographic projection matrix
Projection matrix constructors ala OpenGL (clip space of z coordinate has a range of -1 to 1)
Geo3d::Matrix.glu_perspective_degrees fovy, aspect, zn, zf #returns an opengl style right handed perspective projection matrix
Geo3d::Matrix.gl_frustum l, r, b, t, zn, zf #returns an opengl style right handed perspective projection matrix
Geo3d::Matrix.gl_ortho l, r, b, t, zn, zf #returns an opengl style righthanded orthographic projection matrix
View matrix constructors
Geo3d::Matrix.look_at_rh eye_position, look_at_position, up_direction #returns a right handed view matrix
Geo3d::Matrix.look_at_lh eye_position, look_at_position, up_direction #returns a left handed view matrix
Viewport matrix constructors
Geo3d::Matrix.viewport x, y, width, height
Misc constructors
Geo3d::Matrix.reflection reflection_plane #returns a reflection matrix where reflection_plane is a Geo3d::Vector that corresponds to the normal of the plane
Geo3d::Matrix.shadow light_position, plane #returns a shadow matrix
Matrix Decomposition
matrix.scaling_component
matrix.translation_component
matrix.rotation_component
Plane
Represents a 2d surface in three dimensional space. Has the attributes a,b,c,d that mirror the standard plane equations.
There are a couple constructors to build planes from points and normals.
Geo3d::Plane.from_points pv1, pv2, pv3 #builds a plane from known points on the plane
Geo3d::Plane.from_point_and_normal point, normal #builds a plane from it's normal and a known point
Additional plane operations
Dot product
plane.dot v #v can be a vector or another plane
Normalize
plane.normalize #returns a normalized version of the plane
plane.normalize! #normalizes the plane in place
Normal
plane.normal #returns the normal of the plane
Line intersection
plane.line_intersection line_start, line_end #returns the intersection of the line onto the plane
Plane Transformation
#transforms plane by the matrix, if use_inverse_transpose is set to true, the plane will be transformed by the inverse transpose of matrix
plane.transform matrix, use_inverse_transpose = true
Quaternion
A mathematical construct to represent rotations in 3d space.
Quaternions support all the basic math operations.
Addition
quat_a + quat_b
Subtraction
quat_a - quat_b
Quaternion Multiplication
quat_a * quat_b
Scalar Multiplication
quat * scalar
Scalar Division
quat / scalar
Getting axis and angle
quat.axis
quat.angle #returns angle in radians
quat.angle_degrees #returns angle in degrees
Converting to a matrix
quat.to_matrix
Additional quaternion operations Magnitude
quat.length
Squared Magnitude
quat.length_squared
Normalize
quat.normalize #returns a normalized version of the quaternion
quat.normalize! #normalizes the quaternion in place
Inverse
quat.inverse #returns inverse of quaternion
Conjugate
quat.conjugate
Dot product
quat.dot
Constructors
Geo3d::Quaternion.from_axis rotation_axis, radians #returns a quaternion from an axis and angle
Geo3d::Quaternion.from_matrix m #returns a quaternion from a rotation matrix
Geo3d::Quaternion.identity #returns the identity quaternion
Triangle
Represents a triangle in three dimensional space
Constructors
Geo3d::Triangle.from_axis rotation_axis, radians #returns a quaternion from an axis and angle
Geo3d::Quaternion.from_matrix m #returns a quaternion from a rotation matrix
Geo3d::Quaternion.identity #returns the identity quaternion
Normal
triangle.normal #returns the normal of the plane
Winding
triangle.clockwise? #is the triangle winded clockwise?
triangle.counter_clockwise? #is the triangle winded counter clockwise?
Flipping
triangle.flip #returns a flipped version of the triangle (reverses the winding)
triangle.flip! #flips the triangle in place
signed area
triangle.signed_area
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request