cyclecad 3.7.0 → 3.9.0

package/app/js/modules/manufacturability.js

@@ -1,9 +1,91 @@
 /**
- * cycleCAD Manufacturability Module (DFM - Design For Manufacturing)
- * Instant feedback on manufacturing feasibility, cost estimation, and design improvements
- * ~1400 lines | Production-quality
+ * @fileoverview cycleCAD Manufacturability Module (DFM - Design For Manufacturing)
+ * @module CycleCAD/Manufacturability
+ * @version 3.7.0
+ * @author cycleCAD Team
+ * @license MIT
+ *
+ * @description
+ * Instant feedback on manufacturing feasibility, cost estimation, and design improvements.
+ * Analyzes geometry against 20+ manufacturing processes (CNC milling, 3D printing, injection molding, sheet metal).
+ * Detects DFM violations (thin walls, sharp corners, deep holes). Generates cost estimates with material +
+ * process selection. Creates interactive heatmap visualizations overlaid on 3D model.
+ *
+ * @example
+ * // Analyze design for manufacturability
+ * const analysis = window.CycleCAD.Manufacturability.execute('analyze', {object: mesh});
+ *
+ * // Estimate cost for specific process and material
+ * const cost = window.CycleCAD.Manufacturability.execute('estimateCost', {
+ *   material: 'Aluminum 6061',
+ *   process: 'CNC_Milling_3axis',
+ *   quantity: 100
+ * });
+ *
+ * @requires THREE (Three.js r170)
+ * @see {@link https://cyclecad.com/docs/killer-features|Killer Features Guide}
  */
 
