{"_id":"@amanyadev/half-edge","name":"@amanyadev/half-edge","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@amanyadev/half-edge","version":"0.1.0","description":"A TypeScript half-edge mesh library for 3D geometry operations and modeling","keywords":["3d","geometry","mesh","half-edge","modeling","cad","graphics"],"author":{"name":"Aman","email":"your.email@example.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/amanyadev/surface-modeler.git","directory":"packages/kernel"},"homepage":"https://github.com/amanyadev/surface-modeler/tree/main/packages/kernel#readme","bugs":{"url":"https://github.com/amanyadev/surface-modeler/issues"},"type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"build":"tsc","dev":"tsc --watch","test":"vitest","test:watch":"vitest --watch","lint":"eslint src --ext .ts","type-check":"tsc --noEmit","clean":"rm -rf dist"},"devDependencies":{"@types/node":"^20.11.16","typescript":"^5.3.3","vitest":"^1.2.2"},"dependencies":{"uuid":"^9.0.1"},"_id":"@amanyadev/half-edge@0.1.0","gitHead":"94178168f39107e6732ff339b6bef00d8c3cbc9e","_nodeVersion":"21.6.2","_npmVersion":"10.2.4","dist":{"integrity":"sha512-fi/J6DhivOwLoHkuW3WFxXJjilpffVclZHTF/wZtBk27W6msSCyJ+ktq5ts3QHXcukC5ID9qKTXF+x+OxQStRA==","shasum":"5f920cbed7cbf3cb0e3bf32ba0dff8132d4f1e6f","tarball":"https://registry.npmjs.org/@amanyadev/half-edge/-/half-edge-0.1.0.tgz","fileCount":111,"unpackedSize":318867,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD1Gzl4MpNrp6qQ4P7t0uCuRCsGd3KfOETgEtDJOfZ9ZAIgZ7pQx/Nb/tHjNW1Y3elSLc7NAexTwx8fU3/PFHnleyw="}]},"_npmUser":{"name":"amanyadev","email":"yadav.aman099@gmail.com"},"directories":{},"maintainers":[{"name":"amanyadev","email":"yadav.aman099@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/half-edge_0.1.0_1761536913626_0.25982706716461523"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-27T03:48:33.543Z","0.1.0":"2025-10-27T03:48:33.826Z","modified":"2025-10-27T03:48:34.114Z"},"maintainers":[{"name":"amanyadev","email":"yadav.aman099@gmail.com"}],"description":"A TypeScript half-edge mesh library for 3D geometry operations and modeling","homepage":"https://github.com/amanyadev/surface-modeler/tree/main/packages/kernel#readme","keywords":["3d","geometry","mesh","half-edge","modeling","cad","graphics"],"repository":{"type":"git","url":"git+https://github.com/amanyadev/surface-modeler.git","directory":"packages/kernel"},"author":{"name":"Aman","email":"your.email@example.com"},"bugs":{"url":"https://github.com/amanyadev/surface-modeler/issues"},"license":"MIT","readme":"# @amanyadev/half-edge\n\nA pure TypeScript geometry and modeling kernel for 3D surface modeling applications.\n\n## Overview\n\nThe kernel provides a complete mesh data structure and modeling operations using the half-edge representation. It's designed to be platform-agnostic and can run in browsers, Node.js, or WebWorkers.\n\n## Installation\n\n```bash\nnpm install @amanyadev16/half-edge\n```\n\n## Quick Start\n\n```typescript\nimport { \n  HalfEdgeMesh, \n  createCube, \n  ExtrudeCommand, \n  CommandHistory \n} from '@half-edge/kernel';\n\n// Create a cube primitive\nconst mesh = createCube(2);\n\n// Setup command history for undo/redo\nconst history = new CommandHistory();\n\n// Get a face to extrude\nconst face = mesh.faces()[0];\n\n// Create and execute an extrude command\nconst extrudeCmd = new ExtrudeCommand(face.id, 1.0);\nhistory.execute(extrudeCmd, mesh);\n\n// Undo the operation\nhistory.undo(mesh);\n```\n\n## API Reference\n\n### Core Types\n\n#### Vec3\n```typescript\ntype Vec3 = { x: number; y: number; z: number };\n```\n\n#### Vertex\n```typescript\ninterface Vertex {\n  id: string;\n  pos: Vec3;\n  normal?: Vec3;\n  uv?: Vec2;\n  halfEdge?: string; // Reference to outgoing half-edge\n}\n```\n\n#### HalfEdge\n```typescript\ninterface HalfEdge {\n  id: string;\n  vertex: string;   // Target vertex\n  twin?: string;    // Opposite half-edge\n  next?: string;    // Next half-edge in face loop\n  prev?: string;    // Previous half-edge in face loop\n  face?: string;    // Face this half-edge bounds\n  edge?: string;    // Parent edge\n}\n```\n\n#### Face\n```typescript\ninterface Face {\n  id: string;\n  halfEdge: string; // One of the bounding half-edges\n  normal?: Vec3;\n  materialId?: string;\n}\n```\n\n### Mesh Operations\n\n#### HalfEdgeMesh\n\nThe main mesh class implementing the half-edge data structure:\n\n```typescript\nconst mesh = new HalfEdgeMesh();\n\n// Add vertices\nconst v1 = mesh.addVertex({ x: 0, y: 0, z: 0 });\nconst v2 = mesh.addVertex({ x: 1, y: 0, z: 0 });\nconst v3 = mesh.addVertex({ x: 0.5, y: 1, z: 0 });\n\n// Add a triangular face\nconst face = mesh.addFace([v1.id, v2.id, v3.id]);\n\n// Query the mesh\nconst vertices = mesh.vertices();\nconst faces = mesh.faces();\nconst faceVertices = mesh.getFaceVertices(face.id);\n\n// Clone the mesh\nconst cloned = mesh.clone();\n```\n\n### Primitive Creation\n\nCreate common geometric primitives:\n\n```typescript\nimport { createPlane, createCube, createCylinder } from '@half-edge/kernel';\n\n// Create a 2x2 plane\nconst plane = createPlane(2, 2);\n\n// Create a unit cube\nconst cube = createCube(1);\n\n// Create a cylinder with radius=1, height=2, 8 segments\nconst cylinder = createCylinder(1, 2, 8);\n```\n\n### Command System\n\nAll modeling operations are implemented as commands supporting undo/redo:\n\n```typescript\nimport { CommandHistory, ExtrudeCommand, FlipNormalsCommand } from '@half-edge/kernel';\n\nconst history = new CommandHistory();\n\n// Execute commands\nconst extrudeCmd = new ExtrudeCommand(faceId, 1.5);\nhistory.execute(extrudeCmd, mesh);\n\nconst flipCmd = new FlipNormalsCommand(faceId);\nhistory.execute(flipCmd, mesh);\n\n// Undo/redo\nif (history.canUndo()) {\n  history.undo(mesh);\n}\n\nif (history.canRedo()) {\n  history.redo(mesh);\n}\n\n// Clear history\nhistory.clear();\n```\n\n### Available Commands\n\n#### ExtrudeCommand\nExtrudes a face along its normal:\n\n```typescript\nconst cmd = new ExtrudeCommand(faceId, distance);\n```\n\n#### FlipNormalsCommand\nReverses the orientation of a face:\n\n```typescript\nconst cmd = new FlipNormalsCommand(faceId);\n```\n\n### Custom Commands\n\nImplement your own modeling operations:\n\n```typescript\nimport { BaseCommand, Mesh } from '@half-edge/kernel';\n\nexport class MyCustomCommand extends BaseCommand {\n  constructor(private param1: string, private param2: number) {\n    super('my_custom_operation');\n  }\n\n  do(mesh: Mesh): void {\n    // Store original state for undo\n    this.originalState = /* serialize mesh state */;\n    \n    // Perform the operation\n    /* modify mesh */\n  }\n\n  undo(mesh: Mesh): void {\n    // Restore original state\n    /* restore mesh from this.originalState */\n  }\n}\n```\n\n### Utility Functions\n\nVector math utilities:\n\n```typescript\nimport { vec3, vec3Add, vec3Sub, vec3Scale, vec3Cross, vec3Normalize } from '@half-edge/kernel';\n\nconst a = vec3(1, 0, 0);\nconst b = vec3(0, 1, 0);\n\nconst sum = vec3Add(a, b);           // { x: 1, y: 1, z: 0 }\nconst cross = vec3Cross(a, b);       // { x: 0, y: 0, z: 1 }\nconst normalized = vec3Normalize(a); // { x: 1, y: 0, z: 0 }\n```\n\n## Half-Edge Data Structure\n\nThe half-edge representation provides efficient access to mesh connectivity:\n\n### Benefits\n- **Efficient Traversal**: Constant-time access to adjacent faces, edges, and vertices\n- **Robust Operations**: Supports complex modeling operations like extrusion and boolean ops\n- **Manifold Meshes**: Enforces topological consistency\n- **Extensible**: Easy to add custom attributes and operations\n\n### Structure\n- Each edge is split into two directed half-edges\n- Each half-edge points to its target vertex, twin half-edge, next/prev in face loop\n- Each face references one of its bounding half-edges\n- Each vertex references one of its outgoing half-edges\n\n### Traversal Examples\n\n```typescript\n// Get all vertices of a face\nconst faceVertices = mesh.getFaceVertices(faceId);\n\n// Walk around a vertex to find adjacent faces\nfunction getVertexFaces(mesh: HalfEdgeMesh, vertexId: string): Face[] {\n  const vertex = mesh.getVertex(vertexId);\n  if (!vertex?.halfEdge) return [];\n  \n  const faces: Face[] = [];\n  let currentHalfEdge = vertex.halfEdge;\n  \n  do {\n    const halfEdge = mesh.getHalfEdge(currentHalfEdge);\n    if (halfEdge?.face) {\n      const face = mesh.getFace(halfEdge.face);\n      if (face) faces.push(face);\n    }\n    \n    // Move to next half-edge around vertex\n    const twin = halfEdge?.twin;\n    if (!twin) break;\n    \n    const twinHalfEdge = mesh.getHalfEdge(twin);\n    currentHalfEdge = twinHalfEdge?.next;\n  } while (currentHalfEdge && currentHalfEdge !== vertex.halfEdge);\n  \n  return faces;\n}\n```\n\n## Performance Notes\n\n- Operations are designed for interactive modeling (not batch processing)\n- Large meshes may benefit from spatial indexing (not yet implemented)\n- Command history stores full mesh snapshots (consider checkpointing for large operations)\n- Half-edge traversal is O(1) for most operations\n\n## Future Extensions\n\nPlanned additions to the kernel:\n\n- **Boolean Operations**: Union, intersection, difference\n- **Subdivision Surfaces**: Catmull-Clark and Loop subdivision\n- **Spatial Indexing**: Octree and BVH for large meshes\n- **Mesh Validation**: Topology checking and repair\n- **Advanced Primitives**: Torus, icosphere, etc.\n- **Mesh Simplification**: LOD generation and decimation\n\n## Testing\n\nThe kernel includes comprehensive unit tests:\n\n```bash\nnpm test          # Run all tests\nnpm run test:watch # Watch mode\n```\n\nTest coverage includes:\n- Mesh construction and modification\n- Command execution and undo/redo\n- Primitive generation\n- Half-edge connectivity validation\n\n## License\n\nMIT","readmeFilename":"README.md","_rev":"1-1ff238a6575dd22aec4398724e35548c"}