vaseweld 1.3.0__py3-none-any.whl

vaseweld/__init__.py

@@ -0,0 +1,5 @@
+"""Weld two G-code files sliced from the same plate at a chosen Z height."""
+
+__version__ = "1.3.0"
+
+__all__ = ["__version__"]

vaseweld/bgcode.py

@@ -0,0 +1,307 @@
+"""Read PrusaSlicer's binary G-code back into the text form the rest of vaseweld expects.
+
+Binarising a slice moves two things out of the G-code stream that vaseweld needs: the
+config block, which becomes a Slicer Metadata block, and the filament and time totals,
+which become a Print Metadata block. Without them the compatibility check has no fields
+to compare and the totals cannot be recomputed, so this puts both back where PrusaSlicer
+would have written them in a text file.
+
+The trailing comment on every command (``G28 ; home all axes``) is not recoverable. The
+binariser drops it, which is a good part of why the format is smaller.
+
+Format: https://github.com/prusa3d/libbgcode/blob/main/doc/specifications.md
+"""
+
+from __future__ import annotations
+
+import struct
+import zlib
+
+MAGIC = b"GCDE"
+
+_FILE_METADATA = 0
+_GCODE = 1
+_SLICER_METADATA = 2
+_PRINT_METADATA = 4
+_THUMBNAIL = 5
+
+_DEFLATE = 1
+_HEATSHRINK_11_4 = 2
+_HEATSHRINK_12_4 = 3
+
+_MEATPACK = 1
+_MEATPACK_COMMENTS = 2
+
+# The 16 characters MeatPack can pack two-to-a-byte. 0xF means "not packed, the real
+# byte follows"; 0xB is a space unless the no-spaces command swapped it for 'E'.
+_PACKED = "0123456789. \nGX"
+_SIGNAL = 0xFF
+_ENABLE_PACKING = 251
+_DISABLE_PACKING = 250
+_RESET_ALL = 249
+_ENABLE_NO_SPACES = 247
+_DISABLE_NO_SPACES = 246
+
+# G-line parameters, which the binariser is free to drop the space in front of.
+_PARAMETERS = frozenset("XYZEFIJRSGPWHCA")
+
+_CONFIG_MARKERS = {
+    "OrcaSlicer": ("; CONFIG_BLOCK_START", "; CONFIG_BLOCK_END"),
+    "BambuStudio": ("; CONFIG_BLOCK_START", "; CONFIG_BLOCK_END"),
+    "SuperSlicer": ("; SuperSlicer_config = begin", "; SuperSlicer_config = end"),
+}
+_DEFAULT_MARKERS = ("; prusaslicer_config = begin", "; prusaslicer_config = end")
+
+
+class BgcodeError(ValueError):
+    """The file claims to be binary G-code but cannot be read as one."""
+
+
+def is_bgcode(raw: bytes) -> bool:
+    return raw[:4] == MAGIC
+
+
+def heatshrink(data: bytes, window_bits: int, lookahead_bits: int, size: int) -> bytes:
+    """Decompress a heatshrink stream, stopping at ``size`` bytes.
+
+    Tokens are read most significant bit first: a 1 bit introduces an 8-bit literal, a 0
+    bit a backreference of ``window_bits`` index and ``lookahead_bits`` count, both stored
+    one less than their real value. The final byte is zero-padded, so the caller's
+    uncompressed size is what ends the stream rather than running out of bits.
+    """
+    out = bytearray()
+    append = out.append
+    acc = held = pos = 0
+    end_of_data = len(data)
+    # The widest token is the tag plus a whole backreference; refilling to that once
+    # per token keeps the bit twiddling out of a helper, which this loop runs millions
+    # of times on a real file.
+    wanted = 1 + max(8, window_bits + lookahead_bits)
+    index_mask = (1 << window_bits) - 1
+    count_mask = (1 << lookahead_bits) - 1
+
+    while len(out) < size:
+        while held < wanted and pos < end_of_data:
+            acc = (acc << 8) | data[pos]
+            pos += 1
+            held += 8
+        if held < 1:
+            break
+
+        held -= 1
+        literal = (acc >> held) & 1
+        acc &= (1 << held) - 1
+
+        if literal:
+            if held < 8:
+                break
+            held -= 8
+            append((acc >> held) & 0xFF)
+            acc &= (1 << held) - 1
+            continue
+
+        if held < window_bits + lookahead_bits:
+            break
+        held -= window_bits
+        index = (acc >> held) & index_mask
+        held -= lookahead_bits
+        count = ((acc >> held) & count_mask) + 1
+        acc &= (1 << held) - 1
+
+        start = len(out) - index - 1
+        if start < 0:
+            raise BgcodeError("backreference points before the start of the stream")
+        stop = start + count
+        if stop <= len(out):
+            out += out[start:stop]
+        else:
+            # The match runs into what it is producing, which is how a run of one
+            # repeated byte is stored. It has to be copied a byte at a time.
+            for i in range(start, stop):
+                append(out[i])
+
+    if len(out) < size:
+        raise BgcodeError(f"stream ended early, got {len(out)} of {size} bytes")
+    return bytes(out[:size])
+
+
+def meatpack(data: bytes, respace: bool) -> str:
+    """Unpack a MeatPack stream, optionally putting the G-line spaces back."""
+    chars: list[str] = []
+    packing = no_spaces = command = False
+    signals = pending = 0
+    held: str | None = None
+
+    def unpack(nibble: int) -> str:
+        return "E" if nibble == 0xB and no_spaces else _PACKED[nibble]
+
+    def receive(byte: int) -> None:
+        nonlocal pending, held
+        if not packing:
+            chars.append(chr(byte))
+            return
+        if pending:
+            # A full-width character owed from the previous byte. If its partner was
+            # packed it was decoded already and has been waiting for this one.
+            chars.append(chr(byte))
+            if held is not None:
+                chars.append(held)
+                held = None
+            pending -= 1
+            return
+        low, high = byte & 0xF, byte >> 4
+        if low == 0xF:
+            pending += 1
+            if high == 0xF:
+                pending += 1
+            else:
+                held = unpack(high)
+            return
+        first = unpack(low)
+        chars.append(first)
+        if first == "\n":
+            return
+        if high == 0xF:
+            pending += 1
+        else:
+            chars.append(unpack(high))
+
+    for byte in data:
+        if byte == _SIGNAL:
+            if signals:
+                command, signals = True, 0
+            else:
+                signals = 1
+            continue
+        if command:
+            if byte == _ENABLE_PACKING:
+                packing = True
+            elif byte in (_DISABLE_PACKING, _RESET_ALL):
+                packing = False
+            elif byte == _ENABLE_NO_SPACES:
+                no_spaces = True
+            elif byte == _DISABLE_NO_SPACES:
+                no_spaces = False
+            command = False
+            continue
+        if signals:
+            receive(_SIGNAL)
+            signals = 0
+        receive(byte)
+
+    return _respace(chars) if respace else "".join(chars)
+
+
+def _respace(chars: list[str]) -> str:
+    """Re-insert the spaces between G-line parameters that the binariser dropped."""
+    out: list[str] = []
+    spacing = False
+    for char in chars:
+        starts_line = not out or out[-1] == "\n"
+        opened = False
+        if char == "G" and starts_line:
+            spacing = opened = True
+        elif char == "\n":
+            spacing = False
+        if not opened and spacing and char in _PARAMETERS and (not out or out[-1] != " "):
+            out.append(" ")
+        if char != "\n" or not out or out[-1] != "\n":
+            out.append(char)
+    return "".join(out)
+
+
+def _blocks(raw: bytes):
+    """Yield ``(type, parameter, payload)`` for every block, decompressed."""
+    if len(raw) < 10:
+        raise BgcodeError("file is too short to hold a header")
+    magic, version, checksum = struct.unpack_from("<4sIH", raw, 0)
+    if magic != MAGIC:
+        raise BgcodeError("missing the GCDE magic number")
+    if version != 1:
+        raise BgcodeError(f"version {version} is not supported, only version 1 is")
+    if checksum > 1:
+        raise BgcodeError(f"unknown checksum type {checksum}")
+
+    at = 10
+    while at < len(raw):
+        try:
+            btype, compression = struct.unpack_from("<HH", raw, at)
+            at += 4
+            (size,) = struct.unpack_from("<I", raw, at)
+            at += 4
+            stored = size
+            if compression:
+                (stored,) = struct.unpack_from("<I", raw, at)
+                at += 4
+            if btype == _THUMBNAIL:
+                parameter = 0
+                at += 6
+            else:
+                (parameter,) = struct.unpack_from("<H", raw, at)
+                at += 2
+        except struct.error as exc:
+            raise BgcodeError("truncated block header") from exc
+
+        payload = raw[at : at + stored]
+        if len(payload) < stored:
+            raise BgcodeError("truncated block data")
+        at += stored + (4 if checksum else 0)
+
+        if btype == _THUMBNAIL:
+            continue
+        if compression == _DEFLATE:
+            try:
+                payload = zlib.decompress(payload)
+            except zlib.error as exc:
+                raise BgcodeError(f"deflate block would not decompress ({exc})") from exc
+        elif compression in (_HEATSHRINK_11_4, _HEATSHRINK_12_4):
+            window = 11 if compression == _HEATSHRINK_11_4 else 12
+            payload = heatshrink(payload, window, 4, size)
+        elif compression:
+            raise BgcodeError(f"unknown compression algorithm {compression}")
+        yield btype, parameter, payload
+
+
+def decode(raw: bytes) -> str:
+    """Turn binary G-code into the text file the same slice would have produced."""
+    gcode: list[str] = []
+    producer = ""
+    totals: list[str] = []
+    config: list[str] = []
+
+    for btype, parameter, payload in _blocks(raw):
+        if btype == _GCODE:
+            if parameter in (_MEATPACK, _MEATPACK_COMMENTS):
+                gcode.append(meatpack(payload, parameter == _MEATPACK_COMMENTS))
+            else:
+                gcode.append(payload.decode("utf-8", errors="replace"))
+            continue
+        text = payload.decode("utf-8", errors="replace")
+        if btype == _FILE_METADATA:
+            producer = _entries(text).get("Producer", "")
+        elif btype == _PRINT_METADATA:
+            totals = [f"; {key} = {value}" for key, value in _entries(text).items()]
+        elif btype == _SLICER_METADATA:
+            config = [f"; {key} = {value}" for key, value in _entries(text).items()]
+
+    if not gcode:
+        raise BgcodeError("no G-code blocks in the file")
+
+    lines = "".join(gcode).splitlines()
+    lines += totals
+    if config:
+        begin, end = _DEFAULT_MARKERS
+        for name, markers in _CONFIG_MARKERS.items():
+            if producer.startswith(name):
+                begin, end = markers
+        lines += ["", begin, *config, end]
+    return "\n".join(lines) + "\n"
+
+
+def _entries(text: str) -> dict[str, str]:
+    entries: dict[str, str] = {}
+    for line in text.splitlines():
+        key, sep, value = line.partition("=")
+        if sep:
+            entries[key.strip()] = value.strip()
+    return entries

