feat: add divide method to Cuboid class

Author: Fabrimat

src/space/cuboid.test.ts

@@ -116,4 +116,103 @@ describe("Cuboid", () => {
 		expect(result).toBe(false);
 		expect(spyCallback).toHaveBeenCalled();
 	});
+
+	// Tests for the divide method
+	describe("divide method", () => {
+		it("should return a clone of the original cuboid when all divisions are 1", () => {
+			const divisions = cuboid.divide(1, 1, 1);
+			expect(divisions.length).toBe(1);
+			expect(divisions[0].point1).toEqual(cuboid.point1);
+			expect(divisions[0].point2).toEqual(cuboid.point2);
+			expect(divisions[0]).not.toBe(cuboid); // Should be a clone, not the same instance
+		});
+
+		it("should divide a cuboid into 8 equal parts (2x2x2)", () => {
+			const divisions = cuboid.divide(2, 2, 2);
+			expect(divisions.length).toBe(8);
+
+			// Each subdivided cuboid should have 1/8 of the original volume
+			const expectedVolume = cuboid.getVolume() / 8;
+			divisions.forEach((div) => {
+				expect(div.getVolume()).toBeCloseTo(expectedVolume);
+			});
+
+			// Check if we have all the expected subdivisions
+			const centers = divisions.map((div) => div.getCenter());
+
+			// Expected centers for a 2x2x2 division of a cuboid from (0,0,0) to (10,10,10)
+			const expectedCenters = [
+				{ x: 2.5, y: 2.5, z: 2.5 },
+				{ x: 2.5, y: 2.5, z: 7.5 },
+				{ x: 2.5, y: 7.5, z: 2.5 },
+				{ x: 2.5, y: 7.5, z: 7.5 },
+				{ x: 7.5, y: 2.5, z: 2.5 },
+				{ x: 7.5, y: 2.5, z: 7.5 },
+				{ x: 7.5, y: 7.5, z: 2.5 },
+				{ x: 7.5, y: 7.5, z: 7.5 },
+			];
+
+			// Verify all expected centers exist (allowing for small floating point differences)
+			expectedCenters.forEach((expected) => {
+				const found = centers.some(
+					(center) =>
+						Math.abs(center.x - expected.x) < 0.001 &&
+						Math.abs(center.y - expected.y) < 0.001 &&
+						Math.abs(center.z - expected.z) < 0.001,
+				);
+				expect(found).toBe(true);
+			});
+		});
+
+		it("should divide a cuboid along a single axis", () => {
+			// Divide only along x-axis into 5 parts
+			const divisions = cuboid.divide(5, 1, 1);
+			expect(divisions.length).toBe(5);
+
+			// Check sizes
+			divisions.forEach((div) => {
+				expect(div.getSize().x).toBeCloseTo(2); // 10/5 = 2
+				expect(div.getSize().y).toBeCloseTo(10);
+				expect(div.getSize().z).toBeCloseTo(10);
+			});
+
+			// Check positions - each division should be 2 units wide on x-axis
+			for (let i = 0; i < 5; i++) {
+				expect(divisions[i].point1.x).toBeCloseTo(i * 2);
+				expect(divisions[i].point2.x).toBeCloseTo((i + 1) * 2);
+			}
+		});
+
+		it("should handle uneven divisions correctly", () => {
+			// Create a non-square cuboid
+			const unevenCuboid = new Cuboid(
+				{ x: 0, y: 0, z: 0 },
+				{ x: 10, y: 5, z: 20 },
+			);
+
+			const divisions = unevenCuboid.divide(2, 1, 4);
+			expect(divisions.length).toBe(8); // 2x1x4 = 8
+
+			// Check dimensions of first division
+			expect(divisions[0].getSize()).toEqual({
+				x: 5, // 10/2
+				y: 5, // 5/1
+				z: 5, // 20/4
+			});
+		});
+
+		it("should throw an error if any division parameter is less than 1", () => {
+			expect(() => cuboid.divide(0, 1, 1)).toThrow();
+			expect(() => cuboid.divide(1, 0, 1)).toThrow();
+			expect(() => cuboid.divide(1, 1, 0)).toThrow();
+			expect(() => cuboid.divide(-2, 3, 4)).toThrow();
+		});
+
+		it("should create the correct number of divisions", () => {
+			expect(cuboid.divide(3, 4, 5).length).toBe(3 * 4 * 5);
+			expect(cuboid.divide(10, 1, 1).length).toBe(10);
+			expect(cuboid.divide(1, 10, 1).length).toBe(10);
+			expect(cuboid.divide(1, 1, 10).length).toBe(10);
+		});
+	});
 });

src/space/cuboid.ts

@@ -383,4 +383,59 @@ export class Cuboid extends Polygon {
 	public clone(): Cuboid {
 		return new Cuboid(this.point1, this.point2);
 	}
+
+	/**
+	 * Divides the cuboid into a specified number of equal-sized smaller cuboids along each axis.
+	 * @param divisionsX Number of divisions along the X axis (must be ≥ 1)
+	 * @param divisionsY Number of divisions along the Y axis (must be ≥ 1)
+	 * @param divisionsZ Number of divisions along the Z axis (must be ≥ 1)
+	 * @returns An array of smaller Cuboids that together make up the original Cuboid
+	 * @throws Error if any division parameter is less than 1
+	 */
+	public divide(
+		divisionsX: number = 1,
+		divisionsY: number = 1,
+		divisionsZ: number = 1,
+	): Cuboid[] {
+		// Validate input parameters
+		if (divisionsX < 1 || divisionsY < 1 || divisionsZ < 1) {
+			throw new Error("Division parameters must be at least 1");
+		}
+
+		// If all divisions are 1, return a copy of this cuboid
+		if (divisionsX === 1 && divisionsY === 1 && divisionsZ === 1) {
+			return [this.clone()];
+		}
+
+		const result: Cuboid[] = [];
+
+		// Calculate size of each division
+		const size = this.getSize();
+		const divSizeX = size.x / divisionsX;
+		const divSizeY = size.y / divisionsY;
+		const divSizeZ = size.z / divisionsZ;
+
+		// Generate all smaller cuboids
+		for (let x = 0; x < divisionsX; x++) {
+			for (let y = 0; y < divisionsY; y++) {
+				for (let z = 0; z < divisionsZ; z++) {
+					const p1: Vector3 = {
+						x: this.point1.x + x * divSizeX,
+						y: this.point1.y + y * divSizeY,
+						z: this.point1.z + z * divSizeZ,
+					};
+
+					const p2: Vector3 = {
+						x: this.point1.x + (x + 1) * divSizeX,
+						y: this.point1.y + (y + 1) * divSizeY,
+						z: this.point1.z + (z + 1) * divSizeZ,
+					};
+
+					result.push(new Cuboid(p1, p2));
+				}
+			}
+		}
+
+		return result;
+	}
 }