plotline 0.1.0.dev0__cp311-abi3-win_amd64.whl

plotline/__init__.py

@@ -0,0 +1,30 @@
+"""plotline: turn images into drawings for pen plotters.
+
+The engine is the extension module ``plotline._core``. This package is the Python host around it:
+``Session`` for working with an image, the values it takes and gives, and the style registry.
+"""
+
+from plotline._core import describe, inks
+from plotline.registry import get_style, list_styles
+from plotline.session import RunHandle, Session
+from plotline.types import Cancelled, Canvas, Drawing, Frame, Pen, RunState, Speeds, Stats, Style
+
+__all__ = [
+    "Cancelled",
+    "Canvas",
+    "Drawing",
+    "Frame",
+    "Pen",
+    "RunHandle",
+    "RunState",
+    "Session",
+    "Speeds",
+    "Stats",
+    "Style",
+    "describe",
+    "get_style",
+    "inks",
+    "list_styles",
+]
+
+__version__ = "0.1.0.dev0"

plotline/_core.pyi

@@ -0,0 +1,58 @@
+"""Types for ``plotline._core``, the Rust engine built as an extension module (crates/py)."""
+
+from typing import Any, Literal
+
+import numpy as np
+from numpy.typing import NDArray
+
+_State = Literal["idle", "running", "done", "cancelled", "error"]
+
+class Run:
+    def next_frame(self) -> dict[str, Any] | None: ...
+    def cancel(self) -> None: ...
+    def state(self) -> _State: ...
+    def error(self) -> str | None: ...
+
+class Session:
+    def __init__(self, cache_bytes: int = 536870912) -> None: ...
+    def set_image_bytes(self, data: bytes) -> None: ...
+    def set_image(self, array: NDArray[np.float32]) -> None: ...
+    def image(self) -> NDArray[np.float32] | None: ...
+    def canvas(self) -> dict[str, Any]: ...
+    def set_canvas(self, canvas: dict[str, Any]) -> None: ...
+    def pens(self) -> list[dict[str, Any]]: ...
+    def set_pens(self, pens: list[dict[str, Any]]) -> None: ...
+    def style_name(self) -> str: ...
+    def set_style(self, name: str) -> None: ...
+    def settings(self) -> dict[str, Any]: ...
+    def update(self, stage: str, patch: dict[str, Any]) -> None: ...
+    def speeds(self) -> dict[str, float]: ...
+    def set_speeds(self, speeds: dict[str, float]) -> None: ...
+    def start(self) -> Run: ...
+    def state(self) -> _State: ...
+    def error(self) -> str | None: ...
+    def drawing(self) -> dict[str, Any] | None: ...
+    def svg(self) -> str | None: ...
+    def json(self) -> dict[str, Any] | None: ...
+    def stats(self) -> dict[str, Any] | None: ...
+    def analysis(self) -> dict[str, Any] | None: ...
+    def preview_png(
+        self,
+        width_px: int,
+        travel: bool,
+        source: bool,
+        region: tuple[float, float, float, float] | None = None,
+    ) -> bytes | None: ...
+    def preset(self) -> dict[str, Any]: ...
+    def load_preset(self, preset: dict[str, Any]) -> list[str]: ...
+    def cache_stats(self) -> dict[str, int]: ...
+    def clear_cache(self) -> None: ...
+
+def list_styles() -> list[dict[str, str]]: ...
+def describe(name: str) -> dict[str, Any]: ...
+def inks() -> dict[str, str]: ...
+def synthetic_gradient(w: int, h: int) -> NDArray[np.float32]: ...
+def synthetic_checkerboard(w: int, h: int, cells: int) -> NDArray[np.float32]: ...
+def synthetic_radial(w: int, h: int) -> NDArray[np.float32]: ...
+def synthetic_noise(w: int, h: int, seed: int) -> NDArray[np.float32]: ...
+def synthetic_flat(w: int, h: int, value: float) -> NDArray[np.float32]: ...

plotline/cli/main.py

