pydfig 0.1.0__py3-none-any.whl

pydfig/__init__.py

@@ -0,0 +1,43 @@
+"""
+pydfig — self-describing scientific figures (Figure-as-Data).
+
+A pydfig figure looks like a normal SVG/PNG in any viewer, but carries its
+exact underlying data as structured JSON that parsers and LLM agents read
+losslessly — no OCR, no pixel digitization, no error.
+
+  * SVG -> JSON payload inside the standard W3C <metadata> element
+          (renderers ignore it; parsers/LLMs read it losslessly),
+          plus per-element `data-*` attribute redundancy.
+  * PNG -> JSON payload inside a private ancillary chunk `dDat`
+          (a legal PNG; any viewer opens it).
+
+Pure standard library for encode/decode; matplotlib is an optional extra for
+the matplotlib export helper.
+"""
+
+from .decoder import (
+    decode_svg,
+    decode_png,
+    decode_any,
+    extract_datapoints,
+)
+from .encoder import (
+    build_payload,
+    embed_in_svg,
+    inject_png_ddat,
+    PYDFIG_NS,
+    SCHEMA_VERSION,
+)
+from .html import render_html, write_html
+from .matplotlib_converter import convert, quick_convert
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "decode_svg", "decode_png", "decode_any", "extract_datapoints",
+    "build_payload", "embed_in_svg", "inject_png_ddat",
+    "PYDFIG_NS", "SCHEMA_VERSION",
+    "render_html", "write_html",
+    "convert", "quick_convert",
+    "__version__",
+]

pydfig/__main__.py

@@ -0,0 +1,7 @@
+"""Enable ``python -m pydfig ...``."""
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

pydfig/cli.py

@@ -0,0 +1,88 @@
+"""
+pydfig.cli — command line interface.
+
+Usage:
+    python -m pydfig encode <file.svg|file.png> --payload P.json [-o OUT]
+        inject a pydfig payload into an SVG or PNG file.
+
+    python -m pydfig decode <file.svg|file.png> [-o OUT_BASE]
+        decode the payload and write two files:
+          OUT_BASE.json  — machine-readable JSON for AI / pipelines
+          OUT_BASE.html  — human-friendly HTML view of the data
+"""
+
+import argparse
+import json
+import os
+import sys
+
+from .decoder import decode_any
+from .encoder import embed_in_svg, inject_png_ddat
+
+
+def _info(payload):
+    ft = payload.get("figure_type", "?")
+    n_pts = len(payload.get("points", []))
+    n_curves = len(payload.get("curves", []))
+    return f"type={ft}  points={n_pts}  curves={n_curves}"
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="pydfig", description="pydfig self-describing figure toolkit")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p_enc = sub.add_parser("encode", help="inject a pydfig payload into an SVG or PNG")
+    p_enc.add_argument("file", help="input SVG or PNG file")
+    p_enc.add_argument("--payload", required=True, help="JSON file with the pydfig payload")
+    p_enc.add_argument("-o", "--out", default=None, help="output file (default: <input>_pydfig.<ext>)")
+
+    p_dec = sub.add_parser("decode", help="decode payload -> JSON (AI) + HTML (human)")
+    p_dec.add_argument("file", help="input SVG or PNG file")
+    p_dec.add_argument("-o", "--out", default=None, help="output base name (default: <input>_pydfig)")
+
+    args = ap.parse_args(argv)
+
+    if args.cmd == "encode":
+        with open(args.payload, encoding="utf-8") as f:
+            payload = json.load(f)
+        ext = os.path.splitext(args.file)[1].lower()
+        if ext == ".svg":
+            with open(args.file, "r", encoding="utf-8") as f:
+                svg_text = f.read()
+            out = args.out or (os.path.splitext(args.file)[0] + "_pydfig.svg")
+            with open(out, "w", encoding="utf-8") as f:
+                f.write(embed_in_svg(svg_text, payload))
+        elif ext == ".png":
+            with open(args.file, "rb") as f:
+                png_bytes = f.read()
+            out = args.out or (os.path.splitext(args.file)[0] + "_pydfig.png")
+            with open(out, "wb") as f:
+                f.write(inject_png_ddat(png_bytes, payload))
+        else:
+            print("unsupported input extension; use .svg or .png", file=sys.stderr)
+            return 1
+        print("pydfig payload injected ->", out)
+        return 0
+
+    if args.cmd == "decode":
+        payload = decode_any(args.file)
+        if payload is None:
+            print("no pydfig payload found in", args.file, file=sys.stderr)
+            return 1
+        base = args.out or (os.path.splitext(args.file)[0] + "_pydfig")
+        json_path = base + ".json"
+        html_path = base + ".html"
+        with open(json_path, "w", encoding="utf-8") as f:
+            json.dump(payload, f, ensure_ascii=False, indent=2)
+        from .html import write_html
+        write_html(payload, html_path)
+        print("decoded:", _info(payload))
+        print("  ->", json_path, "(machine-readable JSON)")
+        print("  ->", html_path, "(human-friendly HTML)")
+        return 0
+
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pydfig/decoder.py

