Math & Utility Functions
Relevant source files
The following files were used as context for generating this wiki page:
Math and Utility functions form the foundational logic layer of HoloPrint, providing the necessary computational tools for geometry generation, 3D transformations, and data structure management. These utilities are centralized to ensure consistency across modules such as the BlockGeoMaker and PreviewRenderer.
The utility system is structured into specialized modules for 2D/3D vector math, standard trigonometric operations, and custom collection types like JSONSet and JSONMap that facilitate complex object comparisons within the pack generation pipeline.
Sources: src/utils.js:1-18, src/HoloPrint.js:20-25
Core Mathematical Operations
The system extends the native JavaScript Math object with specialized functions for degree-based trigonometry, matrix manipulations, and geometric algorithms required for Minecraft structure processing.
Trigonometry and Rotation
HoloPrint uses degree-based trigonometric functions to simplify rotations defined in Minecraft's block state definitions.
| Function | Description |
|---|---|
sinDeg(deg) | Returns the sine of an angle in degrees. |
cosDeg(deg) | Returns the cosine of an angle in degrees. |
tanDeg(deg) | Returns the tangent of an angle in degrees. |
rotateDeg(p, deg) | Rotates a 2D point p by a specified number of degrees. |
Sources: src/utils/math.js:3-15
Algorithmic Utilities
The math module provides implementations for Euclidean algorithms and coordinate range generation.
- GCD & LCM: Used for calculating optimal texture scales and resolutions when compositing control item textures.
- Transpose Matrix: Pivots matrices, primarily used for reorienting Coordinate Lock data.
- Range: Generates arrays of numbers with optional stepping, used in iterative geometry calculations.
Sources: src/utils/math.js:20-56, src/HoloPrint.js:335-340
Vector Mathematics (Vec3)
The vec3 utility provides a suite of functional tools for manipulating 3D coordinates represented as [x, y, z] arrays. These are critical for the PolyMeshMaker to position vertices accurately in 3D space.
The diagram shows the functional flow of vector operations where inputs are transformed into new vector outputs or normalized/rounded results.
Key Vec3 Functions
add(a, b)/sub(a, b): Performs element-wise addition or subtraction of two 3D vectors.crossProduct(a, b): Calculates the vector perpendicular to two given vectors, used to determine surface normals for faces.normalize(vec): Scales a vector to unit length (1), essential for lighting calculations in the preview.toFixed(vec, decimals): Rounds vector components to a specific precision, preventing floating-point errors in exported geometry files.
Sources: src/utils/vec3.js:1-42, src/PolyMeshMaker.js:52-55
Geometric Logic and Transformations
HoloPrint utilizes these math utilities to perform complex Euler rotations and center-of-mass calculations during the conversion of .mcstructure data into geometry.
Euler Rotations
The system applies rotations in the X-Y-Z order to orient ghost blocks. This process involves translating the position relative to a pivot (defaulting to the block center [8, 8, 8]), applying 2D rotations across planes, and translating back.
// src/BlockGeoMaker.js:192-200
#applyEulerRotation(pos, rotation, pivot) {
let res = vec3.add(pos, vec3.mul(pivot, -1));
[res[1], res[2]] = rotateDeg([res[1], res[2]], -rotation[0]);
[res[0], res[2]] = rotateDeg([res[0], res[2]], -rotation[1]);
[res[0], res[1]] = rotateDeg([res[0], res[1]], -rotation[2]);
res = vec3.add(res, pivot);
return res;
}
Sources: src/BlockGeoMaker.js:192-200, src/utils/math.js:12-18
Center of Mass Calculation
To ensure proper scaling (typically 95% to prevent Z-fighting), the system calculates the center of mass of a block's constituent cubes. It assumes uniform mass density where mass equals volume (w * h * d). If cubes are flat, surface area is used as a fallback for mass calculation.
Sources: src/BlockGeoMaker.js:520-545
Specialized Collections
Standard JavaScript Set and Map compare objects by reference. HoloPrint implements JSONSet and JSONMap to compare objects by their stringified values, which is vital for de-duplicating block palette entries and texture references.
| Collection | Purpose |
|---|---|
JSONSet | Stores unique objects based on content. Used in BlockGeoMaker to track unique texture references. |
JSONMap | Maps objects to values. Used in PolyMeshMaker to identify block positions that contain multiple layers (e.g., waterlogged blocks). |
TripleSet | Optimized set for 3D coordinates, used in PolyMeshMaker to build the vertex list for poly_mesh exports. |
Sources: src/utils.js:5-15, src/PolyMeshMaker.js:1-15, src/BlockGeoMaker.js:11-15
Conclusion
The Math & Utility functions provide a robust framework for the high-precision requirements of 3D hologram generation. By centralizing vector math, degree-based trigonometry, and content-based collection types, the architecture ensures that complex transformations like Euler rotations and geometry optimization remain performant and accurate across the application.