lbrnts 0.0.1

package/README.md

@@ -0,0 +1,394 @@
+# lbrnts
+
+A type-safe library for parsing and writing [LightBurn](https://lightburnsoftware.com/) files.
+
+## Installation
+
+```bash
+npm install lbrnts
+```
+
+## Usage
+
+### Parsing Existing Projects
+
+```tsx
+import { LightBurnProject } from "lbrnts"
+
+const project = LightBurnProject.parse(fs.readFileSync("project.lbrn2", "utf8"))
+
+console.log(project.children)
+```
+
+### Creating Projects from Scratch
+
+You can programmatically create LightBurn projects by constructing the project and its elements. Below is a table of all constructible classes with links to their documentation:
+
+| Class | Description |
+|-------|-------------|
+| [LightBurnProject](#lightburnproject) | Root project container |
+| [CutSetting](#cutsetting) | Cut/engrave settings (speed, power, etc.) |
+| [ShapePath](#shapepath) | Custom paths with lines and bezier curves |
+| [ShapeRect](#shaperect) | Rectangle shapes |
+| [ShapeEllipse](#shapeellipse) | Ellipse/circle shapes |
+| [ShapeText](#shapetext) | Text shapes |
+| [ShapeBitmap](#shapebitmap) | Bitmap/image shapes |
+| [ShapeGroup](#shapegroup) | Group container for shapes |
+| [Notes](#notes) | Project notes |
+| [VariableText](#variabletext) | Variable text settings |
+
+## API Reference
+
+### LightBurnProject
+
+The root container for a LightBurn project.
+
+#### Constructor
+
+```typescript
+new LightBurnProject(init?: {
+  appVersion?: string
+  formatVersion?: string
+  materialHeight?: number
+  mirrorX?: boolean
+  mirrorY?: boolean
+  children?: LightBurnBaseElement[]
+})
+```
+
+#### Example
+
+```typescript
+import { LightBurnProject, CutSetting, ShapePath } from "lbrnts"
+
+const cutSetting = new CutSetting({
+  index: 0,
+  name: "Wood Cut",
+  priority: 0,
+  type: "Cut",
+  speed: 10,
+  maxPower: 80,
+  minPower: 60,
+})
+
+const path = new ShapePath({
+  cutIndex: 0,
+  verts: [
+    { x: -25, y: -25 },
+    { x: 25, y: -25 },
+    { x: 25, y: 25 },
+    { x: -25, y: 25 },
+  ],
+  prims: [
+    { type: 0 },
+    { type: 0 },
+    { type: 0 },
+    { type: 0 },
+  ],
+  isClosed: true,
+})
+
+const project = new LightBurnProject({
+  appVersion: "1.7.03",
+  formatVersion: "1",
+  materialHeight: 0,
+  children: [cutSetting, path],
+})
+```
+
+#### Methods
+
+- `getChildren()`: Returns the children array
+
+---
+
+### CutSetting
+
+Defines cutting/engraving settings for laser operations.
+
+#### Constructor
+
+```typescript
+new CutSetting(init?: {
+  type?: string                // "Cut", "Scan", "Image", etc.
+  index?: number               // Layer index
+  name?: string                // Layer name
+  priority?: number            // Execution priority
+  minPower?: number           // Minimum power (0-100%)
+  maxPower?: number           // Maximum power (0-100%)
+  minPower2?: number          // Secondary laser minimum power
+  maxPower2?: number          // Secondary laser maximum power
+  speed?: number              // Speed in mm/s
+  kerf?: number               // Kerf offset in mm
+  zOffset?: number            // Z-axis offset
+  enablePowerRamp?: boolean   // Enable power ramping
+  rampLength?: number         // Ramp length in mm
+  numPasses?: number          // Number of passes
+  zPerPass?: number           // Z increment per pass
+  perforate?: boolean         // Perforate mode
+  dotMode?: boolean           // Dot mode
+  scanOpt?: string            // Scan optimization
+  interval?: number           // Scan line interval
+  angle?: number              // Scan angle
+  overScanning?: number       // Over-scanning distance
+  lineAngle?: number          // Line angle for fill
+})
+```
+
+#### Example
+
+```typescript
+const cutSetting = new CutSetting({
+  index: 0,
+  name: "Acrylic Engrave",
+  priority: 1,
+  type: "Cut",
+  speed: 150,
+  maxPower: 50,
+  minPower: 40,
+  numPasses: 3,
+  enablePowerRamp: true,
+  rampLength: 2,
+})
+```
+
+---
+
+### ShapePath
+
+Custom paths with vertices and primitives (lines and bezier curves).
+
+#### Constructor
+
+```typescript
+new ShapePath(init?: {
+  verts?: Vert[]       // Array of vertices
+  prims?: Prim[]       // Array of primitives (drawing commands)
+  isClosed?: boolean   // Whether the path is closed
+  cutIndex?: number    // Cut setting index to use
+  locked?: boolean     // Lock the shape
+  xform?: Mat          // Transformation matrix [a, b, c, d, tx, ty]
+})
+
+interface Vert {
+  x: number
+  y: number
+  c?: number           // Control point flag
+  c0x?: number         // Control point 0 x
+  c0y?: number         // Control point 0 y
+  c1x?: number         // Control point 1 x
+  c1y?: number         // Control point 1 y
+}
+
+interface Prim {
+  type: number         // 0 = LineTo, 1 = BezierTo
+}
+
+type Mat = [a: number, b: number, c: number, d: number, tx: number, ty: number]
+```
+
+#### Example: Simple Square
+
+```typescript
+const square = new ShapePath({
+  cutIndex: 0,
+  verts: [
+    { x: -25, y: -25 },
+    { x: 25, y: -25 },
+    { x: 25, y: 25 },
+    { x: -25, y: 25 },
+  ],
+  prims: [
+    { type: 0 }, // LineTo
+    { type: 0 }, // LineTo
+    { type: 0 }, // LineTo
+    { type: 0 }, // LineTo (close path)
+  ],
+  isClosed: true,
+})
+```
+
+#### Example: Curved Path with Bezier Curves
+
+```typescript
+const curved = new ShapePath({
+  cutIndex: 0,
+  verts: [
+    { x: 0, y: -30 },
+    { x: 30, y: 0, c: 1, c0x: 30, c0y: -16.5, c1x: 30, c1y: -16.5 },
+    { x: 0, y: 30, c: 1, c0x: 30, c0y: 16.5, c1x: 30, c1y: 16.5 },
+    { x: -30, y: 0, c: 1, c0x: -30, c0y: 16.5, c1x: -30, c1y: 16.5 },
+    { x: 0, y: -30, c: 1, c0x: -30, c0y: -16.5, c1x: -30, c1y: -16.5 },
+  ],
+  prims: [
+    { type: 1 }, // BezierTo
+    { type: 1 }, // BezierTo
+    { type: 1 }, // BezierTo
+    { type: 1 }, // BezierTo
+  ],
+  isClosed: true,
+})
+```
+
+---
+
+### ShapeRect
+
+Rectangle shape (currently read-only from parsed files).
+
+#### Constructor
+
+```typescript
+new ShapeRect()
+```
+
+#### Properties
+
+- `w`: Width
+- `h`: Height
+- `cr`: Corner radius
+- `cutIndex`: Cut setting index
+- `locked`: Lock state
+- `xform`: Transformation matrix
+
+---
+
+### ShapeEllipse
+
+Ellipse/circle shape (currently read-only from parsed files).
+
+#### Constructor
+
+```typescript
+new ShapeEllipse()
+```
+
+#### Properties
+
+- `rx`: X radius
+- `ry`: Y radius
+- `cutIndex`: Cut setting index
+- `locked`: Lock state
+- `xform`: Transformation matrix
+
+---
+
+### ShapeText
+
+Text shape (currently read-only from parsed files).
+
+#### Constructor
+
+```typescript
+new ShapeText()
+```
+
+#### Properties
+
+- `text`: Text content
+- `font`: Font name
+- `backupPath`: Backup path representation
+- `cutIndex`: Cut setting index
+- `locked`: Lock state
+- `xform`: Transformation matrix
+
+---
+
+### ShapeBitmap
+
+Bitmap/image shape (currently read-only from parsed files).
+
+#### Constructor
+
+```typescript
+new ShapeBitmap()
+```
+
+#### Properties
+
+- `w`: Width
+- `h`: Height
+- `dataBase64`: Base64-encoded image data
+- `grayscale`: Grayscale mode
+- `dpi`: DPI setting
+- `ditherMode`: Dither mode
+- `halftone`: Halftone mode
+- `negative`: Negative mode
+- `brightnessAdjust`: Brightness adjustment
+- `contrastAdjust`: Contrast adjustment
+- `gammaAdjust`: Gamma adjustment
+- `cutIndex`: Cut setting index
+- `locked`: Lock state
+- `xform`: Transformation matrix
+
+---
+
+### ShapeGroup
+
+Container for grouping shapes together (currently read-only from parsed files).
+
+#### Constructor
+
+```typescript
+new ShapeGroup()
+```
+
+#### Properties
+
+- `children`: Array of child shapes
+- `cutIndex`: Cut setting index
+- `locked`: Lock state
+- `xform`: Transformation matrix
+
+#### Methods
+
+- `getChildren()`: Returns the children array
+
+---
+
+### Notes
+
+Project notes that can be displayed when loading the project.
+
+#### Constructor
+
+```typescript
+new Notes()
+```
+
+#### Properties
+
+- `showOnLoad`: Whether to show notes on load
+- `text`: Note text content
+
+---
+
+### VariableText
+
+Variable text settings for dynamic text generation.
+
+#### Constructor
+
+```typescript
+new VariableText()
+```
+
+#### Properties
+
+- `start`: Start value
+- `end`: End value
+- `current`: Current value
+- `increment`: Increment value
+- `autoAdvance`: Auto-advance setting
+
+---
+
+## Generating SVG
+
+You can generate SVG representations of your projects:
+
+```typescript
+import { generateLightBurnSvg } from "lbrnts"
+
+const svg = generateLightBurnSvg(project)
+```

package/dist/index.d.ts

@@ -0,0 +1,329 @@
+/**
+ * Type representing the JSON structure returned by xml2js
+ */
+type XmlJson = {
+    [key: string]: XmlJsonValue;
+};
+type XmlJsonValue = string | number | boolean | null | XmlJsonElement | XmlJsonValue[];
+type XmlJsonElement = {
+    $?: Record<string, string | number | boolean>;
+    _?: string;
+    [key: string]: XmlJsonValue | Record<string, string | number | boolean> | string | undefined;
+};
+
+declare class LightBurnBaseElement {
+    token: string;
+    static token: string;
+    getChildren(): LightBurnBaseElement[];
+    getStringIndented(): string;
+    getString(): string;
+    get [Symbol.toStringTag](): string;
+    private static elementRegistry;
+    private static shapeRegistry;
+    /**
+     * Should be called after class definition to register the class for parsing
+     */
+    static register(token: string, klass: any): void;
+    /**
+     * Parse an XML string into registered LightBurnBaseElement instances
+     */
+    static parse(xml: string): LightBurnBaseElement | LightBurnBaseElement[];
+    static fromXmlJson(node: XmlJsonElement): LightBurnBaseElement;
+    static parseXmlJson(xmlJson: XmlJsonValue): any;
+    static instantiateElement(tag: string, node: XmlJsonElement): LightBurnBaseElement;
+}
+
+interface LightBurnProjectInit {
+    appVersion?: string;
+    formatVersion?: string;
+    materialHeight?: number;
+    mirrorX?: boolean;
+    mirrorY?: boolean;
+    children?: LightBurnBaseElement[];
+}
+declare class LightBurnProject extends LightBurnBaseElement {
+    appVersion?: string;
+    formatVersion?: string;
+    materialHeight?: number;
+    mirrorX?: boolean;
+    mirrorY?: boolean;
+    children: LightBurnBaseElement[];
+    constructor(init?: LightBurnProjectInit);
+    static fromXmlJson(node: XmlJsonElement): LightBurnProject;
+    getChildren(): LightBurnBaseElement[];
+}
+
+interface CutSettingInit {
+    type?: string;
+    index?: number;
+    name?: string;
+    priority?: number;
+    minPower?: number;
+    maxPower?: number;
+    minPower2?: number;
+    maxPower2?: number;
+    speed?: number;
+    kerf?: number;
+    zOffset?: number;
+    enablePowerRamp?: boolean;
+    rampLength?: number;
+    numPasses?: number;
+    zPerPass?: number;
+    perforate?: boolean;
+    dotMode?: boolean;
+    scanOpt?: string;
+    interval?: number;
+    angle?: number;
+    overScanning?: number;
+    lineAngle?: number;
+}
+declare class CutSetting extends LightBurnBaseElement {
+    private _type;
+    private _index?;
+    private _name?;
+    private _priority?;
+    private _minPower?;
+    private _maxPower?;
+    private _minPower2?;
+    private _maxPower2?;
+    private _speed?;
+    private _kerf?;
+    private _zOffset?;
+    private _enablePowerRamp?;
+    private _rampLength?;
+    private _numPasses?;
+    private _zPerPass?;
+    private _perforate?;
+    private _dotMode?;
+    private _scanOpt?;
+    private _interval?;
+    private _angle?;
+    private _overScanning?;
+    private _lineAngle?;
+    constructor(init?: CutSettingInit);
+    get type(): string;
+    set type(value: string);
+    get index(): number | undefined;
+    set index(value: number | undefined);
+    get name(): string | undefined;
+    set name(value: string | undefined);
+    get priority(): number | undefined;
+    set priority(value: number | undefined);
+    get minPower(): number | undefined;
+    set minPower(value: number | undefined);
+    get maxPower(): number | undefined;
+    set maxPower(value: number | undefined);
+    get minPower2(): number | undefined;
+    set minPower2(value: number | undefined);
+    get maxPower2(): number | undefined;
+    set maxPower2(value: number | undefined);
+    get speed(): number | undefined;
+    set speed(value: number | undefined);
+    get kerf(): number | undefined;
+    set kerf(value: number | undefined);
+    get zOffset(): number | undefined;
+    set zOffset(value: number | undefined);
+    get enablePowerRamp(): boolean | undefined;
+    set enablePowerRamp(value: boolean | undefined);
+    get rampLength(): number | undefined;
+    set rampLength(value: number | undefined);
+    get numPasses(): number | undefined;
+    set numPasses(value: number | undefined);
+    get zPerPass(): number | undefined;
+    set zPerPass(value: number | undefined);
+    get perforate(): boolean | undefined;
+    set perforate(value: boolean | undefined);
+    get dotMode(): boolean | undefined;
+    set dotMode(value: boolean | undefined);
+    get scanOpt(): string | undefined;
+    set scanOpt(value: string | undefined);
+    get interval(): number | undefined;
+    set interval(value: number | undefined);
+    get angle(): number | undefined;
+    set angle(value: number | undefined);
+    get overScanning(): number | undefined;
+    set overScanning(value: number | undefined);
+    get lineAngle(): number | undefined;
+    set lineAngle(value: number | undefined);
+    static fromXmlJson(node: XmlJsonElement): CutSetting;
+}
+
+declare class Notes extends LightBurnBaseElement {
+    showOnLoad?: boolean;
+    text?: string;
+    constructor();
+    static fromXmlJson(node: XmlJsonElement): Notes;
+}
+
+declare class VariableText extends LightBurnBaseElement {
+    start?: number;
+    end?: number;
+    current?: number;
+    increment?: number;
+    autoAdvance?: boolean;
+    constructor();
+    static fromXmlJson(node: XmlJsonElement): VariableText;
+}
+
+declare class UIPrefs extends LightBurnBaseElement {
+    prefs: Record<string, string>;
+    constructor();
+    static fromXmlJson(node: XmlJsonElement): UIPrefs;
+}
+
+declare class Thumbnail extends LightBurnBaseElement {
+    pngBase64?: string;
+    constructor();
+    static fromXmlJson(node: XmlJsonElement): Thumbnail;
+}
+
+type Mat = [
+    a: number,
+    b: number,
+    c: number,
+    d: number,
+    tx: number,
+    ty: number
+];
+declare abstract class ShapeBase extends LightBurnBaseElement {
+    cutIndex?: number;
+    locked?: boolean;
+    xform?: Mat;
+    static readCommon(node: XmlJsonElement): {
+        cutIndex?: number;
+        locked?: boolean;
+        xform?: Mat;
+    };
+}
+
+declare class ShapeEllipse extends ShapeBase {
+    rx?: number;
+    ry?: number;
+    constructor();
+    static fromXmlJson(node: XmlJsonElement): ShapeEllipse;
+}
+
+declare class ShapeRect extends ShapeBase {
+    w?: number;
+    h?: number;
+    cr?: number;
+    constructor();
+    static fromXmlJson(node: XmlJsonElement): ShapeRect;
+}
+
+interface Vert {
+    x: number;
+    y: number;
+    c?: number;
+    c0x?: number;
+    c0y?: number;
+    c1x?: number;
+    c1y?: number;
+}
+interface Prim {
+    type: number;
+}
+interface ShapePathInit {
+    verts?: Vert[];
+    prims?: Prim[];
+    isClosed?: boolean;
+    cutIndex?: number;
+    locked?: boolean;
+    xform?: Mat;
+}
+declare class ShapePath extends ShapeBase {
+    verts: Vert[];
+    prims: Prim[];
+    isClosed: boolean;
+    private static templateRegistry;
+    constructor(init?: ShapePathInit);
+    static clearTemplateRegistry(): void;
+    static fromXmlJson(node: XmlJsonElement): ShapePath;
+    /**
+     * Parse encoded VertList string format
+     * Format: V{x} {y}c{flag}x{flag}c{flag}x{c1x}c{flag}y{c1y}...
+     * Example: V2.1156745 -12.3306c0x1c1x1.5871694c1y-12.3306
+     *
+     * Control points are encoded as:
+     * - c0x{value}c0y{value} = control point 0 (when both present)
+     * - c1x{value}c1y{value} = control point 1 (when both present)
+     * - c{num}x{num} alone (like c0x1) = flag, not a coordinate
+     */
+    static parseEncodedVertList(encoded: string): Vert[];
+    /**
+     * Parse encoded PrimPolyline string format
+     * This typically contains line-to commands, each prim is type 0 (LineTo)
+     */
+    static parseEncodedPrimPolyline(encoded: string): Prim[];
+    /**
+     * Generate primitives from vertices based on PrimID
+     * PrimID meanings:
+     * - 0: Simple polyline (all LineTo)
+     * - 2: Rounded rectangle with bezier curves at corners
+     * - 3: Other curve type
+     */
+    static generatePrimsFromVerts(verts: Vert[], primID?: number): Prim[];
+}
+
+declare class ShapeText extends ShapeBase {
+    text?: string;
+    font?: string;
+    backupPath?: ShapePath;
+    constructor();
+    static fromXmlJson(node: XmlJsonElement): ShapeText;
+}
+
+declare class ShapeGroup extends ShapeBase {
+    children: LightBurnBaseElement[];
+    constructor();
+    static fromXmlJson(node: XmlJsonElement): ShapeGroup;
+    getChildren(): LightBurnBaseElement[];
+}
+
+declare class ShapeBitmap extends ShapeBase {
+    private _w?;
+    private _h?;
+    private _dataBase64?;
+    private _grayscale?;
+    private _dpi?;
+    private _ditherMode?;
+    private _halftone?;
+    private _negative?;
+    private _brightnessAdjust?;
+    private _contrastAdjust?;
+    private _gammaAdjust?;
+    constructor();
+    get w(): number | undefined;
+    set w(value: number | undefined);
+    get h(): number | undefined;
+    set h(value: number | undefined);
+    get dataBase64(): string | undefined;
+    set dataBase64(value: string | undefined);
+    get grayscale(): boolean | undefined;
+    set grayscale(value: boolean | undefined);
+    get dpi(): number | undefined;
+    set dpi(value: number | undefined);
+    get ditherMode(): string | undefined;
+    set ditherMode(value: string | undefined);
+    get halftone(): boolean | undefined;
+    set halftone(value: boolean | undefined);
+    get negative(): boolean | undefined;
+    set negative(value: boolean | undefined);
+    get brightnessAdjust(): number | undefined;
+    set brightnessAdjust(value: number | undefined);
+    get contrastAdjust(): number | undefined;
+    set contrastAdjust(value: number | undefined);
+    get gammaAdjust(): number | undefined;
+    set gammaAdjust(value: number | undefined);
+    static fromXmlJson(node: XmlJsonElement): ShapeBitmap;
+}
+
+interface GenerateSvgOptions {
+    margin?: number;
+}
+
+declare function generateLightBurnSvg(root: LightBurnBaseElement | LightBurnBaseElement[], options?: GenerateSvgOptions): string;
+
+declare const parseXml: (xml: string) => XmlJson;
+
+export { LightBurnBaseElement as BaseLightBurnElement, CutSetting, type CutSettingInit, type GenerateSvgOptions, LightBurnBaseElement, LightBurnProject, type LightBurnProjectInit, type Mat, Notes, type Prim, ShapeBase, ShapeBitmap, ShapeEllipse, ShapeGroup, ShapePath, type ShapePathInit, ShapeRect, ShapeText, Thumbnail, UIPrefs, VariableText, type Vert, generateLightBurnSvg, parseXml };