planlens 0.1.0__tar.gz

planlens-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Sean O'Connell
+
+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.

planlens-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: planlens
+Version: 0.1.0
+Summary: Drawing & submittal intelligence — deterministic geometry extraction and confidence-scored annotation constructs (leaders, dimensions, title blocks, bubbles, revision clouds) from PDF and DXF construction drawings
+Author-email: Sean O'Connell <soconnell345@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Requires-Dist: ezdxf>=1.4
+Requires-Dist: PyMuPDF>=1.23
+Provides-Extra: raster
+Requires-Dist: opencv-python-headless>=4.8; extra == "raster"
+Provides-Extra: ocr
+Requires-Dist: rapidocr-onnxruntime<1.3,>=1.2; extra == "ocr"
+Dynamic: license-file
+
+# planlens
+
+Drawing & submittal intelligence: deterministic geometry extraction plus
+confidence-scored annotation constructs from PDF and DXF construction
+drawings.
+
+## Architecture
+
+Two layers, one principle — **geometry says WHERE, vision says WHAT**.
+LLM/VLM vision is unreliable on precise geometry, so a deterministic
+extractor owns every coordinate and an LLM (if you attach one) owns only
+semantics.
+
+1. **Primitive layer** (`planlens.ir`): a unified intermediate
+   representation — Line / Polyline / Arc / Circle / Text with
+   coordinates, layer, provenance, and confidence — ingested from DXF
+   (`ezdxf`, confidence 1.0), vector PDF (`planlens.pdf`, confidence
+   1.0), or raster images (OpenCV, confidence < 1.0, `raster` extra).
+   Slice queries (bbox / angle / text / layer / nearest / endpoint) let
+   a caller request exactly the geometry it needs.
+2. **Composition layer** (`planlens.ir.queries`): named annotation
+   constructs assembled from primitives as confidence-scored
+   **proposals**, never asserted facts — leaders, dimensions, title
+   blocks, bubble callouts (keynotes, grid bubbles, detail marks), and
+   best-effort revision clouds. Every proposal carries the evidence it
+   was built from.
+
+`planlens.ir.render.render_region` snips any region of a sheet to a
+high-DPI PNG (optionally with numbered set-of-marks overlays) so a
+vision model can answer "what is this pointing at" about a location the
+geometry layer pinned down.
+
+`planlens.ocr` (optional `[ocr]` extra) reads lettering optically off
+rendered sheets — many production plots letter with stroked outlines
+(no text layer at all) — and merges the results into the IR as
+confidence-scored text entities in the same coordinate frame
+(auto-detects sideways-plotted sheets and PDF page rotation, and
+corrects the engine's silent corner-order rotation on flipped or
+vertical lines — verified within ~2 pt of the vector-ingest frame on
+/Rotate=0/90/180/270 and both vertical reading directions).
+
+`planlens.ir.align.fit_plot_transform` fits the model-space-to-plot
+transform (axis rotation + scale + offset) from anchor geometry, so
+native CAD entities can be located on the plotted page.
+
+## Capability status (kept honest)
+
+- **Proven on real agency sheets**: bubble callouts (40/40 count match
+  on a dense municipal standard detail), region rendering, endpoint /
+  text-anchored queries, multi-page drawing-set search, OCR text
+  recovery on no-text-layer plots (88-100% truth-text coverage, median
+  coordinate error 2.2-15.5 pt per the committed ocr_coverage_check
+  convention on the validation sheets), plot-transform
+  fitting (0.02-0.03 pt rms on rotated real plots; guarded against the
+  degenerate-scale and chance-match regimes — random anchors on a dense
+  10k-entity sheet now return None in 60/60 trials while every true fit
+  still passes), and native DXF annotation ingest (LEADER/MULTILEADER/
+  DIMENSION/ATTRIB as first-class entities at confidence 1.0, surfaced
+  by find_leaders/find_dimensions as evidence "native_dxf"; the
+  ground-truth extractor lives at planlens.dxf.truth and reproduces the
+  committed corpus's MODEL-SPACE annotation content exactly — it does
+  not yet extract paper-space layouts, which the committed files also
+  carry, so regenerating the corpus with it would drop those blocks).
+- **Partially proven on real sheets**: leader detection reaches 21/25
+  native-truth tips on the validation set (11/25 before the 2026-09-05
+  arrowhead-representation work; 0/25 before the plot-transform fit).
+  The 2026-09-05 gain came from accepting 3-vertex OPEN arrow chains —
+  real plotters draw an arrow outline minus one whole edge, in both
+  base+leg and chevron flavors — behind a shape gate calibrated to
+  measured real arrows. PRECISION IS SHEET-DEPENDENT and verified by
+  rendering: the gate does NOT filter SHX letterforms on
+  annotation-free, lettering-heavy sheets (hundreds of
+  letterform leader proposals at default confidence there — treat
+  leader RECALL as proven and leader precision as unproven outside
+  annotation-rich sheets). Dimension detection on the same sheets
+  reaches 13/16 native defpoints (from 1/16) via a split-shaft
+  pairing leg: two collinear opposed-arrow half-shafts around a
+  centered text gap, plus the outside-arrows narrow style, both with
+  witness-line corroboration; proposal ends are the arrow apexes (the
+  CAD defpoints). Witness lines require arrowhead-scale length and
+  un-corroborated no-text proposals cap at confidence 0.45 — the
+  worst sheet's default output went from 44 proposals at ~0 precision
+  to 11 with 8 touching native truth. Independent render-adjudication
+  of every non-matching detection (2026-09-05): on the curb-ramp
+  sheet 9 of 10 were REAL manually-drafted dimensions the native
+  truth cannot record (measured precision ~14/15); on note-heavy SHX
+  sheets confidence 1.0 does NOT preclude glyph junk (21.01: ~5/14
+  semantic precision) — verify visually there. Residual misses:
+  tips with no plotted arrow fragments, sparse dots inside stipple,
+  and witness-crossing vertical dimension layouts (not yet modeled).
+- **Best-effort tier**: revision clouds (drafting-practice dependent).
+
+## Install
+
+```
+pip install planlens            # DXF + vector-PDF ingest
+pip install "planlens[raster]"  # + raster/scanned-sheet tracing
+pip install "planlens[ocr]"     # + optical text for stroked/scanned sheets
+```
+
+The `[ocr]` extra installs RapidOCR + onnxruntime with PP-OCR models
+inside the wheel (no runtime downloads; all-permissive licenses:
+Apache-2.0/MIT/BSD).
+
+**OpenCV variants — pick per environment.** Every published rapidocr
+distribution (`rapidocr-onnxruntime` 1.x and the unified `rapidocr`
+2/3.x alike) hard-requires the full GUI `opencv-python` (~112 MB),
+while the `[raster]` extra uses `opencv-python-headless`; pip cannot
+express "either variant", and installing both leaves two distributions
+owning the `cv2` namespace (works, but uninstalling either can break
+the other). Decision:
+
+- **Desktop / notebook**: `pip install "planlens[raster,ocr]"` as
+  above — the GUI build wins the namespace and everything works.
+- **Server / headless deploy** (Databricks, TinyApps — no GUI libs):
+  skip the `[ocr]` extra and install the engine without its metadata
+  deps; the OCR leg needs only the cv2 APIs headless provides
+  (verified end-to-end in a clean headless-only venv, 2026-09-05):
+
+  ```
+  pip install "planlens[raster]"
+  pip install --no-deps "rapidocr-onnxruntime==1.2.3"
+  pip install "onnxruntime>=1.7" pyclipper shapely pillow pyyaml six
+  ```
+
+  Pin the rapidocr version you validated — `--no-deps` means ITS
+  dependency list is being supplied by hand, so an unpinned upgrade
+  could silently need something new. (1.2.3 is the newest wheel that
+  installs on Python 3.14 today; newer versions keep the same runtime
+  set — re-verify when bumping.)