vaseweld/cli.py

@@ -0,0 +1,286 @@
+"""Command line entry point for vaseweld."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+from .compat import CompatError, check_compatible
+from .parser import GcodeError, parse_file
+from .preview import write as write_preview
+from .validate import check as run_check
+from .weld import WeldError, weld
+
+EXIT_OK = 0
+EXIT_PROBLEMS = 1
+EXIT_USAGE = 2
+
+_EPILOG = r"""Slice the same plate twice, once with Spiral Vase off and once on, then:
+
+  vaseweld layers body.gcode
+  vaseweld weld --normal base.gcode --vase body.gcode --at 12.4 -o out.gcode
+  vaseweld check out.gcode
+  vaseweld preview out.gcode
+
+Repeat --at to alternate again, so a solid base, a vase body and a solid lid is:
+
+  vaseweld weld --normal base.gcode --vase body.gcode --at 12.4 --at 30 -o out.gcode
+
+The output always uses relative extrusion (M83). Absolute-E inputs are converted.
+
+As a slicer post-processing script, leave out the side the slicer is producing and
+let it append the temporary file path:
+
+  vaseweld weld --normal C:\prints\base.gcode --at 12.4
+"""
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="vaseweld",
+        description="Weld two G-code files sliced from the same plate at a chosen Z height.",
+        epilog=_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"vaseweld {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    weld_cmd = sub.add_parser(
+        "weld",
+        help="splice a normal slice and a vase slice at a Z height",
+        description="Splice a normal slice and a spiral vase slice at a Z height.",
+    )
+    weld_cmd.add_argument("--normal", type=Path, help="the non-vase slice")
+    weld_cmd.add_argument("--vase", type=Path, help="the spiral vase slice")
+    weld_cmd.add_argument(
+        "--at",
+        required=True,
+        type=float,
+        metavar="Z",
+        action="append",
+        help="cut height in mm; repeat it to alternate again, so two cuts give a "
+        "solid base, a vase body and a solid lid",
+    )
+    weld_cmd.add_argument("-o", "--output", type=Path, help="file to write")
+    weld_cmd.add_argument(
+        "gcode",
+        nargs="?",
+        type=Path,
+        help="the file a slicer post-processing hook just produced; it takes whichever "
+        "of --normal or --vase you left out, and is rewritten in place unless -o is given",
+    )
+    weld_cmd.add_argument(
+        "--vase-first",
+        action="store_true",
+        help="start with the vase part below the first cut instead of the normal part",
+    )
+    weld_cmd.add_argument(
+        "--start-flow",
+        type=float,
+        metavar="RATIO",
+        help="flow ratio the vase transition layer ramps up from "
+        "(default: spiral_starting_flow_ratio from the vase file, else 0.8)",
+    )
+    weld_cmd.add_argument(
+        "--finish-flow",
+        type=float,
+        metavar="RATIO",
+        help="flow ratio the last vase layer ramps down to "
+        "(default: spiral_finishing_flow_ratio from the vase file, else 0.25)",
+    )
+    weld_cmd.add_argument(
+        "--no-seam-retract",
+        action="store_true",
+        help="do not retract before the seam travel; the retraction state is still matched",
+    )
+    weld_cmd.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="report the plan and write nothing",
+    )
+    weld_cmd.add_argument(
+        "--force",
+        action="store_true",
+        help="weld even if the two files disagree on printer or plate settings",
+    )
+
+    preview_cmd = sub.add_parser(
+        "preview",
+        help="write a self-contained HTML page you can open and scrub through",
+        description="Draw the toolpath into one HTML file: no server, no dependencies.",
+    )
+    preview_cmd.add_argument("file", type=Path, help="G-code file to draw")
+    preview_cmd.add_argument("-o", "--output", type=Path, help="defaults to FILE.html")
+
+    layers_cmd = sub.add_parser(
+        "layers",
+        help="list the layer heights a file can be cut at",
+        description="Report the Z ladder, so you can pick a cut without guessing.",
+    )
+    layers_cmd.add_argument("file", type=Path, help="G-code file to inspect")
+    layers_cmd.add_argument(
+        "--all", action="store_true", help="print every layer, not just the summary"
+    )
+
+    check_cmd = sub.add_parser(
+        "check",
+        help="verify a G-code file is coherent enough to print",
+        description="Verify Z, extrusion, retractions and the temperature timeline.",
+    )
+    check_cmd.add_argument("file", type=Path, help="G-code file to check")
+    return parser
+
+
+def _validate_flow(name: str, value: float | None) -> None:
+    if value is not None and not 0.0 <= value <= 1.0:
+        raise WeldError(f"{name} must be between 0 and 1, got {value}")
+
+
+def _resolve_inputs(args: argparse.Namespace) -> tuple[Path, Path, Path]:
+    """Work out the two inputs and the destination, honouring a trailing hook file."""
+    normal, vase, output = args.normal, args.vase, args.output
+    if args.gcode is not None:
+        if normal is not None and vase is not None:
+            raise WeldError(
+                f"--normal and --vase are both set, so {args.gcode} has no role. "
+                "Drop one of them when a slicer passes the file it just wrote."
+            )
+        if normal is None:
+            normal = args.gcode
+        else:
+            vase = args.gcode
+        output = output or args.gcode
+    if normal is None or vase is None:
+        raise WeldError(
+            "need both slices: pass --normal and --vase, or pass one of them plus the "
+            "file a slicer post-processing hook hands over as the last argument"
+        )
+    if output is None:
+        raise WeldError("no destination: pass -o/--output")
+    if output.suffix.lower() == ".bgcode":
+        raise WeldError(
+            f"{output}: vaseweld reads binary G-code but cannot write it. "
+            "Give -o a .gcode name, or turn off 'Supports binary G-code' in "
+            "Print Settings > Output options on the profile that runs this hook. "
+            "Printers that take .bgcode take plain G-code too."
+        )
+    return normal, vase, output
+
+
+def _run_weld(args: argparse.Namespace, out: "object") -> int:
+    _validate_flow("--start-flow", args.start_flow)
+    _validate_flow("--finish-flow", args.finish_flow)
+    normal_path, vase_path, output = _resolve_inputs(args)
+
+    normal = parse_file(normal_path)
+    vase = parse_file(vase_path)
+    try:
+        check_compatible(normal, vase)
+    except CompatError as exc:
+        if not args.force:
+            raise
+        print(f"warning: {exc}", file=sys.stderr)
+        print("warning: continuing because --force was given", file=sys.stderr)
+
+    result = weld(
+        normal,
+        vase,
+        args.at,
+        first_role="vase" if args.vase_first else "normal",
+        start_flow=args.start_flow,
+        finish_flow=args.finish_flow,
+        seam_retract=not args.no_seam_retract,
+    )
+
+    if not args.dry_run:
+        text = result.newline.join(result.lines) + result.newline
+        try:
+            output.write_text(text, encoding="utf-8", newline="")
+        except OSError as exc:
+            raise GcodeError(f"{output}: cannot write ({exc.strerror or exc})") from exc
+
+    for line in result.summary():
+        print(line, file=out)
+    verb = "would write" if args.dry_run else "wrote"
+    print(f"{verb} {output} ({len(result.lines)} lines)", file=out)
+    for warning in result.warnings:
+        print(f"warning: {warning}", file=sys.stderr)
+    if result.stats_removed:
+        print(
+            "note: removed "
+            + " and ".join(result.stats_removed)
+            + ", which cannot be recomputed from these two files",
+            file=sys.stderr,
+        )
+    destination = os.environ.get("SLIC3R_PP_OUTPUT_NAME")
+    if destination:
+        print(f"slicer will save it as {destination}", file=out)
+    return EXIT_OK
+
+
+def _run_preview(args: argparse.Namespace, out: "object") -> int:
+    destination = args.output or args.file.with_suffix(".html")
+    try:
+        written = write_preview(destination, args.file)
+    except OSError as exc:
+        raise GcodeError(f"{destination}: cannot write ({exc.strerror or exc})") from exc
+    size = written.stat().st_size / 1024
+    print(f"wrote {written} ({size:.0f} KB), open it in any browser", file=out)
+    return EXIT_OK
+
+
+def _run_layers(args: argparse.Namespace, out: "object") -> int:
+    gcode = parse_file(args.file)
+    zs = [layer.z for layer in gcode.layers]
+    steps = {round(b - a, 4) for a, b in zip(zs, zs[1:])}
+    print(f"{gcode.path.name}: {len(zs)} layers, Z {zs[0]:.3f} to {zs[-1]:.3f}", file=out)
+    if len(steps) == 1:
+        print(f"layer height: {next(iter(steps)):.3f} mm", file=out)
+    else:
+        print(
+            f"layer height: varies, {min(steps):.3f} to {max(steps):.3f} mm. "
+            "Slice both files at a fixed layer height before welding.",
+            file=out,
+        )
+    print(
+        f"weldable range: Z {zs[1]:.3f} to {zs[-1]:.3f} (layers 2 to {len(zs)})",
+        file=out,
+    )
+    if args.all:
+        for layer in gcode.layers:
+            print(f"  layer {layer.index:4d}  Z {layer.z:.3f}", file=out)
+    return EXIT_OK
+
+
+def _run_check(args: argparse.Namespace, out: "object") -> int:
+    report = run_check(args.file)
+    print(report.summary(), file=out)
+    for problem in report.problems:
+        print(problem, file=out)
+    return EXIT_OK if report.ok else EXIT_PROBLEMS
+
+
+def main(argv: list[str] | None = None, out: "object" = None) -> int:
+    out = out or sys.stdout
+    args = _build_parser().parse_args(argv)
+    try:
+        if args.command == "weld":
+            return _run_weld(args, out)
+        if args.command == "layers":
+            return _run_layers(args, out)
+        if args.command == "preview":
+            return _run_preview(args, out)
+        return _run_check(args, out)
+    except (GcodeError, CompatError, WeldError) as exc:
+        print(f"vaseweld: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    except KeyboardInterrupt:
+        print("vaseweld: interrupted", file=sys.stderr)
+        return EXIT_USAGE
+
+
+if __name__ == "__main__":
+    sys.exit(main())