cyclecad 3.7.0 → 3.8.0

package/app/js/modules/photo-to-cad.js

@@ -1,14 +1,28 @@
 /**
- * Photo-to-CAD Reverse Engineering Module
- * Converts photographs of parts into parametric 3D CAD models
+ * @fileoverview Photo-to-CAD Reverse Engineering Module
+ * @module CycleCAD/PhotoToCAD
+ * @version 3.7.0
+ * @author cycleCAD Team
+ * @license MIT
  *
- * Features:
- * - Image input: drag-drop, camera, clipboard
- * - Edge detection: Sobel + Canny + contour tracing
- * - Geometry reconstruction: 2D contours → 3D primitives
- * - Interactive refinement: overlay, sliders, reference dimensions
- * - AI enhancement: Gemini Flash Vision API integration
- * - UI panel with side-by-side photo + 3D preview
+ * @description
+ * Converts photographs of parts into parametric 3D CAD models through image analysis.
+ * Features drag-drop/camera/clipboard image input, Sobel+Canny edge detection with non-maximum suppression,
+ * contour tracing, 2D → 3D primitive reconstruction, interactive refinement with sliders,
+ * Gemini Flash Vision API integration, and side-by-side photo + 3D preview.
+ *
+ * @example
+ * // Initialize the module
+ * window.CycleCAD.PhotoToCAD.init();
+ *
+ * // Load image and detect features
+ * window.CycleCAD.PhotoToCAD.execute('loadImage', {imageData: dataUrl});
+ *
+ * // Detect geometric primitives
+ * window.CycleCAD.PhotoToCAD.execute('detectPrimitives');
+ *
+ * @requires THREE (Three.js r170)
+ * @see {@link https://cyclecad.com/docs/killer-features|Killer Features Guide}
  */
 
 (function() {
@@ -18,6 +32,40 @@
   // STATE
   // ============================================================================
 
+  // ========== TYPEDEFS ==========
+  /**
+   * @typedef {Object} DetectedFeature
+   * @property {string} type - Feature type: 'circle'|'rectangle'|'line'|'arc'
+   * @property {Array<Point>} contour - Ordered points defining the feature boundary
+   * @property {Object} geometry - Computed geometric properties
+   * @property {number} confidence - Detection confidence 0-1
+   */
+
+  /**
+   * @typedef {Object} ContourPoint
+   * @property {number} x - X coordinate in image pixels
+   * @property {number} y - Y coordinate in image pixels
+   * @property {number} angle - Edge angle in radians (-π to π)
+   * @property {number} magnitude - Edge magnitude 0-255
+   */
+
+  /**
+   * @typedef {Object} EdgeMap
+   * @property {Uint8ClampedArray} data - Edge magnitude per pixel
+   * @property {number} width - Image width in pixels
+   * @property {number} height - Image height in pixels
+   * @property {number} maxMagnitude - Highest magnitude value found
+   * @property {Uint8ClampedArray} angles - Edge angle per pixel
+   */
+
+  /**
+   * @typedef {Object} ReconstructionResult
+   * @property {THREE.Object3D} geometry - Generated 3D model
+   * @property {Array<DetectedFeature>} features - Detected 2D features
+   * @property {Object} metrics - Quality metrics (area coverage, confidence, etc.)
+   */
+
+  // ========== MODULE STATE ==========
   const state = {
     originalImage: null,
     processedImage: null,
@@ -45,7 +93,15 @@
   // ============================================================================
 
   /**
-   * Initialize image input handlers
+   * Initialize image input handlers (drag-drop, file input, camera, paste)
+   *
+   * Sets up event listeners for multiple image input methods:
+   * - Drag-drop files onto designated drop zone
+   * - File <input> element selection
+   * - Camera/device capture via getUserMedia
+   * - Paste from clipboard (Ctrl+V)
+   *
+   * @returns {void}
    */
   function initImageInput() {
     const dropZone = document.getElementById('photo-cad-drop-zone');
@@ -276,6 +332,18 @@
   /**
    * Detect edges using Sobel operator + Canny-style thinning
    */
+  /**
+   * Detect edges in image using Sobel operator with non-maximum suppression
+   *
+   * Two-stage edge detection:
+   * 1. Sobel: Applies 3x3 Sobel kernels for Gx/Gy gradients (fast, robust to noise)
+   * 2. Non-Maximum Suppression: Thins edges to single-pixel width, removes weak edges below threshold
+   *
+   * Sobel is chosen over Canny here for speed (no hysteresis linking) while maintaining quality.
+   * Non-maximum suppression uses gradient angle to suppress perpendicular pixels.
+   *
+   * @returns {void} Updates state.processedImage with binary edge map
+   */
   function detectEdges() {
     if (!state.canvas) return;
 
@@ -325,6 +393,22 @@
    * @param {number} height
    * @returns {Uint8Array} Edge magnitude
    */
+  /**
+   * Apply Sobel edge detection operator to grayscale image
+   *
+   * Computes image gradients using 3x3 Sobel kernels (Gx for horizontal, Gy for vertical).
+   * Returns magnitude (edge strength) and angle (edge direction) for each pixel.
+   *
+   * Sobel kernels:
+   * Gx = [-1 0 +1] / 2    Gy = [-1 -2 -1] / 2
+   *      [-2 0 +2]             [ 0  0  0]
+   *      [-1 0 +1]             [+1 +2 +1]
+   *
+   * @param {Uint8ClampedArray} gray - Grayscale image data (single channel)
+   * @param {number} width - Image width in pixels
+   * @param {number} height - Image height in pixels
+   * @returns {EdgeMap} Edge magnitude and direction data
+   */
   function sobelEdgeDetection(gray, width, height) {
     const sobelX = [[-1, 0, 1], [-2, 0, 2], [-1, 0, 1]];
     const sobelY = [[-1, -2, -1], [0, 0, 0], [1, 2, 1]];
@@ -356,6 +440,20 @@
    * @param {number} height
    * @returns {Uint8Array} Thinned edges
    */
+  /**
+   * Apply non-maximum suppression to thin edges and remove weak responses
+   *
+   * For each edge pixel: checks if it's a local maximum along the gradient direction.
+   * Only keeps pixels stronger than both perpendicular neighbors. Applies threshold
+   * to remove weak edges below sensitivity level. Produces single-pixel-wide edge outlines.
+   *
+   * Used in classic Canny algorithm but applied here after Sobel for performance.
+   *
+   * @param {EdgeMap} edges - Edge map from sobelEdgeDetection()
+   * @param {number} width - Image width in pixels
+   * @param {number} height - Image height in pixels
+   * @returns {Uint8ClampedArray} Binary edge map (0 or 255 per pixel)
+   */
   function nonMaximumSuppression(edges, width, height) {
     const thinned = new Uint8Array(width * height);
 
@@ -390,6 +488,18 @@
    * @param {number} width
    * @param {number} height
    */
+  /**
+   * Extract closed contours from binary edge map using flood fill
+   *
+   * Finds all edge pixels and traces connected components to form contours.
+   * Each contour is an ordered array of points that form a closed loop.
+   * Contours smaller than minSize are discarded as noise.
+   *
+   * @param {Uint8ClampedArray} binary - Binary edge map (0 or 255 per pixel)
+   * @param {number} width - Image width in pixels
+   * @param {number} height - Image height in pixels
+   * @returns {Array<Array<ContourPoint>>} Array of contours, each contour is array of points
+   */
   function extractContours(binary, width, height) {
     const visited = new Uint8Array(width * height);
     const contours = [];
@@ -419,6 +529,21 @@
    * @param {number} height
    * @returns {Array<{x, y}>} Contour points
    */
+  /**
+   * Trace a single contour starting from a seed point (internal helper)
+   *
+   * Uses 8-connectivity neighborhood traversal to follow edge pixels.
+   * Starts at seed point and walks perimeter in consistent direction.
+   * Marks visited pixels to avoid tracing same contour twice.
+   *
+   * @param {Uint8ClampedArray} binary - Binary edge map
+   * @param {Set<string>} visited - Set of already-traced pixel coordinates
+   * @param {number} startX - X coordinate of seed point
+   * @param {number} startY - Y coordinate of seed point
+   * @param {number} width - Image width in pixels
+   * @param {number} height - Image height in pixels
+   * @returns {Array<ContourPoint>} Ordered contour points
+   */
   function traceContour(binary, visited, startX, startY, width, height) {
     const contour = [];
     let x = startX, y = startY;
@@ -459,6 +584,19 @@
   /**
    * Detect primitives: circles, lines, rectangles, arcs
    */
+  /**
+   * Detect geometric primitives (circles, rectangles, lines) from extracted contours
+   *
+   * For each contour, attempts to fit known shapes in order of specificity:
+   * 1. Circle: Uses least-squares circle fitting (Taubin method)
+   * 2. Rectangle: Finds axis-aligned bounding box, checks linearity
+   * 3. Line: Fits line segment if contour is nearly straight
+   * 4. Arc: Fits circular arc for partial shapes
+   *
+   * Assigns confidence score based on fit quality. Returns array of detected features.
+   *
+   * @returns {Array<DetectedFeature>} Detected geometric primitives
+   */
   function detectPrimitives() {
     const contours = state.detectedFeatures.contours;
     state.detectedFeatures.circles = [];
@@ -492,6 +630,16 @@
    * @param {Array<{x, y}>} contour
    * @returns {{x, y, radius, confidence} | null}
    */
+  /**
+   * Fit least-squares circle to contour points (internal helper)
+   *
+   * Uses Taubin circle fitting algorithm (robust, algebraic method).
+   * Computes circle center and radius minimizing algebraic distance to all points.
+   * Returns null if fit quality is poor (e.g., contour is linear, not circular).
+   *
+   * @param {Array<ContourPoint>} contour - Ordered contour points
+   * @returns {Object|null} {center: {x, y}, radius, confidence} or null if not a circle
+   */
   function detectCircle(contour) {
     if (contour.length < 8) return null;
 
@@ -725,6 +873,20 @@
   /**
    * Reconstruct 3D geometry from detected features
    */
+  /**
+   * Reconstruct 3D geometry from 2D detected primitives
+   *
+   * Multi-mode reconstruction based on detected shape types:
+   * - Single circle → cylinder (rotational extrusion)
+   * - Single rectangle → box (extrusion)
+   * - Circle + reference dimension → scaled cylinder
+   * - Multiple shapes → composite assembly
+   *
+   * Uses reference dimension to establish real-world scale from pixel measurements.
+   * Returns composite THREE.Group with all 3D models.
+   *
+   * @returns {ReconstructionResult} 3D geometry and metrics
+   */
   function reconstruct3D() {
     const features = Array.from(state.selectedFeatures);
     if (features.length === 0) {
@@ -1048,6 +1210,14 @@
   /**
    * Initialize module
    */
+  /**
+   * Initialize PhotoToCAD module with UI and event handlers
+   *
+   * Sets up drop zone, file input, camera button, and Three.js preview scene.
+   * Must be called once before execute() calls. Safe to call multiple times.
+   *
+   * @returns {void}
+   */
   function init() {
     initImageInput();
     setupUIEventListeners();
@@ -1274,6 +1444,26 @@
    * @param {string} command
    * @param {*} params
    */
+  /**
+   * Execute command in PhotoToCAD module (public API)
+   *
+   * Main entry point for reverse engineering operations:
+   * - 'loadImage': Load image from data URL, file, or camera
+   * - 'detectEdges': Apply Sobel edge detection
+   * - 'detectPrimitives': Recognize circles, rectangles, lines
+   * - 'reconstruct3D': Convert 2D shapes to 3D geometry
+   * - 'setReferenceDimension': Set pixel-to-mm scale
+   * - 'enhanceWithAI': Ask Gemini to refine detection
+   * - 'exportModel': Export as STL or glTF
+   *
+   * @param {string} command - Command name
+   * @param {Object} [params={}] - Command parameters
+   * @param {string} params.imageData - For 'loadImage': data URL or file
+   * @param {number} params.pixelLength - For 'setReferenceDimension': length in pixels
+   * @param {number} params.mmLength - For 'setReferenceDimension': length in mm
+   * @param {string} params.format - For 'exportModel': 'stl'|'gltf'|'glb'
+   * @returns {Object} Command result (varies by command)
+   */
   function execute(command, params) {
     switch (command) {
       case 'processImage':

package/app/js/modules/smart-parts.js

@@ -1,15 +1,72 @@
 /**
- * Smart Parts Library with AI Search
+ * @fileoverview Smart Parts Library with AI Search
+ * @module CycleCAD/SmartParts
+ * @version 3.7.0
+ * @author cycleCAD Team
+ * @license MIT
  *
- * Provides access to 200+ standard parts with:
- * - AI-powered natural language search
- * - 3D parametric geometry generation
- * - Supplier part number cross-reference
- * - BOM management and export
- * - Real-time pricing estimation
+ * @description
+ * Unified smart parts catalog with 200+ standard mechanical parts. Features AI-powered
+ * natural language search (fuzzy matching), 3D parametric geometry generation for all parts,
+ * supplier part number cross-reference (McMaster-Carr, MISUMI, Digi-Key), BOM management and export,
+ * real-time pricing from multiple suppliers, and smart consolidation (combines duplicate parts).
  *
- * @namespace CycleCAD.SmartParts
- * @requires THREE.js
+ * @example
+ * // Search for parts using natural language
+ * const results = window.CycleCAD.SmartParts.execute('search', {query: 'm3 socket head cap screw'});
+ *
+ * // Add part to BOM
+ * window.CycleCAD.SmartParts.execute('addToBOM', {partId: 'fastener_shcs_m3_8', quantity: 10});
+ *
+ * // Generate 3D geometry for part
+ * const geometry = window.CycleCAD.SmartParts.execute('generateGeometry', {partId: 'fastener_shcs_m3_8'});
+ *
+ * @requires THREE (Three.js r170)
+ * @see {@link https://cyclecad.com/docs/killer-features|Killer Features Guide}
+ */
+
+/**
+ * @typedef {Object} CatalogPart
+ * @property {string} id - Unique part identifier
+ * @property {string} name - Human-readable part name
+ * @property {string} category - Part category (e.g., 'Fasteners', 'Bearings')
+ * @property {string} subcategory - Subcategory (e.g., 'Socket Head Cap Screws')
+ * @property {string} standard - Standard designation (e.g., 'ISO 4762', 'ANSI B18.3')
+ * @property {Object} dimensions - Parametric dimensions {dia, length, headDia, etc.}
+ * @property {string} material - Material designation
+ * @property {string} finish - Surface finish (e.g., 'Zinc Plated', 'Stainless')
+ * @property {number} weight - Weight in grams
+ * @property {Object} supplier - Supplier part numbers {mcmaster, misumi, digi, amazon}
+ * @property {Object} price - Pricing in different currencies {usd, eur, gbp}
+ * @property {Array<string>} tags - Search tags (for fuzzy matching)
+ */
+
+/**
+ * @typedef {Object} SearchResult
+ * @property {CatalogPart} part - The matched part
+ * @property {number} score - Match score 0-1 (1.0 = perfect match)
+ * @property {string} reason - Why this matched (e.g., 'tag match', 'description match')
+ */
+
+/**
+ * @typedef {Object} BOMEntry
+ * @property {string} partId - Reference to catalog part
+ * @property {CatalogPart} partData - Full part information
+ * @property {number} quantity - Number of units required
+ * @property {number} costPerUnit - Unit price in default currency
+ * @property {number} totalCost - quantity × costPerUnit
+ * @property {string} notes - User notes (e.g., "green anodized")
+ */
+
+/**
+ * @typedef {Object} SupplierInfo
+ * @property {string} supplier - Supplier name (e.g., 'McMaster', 'MISUMI')
+ * @property {string} partNumber - Supplier's part number
+ * @property {string} url - Direct link to part on supplier website
+ * @property {number} leadTime - Delivery time in days
+ * @property {number} minimumOrder - Minimum order quantity
+ * @property {number} unitPrice - Current unit price
+ * @property {number} stockLevel - Available inventory (-1 if unknown)
  */
 
 window.CycleCAD = window.CycleCAD || {};
@@ -616,6 +673,15 @@ window.CycleCAD.SmartParts = (() => {
    * @param {Object} dims - { dia, length, headDia, headHeight }
    * @returns {THREE.Group}
    */
+  /**
+   * Generate 3D bolt/screw geometry from dimensions (internal helper)
+   *
+   * Parametric socket head cap screw geometry: cylindrical shank + hex socket head.
+   * Creates proper proportions per ISO 4762 standard. Head includes drive recess.
+   *
+   * @param {Object} dims - Bolt dimensions {dia, length, headDia, headHeight, socketSize}
+   * @returns {THREE.BufferGeometry} 3D bolt mesh
+   */
   function generateBolt(dims) {
     const group = new THREE.Group();
 
@@ -963,6 +1029,15 @@ window.CycleCAD.SmartParts = (() => {
    * @param {Object} part - Part catalog entry
    * @returns {THREE.Group}
    */
+  /**
+   * Dispatch parametric geometry generation for any part in catalog
+   *
+   * Routes to specialized generator function based on part category.
+   * Caches geometry results for repeated access. Returns Three.js mesh ready for scene.
+   *
+   * @param {CatalogPart} part - Part from catalog
+   * @returns {THREE.BufferGeometry} Generated 3D geometry
+   */
   function getPartGeometry(part) {
     if (geometryCache.has(part.id)) {
       return geometryCache.get(part.id).clone();
@@ -1022,6 +1097,15 @@ window.CycleCAD.SmartParts = (() => {
    * @param {string} query
    * @returns {string[]}
    */
+  /**
+   * Tokenize search query into words for matching (internal helper)
+   *
+   * Splits on whitespace, removes common words (stop words), converts to lowercase.
+   * Expands abbreviations (e.g., "dia" → "diameter") before tokenization.
+   *
+   * @param {string} query - Natural language search query
+   * @returns {Array<string>} Processed tokens
+   */
   function tokenizeQuery(query) {
     return query
       .toLowerCase()
@@ -1036,6 +1120,17 @@ window.CycleCAD.SmartParts = (() => {
    * @param {string} b
    * @returns {number} 0-1
    */
+  /**
+   * Compute string similarity using Levenshtein edit distance (internal helper)
+   *
+   * Measures minimum edits (insert/delete/replace) needed to transform a→b.
+   * Normalized 0-1: 1.0 = identical, 0.0 = completely different.
+   * Used for typo tolerance in search (e.g., "dieameter" matches "diameter").
+   *
+   * @param {string} a - First string
+   * @param {string} b - Second string
+   * @returns {number} Similarity score 0-1
+   */
   function stringSimilarity(a, b) {
     a = a.toLowerCase();
     b = b.toLowerCase();
@@ -1084,6 +1179,27 @@ window.CycleCAD.SmartParts = (() => {
    * @param {Object} filters
    * @returns {Array} Sorted results with scores
    */
+  /**
+   * Search parts catalog using natural language query with optional filters
+   *
+   * Implements multi-strategy fuzzy matching:
+   * 1. Exact keyword match in tags (score 1.0)
+   * 2. Substring match in name/description (score 0.9)
+   * 3. Levenshtein edit distance for typo tolerance (score 0.7-0.8)
+   * 4. Category/material filtering to narrow results
+   *
+   * Results sorted by score (highest first). Duplicate parts consolidated.
+   *
+   * @param {string} query - Natural language search query (e.g., "m3 socket head cap screw 10mm")
+   * @param {Object} [filters={}] - Optional filters
+   * @param {string} filters.category - Filter by category (e.g., 'Fasteners')
+   * @param {string} filters.material - Filter by material (e.g., 'Steel')
+   * @param {number} filters.maxPrice - Price ceiling in default currency
+   * @returns {Array<SearchResult>} Ranked search results (best match first)
+   * @example
+   * const results = searchCatalog('iso 4762 m5 socket head cap screw 16mm', {material: 'Steel'});
+   * // → [{part: {...}, score: 0.98, reason: 'tag match'}, ...]
+   */
   function searchCatalog(query, filters = {}) {
     if (!query || query.trim().length === 0) {
       return Object.values(partCatalog).slice(0, 30);
@@ -1285,6 +1401,17 @@ window.CycleCAD.SmartParts = (() => {
    * @param {Object} config - { quantity, size, material, finish }
    * @returns {Object} { id, part, mesh, position }
    */
+  /**
+   * Insert part instance into 3D scene at specified position
+   *
+   * Generates geometry, creates THREE.Mesh, applies material and transform,
+   * adds to scene. Optionally applies color, scale, and user-specified configurations.
+   *
+   * @param {CatalogPart} part - Part from catalog
+   * @param {THREE.Vector3} [position] - World position for part placement
+   * @param {Object} [config={}] - Configuration {color, scale, visible, castShadow, receiveShadow}
+   * @returns {THREE.Mesh} Instance mesh added to scene
+   */
   function insertPart(part, position = new THREE.Vector3(0, 0, 0), config = {}) {
     const geometry = getPartGeometry(part);
     const mesh = geometry.clone();
@@ -1586,6 +1713,15 @@ window.CycleCAD.SmartParts = (() => {
    * Initialize module
    * @param {THREE.Scene} sceneRef
    */
+  /**
+   * Initialize SmartParts module with Three.js scene
+   *
+   * Sets up UI panel, search bar, category filters, BOM viewer,
+   * pricing display, and supplier links. Must be called once before execute() calls.
+   *
+   * @param {THREE.Scene} sceneRef - The Three.js scene for part insertion
+   * @returns {void}
+   */
   function init(sceneRef) {
     scene = sceneRef;
     console.log('[SmartParts] Initialized with', Object.keys(partCatalog).length, 'parts');
@@ -1665,6 +1801,40 @@ window.CycleCAD.SmartParts = (() => {
    * @param {string} command
    * @param {Object} params
    */
+  /**
+   * Execute command in SmartParts module (public API)
+   *
+   * Commands:
+   * - 'search': Search parts catalog with natural language query
+   * - 'getCatalog': Get full parts list (optionally filtered)
+   * - 'generateGeometry': Get 3D geometry for a part
+   * - 'insertPart': Add part instance to 3D scene
+   * - 'addToBOM': Add part to Bill of Materials
+   * - 'removeBOM': Remove part from BOM
+   * - 'consolidateBOM': Merge duplicate parts in BOM
+   * - 'exportBOM': Export BOM as CSV or Excel
+   * - 'getSuppliersForPart': Get all supplier options for a part
+   * - 'compareSuppliers': Compare pricing/lead time across suppliers
+   * - 'getCategories': List all part categories
+   * - 'getPricingHistory': Get historical pricing for a part
+   *
+   * @param {string} command - Command name
+   * @param {Object} [params={}] - Command parameters (varies by command)
+   * @param {string} params.query - For 'search': natural language query
+   * @param {string} params.partId - For most commands: part identifier
+   * @param {number} params.quantity - For 'addToBOM': quantity to add
+   * @param {string} params.format - For 'exportBOM': 'csv'|'excel'|'json'
+   * @returns {Object} Command result (varies by command)
+   * @example
+   * // Search for parts
+   * const results = window.CycleCAD.SmartParts.execute('search', {query: 'm5 socket head cap screw'});
+   *
+   * // Add to BOM
+   * window.CycleCAD.SmartParts.execute('addToBOM', {partId: results[0].part.id, quantity: 10});
+   *
+   * // Export BOM
+   * const bomData = window.CycleCAD.SmartParts.execute('exportBOM', {format: 'excel'});
+   */
   function execute(command, params = {}) {
     switch (command) {
       case 'search':