feat: add twin and modification support to JS geometry engine

Ported from Python crystal_geometry package:
- transforms.ts: Matrix operations (Rodrigues rotation, reflection)
- twin-laws.ts: 14 twin law definitions with axes and angles
- twin-generator.ts: Geometry merging for dual/v-shaped/cyclic twins
- modifications.ts: elongate(), flatten(), scale() support

Updated:
- cdl-parser.ts: Parse twin(name) and modification specs
- crystal-geometry.ts: Apply modifications and twins to geometry

This enables the playground to render complex CDL with twins like:
  trigonal[32]:{10-10}@0.5 | elongate(c:2.0) | twin(brazil)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: Bissbert

src/lib/cdl-parser.ts

@@ -15,11 +15,23 @@ export interface CrystalForm {
   scale: number;
 }
 
+export interface TwinSpec {
+  law: string;
+}
+
+export interface ModificationSpec {
+  type: 'elongate' | 'flatten' | 'scale';
+  axis: 'a' | 'b' | 'c';
+  factor: number;
+}
+
 export interface CDLParseResult {
   system: string;
   pointGroup: string;
   forms: CrystalForm[];
   modifier?: string;
+  twin?: TwinSpec;
+  modifications?: ModificationSpec[];
 }
 
 export interface ValidationResult {
@@ -180,13 +192,38 @@ export function parseCDL(cdl: string): ValidationResult {
     return { valid: false, error: 'At least one crystal form is required' };
   }
 
+  // Parse twin and modifications from modifier string
+  let twin: TwinSpec | undefined;
+  const modifications: ModificationSpec[] = [];
+
+  if (modifier) {
+    // Parse twin: twin(name)
+    const twinMatch = modifier.match(/twin\s*\(\s*(\w+)\s*\)/i);
+    if (twinMatch) {
+      twin = { law: twinMatch[1].toLowerCase() };
+    }
+
+    // Parse modifications: elongate(c:2.0), flatten(a:0.5), scale(b:1.5)
+    const modRegex = /(elongate|flatten|scale)\s*\(\s*([abc])\s*:\s*([\d.]+)\s*\)/gi;
+    let modMatch;
+    while ((modMatch = modRegex.exec(modifier)) !== null) {
+      modifications.push({
+        type: modMatch[1].toLowerCase() as ModificationSpec['type'],
+        axis: modMatch[2].toLowerCase() as ModificationSpec['axis'],
+        factor: parseFloat(modMatch[3]),
+      });
+    }
+  }
+
   return {
     valid: true,
     parsed: {
       system: system.toLowerCase(),
       pointGroup,
       forms,
       modifier,
+      twin,
+      modifications: modifications.length > 0 ? modifications : undefined,
     },
   };
 }

src/lib/crystal-geometry.ts

@@ -3,7 +3,8 @@
  * Generates 3D crystal geometry using half-space intersection algorithm
  */
 
-import type { CDLParseResult, MillerIndex } from './cdl-parser';
+import type { CDLParseResult, MillerIndex, ModificationSpec } from './cdl-parser';
+import { generateTwinnedGeometry } from './twin-generator';
 
 export interface Vector3 {
   x: number;
@@ -401,5 +402,72 @@ export function generateGeometry(parsed: CDLParseResult): CrystalGeometry {
     }
   }
 
-  return { vertices, faces, edges };
+  let geometry: CrystalGeometry = { vertices, faces, edges };
+
+  // Apply modifications (elongate, flatten, scale)
+  if (parsed.modifications && parsed.modifications.length > 0) {
+    geometry = applyModifications(geometry, parsed.modifications);
+  }
+
+  // Apply twin transformation
+  if (parsed.twin) {
+    geometry = generateTwinnedGeometry(geometry, parsed.twin.law);
+  }
+
+  return geometry;
+}
+
+/**
+ * Apply modifications to geometry (elongate, flatten, scale)
+ */
+function applyModifications(geom: CrystalGeometry, mods: ModificationSpec[]): CrystalGeometry {
+  // Calculate scale factors for each axis
+  const scales = { a: 1, b: 1, c: 1 };
+
+  for (const mod of mods) {
+    let factor = mod.factor;
+    if (mod.type === 'flatten') {
+      factor = 1 / factor;
+    }
+    scales[mod.axis] *= factor;
+  }
+
+  // Apply scales to vertices
+  const newVertices = geom.vertices.map(v => ({
+    x: v.x * scales.a,
+    y: v.y * scales.b,
+    z: v.z * scales.c,
+  }));
+
+  // Apply scales to face vertices and recalculate normals
+  const newFaces = geom.faces.map(face => {
+    const scaledVertices = face.vertices.map(v => ({
+      x: v.x * scales.a,
+      y: v.y * scales.b,
+      z: v.z * scales.c,
+    }));
+
+    // Recalculate normal after scaling
+    let normal = face.normal;
+    if (scaledVertices.length >= 3) {
+      const v0 = scaledVertices[0];
+      const v1 = scaledVertices[1];
+      const v2 = scaledVertices[2];
+      const edge1 = sub(v1, v0);
+      const edge2 = sub(v2, v0);
+      normal = normalize(cross(edge1, edge2));
+    }
+
+    return {
+      ...face,
+      vertices: scaledVertices,
+      normal,
+    };
+  });
+
+  return {
+    vertices: newVertices,
+    faces: newFaces,
+    edges: geom.edges,
+  };
 }

