feat: circularArray

Author: BCsabaEngine

CLAUDE.md

@@ -122,11 +122,13 @@ npm run export --silent -- Box > box.stl
 
 ```typescript
 Solid.cube(width, height, depth, { color? })
+Solid.roundedBox(width, height, depth, { color?, radius?, segments? })
 Solid.cylinder(radius, height, { color?, angle? })  // angle in degrees
 Solid.sphere(radius, { color?, angle? })
 Solid.cone(radius, height, { color?, angle? })
 Solid.prism(sides, radius, height, { color?, angle? })
 Solid.trianglePrism(radius, height, { color? })
+Solid.text(text, { color?, size?, height?, curveSegments?, bevelEnabled? })
 ```
 
 ### Custom Profile Prisms
@@ -159,6 +161,77 @@ Solid.revolutionSolidFromPath([straight(5), curve(2, 90), ...], { angle?, color?
 
 **Profile coordinates:** X=radius from center, Y=height, rotates around Y-axis
 
+### 3D Text Extrusion
+
+Create 3D text shapes with customizable size and extrusion depth:
+
+```typescript
+// Simple text
+const label = Solid.text('Hello', { size: 10, height: 2, color: 'blue' });
+
+// Text with bevel (rounded edges)
+const logo = Solid.text('LOGO', { size: 15, height: 3, bevelEnabled: true, color: 'gold' });
+
+// Text as cutter for engraving
+const plate = Solid.cube(50, 20, 5, { color: 'gray' });
+const text = Solid.text('ENGRAVED', { size: 4, height: 10, color: 'gray' });
+const engraved = Solid.SUBTRACT(plate, text);
+
+// Embossed text (raised text on surface)
+const base = Solid.cube(40, 30, 3, { color: 'gray' });
+const embossText = Solid.text('LOGO', { size: 6, height: 2, color: 'gold' }).move({ y: 3 }); // Position on top of base
+const embossed = Solid.UNION(base, embossText);
+```
+
+**Text Parameters:**
+
+- `text`: The string to render (required, cannot be empty)
+- `size`: Font size (default: 10)
+- `height`: Extrusion depth along Y-axis (default: 2)
+- `curveSegments`: Smoothness of curves (default: 12, lower=faster but blockier)
+- `bevelEnabled`: Add rounded edges to text (default: false)
+- `color`: Color of the text geometry
+
+**Important Notes:**
+
+- Uses Helvetiker Regular font (built-in)
+- Text is automatically centered on XZ plane and aligned to Y=0
+- For engraving/embossing, make text height > target depth to ensure complete cut
+- **Performance warning:** Long text (>10 characters) or high curveSegments can slow CSG operations
+- For better performance with long text, reduce `curveSegments` to 8
+
+### Rounded Box
+
+Create boxes with filleted/rounded edges:
+
+```typescript
+// Basic rounded box with auto-calculated radius (10% of smallest dimension)
+const box = Solid.roundedBox(10, 10, 10, { color: 'teal' });
+
+// Custom radius
+const customBox = Solid.roundedBox(20, 15, 10, { color: 'blue', radius: 2 });
+
+// High quality rounding (more segments)
+const smoothBox = Solid.roundedBox(10, 10, 10, { color: 'red', radius: 1.5, segments: 4 });
+```
+
+**Rounded Box Parameters:**
+
+- `width`, `height`, `depth`: Box dimensions (required, must be positive)
+- `radius`: Corner radius (default: 10% of smallest dimension)
+  - Must be ≤ half of smallest dimension
+  - Larger radius = more rounded corners
+- `segments`: Rounding quality (default: 2)
+  - Higher values = smoother but more geometry
+  - 2 is sufficient for most cases
+
+**Use Cases:**
+
+- Mechanical parts with filleted edges
+- Product design and prototyping
+- Realistic objects (boxes are rarely sharp-edged in real life)
+- Ergonomic designs
+
 ## Import Capabilities
 
 ### STL Import
@@ -295,6 +368,67 @@ Solid.GRID_XY(brick, { cols: 10, rows: 5, spacing: [1, 0.5] }); // 2D
 Solid.GRID_XYZ(brick, { cols: 5, rows: 5, levels: 3, spacing: [1, 1, 2] }); // 3D
 ```
 
+### Circular Arrays
+
+Arrange solids in circular/radial patterns (polar arrays):
+
+```typescript
+// Gear teeth - elements face outward by default
+// IMPORTANT: Element must extend in +X direction to face outward when rotated
+// Width (X) > depth (Z) makes tooth point radially
+const disk = Solid.cylinder(15, 8, { color: 'gray' }).align('bottom');
+const tooth = Solid.cube(3, 10, 2, { color: 'gray' }) // 3 wide (X), 2 deep (Z)
+	.center({ x: true, z: true })
+	.align('bottom')
+	.move({ y: 8 }); // Position on top of disk
+const teeth = Solid.ARRAY_CIRCULAR(tooth, { count: 24, radius: 17 });
+const gear = Solid.UNION(disk, teeth);
+
+// Bolt holes - no rotation needed for holes
+const hole = Solid.cylinder(2, 10, { color: 'blue' }).setNegative();
+const pattern = Solid.ARRAY_CIRCULAR(hole, { count: 8, radius: 20, rotateElements: false });
+
+// Half circle (amphitheater seating)
+const seat = Solid.cube(2, 1, 2, { color: 'red' });
+const seating = Solid.ARRAY_CIRCULAR(seat, { count: 15, radius: 25, startAngle: 0, endAngle: 180 });
+
+// Wheel spokes from center (radius = 0, just rotation)
+const spoke = Solid.cube(1, 20, 2, { color: 'silver' }).center({ x: true, z: true });
+const spokes = Solid.ARRAY_CIRCULAR(spoke, { count: 12, radius: 0 });
+
+// Decorative rosette with multiple layers
+const orb = Solid.sphere(2, { color: 'gold' });
+const innerRing = Solid.ARRAY_CIRCULAR(orb, { count: 8, radius: 8, rotateElements: false });
+const outerRing = Solid.ARRAY_CIRCULAR(orb, { count: 16, radius: 15, rotateElements: false });
+const rosette = Solid.UNION(innerRing, outerRing);
+```
+
+**Parameters:**
+
+- `count`: Number of copies (required, must be >= 1)
+- `radius`: Radius of circular arrangement (required, must be > 0)
+- `startAngle`: Starting angle in degrees (default: 0)
+- `endAngle`: Ending angle in degrees (default: 360)
+- `rotateElements`: Rotate elements to face outward (default: true)
+
+**Key Behaviors:**
+
+- Elements distributed evenly in XZ plane (horizontal circle around Y-axis)
+- By default, elements rotate to face outward (like gear teeth)
+- Set `rotateElements: false` for spheres, holes, or decorative elements
+- Partial circles: use `startAngle`/`endAngle` for arcs (e.g., 0° to 180° = half circle)
+- Elements evenly spaced within angular range (startAngle included, endAngle excluded for full circles)
+- **Y position preserved**: Elements maintain their vertical (Y) position, allowing layered circular patterns
+- **Element orientation**: For radial elements, create them so they extend in the +X direction. When rotated, they'll face outward correctly. Example: for a tooth pointing outward, use `cube(3, 10, 2)` not `cube(2, 10, 3)` - width > depth
+- **IMPORTANT**: Center elements with `.center({ x: true, z: true })` before passing to ARRAY_CIRCULAR. The `radius` parameter handles X/Z positioning, but you can use `.move({ y })` for vertical placement
+
+**Common Use Cases:**
+
+- Mechanical: Gear teeth, splines, bolt holes, heat sink fins
+- Architectural: Columns, amphitheater seating, circular windows
+- Decorative: Medallions, rosettes, clock markers, mandalas
+- Functional: Turbine blades, fan blades, ventilation slots, spokes
+
 ## Performance - Caching
 
 ```typescript
@@ -325,7 +459,7 @@ const w3 = Wall(30); // Different params, new computation
 
 ### Factory Methods
 
-`cube(w,h,d,opts)`, `cylinder(r,h,opts)`, `sphere(r,opts)`, `cone(r,h,opts)`, `prism(sides,r,h,opts)`, `trianglePrism(r,h,opts)`
+`cube(w,h,d,opts)`, `roundedBox(w,h,d,opts)`, `cylinder(r,h,opts)`, `sphere(r,opts)`, `cone(r,h,opts)`, `prism(sides,r,h,opts)`, `trianglePrism(r,h,opts)`, `text(text,opts)`
 
 ### Import Methods
 
@@ -351,9 +485,9 @@ const w3 = Wall(30); // Different params, new computation
 
 `SUBTRACT(src,...others)`, `UNION(src,...others)`, `INTERSECT(a,b)`, `MERGE(solids[])`
 
-### Grids (static, immutable)
+### Grids & Arrays (static, immutable)
 
-`GRID_X(solid,{cols,spacing?})`, `GRID_XY(solid,{cols,rows,spacing?})`, `GRID_XYZ(solid,{cols,rows,levels,spacing?})`
+`GRID_X(solid,{cols,spacing?})`, `GRID_XY(solid,{cols,rows,spacing?})`, `GRID_XYZ(solid,{cols,rows,levels,spacing?})`, `ARRAY_CIRCULAR(solid,{count,radius,startAngle?,endAngle?,rotateElements?})`
 
 ### Alignment (chainable)
 

plan.MD

@@ -4,12 +4,7 @@ Analysis of potential improvements and missing features for the CSG Builder proj
 
 ## 🟡 MEDIUM PRIORITY (Quality of Life)
 
-### 1. Missing Primitives
-
-- **Rounded Box** (filleted edges - very common)
-- **Text Extrusion** (3D text via Three.js TextGeometry)
-
-### 2. Missing CSG Operations
+### 1. Missing CSG Operations
 
 - **MIRROR** - Reflect across planes
 - **CHAMFER/FILLET** - Edge rounding (critical for manufacturing)