@@ -0,0 +1,294 @@
+"""The command line interface: list the styles, describe one, analyse an image, run a style on it,
+and serve the web interface and the MCP server.
+
+``run`` sets a ``Session`` up from its options, runs the style and writes the outputs. ``analyse``
+prints the session's analysis of an image. ``styles`` and ``describe`` read the style registry.
+``gui`` serves the web bundle that a release wheel carries. ``mcp`` serves a session to an AI
+assistant on stdio. The work all happens in the session layer, so this module holds no algorithm
+code.
+"""
+
+import http.server
+import importlib.util
+import json
+import sys
+import webbrowser
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from dataclasses import replace
+from functools import partial
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import click
+
+from plotline import inks
+from plotline.registry import get_style, list_styles
+from plotline.session import Session
+from plotline.types import Pen
+
+
+def coerce(text: str) -> bool | int | float | str:
+    """Read a ``--set`` value: ``true`` and ``false`` as booleans, then an integer, then a
+    float, and anything else as the text itself. The engine checks the value against the setting."""
+    if text in ("true", "false"):
+        return text == "true"
+    for kind in (int, float):
+        try:
+            return kind(text)
+        except ValueError:
+            pass
+    return text
+
+
+def parse_set(value: str) -> tuple[str, str, bool | int | float | str]:
+    """Split ``STAGE.KEY=VALUE`` into ``(stage, key, value)``, with the value read by ``coerce``.
+
+    There must be exactly one ``.`` before the ``=`` and exactly one ``=``, and the stage and the
+    key must not be empty. Anything else raises ``click.BadParameter``.
+    """
+    target, equals, text = value.partition("=")
+    stage, _, key = target.partition(".")
+    if not (equals and stage and key) or "." in key or "=" in text:
+        raise click.BadParameter(f"{value!r} must look like STAGE.KEY=VALUE")
+    return stage, key, coerce(text)
+
+
+def parse_pen(value: str) -> Pen:
+    """Split ``NAME:WIDTH_MM:COLOR`` into a ``Pen``, as in ``Red 0.5:0.5:#ff0000``.
+
+    Only the last two colons separate the fields, so the name may hold colons and the colour keeps
+    its ``#``. The colour may also be the name of one of the ``inks()``, in any case. A wrong
+    shape or a width that is not a number raise ``click.BadParameter``; the engine checks the
+    width and colour when the session is given the pen.
+    """
+    parts = value.rsplit(":", 2)
+    if len(parts) != 3:
+        raise click.BadParameter(f"{value!r} must look like NAME:WIDTH_MM:COLOR")
+    name, width, color = parts
+    color = inks().get(color.lower(), color)
+    try:
+        return Pen(name, float(width), color)
+    except ValueError as error:
+        raise click.BadParameter(f"{value!r}: {error}") from error
+
+
+@contextmanager
+def _errors() -> Iterator[None]:
+    """Turn the errors that bad input causes in the session into a one-line CLI error. The engine
+    reports a refused value as ``ValueError``, and a file that cannot be read is an
+    ``OSError``."""
+    try:
+        yield
+    except (ValueError, OSError) as error:
+        raise click.ClickException(str(error)) from error
+
+
+@click.group()
+def main() -> None:
+    """Turn images into line art for pen plotters."""
+
+
+@main.command()
+def styles() -> None:
+    """List the styles that can be run."""
+    for style in list_styles():
+        click.echo(f"{style.name}  {style.label}  {style.description}")
+
+
+@main.command()
+@click.argument("style")
+@click.option("--json", "as_json", is_flag=True, help="Print the settings as JSON Schema.")
+def describe(style: str, as_json: bool) -> None:
+    """Show the stages of STYLE and the settings of each."""
+    with _errors():
+        schema = get_style(style).schema()
+    if as_json:
+        click.echo(json.dumps(schema, indent=2))
+        return
+    for i, stage in enumerate(schema["stages"]):
+        if i:
+            click.echo()
+        click.echo(f"{stage['name']} ({stage['label']})")
+        # A stage without settings has no properties in its schema.
+        for name, prop in stage["schema"].get("properties", {}).items():
+            fields = [name, prop.get("type", "any"), f"default {json.dumps(prop.get('default'))}"]
+            for word, key in (("min", "minimum"), ("max", "maximum")):
+                if key in prop:
+                    fields.append(f"{word} {prop[key]}")
+            fields.append(prop.get("description", ""))
+            click.echo("  " + "  ".join(fields))
+
+
+def page_options(command: Callable[..., Any]) -> Callable[..., Any]:
+    """Give ``command`` the options that set the page, which ``set_page`` then applies."""
+    for option in (
+        click.option(
+            "--fit",
+            type=click.Choice(["fit", "fill"]),
+            help="Keep the whole image on the page (fit) or fill the drawing area with it (fill).",
+        ),
+        click.option("--margin", type=float, metavar="MM", help="Margin around the drawing area."),
+        click.option("--height", type=float, metavar="MM", help="Page height."),
+        click.option("--width", type=float, metavar="MM", help="Page width."),
+    ):  # the last one applied is listed first
+        command = option(command)
+    return command
+
+
+def set_page(
+    session: Session,
+    width: float | None,
+    height: float | None,
+    margin: float | None,
+    fit: str | None,
+) -> None:
+    """Change the page of ``session`` by the options that were given; the rest stay as they are."""
+    page: dict[str, Any] = {
+        "width_mm": width,
+        "height_mm": height,
+        "margin_mm": margin,
+        "fit": fit,
+    }
+    changes = {key: value for key, value in page.items() if value is not None}
+    if changes:
+        session.set_canvas(replace(session.canvas, **changes))
+
+
+@main.command()
+@click.argument("image", type=click.Path())
+@page_options
+def analyse(
+    image: str, width: float | None, height: float | None, margin: float | None, fit: str | None
+) -> None:
+    """Print what IMAGE looks like and the changes that would suit it, as JSON."""
+    session = Session()
+    with _errors():
+        session.load_image(image)
+        set_page(session, width, height, margin, fit)
+        click.echo(json.dumps(session.analysis(), indent=2))
+
+
+@main.command()
+@click.argument("style")
+@click.argument("image", type=click.Path())
+@click.option("--out", required=True, type=click.Path(), help="Where to write the SVG.")
+@click.option("--json", "json_out", type=click.Path(), help="Also write the paths as JSON.")
+@click.option("--preview", type=click.Path(), help="Also write a PNG preview.")
+@page_options
+@click.option(
+    "--pen",
+    "pens",
+    multiple=True,
+    callback=lambda ctx, param, values: [parse_pen(v) for v in values],
+    metavar="NAME:WIDTH_MM:COLOR",
+    help=(
+        "A pen, such as 'Red:0.5:#ff0000' or 'Fine:0.3:blue'. The colour is #rrggbb or one of "
+        f"the inks {', '.join(inks())}. "
+        "Repeat the option to give more pens. By default only the first pen draws; "
+        "set split.mode to share the drawing between them."
+    ),
+)
+@click.option(
+    "--set",
+    "sets",
+    multiple=True,
+    callback=lambda ctx, param, values: [parse_set(v) for v in values],
+    metavar="STAGE.KEY=VALUE",
+    help="Change a setting, such as tone.resolution=500. Repeat for more. See 'describe'.",
+)
+@click.option("--preset", type=click.Path(), help="Start from a saved preset.")
+@click.option(
+    "--save-preset",
+    type=click.Path(),
+    help="Write the style, page, pens and settings used to a preset file.",
+)
+@click.option("--quiet", is_flag=True, help="Do not print progress.")
+def run(
+    style: str,
+    image: str,
+    out: str,
+    json_out: str | None,
+    preview: str | None,
+    width: float | None,
+    height: float | None,
+    margin: float | None,
+    fit: str | None,
+    pens: list[Pen],
+    sets: list[tuple[str, str, bool | int | float | str]],
+    preset: str | None,
+    save_preset: str | None,
+    quiet: bool,
+) -> None:
+    """Run STYLE on IMAGE and write the drawing as an SVG."""
+    session = Session(max_fps=4)
+    if not quiet:
+        session.subscribe(lambda frame: click.echo(f"{frame.stage}: {frame.label}", err=True))
+    with _errors():
+        session.load_image(image)
+        if preset is not None:
+            session.load_preset(preset)
+        # A preset of the same style keeps its settings, which set_style would reset.
+        if session.style.name != style:
+            session.set_style(style)
+        set_page(session, width, height, margin, fit)
+        if pens:
+            session.set_pens(pens)
+        for stage, key, value in sets:
+            session.update(stage, **{key: value})
+        session.run_blocking()
+        session.export_svg(out)
+        if json_out is not None:
+            session.export_json(json_out)
+        if preview is not None:
+            Path(preview).write_bytes(session.preview_png())
+        if save_preset is not None:
+            session.save_preset(save_preset)
+    stats = session.stats()
+    click.echo(
+        f"paths: {stats.path_count}  pen down: {stats.pen_down_mm:.1f} mm  "
+        f"pen up: {stats.pen_up_mm:.1f} mm  estimated: {stats.estimated_seconds:.1f} s"
+    )
+    if len(pens) > 1 and session.settings["split"]["mode"] == "one_pen":
+        click.echo(
+            "Pen use is set to one pen, so only the first pen draws. Add "
+            "--set split.mode=light_to_dark or --set split.mode=by_colour to use the others.",
+            err=True,
+        )
+
+
+@main.command()
+@click.option("--port", type=int, default=8765, show_default=True, help="Port to serve on.")
+def gui(port: int) -> None:
+    """Serve the web interface on this computer and open it in the browser."""
+    web = resources.files("plotline") / "web"
+    if not (web / "index.html").is_file():
+        message = "This build has no GUI bundle; install a release wheel or build the web app."
+        click.echo(message, err=True)
+        sys.exit(1)
+    handler = partial(http.server.SimpleHTTPRequestHandler, directory=str(web))
+    with _errors():  # most often the port is taken
+        server = http.server.ThreadingHTTPServer(("127.0.0.1", port), handler)
+    with server:
+        url = f"http://127.0.0.1:{server.server_address[1]}/"
+        click.echo(f"Serving the GUI at {url}; press Ctrl-C to stop.")
+        webbrowser.open(url)
+        try:
+            server.serve_forever()
+        except KeyboardInterrupt:
+            pass
+
+
+@main.command()
+def mcp() -> None:
+    """Serve the session to an AI assistant over MCP on stdio."""
+    # Asked first because the server imports other modules of the extra before the SDK; any other
+    # missing module is a bug, not a missing extra.
+    if importlib.util.find_spec("mcp") is None:
+        click.echo('The MCP server needs the mcp extra: pip install "plotline[mcp]"', err=True)
+        sys.exit(1)
+    # Imported here so the other commands do not load the SDK.
+    from plotline.mcp_server import build_server
+
+    build_server().run()