ofs-dxf-ts 1.0.0

package/dist/core/dxf-builder.d.ts

@@ -0,0 +1,348 @@
+/**
+ * DxfBuilder — Backward-compatible wrapper around DxfDocument.
+ *
+ * ✅ Works in both Node.js AND Browser/Angular environments.
+ *
+ * Usage (existing — unchanged):
+ *   const builder = new DxfBuilder();
+ *   builder.addPolyline(points, 'MyLayer', 3);
+ *   builder.addText('Hello', 100, 200, 5, 0, 'TEXT', 7);
+ *   const dxfString = builder.saveString();
+ *
+ * NEW: Template-based (Node.js):
+ *   const builder = new DxfBuilder('./template/template2018.dxf');
+ *
+ * NEW: Template-based (Browser/Angular):
+ *   const builder = DxfBuilder.fromString(templateDxfString);
+ *
+ * NEW: Convenience API:
+ *   builder.addLayer('MyLayer', 3, 'DASHED');
+ *   builder.addLine([0,0], [100,100], 'MyLayer', 1);
+ *   builder.addArc(50, 50, 25, 0, 180, 'MyLayer', 4);
+ *   builder.addHatch('SOLID', [[[0,0],[100,0],[100,100],[0,100]]], 'MyLayer', 3);
+ *
+ * NEW: Sheet composition:
+ *   builder.defineBlock('BM', b => { b.addCircle(0, 0, 1.5, '0'); b.addLine([-2, 0], [2, 0], '0'); });
+ *   builder.addBlock('BM', 519395.8, 1034018.6, 10, 0, 'SYMBOL');
+ *   builder.addCallout([519300, 1034000], ['ก่อสร้างอาคารทางน้ำเข้า', 'ขนาด 2-1.75x1.75 ม.'], [519350, 1034150]);
+ *   builder.addLayout('A1', 841, 594, [0, 0, 0, 0], [{ center: [420, 297], width: 800, height: 560,
+ *       viewCenter: [519500, 1033500], scale: 12500 }]);
+ *   builder.onLayout('A1', b => b.addText('แผนที่แสดงตำแหน่งหมุดหลักฐาน', 420, 20, 8));
+ */
+import { DxfDocument } from './dxf-document.js';
+import { Modelspace } from './modelspace.js';
+import { Coordinate, Coordinate3D, OnfarmLine } from '../types/index.js';
+import { TableCellDef, GeoReferenceDef, LayoutViewportDef } from './dxf-entities.js';
+import { HatchPatternLine } from './hatch-patterns.js';
+/** Options for `DxfBuilder.addImage`. */
+export interface ImageOptions {
+    /** Rotation around the insertion point, degrees counter-clockwise. */
+    rotation?: number;
+    /** Clip polygon in drawing coordinates. */
+    clip?: [number, number][];
+    brightness?: number;
+    contrast?: number;
+    fade?: number;
+}
+/** Options for `DxfBuilder.addCallout`. */
+export interface CalloutOptions {
+    layer?: string;
+    /** Color of leader, box and text (unless overridden below). */
+    color?: number;
+    textColor?: number;
+    boxColor?: number;
+    style?: string;
+    /** Text height in drawing units (default 2.5). */
+    textHeight?: number;
+    /** Baseline-to-baseline distance as a multiple of text height (default 1.6). */
+    lineSpacing?: number;
+    /** Space between box and text (default 0.8 × text height). */
+    padding?: number;
+    /** Fixed box width; estimated from the text when omitted. */
+    boxWidth?: number;
+    /** Average glyph width / text height used for the estimate (default 0.75). */
+    widthFactor?: number;
+    align?: 'left' | 'center';
+    /** Marker at the anchor end of the leader (default 'none'). */
+    arrow?: 'none' | 'dot' | 'arrow';
+    arrowSize?: number;
+}
+export declare class DxfBuilder {
+    private _document;
+    /** Current drawing target: model space, a layout, or a block being defined. */
+    private _msp;
+    /**
+     * Create a new DxfBuilder.
+     * @param template Optional path to a DXF template file (Node.js only), or a loaded DxfDocument.
+     */
+    constructor(template?: string | DxfDocument);
+    /**
+     * Create a DxfBuilder from a DXF template string.
+     * ✅ Works in Browser/Angular.
+     */
+    static fromString(content: string): DxfBuilder;
+    /** Access the underlying DxfDocument. */
+    get doc(): DxfDocument;
+    /** Access the current drawing target directly for ezdxf-style operations. */
+    get msp(): Modelspace;
+    /**
+     * Add or update a layer.
+     * @param name  Layer name
+     * @param color ACI color index (0-256)
+     * @param linetype Linetype name (e.g. 'CONTINUOUS', 'DASHED', 'CENTER')
+     */
+    addLayer(name: string, color?: number, linetype?: string): void;
+    /**
+     * Add a linetype. Pattern values are in drawing units: positive = dash,
+     * negative = gap, 0 = dot. Existing names in the template are kept.
+     * @example builder.addLineType('BOUNDARY', '____ . ____', [20, -5, 0, -5]);
+     */
+    addLineType(name: string, description: string, pattern: number[]): void;
+    /**
+     * Add a text style. Existing names in the template are kept.
+     * @example builder.addTextStyle('THAI', 'THSarabunNew.ttf');
+     */
+    addTextStyle(name: string, font: string, height?: number): void;
+    /**
+     * Add a single LINE entity (two-point segment).
+     */
+    addLine(start: [number, number], end: [number, number], layer?: string, color?: number, linetype?: string): void;
+    /**
+     * Add a LWPOLYLINE entity (multi-vertex polyline).
+     */
+    addPolyline(points: Coordinate[] | Coordinate3D[], layer?: string, color?: number, linetype?: string, closed?: boolean): void;
+    /**
+     * Add a CIRCLE entity.
+     */
+    addCircle(cx: number, cy: number, radius: number, layer?: string, color?: number): void;
+    /**
+     * Add an ARC entity.
+     * @param cx Center X
+     * @param cy Center Y
+     * @param radius Radius
+     * @param startAngle Start angle in degrees
+     * @param endAngle End angle in degrees
+     */
+    addArc(cx: number, cy: number, radius: number, startAngle: number, endAngle: number, layer?: string, color?: number): void;
+    /**
+     * Add an ELLIPSE entity.
+     * @param cx Center X
+     * @param cy Center Y
+     * @param majorAxisX Major axis endpoint X (relative to center)
+     * @param majorAxisY Major axis endpoint Y (relative to center)
+     * @param ratio Ratio of minor to major axis (0..1)
+     */
+    addEllipse(cx: number, cy: number, majorAxisX: number, majorAxisY: number, ratio: number, layer?: string, color?: number): void;
+    /**
+     * Add a POINT entity.
+     */
+    addPoint(x: number, y: number, layer?: string, color?: number): void;
+    /**
+     * Add a TEXT entity.
+     */
+    addText(text: string, x: number, y: number, height?: number, rotation?: number, layer?: string, color?: number): void;
+    /**
+     * Add an MTEXT entity (multi-line text with word wrap).
+     */
+    addMText(text: string, x: number, y: number, width?: number, height?: number, layer?: string, color?: number): void;
+    /**
+     * Add a HATCH entity (solid fill or pattern fill).
+     *
+     * @param patternName  'SOLID', a built-in pattern (see HATCH_PATTERNS, ISO/mm based),
+     *                     or any name together with `opts.patternLines`.
+     * @param boundaries   Array of boundary polygons, each as an array of [x,y] points.
+     *                     Polygons inside another polygon become holes.
+     * @param layer        Layer name
+     * @param color        ACI color
+     * @param opts         scale (pattern units × scale = drawing units), angle (degrees), patternLines
+     *
+     * @example
+     *   // Solid fill
+     *   builder.addHatch('SOLID', [[[0,0],[100,0],[100,100],[0,100]]], 'MyLayer', 3);
+     *
+     *   // Pattern fill
+     *   builder.addHatch('ANSI31', [[[0,0],[50,0],[50,50],[0,50]]], 'MyLayer', 7, { scale: 2, angle: 45 });
+     */
+    addHatch(patternName: string, boundaries: [number, number][][], layer?: string, color?: number, opts?: {
+        scale?: number;
+        angle?: number;
+        patternLines?: HatchPatternLine[];
+    }): void;
+    /**
+     * Add a raster IMAGE, e.g. a scanned topographic map as a background.
+     *
+     * DXF only references the image file: keep the file next to the .dxf and
+     * pass its file name, or pass an absolute path.
+     *
+     * @param imagePath  file name/path as the CAD application should resolve it
+     * @param pixelSize  image size in pixels [width, height] (DXF cannot read the file)
+     * @param insertion  lower-left corner in drawing units
+     * @param worldSize  image size in drawing units [width, height]
+     *
+     * @example
+     *   // 1:50,000 sheet scanned at 7087×7087 px covering 15 km
+     *   builder.addImage('topo_4927II.jpg', [7087, 7087], [513000, 1027000], [15000, 15000], 'RASTER');
+     */
+    addImage(imagePath: string, pixelSize: [number, number], insertion: [number, number], worldSize: [number, number], layer?: string, opts?: ImageOptions): void;
+    /**
+     * Add a DIMENSION entity (linear dimension between two points).
+     */
+    addDimension(point1: [number, number], point2: [number, number], dimLinePosition: [number, number], layer?: string, color?: number, text?: string): void;
+    /**
+     * Add a LEADER entity (arrow with annotation line).
+     */
+    addLeader(vertices: [number, number][], layer?: string, color?: number, hasArrowhead?: boolean): void;
+    /**
+     * Add a SPLINE entity (smooth curve through control points).
+     */
+    addSpline(controlPoints: [number, number][], degree?: number, layer?: string, color?: number): void;
+    /** Add a line from an OnfarmLine structure object. */
+    addLineFromObject(onfarmLine: OnfarmLine, layer?: string): void;
+    /**
+     * Define a reusable block (symbol). Draw it with the normal builder API in
+     * block-local coordinates around `basePoint`, then place it with addBlock().
+     *
+     * @example
+     *   builder.defineBlock('SCHOOL', b => {
+     *       b.addPolyline([[-2, -1.5], [2, -1.5], [2, 1.5], [-2, 1.5]], '0', 5, undefined, true);
+     *       b.addHatch('SOLID', [[[-2, -1.5], [2, -1.5], [2, 1.5], [-2, 1.5]]], '0', 5);
+     *   });
+     *   builder.addBlock('SCHOOL', 518807, 1033917, 20, 0, 'POI');
+     */
+    defineBlock(name: string, draw: (builder: DxfBuilder) => void, basePoint?: [number, number]): void;
+    /**
+     * Add a block reference (INSERT).
+     * Template or defined block → INSERT entity. Registry block → manual drawing. Neither → placeholder.
+     */
+    addBlock(name: string, x: number, y: number, scale: number, rotation: number, layer?: string, attributes?: Record<string, string>): void;
+    /**
+     * Auto-zoom to fit all entities with optional padding.
+     * Sets $EXTMIN, $EXTMAX, $VIEWCTR, $VIEWSIZE in HEADER.
+     * @example builder.zoomExtents(100);  // 100 unit padding
+     */
+    zoomExtents(padding?: number): void;
+    /**
+     * Zoom to a specific window (rectangle).
+     * @example builder.zoomWindow(1000, 2000, 5000, 6000);
+     */
+    zoomWindow(minX: number, minY: number, maxX: number, maxY: number): void;
+    /**
+     * Set the drawing extents manually.
+     */
+    setExtents(minX: number, minY: number, maxX: number, maxY: number): void;
+    /**
+     * Set initial view center and zoom level.
+     */
+    setViewCenter(x: number, y: number, viewHeight?: number): void;
+    /** Freeze a layer (hidden, not plotted, not selectable). */
+    freezeLayer(name: string): void;
+    /** Thaw a layer (undo freeze). */
+    thawLayer(name: string): void;
+    /** Lock a layer (visible but not editable). */
+    lockLayer(name: string): void;
+    /** Unlock a layer. */
+    unlockLayer(name: string): void;
+    /** Turn a layer off (hidden but still selectable). */
+    setLayerOff(name: string): void;
+    /** Turn a layer on. */
+    setLayerOn(name: string): void;
+    /** Change layer color. */
+    setLayerColor(name: string, color: number): void;
+    /** Change layer linetype. */
+    setLayerLinetype(name: string, linetype: string): void;
+    /**
+     * Add a callout: a leader from `anchor` to a boxed, multi-line label.
+     * The leader attaches to the box edge midpoint nearest the anchor.
+     *
+     *   anchor ●──────────┤ ก่อสร้างอาคารทางน้ำเข้า │
+     *                     │ ขนาด 2-1.75x1.75 ม.   │
+     *
+     * @param anchor  the point being annotated
+     * @param text    lines of text (array, or a string with "\n")
+     * @param boxAt   top-left corner of the box
+     * @returns the box extent [minX, minY, maxX, maxY]
+     */
+    addCallout(anchor: [number, number], text: string | string[], boxAt: [number, number], opts?: CalloutOptions): [number, number, number, number];
+    /**
+     * Add an annotation with a leader.
+     *
+     * @deprecated MULTILEADER entities written by this library were not
+     * AutoCAD-compatible. This now draws `addCallout(vertices[0], text, textPosition)`
+     * with an arrowhead; use addCallout directly.
+     */
+    addMLeader(vertices: [number, number][], text: string, textPosition: [number, number], layer?: string, color?: number, opts?: {
+        textHeight?: number;
+        textWidth?: number;
+        arrowSize?: number;
+        doglegLength?: number;
+    }): void;
+    /**
+     * Add a TABLE (drawn as grid of LINE + TEXT entities).
+     * Cells may span columns/rows with `colSpan` / `rowSpan` (HTML table rules).
+     *
+     * @example
+     *   builder.addTable([100, 500], [20, 40, 50, 50], 8, [
+     *       [{ text: 'ลำดับ', rowSpan: 2 }, { text: 'หมุด', rowSpan: 2 }, { text: 'พิกัด', colSpan: 2 }],
+     *       [{ text: 'North' }, { text: 'East' }],
+     *       [{ text: '1' }, { text: 'BM.07' }, { text: '1,034,018.584' }, { text: '519,395.838' }],
+     *   ], 'TABLE', 2.5);
+     */
+    addTable(position: [number, number], columnWidths: number[], rowHeight: number, rows: TableCellDef[][], layer?: string, textHeight?: number, opts?: {
+        headerColor?: number;
+        gridColor?: number;
+        textColor?: number;
+        rowHeights?: number[];
+    }): void;
+    /**
+     * Add a Paper Space layout for plotting. Paper units are mm; the origin
+     * is the lower-left corner of the printable area (inside the margins).
+     * A viewport's model-space extent comes from `viewHeight`, or from `scale`
+     * (e.g. 12500 for 1:12,500 with the model in meters).
+     *
+     * @example
+     *   builder.addLayout('A1', 841, 594, [0, 0, 0, 0], [{
+     *       center: [420, 297], width: 800, height: 560,
+     *       viewCenter: [519500, 1033500], scale: 12500,
+     *       frozenLayers: ['GRID'],
+     *   }]);
+     */
+    addLayout(name: string, paperWidth: number, paperHeight: number, margins?: [number, number, number, number], viewports?: LayoutViewportDef[]): void;
+    /**
+     * Draw into a paper space layout: every builder call made inside `draw`
+     * targets that layout. Works with layouts from the template (e.g.
+     * 'Layout1') and ones added with addLayout().
+     *
+     * @example
+     *   builder.onLayout('A1', b => {
+     *       b.addText('แผนที่แสดงตำแหน่งหมุดหลักฐาน', 300, 25, 8);
+     *       b.addTable([560, 200], [15, 30, 45, 45], 7, rows, 'TABLE', 2.5);
+     *   });
+     */
+    onLayout(name: string, draw: (builder: DxfBuilder) => void): void;
+    /**
+     * Set geographic coordinate reference for the drawing.
+     * Embeds CRS info into the DXF HEADER for GIS interoperability.
+     *
+     * @example
+     *   // UTM Zone 47N (Thailand)
+     *   builder.setGeoReference({
+     *       crsId: 'EPSG:32647',
+     *       designPoint: [0, 0],
+     *       referencePoint: [600000, 1700000],
+     *       northDirection: 0,
+     *       scaleFactor: 1,
+     *       coordinateType: 2,
+     *   });
+     */
+    setGeoReference(geoRef: GeoReferenceDef): void;
+    /** Serialize to DXF string. ✅ Works everywhere. */
+    saveString(): string;
+    /** Save to file (Node.js only). */
+    saveas(filePath: string): void;
+    /** Download DXF in browser (Angular). */
+    downloadAs(filename: string): void;
+    private _withTarget;
+    private _ensureLayer;
+    private _initializeLayers;
+    private _drawFromRegistry;
+}