@@ -0,0 +1,109 @@
+"""
+pydfig.decoder — read pydfig payloads from SVG / PNG files.
+
+Two embedding channels are supported:
+
+1. SVG ``<metadata>`` JSON payload (primary channel).
+2. SVG per-element ``data-*`` attributes (redundancy channel; useful for
+   spot-checking and as a fallback when the metadata block is stripped).
+3. PNG private ancillary chunk ``dDat``.
+"""
+
+import json
+import re
+import struct
+
+_PNG_SIG = b"\x89PNG\r\n\x1a\n"
+
+
+def _read_text(source):
+    """Accept a filesystem path, raw text, or bytes; return text."""
+    if isinstance(source, (bytes, bytearray)):
+        return bytes(source).decode("utf-8")
+    if isinstance(source, str) and source.lstrip().startswith("<"):
+        return source
+    with open(source, "r", encoding="utf-8") as f:
+        return f.read()
+
+
+def decode_svg(source):
+    """Extract the pydfig JSON payload from an SVG file/string.
+
+    Returns the payload dict, or None if no <metadata> payload is present.
+    """
+    text = _read_text(source)
+    m = re.search(r"<metadata>(.*?)</metadata>", text, re.S)
+    if not m:
+        return None
+    inner = m.group(1)
+    cdata = re.search(r"<!\[CDATA\[(.*?)\]\]>", inner, re.S)
+    js = cdata.group(1) if cdata else re.sub(r"<[^>]+>", "", inner)
+    return json.loads(js)
+
+
+def extract_datapoints(source):
+    """Extract per-element ``data-*`` attributes (the redundancy channel).
+
+    Every graphical element a pydfig encoder produces carries its own copy of
+    the underlying values, e.g. ``<circle ... data-x="-1.95" data-y="0.42"
+    data-material="NiO"/>``. This function collects them all.
+
+    Returns a list of dicts; numeric-looking values are converted to float.
+    """
+    text = _read_text(source)
+    out = []
+    for m in re.finditer(r"<(circle|rect|path|line|polyline|text)\b[^>]*>", text):
+        tag = m.group(0)
+        attrs = dict(re.findall(r'(data-[\w-]+)="([^"]*)"', tag))
+        if not attrs:
+            continue
+        rec = {}
+        for k, v in attrs.items():
+            key = k[len("data-"):]
+            try:
+                rec[key] = float(v)
+            except ValueError:
+                rec[key] = v
+        out.append(rec)
+    return out
+
+
+def decode_png(source):
+    """Extract the JSON payload from a PNG ``dDat`` private chunk.
+
+    Accepts a path or raw PNG bytes. Returns the payload dict or None.
+    """
+    if isinstance(source, (bytes, bytearray)):
+        data = bytes(source)
+    else:
+        with open(source, "rb") as f:
+            data = f.read()
+    if data[:8] != _PNG_SIG:
+        raise ValueError("not a PNG/pydfig file")
+    i = 8
+    while i < len(data):
+        length = struct.unpack(">I", data[i:i + 4])[0]
+        ctype = data[i + 4:i + 8]
+        cdata = data[i + 8:i + 8 + length]
+        if ctype == b"dDat":
+            return json.loads(cdata.decode("utf-8"))
+        i += 12 + length
+    return None
+
+
+def decode_any(source):
+    """Auto-detect the container and decode the payload.
+
+    Dispatch order: PNG signature -> SVG text probe.
+    Returns the payload dict or None.
+    """
+    if isinstance(source, (bytes, bytearray)) and bytes(source)[:8] == _PNG_SIG:
+        return decode_png(source)
+    if isinstance(source, str):
+        if source.lstrip().startswith("<"):
+            return decode_svg(source)
+        with open(source, "rb") as f:
+            head = f.read(8)
+        if head == _PNG_SIG:
+            return decode_png(source)
+    return decode_svg(source)

pydfig/encoder.py

