优化NCWriter参数格式和用法

新增NCBuilder接口；
优化部分类型定义，格式化代码；

Reviewed-on: #11
Reviewed-by: 谢凡 <xief@163.com>
Co-authored-by: 2817212736@qq.com <2817212736@qq.com>
Co-committed-by: 2817212736@qq.com <2817212736@qq.com>

README.md

@@ -95,3 +95,58 @@ pnpm clean
 pnpm build  
 pnpm release  
 ```
+
+## 开发
+
+### 处理器类型
+
+处理器的上下文类型应当提交至该项目以方便协作，包括处理器输入，输出以及配置类型。  
+这些类型应当定义在`src/models/processors/<处理器名>.ts`文件中。
+例：
+
+```ts
+// src/models/processors/rectLayout.ts
+
+// 矩形优化处理器类型
+
+export interface RectLayoutProcInput {
+  blocks: Array<RectLayoutBlock>
+}
+export type RectLayoutProcOutput = never;
+export class RectLayoutProcConfig extends ConfigBase {}
+
+export interface RectLayoutBlock {}
+
+```
+
+定义类型时请遵循以下约定：
+
+- 处理器的输入/输出/配置类型(以下称为*相关类型*)请按照特定规则进行命名，其大小写应当遵循[PascalCase](https://pascal-case.com/)：
+  - 输入类型: `<处理器名>Input`
+  - 输出类型: `<处理器名>Output`
+  - 配置类型: `<处理器名>Config`
+- 处理器的配置类型必须为一个Javascript类，并继承自抽象类`ConfigBase`，输入和输出类型不限。
+- 处理器相关类型的字段若涉及到附属类型，也一并定义在文件中，其命名不限，但必须与处理器的名字有所关联，不易于其它处理器混淆，例：
+
+  ```ts
+  export interface RectLayoutProcInput {
+    blocks: Array<RectLayoutBlock> // 附属类型
+  }
+  // 同样定义在该文件中，
+  export interface RectLayoutBlock {}
+  ```
+
+- 若处理器相关类型中出现了唯一标识符，请统一使用`string | number`作为Typescript类型，例：
+
+  ```ts
+  export interface RectLayoutBlock {
+    id: string | number; // 使用string | number类型作为唯一标识符  
+  }
+  ```
+
+- 若处理器相关类型中出现了平面尺寸相关的，请使用“长(`length`)/宽(`width`)”作为其名称，请勿使用“宽(`width`)/高(`height`)”。
+  
+  > [!Warning]
+  > “长”指的是一个矩形板件在**横轴**上的尺寸，而“宽”指的是**纵轴**上的尺寸。
+  > 
+  > 在旧版生产的数据中，“长/宽”与“宽/高”是混用的，在矩形优化后，原有板件的“长(l)”变为了“高(pbg)”，而“宽(w)”变为了“宽(pbk)”，因为矩形优化涉及到了坐标转换，后续还需要对规范进行统一。

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cut-abstractions",
-  "version": "0.2.0",
+  "version": "0.3.3",
   "description": "",
   "files": [
     "dist/**/*"

src/base.ts

@@ -4,7 +4,7 @@ import { ConfigBase } from "./models/config";
 /**
  * 加工处理器上下文
  */
-export interface ProcessorContext<TInput, TOutput, TConfig extends ConfigBase> {
+export interface ProcessorContext<TInput = any, TOutput = any, TConfig extends ConfigBase = ConfigBase> {
     /**
      * 输入数据
      */

src/index.ts

@@ -4,4 +4,9 @@ export * from './models/config';
 export * from './models/knife';
 export * from './models/file';
 export * from './models/processors/rectLayout';
-export * from './models/processors/cutOrder'
+export * from './models/processors/cutOrder';
+export * from './models/processItem';
+export * from './models/processors/modelProcessPoints';
+export * from './models/processors/cutPoint';
+export * from './models/processors/holeToModel';
+export * from './nc/ncWriter';

src/models/config.ts

@@ -2,17 +2,17 @@
  * 配置基类,下划线开头的变量不会被序列化
  */
 export class ConfigBase {
-    name: string = '';
-    version:string = '1.0.0';
+    readonly name: string = '';
+    readonly version: string = '1.0.0';
     [key: string]: any;
 
     /**
      * 加载反序列化数据
      * @param data 
      */
-    load(data:Record<string,unknown>){
-        for (const key of Object.getOwnPropertyNames(this).filter(i=>i[0]!=='_')) {
-            if(data[key]!=undefined){
+    load(data: Record<string, unknown>) {
+        for (const key of Object.getOwnPropertyNames(this).filter(i => i[0] !== '_')) {
+            if (data[key] != undefined) {
                 this[key] = data[key];
             }
         }
@@ -22,7 +22,7 @@ export class ConfigBase {
      * 序列化json方法
      * @returns 
      */
-    toJson(){
-        return JSON.stringify(this,(k,v)=>k[0]=='_'?undefined:v);
+    toJson() {
+        return JSON.stringify(this, (k, v) => k[0] == '_' ? undefined : v);
     }
 }

src/models/processors/cutPoint.ts

@@ -0,0 +1,59 @@
+import { ConfigBase } from "../config"
+import { IProcessingItem } from "../processItem"
+
+/**
+ * 下刀点 入参
+ */
+export type CutPointInput = {
+
+    /** (余料板异形点) 开料大板的开料轮廓数据 若没有则需要传 开料大板宽、高*/
+    boardPointInfo?: IProcessingItem,
+    /** 开料大板宽 若有 boardPointInfo 则不需要传 */
+    boardWidth?: number,
+    /** 开料大板长 若有 boardPointInfo 则不需要传 */
+    boardLength?: number
+    /** 小板数据集 */
+    blocks?: CutPointInputBlock[]
+}
+/** 处理器输出---下刀点 */
+export type CutPointOutput = {
+    blocks: CutPointOutputBlock[]
+}
+
+/**
+ * 小板类型 输入
+ */
+export type CutPointInputBlock = {
+    /** 小板唯一标识  */
+    id: string | number;
+    /** 排版长 */
+    length: number;
+    /** 排版宽 */
+    width: number;
+    /** 板件坐标X */
+    x: number;
+    /** 板件坐标y */
+    y: number;
+    /** 开料顺序 */
+    cutOrder: number;
+    /** 
+     * 板件轮廓 
+     * 用以分析下刀点的板件轮廓 
+     * */
+    blockPoints: IProcessingItem
+    /** 是否异形  true 是异形  false 矩形 */
+    isUnRegular: boolean
+};
+
+/** 小板类型 输出 */
+export type CutPointOutputBlock = CutPointInputBlock & {
+    /** 下刀点  板件轮廓的下标 */
+    cutPointId?: number,
+}
+
+/** 下刀点配置 
+ * 
+ * 注：暂时没有配置项
+ */
+export declare class CutPointConfig extends ConfigBase {
+}

src/models/processors/holeToModel.ts

@@ -0,0 +1,38 @@
+import { ConfigBase } from "../config"
+import { IProcessingItem } from "../processItem"
+
+/** 处理器输入 -孔转造型*/
+export type HoleToModelInput = {
+    /** 孔信息 */
+    holeData: HoleToModelProcessingItem[],
+    /** 孔所在板件的优化后的坐标 X (可选)*/
+    placeX?: number,
+    /** 孔所在板件的优化后的坐标 Y (可选)*/
+    placeY?: number,
+    /** 孔所在板件的 厚度 */
+    thickness: number
+}
+/** 处理器输出-- 获取造型在大板的刀路 */
+export type HoleToModelOutput = {
+    /** 孔转造型 后的 造型数据 */
+    modelData: HoleToModelProcessingItem[],
+    /** 未处理的孔数据 以及信息 */
+    noHandleItem: noHandleItemType[]
+}
+export type noHandleItemType = {
+    /** 未处理的孔信息 */
+    holeData: HoleToModelProcessingItem,
+    /** 未处理 说明 */
+    info: string
+}
+/** 处理器配置-- 获取造型在大板的刀路  */
+export declare class HoleToModelProcConfig extends ConfigBase {
+
+}
+
+ 
+/** 加工项的类型  */
+export type HoleToModelProcessingItem = IProcessingItem & {
+    /** 使用刀具的刀半径 */
+    knifeRadius: number
+}

src/models/processors/modelProcessPoints.ts

@@ -0,0 +1,113 @@
+import { ConfigBase } from "../config"
+import { IPoint } from "../processItem"
+
+/** 处理器输入-- 获取造型在大板的刀路 */
+export type ModelProcessPointsInput = {
+    /** 小板数据 */
+    block: ModelProcessPointsInputBlock,
+    /** 小板的最终的放置位置 */
+    targetPosition: PositionType
+}
+/** 处理器输入--小板 -- 获取造型在大板的刀路 */
+export type ModelProcessPointsInputBlock = {
+    /** 板件唯一标识 */
+    id: string | number,
+    /** 板件基于大板的 坐标X */
+    x: number,
+    /** 板件基于大板的 坐标y */
+    y: number,
+    /** 板件(小板)长 */
+    length: number,
+    /** 板件(小板)宽 */
+    width: number,
+    /** 造型数据 依据放置方式positionType 下的造型数据  默认为 依据放置方式positionType.FRONT 的造型数据 */
+    models: ModelProcessItem[],
+    /** 板件的原放置方式 默认为正面（0） 不传则为正面  原 placestyle*/
+    positionType?: PositionType,
+    /** 偏移值 */
+    offsetInfo: OffsetInfo
+
+}
+/** 板件 上下左右 偏移值信息 */
+export type OffsetInfo = {
+    top: number,
+    bottom: number,
+    left: number,
+    right: number,
+}
+/** 处理器输出--小板 -- 获取造型在大板的刀路 */
+export type ModelProcessPointsOutputBlock = {
+    /** 板件唯一标识 */
+    id: string | number
+    /** 放置方式 */
+    positionType: PositionType
+    /** 造型数据 */
+    models: ModelProcessItem[]
+    /** 板件(小板)长 */
+    length: number,
+    /** 板件(小板)宽 */
+    width: number,
+    /** 偏移值 */
+    offsetInfo: OffsetInfo
+}
+/** 处理器输出-- 获取造型在大板的刀路 */
+export type ModelProcessPointsOutput = {
+    block: ModelProcessPointsOutputBlock
+}
+
+/** 处理器配置-- 获取造型在大板的刀路  暂无 */
+export declare class ModelProcessPointsProcConfig extends ConfigBase {
+
+}
+
+
+/** 造型类 */
+export interface ModelProcessItem {
+    /** 加工项唯一标识 */
+    id?: string | number
+    /**
+    * 加工点数组
+    */
+    pts: IPoint[];
+    /**
+     * 凸度数组
+     */
+    buls: number[];
+    /** 加工面 */
+    face: FaceType
+
+}
+
+/** 加工面 */
+export enum FaceType {
+    /** 正面 */
+    FRONT = 0,
+    /** 反面 */
+    BACK = 1,
+}
+
+ 
+/** 小板的放置方式 */
+export enum PositionType {
+    /** 正面 */
+    FRONT = 0,
+    /** 正面右转 */
+    FRONT_TURN_RIGHT = 1,
+    /** 正面后转 */
+    FRONT_TURN_BACK = 2,
+    /** 正面左转 */
+    FRONT_TURN_LEFT = 3,
+    /** 反面 */
+    BACK = 4,
+    /** 反面右转 */
+    BACK_TURN_RIGHT = 5,
+    /** 反面后转 */
+    BACK_TURN_BACK = 6,
+    /** 反面左转 */
+    BACK_TURN_LEFT = 7,
+}
+
+
+/** 行为类型  */
+export type RotationAction = 'doNothing' | 'turnLeft' | 'turnRight' | 'turnAround'
+

src/nc/ncWriter.ts

@@ -0,0 +1,161 @@
+import { Knife } from "../models/knife";
+
+/**
+ * NC代码构建器接口，实现该接口来定义一个处理器用的NC代码构建器
+ * @author CZY
+ * @since 0.3.0
+ * @version 0.1.2
+ */
+export interface INcWriter {
+    get ncActions(): NcAction[];
+
+    /**
+     * 写入G代码或解析一条自定义代码
+     * @example
+     * gCode('G0', { x: 0, y: 0, z: 0, f: 25000 });
+     * gCode('CArc', { x: 0, y: 0, z: 0, b: 1, f: 25000 });
+     */
+    gCode<TCode extends (keyof typeof GCode | keyof typeof CCode)>(code: TCode, params: Partial<TCode extends keyof typeof GCode ? GCodeParams : CCodeParams>): void;
+
+    /** 基于刀具实体执行换刀操作 */
+    changeKnife(knife: Knife): void;
+
+    /** 添加一行注释 */
+    comment(content: string): void;
+
+    /**
+     * 记录一次NC加工操作
+     * 
+     * NC加工操作指的是一次完整的加工过程，例如一次排钻，一次造型切割，或是一次小板加工
+     * 
+     * 一次NC加工操作可能包含多行的GCode
+     * 
+     * 该方法旨在为NC文件提供记录加工步骤的能力
+     * 
+     * 返回本次NC操作的ID，此ID由内部生成
+     * @param type NC操作类型
+     * @returns 本次NC操作的ID
+     */
+    recordAction(type: NcActionType): string;
+
+    /** 直接在末尾追加任意字符串 */
+    append(str: string): void;
+
+    /** 直接在末尾追加一行任意字符串 */
+    appendLine(str: string): void;
+
+    /** 返回当前构建的NC代码 */
+    toString(): string;
+}
+
+/** 基础G代码 */
+export const GCode = {
+    /**
+     * 快速定位
+     * @param X X 坐标
+     * @param Y Y 坐标
+     * @param Z Z 坐标
+     * @param F 给进速度 mm/min
+     * @example G0 X0 Y0 F25000
+     */
+    G0: 'G0',
+
+    /**
+     * 直线插补
+     * @param X X 坐标
+     * @param Y Y 坐标
+     * @param Z Z 坐标
+     * @param F 给进速度 mm/min
+     * @example G1 X0 Y0 F25000
+     */
+    G1: 'G1',
+
+    /**
+     * 顺时针圆弧插补
+     * @param X X 坐标
+     * @param Y Y 坐标
+     * @param Z Z 坐标
+     * @param I （圆心坐标模式）从圆弧起点到圆心在X轴上的**增量距离**
+     * @param J （圆心坐标模式）从圆弧起点到圆心在Y轴上的**增量距离**
+     * @param K （圆心坐标模式）从圆弧起点到圆心在Z轴上的**增量距离**
+     * @param R （圆弧半径模式）指定圆弧的半径
+     * @example
+     * ; 假设当前刀具在 (X10, Y0)
+     * G2 X0 Y10 I-10 J0 F150 ; 顺时针圆弧到X0 Y10，圆心在(0,0) (10 + (-10) = 0, 0 + 0 = 0)
+     * G2 X0 Y10 R10 F150 ; 顺时针圆弧到X0 Y10，半径10 (小于等于180度)
+     */
+    G2: 'G2',
+
+    /**
+     * 逆时针圆弧插补
+     * @param X X 坐标
+     * @param Y Y 坐标
+     * @param Z Z 坐标
+     * @param I （圆心坐标模式）从圆弧起点到圆心在X轴上的**增量距离**
+     * @param J （圆心坐标模式）从圆弧起点到圆心在Y轴上的**增量距离**
+     * @param K （圆心坐标模式）从圆弧起点到圆心在Z轴上的**增量距离**
+     * @param R （圆弧半径模式）指定圆弧的半径
+     * @example
+     * ; 假设当前刀具在 (X10, Y0)
+     * G3 X0 Y-10 I-10 J0 F150 ; 逆时针圆弧到X0 Y-10，圆心在(0,0)
+     * G3 X0 Y-10 R-10 F150 ; 逆时针圆弧到X0 Y-10，半径10 (大于180度)
+     */
+    G3: 'G3',
+} as const;
+
+/** 自定义数控代码，由内部解析并实现，不直接输出给设备 */
+export const CCode = {
+    /**
+     * 自动圆弧插补
+     * @param X X 坐标
+     * @param Y Y 坐标
+     * @param Z Z 坐标
+     * @param B Bulge圆弧凸度，表示圆弧所包含角度的四分之一的正切值。当B=0时，圆弧为直线，当B>0时，圆弧为顺时针圆弧，当B<0时，圆弧为逆时针圆弧 (所谓“顺时针”和“逆时针”是指从起始点到结束点的绘制角度)
+     * @description 使用此命令时，X, Y, Z作为圆弧的结束点，当前刀具的位置作为起始点。
+     * @example
+     * FROM: CArc X0 Y10 Z0 B1
+     * TO: G2 X0 Y10 R5  
+     */
+    CArc: 'CArc',
+} as const;
+
+/** NC GCode 参数结构 */
+export class GCodeParams {
+    /** X坐标值 mm */
+    x: number = 0;
+    /** Y坐标值 mm */
+    y: number = 0;
+    /** Z坐标值 mm */
+    z: number = 0;
+    /** 使用圆弧指令(G2,G3)的圆弧半径模式(R)时，定义圆弧半径 */
+    r: number = 0;
+    /** 使用圆弧指令(G2,G3)的圆心坐标模式(I,J,K)时，定义圆心坐标在X轴上的增量距离 */
+    i: number = 0;
+    /** 使用圆弧指令(G2,G3)的圆心坐标模式(I,J,K)时，定义圆心坐标在Y轴上的增量距离 */
+    j: number = 0;
+    /** 给进速度(Feed Rate) mm/min */
+    f: number = 0;
+};
+
+/** 自定义数控代码参数结构 */
+export class CCodeParams {
+    /** X坐标值 mm */
+    x: number = 0;
+    /** Y坐标值 mm */
+    y: number = 0;
+    /** Z坐标值 mm */
+    z: number = 0;
+    /** 使用自动圆弧(CArc)命令时，定义圆弧凸度 */
+    b: number = 0;
+    /** 给进速度(Feed Rate) mm/min */
+    f: number = 0;
+}
+
+/** 单次NC加工行为 */
+export interface NcAction {
+    readonly id: string;
+    readonly type: NcActionType;
+    readonly lineIndex: number;
+}
+
+export type NcActionType = string;