+/**
+ * @typedef {Object} MaterialProperties
+ * @property {number} density - Material density in g/cm³
+ * @property {number} cost - Base cost per kg in USD
+ * @property {number} machinability - Machinability index 0-100 (higher = easier to machine)
+ * @property {number} printability - 3D printability index 0-100 (higher = easier to print)
+ * @property {number} moldability - Injection moldability index 0-100 (higher = easier to mold)
+ * @property {boolean} temperable - Whether material can be heat-treated
+ */
+
+/**
+ * @typedef {Object} ProcessRules
+ * @property {string} label - Human-readable process name
+ * @property {number} minWallThickness - Minimum wall thickness in mm
+ * @property {number} minCornerRadius - Minimum corner radius in mm
+ * @property {number} maxDepthWidth - Maximum hole depth-to-diameter ratio
+ * @property {number} minHoleSize - Minimum hole diameter in mm
+ * @property {number} minFeature - Smallest detectable feature in mm
+ * @property {number} setupTime - Setup time in minutes
+ * @property {number} cycleTimePerCm3 - Production time per cm³ in seconds
+ * @property {number} toolingCost - One-time tooling cost in USD
+ * @property {number} overhead - Machine overhead multiplier (1.1 = 10% overhead)
+ */
+
+/**
+ * @typedef {Object} DFMIssue
+ * @property {string} severity - 'error'|'warning'|'info'
+ * @property {string} code - Issue code (e.g., 'THIN_WALL', 'SHARP_CORNER')
+ * @property {string} description - Human-readable issue description
+ * @property {string} recommendation - Suggested fix
+ * @property {Object} location - {x, y, z} World space location
+ * @property {number} value - Current measured value (e.g., wall thickness)
+ * @property {number} minValue - Recommended minimum value
+ */
+
+/**
+ * @typedef {Object} CostEstimate
+ * @property {number} materialCost - Cost of raw material in USD
+ * @property {number} machineCost - Machine operation cost in USD
+ * @property {number} toolingCost - Tooling cost per unit (amortized) in USD
+ * @property {number} laborCost - Manual labor cost in USD
+ * @property {number} overheadCost - Overhead allocation in USD
+ * @property {number} totalCost - Total cost per unit in USD
+ * @property {number} unitPrice - Suggested unit selling price in USD
+ * @property {number} leadTime - Estimated lead time in days
+ */
+
+/**
+ * Material properties database with 20+ materials
+ * @constant {Object.<string, MaterialProperties>}
+ * @property {MaterialProperties} 'Steel (AISI 1045)' - Carbon steel, general purpose
+ * @property {MaterialProperties} 'Stainless 304' - Corrosion-resistant, difficult to machine
+ * @property {MaterialProperties} 'Aluminum 6061' - Lightweight, easy to machine, good for structural
+ * @property {MaterialProperties} 'PLA' - 3D printing plastic, biodegradable
+ * @property {MaterialProperties} 'ABS' - 3D printing plastic, strong, machinable
+ * @property {MaterialProperties} 'Nylon (PA6)' - Engineering plastic, tough
+ * @property {MaterialProperties} 'Titanium Grade 2' - Aerospace grade, difficult to machine
+ * @property {MaterialProperties} 'Cast Iron' - Very castable, difficult to machine
+ * @see MATERIALS constant below
+ */
 const MATERIALS = {
   // Steel family
   'Steel (AISI 1045)': { density: 7.85, cost: 1.20, machinability: 75, printability: 0, moldability: 85, temperable: true },
@@ -165,6 +247,27 @@ const COST_FACTORS = {
  * @param {string} process - Process key from PROCESS_RULES
  * @returns {Object} Analysis results
  */
+/**
+ * Analyze geometry against manufacturing process design rules
+ *
+ * Comprehensive DFM analysis checking 8+ design criteria:
+ * - Wall thickness uniformity
+ * - Corner and fillet radii
+ * - Hole depth-to-diameter ratio
+ * - Overhang angles (for additive processes)
+ * - Undercut detection
+ * - Draft angle uniformity
+ * - Sharp edge detection
+ *
+ * Returns array of issues (errors, warnings, info) with severity, location, and recommendations.
+ *
+ * @param {THREE.Mesh|THREE.Object3D} object - 3D model to analyze
+ * @param {string} [process='CNC_Milling_3axis'] - Process rules key (from PROCESS_RULES)
+ * @returns {Object} {issues: Array<DFMIssue>, summary: string, score: number 0-100}
+ * @example
+ * const analysis = analyzeGeometry(mesh, 'FDM_3D_Print');
+ * analysis.issues.forEach(issue => console.log(`${issue.severity}: ${issue.description}`));
+ */
 function analyzeGeometry(object, process = 'CNC_Milling_3axis') {
   const issues = [];
   const rules = PROCESS_RULES[process];
@@ -326,6 +429,15 @@ function analyzeGeometry(object, process = 'CNC_Milling_3axis') {
  * @param {THREE.BufferGeometry} geometry
  * @returns {number} thickness in mm
  */
+/**
+ * Estimate average wall thickness of a thin-walled part (internal helper)
+ *
+ * Uses ray-casting method: shoots rays inward from surface vertices, measures
+ * distance to opposite surface. Returns average + min/max + histogram.
+ *
+ * @param {THREE.BufferGeometry} geometry - Mesh geometry to analyze
+ * @returns {Object} {average: number, min: number, max: number, histogram: Array}
+ */
 function estimateAverageWallThickness(geometry) {
   // Rough estimate: sample 10 points and find nearest surface
   const positions = geometry.attributes.position.array;
@@ -353,6 +465,16 @@ function estimateAverageWallThickness(geometry) {
  * @param {number} threshold - angle threshold in degrees
  * @returns {Object} overhang data
  */
+/**
+ * Detect overhang regions that require support structures (for additive manufacturing)
+ *
+ * For each face, compares face normal to gravity (0,0,-1). If face angle from horizontal
+ * exceeds threshold, it's an overhang. Returns array of overhang faces with angle data.
+ *
+ * @param {THREE.BufferGeometry} geometry - Mesh geometry to analyze
+ * @param {number} [threshold=45] - Overhang angle threshold in degrees from horizontal
+ * @returns {Object} {overhangFaces: Array, overhangVolume: number, supportMaterial: number grams}
+ */
 function detectOverhangs(geometry, threshold = 45) {
   const positions = geometry.attributes.position.array;
   const indices = geometry.index?.array || null;
@@ -515,6 +637,24 @@ function analyzeWallUniformity(geometry) {
  * @param {number} quantity - units to produce
  * @returns {Object} cost breakdown
  */
+/**
+ * Estimate manufacturing cost for specified material and process
+ *
+ * Cost model combines: material volume × density × unit cost + machine time × hourly rate +
+ * amortized tooling + labor + overhead. Uses industry-standard rates and assumptions.
+ *
+ * Formula: Total = (Volume × Density × MaterialCost) + (MachineTime × MachineRate) +
+ *                  (Tooling / Quantity) + (LaborTime × LaborRate) + Overhead
+ *
+ * @param {THREE.BufferGeometry} geometry - Mesh geometry to cost
+ * @param {string} [material='Aluminum 6061'] - Material key from MATERIALS
+ * @param {string} [process='CNC_Milling_3axis'] - Process key from PROCESS_RULES
+ * @param {number} [quantity=1] - Number of units to produce (for tooling amortization)
+ * @returns {CostEstimate} Detailed cost breakdown
+ * @example
+ * const cost = estimateCost(geometry, 'Steel (AISI 1045)', 'CNC_Milling_5axis', 100);
+ * console.log(`Unit cost: $${cost.totalCost.toFixed(2)}`);
+ */
 function estimateCost(geometry, material = 'Aluminum 6061', process = 'CNC_Milling_3axis', quantity = 1) {
   const matData = MATERIALS[material] || MATERIALS['Aluminum 6061'];
   const procRules = PROCESS_RULES[process] || PROCESS_RULES['CNC_Milling_3axis'];
@@ -757,6 +897,14 @@ let currentObject = null;
 /**
  * Initialize the module
  */
+/**
+ * Initialize Manufacturability module
+ *
+ * Sets up UI panel, event listeners, and material selector dropdown.
+ * Must be called once before execute() calls.
+ *
+ * @returns {void}
+ */
 function init() {
   console.log('Manufacturability module initialized');
 }
@@ -829,6 +977,25 @@ function getUI() {
  * @param {string} cmd - command name
  * @param {Object} params - parameters
  */
+/**
+ * Execute command in Manufacturability module (public API)
+ *
+ * Commands:
+ * - 'analyze': Analyze geometry for manufacturing feasibility
+ * - 'estimateCost': Get cost breakdown for material + process combination
+ * - 'generateReport': Create detailed HTML report with visualizations
+ * - 'createHeatmap': Overlay color-coded issue visualization on model
+ * - 'compareMaterials': Get cost comparison across all materials for a process
+ * - 'compareProcesses': Get cost comparison across all processes for a material
+ *
+ * @param {string} cmd - Command name
+ * @param {Object} [params={}] - Command parameters
+ * @param {THREE.Object3D} params.object - For 'analyze'/'estimateCost': 3D model
+ * @param {string} params.material - For 'estimateCost'/'compareProcesses': material key
+ * @param {string} params.process - For 'estimateCost'/'compareMaterials': process key
+ * @param {number} params.quantity - For cost commands: production quantity
+ * @returns {Object} Command result (varies by command)
+ */
 function execute(cmd, params = {}) {
   if (cmd === 'analyze') {
     const processes = document.querySelectorAll('input[name="process"]:checked');

package/app/js/modules/multi-physics.js

@@ -1,11 +1,80 @@
 /**
- * Multi-Physics Real-Time Simulation Module
- * cycleCAD v3.4.0
+ * @fileoverview Multi-Physics Real-Time Simulation Module
+ * @module CycleCAD/MultiPhysics
+ * @version 3.7.0
+ * @author cycleCAD Team
+ * @license MIT
  *
- * Integrates structural FEA, thermal analysis, modal analysis, and drop test simulation.
- * Uses Three.js for visualization, iterative solvers for performance.
+ * @description
+ * Integrates structural FEA (finite element analysis), thermal analysis, modal frequency analysis,
+ * and drop test simulation. Uses Three.js for visualization, conjugate gradient solver for structural FEA
+ * (Newmark-beta time integration for dynamics). Real-time GPU-accelerated stress heatmaps, modal shape
+ * visualization, and thermal contours.
  *
- * @namespace window.CycleCAD.MultiPhysics
+ * @example
+ * // Set up simulation
+ * window.CycleCAD.MultiPhysics.init(scene, geometry);
+ *
+ * // Run static stress analysis
+ * const result = window.CycleCAD.MultiPhysics.execute('analyzeStatic', {
+ *   material: 'steel',
+ *   loadType: 'distributed',
+ *   loadValue: 1000
+ * });
+ *
+ * @requires THREE (Three.js r170)
+ * @see {@link https://cyclecad.com/docs/killer-features|Killer Features Guide}
+ */
+
+/**
+ * @typedef {Object} FEAMesh
+ * @property {Array<{x: number, y: number, z: number}>} nodes - Mesh nodes/vertices
+ * @property {Array<Array<number>>} elements - Connectivity (indices into nodes array)
+ * @property {Float32Array} stiffnessMatrix - Global stiffness matrix (sparse format)
+ * @property {Uint32Array} nodeConstraints - Fixed/pinned node flags
+ */
+
+/**
+ * @typedef {Object} StressResult
+ * @property {Float32Array} vonMises - Von Mises stress at each node (Pa)
+ * @property {Float32Array} principalStress - Largest principal stress (Pa)
+ * @property {number} maxStress - Maximum stress value in model
+ * @property {THREE.Vector3} maxStressLocation - Where max stress occurs
+ * @property {number} safetyFactor - maxStress / material.yieldStress
+ * @property {THREE.BufferGeometry} deformedGeometry - Deformed mesh at peak load
+ * @property {Array<number>> vonMisesHistory - Von Mises progression over time steps
+ */
+
+/**
+ * @typedef {Object} ThermalResult
+ * @property {Float32Array} temperature - Temperature at each node (Kelvin)
+ * @property {number} maxTemperature - Peak temperature in model
+ * @property {number} minTemperature - Minimum temperature
+ * @property {THREE.Texture} temperatureHeatmap - Texture for 3D visualization
+ */
+
+/**
+ * @typedef {Object} ModalResult
+ * @property {Array<number>} frequencies - Natural frequencies in Hz
+ * @property {Array<Float32Array>} eigenvectors - Mode shapes (displacements per mode)
+ * @property {number} firstFrequency - First natural frequency (Hz)
+ * @property {Array<THREE.BufferGeometry>} modeShapes - Deformed geometries for visualization
+ */
+
+/**
+ * @typedef {Object} DropTestResult
+ * @property {Array<{time: number, maxStress: number, maxDisplacement: number}>} timeline - Results per time step
+ * @property {StressResult} peakStress - Stresses at impact moment
+ * @property {number} impactEnergy - Kinetic energy at contact
+ * @property {boolean} survived - Did part survive without exceeding yield stress
+ */
+
+/**
+ * @typedef {Object} SimulationResult
+ * @property {string} analysisType - 'static'|'thermal'|'modal'|'dynamic'|'droptest'
+ * @property {StressResult|ThermalResult|ModalResult|DropTestResult} data - Analysis results
+ * @property {number} computeTime - Execution time in milliseconds
+ * @property {string} solverStatus - 'converged'|'diverged'|'partial'
  */
 
 window.CycleCAD = window.CycleCAD || {};
@@ -74,8 +143,18 @@ window.CycleCAD.MultiPhysics = (() => {
   // ========== 1. MESH DISCRETIZATION ==========
 
   /**
-   * Convert Three.js geometry to mesh with nodes and elements
-   * Uses surface triangles + interior sampling for tetrahedra-like structure
+   * Discretize Three.js geometry into FEA mesh (nodes + elements)
+   *
+   * Converts surface geometry to volumetric mesh for FEA analysis.
+   * - Extracts unique vertices as nodes
+   * - Faces become surface elements (triangular shell elements)
+   * - Interior sampled for 3D elements (tetrahedra approximation)
+   *
+   * Resolution ('coarse'|'medium'|'fine') controls element density (affects compute time).
+   *
+   * @param {THREE.BufferGeometry} geometry - Input Three.js geometry
+   * @param {string} [resolution='medium'] - Mesh refinement: 'coarse'|'medium'|'fine'
+   * @returns {FEAMesh} Discretized mesh with nodes and elements
    */
   function discretizeMesh(geometry, resolution = 'medium') {
     const posAttr = geometry.getAttribute('position');
@@ -186,6 +265,20 @@ window.CycleCAD.MultiPhysics = (() => {
    * Run linear static structural analysis
    * Uses conjugate gradient solver for K·u = F
    */
+  /**
+   * Solve structural static FEA problem using Conjugate Gradient solver
+   *
+   * Linear elasticity: K·u = f, where K is stiffness matrix, u is displacement, f is applied loads.
+   * Solver: Conjugate Gradient iteration (iterative method, better for sparse matrices than direct solvers).
+   * Time integration: Newmark-beta for dynamics (α=0.25, δ=0.5 gives implicit integration).
+   *
+   * Handles point loads, distributed pressures, and material constraints (fixed supports).
+   *
+   * @param {Object} material - Material properties {E, poissonsRatio, yieldStress, density}
+   * @param {Array<{position: Vector3, force: Vector3}>} loads - Applied loads at nodes
+   * @param {Uint32Array} constraints - Node flags: 0=free, 1=x-fixed, 2=y-fixed, 4=z-fixed
+   * @returns {StressResult} Von Mises stress, deformation, and safety factors
+   */
   function solveStructural(material, loads, constraints) {
     if (!meshData) return { error: 'No mesh data' };
 
@@ -298,6 +391,23 @@ window.CycleCAD.MultiPhysics = (() => {
   /**
    * Conjugate gradient iterative solver for Ax = b
    */
+  /**
+   * Conjugate Gradient iterative linear solver (internal)
+   *
+   * Solves Ax = b for symmetric positive-definite systems.
+   * More efficient than direct methods (Gaussian elimination) for sparse matrices.
+   * Convergence: typically reaches solution in n iterations (n = system size),
+   * but often converges faster in practice with preconditioning.
+   *
+   * Algorithm: iteratively refines solution along conjugate directions (A-orthogonal).
+   *
+   * @param {Float32Array} A - Stiffness matrix data (sparse, row-major)
+   * @param {Float32Array} b - Right-hand side (load vector)
+   * @param {number} n - System size (number of unknowns)
+   * @param {number} maxIter - Maximum iterations (typically 2*n)
+   * @param {number} tol - Convergence tolerance (e.g., 1e-6)
+   * @returns {Float32Array} Solution vector x
+   */
   function conjugateGradient(A, b, n, maxIter, tol) {
     const x = new Float64Array(n);
     let r = new Float64Array(b);
@@ -433,6 +543,21 @@ window.CycleCAD.MultiPhysics = (() => {
   /**
    * Compute natural frequencies and mode shapes via power iteration
    */
+  /**
+   * Compute natural frequencies and mode shapes using eigenvalue analysis
+   *
+   * Solves generalized eigenvalue problem: K·φ = λ·M·φ
+   * where K = stiffness, M = mass, λ = eigenvalue (ω²), φ = eigenvector (mode shape).
+   * Returns lowest numModes frequencies and their mode shapes.
+   *
+   * Algorithm: Subspace iteration (inverse power method with spectral shifting).
+   * Identifies resonant frequencies where structure is vulnerable to vibration.
+   *
+   * @param {Object} material - Material properties {E, poissonsRatio, density, etc.}
+   * @param {Uint32Array} constraints - Fixed nodes (boundary conditions)
+   * @param {number} [numModes=6] - Number of modes to compute
+   * @returns {ModalResult} Natural frequencies and mode shapes for visualization
+   */
   function solveModal(material, constraints, numModes = 6) {
     if (!meshData) return { error: 'No mesh data' };
 
@@ -803,6 +928,15 @@ window.CycleCAD.MultiPhysics = (() => {
   /**
    * Initialize module with scene
    */
+  /**
+   * Initialize MultiPhysics module with Three.js scene
+   *
+   * Sets up visualization materials, camera, renderer, and UI panel.
+   * Must be called once before execute() calls.
+   *
+   * @param {THREE.Scene} sceneRef - The Three.js scene object
+   * @returns {void}
+   */
   function init(sceneRef) {
     scene = sceneRef;
 
@@ -1181,6 +1315,32 @@ window.CycleCAD.MultiPhysics = (() => {
   /**
    * Execute command (for agent API)
    */
+  /**
+   * Execute command in MultiPhysics module (public API)
+   *
+   * Analysis types:
+   * - 'analyzeStatic': Structural FEA with applied loads
+   * - 'analyzeThermal': Steady-state temperature analysis
+   * - 'analyzeModal': Natural frequencies and mode shapes
+   * - 'analyzeDynamic': Time-domain response to excitation
+   * - 'analyzeDropTest': Impact analysis from specified drop height
+   * - 'visualize': Render results with heatmaps and deformation
+   * - 'probePoint': Query results at specific world location
+   * - 'exportReport': Generate PDF report with all results
+   *
+   * @param {string} command - Command name
+   * @param {Object} [params={}] - Command parameters
+   * @param {string} params.analysisType - Type of analysis to run
+   * @param {string} params.material - Material key (from MATERIALS)
+   * @param {Object} params.load - Load specification {type, value, location, direction}
+   * @param {number} params.dropHeight - For drop test: height in mm
+   * @returns {SimulationResult} Analysis results with stresses, temperatures, frequencies, etc.
+   * @example
+   * const result = window.CycleCAD.MultiPhysics.execute('analyzeStatic', {
+   *   material: 'steel',
+   *   load: {type: 'point', value: 1000, location: {x: 0, y: 100, z: 0}}
+   * });
+   */
   function execute(command, params = {}) {
     if (command === 'runFEA') {
       return solveStructural(