@@ -0,0 +1,103 @@
+"""
+pydfig.encoder — minimal pydfig writer (pure standard library).
+
+Embedding primitives:
+
+  * ``embed_in_svg``   : insert a <metadata> JSON payload into existing SVG text
+  * ``inject_png_ddat``: insert a `dDat` private chunk into existing PNG bytes
+
+A pydfig figure looks identical to a normal SVG/PNG in any viewer, but carries
+its exact underlying data as structured JSON that parsers and LLM agents read
+losslessly.
+"""
+
+import json
+import re
+import struct
+import zlib
+from datetime import datetime, timezone
+
+PYDFIG_NS = "https://pydfig.ai4c/schema"
+SCHEMA_VERSION = "2.0"
+
+_PNG_SIG = b"\x89PNG\r\n\x1a\n"
+
+
+def build_payload(figure_type, points=None, curves=None, axes=None,
+                  provenance=None, extra=None, caption=None, version=SCHEMA_VERSION):
+    """Construct a pydfig metadata payload.
+
+    Parameters
+    ----------
+    figure_type : str   Semantic figure type (scatter, line, xrd, volcano, ...).
+    points      : list  Exact data points (dicts with numeric x, y).
+    curves      : list  Continuous curves as {"x": [...], "y": [...], "label": ...}.
+    axes        : dict  {"x": {"label", "unit", "range"}, "y": {...}}.
+    provenance  : dict  Free-form domain/technique/method/project metadata.
+    extra       : dict  Domain-specific extension fields.
+    caption     : str   Human-readable figure caption.
+    """
+    payload = {
+        "format": "pydfig",
+        "version": version,
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "figure_type": figure_type,
+        "caption": caption or "",
+        "axes": axes or {},
+        "points": points or [],
+        "curves": curves or [],
+        "provenance": provenance or {},
+    }
+    if extra:
+        payload["extra"] = extra
+    return payload
+
+
+def metadata_block(payload):
+    """Render the payload as an SVG <metadata> block (JSON inside CDATA)."""
+    js = json.dumps(payload, ensure_ascii=False, indent=2)
+    return (
+        "<metadata>\n"
+        f'  <pydfig:payload xmlns:pydfig="{PYDFIG_NS}" format="pydfig" '
+        f'version="{payload.get("version", SCHEMA_VERSION)}">\n'
+        f"  <![CDATA[\n{js}\n]]>\n"
+        "  </pydfig:payload>\n"
+        "</metadata>\n"
+    )
+
+
+def embed_in_svg(svg_text, payload):
+    """Insert a pydfig <metadata> block right after the root <svg ...> tag.
+
+    The visual content is untouched: every compliant SVG renderer ignores
+    <metadata>, so the figure looks identical while becoming machine-readable.
+    """
+    if "<metadata>" in svg_text:
+        raise ValueError("SVG already contains a <metadata> block; refusing to duplicate")
+    m = re.search(r"<svg\b[^>]*>", svg_text)
+    if m is None:
+        raise ValueError("no root <svg> tag found")
+    insert_at = m.end()
+    return svg_text[:insert_at] + metadata_block(payload) + svg_text[insert_at:]
+
+
+def _chunk(chunk_type, data):
+    return (struct.pack(">I", len(data)) + chunk_type + data
+            + struct.pack(">I", zlib.crc32(chunk_type + data) & 0xFFFFFFFF))
+
+
+def inject_png_ddat(png_bytes, payload):
+    """Insert a `dDat` private chunk (JSON payload) before IEND; return new PNG bytes.
+
+    `dDat` is a legal ancillary/private PNG chunk (lowercase second letter),
+    so the result remains a valid PNG that any viewer can open.
+    """
+    png_bytes = bytes(png_bytes)
+    if png_bytes[:8] != _PNG_SIG:
+        raise ValueError("not a PNG file")
+    idx = png_bytes.rfind(b"IEND")
+    if idx < 4:
+        raise ValueError("PNG has no IEND chunk")
+    chunk_start = idx - 4  # step back to the IEND length field
+    ddat = _chunk(b"dDat", json.dumps(payload, ensure_ascii=False).encode("utf-8"))
+    return png_bytes[:chunk_start] + ddat + png_bytes[chunk_start:]

pydfig/html.py

