**zk3d** is an open-source npm package designed to extend the mathematical capabilities of the Three.js library to o1js applications within the Mina ecosystem. It features core classes such as `Matrix4`

, `Vector3`

, and `Real64`

, offering a wide range of mathematical operations for 3D transformations and calculations.

To install zk3d, run the following command in your project directory:

`npm install zk3d`

First, import the required classes into your project:

`import { Matrix4, Vector3, Real64 } from "zk3d";`

Real64 provides a high-precision numerical type, essential for accurate mathematical operations within zk3d. This class ensures that your 3D calculations maintain numerical integrity, especially critical in the context of complex transformations or when precision is paramount. Below is an example illustrating how to instantiate and use Real64:

```
// Create a new Real64 instance
let num = Real64.from(12.34);
// Arithmetic operations with Real64
let sum = num.add(Real64.from(23.45)); // Perform addition
let product = num.multiply(Real64.from(3.21)); // Perform multiplication
```

Vector2 represents two-dimensional vectors. This class can be crucial for operations in a plane or for simplifying 3D problems into 2D scenarios when appropriate. Here's how you can use it:

```
// Create a new Vector2 instance
let v4 = new Vector2({ x: Real64.from(7), y: Real64.from(8) });
// Perform vector addition
let v5 = new Vector2({ x: Real64.from(1), y: Real64.from(2) });
let v6 = v4.add(v5); // v6 is now the result of v4 + v5
```

Vector3 represents three-dimensional vectors. Here's an example of how to use it:

```
// Create a new Vector3 instance
let v1 = new Vector3({
x: Real64.from(1),
y: Real64.from(2),
z: Real64.from(3),
});
// Perform vector addition
let v2 = new Vector3({
x: Real64.from(4),
y: Real64.from(5),
z: Real64.from(6),
});
let v3 = v1.add(v2); // v3 is now the result of v1 + v2
```

Matrix3 represents 3x3 matrices, which are crucial in 2D transformations and can also be applied in 3D contexts. Here's a basic usage example:

```
// Create a new Matrix3 instance
let m2 = new Matrix3({
n11: Real64.from(1),
n12: Real64.from(0),
n13: Real64.from(0),
n21: Real64.from(0),
n22: Real64.from(1),
n23: Real64.from(0),
n31: Real64.from(0),
n32: Real64.from(0),
n33: Real64.from(1),
});
```

Matrix4 is used for 4x4 matrix operations. Below is an example:

```
// Create a new Matrix4 instance
let m1 = new Matrix4({
n11: Real64.from(1),
n12: Real64.from(0),
n13: Real64.from(0),
n14: Real64.from(0),
n21: Real64.from(0),
n22: Real64.from(1),
n23: Real64.from(0),
n24: Real64.from(0),
n31: Real64.from(0),
n32: Real64.from(0),
n33: Real64.from(1),
n34: Real64.from(0),
n41: Real64.from(0),
n42: Real64.from(0),
n43: Real64.from(0),
n44: Real64.from(1),
});
// Apply transformations
m1.makeTranslation(Real64.from(5), Real64.from(10), Real64.from(15));
```

The Plane class is used to represent and manipulate planes in 3D space:

```
// Define a Plane using a point and a normal vector
let point = new Vector3({
x: Real64.from(0),
y: Real64.from(0),
z: Real64.from(1),
});
let normal = new Vector3({
x: Real64.from(0),
y: Real64.from(1),
z: Real64.from(0),
});
let plane = new Plane({ point: point, normal: normal });
// Calculate the distance from a point to the plane
let point2 = new Vector3({
x: Real64.from(1),
y: Real64.from(2),
z: Real64.from(3),
});
let distance = plane.distanceToPoint(point2);
```

Box3 is used for bounding box operations in 3D space:

```
// Create two Vector3 instances to define the Box3 corners
let min = new Vector3({
x: Real64.from(-1),
y: Real64.from(-1),
z: Real64.from(-1),
});
let max = new Vector3({
x: Real64.from(1),
y: Real64.from(1),
z: Real64.from(1),
});
let box = new Box3({ min: min, max: max });
// Check if a point is inside the Box3
let point = new Vector3({
x: Real64.from(0.5),
y: Real64.from(0.5),
z: Real64.from(0.5),
});
let isInside = box.containsPoint(point);
```

Sphere is utilized for representing and working with spheres in 3D space:

```
// Define a Sphere with a center and a radius
let center = new Vector3({
x: Real64.from(0),
y: Real64.from(0),
z: Real64.from(0),
});
let radius = Real64.from(5);
let sphere = new Sphere({ center: center, radius: radius });
// Check if a point lies on the sphere's surface
let point = new Vector3({
x: Real64.from(3),
y: Real64.from(4),
z: Real64.from(0),
}); // Should be on the sphere
let isOnSurface = sphere.containsPoint(point);
```

Contributions to zk3d are welcome! Please read our contributing guidelines for details on how to contribute.

zk3d is MIT licensed.