From be6203ddd38fa39298927e9f465b07b0091d1975 Mon Sep 17 00:00:00 2001
From: kosuke55 <kosuke.tnp@gmail.com>
Date: Tue, 11 Aug 2026 00:29:14 +0900
Subject: [PATCH] docs(sdk): add a headless usage quickstart to the README

The README documented only the extension (iframe) workflow, while the
factories and exporters also work from plain Node.js since the ESM fix
(#99) and the factory fixes (#100, #101). Add a copy-paste runnable
example that builds a lane + driving path + vehicle and exports
OpenDRIVE / OpenSCENARIO / Lanelet2, notes the 0.17.0 requirement, and
points scenario logic (triggers, speed profiles) to the editor.
---
 packages/drawtonomy-sdk/README.ja.md | 43 +++++++++++++++++++++++++++
 packages/drawtonomy-sdk/README.md    | 44 ++++++++++++++++++++++++++++
 2 files changed, 87 insertions(+)

diff --git a/packages/drawtonomy-sdk/README.ja.md b/packages/drawtonomy-sdk/README.ja.md
index 7c2cb7c..7b5b0ec 100644
--- a/packages/drawtonomy-sdk/README.ja.md
+++ b/packages/drawtonomy-sdk/README.ja.md
@@ -70,6 +70,49 @@ pnpm dev --port 3001
 https://drawtonomy.com?ext=http://localhost:3001/manifest.json
 ```
 
+## ヘッドレス利用 (Node.js)
+
+ファクトリと exporter は純関数なので、ブラウザもエディタも不要です。
+スクリプトでシーンを組み立てて ASAM 形式に出力できます
+(`@drawtonomy/sdk` 0.17.0 以降が必要):
+
+```js
+// generate.mjs — 実行: node generate.mjs
+import { createLaneWithBoundaries, createPathWithFootprints, createVehicle, createSnapshot, exporter } from '@drawtonomy/sdk'
+import { writeFileSync } from 'node:fs'
+
+// 500 px (= 30 m) の直線レーン。キャンバス単位は px、1 m = 16.67 px。
+const lane = createLaneWithBoundaries(
+  [{ x: 0, y: 0 }, { x: 500, y: 0 }],
+  [{ x: 0, y: 50 }, { x: 500, y: 50 }],
+)
+
+// レーンに沿った走行パス。エクスポート時に時刻付き軌跡になる (既定 10 m/s の等速)。
+const path = createPathWithFootprints(
+  [{ x: 0, y: 25 }, { x: 250, y: 25 }, { x: 500, y: 25 }],
+  { count: 5 },
+)
+
+const snapshot = createSnapshot([...lane, ...path, createVehicle(300, 120)])
+
+writeFileSync('scene.xodr', exporter.exportToOpenDrive(snapshot, {}))   // OpenDRIVE 1.8
+writeFileSync('scene.xosc', exporter.exportToOpenScenario(snapshot, {})) // OpenSCENARIO 1.3
+writeFileSync('scene.osm', exporter.exportToLanelet2(snapshot, {}))     // Lanelet2
+```
+
+`.xosc` には時刻付き polyline の `FollowTrajectoryAction` が入るので、
+上の `.xodr` と組み合わせれば esmini でそのまま再生できます。
+生成した OpenDRIVE の読み戻しも可能です:
+
+```js
+const parsed = exporter.parseOpenDriveXml(xodrText)
+const { lanes, linestrings, points } = exporter.odrToShapes(parsed)
+```
+
+この経路で出力される軌跡は等速です。トリガー・イベントロジック・速度
+プロファイルは [drawtonomy エディタ](https://drawtonomy.com) の
+シナリオモードで作成してください。
+
 ## API
 
 ### ExtensionClient
diff --git a/packages/drawtonomy-sdk/README.md b/packages/drawtonomy-sdk/README.md
index 019cd1a..a09b5bf 100644
--- a/packages/drawtonomy-sdk/README.md
+++ b/packages/drawtonomy-sdk/README.md
@@ -72,6 +72,50 @@ pnpm dev --port 3001
 http://localhost:3000/?ext=http://localhost:3001/manifest.json
 ```
 
+## Headless usage (Node.js)
+
+The factories and exporters are pure functions — no browser or editor
+required. Build scenes in a script and export them to ASAM formats
+(requires `@drawtonomy/sdk` 0.17.0 or later):
+
+```js
+// generate.mjs — run with: node generate.mjs
+import { createLaneWithBoundaries, createPathWithFootprints, createVehicle, createSnapshot, exporter } from '@drawtonomy/sdk'
+import { writeFileSync } from 'node:fs'
+
+// A 500 px (= 30 m) straight lane. Canvas units are pixels; 1 m = 16.67 px.
+const lane = createLaneWithBoundaries(
+  [{ x: 0, y: 0 }, { x: 500, y: 0 }],
+  [{ x: 0, y: 50 }, { x: 500, y: 50 }],
+)
+
+// A driving path along the lane. On export it becomes a timed
+// trajectory (constant speed, 10 m/s by default).
+const path = createPathWithFootprints(
+  [{ x: 0, y: 25 }, { x: 250, y: 25 }, { x: 500, y: 25 }],
+  { count: 5 },
+)
+
+const snapshot = createSnapshot([...lane, ...path, createVehicle(300, 120)])
+
+writeFileSync('scene.xodr', exporter.exportToOpenDrive(snapshot, {}))   // OpenDRIVE 1.8
+writeFileSync('scene.xosc', exporter.exportToOpenScenario(snapshot, {})) // OpenSCENARIO 1.3
+writeFileSync('scene.osm', exporter.exportToLanelet2(snapshot, {}))     // Lanelet2
+```
+
+The `.xosc` contains a `FollowTrajectoryAction` with a timed polyline,
+so esmini plays it back directly (pair it with the `.xodr` above).
+Generated OpenDRIVE can also be parsed back:
+
+```js
+const parsed = exporter.parseOpenDriveXml(xodrText)
+const { lanes, linestrings, points } = exporter.odrToShapes(parsed)
+```
+
+Trajectories exported this way run at a constant speed. For triggers,
+event logic, and speed profiles, author the scenario in the
+[drawtonomy editor](https://drawtonomy.com)'s scenario mode.
+
 ## API
 
 ### ExtensionClient