@modular-circuit/ir 0.0.63 → 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,739 @@
+import { GRAPHICS_ITEM, VECTOR2, Color, GRAPHICS_TEXT, At, GS_Junction, ELECTRICAL_PINTYPE, GRAPHIC_PINSHAPE, GS_NoConnect, LabelShapes, GS_SCH_LINE, PortLike, PortType, GroundParam, VoltageSourceParam, Connection } from '@modular-circuit/electronics-model';
+
+interface EDA_ITEM extends GRAPHICS_ITEM {
+}
+
+interface Font {
+    face?: string;
+    size: VECTOR2;
+    thickness?: number;
+    bold?: boolean;
+    italic?: boolean;
+    color?: Color;
+}
+
+interface Justify {
+    horizontal: 'left' | 'center' | 'right';
+    vertical: 'top' | 'center' | 'bottom';
+    mirror?: boolean;
+}
+
+interface Effects {
+    font: Font;
+    justify?: Justify;
+    hide?: boolean;
+}
+
+interface EDA_TEXT extends GRAPHICS_TEXT {
+    effects: Effects;
+}
+
+declare enum FILE_TYPE {
+    FONT = 0,
+    MODEL = 1,
+    WORKSHEET = 2,
+    DATA_SHEET = 3,
+    OTHER = 4
+}
+interface EMBEDDED_FILE {
+    Validate: () => boolean;
+    GetLink: () => string;
+    name: string;
+    type: FILE_TYPE;
+    is_valid: boolean;
+    compressedEncodedData: string;
+    decompressedData: string;
+    data_sha: string;
+}
+interface EMBEDDED_FILES {
+    AddFile(file: EMBEDDED_FILE): void;
+    RemoveFile(filename: string): void;
+    HasFile(filename: string): boolean;
+    IsEmpty(): boolean;
+    UpdateFontFiles(): string[];
+    GetFontFiles(): string[];
+    GetEmbeddedFile(filename: string): EMBEDDED_FILE | undefined;
+    files: {
+        [filename: string]: EMBEDDED_FILE;
+    };
+    fontFile: string[];
+}
+
+interface Fill {
+    type: 'none' | 'outline' | 'background' | 'color';
+    color?: Color;
+}
+
+declare const PaperSize: {
+    User: readonly [431.8, 279.4];
+    A0: readonly [1189, 841];
+    A1: readonly [841, 594];
+    A2: readonly [594, 420];
+    A3: readonly [420, 297];
+    A4: readonly [297, 210];
+    A5: readonly [210, 148];
+    A: readonly [279.4, 215.9];
+    B: readonly [431.8, 279.4];
+    C: readonly [558.8, 431.8];
+    D: readonly [863.6, 558.8];
+    E: readonly [1117.6, 863.6];
+    USLetter: readonly [279.4, 215.9];
+    USLegal: readonly [355.6, 215.9];
+    USLedger: readonly [431.8, 279.4];
+};
+type PaperSizeName = keyof typeof PaperSize;
+
+interface Paper {
+    size: PaperSizeName;
+    width?: number;
+    height?: number;
+}
+
+interface SERIALIZABLE {
+    Serialize(): JSON;
+    Deserialize(data: JSON): void;
+}
+
+interface Stroke {
+    width: number;
+    type: 'dash' | 'dot' | 'dash_dot' | 'dash_dot_dot' | 'solid' | 'default';
+    color?: Color;
+}
+
+interface TitleBlock {
+    title: string;
+    date: string;
+    rev: string;
+    comment: Record<string, string>;
+}
+
+interface SCH_ITEM extends EDA_ITEM {
+}
+
+interface BASE_SYMBOL extends SCH_ITEM {
+    unit?: number;
+    convert?: number;
+    in_bom: boolean;
+    on_board: boolean;
+    dnp: boolean;
+    fields_autoplaced: boolean;
+    exclude_from_sim: boolean;
+}
+
+interface Bus extends GRAPHICS_ITEM {
+    pts: VECTOR2[];
+    stroke: Stroke;
+}
+
+interface BusAlias {
+    name: string;
+    members: string[];
+}
+
+interface BusEntry extends GRAPHICS_ITEM {
+    at: At;
+    size: VECTOR2;
+    stroke: Stroke;
+}
+
+declare enum SHAPE_T {
+    SEGMENT = "line",
+    RECTANGLE = "rect",/// use RECTANGLE instead of RECT to avoid collision in a Windows header
+    ARC = "arc",
+    CIRCLE = "circle",
+    POLY = "polyline",
+    BEZIER = "bezier"
+}
+interface GraphicItem {
+    stroke?: Stroke;
+    fill?: Fill;
+}
+interface Polyline extends GraphicItem {
+    shape: SHAPE_T.POLY;
+    pts: VECTOR2[];
+}
+interface Arc extends GraphicItem {
+    shape: SHAPE_T.ARC;
+    start: VECTOR2;
+    mid: VECTOR2;
+    end: VECTOR2;
+}
+interface Bezier extends GraphicItem {
+    shape: SHAPE_T.BEZIER;
+    pts: VECTOR2[];
+}
+interface Circle extends GraphicItem {
+    shape: SHAPE_T.CIRCLE;
+    center: VECTOR2;
+    radius: number;
+}
+interface Rectangle extends GraphicItem {
+    shape: SHAPE_T.RECTANGLE;
+    start: VECTOR2;
+    end: VECTOR2;
+}
+interface TextBox extends GraphicItem {
+    shape: SHAPE_T.RECTANGLE;
+    text: string;
+    at: At;
+    size: VECTOR2;
+    effects: Effects;
+}
+
+interface SCH_TEXT extends SCH_ITEM, EDA_TEXT {
+    exclude_from_sim?: boolean;
+}
+
+interface SCH_TEXT_BOX extends SCH_ITEM, EDA_TEXT {
+}
+
+type Drawing = Arc | Bezier | Circle | Polyline | Rectangle | SCH_TEXT | SCH_TEXT_BOX;
+
+interface Junction extends GS_Junction {
+    color?: Color;
+}
+
+interface PIN_ALTERNATE {
+    name: string;
+    type: ELECTRICAL_PINTYPE;
+    shape: GRAPHIC_PINSHAPE;
+}
+
+interface PIN_DEFINITION {
+    type: ELECTRICAL_PINTYPE;
+    shape: GRAPHIC_PINSHAPE;
+    hide?: boolean;
+    at: At;
+    length: number;
+    name: {
+        text: string;
+        effects: Effects;
+    };
+    number: {
+        text: string;
+        effects: Effects;
+    };
+    alternates?: PIN_ALTERNATE[];
+}
+
+interface SCH_FIELD extends EDA_TEXT {
+    name: string;
+}
+
+interface SCH_ITEM_PROPERTY extends Omit<SCH_FIELD, 'uuid'> {
+}
+
+interface PIN_DISPLAY_OPT {
+    offset?: number;
+    hide?: boolean;
+}
+interface LIB_SYMBOL {
+    name: string;
+    power?: true;
+    pin_numbers?: PIN_DISPLAY_OPT;
+    pin_names?: PIN_DISPLAY_OPT;
+    exclude_from_sim?: boolean;
+    in_bom?: boolean;
+    on_board?: boolean;
+    properties?: SCH_ITEM_PROPERTY[];
+    children?: LIB_SYMBOL[];
+    pins?: PIN_DEFINITION[];
+    drawings?: Drawing[];
+}
+
+interface LIB_SYMBOLS {
+    symbols: LIB_SYMBOL[];
+}
+
+interface NoConnect extends GS_NoConnect {
+}
+
+interface PIN_INSTANCE extends GRAPHICS_ITEM {
+    number: string;
+    alternate?: string;
+}
+
+interface SCH_IMAGE extends GRAPHICS_ITEM {
+    at: At;
+    data: string;
+    scale: number;
+}
+
+type LabelType = 'label' | 'global_label' | 'hierarchical_label';
+interface SCH_LABEL_BASE extends SCH_TEXT {
+    fields?: SCH_FIELD[];
+    shape: LabelShapes;
+    fields_autoplaced?: boolean;
+}
+interface NetLabel extends Omit<SCH_LABEL_BASE, 'shape'> {
+    label_type: 'label';
+}
+interface GlobalLabel extends SCH_LABEL_BASE {
+    label_type: 'global_label';
+}
+interface HierarchicalLabel extends SCH_LABEL_BASE {
+    label_type: 'hierarchical_label';
+}
+type SCH_LABEL = NetLabel | GlobalLabel | HierarchicalLabel;
+interface LABEL_META {
+    text: string;
+    shape: LabelShapes;
+}
+
+interface SCH_LINE extends SCH_ITEM, GS_SCH_LINE {
+    stroke: Stroke;
+}
+
+interface SCH_SHEET_PIN extends HierarchicalLabel {
+}
+
+/**
+ * 摆放在画布中的原理图符号，通过SHEET_FILENAME字段关联实际设计
+ * SHEET_FILENAME字段内容可以是项目中设计的相对路径比如module_a.kicad_sch
+ * 也可以是指向registry中的project，比如@eda.cn/module_a
+ */
+interface SCH_SHEET extends SCH_ITEM {
+    at: At;
+    size: VECTOR2;
+    pins: SCH_SHEET_PIN[];
+    fields: SCH_FIELD[];
+    fields_autoplaced: boolean;
+    stroke: Stroke;
+    fill: Required<Omit<Fill, 'type'>>;
+}
+
+interface SCH_SHEET_INSTANCE {
+    path: string;
+    page?: string;
+    project: string;
+}
+
+interface SYMBOL_INSTANCE {
+    path: string;
+    project?: string;
+    reference?: string;
+    value?: string;
+    unit?: number;
+    footprint?: string;
+}
+
+/**
+ * lib_id is enough for performing ERC for power symbols
+ */
+interface SCH_SYMBOL_META {
+    lib_id: string | null;
+}
+interface SCH_SYMBOL extends BASE_SYMBOL, SCH_SYMBOL_META {
+    lib_name?: string;
+    at: At;
+    mirror?: 'x' | 'y';
+    properties: SCH_ITEM_PROPERTY[];
+    pins: PIN_INSTANCE[];
+    instances?: SYMBOL_INSTANCE[];
+}
+
+/**
+ * KiCad原理图符号的固有属性
+ */
+interface SCH_SYMBOL_PROPERTIES {
+    value: string;
+    footprint: string;
+}
+
+interface SheetInstance {
+    page: string;
+    path: string;
+}
+
+interface SheetInstances {
+    sheet_instances: Record<string, SheetInstance>;
+}
+
+/**
+ * 一张完整的原理图
+ */
+interface SCHEMATIC extends EDA_ITEM {
+    version: number;
+    generator: string;
+    generator_version: string;
+    paper: Paper;
+    title_block: TitleBlock;
+    lib_symbols?: LIB_SYMBOLS;
+    labels?: SCH_LABEL[];
+    symbols?: SCH_SYMBOL[];
+    wires?: SCH_LINE[];
+    buses?: Bus[];
+    bus_entries?: BusEntry[];
+    bus_aliases?: BusAlias[];
+    junctions?: Junction[];
+    no_connects?: NoConnect[];
+    drawings?: (Polyline | SCH_TEXT)[];
+    images?: SCH_IMAGE[];
+    sheet_instances?: SheetInstances;
+    symbol_instances?: SYMBOL_INSTANCE;
+    sheets?: SCH_SHEET[];
+}
+
+declare enum SHEET_FIELD_TYPE {
+    SHEETNAME = 0,
+    SHEETFILENAME = 1,
+    SHEET_MANDATORY_FIELDS = 2
+}
+
+interface ComponentProperty {
+    /**
+     * 器件的类型
+     */
+    readonly Type: string;
+    /**
+     * 器件的MPN
+     */
+    MPN: string;
+    /**
+     * 器件的制造商
+     */
+    Manufacturer: string;
+    /**
+     * 器件的值
+     */
+    Value: string;
+    /**
+     * 器件的备注
+     */
+    Description: string;
+    /**
+     * 器件的类别
+     */
+    readonly Category: string;
+    /**
+     * 器件的包体
+     */
+    readonly Package: string;
+    /**
+     * 器件生命周期
+     */
+    readonly Lifecycle: string;
+    /**
+     * 器件关联的封装
+     */
+    readonly Footprint: string;
+    /**
+     *器件的数据表
+     */
+    readonly Datasheet: string;
+}
+
+interface Component extends ComponentProperty {
+}
+
+/**
+ * 允许为BOM中器件添加替代料（2nd source,3rd source）
+ */
+interface BomItem extends ComponentProperty {
+    /**
+     * 位号
+     */
+    readonly Designator: string;
+    /**
+     * 元器件, undefined 表示未匹配
+     */
+    component: Component | undefined;
+    /**
+     * 替代料的元器件
+     */
+    alternatives: Component[];
+}
+
+type EDA_PORT_ANNOTATION = SCH_SYMBOL_META | LABEL_META;
+declare const KICAD_GND_NAME = "GND";
+declare enum PORT_ANNOT_TYPE {
+    NORMAL_SYMBOL_PIN = 0,
+    GLOBAL_GND_PIN = 1,
+    GLOBAL_POWER_PIN = 2
+}
+interface EDA_PORT_ELECTRICAL_ANNOT {
+    pin_type: ELECTRICAL_PINTYPE;
+    port_annot_type: PORT_ANNOT_TYPE;
+}
+declare function parse_eda_annotation(eda_annotation?: EDA_PORT_ANNOTATION): EDA_PORT_ELECTRICAL_ANNOT;
+
+/**
+ * 除了HierarchicalLabel之外，也包含了电源符号
+ */
+type DesignPort = PortLike & EDA_PORT_ANNOTATION;
+
+/**
+ * 模组的BOM展示与模块的BOM略有不同，需要先展示模组中使用的模块
+ */
+interface ModuleBom {
+    [index: string]: BomItem[] | ModuleBom;
+}
+
+/**
+ * .module_circuit后缀(模组)或者.kicad_sch后缀(模块)的文件，对应于KiCad的.kicad_sch和PolymorphicBlocks的Design
+ */
+interface ModuleDesignBase extends SCHEMATIC {
+    get_ports(): DesignPort[];
+}
+/**
+ * 项目的设计
+ */
+interface ProjectDesign extends SCHEMATIC {
+    get_bom(): ModuleBom;
+}
+/**
+ * 项目填充了Port之后才可以发布为模块
+ */
+interface PublishedProjectDesign extends ProjectDesign {
+    get_ports(): DesignPort[];
+}
+/**
+ * 从EDA图纸创建的模块，并从其中自动提取Port及BOM
+ */
+interface EDA_DESIGN {
+    readonly bom_is_complete: boolean;
+}
+/**
+ * 通用模块，仅包含基础属性但并不完全(元器件并未指定到具体的型号)的模块，,摆放到设计后再推荐其元器件值和型号
+ */
+interface GeneralModuleDesign extends ModuleDesignBase, EDA_DESIGN {
+    readonly bom_is_complete: true;
+    get_recommendation(): BomItem[][];
+}
+/**
+ * 包含了完整BOM的模块
+ */
+interface ConcreteBlockDesign extends ModuleDesignBase, EDA_DESIGN {
+    readonly bom_is_complete: false;
+    get_bom(): BomItem[];
+}
+type ReusableDesign = GeneralModuleDesign | ConcreteBlockDesign | PublishedProjectDesign;
+type Design = ProjectDesign | ReusableDesign;
+
+/**
+ * 除了SHEET_PIN之外，也包含了电源符号
+ */
+type BlockPort = PortLike & (SCH_SHEET_PIN & SCH_SYMBOL);
+
+/**
+ * 模块的属性，依次是名称、值、单位、功能
+ */
+interface ModuleSpec {
+    name: string;
+    value: string;
+    unit?: string;
+    functionality: string;
+}
+
+declare const MODULAR_CIRCUIT_EXT = "modular_circuit";
+/**
+ *用户通过Design Studio创建的项目
+ */
+interface Project {
+    /**
+     * 项目的id
+     */
+    id: string;
+    /**
+     * 项目的名称
+     */
+    name: string;
+    /**
+     * 项目的主文件，可以是.kicad_sch或者.modular_circuit
+     */
+    main: string;
+    /**
+     * 项目的作者
+     */
+    author: string;
+    /**
+     * 项目的短描述
+     */
+    short_description: string;
+    /**
+     * 项目的详细描述
+     */
+    detailed_description: string;
+    /**
+     * 项目的创建时间
+     */
+    create_date_time: string;
+    /**
+     * 模块或者项目的特性
+     */
+    specifications: ModuleSpec[];
+    /**
+     * 项目的依赖
+     */
+    dependencies: {
+        [key: string]: string;
+    };
+}
+
+/**
+ * 模块标签用于快速搜索、定位相似功能的模块
+ * 预置的Tag由管理员定义
+ * “LDO”、“电源转换”、“3.3V”等
+ */
+interface Tag {
+    name: string;
+}
+
+interface BlockBase extends SCH_SHEET {
+    /**
+     *  对应KiCad的SCH_SHEET_PIN的拓展
+     *  现在的思路是分别拿SCH_SHEET_PIN 跟Named Port Map 中的同名Port拼出来一个SheetPort
+     */
+    get_ports(): BlockPort[];
+}
+
+/**
+ *摆到画布中的模块
+ */
+interface KiCadBlock extends BlockBase {
+    has_bom(): boolean;
+}
+
+/**
+ * 摆放到画布中的模组
+ */
+interface ModuleBlock extends BlockBase {
+    get_kicad_blocks(): KiCadBlock[];
+    get_module_blocks(): ModuleBlock[];
+}
+
+/**
+ *项目在填充了Ports之后即可发布为模块，可以是在Design Studio中创建并发布的项目，也可以是后台从EDA设计发布的项目
+ */
+interface ModuleCircuit extends Project {
+    /**
+     * 模块的版本，须符合semantic versioning
+     */
+    version: string;
+    /**
+     EDA工具制作的原理图自带的可有效用于ERC检查的端口信息，对于Global Power，Value相同的视作同一端口，比如GND、+3.3V、-5V等，
+     同时Global Power的Value也会用作EDA_PORT_ANNOTATION的key
+     */
+    eda_port_annotations: {
+        [key: string]: EDA_PORT_ANNOTATION;
+    };
+    /**
+     * 模块的端口定义，既会用于ERC检查、也会用于生成网表并最终生成kicad原理图，一个Port里可以有一个或者多个信号（层次标签）
+     */
+    ports: PortLike[];
+    /**
+     * BOM是否齐备
+     */
+    bom_matched: boolean;
+    /**
+     * 分类为树形结构由管理员定义，用户无法修改；这里存放的是树形结构节点的code name ，每个节点的code name 是唯一的
+     */
+    categories: string[];
+    /**
+     * 项目的分类标签
+     */
+    tags: Tag[];
+    /**
+     * 模块的BOM
+     */
+    bom: BomItem[];
+}
+
+interface ModuleName {
+    author: string;
+    name: string;
+}
+interface ModuleIndex extends ModuleName {
+    version: string;
+}
+type RuntimeModuleCircuit = ModuleCircuit & {
+    cate_name: string;
+    file_zip: string;
+};
+interface ModuleResolver {
+    /**
+     * 获取一个已发布项目(项目)的design(.zip)的url
+     * 项目发布时候是作为zip发布，里面是平铺的.kicad_sch或者.modular_circuit
+     */
+    get_module_archive(idx: ModuleIndex): Promise<URL | undefined>;
+    /**
+     * 获取模块的详细信息
+     */
+    get_module_circuit(idx: ModuleIndex): Promise<ModuleCircuit | undefined>;
+    /**
+     * 获取模块的详细信息
+     */
+    get_module_circuit_by_id(id: string): Promise<ModuleCircuit | undefined>;
+    /**
+     * 根据后端的id获取一个已发布项目(项目)的design(.zip)的url
+     */
+    get_module_archive_by_id(id: string): Promise<URL | undefined>;
+}
+
+interface IR_GraphItem extends GRAPHICS_ITEM {
+}
+
+interface IR_Port extends IR_GraphItem {
+    /**
+     *递增的端口序号，对应于模块定义中的PortList (VIEW层从1开始)
+     */
+    index: number;
+    /**
+     * 可以重复、同一模块中只有index才是唯一的
+     */
+    name: string;
+    /**
+     * 电气端口类型
+     */
+    shape: ELECTRICAL_PINTYPE;
+    type: PortType | string;
+}
+
+interface IR_Block extends IR_GraphItem {
+    name?: string;
+    /**
+     * 模块类型
+     */
+    type: ModuleName;
+    /**
+     * 模块摆到画布上之后的ID
+     */
+    ports: IR_Port[];
+}
+
+interface PowerBase extends IR_GraphItem {
+    value: string;
+}
+
+interface IR_GND extends PowerBase {
+    param?: GroundParam;
+}
+
+interface IR_Junction extends IR_GraphItem {
+}
+
+interface IR_Label extends IR_GraphItem {
+    type: LabelType;
+    text: string;
+}
+
+interface IR_PowerSym extends PowerBase {
+    param?: VoltageSourceParam;
+}
+
+interface IR_Wire extends IR_GraphItem, Connection {
+}
+
+interface IR_Graph extends IR_GraphItem {
+    name?: string;
+    blocks?: IR_Block[];
+    wires?: IR_Wire[];
+    gnd?: IR_GND[];
+    pwr?: IR_PowerSym[];
+    labels?: IR_Label[];
+    junctions?: IR_Junction[];
+}
+
+declare const MODULAR_CIRCUIT_SCH_EXT = "modular_circuit";
+
+export { type Arc, type BASE_SYMBOL, type Bezier, type BlockBase, type BlockPort, type BomItem, type Bus, type BusAlias, type BusEntry, type Circle, type Component, type ComponentProperty, type ConcreteBlockDesign, type Design, type DesignPort, type Drawing, type EDA_DESIGN, type EDA_ITEM, type EDA_PORT_ANNOTATION, type EDA_PORT_ELECTRICAL_ANNOT, type EDA_TEXT, type EMBEDDED_FILE, type EMBEDDED_FILES, type Effects, FILE_TYPE, type Fill, type Font, type GeneralModuleDesign, type GlobalLabel, type GraphicItem, type HierarchicalLabel, type IR_Block, type IR_GND, type IR_Graph, type IR_GraphItem, type IR_Junction, type IR_Label, type IR_Port, type IR_PowerSym, type IR_Wire, type Junction, type Justify, KICAD_GND_NAME, type KiCadBlock, type LABEL_META, type LIB_SYMBOL, type LIB_SYMBOLS, type LabelType, MODULAR_CIRCUIT_EXT, MODULAR_CIRCUIT_SCH_EXT, type ModuleBlock, type ModuleBom, type ModuleCircuit, type ModuleDesignBase, type ModuleIndex, type ModuleName, type ModuleResolver, type ModuleSpec, type NetLabel, type NoConnect, type PIN_ALTERNATE, type PIN_DEFINITION, type PIN_DISPLAY_OPT, type PIN_INSTANCE, PORT_ANNOT_TYPE, type Paper, PaperSize, type PaperSizeName, type Polyline, type Project, type ProjectDesign, type PublishedProjectDesign, type Rectangle, type ReusableDesign, type RuntimeModuleCircuit, type SCHEMATIC, type SCH_FIELD, type SCH_IMAGE, type SCH_ITEM, type SCH_ITEM_PROPERTY, type SCH_LABEL, type SCH_LINE, type SCH_SHEET, type SCH_SHEET_INSTANCE, type SCH_SHEET_PIN, type SCH_SYMBOL, type SCH_SYMBOL_META, type SCH_SYMBOL_PROPERTIES, type SCH_TEXT, type SCH_TEXT_BOX, type SERIALIZABLE, SHAPE_T, SHEET_FIELD_TYPE, type SYMBOL_INSTANCE, type SheetInstance, type SheetInstances, type Stroke, type Tag, type TextBox, type TitleBlock, parse_eda_annotation };