@@ -0,0 +1,191 @@
+"""
+pydfig.html — render a decoded pydfig payload as a human-friendly HTML file.
+
+The HTML is fully self-contained (inline CSS + a reconstructed SVG plot built
+from the embedded data), so the user can open it in any browser and *see* the
+exact data without re-running any parser.
+"""
+
+import json
+
+
+def _bounds(payload):
+    xs, ys = [], []
+    for p in payload.get("points", []):
+        if isinstance(p.get("x"), (int, float)):
+            xs.append(p["x"])
+        if isinstance(p.get("y"), (int, float)):
+            ys.append(p["y"])
+    for c in payload.get("curves", []):
+        xs.extend([v for v in c.get("x", []) if isinstance(v, (int, float))])
+        ys.extend([v for v in c.get("y", []) if isinstance(v, (int, float))])
+    if not xs or not ys:
+        return None
+    return [min(xs), max(xs), min(ys), max(ys)]
+
+
+def _reconstructed_plot(payload):
+    b = _bounds(payload)
+    if not b:
+        return ""
+    xmin, xmax, ymin, ymax = b
+    W, H = 640, 380
+    pad = 48
+    def sx(x):
+        if xmax == xmin:
+            return pad + (W - 2 * pad) / 2
+        return pad + (x - xmin) / (xmax - xmin) * (W - 2 * pad)
+    def sy(y):
+        if ymax == ymin:
+            return H - pad - (H - 2 * pad) / 2
+        return H - pad - (y - ymin) / (ymax - ymin) * (H - 2 * pad)
+
+    parts = [f'<svg viewBox="0 0 {W} {H}" class="plot" preserveAspectRatio="xMidYMid meet">']
+    # axes
+    parts.append(f'<line x1="{pad}" y1="{H-pad}" x2="{W-pad}" y2="{H-pad}" class="axis"/>')
+    parts.append(f'<line x1="{pad}" y1="{pad}" x2="{pad}" y2="{H-pad}" class="axis"/>')
+    # curves
+    for c in payload.get("curves", []):
+        cx = [v for v in c.get("x", []) if isinstance(v, (int, float))]
+        cy = [v for v in c.get("y", []) if isinstance(v, (int, float))]
+        if len(cx) != len(cy) or not cx:
+            continue
+        pts = " ".join(f"{sx(x):.1f},{sy(y):.1f}" for x, y in zip(cx, cy))
+        parts.append(f'<polyline points="{pts}" class="curve"/>')
+    # points
+    for p in payload.get("points", []):
+        if not isinstance(p.get("x"), (int, float)) or not isinstance(p.get("y"), (int, float)):
+            continue
+        parts.append(f'<circle cx="{sx(p["x"]):.1f}" cy="{sy(p["y"]):.1f}" r="3.2" class="pt"/>')
+    # axis labels
+    ax = payload.get("axes", {})
+    xl = ax.get("x", {}).get("label", "")
+    yl = ax.get("y", {}).get("label", "")
+    if xl:
+        parts.append(f'<text x="{W/2}" y="{H-12}" class="axlabel">{_esc(xl)}</text>')
+    if yl:
+        parts.append(f'<text x="14" y="{H/2}" class="axlabel" transform="rotate(-90 14 {H/2})">{_esc(yl)}</text>')
+    parts.append("</svg>")
+    return "\n".join(parts)
+
+
+def _esc(s):
+    return (str(s).replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;"))
+
+
+def _points_table(payload):
+    pts = payload.get("points", [])
+    if not pts:
+        return ""
+    cols = []
+    for p in pts:
+        for k in p:
+            if k not in cols:
+                cols.append(k)
+    rows = "".join(
+        "<tr>" + "".join(f"<td>{_esc(p.get(c, ''))}</td>" for c in cols) + "</tr>"
+        for p in pts
+    )
+    head = "".join(f"<th>{_esc(c)}</th>" for c in cols)
+    return f'<table class="data"><thead><tr>{head}</tr></thead><tbody>{rows}</tbody></table>'
+
+
+def _meta_rows(payload):
+    rows = []
+    rows.append(("Figure type", _esc(payload.get("figure_type", ""))))
+    rows.append(("Format", f'pydfig {_esc(payload.get("version", ""))}'))
+    if payload.get("caption"):
+        rows.append(("Caption", _esc(payload["caption"])))
+    ax = payload.get("axes", {})
+    if ax.get("x"):
+        rows.append(("X axis", _esc(ax["x"].get("label", "")) +
+                     (f' ({ax["x"]["unit"]})' if ax["x"].get("unit") else "")))
+    if ax.get("y"):
+        rows.append(("Y axis", _esc(ax["y"].get("label", "")) +
+                     (f' ({ax["y"]["unit"]})' if ax["y"].get("unit") else "")))
+    if payload.get("provenance"):
+        rows.append(("Provenance", _esc(json.dumps(payload["provenance"], ensure_ascii=False))))
+    body = "".join(f"<tr><th>{k}</th><td>{v}</td></tr>" for k, v in rows)
+    return f'<table class="meta"><tbody>{body}</tbody></table>'
+
+
+def render_html(payload):
+    """Return a self-contained HTML string describing the pydfig payload."""
+    ptype = _esc(payload.get("figure_type", "figure"))
+    caption = _esc(payload.get("caption") or f"pydfig {ptype} figure")
+    plot = _reconstructed_plot(payload)
+    points_tbl = _points_table(payload)
+    curves = payload.get("curves", [])
+    curves_info = ""
+    if curves:
+        items = "".join(f"<li><code>{_esc(c.get('label', 'curve'))}</code> — "
+                        f"{len(c.get('x', []))} samples</li>" for c in curves)
+        curves_info = f"<h3>Curves</h3><ul class='curves'>{items}</ul>"
+    n_pts = len(payload.get("points", []))
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{caption}</title>
+<style>
+  :root {{
+    --bg: #f4f6f9; --card: #ffffff; --ink: #1f2933; --muted: #6b7280;
+    --line: #e3e8ef; --accent: #2f6f9f; --accent2: #4f9d8c;
+  }}
+  * {{ box-sizing: border-box; }}
+  body {{
+    margin: 0; background: var(--bg); color: var(--ink);
+    font: 15px/1.55 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    padding: 32px 16px;
+  }}
+  .wrap {{ max-width: 760px; margin: 0 auto; }}
+  .card {{
+    background: var(--card); border: 1px solid var(--line); border-radius: 14px;
+    padding: 22px 24px; margin-bottom: 18px; box-shadow: 0 1px 3px rgba(20,30,50,.05);
+  }}
+  h1 {{ font-size: 20px; margin: 0 0 4px; }}
+  .badge {{
+    display: inline-block; font-size: 12px; padding: 2px 10px; border-radius: 999px;
+    background: rgba(47,111,159,.12); color: var(--accent); border: 1px solid rgba(47,111,159,.25);
+  }}
+  h3 {{ font-size: 14px; text-transform: uppercase; letter-spacing: .04em;
+        color: var(--muted); margin: 22px 0 8px; }}
+  table {{ border-collapse: collapse; width: 100%; font-size: 13.5px; }}
+  .meta th, .meta td {{ text-align: left; padding: 7px 10px; border-bottom: 1px solid var(--line); vertical-align: top; }}
+  .meta th {{ color: var(--muted); font-weight: 600; width: 130px; }}
+  .data {{ margin-top: 6px; overflow-x: auto; display: block; }}
+  .data th, .data td {{ padding: 5px 10px; border-bottom: 1px solid var(--line); text-align: right; }}
+  .data th {{ color: var(--muted); font-weight: 600; }}
+  .plot {{ width: 100%; height: auto; background: #fbfcfe; border: 1px solid var(--line); border-radius: 10px; }}
+  .axis {{ stroke: #c4ccd6; stroke-width: 1; }}
+  .curve {{ fill: none; stroke: var(--accent2); stroke-width: 2; }}
+  .pt {{ fill: var(--accent); }}
+  .axlabel {{ fill: var(--muted); font-size: 12px; }}
+  ul.curves {{ margin: 4px 0; padding-left: 18px; color: var(--muted); }}
+  code {{ background: #eef2f7; padding: 1px 5px; border-radius: 5px; font-size: 12.5px; }}
+  .foot {{ color: var(--muted); font-size: 12px; text-align: center; margin-top: 8px; }}
+</style>
+</head>
+<body>
+<div class="wrap">
+  <div class="card">
+    <span class="badge">{_esc(payload.get('figure_type', ''))}</span>
+    <h1>{caption}</h1>
+    {_meta_rows(payload)}
+  </div>
+  {f'<div class="card"><h3>Reconstructed from embedded data</h3>{plot}</div>' if plot else ''}
+  {f'<div class="card"><h3>Data points ({n_pts})</h3>{points_tbl}</div>' if points_tbl else ''}
+  {f'<div class="card">{curves_info}</div>' if curves_info else ''}
+  <div class="foot">Generated by pydfig — exact data decoded losslessly from the figure file.</div>
+</div>
+</body>
+</html>"""
+
+
+def write_html(payload, path):
+    """Write the HTML rendering of *payload* to *path*."""
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(render_html(payload))
+    return path

pydfig/matplotlib_converter.py

@@ -0,0 +1,213 @@
+"""
+pydfig.matplotlib_converter — export a matplotlib Figure as a pydfig figure.
+
+Extract exact data from matplotlib Axes and embed it into a pydfig SVG or PNG.
+No matplotlib import at module level — only needed when user calls convert().
+
+Usage:
+    import matplotlib.pyplot as plt
+    from pydfig.matplotlib_converter import convert
+
+    fig, ax = plt.subplots()
+    ax.plot([1, 2, 3], [4, 5, 6])
+    convert(fig, "output.svg", caption="My experiment")
+    convert(fig, "output.png", caption="My experiment")
+"""
+
+import math
+import os
+from .encoder import metadata_block, inject_png_ddat
+
+SVG_NS = "http://www.w3.org/2000/svg"
+
+
+def _with_correct_ext(output_path, fmt):
+    """Ensure the output path carries the extension matching the chosen format."""
+    base, _ = os.path.splitext(output_path)
+    return base + (".png" if fmt == "png" else ".svg")
+
+
+def _extract_points(ax):
+    """Extract scatter/line data points from a matplotlib Axes."""
+    points = []
+    curves = []
+    for line in ax.get_lines():
+        xdata = list(line.get_xdata())
+        ydata = list(line.get_ydata())
+        label = line.get_label() if line.get_label() else None
+        clean = [(x, y) for x, y in zip(xdata, ydata)
+                 if x is not None and y is not None
+                 and not (isinstance(x, float) and math.isnan(x))]
+        if not clean:
+            continue
+        xs = [float(x) for x, _ in clean]
+        ys = [float(y) for _, y in clean]
+        linestyle = line.get_linestyle()
+        if linestyle in (None, "", " ", "None", "none"):
+            for x, y in clean:
+                points.append({"x": float(x), "y": float(y)})
+        else:
+            curve = {"x": xs, "y": ys}
+            if label:
+                curve["label"] = label
+            curves.append(curve)
+    for coll in ax.collections:
+        try:
+            offsets = coll.get_offsets()
+            for i in range(len(offsets)):
+                x, y = offsets[i][0], offsets[i][1]
+                if not (isinstance(x, float) and math.isnan(x)):
+                    points.append({"x": float(x), "y": float(y)})
+        except Exception:
+            pass
+    return points, curves
+
+
+def _extract_axes(ax):
+    """Extract axis metadata."""
+    xlabel = ax.get_xlabel()
+    ylabel = ax.get_ylabel()
+    title = ax.get_title()
+    xlim = ax.get_xlim()
+    ylim = ax.get_ylim()
+
+    axes = {}
+    if xlabel:
+        axes["x"] = {"label": xlabel, "range": [float(xlim[0]), float(xlim[1])]}
+    if ylabel:
+        axes["y"] = {"label": ylabel, "range": [float(ylim[0]), float(ylim[1])]}
+    if ax.get_xscale() == "log":
+        axes.setdefault("x", {})["scale"] = "log"
+    if ax.get_yscale() == "log":
+        axes.setdefault("y", {})["scale"] = "log"
+
+    info = {}
+    if title:
+        info["title"] = title
+    return axes, info
+
+
+def _guess_figure_type(ax):
+    """Heuristic: guess the scientific figure type from axis labels."""
+    xl = (ax.get_xlabel() or "").lower()
+    yl = (ax.get_ylabel() or "").lower()
+    combined = f"{xl} {yl}"
+    if "2theta" in combined or "xrd" in combined or "diffraction" in combined:
+        return "xrd"
+    if "wavenumber" in combined or "ftir" in combined:
+        return "ftir"
+    if "wavelength" in combined and ("absorbance" in combined or "intensity" in combined):
+        return "uvvis"
+    if "binding energy" in combined or "xps" in combined:
+        return "xps"
+    if "temperature" in combined and ("weight" in combined or "deriv" in combined):
+        return "tga"
+    if "potential" in combined and ("current" in combined or "current density" in combined):
+        if "cycle" in combined or "cv" in combined:
+            return "cv"
+        return "tafel"
+    if "frequency" in combined and ("impedance" in combined or "z" in combined):
+        return "nyquist"
+    if "overpotential" in combined or "volcano" in combined:
+        return "volcano"
+    if "rdf" in combined or "radial distribution" in combined:
+        return "rdf"
+    if "dos" in combined or "density of states" in combined:
+        return "dos"
+    if "band" in combined and ("energy" in combined or "k-path" in combined):
+        return "band_structure"
+    if "p/p0" in combined or "bet" in combined or ("relative pressure" in combined):
+        return "bet"
+    if "heat flow" in combined or "dsc" in combined:
+        return "dsc"
+    if "1000/t" in combined or "ln(k)" in combined or "arrhenius" in combined:
+        return "arrhenius"
+    return "scatter_generic"
+
+
+def convert(fig, output_path, caption=None, figure_type=None, provenance=None,
+            width=680, height=480, fmt=None):
+    """
+    Convert a matplotlib Figure to a pydfig self-describing figure.
+
+    The SAME payload (exact points/curves/axes) is embedded regardless of the
+    container format; only the carrier differs:
+
+      * fmt="svg" (default) -> SVG file, payload inside the <metadata> element
+      * fmt="png"           -> PNG file, payload inside a `dDat` private chunk
+
+    Parameters:
+        fig: matplotlib.figure.Figure
+        output_path: str — output path (extension is auto-fixed to match fmt)
+        caption: str — figure caption (optional)
+        figure_type: str — override the auto-detected figure type (optional)
+        provenance: dict — {tool, version, date, doi, ...} (optional)
+        width: int — SVG width in px (ignored for PNG)
+        height: int — SVG height in px (ignored for PNG)
+        fmt: str — "svg" (default) or "png". If None, inferred from the
+              output_path extension (.png -> png, otherwise svg).
+
+    Returns:
+        dict — the embedded payload
+    """
+    ext = os.path.splitext(output_path)[1].lower()
+    if fmt is None:
+        fmt = "png" if ext == ".png" else "svg"
+    else:
+        fmt = fmt.lower()
+    if fmt not in ("svg", "png"):
+        raise ValueError("fmt must be 'svg' or 'png'")
+    out_path = _with_correct_ext(output_path, fmt)
+
+    axes_list = fig.get_axes()
+    if not axes_list:
+        raise ValueError("Figure has no axes")
+    ax = axes_list[0]
+
+    points, curves = _extract_points(ax)
+    axes_info, extra_info = _extract_axes(ax)
+    ftype = figure_type or _guess_figure_type(ax)
+
+    payload = {
+        "format": "pydfig",
+        "version": "2.0",
+        "figure_type": ftype,
+        "caption": caption or "",
+        "axes": axes_info,
+        "points": points,
+        "curves": curves,
+    }
+    if provenance:
+        payload["provenance"] = provenance
+    if extra_info:
+        payload["extra"] = extra_info
+
+    if fmt == "svg":
+        import io
+        import re
+        buf = io.StringIO()
+        fig.savefig(buf, format="svg", bbox_inches="tight")
+        svg_text = buf.getvalue()
+        meta = metadata_block(payload)
+        m = re.search(r"<svg\b[^>]*>", svg_text)
+        if m:
+            insert_pos = m.end()
+            svg_text = svg_text[:insert_pos] + meta + svg_text[insert_pos:]
+        with open(out_path, "w", encoding="utf-8") as f:
+            f.write(svg_text)
+    else:  # png
+        import io
+        buf = io.BytesIO()
+        fig.savefig(buf, format="png", dpi=150, bbox_inches="tight")
+        png_bytes = buf.getvalue()
+        pydfig_png = inject_png_ddat(png_bytes, payload)
+        with open(out_path, "wb") as f:
+            f.write(pydfig_png)
+
+    return payload
+
+
+def quick_convert(output_path, **kwargs):
+    """Convert the current matplotlib figure (plt.gcf()) to pydfig."""
+    import matplotlib.pyplot as plt
+    return convert(plt.gcf(), output_path, **kwargs)

pydfig-0.1.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: pydfig
+Version: 0.1.0
+Summary: Self-describing scientific figures (Figure-as-Data): embed exact data in SVG/PNG, decode losslessly to JSON (for AI) and HTML (for humans).
+Author-email: Fenglong Li <15340666394@163.com>, Siyang Li <15340666394@163.com>
+License: MIT
+Project-URL: Homepage, https://pydfig.ai4c/schema
+Keywords: scientific figures,Figure-as-Data,FAIR data,machine-readable,AI4Science,SVG,PNG,metadata
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: matplotlib
+Requires-Dist: matplotlib; extra == "matplotlib"
+Dynamic: license-file
+
+# pydfig — Make your scientific figures carry their own data
+
+A normal chart is just a **picture**. **pydfig** makes the same chart also
+**contain its exact numbers** — so a computer can read them back perfectly,
+without guessing from pixels (no OCR, no digitizing error).
+
+> One sentence: pydfig hides a small JSON with your exact data *inside* the
+> image file. The picture still looks identical; a parser reads the JSON back
+> losslessly.
+
+## Why does this matter?
+
+Scientific figures in papers and PDFs are images. If an AI agent — or a
+colleague — wants the real data points, they usually have to scrape the PDF
+or eyeball the pixels, and both lose precision. pydfig embeds the **exact
+data** inside the figure file itself, invisibly.
+
+## How it works
+
+| Carrier | Where the data lives | Still a normal file? |
+|---------|----------------------|----------------------|
+| **SVG** | the standard `<metadata>` element (renderers ignore it) | ✅ opens in any SVG viewer |
+| **PNG** | a legal private chunk called `dDat` | ✅ opens in any image viewer |
+
+## Two things pydfig does
+
+1. **Encode** — export a PNG or SVG that carries your exact data (from a
+   `payload` dict, or directly from a matplotlib figure).
+2. **Decode** — read a pydfig PNG/SVG and write out:
+   - a **`.json`** file — machine-readable, for AI / data pipelines
+   - an **`.html`** file — human-readable, opens in any browser and shows the
+     data plus a reconstructed plot
+
+## Install
+
+```bash
+pip install pydfig
+# optional: to export directly from a matplotlib figure
+pip install "pydfig[matplotlib]"
+```
+
+The core encode/decode path is **pure Python standard library** — no heavy
+dependencies required.
+
+## Quick start
+
+### Command line
+
+```bash
+# Encode: inject a data JSON into an existing SVG or PNG
+python -m pydfig encode chart.png --payload payload.json -o chart_pydfig.png
+
+# Decode: get back JSON (for AI) + HTML (for humans)
+python -m pydfig decode chart_pydfig.png -o result
+#   result.json  <- exact data, machine-readable
+#   result.html  <- open in a browser to see the data and a reconstructed chart
+```
+
+### In Python
+
+```python
+from pydfig import build_payload, embed_in_svg, inject_png_ddat, decode_any
+
+payload = build_payload(
+    "scatter",
+    points=[{"x": -1.95, "y": 0.42, "material": "NiO"}],
+    axes={"x": {"label": "d-band", "unit": "eV"}},
+    caption="My figure",
+)
+
+svg = embed_in_svg(open("chart.svg").read(), payload)        # data in <metadata>
+png = inject_png_ddat(open("chart.png", "rb").read(), payload)  # data in dDat chunk
+
+data = decode_any("chart_pydfig.png")   # exact, lossless
+```
+
+### From a matplotlib figure (needs the `matplotlib` extra)
+
+```python
+import matplotlib.pyplot as plt
+from pydfig.matplotlib_converter import convert
+
+fig, ax = plt.subplots()
+ax.plot([1, 2, 3], [4, 5, 6])
+ax.set_xlabel("d-band (eV)")
+ax.set_ylabel("E_ads (eV)")
+
+convert(fig, "out.svg", caption="experiment")   # -> out.svg
+convert(fig, "out.png", caption="experiment")   # -> out.png
+```
+
+`convert()` chooses PNG vs SVG automatically from the output file extension.
+
+### Decode to a readable HTML page
+
+```python
+from pydfig import decode_any, write_html
+
+payload = decode_any("out.png")
+write_html(payload, "out.html")   # self-contained, light-theme viewer
+```
+
+## What the embedded data looks like
+
+```json
+{
+  "format": "pydfig",
+  "version": "2.0",
+  "figure_type": "xrd",
+  "caption": "XRD pattern",
+  "axes": {"x": {"label": "2θ", "unit": "degree"}, "y": {"label": "Intensity"}},
+  "points": [{"x": 44.0, "y": 20.0}, {"x": 64.0, "y": 12.0}],
+  "curves": [{"x": [0, 1, 2], "y": [10, 12, 11], "label": "intensity"}]
+}
+```
+
+## Examples
+
+The `examples/` folder ships `demo_volcano`, `demo_xrd`, and `demo_dband` as
+both `.svg` and `.png` — each carrying its exact data. Regenerate them with:
+
+```bash
+python examples/gen_examples.py
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pydfig-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pydfig/__init__.py,sha256=PxMMasCv-4PTFJC1wBVSFNd48SLdVGlR2iykxsXJw-s,1284
+pydfig/__main__.py,sha256=8CmTEo6ZGNOzmYks62vytUz4emqnOQM8SgX_dCtTyxI,122
+pydfig/cli.py,sha256=ekDqrwhSZA45N3yPX9xRfRlLp-8BfZN-iX55Wz9QH5w,3329
+pydfig/decoder.py,sha256=MDA2-w3umHH9O45X2vP62iO-C5-RMf1m04lCxXvRj5A,3429
+pydfig/encoder.py,sha256=qxUAXc0P3LBnTjpUZD5t1OrAFFOqUAAafZaKlXhV3uQ,3696
+pydfig/html.py,sha256=0yd-CpoDlDKZY_HhkKgGp8itMm-dVhY2kq4agIa5XRk,7826
+pydfig/matplotlib_converter.py,sha256=UjzQh-8ZbdvVK8q6MC7dRASC7dbW13f0nUuyL1Bsg7k,7519
+pydfig-0.1.0.dist-info/licenses/LICENSE,sha256=e2gyWjB9IrhELWVNco6He1qbuAnXI5qrWJEuA2vNvyY,1079
+pydfig-0.1.0.dist-info/METADATA,sha256=wP1Y3r36yUZ5A0nc6j6hKqKcKzcHWV0w0UX7_kdJ6Es,5099
+pydfig-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pydfig-0.1.0.dist-info/entry_points.txt,sha256=C0URwJBmiO3UBePuHLAQUVrwTTe-9xm1VUI5jNAaf2o,43
+pydfig-0.1.0.dist-info/top_level.txt,sha256=Mo4caJpo1qp8Obh2_ojP1x5-WDl8MxQ1jkfqU97hOpw,7
+pydfig-0.1.0.dist-info/RECORD,,

pydfig-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pydfig-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pydfig = pydfig.cli:main

pydfig-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fenglong Li, Siyang Li
+
+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.

pydfig-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pydfig