planlens-0.1.0/README.md

@@ -0,0 +1,130 @@
+# planlens
+
+Drawing & submittal intelligence: deterministic geometry extraction plus
+confidence-scored annotation constructs from PDF and DXF construction
+drawings.
+
+## Architecture
+
+Two layers, one principle — **geometry says WHERE, vision says WHAT**.
+LLM/VLM vision is unreliable on precise geometry, so a deterministic
+extractor owns every coordinate and an LLM (if you attach one) owns only
+semantics.
+
+1. **Primitive layer** (`planlens.ir`): a unified intermediate
+   representation — Line / Polyline / Arc / Circle / Text with
+   coordinates, layer, provenance, and confidence — ingested from DXF
+   (`ezdxf`, confidence 1.0), vector PDF (`planlens.pdf`, confidence
+   1.0), or raster images (OpenCV, confidence < 1.0, `raster` extra).
+   Slice queries (bbox / angle / text / layer / nearest / endpoint) let
+   a caller request exactly the geometry it needs.
+2. **Composition layer** (`planlens.ir.queries`): named annotation
+   constructs assembled from primitives as confidence-scored
+   **proposals**, never asserted facts — leaders, dimensions, title
+   blocks, bubble callouts (keynotes, grid bubbles, detail marks), and
+   best-effort revision clouds. Every proposal carries the evidence it
+   was built from.
+
+`planlens.ir.render.render_region` snips any region of a sheet to a
+high-DPI PNG (optionally with numbered set-of-marks overlays) so a
+vision model can answer "what is this pointing at" about a location the
+geometry layer pinned down.
+
+`planlens.ocr` (optional `[ocr]` extra) reads lettering optically off
+rendered sheets — many production plots letter with stroked outlines
+(no text layer at all) — and merges the results into the IR as
+confidence-scored text entities in the same coordinate frame
+(auto-detects sideways-plotted sheets and PDF page rotation, and
+corrects the engine's silent corner-order rotation on flipped or
+vertical lines — verified within ~2 pt of the vector-ingest frame on
+/Rotate=0/90/180/270 and both vertical reading directions).
+
+`planlens.ir.align.fit_plot_transform` fits the model-space-to-plot
+transform (axis rotation + scale + offset) from anchor geometry, so
+native CAD entities can be located on the plotted page.
+
+## Capability status (kept honest)
+
+- **Proven on real agency sheets**: bubble callouts (40/40 count match
+  on a dense municipal standard detail), region rendering, endpoint /
+  text-anchored queries, multi-page drawing-set search, OCR text
+  recovery on no-text-layer plots (88-100% truth-text coverage, median
+  coordinate error 2.2-15.5 pt per the committed ocr_coverage_check
+  convention on the validation sheets), plot-transform
+  fitting (0.02-0.03 pt rms on rotated real plots; guarded against the
+  degenerate-scale and chance-match regimes — random anchors on a dense
+  10k-entity sheet now return None in 60/60 trials while every true fit
+  still passes), and native DXF annotation ingest (LEADER/MULTILEADER/
+  DIMENSION/ATTRIB as first-class entities at confidence 1.0, surfaced
+  by find_leaders/find_dimensions as evidence "native_dxf"; the
+  ground-truth extractor lives at planlens.dxf.truth and reproduces the
+  committed corpus's MODEL-SPACE annotation content exactly — it does
+  not yet extract paper-space layouts, which the committed files also
+  carry, so regenerating the corpus with it would drop those blocks).
+- **Partially proven on real sheets**: leader detection reaches 21/25
+  native-truth tips on the validation set (11/25 before the 2026-09-05
+  arrowhead-representation work; 0/25 before the plot-transform fit).
+  The 2026-09-05 gain came from accepting 3-vertex OPEN arrow chains —
+  real plotters draw an arrow outline minus one whole edge, in both
+  base+leg and chevron flavors — behind a shape gate calibrated to
+  measured real arrows. PRECISION IS SHEET-DEPENDENT and verified by
+  rendering: the gate does NOT filter SHX letterforms on
+  annotation-free, lettering-heavy sheets (hundreds of
+  letterform leader proposals at default confidence there — treat
+  leader RECALL as proven and leader precision as unproven outside
+  annotation-rich sheets). Dimension detection on the same sheets
+  reaches 13/16 native defpoints (from 1/16) via a split-shaft
+  pairing leg: two collinear opposed-arrow half-shafts around a
+  centered text gap, plus the outside-arrows narrow style, both with
+  witness-line corroboration; proposal ends are the arrow apexes (the
+  CAD defpoints). Witness lines require arrowhead-scale length and
+  un-corroborated no-text proposals cap at confidence 0.45 — the
+  worst sheet's default output went from 44 proposals at ~0 precision
+  to 11 with 8 touching native truth. Independent render-adjudication
+  of every non-matching detection (2026-09-05): on the curb-ramp
+  sheet 9 of 10 were REAL manually-drafted dimensions the native
+  truth cannot record (measured precision ~14/15); on note-heavy SHX
+  sheets confidence 1.0 does NOT preclude glyph junk (21.01: ~5/14
+  semantic precision) — verify visually there. Residual misses:
+  tips with no plotted arrow fragments, sparse dots inside stipple,
+  and witness-crossing vertical dimension layouts (not yet modeled).
+- **Best-effort tier**: revision clouds (drafting-practice dependent).
+
+## Install
+
+```
+pip install planlens            # DXF + vector-PDF ingest
+pip install "planlens[raster]"  # + raster/scanned-sheet tracing
+pip install "planlens[ocr]"     # + optical text for stroked/scanned sheets
+```
+
+The `[ocr]` extra installs RapidOCR + onnxruntime with PP-OCR models
+inside the wheel (no runtime downloads; all-permissive licenses:
+Apache-2.0/MIT/BSD).
+
+**OpenCV variants — pick per environment.** Every published rapidocr
+distribution (`rapidocr-onnxruntime` 1.x and the unified `rapidocr`
+2/3.x alike) hard-requires the full GUI `opencv-python` (~112 MB),
+while the `[raster]` extra uses `opencv-python-headless`; pip cannot
+express "either variant", and installing both leaves two distributions
+owning the `cv2` namespace (works, but uninstalling either can break
+the other). Decision:
+
+- **Desktop / notebook**: `pip install "planlens[raster,ocr]"` as
+  above — the GUI build wins the namespace and everything works.
+- **Server / headless deploy** (Databricks, TinyApps — no GUI libs):
+  skip the `[ocr]` extra and install the engine without its metadata
+  deps; the OCR leg needs only the cv2 APIs headless provides
+  (verified end-to-end in a clean headless-only venv, 2026-09-05):
+
+  ```
+  pip install "planlens[raster]"
+  pip install --no-deps "rapidocr-onnxruntime==1.2.3"
+  pip install "onnxruntime>=1.7" pyclipper shapely pillow pyyaml six
+  ```
+
+  Pin the rapidocr version you validated — `--no-deps` means ITS
+  dependency list is being supplied by hand, so an unpinned upgrade
+  could silently need something new. (1.2.3 is the newest wheel that
+  installs on Python 3.14 today; newer versions keep the same runtime
+  set — re-verify when bumping.)

