How huaqiu-electronics/ecad-viewer works
Project Type and Purpose
• This is a full-stack web-based application designed to display electronic design files (PCB, schematic, and 3D models) interactively in the browser.
• The README makes clear that ECAD-Viewer builds upon the kicanvas framework and incorporates additional features (such as integration with kicad-cli for file conversion, 3D visualization with Three.js, etc.).
• It supports both standalone and embedded usage, includes Docker deployments (full and lite), and provides build scripts and utilities for font/sprite generation.
File Structure
• The root includes configuration files (eslint, prettier, tsconfig, .gitignore) and Docker configurations, which indicate that there are distinct environments for development and deployment.
• The “src” directory is the heart of the project. It’s further broken into multiple subdirectories:
a. “3d-viewer”: Manages the 3D models and the Three.js integration.
b. “base”: Provides utilities, helper functions, math operations, DOM utilities, and common web-components, which are used across the project.
c. “ecad-viewer”: Contains the core viewer logic and file conversion for handling electronic design files.
d. “graphics”: Holds rendering logic both for canvas2d and WebGL (including shader files).
e. “kc-ui”: Implements the custom UI components (buttons, menus, panels, charts, etc.) using web components.
f. “kicad”: Implements parsing and processing of KiCad files, including visitors and tokenizers for boards, schematics, BOM extraction, etc.
g. “kicanvas”: Contains the integration layers for the interactive canvas elements to display different types of designs (board, schematic, and common application features for viewer operations) and includes service modules (such as GitHub integration and virtual file system (VFS) support).
h. “viewers”: Provides distinct viewers for documents, board, drawing sheet, and schematic with specific painter and layer management classes.
i. “utils”: Contains various helper scripts such as design utilities and functions for working with ZIP files.
• There is also a “third_party” folder which bundles external libraries (such as “earcut” for polygon triangulation and “newstroke” for fonts).
Key System Components & Their Roles
• Web Frontend:
• Built using plain JavaScript/TypeScript modules and web components.
• UI components are defined under “kc-ui” and “kicanvas”, used to render the interactive viewer.
• Multiple viewer modules exist for handling PCB (board), schematic, drawing sheet, and 3D presentations.
• Graphics Engine:
• “graphics” handles various rendering pipelines: a 2D canvas-based renderer and a WebGL-based renderer for complex visualizations.
• KiCad File and Design Processing:
• Under “kicad”, files are parsed and processed, with multiple utilities (such as visitors, tokenizers, parsers, and font/text renderers) that prepare design data for viewing.
• Conversion/Integration Services:
• Integration with kicad-cli (running as Docker containers) is critical. The frontend calls REST API endpoints (e.g. /convert_pcb_to_glb) to convert design files into formats suitable for viewing (3D models in GLB format).
• This processing may be implemented externally (via the provided Docker images for kicad-cli) and potentially, a lightweight Python wrapper using kicad-cli-python.
• Build/Deployment & DevOps:
• Dockerfiles for the “full” and “lite” versions enable containerized deployment.
• Scripts in the “scripts” directory bundle assets, build fonts/sprites, and handle testing/serving, which are critical during CI/CD (also evidenced by the GitHub workflows).
Final Points
• Every component is labeled clearly.
• Notes on which parts are executed in the browser (frontend) and which (like the kicad-cli service) are on separated backend containers.
• Don’t overcomplicate: focus on key modules and how they interact. The above divisions into front-end components, processing/parsing layers, rendering engines, and conversion APIs should be sufficient.