# Josh's 3D Math Library - J3ML

![J3ML Logo](logo_light_small.png)

Yet Another C++ Math Standard

J3ML is a "Modern C++" library designed to provide comprehensive support for 3D mathematical operations commonly used in computer graphics, game development, physics simulations, and related fields. It offers a wide range of functionalities to simplify the implementation of complex mathematical operations in your projects.

![Static Badge](https://img.shields.io/badge/Lit-Based-%20)

## Features

* **Vector Operations:** Comprehensive support for 3D vector operations including addition, subtraction, scalar multiplication, dot product, cross product, normalization, and more. 
* **Matrix Operations:** Efficient implementation of 3x3 and 4x4 matrices with support for common operations such as multiplication, transpose, determinant calculation, and inverse calculation.
* **Quaternion Operations:** Quaternion manipulation functions including conversion to/from axis-angle representation, quaternion multiplication, normalization, and interpolation (slerp).
* **Transformation Functions:** Functions for transforming points, vectors, and normals using matrices and quaternions.
* **Geometric Types:** Support for geometric types such as points, lines, rays, planes, spheres, axis-aligned bounding boxes (AABB), and oriented bounding boxes (OBB).
* **Algorithms:** Implementation of various algorithms including Gilbert-Johnson-Keerthi (GJK) algorithm for collision detection, random number generator, and more.
* **Utility Functions:** Additional utilities such as conversion between degrees and radians, random number generation, and common constants.

## Coming Soon

* **SIMD:** (Single-instruction, multiple-data) utilizes a vectorized instruction set to compute operations on multiple values at once. This is particularly useful in matrix maths.
* **LUTs:** Compute Lookup-tables for common operations, and bake them into your program via constexpr. (Sin, Cos, Tan, Sqrt, FastInverseSqrt)

# Installation

We support integration via CMake Package Manager (CPM). It's quite clean and flexible. It's a single CMake script too.

Here's what we recommend:

Install CPM.cmake to a `cmake` directory in your project root, and add the lines below into your CMakeLists.txt

To integrate the package manager:
```cmake
include("cmake/CPM.cmake")
```

To automatically download and build J3ML version 3.4.5 (Check releases for new versions!):

```cmake
CPMAddPackage(
        NAME J3ML
        URL https::/git.redacted.cc/josh/J3ML/archive/3.4.5.zip
)
```
Then you should be able to link J3ML to your project like any other library:

```cmake
target_include_directories(MyProgramOrLib PUBLIC ${J3ML_SOURCE_DIR}/include)
###
target_link_libraries(MyProgramOrLib PUBLIC J3ML)
```


# Usage Samples

## 2D Vector Operations

```cpp
#include <J3ML/LinearAlgebra.hpp>

Vector2 position {10.f, 10.f};
Vector2 velocity {5.f, 1.5f};
float step = 1.f/60.f;

void doStep() {
    position = position + (velocity * step);
    velocity = velocity.Lerp(Vector2::Zero, step);
    float speed = velocity.Length();
}
```

## Matrix3x3 and Rotation Types

```cpp
#include <j3ml/LinearAlgebra.h>

Matrix3x3 mRotation = Matrix3x3::RotateX(Math::PiOverTwo);
Quaternion qRotation(mRotation); // Convert to Quaternion
AxisAngle aRotation(qRotation); // Convert to AxisAngle
EulerAngleXYZ eRotation(aRotation); // Convert to Euler Angle (XYZ)
```

For more detailed usage instructions and examples, please refer to the documentation.
# Documentation

Documentation is automatically generated from latest commit and is hosted at https://doc.redacted.cc/j3ml .

# Contributing

Contributions to J3ML are welcome! If you find a bug, have a feature request, or would like to contribute code, please submit an issue or pull request to the repository.

# License

J3ML is licensed under the Public Domain. See the LICENSE file for details.

# Acknowledgements

J3ML is developed and maintained by Joshua O'Leary from Redacted Software and contributors. Special thanks to William J Tomasine II.

bump :3 :3 :3 :3 :3 :3 :3 :3 :3 :3 :3 :3 :3 :3 :3 :3 :3