บทที่ 1 บทนำ

ETABS API คืออะไร

ETABS API เป็น COM-based interface ที่ CSi (Computers & Structures, Inc.) เปิดให้โปรแกรมภายนอก สั่งงาน ETABS ได้โดยตรง — โดยไม่ต้องเปิด GUI คลิกทีละปุ่ม

ในทางปฏิบัติ เราเขียนโปรแกรม Python ที่ “คุยกับ” ETABS ผ่าน Component Object Model (COM) ซึ่งเป็นเทคโนโลยีของ Windows สำหรับให้ process ต่างกันสื่อสารกันได้

COM Interop ทำงานอย่างไร

%%{init: {
  "theme": "base",
  "flowchart": {
    "curve": "basis",
    "htmlLabels": true,
    "nodeSpacing": 46,
    "rankSpacing": 58,
    "padding": 16
  }
}}%%
flowchart LR
    subgraph Python["Python Application (3.9+)"]
        A1["สั่ง Analyze"]
        A2["อ่าน Results"]
        A3["Export data"]
    end
    subgraph ETABS["ETABS Engine (x64)"]
        B1["คำนวณโครงสร้าง"]
        B2["จัดการ model"]
        B3["render 3D/2D"]
    end
    Python <-->|"COM Interop<br/>comtypes"| ETABS

ขั้นตอนหลัก:

1. โปรแกรม Python เรียก GetActiveObject() หรือ CreateObject() เพื่อเชื่อม ETABS
2. ได้ object etabs (root) → แล้วเข้าถึง SapModel (ตัวโมเดล)
3. ใช้ SapModel อ่าน/เขียนข้อมูล, สั่ง Analyze, อ่าน Results
4. เสร็จแล้ว del COM objects + gc.collect() เพื่อป้องกัน memory leak

Sequence Diagram: การทำงานทีละ Step

sequenceDiagram
    autonumber
    participant App as Python Script
    participant ETABS as ETABS Engine
    participant COM as COM Interop

    App->>COM: GetActiveObject("CSI.ETABS.API.ETABSObject")
    activate COM
    COM->>ETABS: ค้นหา running instance
    activate ETABS
    ETABS-->>COM: etabs reference
    deactivate ETABS
    COM-->>App: etabs object
    deactivate COM

    App->>ETABS: etabs.SapModel
    activate ETABS
    ETABS-->>App: SapModel reference
    deactivate ETABS

    App->>ETABS: FrameObj.GetNameList()
    activate ETABS
    ETABS-->>App: (ret, count, names)
    deactivate ETABS

    App->>ETABS: Analyze.RunAnalysis()
    activate ETABS
    ETABS-->>App: ret = 0 (success)
    deactivate ETABS

    App->>ETABS: Results.FrameForce("B1")
    activate ETABS
    ETABS-->>App: (ret, P, V2, M3...)
    deactivate ETABS

    note over App,ETABS: Cleanup สำคัญเพื่อป้องกัน memory leak
    App->>COM: del sap_model, del etabs

ทำไมใช้ Python?

หัวข้อ	C#	Python
Setup	ต้อง Visual Studio + .NET 4.8 + x64	pip install comtypes แค่นี้
Syntax	Verbose (ref, type declarations)	กระชับ ไม่ต้อง ref
Data Processing	ต้องเขียน CSV writer เอง	pandas → CSV/Excel ทันที
Visualization	ต้องเพิ่ม library	matplotlib พร้อมใช้
Interactive	ไม่มี	Jupyter Notebook ทดลอง API ได้ทันที
Learning Curve	สูง (สำหรับวิศวกร)	ต่ำ — วิศวกรหลายคนใช้ Python อยู่แล้ว

ใช้เมื่อไร

สถานการณ์	ทำด้วยมือ	ทำด้วย API
ดึง Frame Force ทุก member → Excel	เปิด ETABS → Display → Export ทีละตาราง	โค้ดรันครั้งเดียวได้ทุก member
เปลี่ยน section แล้ว re-analyze 10 รอบ	คลิกเปลี่ยน → Run → รอ → ซ้ำ 10 ครั้ง	Loop ใน Python เสร็จใน 2 นาที
สร้างรายงาน PDF อัตโนมัติ	Copy ผลจาก ETABS → Word → Format	สร้าง report จากข้อมูล API โดยตรง
ตรวจ drift ทุกชั้นทุก combo	ดูทีละ combo ทีละชั้น	อ่าน StoryDrift ทุก combo ในรอบเดียว

Use Cases จริงในงานวิศวกรรม

1. Auto Report — ดึงผล analysis ทั้งหมดแล้วสร้างรายงานอัตโนมัติ
2. Batch Processing — เปลี่ยน parameter แล้วรัน analysis หลายรอบ (parametric study)
3. Data Extraction — ดึงข้อมูลโมเดลและผลลัพธ์เข้า database หรือ dashboard
4. Design Verification — ตรวจสอบค่า drift, deflection, base shear ตาม code อัตโนมัติ
5. Model QC — ตรวจสอบว่าโมเดลมี element ครบ, support ถูกต้อง

Flow หลักของโปรแกรม

%%{init: {
  "theme": "base",
  "flowchart": {
    "curve": "basis",
    "htmlLabels": true,
    "nodeSpacing": 42,
    "rankSpacing": 56,
    "padding": 16
  }
}}%%
flowchart LR
    C["Connect<br/>GetActiveObject"] --> R["Read Model<br/>GetNameList<br/>GetCoord<br/>GetSection"]
    R --> A["Analyze<br/>RunAnalysis<br/>SetCaseForOutput<br/>DeselectAll"]
    A --> RS["Read Results<br/>FrameForce<br/>JointDispl<br/>StoryDrift"]
    RS --> CL["Cleanup<br/>del + gc.collect"]

กฎสำคัญ

ทุก API call จะ return int — ถ้าได้ 0 แปลว่าสำเร็จ ถ้าได้ค่าอื่น แปลว่าล้มเหลว ตรวจค่า return ทุกครั้งเพื่อจับ error ก่อนที่จะลุกลาม

สิ่งที่หนังสือเล่มนี้ครอบคลุม

• บทที่ 1-3: ทฤษฎีพื้นฐานและตั้งค่าโปรเจกต์
• บทที่ 4-7: ใช้งาน API จริง ตั้งแต่เชื่อมจนอ่าน results
• บทที่ 8-10: จัดการ memory, แก้ปัญหา, จัดโครงสร้างโค้ด
• บทที่ 11-12: ใช้งานจริงรายวัน และ reference