DOCSEARCHbyAlgolia
Submit Docs

KiCanvas Documentation

repository·main·Indexed 22 days ago

https://github.com/theacodes/kicanvas

An interactive, browser-based, read-only viewer for KiCad schematics and PCB layouts. Built with vanilla TypeScript and WebGL for high-performance rendering, KiCanvas supports KiCad 6 and later (.sch, .pcb, .wks, and .pro files) without requiring external plugins or runtime dependencies. It features an embedding API for integrating interactive viewers into websites and is implemented using standard Web Components for framework-agnostic compatibility.

Tokens
11.4K
Snippets
33
Records
51
Agent score
77%

What's inside KiCanvas

  1. Overview of KiCanvas

    main

    KiCanvas is an interactive, browser-based viewer for KiCad schematics and boards. It is designed to be a read-only viewer that parses KiCad files directly without requiring any external plugins. It is built using modern vanilla TypeScript and utilizes the HTML5 Canvas element and WebGL for high-performance rendering.

    Key Characteristics:

    • Read-only: It is not intended to be a browser-based editor.
    • Dependency-free: It does not pull in additional libraries to avoid interference with host websites.
    • Direct Parsing: It reads KiCad files directly, meaning no special KiCad plugins are needed to view files.

  2. Understand the KiCanvas development roadmap

    main

    KiCanvas is currently focused on parsing and rendering KiCad files, with a secondary focus on its embedding API.

    Current Capabilities:

    • Parsing: Supports KiCad .sch, .pcb, .wks, and .pro files (including KiCad 6 and 7).
    • Rendering: Supports schematics, boards, text, and worksheets, including hierarchical schematics.
    • Viewer Features: Includes pan/zoom, symbol/footprint selection and inspection, layer visibility, and theming.
    • Embedding: Supports both non-interactive and interactive document embedding.
    • Browser Support: Compatible with Chrome, Firefox, and Safari.

    Planned Features:

    • Rendering of bitmap objects and custom fonts.
    • Advanced board selection (traces, zones).
    • Fragment, footprint, and symbol embedding.
    • Integrations with MkDocs, Jupyter, and Sphinx.

  3. Understand KiCanvas source code organization

    main

    The source code under ./src is organized into functional modules. If you are extending the project or building custom viewers, understanding these boundaries is essential:

    • base: Generic utilities for JavaScript, TypeScript, the DOM, and mathematics.
    • kicad: The KiCad data layer, including parsers for KiCad files and text layout implementations.
    • graphics: The rendering engine. It handles primitives (lines, circles, polygons) and is tailored for KiCanvas's specific rendering needs.
    • viewers: Implementations of viewers for different KiCad documents. Viewers use "Painters" to create geometry and manage "Layers" for the renderer. They provide high-level APIs for UI elements to control them but do not provide a UI themselves.
    • kc-ui: Low-level, generic Web Components (e.g., <kc-ui-button>, <kc-ui-icon>) that can be reused in other projects.
    • kicanvas: The core KiCanvas application logic and high-level UI elements (e.g., <kc-project-panel>, <kc-symbols-panel>).

  4. Technical overview of KiCanvas architecture

    main

    KiCanvas is built using modern vanilla TypeScript and leverages the HTML5 Canvas element and WebGL for high-performance rendering. The user interface is constructed using standard Web Components.

    A key architectural feature is that KiCanvas has no runtime dependencies. All necessary logic is bundled together, ensuring that nothing pollutes the global namespace, which makes the library easy to embed into other applications.

  5. Identify KiCanvas non-goals and limitations

    main

    When planning your integration, be aware of the following architectural constraints and non-goals:

    • Read-Only: KiCanvas is strictly a viewer. It does not support editing of any kind; this assumption is baked into the core code.
    • No 3D Rendering: It does not support 3D board or component rendering.
    • No Offline Rendering: Rendering is performed in the browser.
    • No Server-Side Usage: The tool is designed for client-side execution.
    • No Framework-Specific Integrations: KiCanvas does not provide dedicated wrappers for React, Vue, etc. Instead, it is built using Web Components, meaning it is designed to work out of the box with any web framework.

  7. Embed KiCanvas on your own website

    main

    You can use KiCanvas on your own websites via the embedding API.

    Note: As of the current version, the developer-facing APIs for embedding and parsing are still in early development and are subject to rapid changes. It is not yet published on NPM to avoid breaking changes for users.

    For detailed instructions on how to implement the embedding API, refer to the embedding guide.

  9. Generate the Newstroke font header using AWK

    main

    To compile the Newstroke font project into a C header file (newstroke_font.h), use the fontconv.awk script with the provided library files and the Unicode character map. This process converts the KiCad library format into a C source header.

    awk -f fontconv.awk symbol.lib font.lib charlist.txt >newstroke_font.h

  10. How to edit and update Newstroke glyphs

    main

    The Newstroke font is managed as a KiCad library. To modify the font:

    1. Edit Glyphs: Use the KiCad EESchema library editor to modify the glyphs in the .lib files.
    2. Update Mapping: Add new Unicode positions to charlist.txt to map the glyphs correctly.
    3. Regenerate: Run the AWK compilation command to produce a new newstroke_font.h header.

  11. How layers work in Canvas2DRenderer

    main

    The Canvas2DRenderer uses a layer-based system to organize draw commands. Instead of drawing directly to the canvas immediately, commands are collected into Canvas2dRenderLayer instances. This is similar to generating a display list.

    To use layers:

    1. Call start_layer(name: string) to begin recording commands for a new layer.
    2. Execute drawing commands (e.g., line, circle, polygon).
    3. Call end_layer() to finalize the current layer and add it to the renderer's layer stack.

    You can iterate over all created layers using the layers property.

    renderer.start_layer("background");
renderer.circle({ x: 50, y: 50 }, 20, new Color("white"));
renderer.end_layer();

renderer.start_layer("foreground");
renderer.line([{ x: 0, y: 0 }, { x: 100, y: 100 }], 5, new Color("black"));
renderer.end_layer();

// Accessing layers
for (const layer of renderer.layers) {
  console.log(layer.name);
}

  12. Understand KiCanvas geometric primitives

    main
    In KiCanvas, shapes like Circle, Arc, Polygon, and Polyline are treated as dumb data structures. They hold geometric information (points, radii, angles) and styling (colors, widths), but they do not contain the logic to actually draw themselves. The actual rendering logic is implemented by specific Renderer classes that consume these shape objects.