rmink 2.0.0__py3-none-any.whl

rmink/api.py

@@ -0,0 +1,258 @@
+"""Public entry point: inputs -> ``.rmdoc``. The CLI, MCP server and web UI are
+thin wrappers around :func:`convert`."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from uuid import UUID
+
+from PIL import Image
+
+from rmink.devices import MONO_PALETTE, DeviceProfile, get_device
+from rmink.extract.raster import extract_raster
+from rmink.extract.vector import extract_vector
+from rmink.geometry.order import enforce_budget, reading_order
+from rmink.geometry.transform import Fit, place
+from rmink.ingest import RasterSource, Source, VectorSource, load
+from rmink.model import Document, Page
+from rmink.options import ConvertOptions, ConvertResult, Mode, PageStats
+from rmink.package.rmdoc import RmdocPage, UuidFactory, write_rmdoc
+from rmink.render.preview import contact_sheet, render_rm, thumbnail_png
+from rmink.writer.rm_v6 import write_page
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class Rendered:
+    """A converted document before packaging."""
+
+    document: Document
+    labels: list[str]
+    rm_pages: list[bytes]
+    images: list[Image.Image]
+    warnings: list[str]
+    device: DeviceProfile
+    uuids: UuidFactory
+    author: UUID  # must match .content cPages.uuids[0].first
+
+
+def _palette(device: DeviceProfile, colors: str):
+    if colors == "mono":
+        return MONO_PALETTE[:1], None
+    clusters = int(colors) if colors.isdigit() else None
+    return device.palette, clusters
+
+
+def source_to_page(src: Source, device: DeviceProfile, opts: ConvertOptions) -> Page:
+    palette, clusters = _palette(device, opts.colors)
+    if isinstance(src, VectorSource):
+        placement = place(
+            src.width,
+            src.height,
+            device,
+            opts.fit,
+            opts.margin_mm,
+            physical_px_per_unit=src.px_per_unit_at_dpi * device.dpi,
+        )
+        strokes = extract_vector(src, placement, device, palette, opts)
+    else:
+        h, w = src.image.shape[:2]
+        true_size = device.dpi / src.dpi if src.dpi else 1.0
+        placement = place(w, h, device, opts.fit, opts.margin_mm, physical_px_per_unit=true_size)
+        # Photographed black ink reads as grey; gray is only offered when it is
+        # an exact source colour (vectors).
+        raster_palette = tuple(e for e in palette if e.name != "gray") or palette
+        strokes = extract_raster(src, placement, device, raster_palette, clusters, opts)
+
+    strokes = enforce_budget(reading_order(strokes), opts.max_points, opts.simplify)
+    return Page(device.width, placement.page_height, strokes)
+
+
+def render(inputs: list[Path], opts: ConvertOptions) -> Rendered:
+    device = get_device(opts.device)
+    if opts.mode == Mode.vector and any(p.suffix.lower() not in (".pdf", ".svg") for p in inputs):
+        raise ValueError("--mode vector only works for PDF and SVG inputs")
+
+    sources: list[Source] = []
+    for path in inputs:
+        if not path.is_file():
+            raise FileNotFoundError(path)
+        sources.extend(load(path, opts.mode.value, opts.pages))
+    if not sources:
+        raise ValueError("No pages to convert")
+
+    warnings = [w for s in sources for w in s.warnings]
+    if not device.verified:
+        warnings.append(
+            f"{device.name}: coordinate scale is not yet verified on hardware; "
+            "print `rmink calibrate` and check the ruler."
+        )
+
+    uuids = UuidFactory(opts.seed)
+    author = uuids()
+    doc = Document(name=opts.name or inputs[0].stem)
+    rm_pages, images, labels = [], [], []
+    for src in sources:
+        log.info("Converting %s", src.label)
+        page = source_to_page(src, device, opts)
+        if not page.strokes:
+            warnings.append(f"{src.label}: no ink found")
+        data = write_page(page, device, author)
+        doc.pages.append(page)
+        rm_pages.append(data)
+        images.append(render_rm(data, device, page.height))
+        labels.append(src.label)
+        if isinstance(src, RasterSource) and opts.fit == Fit.none and not src.dpi:
+            warnings.append(f"{src.label}: image has no DPI; assumed 1 px = 1 device px")
+    return Rendered(doc, labels, rm_pages, images, warnings, device, uuids, author)
+
+
+def convert(
+    inputs: list[Path],
+    output: Path | None = None,
+    opts: ConvertOptions | None = None,
+    preview: Path | None = None,
+) -> ConvertResult:
+    opts = opts or ConvertOptions()
+    inputs = [Path(p) for p in inputs]
+    rendered = render(inputs, opts)
+    name = rendered.document.name
+    output = Path(output) if output else inputs[0].with_name(f"{inputs[0].stem}.rmdoc")
+    if output.suffix.lower() != ".rmdoc":
+        output = output.with_suffix(".rmdoc")
+
+    doc_id = str(rendered.uuids())
+    page_ids = [str(rendered.uuids()) for _ in rendered.rm_pages]
+    pages = [
+        RmdocPage(data, thumbnail_png(img))
+        for data, img in zip(rendered.rm_pages, rendered.images, strict=True)
+    ]
+    result = write_rmdoc(
+        output,
+        name,
+        pages,
+        page_ids,
+        rendered.author,
+        rendered.device,
+        doc_id,
+        compress=opts.compress,
+        now_ms=0 if opts.seed is not None else None,
+    )
+
+    if preview is not None:
+        save_preview(rendered.images, Path(preview))
+
+    return ConvertResult(
+        path=result.path,
+        name=name,
+        device=rendered.device.key,
+        size_bytes=result.size_bytes,
+        pages=[
+            PageStats(label=lbl, strokes=len(p.strokes), points=p.point_count, height_px=p.height)
+            for lbl, p in zip(rendered.labels, rendered.document.pages, strict=True)
+        ],
+        warnings=rendered.warnings + result.warnings,
+        preview_path=Path(preview) if preview else None,
+    )
+
+
+def save_preview(images: list[Image.Image], path: Path) -> Path:
+    img = images[0] if len(images) == 1 else contact_sheet(images)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    img.save(path)
+    return path
+
+
+def calibration_page(device: DeviceProfile) -> Page:
+    """A page with millimetre rulers along two edges and a 50 mm square, for
+    checking the coordinate scale on real hardware."""
+    from rmink.model import Stroke
+
+    mm = device.px_per_mm
+    x0, y0 = 10 * mm, 10 * mm
+    strokes = []
+    length_x = int((device.width - 2 * x0) / mm)
+    length_y = int((device.height - 2 * y0) / mm)
+    strokes.append(Stroke([[x0, y0], [x0 + length_x * mm, y0]], width=2))
+    strokes.append(Stroke([[x0, y0], [x0, y0 + length_y * mm]], width=2))
+    for i in range(length_x + 1):
+        tick = 6 if i % 10 == 0 else (4 if i % 5 == 0 else 2)
+        strokes.append(Stroke([[x0 + i * mm, y0], [x0 + i * mm, y0 + tick * mm]], width=1.5))
+    for i in range(length_y + 1):
+        tick = 6 if i % 10 == 0 else (4 if i % 5 == 0 else 2)
+        strokes.append(Stroke([[x0, y0 + i * mm], [x0 + tick * mm, y0 + i * mm]], width=1.5))
+    cx, cy, s = device.width / 2, device.height / 2, 25 * mm
+    corners = [(-1, -1), (1, -1), (1, 1), (-1, 1), (-1, -1)]
+    strokes.append(Stroke([[cx + dx * s, cy + dy * s] for dx, dy in corners], width=3))
+    return Page(device.width, device.height, strokes)
+
+
+def calibration_sheet(device_key: str, output: Path, seed: int | None = None) -> Path:
+    device = get_device(device_key)
+    uuids = UuidFactory(seed)
+    author = uuids()
+    page = calibration_page(device)
+    data = write_page(page, device, author)
+    image = render_rm(data, device)
+    write_rmdoc(
+        Path(output),
+        f"rmink calibration ({device.key})",
+        [RmdocPage(data, thumbnail_png(image))],
+        [str(uuids())],
+        author,
+        device,
+        str(uuids()),
+    )
+    return Path(output)
+
+
+def inspect(path: Path) -> dict:
+    """Summarise a ``.rmdoc`` archive or a single ``.rm`` page."""
+    import json
+    import zipfile
+    from collections import Counter
+
+    from rmink.render.preview import read_lines
+
+    def page_summary(name: str, data: bytes) -> dict:
+        header = data[:43].decode("ascii", "replace").strip()
+        lines = read_lines(data) if "version=6" in header else []
+        return {
+            "page": name,
+            "header": header,
+            "strokes": len(lines),
+            "points": sum(len(ln.points) for ln in lines),
+            "pens": dict(Counter(ln.tool.name for ln in lines)),
+            "colors": dict(Counter(ln.color.name for ln in lines)),
+            "bytes": len(data),
+        }
+
+    path = Path(path)
+    if path.suffix.lower() == ".rm":
+        return {"file": str(path), "pages": [page_summary(path.name, path.read_bytes())]}
+
+    with zipfile.ZipFile(path) as zf:
+        names = zf.namelist()
+        content_name = next(n for n in names if n.endswith(".content"))
+        meta_name = next((n for n in names if n.endswith(".metadata")), None)
+        content = json.loads(zf.read(content_name))
+        doc_id = content_name.removesuffix(".content")
+        pages = content.get("cPages", {}).get("pages") or [
+            {"id": pid} for pid in content.get("pages", [])
+        ]
+        summaries = []
+        for p in pages:
+            rm_name = f"{doc_id}/{p['id']}.rm"
+            if rm_name in names:
+                summaries.append(page_summary(p["id"], zf.read(rm_name)))
+        meta = json.loads(zf.read(meta_name)) if meta_name else {}
+    return {
+        "file": str(path),
+        "name": meta.get("visibleName"),
+        "size_bytes": path.stat().st_size,
+        "page_count": len(pages),
+        "pages": summaries,
+    }

rmink/cli.py

@@ -0,0 +1,193 @@
+"""Command line interface: ``rmink convert|preview|inspect|devices|calibrate|mcp``."""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from rmink import api
+from rmink.devices import all_devices
+from rmink.geometry.transform import Fit
+from rmink.options import ConvertOptions, FillMode, Mode, PenChoice
+from rmink.support import support_url
+
+app = typer.Typer(
+    help="Convert images, photos, SVGs and PDFs into native, editable reMarkable ink.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+Inputs = Annotated[list[Path], typer.Argument(help="PDF, SVG or image files", exists=True)]
+Device = Annotated[str, typer.Option("--device", "-d", help="rm2 | pure | pro | move")]
+ModeOpt = Annotated[Mode, typer.Option(help="How ink is extracted")]
+Colors = Annotated[str, typer.Option(help="auto | mono | number of colour clusters")]
+PenOpt = Annotated[PenChoice, typer.Option(help="Tablet pen used for the strokes")]
+Width = Annotated[float, typer.Option(help="Outline/hatch pen width in device px")]
+FillOpt = Annotated[FillMode, typer.Option(help="How filled areas are drawn")]
+FitOpt = Annotated[Fit, typer.Option(help="page: fit page | width: fit width | none: true size")]
+Margin = Annotated[float, typer.Option(help="Page margin in mm")]
+Threshold = Annotated[str, typer.Option(help="auto or a 0-255 ink threshold for rasters")]
+Simplify = Annotated[float, typer.Option(help="Simplification tolerance in device px")]
+ThickPx = Annotated[float, typer.Option(help="Raster ink wider than this is outlined")]
+MaxPoints = Annotated[int, typer.Option(help="Point budget per page")]
+Pages = Annotated[str | None, typer.Option(help="PDF pages, e.g. 1-3,7")]
+Seed = Annotated[int | None, typer.Option(help="Deterministic UUIDs (for tests)")]
+Verbose = Annotated[bool, typer.Option("--verbose", "-v")]
+
+
+def _setup_logging(verbose: bool) -> None:
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.WARNING, format="%(levelname)s %(message)s"
+    )
+
+
+def _options(**kw) -> ConvertOptions:
+    return ConvertOptions(**{k: v for k, v in kw.items() if v is not None})
+
+
+@app.command()
+def convert(
+    inputs: Inputs,
+    output: Annotated[Path | None, typer.Option("--output", "-o", help="Output .rmdoc")] = None,
+    name: Annotated[str | None, typer.Option(help="Notebook name on the tablet")] = None,
+    device: Device = "rm2",
+    mode: ModeOpt = Mode.auto,
+    colors: Colors = "auto",
+    pen: PenOpt = PenChoice.fineliner,
+    width: Width = 2.0,
+    fill: FillOpt = FillMode.hatch,
+    fit: FitOpt = Fit.page,
+    margin: Margin = 5.0,
+    threshold: Threshold = "auto",
+    simplify: Simplify = 0.6,
+    thick_px: ThickPx = 9.0,
+    max_points: MaxPoints = 150_000,
+    pages: Pages = None,
+    preview: Annotated[Path | None, typer.Option(help="Also write a PNG preview")] = None,
+    compress: Annotated[bool, typer.Option(help="Deflate the archive")] = False,
+    seed: Seed = None,
+    verbose: Verbose = False,
+) -> None:
+    """Convert inputs into one .rmdoc notebook (one page per image / PDF page)."""
+    _setup_logging(verbose)
+    opts = _options(
+        device=device, mode=mode, colors=colors, pen=pen, width=width, fill=fill, fit=fit,
+        margin_mm=margin, threshold=threshold, simplify=simplify, thick_px=thick_px,
+        max_points=max_points, pages=pages, name=name, compress=compress, seed=seed,
+    )  # fmt: skip
+    try:
+        result = api.convert(inputs, output, opts, preview=preview)
+    except (ValueError, FileNotFoundError, RuntimeError) as e:
+        typer.secho(f"error: {e}", fg="red", err=True)
+        raise typer.Exit(1) from e
+    for w in result.warnings:
+        typer.secho(f"warning: {w}", fg="yellow", err=True)
+    total = sum(p.strokes for p in result.pages)
+    typer.echo(
+        f"{result.path}  ({len(result.pages)} pages, {total} strokes, "
+        f"{result.size_bytes / 1000:.0f} kB, {result.device})"
+    )
+    if result.preview_path:
+        typer.echo(f"preview: {result.preview_path}")
+
+
+@app.command()
+def preview(
+    inputs: Inputs,
+    output: Annotated[Path, typer.Option("--output", "-o")] = Path("preview.png"),
+    device: Device = "rm2",
+    mode: ModeOpt = Mode.auto,
+    colors: Colors = "auto",
+    width: Width = 2.0,
+    fill: FillOpt = FillMode.hatch,
+    fit: FitOpt = Fit.page,
+    threshold: Threshold = "auto",
+    simplify: Simplify = 0.6,
+    pages: Pages = None,
+    verbose: Verbose = False,
+) -> None:
+    """Render what the converted ink will look like, without writing a notebook."""
+    _setup_logging(verbose)
+    opts = _options(
+        device=device, mode=mode, colors=colors, width=width, fill=fill, fit=fit,
+        threshold=threshold, simplify=simplify, pages=pages,
+    )  # fmt: skip
+    rendered = api.render(inputs, opts)
+    api.save_preview(rendered.images, output)
+    for w in rendered.warnings:
+        typer.secho(f"warning: {w}", fg="yellow", err=True)
+    typer.echo(str(output))
+
+
+@app.command()
+def inspect(path: Annotated[Path, typer.Argument(exists=True)]) -> None:
+    """Show pages, strokes, pens and colours of a .rmdoc or .rm file."""
+    typer.echo(json.dumps(api.inspect(path), indent=2))
+
+
+@app.command()
+def devices() -> None:
+    """List device profiles."""
+    for d in all_devices().values():
+        status = "verified" if d.verified else "beta"
+        colour = "colour" if d.color else "mono"
+        typer.echo(f"{d.key:6} {d.name:28} {d.width}x{d.height} {d.dpi:g} dpi {colour:6} {status}")
+
+
+@app.command()
+def calibrate(
+    device: Device = "rm2",
+    output: Annotated[Path, typer.Option("--output", "-o")] = Path("rmink-calibration.rmdoc"),
+) -> None:
+    """Write a ruler page; measure it on the tablet to verify the scale."""
+    path = api.calibration_sheet(device, output)
+    typer.echo(
+        f"{path}\nOpen it on the tablet: the long ticks are 10 mm apart and the square is "
+        "50 mm. If they are off, set ink_scale for this device in "
+        "~/.config/rmink/devices.toml."
+    )
+
+
+@app.command()
+def web(
+    host: Annotated[str, typer.Option(help="Interface to bind")] = "127.0.0.1",
+    port: Annotated[int, typer.Option(help="Port")] = 8765,
+    open_browser: Annotated[bool, typer.Option("--open/--no-open")] = True,
+) -> None:
+    """Start the web UI: drop files, preview the ink, download the notebook."""
+    try:
+        import uvicorn
+
+        from rmink.web import create_app
+    except ImportError as e:
+        typer.secho("The web UI needs: pip install 'rmink[web]'", fg="red", err=True)
+        raise typer.Exit(1) from e
+    url = f"http://{'localhost' if host in ('127.0.0.1', '0.0.0.0') else host}:{port}"
+    typer.echo(f"rmink web UI on {url}  (Ctrl+C to stop)")
+    if support := support_url():
+        typer.echo(f"rmink is free. If it is useful to you, you can support it: {support}")
+    if open_browser:
+        import threading
+        import webbrowser
+
+        threading.Timer(1.0, webbrowser.open, args=(url,)).start()
+    uvicorn.run(create_app(), host=host, port=port, log_level="warning")
+
+
+@app.command()
+def mcp() -> None:
+    """Run the MCP server on stdio (for Claude and other MCP clients)."""
+    try:
+        from rmink.mcp_server import main
+    except ImportError as e:
+        typer.secho("The MCP server needs: pip install 'rmink[mcp]'", fg="red", err=True)
+        raise typer.Exit(1) from e
+    main()
+
+
+if __name__ == "__main__":
+    app()

rmink/color/palette.py

@@ -0,0 +1,35 @@
+"""Mapping arbitrary colours to the device pen palette."""
+
+from __future__ import annotations
+
+import numpy as np
+from skimage.color import rgb2lab
+
+from rmink.devices import PaletteEntry
+
+# Colours lighter than this (CIE L*) with little chroma count as background.
+_WHITE_L = 92.0
+_WHITE_CHROMA = 12.0
+
+
+def to_lab(rgb: np.ndarray) -> np.ndarray:
+    arr = np.asarray(rgb, dtype=np.float64).reshape(-1, 1, 3) / 255.0
+    return rgb2lab(arr).reshape(-1, 3)
+
+
+def is_background(rgb: tuple[int, int, int]) -> bool:
+    L, a, b = to_lab(np.array(rgb))[0]
+    return L > _WHITE_L and np.hypot(a, b) < _WHITE_CHROMA
+
+
+def nearest(rgb: tuple[int, int, int], palette: tuple[PaletteEntry, ...]) -> PaletteEntry:
+    return palette[int(nearest_indices(np.array([rgb]), palette)[0])]
+
+
+def nearest_indices(rgbs: np.ndarray, palette: tuple[PaletteEntry, ...]) -> np.ndarray:
+    lab = to_lab(rgbs)
+    pal = to_lab(np.array([e.rgb for e in palette]))
+    # Weight lightness less so dark saturated ink maps to its hue, not black.
+    w = np.array([0.6, 1.0, 1.0])
+    d = (((lab[:, None, :] - pal[None, :, :]) * w) ** 2).sum(axis=2)
+    return np.argmin(d, axis=1)

rmink/devices.py

@@ -0,0 +1,110 @@
+"""reMarkable device profiles.
+
+Coordinates in `.rm` v6 files are expressed in "scene units". On the
+reMarkable 2 one scene unit equals one screen pixel (226 DPI), with x measured
+from the horizontal centre of the page and y from the top. Other devices are
+believed to use the same unit with a larger page, but this is not documented;
+`ink_scale` (scene units per device pixel) lets a calibration correct it
+without a new release. Profiles can be overridden in
+``~/.config/rmink/devices.toml``::
+
+    [pro]
+    ink_scale = 0.987
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, replace
+from functools import cache
+from pathlib import Path
+
+from rmscene.scene_items import PenColor
+
+
+@dataclass(frozen=True)
+class PaletteEntry:
+    name: str
+    color: PenColor
+    rgb: tuple[int, int, int]
+
+
+MONO_PALETTE: tuple[PaletteEntry, ...] = (
+    PaletteEntry("black", PenColor.BLACK, (0, 0, 0)),
+    PaletteEntry("gray", PenColor.GRAY, (125, 125, 125)),
+)
+
+# Approximate on-screen colours of the Paper Pro (Gallery 3) pen palette.
+COLOR_PALETTE: tuple[PaletteEntry, ...] = MONO_PALETTE + (
+    PaletteEntry("blue", PenColor.BLUE, (40, 80, 200)),
+    PaletteEntry("red", PenColor.RED, (200, 40, 40)),
+    PaletteEntry("green", PenColor.GREEN, (40, 150, 60)),
+    PaletteEntry("yellow", PenColor.YELLOW, (240, 210, 40)),
+    PaletteEntry("pink", PenColor.PINK, (230, 110, 170)),
+    PaletteEntry("cyan", PenColor.CYAN, (60, 180, 220)),
+    PaletteEntry("magenta", PenColor.MAGENTA, (170, 70, 180)),
+)
+
+
+@dataclass(frozen=True)
+class DeviceProfile:
+    key: str
+    name: str
+    width: int  # portrait canvas, device px
+    height: int
+    dpi: float
+    color: bool
+    ink_scale: float = 1.0  # scene units per device px
+    paper_size: tuple[int, int] | None = None  # written to SceneInfo when set
+    verified: bool = False
+
+    @property
+    def palette(self) -> tuple[PaletteEntry, ...]:
+        return COLOR_PALETTE if self.color else MONO_PALETTE
+
+    @property
+    def px_per_mm(self) -> float:
+        return self.dpi / 25.4
+
+
+_BUILTIN: dict[str, DeviceProfile] = {
+    p.key: p
+    for p in (
+        DeviceProfile("rm2", "reMarkable 2", 1404, 1872, 226, False, verified=True),
+        DeviceProfile("pure", "reMarkable Paper Pure", 1404, 1872, 226, False),
+        DeviceProfile(
+            "pro", "reMarkable Paper Pro", 1620, 2160, 229, True, paper_size=(1620, 2160)
+        ),
+        DeviceProfile(
+            "move", "reMarkable Paper Pro Move", 954, 1696, 264, True, paper_size=(954, 1696)
+        ),
+    )
+}
+
+
+def _config_path() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config"
+    return Path(base) / "rmink" / "devices.toml"
+
+
+@cache
+def all_devices() -> dict[str, DeviceProfile]:
+    devices = dict(_BUILTIN)
+    path = _config_path()
+    if path.is_file():
+        overrides = tomllib.loads(path.read_text())
+        for key, values in overrides.items():
+            if key in devices:
+                devices[key] = replace(devices[key], **values)
+            else:
+                devices[key] = DeviceProfile(key=key, **values)
+    return devices
+
+
+def get_device(key: str) -> DeviceProfile:
+    try:
+        return all_devices()[key]
+    except KeyError:
+        known = ", ".join(all_devices())
+        raise ValueError(f"Unknown device {key!r}; choose one of: {known}") from None