Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 7 additions & 14 deletions README.ja.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

- Input: GCPs plus a single CRS
- Output: `world_file_basic` and post-shear refinement
- Runtime: Node.js と browser。browser は**行ごとに実績が違う**ため 3 段に分けて書く(m3-t1)。**(1) バンドル可能性 = 検証済**: Teiresias の `pnpm run verify:demo-bundle`(`scripts/verify-demo-browser-bundle.mjs`)が demo build の出力チャンクを走査し、Node 固有指定子が残っていないことと Daedalus 由来コードが実在することを機械検証する(CI から継続的に走る)。**(2) 実ブラウザでの実行 = 観測済(「検証済」ではない)**: 2026-08-29 に Teiresias デモを実ブラウザで **1 回観測**した(m3-t1/AC-16)。1 回の観測は自動検査ではない ∴ 回帰を守らない。**(3) CI 上での継続的・自動のブラウザ実行と canvas ドラッグの自動操作 = 未検証**(Cycle 1 の既知欠落)。`Daedalus/src` は本件のために 1 バイトも変更していない(m0 凍結を解いていない)
- Runtime: Node.js とブラウザ。ブラウザでの対応は 3 段に分けて書きます。**(1) バンドルできること = 検証済み**: Teiresias の `pnpm run verify:demo-bundle`(`scripts/verify-demo-browser-bundle.mjs`)がデモのビルドの出力チャンクを走査し、Node 固有の指定子が残っていないことと Daedalus 由来のコードが実在することを機械で検証します(CI から継続的に走ります)。**(2) 実ブラウザでの実行 = 手動で 1 回確認済み**: 2026-08-29 に Teiresias のデモを実ブラウザで動かして確かめました。1 回の手動確認は自動テストではないため、回帰は防げません。**(3) CI での継続的・自動のブラウザ実行 = 未対応**(予定。[#4](https://github.com/code4history/Daedalus/issues/4) を参照)。
- Scope: fitting only, not CRS candidate lookup

English README is [here](./README.md).
Expand Down Expand Up @@ -81,7 +81,7 @@ affine の残差自由度は `df2 = 2n-6` である。採用は次の**両方**

`holdout` を指定した場合はさらに `holdoutRmsAffine <= holdoutRmsSimilarity` を要求する。

**SSE の数値的ゼロ**は厳密比較ではなく許容つきで判定する(仕様正本の「数値許容内の厳密適合」)。
**SSE の数値的ゼロ**は厳密比較ではなく許容つきで判定する(「数値許容内の厳密適合」)。

```
epsSSE = 1024 · Number.EPSILON² · Σ(X² + Y²) (和は training GCP の geo 座標)
Expand All @@ -92,7 +92,7 @@ Z(s) = (s <= epsSSE)
- `Z(SSE6)` かつ `¬Z(SSE4)`: `F = +Infinity` として F gate を通す

`alpha = 0.05` / `minRelativeImprovement = 0.01` / 安全係数 `1024` は実データで較正した値ではなく、
Cycle 1 の過適合抑制のための初期ヒューリスティック(仮仕様)である。
過適合抑制のための初期ヒューリスティックである。

### `debug`(`options.debug` が真のときのみ)

Expand All @@ -104,21 +104,14 @@ Cycle 1 の過適合抑制のための初期ヒューリスティック(仮仕
| `fStatistic` / `criticalF` / `relativeImprovement` | F gate を評価したとき |
| `holdoutRmsSimilarity` / `holdoutRmsAffine` | `holdout` を指定して検証に到達したとき |

### 非目標(Cycle 1)
### 非目標

次のものには対応していません。将来の版の候補として [#3](https://github.com/code4history/Daedalus/issues/3)(検証・重み・ロバスト推定・広域など)と [#4](https://github.com/code4history/Daedalus/issues/4)(CI でのブラウザ実行)で扱います。

- LOO(leave-one-out)validation(未指定 holdout は `validationSkipped`)
- 一般形 `criticalF`(df1≠2 の不完全ベータ)
- weight / robust fitting / 逆写像 RMS の高度化 / アンチメリディアン・極域

## 関連文書

- [CRS 推定ライブラリ群 仮仕様正本](../docs/superpowers/specs/2026-08-27-c1-crs-libs-provisional-spec.md) —
本 package の観測契約・数値挙動が集約されている(**仮仕様**であり人間承認済みの確定仕様ではない)。
- [mock transformer 契約文書](../docs/superpowers/specs/2026-08-28-mock-transformer-contract.md) —
`src/testkit/` が提供する mock adapter の契約。

上記リンクは**親リポジトリ(monorepo)を checkout したときにのみ解決する**。
本 repository を単体で clone した場合、`../docs/` は存在しない。
- CI での継続的・自動のブラウザ実行(上の「Runtime」を参照)

## ライセンス

Expand Down
25 changes: 9 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

- Input: GCPs plus a single CRS
- Output: `world_file_basic` and post-shear refinement
- Runtime: Node.js and browser. The browser story differs line by line, so it is written in three tiers (m3-t1). **(1) Bundlability = verified**: Teiresias' `pnpm run verify:demo-bundle` (`scripts/verify-demo-browser-bundle.mjs`) scans the output chunks of the demo build and mechanically verifies that no Node-specific specifier remains and that Daedalus-derived code is actually present (it runs continuously from CI). **(2) Execution in a real browser = observed (not "verified")**: the Teiresias demo was observed **once** in a real browser on 2026-08-29 (m3-t1/AC-16). A single observation is not an automated check, so it does not guard against regressions. **(3) Continuous, automated browser execution on CI and automated canvas drag operation = unverified** (a known gap of Cycle 1). `Daedalus/src` has not been changed by a single byte for this work (the m0 freeze has not been lifted).
- Runtime: Node.js and browser. Browser support is described in three levels. **(1) Bundlability = verified**: Teiresias' `pnpm run verify:demo-bundle` (`scripts/verify-demo-browser-bundle.mjs`) scans the output chunks of the demo build and mechanically verifies that no Node-specific specifier remains and that Daedalus-derived code is actually present (it runs continuously from CI). **(2) Execution in a real browser = checked manually once**: the Teiresias demo was run in a real browser on 2026-08-29. A single manual check is not an automated test, so it does not guard against regressions. **(3) Continuous, automated browser execution on CI = not available yet** (planned; see [#4](https://github.com/code4history/Daedalus/issues/4)).
- Scope: fitting only, not CRS candidate lookup

日本語のREADMEは[こちら](./README.ja.md)。
Expand Down Expand Up @@ -84,7 +84,7 @@ the following hold.
When `holdout` is specified, `holdoutRmsAffine <= holdoutRmsSimilarity` is required in addition.

**Numerical zero of the SSE** is judged with a tolerance rather than by strict comparison
(the "exact fit within numerical tolerance" of the provisional specification).
("exact fit within numerical tolerance").

```
epsSSE = 1024 · Number.EPSILON² · Σ(X² + Y²) (the sum is over the geo coordinates of the training GCPs)
Expand All @@ -96,8 +96,7 @@ Z(s) = (s <= epsSSE)
- `Z(SSE6)` and `¬Z(SSE4)`: the F gate is passed by treating `F = +Infinity`

`alpha = 0.05`, `minRelativeImprovement = 0.01` and the safety factor `1024` are not values calibrated
against real data; they are initial heuristics (a provisional specification) for suppressing overfitting
in Cycle 1.
against real data; they are initial heuristics for suppressing overfitting.

### `debug` (only when `options.debug` is truthy)

Expand All @@ -109,22 +108,16 @@ in Cycle 1.
| `fStatistic` / `criticalF` / `relativeImprovement` | when the F gate was evaluated |
| `holdoutRmsSimilarity` / `holdoutRmsAffine` | when `holdout` was specified and validation was reached |

### Non-goals (Cycle 1)
### Non-goals

The following are not supported. They are candidates for a future release and are tracked in the
issues [#3](https://github.com/code4history/Daedalus/issues/3) (validation, weights, robust fitting, wide areas and more) and
[#4](https://github.com/code4history/Daedalus/issues/4) (browser execution on CI).

- LOO (leave-one-out) validation (an unspecified holdout gives `validationSkipped`)
- The general form of `criticalF` (the incomplete beta function for df1≠2)
- Weights / robust fitting / more advanced inverse-mapping RMS / antimeridian and polar regions

## Related documents

- [Provisional specification of the CRS estimation libraries](../docs/superpowers/specs/2026-08-27-c1-crs-libs-provisional-spec.md) —
the observation contract and the numerical behaviour of this package are collected there
(it is a **provisional specification**, not a finalized specification approved by a human).
- [Mock transformer contract](../docs/superpowers/specs/2026-08-28-mock-transformer-contract.md) —
the contract of the mock adapter provided by `src/testkit/`.

The links above **resolve only when the parent repository (the monorepo) is checked out**.
When this repository is cloned on its own, `../docs/` does not exist.
- Continuous, automated browser execution on CI (see "Runtime" above)

## License

Expand Down
14 changes: 11 additions & 3 deletions openspec/changes/bootstrap-worldfile-fitting/tasks.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,12 @@
## 1. Specification
- [ ] 1.1 Define `world_file_basic` fitting.
- [ ] 1.2 Define post-selection shear refinement.
- [ ] 1.3 Define residual metrics and helper contracts.
- [x] 1.1 Define `world_file_basic` fitting.
- [x] 1.2 Define post-selection shear refinement.
- [x] 1.3 Define residual metrics and helper contracts.

> Implemented.
> - 1.1: closed-form similarity (Helmert) fitting behind the public `fitWorldFile` (`src/fitting/similarity.ts`, `src/index.ts`).
> Test: `tests/similarity.test.ts` "similarity closed-form Helmert fitting".
> - 1.2: affine (shear) refinement after selection, adopted only through the F gate and the relative improvement gate,
> with optional holdout validation (`src/fitting/affine.ts`). Test: `tests/affine.test.ts`.
> - 1.3: `rmsMeters` / `rmsPixels`, the `debug` SSE and MSE, and the warning codes (`src/types.ts`).
> Tests: `tests/affine.test.ts`, `tests/contract-freeze.test.ts`, `tests/api-smoke.test.ts`.
2 changes: 1 addition & 1 deletion openspec/project.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Project Context

## Purpose
Daedalus provides world-file fitting for a known target CRS in Maplat V3.1.
Daedalus provides world-file fitting for a known target CRS in Maplat.

## Tech Stack
- TypeScript (planned)
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
"default": "./dist/index.js"
}
},
"description": "World-file fitting helpers for Maplat V3.1.",
"description": "World-file fitting helpers for Maplat.",
"repository": {
"type": "git",
"url": "git+https://github.com/code4history/Daedalus.git"
Expand Down
Loading