src/lib/modifications.ts

@@ -0,0 +1,116 @@
+/**
+ * Crystal modification operations (elongate, flatten, etc.)
+ * Ported from Python crystal_geometry.modifications
+ */
+
+import type { Vec3 } from './transforms';
+
+export interface Modification {
+  type: 'elongate' | 'flatten' | 'scale';
+  axis: 'a' | 'b' | 'c';
+  factor: number;
+}
+
+/**
+ * Parse a modification string like "elongate(c:2.0)" or "flatten(a:0.5)"
+ */
+export function parseModification(modStr: string): Modification | null {
+  // Match patterns like: elongate(c:2.0), flatten(a:0.5), scale(b:1.5)
+  const match = modStr.match(/^(elongate|flatten|scale)\s*\(\s*([abc])\s*:\s*([\d.]+)\s*\)$/i);
+  if (!match) return null;
+
+  const type = match[1].toLowerCase() as Modification['type'];
+  const axis = match[2].toLowerCase() as Modification['axis'];
+  const factor = parseFloat(match[3]);
+
+  if (isNaN(factor) || factor <= 0) return null;
+
+  return { type, axis, factor };
+}
+
+/**
+ * Parse multiple modifications from a modifier string
+ * Handles: "elongate(c:2.0) | flatten(a:0.5)" or just "elongate(c:2.0)"
+ */
+export function parseModifications(modifierStr: string): Modification[] {
+  const modifications: Modification[] = [];
+
+  // Split by | and process each part
+  const parts = modifierStr.split('|').map(s => s.trim());
+
+  for (const part of parts) {
+    // Skip twin modifiers
+    if (part.startsWith('twin(')) continue;
+
+    const mod = parseModification(part);
+    if (mod) {
+      modifications.push(mod);
+    }
+  }
+
+  return modifications;
+}
+
+/**
+ * Apply a modification to a vertex
+ */
+export function applyModificationToVertex(v: Vec3, mod: Modification): Vec3 {
+  const result = { ...v };
+
+  // Determine effective scale factor
+  let scale = mod.factor;
+  if (mod.type === 'flatten') {
+    scale = 1 / mod.factor; // Flatten reduces the dimension
+  }
+
+  // Apply to appropriate axis
+  switch (mod.axis) {
+    case 'a':
+      result.x *= scale;
+      break;
+    case 'b':
+      result.y *= scale;
+      break;
+    case 'c':
+      result.z *= scale;
+      break;
+  }
+
+  return result;
+}
+
+/**
+ * Apply all modifications to a vertex
+ */
+export function applyModificationsToVertex(v: Vec3, mods: Modification[]): Vec3 {
+  let result = { ...v };
+  for (const mod of mods) {
+    result = applyModificationToVertex(result, mod);
+  }
+  return result;
+}
+
+/**
+ * Apply modifications to all vertices in an array
+ */
+export function applyModificationsToVertices(vertices: Vec3[], mods: Modification[]): Vec3[] {
+  if (mods.length === 0) return vertices;
+  return vertices.map(v => applyModificationsToVertex(v, mods));
+}
+
+/**
+ * Get the scale factors for a/b/c axes from modifications
+ */
+export function getScaleFactors(mods: Modification[]): { a: number; b: number; c: number } {
+  const scales = { a: 1, b: 1, c: 1 };
+
+  for (const mod of mods) {
+    let factor = mod.factor;
+    if (mod.type === 'flatten') {
+      factor = 1 / factor;
+    }
+    scales[mod.axis] *= factor;
+  }
+
+  return scales;
+}