ofs-dxf-ts 1.0.0

package/API.md

@@ -0,0 +1,411 @@
+# คู่มือการใช้งาน (API Reference)
+
+`ofs-dxf-ts` — ไลบรารี TypeScript บริสุทธิ์ (pure, API-agnostic, browser-first) สำหรับสร้างไฟล์ DXF จาก coordinate / label / options ทั่วไป โดยจะวาดบน DXF template หรือสร้างจากศูนย์ก็ได้ ทำงานได้ทั้ง **Node.js** และ **Browser/Angular**
+
+> เอกสารนี้อิงตาม public API ที่ export จากแพ็กเกจ (`import { ... } from 'ofs-dxf-ts'`) — type declaration ทั้งหมดมากับแพ็กเกจแล้ว
+
+---
+
+## 1. เริ่มต้นใช้งาน (Quick Start)
+
+```typescript
+import { DxfBuilder } from 'ofs-dxf-ts';
+// หรือระหว่างพัฒนาในโปรเจกต์นี้: import { DxfBuilder } from './src';
+```
+
+### สร้างจากศูนย์ (ไม่มี template)
+
+```typescript
+const builder = new DxfBuilder();
+
+builder.addPolyline([[0, 0], [100, 50], [200, 0]], 'CANAL', 1);
+builder.addCircle(50, 50, 25, 'CANAL', 3);
+builder.addText('KM 0+500', 10, 10, 2.5, 0, 'TEXT', 7);
+
+const dxf = builder.saveString();
+```
+
+ไฟล์ที่ได้เป็น DXF R2018 (AC1032) หน่วยเมตร โครงสร้างครบ (CLASSES, BLOCK_RECORD, OBJECTS, layouts) เพราะสร้างบนเอกสารเปล่าที่ฝังใน lib — จึงใช้ block, image และ layout ได้เหมือนโหมด template
+
+### สร้างบน DXF template
+
+| Environment | วิธีโหลด template |
+|-------------|------------------|
+| **Node.js** | `new DxfBuilder('/path/to/template.dxf')` |
+| **Browser/Angular** | `DxfBuilder.fromString(dxfText)` — โหลดผ่าน `HttpClient` แล้วส่ง text เข้ามา |
+
+```typescript
+// Node.js
+const builder = new DxfBuilder('./template2018.dxf');
+
+// Browser/Angular (เช่นใน service)
+const dxfText = await firstValueFrom(http.get('assets/template2018.dxf', { responseType: 'text' }));
+const builder = DxfBuilder.fromString(dxfText);
+```
+
+ทุก section ของ template ถูกคงไว้ตามลำดับเดิม ส่วนที่เพิ่มใหม่ (layer, linetype, style, block, image, layout) จะถูกแทรกเข้าไป — ถ้าชื่อซ้ำกับของเดิมใน template จะใช้ของเดิม (ยกเว้น block / layout ที่ซ้ำจะ `throw`)
+
+> ⚠️ ต้องเป็น template DXF R2000 ขึ้นไป (มี BLOCK_RECORD table และ OBJECTS section) จึงจะใช้ block definition, image และ layout ได้ ไฟล์แบบ R12 ยังเพิ่ม layer / entity ได้ตามปกติ
+
+### บันทึก / ส่งออก
+
+```typescript
+builder.saveString();          // → string         (ทุก environment)
+builder.saveas('out.dxf');     // เขียนไฟล์         (Node.js เท่านั้น)
+builder.downloadAs('out.dxf'); // trigger download (Browser เท่านั้น)
+```
+
+`saveString()` เรียกซ้ำได้และให้ผลเหมือนเดิมทุกครั้ง
+
+> ℹ️ `saveas()` / `DxfDocument.readFile()` ใช้ `fs` ของ Node ผ่าน `process.getBuiltinModule` จึงต้องใช้ **Node.js ≥ 20.16** ถ้ารันบน runtime อื่น (browser, worker, Node เก่ากว่านั้น) ให้ใช้ `saveString()` แล้วเขียนไฟล์เอง — แพ็กเกจนี้เป็น ESM อย่างเดียว
+
+---
+
+## 2. `DxfBuilder` — API หลัก
+
+ทุก method ที่รับ `layer` จะสร้าง layer อัตโนมัติถ้ายังไม่มี (สี 7, `CONTINUOUS`)
+
+### การสร้าง / เข้าถึงภายใน
+
+| Member | คำอธิบาย |
+|--------|----------|
+| `new DxfBuilder(template?: string \| DxfDocument)` | สร้างใหม่, โหลดจากไฟล์ (Node) หรือห่อ `DxfDocument` ที่มีอยู่ |
+| `static DxfBuilder.fromString(content)` | โหลด template จาก DXF string |
+| `get doc: DxfDocument` | เข้าถึง document |
+| `get msp: Modelspace` | ปลายทางการวาด **ปัจจุบัน** (model space, layout ใน `onLayout`, หรือ block ใน `defineBlock`) สำหรับเรียก API สไตล์ ezdxf เช่น `builder.msp.add_text(...)` |
+
+### Geometry
+
+```typescript
+addLine(start, end, layer?='0', color?, linetype?)
+addPolyline(points, layer?='0', color?, linetype?, closed?=false)   // LWPOLYLINE; รับ [x,y] หรือ [x,y,z]
+addCircle(cx, cy, radius, layer?='0', color?)
+addArc(cx, cy, radius, startAngleDeg, endAngleDeg, layer?='0', color?)
+addEllipse(cx, cy, majorAxisX, majorAxisY, ratio, layer?='0', color?)  // ratio = minor/major (0..1)
+addPoint(x, y, layer?='0', color?)
+addSpline(controlPoints, degree?=3, layer?='0', color?)
+```
+
+### Text
+
+```typescript
+addText(text, x, y, height?=2, rotationDeg?=0, layer?='TEXT', color?=7)
+addMText(text, x, y, width?=100, height?=2.5, layer?='TEXT', color?)   // "\n" = ขึ้นบรรทัดใหม่
+```
+
+ต้องการ text style หรือการจัดตำแหน่ง (alignment) ให้ใช้ `builder.msp.add_text(text, { height, style, rotation, layer }).set_placement([x, y], TextEntityAlignment.BOTTOM_CENTER)`
+
+### Resources: linetype / text style / layer
+
+```typescript
+addLayer(name, color?=7, linetype?='CONTINUOUS')
+addLineType(name, description, pattern)   // pattern หน่วยเดียวกับแบบ: + เส้น, − ช่องว่าง, 0 จุด
+addTextStyle(name, font, height?)          // เช่น addTextStyle('THAI', 'THSarabunNew.ttf')
+```
+
+```typescript
+builder.addLineType('BOUNDARY', '____ . ____', [40, -10, 0, -10]);
+builder.addLayer('ขอบเขตพื้นที่รับประโยชน์', 6, 'BOUNDARY');
+```
+
+### Block
+
+```typescript
+defineBlock(name, draw: (b: DxfBuilder) => void, basePoint?=[0,0])
+addBlock(name, x, y, scale, rotationDeg, layer?='0', attributes?={})
+```
+
+- `defineBlock` — ทุกคำสั่งใน callback วาดลง block definition (พิกัดเทียบ `basePoint`) วาด entity บน layer `'0'` สีไม่ระบุ เพื่อให้ INSERT รับสี/layer ของตัวที่วาง
+- `addBlock` — ลำดับการ resolve: **block ใน template หรือที่ `defineBlock` ไว้** → INSERT, **block ใน `BLOCK_REGISTRY`** → วาดแยกเป็นเส้น, ไม่พบ → ข้อความ `[Block:name]`
+- `attributes` ถูกวาดเป็นข้อความธรรมดาข้าง block (ยังไม่รองรับ ATTRIB)
+
+```typescript
+builder.defineBlock('BM', b => {
+    b.addPolyline([[-1, -1], [1, -1], [1, 1], [-1, 1]], '0', undefined, undefined, true);
+    b.addHatch('SOLID', [[[0, 0], [1, 0], [1, 1], [0, 1]]], '0');
+});
+builder.addBlock('BM', 519395.838, 1034018.584, 20, 0, 'SYMBOL');
+```
+
+### Hatch
+
+```typescript
+addHatch(patternName, boundaries, layer?='0', color?, opts?)
+//   patternName: 'SOLID' | ชื่อลายใน HATCH_PATTERNS | ชื่อใดก็ได้ถ้าส่ง opts.patternLines
+//   boundaries : [x,y][][] — รูปที่อยู่ในรูปอื่นกลายเป็นรู (odd parity)
+//   opts       : { scale?, angle?, patternLines? }
+```
+
+- ลายในตัวเป็นหน่วย ISO (มม.) — `scale` คูณเข้ากับลาย เช่นแบบเป็นเมตรที่พิมพ์ 1:12,500 ลาย `DOTS` ใช้ `scale ≈ 8`
+- ลายในตัว: `ANGLE, ANSI31–ANSI38, AR-CONC, AR-SAND, BOX, BRICK, CROSS, DASH, DOTS, EARTH, GRASS, GRATE, GRAVEL, HEX, HONEY, INSUL, LINE, NET, NET3, PLAST, SQUARE, STARS, SWAMP, TRIANG, ZIGZAG`
+- ชื่อที่ไม่รู้จักโดยไม่มี `patternLines` จะ `throw`
+
+```typescript
+builder.addHatch('SOLID', [[[0,0],[100,0],[100,100],[0,100]]], 'WATER', 5);
+builder.addHatch('ANSI31', [outer, hole], 'AREA', 7, { scale: 10, angle: 45 });
+
+// ลายกำหนดเอง: [angleDeg, [baseX, baseY], [offsetX, offsetY], dashes]
+builder.addHatch('MY_DOTS', [outline], 'AREA', 3, { patternLines: [[0, [0, 0], [2, 2], [0, -2]]] });
+```
+
+### Raster image
+
+```typescript
+addImage(imagePath, pixelSize, insertion, worldSize, layer?='0', opts?: ImageOptions)
+//   pixelSize : [กว้าง, สูง] หน่วย pixel (DXF อ่านไฟล์ภาพเองไม่ได้)
+//   insertion : มุมล่างซ้ายของภาพ (หน่วยแบบ)
+//   worldSize : [กว้าง, สูง] หน่วยแบบ
+//   opts      : { rotation?, clip?: [x,y][], brightness?, contrast?, fade? }
+```
+
+DXF เก็บเพียง **การอ้างอิงไฟล์** — วางไฟล์ภาพไว้ข้าง `.dxf` (ใช้ชื่อไฟล์) หรือใช้ absolute path; ถ้าหาไฟล์ไม่เจอ CAD จะแสดงเพียงกรอบ `clip` ใช้พิกัดโลก
+
+```typescript
+builder.addImage('topo_4927II.jpg', [7087, 7087], [513000, 1027000], [15000, 15000], 'RASTER', { fade: 40 });
+```
+
+### Annotation: callout และตาราง
+
+```typescript
+addCallout(anchor, text: string | string[], boxAt, opts?: CalloutOptions): [minX, minY, maxX, maxY]
+```
+
+วาดกรอบข้อความ (มุมบนซ้ายที่ `boxAt`) และเส้นชี้จาก `anchor` ไปยังจุดกึ่งกลางขอบกล่องที่ใกล้ที่สุด คืนค่าขอบเขตกล่อง
+
+| `CalloutOptions` | ค่าปริยาย | คำอธิบาย |
+|---|---|---|
+| `layer`, `color`, `textColor`, `boxColor`, `style` | `'TEXT'` | |
+| `textHeight` | `2.5` | ความสูงตัวอักษร (หน่วยแบบ) |
+| `lineSpacing` | `1.6` | ระยะบรรทัด × ความสูงตัวอักษร |
+| `padding` | `0.8 × textHeight` | |
+| `boxWidth` | ประมาณจากข้อความ | กำหนดความกว้างเอง |
+| `widthFactor` | `0.75` | ความกว้างเฉลี่ยตัวอักษร / ความสูง (ฟอนต์ไทย ≈ 0.6–0.7) |
+| `align` | `'left'` | `'left' \| 'center'` |
+| `arrow`, `arrowSize` | `'none'` | `'none' \| 'dot' \| 'arrow'` |
+
+```typescript
+addTable(position, columnWidths, rowHeight, rows, layer?='0', textHeight?=2.5, opts?)
+//   rows : TableCellDef[][] — { text, colSpan?, rowSpan?, alignment?, color?, style? }
+//   opts : { headerColor?, gridColor?, textColor?, rowHeights? }
+```
+
+การรวมเซลล์ใช้กติกาแบบ HTML table: เซลล์ที่ span จะกินตำแหน่งทางขวา/ด้านล่าง และเซลล์ถัดไปจะข้ามตำแหน่งที่ถูกกินไปแล้ว ตารางถูกวาดเป็น LINE + TEXT (ไม่ใช่ ACAD_TABLE)
+
+```typescript
+builder.addTable([650, 300], [14, 26, 42, 42, 22], 7, [
+    [{ text: 'ลำดับ', rowSpan: 2 }, { text: 'หมุด', rowSpan: 2 }, { text: 'พิกัด', colSpan: 2 }, { text: 'ค่าระดับ', rowSpan: 2 }],
+    [{ text: 'North' }, { text: 'East' }],
+    [{ text: '1' }, { text: 'BM.07' }, { text: '1,034,018.584' }, { text: '519,395.838' }, { text: '4.622' }],
+], 'TABLE', 3);
+```
+
+อื่น ๆ:
+
+```typescript
+addDimension(point1, point2, dimLinePosition, layer?='DIM', color?, text?)
+addLeader(vertices, layer?='0', color?, hasArrowhead?=true)
+addMLeader(vertices, text, textPosition, layer?, color?, opts?)   // ⚠️ deprecated → วาดด้วย addCallout
+addLineFromObject(onfarmLine, layer?='structure')                // วาด OnfarmLine (ดูหัวข้อ 4)
+```
+
+### Paper space layout
+
+```typescript
+addLayout(name, paperWidth, paperHeight, margins?=[10,10,10,10], viewports?: LayoutViewportDef[])
+onLayout(name, draw: (b: DxfBuilder) => void)
+```
+
+- หน่วยกระดาษเป็น **มม.** จุดกำเนิดพิกัดอยู่ที่มุมล่างซ้ายของพื้นที่พิมพ์ (ขอบใน margin) ตามแบบ AutoCAD — ใช้ `margins: [0,0,0,0]` ถ้าต้องการให้ตรงกับมุมกระดาษ
+- `onLayout` — ทุกคำสั่งใน callback วาดลง paper space ใช้ได้ทั้ง layout ของ template (`'Layout1'`) และที่สร้างด้วย `addLayout`; ชื่อ `'Model'` = model space; ชื่อที่ไม่มีจะ `throw`
+
+| `LayoutViewportDef` | คำอธิบาย |
+|---|---|
+| `center`, `width`, `height` | ตำแหน่ง/ขนาดบนกระดาษ (มม.) |
+| `viewCenter` | จุดกึ่งกลางที่มองใน model space |
+| `viewHeight?` | ความสูงที่มองเห็นใน model space — ถ้าไม่ระบุคำนวณจาก `scale` |
+| `scale?` | ตัวหารมาตราส่วน เช่น `12500` = 1:12,500 → `viewHeight = height × scale × unitFactor` |
+| `unitFactor?` | หน่วย model ต่อ 1 มม. กระดาษที่ 1:1 — ค่าปริยาย `0.001` (model เป็นเมตร) |
+| `frozenLayers?` | layer ที่ซ่อนเฉพาะ viewport นี้ |
+| `locked?` | ล็อก viewport ไม่ให้ zoom/pan เปลี่ยนมาตราส่วน |
+
+```typescript
+builder.addLayout('BM-A1', 841, 594, [0, 0, 0, 0], [
+    { center: [330, 330], width: 600, height: 440, viewCenter: [519000, 1033500], scale: 12500, locked: true },
+]);
+builder.onLayout('BM-A1', s => s.addText('แผนที่แสดงตำแหน่งหมุดหลักฐาน', 250, 70, 9, 0, 'SHEET'));
+```
+
+### View / Zoom
+
+```typescript
+zoomExtents(padding?=0)              // auto-fit entity ใน model space ($EXTMIN/$EXTMAX/$VIEWCTR/$VIEWSIZE)
+zoomWindow(minX, minY, maxX, maxY)
+setExtents(minX, minY, maxX, maxY)
+setViewCenter(x, y, viewHeight?)
+```
+
+### Layer control
+
+```typescript
+setLayerColor(name, color)
+setLayerLinetype(name, linetype)
+freezeLayer(name) / thawLayer(name)      // ซ่อน + ไม่ plot + เลือกไม่ได้
+lockLayer(name)   / unlockLayer(name)    // เห็นแต่แก้ไม่ได้
+setLayerOff(name) / setLayerOn(name)     // ซ่อนแต่ยังเลือกได้
+```
+
+> ⚠️ คำสั่งเหล่านี้มีผลกับ layer ที่สร้างใหม่เท่านั้น — layer ที่มีอยู่แล้วใน template ถูกเขียนออกตามเดิม
+
+### GeoReference
+
+```typescript
+builder.setGeoReference({
+    crsId: 'EPSG:32647',               // UTM Zone 47N
+    designPoint: [0, 0],
+    referencePoint: [600000, 1700000],
+    northDirection: 0,
+    scaleFactor: 1,
+    coordinateType: 2,
+});
+```
+
+> ⚠️ ปัจจุบันเขียน `$INSUNITS`, `$UCSORG` (= `referencePoint`) และ `$ANGBASE` ลง HEADER — `$UCSORG` อาจทำให้ CAD แสดงพิกัดสัมพัทธ์กับจุดนั้น ถ้าแบบวาดด้วยพิกัด UTM จริงอยู่แล้วไม่จำเป็นต้องเรียก
+
+---
+
+## 3. `DxfDocument` และ `Modelspace` (ระดับล่าง)
+
+```typescript
+DxfDocument.create()                  // เอกสารเปล่า R2018
+DxfDocument.fromString(dxfText)       // จาก template string
+DxfDocument.readFile(path)            // Node.js
+
+doc.modelspace(): Modelspace
+doc.paperspace(layoutName): Modelspace          // collector ของ layout
+doc.addLayer / addLineType / addTextStyle
+doc.addBlockDefinition(name, entities: DxfEntity[], basePoint?)
+doc.addLayout(layoutDef)
+doc.layoutNames / hasLayout(name) / hasBlock(name) / getBlockNames()
+doc.setHeaderVar(name, [{ code, value }])       // แทนค่าเดิมใน HEADER
+doc.toDxfString() / saveas(path) / downloadAs(filename)
+```
+
+`Modelspace` เป็นตัวเก็บ entity แบบ ezdxf (`add_line`, `add_lwpolyline`, `add_text(...).set_placement(...)`, `add_hatch`, `add_image`, `add_table`, `add_viewport`, `add_blockref` …) ใช้ทั้งกับ model space, layout และ block
+
+```typescript
+const doc = DxfDocument.create();
+doc.modelspace().add_text('ศูนย์กลาง', { height: 3, style: 'THAI', layer: 'NOTE' })
+    .set_placement([50, 50], TextEntityAlignment.MIDDLE_CENTER);
+```
+
+---
+
+## 4. ตัวสร้างสัญลักษณ์ (Symbol generators)
+
+ฟังก์ชันบริสุทธิ์ — **คืนค่า geometry ไม่วาดเอง**
+
+### อาคารคลอง → `Record<string, OnfarmLine>`
+
+```typescript
+objCheck(xyCord, kmUS)
+objCheckDrop(xyCord, kmUS)
+objChangeSlopeStructure(xyCord, kmUS)
+objFlume(xyCord, kmUS, kmDS, centerline)
+objSiphon(xyCord, kmUS, kmDS, centerline)
+objCulvert(xyCord, kmUS, kmDS, roadLength)
+objCheckCulvert(xyCord, kmUS, kmDS, roadLength)
+objCheckDropCulvert(xyCord, kmUS, kmDS, roadLength)
+```
+
+```typescript
+const struc = objCheck([[0, 0], [1000, 0]], 500);
+for (const key in struc) builder.addLineFromObject(struc[key]);
+```
+
+### สัญลักษณ์ลาด/สันคันนา → segments
+
+```typescript
+slopeSymbolSegments(line, interval, side, halfLen, size): [Coordinate, Coordinate][]
+```
+
+```typescript
+const segs = slopeSymbolSegments(ridgeLine, 20, 'L', 2, 4);
+for (const [start, end] of segs) builder.addLine(start, end, 'SLOPE_SYMBOL', 8);
+```
+
+---
+
+## 5. ยูทิลิตี้ (Geometry / Text)
+
+```typescript
+// math.utils
+formatDistance(distance)                    // 1500 → 'KM 1+500'
+calculateDistance(p1, p2)
+calculateAzimuth(x1, y1, x2, y2)            // วัดจากแกน Y ตามเข็ม 0..360
+rotatePoint(x, y, angleDeg, shiftX, shiftY)
+rotatePointAzimuth(x, y, azimuthDeg, shiftX, shiftY)
+isPointInBounds(x, y, xmin, ymin, xmax, ymax)
+snapBound(value, step, direction?='down')
+
+// polyline.utils
+kmPointPolyline(points, targetDistance)     // → { point, az }
+dividePolylineWithDistance(coords, segmentLength=100)  // → { points, distances, angles }
+
+// offset.utils (ระนาบ หน่วยเดียวกับแบบ — UTM เมตร)
+getLineOffset(points, offsetDistance=1, opts?)   // → { left, right } เส้นขนานสองข้าง z=0 (เช่นขอบคลอง)
+offsetPolyline(points, distance, opts?)          // ข้างเดียว: distance บวก = ซ้ายของทิศทางเส้น, ลบ = ขวา
+//   opts: { closed?, miterLimit?=4 }
+//   มุมต่อกันที่จุดตัด (miter); มุมแหลมที่จุดตัดไกลเกิน miterLimit × distance จะถูกตัดมุม (bevel)
+//   จุดซ้ำติดกันถูกข้าม; เส้นที่จุดแรก = จุดสุดท้ายถือเป็นวงปิด
+
+// text.utils (DXF ไม่มีข้อมูลฟอนต์ — เป็นค่าประมาณ)
+visibleCharCount(text)                      // ไม่นับสระ/วรรณยุกต์ไทยที่อยู่บน/ล่าง
+estimateTextWidth(text, height, widthFactor?=0.75)
+```
+
+---
+
+## 6. ชนิดข้อมูล (Types)
+
+```typescript
+type Coordinate   = [number, number];
+type Coordinate3D = [number, number, number];
+
+interface OnfarmLine { coordinate: Coordinate3D[]; type: string; width: number; color: number }
+
+type HatchPatternLine = [angleDeg, [baseX, baseY], [offsetX, offsetY], dashes[]];
+const HATCH_PATTERNS: Record<string, HatchPatternLine[]>;
+```
+
+ยัง export: `CalloutOptions`, `ImageOptions`, ชนิดจาก `core/dxf-entities` (`DxfEntity`, `TableCellDef`, `LayoutDef`, `LayoutViewportDef`, `GeoReferenceDef`, `TextEntityAlignment` …), template handling (`readTemplate`, `serializeDocument`, `listLayoutNames`, `BLOCK_REGISTRY`) และ parser (หัวข้อ 7) — `serializeWithTemplate` ยังมีอยู่แต่ deprecated
+
+---
+
+## 7. DXF Parser ในตัว
+
+TypeScript port ของ `dxf-parser` (MIT) ทำงานได้ทั้ง Node และ Browser และ **fail-fast บนไฟล์ผิดรูปแทนการค้าง**
+
+```typescript
+import { DxfParser, ParsedDxf } from 'ofs-dxf-ts';
+
+const parsed: ParsedDxf | null = new DxfParser().parseSync(dxfText);
+parsed?.entities;   // ParsedDxfEntity[]
+parsed?.blocks;     // Record<string, ParsedDxfBlock>
+parsed?.tables;     // layer / lineType / style / dimstyle / viewPort
+parsed?.header;     // $ACADVER, $EXTMIN, ...
+```
+
+- ใช้ `parseSync(source: string)` เท่านั้น — ฝั่ง browser อ่านไฟล์อัปโหลดด้วย `await file.text()` ก่อน
+- ชนิดฝั่ง parser export ในชื่อ `ParsedDxfEntity` / `ParsedDxfPoint` / `ParsedDxfBlock`
+- ไฟล์ที่ parse ไม่ได้จะ `throw` — ครอบ `try/catch` เมื่อรับไฟล์จากผู้ใช้
+
+---
+
+## 8. การเปลี่ยนแปลงที่มีผลกับโค้ดเดิม
+
+- **ไฟล์ที่สร้างจากศูนย์** เป็น DXF R2018 โครงสร้างครบ (เดิมเป็นไฟล์ย่อที่ไม่มี CLASSES/OBJECTS)
+- **`addMLeader`** deprecated — วาดเป็น callout แทน MULTILEADER (ของเดิมไม่ถูกต้องสำหรับ AutoCAD)
+- **`addHatch`** ที่ใช้ชื่อลายที่ไม่รู้จักจะ `throw` (เดิมเขียนไฟล์ที่ลายว่าง)
+- **`addLayout`** สร้าง layout จริงแล้ว (เดิมไม่ถูกเขียนลงไฟล์); `LayoutViewportDef.viewHeight` เป็น optional เมื่อระบุ `scale`
+- **Modelspace `add_image`** ตีความ `clipBoundary` เป็นพิกัดโลก
+- **ตาราง** เซลล์ที่ข้อความว่างจะไม่สร้าง TEXT entity

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+รูปแบบตาม [Keep a Changelog](https://keepachangelog.com/) และใช้ [Semantic Versioning](https://semver.org/)
+
+## [1.0.0] — 2026-09-21
+
+เวอร์ชันแรกที่เผยแพร่บน npm ในชื่อ **`ofs-dxf-ts`** (ESM อย่างเดียว, ไม่มี runtime dependency)
+
+### Added
+
+- `DxfBuilder` / `DxfDocument` / `Modelspace` — สร้าง DXF R2018 จากศูนย์ หรือวาดบน DXF template โดยคงทุก section ของ template ไว้ และแจก handle ต่อจาก `$HANDSEED`
+- Entity: Line, Polyline (2D/3D), Circle, Arc, Ellipse, Spline, Text, MText, Hatch, Dimension, Leader, Image, Viewport, Solid, Mesh, Insert
+- `defineBlock()` / `addBlock()` — block definition และการวางซ้ำ
+- Hatch: `SOLID` + ลาย ISO ในตัว 32 ลาย หรือกำหนด `patternLines` เอง รองรับรูใน
+- Raster image พร้อม IMAGEDEF/REACTOR/`ACAD_IMAGE_DICT` และ clip ด้วยพิกัดโลก
+- Paper space layout: `addLayout()` พร้อม viewport ตามมาตราส่วน, freeze layer เฉพาะ viewport, ล็อก viewport และ `onLayout()` สำหรับวาดลง layout (ของใหม่หรือของ template)
+- `addCallout()` (กล่องข้อความพร้อมเส้นชี้) และ `addTable()` ที่รวมเซลล์ได้ (`colSpan` / `rowSpan`)
+- `addLineType()` / `addTextStyle()` / `addLayer()`
+- DXF parser ในตัว (TypeScript port ของ `dxf-parser`, ไม่มี dependency ภายนอก)
+- เรขาคณิตบริสุทธิ์: `getLineOffset()` / `offsetPolyline()` (miter + bevel, รองรับเส้นปิด), azimuth, การแบ่ง polyline, ประมาณความกว้างข้อความ
+- สัญลักษณ์งานชลประทานแบบพารามิเตอร์ (culvert, flume, siphon, check ฯลฯ)
+
+### Notes
+
+- ต้องใช้ **Node.js ≥ 20.16** สำหรับ `saveas()` / `readFile()` (เข้าถึง `fs` ผ่าน `process.getBuiltinModule`) — runtime อื่นใช้ `saveString()` ได้
+- ตรวจไฟล์ผลลัพธ์ด้วย ezdxf (strict read + audit) ได้ 0 errors / 0 fixes — ยังไม่ได้ทดสอบเปิดใน AutoCAD จริง

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 On-Farm Solution Co.,Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# ofs-dxf-ts
+
+ไลบรารี TypeScript สำหรับสร้างไฟล์ DXF (Drawing Exchange Format) สำหรับงาน GIS และวิศวกรรม พัฒนาต่อยอดจากแนวคิดของ `ezdxf` (Python) ทำงานได้ทั้งบน **Node.js** และ **Browser (Angular/React)**
+
+ไลบรารี **บริสุทธิ์และไม่ผูกกับ API ใด ๆ** — รับเฉพาะ coordinate, label และ options ทั่วไป แล้ววาดลงบน DXF template หรือสร้างไฟล์จากศูนย์ ผู้เรียกเป็นผู้เตรียมข้อมูลของตัวเองให้อยู่ในรูป coordinate/options ก่อน
+
+## 🌟 คุณสมบัติ
+
+- **Template-aware**: วาดลงบนไฟล์ DXF ต้นแบบจาก AutoCAD/Civil 3D โดยคงทุก section เดิมไว้ (Layers, Blocks, Styles, Layouts, CLASSES, OBJECTS …) และแจก handle ใหม่ต่อจาก `$HANDSEED` ของ template จึงไม่ชนกับของเดิม
+- **สร้างจากศูนย์ได้ไฟล์ครบโครงสร้าง**: ใช้เอกสาร DXF R2018 เปล่าที่ฝังในตัว lib เป็นฐาน ทั้งสองโหมดจึงได้โครงสร้างแบบเดียวกัน
+- **Block definition**: สร้างสัญลักษณ์เองด้วย `defineBlock()` แล้ววางซ้ำด้วย `addBlock()` (INSERT)
+- **Hatch**: เติมทึบ (`SOLID`) และลาย ISO ในตัว 32 ลาย (ANSI31, DOTS, GRASS, EARTH, AR-SAND …) หรือกำหนดลายเอง รองรับรูใน (hole)
+- **Raster image**: อ้างอิงไฟล์ภาพเป็นพื้นหลัง (เช่นแผนที่ภูมิประเทศ) พร้อม clip ด้วยพิกัดโลก
+- **Paper space layout**: สร้าง layout พร้อม viewport ตามมาตราส่วน (เช่น 1:12,500) ซ่อน layer เฉพาะ viewport ล็อก viewport และวาดลง paper space ได้ทั้ง layout ใหม่และของ template
+- **Annotation**: กล่องข้อความพร้อมเส้นชี้ (`addCallout`) และตารางที่รวมเซลล์ได้ (`colSpan` / `rowSpan`)
+- **Linetype / Text style**: เพิ่ม linetype และ text style (เช่นฟอนต์ไทย TrueType) ได้ทั้งสองโหมด
+- **Entities**: Line, Polyline, Circle, Arc, Ellipse, Spline, Text, MText, Hatch, Dimension, Leader, Image, Viewport, Solid, Mesh ฯลฯ
+- **Layer & view**: Freeze / Lock / On-Off, Zoom Extents / Zoom Window
+- **Zero runtime dependencies**: parser DXF (TypeScript port ของ `dxf-parser`, fail-fast บนไฟล์ผิดรูปแทนการค้าง) และเรขาคณิต (เช่น offset เส้นขอบคลอง) เขียนเองทั้งหมด คำนวณบนระนาบในหน่วยของแบบ (UTM เมตร)
+- **Universal**: Node.js อ่าน/เขียนไฟล์ผ่าน `fs`; Browser/Angular โหลด template จาก string และดาวน์โหลดผลลัพธ์ได้โดยไม่ต้องใช้ `fs`
+
+## 🚀 การติดตั้ง
+
+```bash
+npm install ofs-dxf-ts
+```
+
+**ความต้องการ**
+
+| | |
+|---|---|
+| รูปแบบโมดูล | **ESM เท่านั้น** (ไม่มี CommonJS build) พร้อม type declaration ในตัว |
+| Node.js | ≥ 20.16 — `saveas()` / `readFile()` เข้าถึง `fs` ผ่าน `process.getBuiltinModule` เวอร์ชันเก่ากว่านี้ยังใช้ `saveString()` ได้ปกติ |
+| Browser / Angular | bundler ใดก็ได้ ไม่มีการ import `fs`/`path` แบบ static จึงไม่ต้องตั้ง polyfill |
+
+## 💡 ตัวอย่างการใช้งาน
+
+### 1. วาดบน Template (แนะนำ)
+
+```typescript
+import { DxfBuilder } from 'ofs-dxf-ts';
+
+// Node.js — โหลดไฟล์ผ่าน constructor
+const builder = new DxfBuilder('./template2018.dxf');
+// Browser/Angular — DxfBuilder.fromString(dxfText)
+
+builder.addPolyline([[518600, 1033350], [519000, 1033380]], 'CANAL', 1);
+
+builder.saveas('output.dxf');          // Node.js
+// builder.downloadAs('output.dxf');   // Browser
+// const dxf = builder.saveString();   // string (ทุก environment)
+```
+
+### 2. สัญลักษณ์ กล่องข้อความ และตาราง
+
+```typescript
+// linetype / text style / layer
+builder.addTextStyle('THAI', 'THSarabunNew.ttf');
+builder.addLineType('BOUNDARY', '____ . ____', [40, -10, 0, -10]);   // หน่วยเดียวกับแบบ (เมตร)
+builder.addLayer('ขอบเขต', 6, 'BOUNDARY');
+
+// สัญลักษณ์หมุด BM: วาดในพิกัดของ block แล้ววางด้วย addBlock
+builder.defineBlock('BM', b => {
+    b.addPolyline([[-1, -1], [1, -1], [1, 1], [-1, 1]], '0', undefined, undefined, true);
+    b.addHatch('SOLID', [[[0, 0], [1, 0], [1, 1], [0, 1]]], '0');
+});
+builder.addBlock('BM', 519395.838, 1034018.584, 20, 0, 'SYMBOL');
+
+// กล่องข้อความพร้อมเส้นชี้ (มุมบนซ้ายของกล่องอยู่ที่ boxAt)
+builder.addCallout(
+    [519480, 1034100],                                   // จุดที่ชี้
+    ['ก่อสร้างอาคารทางน้ำเข้า', 'ขนาด 2-1.75x1.75 ม.'],
+    [519700, 1035050],                                   // มุมบนซ้ายของกล่อง
+    { layer: 'NOTE', textHeight: 25, style: 'THAI', arrow: 'dot' },
+);
+
+// ตารางที่รวมเซลล์
+builder.addTable([650, 300], [14, 26, 42, 42], 7, [
+    [{ 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', 3);
+```
+
+### 3. Hatch และภาพพื้นหลัง
+
+```typescript
+// ลายจุด (scale คูณกับหน่วยลาย ISO ที่เป็น mm) และลายเส้นเฉียงหมุน 45°
+builder.addHatch('DOTS', [pondOutline], 'POND', 8, { scale: 8 });
+builder.addHatch('ANSI31', [outer, hole], 'AREA', 7, { scale: 10, angle: 45 });
+
+// ภาพพื้นหลัง: DXF เก็บเพียงการอ้างอิงไฟล์ — วางไฟล์ภาพไว้ข้าง .dxf
+builder.addImage('topo_background.jpg', [3000, 2000], [516000, 1031500], [6000, 4000], 'RASTER', { fade: 40 });
+```
+
+### 4. Layout สำหรับพิมพ์ (Paper Space)
+
+```typescript
+// A1 (มม.) — viewport แสดง model space ที่ 1:12,500 (model เป็นเมตร)
+builder.addLayout('BM-A1', 841, 594, [0, 0, 0, 0], [
+    { center: [330, 330], width: 600, height: 440, viewCenter: [519000, 1033500], scale: 12500, locked: true },
+    { center: [110, 480], width: 150, height: 100, viewCenter: [519000, 1033500], scale: 100000,
+      frozenLayers: ['NOTE', 'GRID'] },                  // key map
+]);
+
+// ทุกคำสั่งภายใน callback วาดลง paper space ของ layout นั้น (ใช้กับ 'Layout1' ของ template ได้ด้วย)
+builder.onLayout('BM-A1', s => {
+    s.addText('แผนที่แสดงตำแหน่งหมุดหลักฐาน', 250, 70, 9, 0, 'SHEET');
+    s.addBlock('NORTH', 800, 530, 2, 0, 'SHEET');
+});
+```
+
+> 🅰️ **Angular**: โหลด template ผ่าน `HttpClient` แบบ `responseType: 'text'` แล้วใช้ `DxfBuilder.fromString()` และดาวน์โหลดด้วย `downloadAs()` — ไม่มีการใช้ `fs`
+
+---
+
+- 📖 **API ทั้งหมด**: [API.md](./API.md) (แนบมากับแพ็กเกจ)
+- 📝 **ประวัติเวอร์ชัน**: [CHANGELOG.md](./CHANGELOG.md)
+- 📄 สัญญาอนุญาต: MIT