planlens-0.1.0/planlens/__init__.py

@@ -0,0 +1,8 @@
+"""planlens — drawing & submittal intelligence.
+
+Deterministic geometry extraction (:mod:`planlens.ir`, :mod:`planlens.pdf`,
+:mod:`planlens.dxf`) plus confidence-scored annotation constructs
+(:mod:`planlens.ir.queries`) from PDF/DXF construction drawings.
+"""
+
+__version__ = "0.1.0"

planlens-0.1.0/planlens/dxf/__init__.py

@@ -0,0 +1,10 @@
+"""DXF-side utilities: unit detection/conversion + native-annotation truth
+extraction (:mod:`planlens.dxf.truth`). Native LEADER / MULTILEADER /
+DIMENSION / ATTRIB ingest into the IR lives in :func:`planlens.ir.from_dxf`."""
+
+from planlens.dxf.units import (  # noqa: F401
+    UNIT_FACTORS,
+    convert_coords,
+    detect_units_from_header,
+)
+from planlens.dxf.truth import extract_native_annotations  # noqa: F401

planlens-0.1.0/planlens/dxf/truth.py

@@ -0,0 +1,153 @@
+"""Native-annotation extraction from a DXF — the ground-truth API.
+
+Extracts the annotation entities a CAD file DECLARES — LEADER,
+MULTILEADER, DIMENSION, TEXT/MTEXT, INSERT — as plain JSON-able dicts in
+raw model-space coordinates (no unit conversion, no IR wrapping). This is
+the extractor behind the drawing-intelligence ground-truth corpus: the
+composition heuristics are scored against what the native CAD file says
+was drawn, so this module deliberately reports raw values (MTEXT
+formatting codes retained, raw group-70 ``dimtype``, coordinates rounded
+to 4 decimals) exactly as the committed ``*.truth.json`` files do.
+
+For the IR-level view of the same entities (unit-converted, plain text,
+first-class :class:`planlens.ir.results.Leader` / ``Dimension`` entities
+at confidence 1.0) use :func:`planlens.ir.from_dxf` — that is the surface
+queries and agents consume; this one is for scoring and corpus building.
+
+Usage::
+
+    from planlens.dxf.truth import extract_native_annotations
+    truth = extract_native_annotations("sheet.dxf")
+    truth["spaces"]["model"]["dimensions"][0]["defpoint"]
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional
+
+__all__ = ["extract_native_annotations"]
+
+
+def _xy(v, nd: int = 4) -> List[float]:
+    try:
+        x, y = v.x, v.y
+    except AttributeError:  # plain tuple/list vertex (older ezdxf paths)
+        x, y = v[0], v[1]
+    return [round(float(x), nd), round(float(y), nd)]
+
+
+def _space_annotations(space) -> Dict[str, List[Dict[str, Any]]]:
+    out: Dict[str, List[Dict[str, Any]]] = {
+        "leaders": [], "multileaders": [], "dimensions": [],
+        "text": [], "inserts": [],
+    }
+    for e in space:
+        etype = e.dxftype()
+        layer = e.dxf.get("layer", "0")
+        if etype == "LEADER":
+            out["leaders"].append({
+                "vertices": [_xy(v) for v in e.vertices],
+                "layer": layer,
+                "has_arrowhead": bool(e.dxf.get("has_arrowhead", 1)),
+                "annotation_handle": e.dxf.get("annotation_handle", None)
+                or "",
+            })
+        elif etype == "MULTILEADER":
+            try:
+                ctx = e.context
+                mtext = getattr(ctx, "mtext", None)
+                text = (mtext.default_content
+                        if mtext is not None else "") or ""
+                lines = [[_xy(v) for v in ln.vertices]
+                         for ml in ctx.leaders for ln in ml.lines]
+            except Exception:
+                text, lines = "", []
+            out["multileaders"].append({
+                "text": text,
+                "leader_lines": lines,
+                "layer": layer,
+            })
+        elif etype == "DIMENSION":
+            try:
+                meas = round(float(e.get_measurement()), 4)
+            except Exception:
+                meas = 0.0
+            dp = e.dxf.get("defpoint", None)
+            tm = e.dxf.get("text_midpoint", None)
+            out["dimensions"].append({
+                "dimtype": int(e.dxf.get("dimtype", 0) or 0),
+                "text": e.dxf.get("text", ""),
+                "defpoint": _xy(dp) if dp is not None else None,
+                "text_midpoint": _xy(tm) if tm is not None else None,
+                "measurement": meas,
+                "layer": layer,
+            })
+        elif etype in ("TEXT", "MTEXT"):
+            ins = e.dxf.get("insert", None)
+            if etype == "TEXT":
+                content = e.dxf.get("text", "")
+                height = e.dxf.get("height", 0.0)
+            else:
+                content = e.text
+                height = e.dxf.get("char_height", 0.0)
+            out["text"].append({
+                "type": etype,
+                "text": content,
+                "insert": _xy(ins) if ins is not None else None,
+                "height": round(float(height), 4),
+                "rotation": round(float(e.dxf.get("rotation", 0.0)), 2),
+                "layer": layer,
+            })
+        elif etype == "INSERT":
+            ins = e.dxf.get("insert", None)
+            rec: Dict[str, Any] = {
+                "name": e.dxf.get("name", ""),
+                "insert": _xy(ins) if ins is not None else None,
+                "layer": layer,
+            }
+            attribs = [{"tag": a.dxf.get("tag", ""),
+                        "text": a.dxf.get("text", ""),
+                        "insert": _xy(a.dxf.insert),
+                        "height": round(float(a.dxf.get("height", 0.0)), 4)}
+                       for a in e.attribs if a.dxf.get("text", "")]
+            if attribs:
+                rec["attribs"] = attribs
+            out["inserts"].append(rec)
+    return out
+
+
+def extract_native_annotations(filepath: Optional[str] = None,
+                               doc=None) -> Dict[str, Any]:
+    """Extract native annotation entities from a DXF, truth-file schema.
+
+    Pass a ``filepath`` or an already-open ezdxf ``doc``. Returns::
+
+        {"source_dxf": <basename>,
+         "spaces": {"model": {"leaders": [...], "multileaders": [...],
+                              "dimensions": [...], "text": [...],
+                              "inserts": [...]}}}
+
+    Model-space coordinates are RAW drawing units rounded to 4 decimals;
+    MTEXT keeps its inline formatting codes; ``dimtype`` is the raw DXF
+    group-70 value. ``inserts`` additionally carry an ``attribs`` list
+    (tag/text/insert/height) when the reference has attribute values — a
+    superset of the original truth schema, additive only.
+    """
+    if (filepath is None) == (doc is None):
+        raise ValueError("pass exactly one of filepath / doc")
+    if doc is None:
+        try:
+            import ezdxf
+        except ImportError as exc:
+            raise ImportError("ezdxf is required: pip install ezdxf>=1.4"
+                              ) from exc
+        doc = ezdxf.readfile(filepath)
+        name = os.path.basename(filepath)
+    else:
+        name = getattr(doc, "filename", None) or ""
+        name = os.path.basename(name) if name else ""
+    return {
+        "source_dxf": name,
+        "spaces": {"model": _space_annotations(doc.modelspace())},
+    }

planlens-0.1.0/planlens/dxf/units.py

@@ -0,0 +1,92 @@
+"""
+Unit conversion utilities for DXF geometry import.
+
+Converts coordinates from DXF drawing units (mm, cm, ft, in) to SI meters.
+Also detects units from the $INSUNITS DXF header variable.
+
+$INSUNITS values (per DXF spec):
+    0 = Unitless, 1 = Inches, 2 = Feet, 3 = Miles, 4 = Millimeters,
+    5 = Centimeters, 6 = Meters, 7 = Kilometers, ...
+"""
+
+from typing import List, Optional, Tuple
+
+# Conversion factors to meters
+UNIT_FACTORS = {
+    "m": 1.0,
+    "mm": 0.001,
+    "cm": 0.01,
+    "ft": 0.3048,
+    "in": 0.0254,
+}
+
+# DXF $INSUNITS header variable mapping
+_INSUNITS_MAP = {
+    1: "in",
+    2: "ft",
+    4: "mm",
+    5: "cm",
+    6: "m",
+}
+
+
+def convert_coords(
+    points: List[Tuple[float, float]],
+    from_units: str,
+    to_units: str = "m",
+) -> List[Tuple[float, float]]:
+    """Convert a list of (x, y) coordinate pairs between unit systems.
+
+    Parameters
+    ----------
+    points : list of (float, float)
+        Input coordinates.
+    from_units : str
+        Source units ('m', 'mm', 'cm', 'ft', 'in').
+    to_units : str
+        Target units. Default 'm'.
+
+    Returns
+    -------
+    list of (float, float)
+        Converted coordinates.
+
+    Raises
+    ------
+    ValueError
+        If either unit string is not recognized.
+    """
+    if from_units not in UNIT_FACTORS:
+        raise ValueError(
+            f"Unknown source unit '{from_units}'. "
+            f"Supported: {sorted(UNIT_FACTORS.keys())}"
+        )
+    if to_units not in UNIT_FACTORS:
+        raise ValueError(
+            f"Unknown target unit '{to_units}'. "
+            f"Supported: {sorted(UNIT_FACTORS.keys())}"
+        )
+    if from_units == to_units:
+        return list(points)
+    factor = UNIT_FACTORS[from_units] / UNIT_FACTORS[to_units]
+    return [(x * factor, y * factor) for x, y in points]
+
+
+def detect_units_from_header(doc) -> Optional[str]:
+    """Read $INSUNITS from a DXF document header and return unit string.
+
+    Parameters
+    ----------
+    doc : ezdxf.document.Drawing
+        An ezdxf document object.
+
+    Returns
+    -------
+    str or None
+        Unit string ('m', 'ft', 'mm', etc.) or None if not set / unknown.
+    """
+    try:
+        insunits = doc.header.get("$INSUNITS", 0)
+    except Exception:
+        return None
+    return _INSUNITS_MAP.get(insunits, None)

planlens-0.1.0/planlens/ir/__init__.py

@@ -0,0 +1,65 @@
+"""
+Drawing IR — an LLM-ready intermediate representation for a drawing page.
+
+Design north star: LLM vision is unreliable on precise geometry, so the
+DETERMINISTIC extractor owns coordinates and the LLM owns semantics. A drawing
+(DXF, PDF vector, or raster scan) is digitized once into a unified
+:class:`DrawingIR` — every line/polyline/arc/circle/text with coordinates,
+provenance and per-entity confidence — and the LLM then requests *slices* of it
+through :mod:`planlens.ir.queries` (spatial windows, angle bands, text near an
+entity, layer/color groups) instead of interpreting pixels.
+
+Quick start::
+
+    from planlens.ir import from_dxf, queries
+
+    ir = from_dxf("section.dxf")           # exact CAD geometry -> DrawingIR
+    print(ir.summary())
+    surf = queries.candidate_ground_surface(ir)   # a PROPOSAL to confirm
+    labels = queries.text_items(ir, pattern="clay")
+
+Ingest legs: :func:`from_dxf` (ezdxf, confidence 1.0), :func:`from_pdf_vector`
+(PyMuPDF + the pdf_import scale module, confidence 1.0), :func:`from_raster`
+(OpenCV tracing, confidence < 1.0). See ``DESIGN.md`` for schema, confidence /
+provenance semantics, and the raster leg's honest limits.
+"""
+
+from planlens.ir.results import (
+    Arc,
+    Circle,
+    Dimension,
+    DrawingIR,
+    Entity,
+    Leader,
+    Line,
+    Polyline,
+    Region,
+    TextItem,
+    entity_from_dict,
+)
+from planlens.ir.ingest import from_dxf, from_pdf_vector, from_raster
+from planlens.ir.render import render_region
+from planlens.ir import queries
+
+__all__ = [
+    # schema
+    "DrawingIR",
+    "Entity",
+    "Line",
+    "Polyline",
+    "Arc",
+    "Circle",
+    "TextItem",
+    "Region",
+    "Leader",
+    "Dimension",
+    "entity_from_dict",
+    # ingest
+    "from_dxf",
+    "from_pdf_vector",
+    "from_raster",
+    # region-snip vision primitive (PyMuPDF imported lazily inside)
+    "render_region",
+    # queries (module)
+    "queries",
+]