Base Math & Geometry
Relevant source files
The following files were used as context for generating this wiki page:
Base Math & Geometry provides the fundamental mathematical foundation for Parashell, a 3D modeling kernel fork of FreeCAD. This module handles coordinate systems, spatial transformations, and geometric primitives necessary for CAD operations. It implements essential linear algebra structures such as 3D vectors, transformation matrices, rotations, and placements that define how objects are positioned and oriented in 3D space.
The system is designed for high-precision engineering applications, utilizing double-precision floating-point arithmetic. It provides the core logic for calculating distances, performing rotations, managing bounding volumes for collision detection/visibility, and mapping coordinates between local and global spaces. These primitives serve as the building blocks for more complex systems like the BIM Workbench and FEM Mesh.
Core Data Structures
The mathematical kernel revolves around several interdependent classes that handle vector math and spatial state.
Vector3D
The Vector3D class is the primary representation of a point or direction in 3D space. It supports standard algebraic operations including addition, subtraction, scalar multiplication, and dot/cross products. It also includes utility functions for normalization and projection.
Sources: Base/Vector3D.cpp
Rotation
The Rotation class manages orientations using quaternions. This avoids gimbal lock issues associated with Euler angles and provides smooth interpolation between states. It can be initialized via axis-angle pairs, Euler angles (Yaw-Pitch-Roll), or from one direction to another.
Sources: Base/Rotation.cpp
Matrix4D
A 4x4 matrix implementation used for affine transformations. It combines rotation, scaling, and translation into a single structure. It is heavily utilized for coordinate system conversions and projection logic.
Sources: Base/Matrix.cpp
Placement
The Placement class represents a complete spatial state, combining a Vector3D (position) and a Rotation (orientation). It is used to define the location of every object within a Parashell document.
Sources: Base/Placement.cpp
Spatial Transformation Logic
The following diagram illustrates how standard geometric types interact to transform coordinates from an object's local space to the global 3D scene.
Spatial data flow derived from transformation implementations. Sources: Base/Placement.cpp, Base/Matrix.cpp
Coordinate Mapping
Placements are multiplicative. Applying a placement to a vector involves rotating the vector by the placement's rotation and then adding the position vector. When two placements are multiplied (e.g., a child object relative to a parent), their matrices are composed to create a single transformation.
Sources: Base/Placement.cpp:45-80
| Operation | Input Types | Result Type | Description |
|---|---|---|---|
multVec | Matrix4D, Vector3D | Vector3D | Transforms a point using the matrix. |
invert | Rotation | Rotation | Calculates the inverse orientation. |
inverse | Placement | Placement | Reverses the position and orientation. |
pow | Placement, double | Placement | Interpolates a placement (0.0 to 1.0). |
Geometric Primitives & Analysis
The module includes analysis tools to evaluate geometric properties and spatial boundaries.
Bounding Boxes
The BoundBox class defines an axis-aligned bounding box (AABB) using two Vector3D points (Minimum and Maximum). It is a critical component for performance optimization in rendering and intersection testing.
Sources: Base/BoundBox.cpp
Logic for extending a bounding box to encapsulate new points. Sources: Base/BoundBox.cpp:20-55
Precision and Tolerances
Parashell uses a global epsilon for floating-point comparisons to handle numerical instability in 3D operations. This is pervasive in functions like isEqual or when checking if a vector is null.
Sources: Base/Vector3D.cpp:150-165, Base/Matrix.cpp:300-315
Rotation Methods
The system supports multiple ways to define or modify an orientation.
| Method | Parameters | Logic |
|---|---|---|
| Axis-Angle | Vector3D, double | Rotates by an angle (radians) around a specific axis vector. |
| Euler | double, double, double | Uses Yaw, Pitch, and Roll conventions. |
| Vector-to-Vector | Vector3D, Vector3D | Calculates the rotation required to align the first vector with the second. |
| Quaternion | double x, y, z, w | Directly sets the 4D complex number representation. |
Sources: Base/Rotation.cpp:10-120
Conclusion
The Base Math & Geometry module provides the stateless and stateful primitives that underpin the entire Parashell architecture. By abstracting complex linear algebra into standardized Vector3D, Rotation, and Placement objects, the system ensures consistent spatial behavior across different workbenches. The robust implementation of 4x4 transformation matrices and quaternion-based rotations allows for efficient, error-resistant 3D modeling and complex assembly solving.