circuit-json-to-gltf 0.0.1

package/README.md

@@ -0,0 +1,96 @@
+# circuit-json-to-gltf
+
+Converts circuit JSON to 3D GLTF files. Used for exporting circuits as 3D models.
+
+## Features
+
+- Convert circuit JSON to GLTF 2.0 format (JSON or binary)
+- Render PCB board with accurate dimensions and textures
+- Support for STL and OBJ model loading for components
+- High-quality board texture rendering using circuit-to-svg and resvg
+- Automatic component positioning and generic 3D representations
+- Customizable camera, lighting, and material settings
+
+## Installation
+
+```bash
+bun install circuit-json-to-gltf
+```
+
+## Usage
+
+```typescript
+import { convertCircuitJsonToGltf } from "circuit-json-to-gltf"
+
+// Your circuit JSON data
+const circuitJson = {
+  elements: [
+    {
+      type: "pcb_board",
+      pcb_board_id: "board1",
+      center: { x: 0, y: 0 },
+      width: 80,
+      height: 60,
+      thickness: 1.6
+    },
+    // ... components, traces, etc.
+  ]
+}
+
+// Convert to GLTF
+const gltf = await convertCircuitJsonToGltf(circuitJson, {
+  format: "gltf", // or "glb" for binary
+  boardTextureResolution: 2048
+})
+
+// Save the result
+fs.writeFileSync("circuit.gltf", JSON.stringify(gltf))
+```
+
+## API
+
+### Main Function
+
+```typescript
+convertCircuitJsonToGltf(circuitJson: CircuitJson, options?: ConversionOptions): Promise<ArrayBuffer | object>
+```
+
+### Options
+
+- `format`: "gltf" (JSON) or "glb" (binary) - default: "gltf"
+- `boardTextureResolution`: Resolution for board texture rendering - default: 1024
+- `includeModels`: Whether to load external 3D models - default: true
+- `modelCache`: Map for caching loaded models
+- `backgroundColor`: Background color for board rendering
+- `showBoundingBoxes`: Show bounding boxes for debugging
+
+## Architecture
+
+The converter uses a modular architecture:
+
+1. **Circuit to 3D Converter**: Parses circuit JSON and creates a 3D scene representation
+2. **Board Renderer**: Renders PCB layers as textures using circuit-to-svg and resvg
+3. **Model Loaders**: Load STL and OBJ files for component 3D models
+4. **GLTF Builder**: Constructs the final GLTF using Three.js
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Run example
+bun run examples/basic-conversion.ts
+```
+
+## Implementation Details
+
+- Uses `circuit-to-svg` to render the top/bottom layers of the board to SVG
+- Uses `@resvg/resvg-js` to convert SVG to PNG textures
+- Includes built-in STL and OBJ parsers for 3D model loading
+- Pure GLTF 2.0 implementation without external 3D library dependencies
+- Supports both JSON (.gltf) and binary (.glb) formats
+- Embeds all assets (textures, buffers) directly in the output

package/dist/index.d.ts

@@ -0,0 +1,167 @@
+import { CircuitJson } from 'circuit-json';
+
+interface ConversionOptions {
+    format?: "gltf" | "glb";
+    boardTextureResolution?: number;
+    includeModels?: boolean;
+    modelCache?: Map<string, STLMesh | OBJMesh>;
+    backgroundColor?: string;
+    showBoundingBoxes?: boolean;
+    coordinateTransform?: CoordinateTransformConfig;
+}
+interface CoordinateTransformConfig {
+    flipX?: number;
+    flipY?: number;
+    flipZ?: number;
+    axisMapping?: {
+        x?: "x" | "y" | "z" | "-x" | "-y" | "-z";
+        y?: "x" | "y" | "z" | "-x" | "-y" | "-z";
+        z?: "x" | "y" | "z" | "-x" | "-y" | "-z";
+    };
+    rotation?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+}
+interface Point3 {
+    x: number;
+    y: number;
+    z: number;
+}
+interface Size3 {
+    x: number;
+    y: number;
+    z: number;
+}
+interface Triangle {
+    vertices: [Point3, Point3, Point3];
+    normal: Point3;
+    color?: Color;
+    materialIndex?: number;
+}
+interface BoundingBox {
+    min: Point3;
+    max: Point3;
+}
+interface STLMesh {
+    triangles: Triangle[];
+    boundingBox: BoundingBox;
+}
+interface OBJMesh extends STLMesh {
+    materials?: Map<string, OBJMaterial>;
+}
+interface OBJMaterial {
+    name: string;
+    color?: Color;
+    ambient?: Color;
+    specular?: Color;
+    shininess?: number;
+    dissolve?: number;
+}
+type Color = string | [number, number, number, number];
+interface Box3D {
+    center: Point3;
+    size: Size3;
+    rotation?: Point3;
+    color?: Color;
+    texture?: {
+        top?: string;
+        bottom?: string;
+        front?: string;
+        back?: string;
+        left?: string;
+        right?: string;
+    };
+    mesh?: STLMesh | OBJMesh;
+    meshUrl?: string;
+    meshType?: "stl" | "obj";
+    label?: string;
+    labelColor?: Color;
+}
+interface Scene3D {
+    boxes: Box3D[];
+    camera?: Camera3D;
+    lights?: Light3D[];
+}
+interface Camera3D {
+    position: Point3;
+    target: Point3;
+    up?: Point3;
+    fov?: number;
+    near?: number;
+    far?: number;
+}
+interface Light3D {
+    type: "ambient" | "directional" | "point";
+    color?: Color;
+    intensity?: number;
+    position?: Point3;
+    direction?: Point3;
+}
+interface GLTFExportOptions {
+    binary?: boolean;
+    trs?: boolean;
+    onlyVisible?: boolean;
+    truncateDrawRange?: boolean;
+    embedImages?: boolean;
+    animations?: any[];
+    forceIndices?: boolean;
+    includeCustomExtensions?: boolean;
+}
+interface CircuitTo3DOptions {
+    pcbColor?: Color;
+    componentColor?: Color;
+    boardThickness?: number;
+    defaultComponentHeight?: number;
+    renderBoardTextures?: boolean;
+    textureResolution?: number;
+    coordinateTransform?: CoordinateTransformConfig;
+}
+interface BoardRenderOptions {
+    layer: "top" | "bottom";
+    resolution?: number;
+    backgroundColor?: string;
+    copperColor?: string;
+    silkscreenColor?: string;
+    padColor?: string;
+    drillColor?: string;
+}
+
+declare function loadSTL(url: string, transform?: CoordinateTransformConfig): Promise<STLMesh>;
+declare function clearSTLCache(): void;
+
+declare function loadOBJ(url: string, transform?: CoordinateTransformConfig): Promise<OBJMesh>;
+declare function clearOBJCache(): void;
+
+declare function convertCircuitJsonTo3D(circuitJson: CircuitJson, options?: CircuitTo3DOptions): Promise<Scene3D>;
+
+declare function convertSceneToGLTF(scene: Scene3D, options?: GLTFExportOptions): Promise<ArrayBuffer | object>;
+
+declare function renderBoardLayer(circuitJson: CircuitJson, options: BoardRenderOptions): Promise<string>;
+declare function renderBoardTextures(circuitJson: CircuitJson, resolution?: number): Promise<{
+    top: string;
+    bottom: string;
+}>;
+
+declare function applyCoordinateTransform(point: Point3, config: CoordinateTransformConfig): Point3;
+declare function transformTriangles(triangles: Triangle[], config: CoordinateTransformConfig): Triangle[];
+declare const COORDINATE_TRANSFORMS: {
+    readonly Z_UP_TO_Y_UP: CoordinateTransformConfig;
+    readonly Z_OUT_OF_TOP: CoordinateTransformConfig;
+    readonly USB_PORT_FIX: CoordinateTransformConfig;
+    readonly Z_UP_TO_Y_UP_USB_FIX: CoordinateTransformConfig;
+    readonly IDENTITY: CoordinateTransformConfig;
+    readonly TEST_ROTATE_X_90: CoordinateTransformConfig;
+    readonly TEST_ROTATE_X_270: CoordinateTransformConfig;
+    readonly TEST_ROTATE_Y_90: CoordinateTransformConfig;
+    readonly TEST_ROTATE_Y_270: CoordinateTransformConfig;
+    readonly TEST_ROTATE_Z_90: CoordinateTransformConfig;
+    readonly TEST_ROTATE_Z_270: CoordinateTransformConfig;
+    readonly TEST_FLIP_X: CoordinateTransformConfig;
+    readonly TEST_FLIP_Z: CoordinateTransformConfig;
+};
+
+declare function convertCircuitJsonToGltf(circuitJson: CircuitJson, options?: ConversionOptions): Promise<ArrayBuffer | object>;
+
+export { type BoardRenderOptions, type BoundingBox, type Box3D, COORDINATE_TRANSFORMS, type Camera3D, type CircuitTo3DOptions, type Color, type ConversionOptions, type CoordinateTransformConfig, type GLTFExportOptions, type Light3D, type OBJMaterial, type OBJMesh, type Point3, type STLMesh, type Scene3D, type Size3, type Triangle, applyCoordinateTransform, clearOBJCache, clearSTLCache, convertCircuitJsonTo3D, convertCircuitJsonToGltf, convertSceneToGLTF, loadOBJ, loadSTL, renderBoardLayer, renderBoardTextures, transformTriangles };