PyGrbl_Build 1.0.0

A collection of algorithms to generate G-code for GRBL diode lasers from different sources, plus tooling around the G-code itself. Five generators today:

• Line-to-Line (l2l_gcode) — raster engraving from an image, with LaserGRBL fidelity.
• Jarvis (jarvis_gcode) — 1-bit Jarvis-Judice-Ninke error diffusion followed by the same raster G-code engine. The dots are short powered raster segments, as in LaserGRBL.
• SVG vector (svg_gcode) — vector tracing from an SVG (paths, basic shapes, groups, transforms), a faithful port of LaserGRBL's SVG import. Pure Python, no extra dependency.
• Image vector (img2vector_gcode) — outline tracing from a raster image (LaserGRBL's "Vectorize!"): the image is reduced to black/white, Potrace traces its outlines as closed contours, and each curve is emitted as G2/G3 arcs. Pure Python, Pillow only. Outlines only today (no interior filling yet).
• Image to SVG (img2svg) — the same Potrace trace as img2vector_gcode, but the contours are written to a standard vector SVG instead of G-code. Inner contours become holes (fill-rule evenodd), so you get the filled black silhouette potrace.exe produces. Pure Python, Pillow only.

Plus G-code bounds & framing (get_bounding_box + generate_framing_gcode): a fast C parser for the bounding box of any G-code (file or in-memory) and a framing pass that traces it, so the operator can confirm placement before engraving.

Part of the pygrbl family, a set of libraries to manage GRBL. Companion to pygrbl_streamer and pygrbl_server

Speed

This is the whole point. A full 300 mm @ 10 lines/mm raster job — nearly 4.7 million lines of G-code — comes out in ~0.34 s. LaserGRBL can take around 2 minutes to produce the same job: that's roughly a 350× speedup, and byte-for-byte the same output.

Install

pip install pygrbl-build

The only requirements are Pillow and a C compiler. Pillow is the single Python dependency (image loading and resizing); the C compiler is needed at install time because the raster engine ships as a C extension. Nothing else — no numpy, no runtime toolchain.

Usage

Each algorithm pairs a *_gcode generator with its own *Profile config, so adding one never touches the others.

Raster Line-to-Line (l2l_gcode + L2LProfile):

from pygrbl_build import L2LProfile, l2l_gcode, write_gcode

profile = L2LProfile(width_mm=300.0, lines_per_mm=10.0, feed=3000, s_max=100)
write_gcode(l2l_gcode("shield.png", profile), "shield.nc")

Jarvis dithering (jarvis_gcode + JarvisProfile):

from pygrbl_build import JarvisProfile, jarvis_gcode, write_gcode

profile = JarvisProfile(width_mm=80.0, lines_per_mm=3.0, feed=3000, s_max=1000)
write_gcode(jarvis_gcode("photo.png", profile), "photo.nc")

Jarvis converts a color or gray image to a black-and-white dot pattern. Its profile exposes LaserGRBL's grayscale formula, channel weights, brightness, contrast and white clip, plus this library's bidirectional scan and optional overscan. It uses horizontal raster passes; vertical and diagonal directions are not implemented. The diffusion follows the coefficients and edge behavior of LaserGRBL's Jarvis implementation.

All image APIs (l2l_gcode, jarvis_gcode, img2vector_gcode, and img2svg) also accept encoded image bytes, bytearray, or an already loaded PIL.Image.Image. This allows in-memory services to work without writing a temporary image:

from PIL import Image

with open("shield.png", "rb") as source:
    from_bytes = l2l_gcode(source.read(), profile)

from_pillow = l2l_gcode(Image.open("shield.png"), profile)

SVG vector (svg_gcode + SvgProfile):

from pygrbl_build import SvgProfile, svg_gcode, write_gcode

profile = SvgProfile(feed=1000, s_max=255)
write_gcode(svg_gcode("logo.svg", profile), "logo.nc")

svg_gcode accepts a path as before, or the SVG XML directly as str, bytes, or bytearray.

SvgProfile's defaults reproduce LaserGRBL's own SVG-import defaults, so the output matches the desktop app for the same drawing. text and image elements are skipped — convert text to paths in your editor first.

Image vector (img2vector_gcode + Img2VectorProfile):

from pygrbl_build import Img2VectorProfile, img2vector_gcode, write_gcode

profile = Img2VectorProfile(width_mm=80.0, quality=10.0, feed=1000, s_max=1000)
write_gcode(img2vector_gcode("logo.png", profile), "logo.nc")

img2vector_gcode is a faithful port of LaserGRBL's "Vectorize!": the image is reduced to black/white (resize, grayscale, white-clip, optional threshold), Potrace traces its outlines, and each cubic Bezier is approximated by biarcs and emitted as G2/G3 arcs (with a G1 fallback). width_mm sets the physical width and quality the tracing resolution in pixels/mm. The Img2VectorProfile defaults follow Potrace's classic settings (smooth curves, optimization on); set alphamax=0.0 and opticurve=False to mimic LaserGRBL's own out-of-the-box UI defaults.

Image to SVG (img2svg + Img2SvgProfile):

from pygrbl_build import Img2SvgProfile, img2svg

profile = Img2SvgProfile(width_mm=80.0, quality=10.0)
svg = img2svg("logo.png", profile)
with open("logo.svg", "w", encoding="utf-8") as f:
    f.write(svg)

img2svg runs the same trace as img2vector_gcode (resize, grayscale, white-clip, optional threshold, then Potrace outlines), but skips the biarc/G-code stages and writes the contours as a single filled <path>. It returns the complete SVG document as a string (not a G-code iterator, so use your own open()). The Img2SvgProfile carries only the tracing and binarization knobs — no feed, power or laser-mode fields. viewBox is in pixels (width_mm*quality) while width/height carry the physical size in mm, and the image keeps its natural top-down orientation (no Y-flip, unlike the G-code path).

G-code bounds & framing (get_bounding_box + generate_framing_gcode):

from pygrbl_build import get_bounding_box, generate_framing_gcode

# From a file path (opened and streamed in C — handles 500MB+ in seconds)...
min_x, max_x, min_y, max_y = get_bounding_box("job.nc")

# ...or straight from G-code already in memory, no file needed:
gcode = "\n".join(svg_gcode("logo.svg", SvgProfile()))
min_x, max_x, min_y, max_y = get_bounding_box(gcode)          # str
min_x, max_x, min_y, max_y = get_bounding_box(gcode.encode()) # or bytes

frame = generate_framing_gcode(min_x, max_x, min_y, max_y, power=10.0, speed=1000)

get_bounding_box is the original gcode-bounds C parser folded in. It accepts a file path (str/Path, opened and streamed in C) or the G-code content directly (bytes, or a multi-line str), so it never has to exist on disk — the Python wrapper picks the route. Only X/Y are considered; rapid moves to the origin (G0 with X0/Y0) are skipped so home moves don't expand the box. generate_framing_gcode returns the perimeter trace as a list of lines (power is 0-100, speed in mm/min).

write_gcode writes the path verbatim, so you choose the extension (.nc, .gcode, .g, ...). It's just a convenience: every *_gcode generator is a lazy iterator of lines, so anything beyond writing a plain file (compression, network shipping, streaming to the machine) is the upper layer's job — consume the iterator with whatever sink you need.

Public API: L2LProfile, l2l_gcode, JarvisProfile, jarvis_gcode, SvgProfile, svg_gcode, Img2VectorProfile, img2vector_gcode, Img2SvgProfile, img2svg, get_bounding_box, generate_framing_gcode, write_gcode. See the docstrings.

Publishing to PyPI

.github/workflows/build.yml builds and tests on pushes to main (excluding documentation-only changes), on published GitHub releases, and on manual runs. Publishing a GitHub release automatically publishes its distributions to PyPI after all required jobs succeed. Pushes and manual runs only create CI artifacts.

Before creating a release, update __version__ in src/pygrbl_build/__init__.py and use the matching version for the release tag (for example, v1.0.0). The workflow checks this match; it does not increment versions or skip existing PyPI files.

One-time setup: create the pypi-release GitHub environment and add a GitHub Trusted Publisher in the PyPI project's Publishing settings with:

• Owner: offerrall
• Repository: pygrbl_build
• Workflow filename: build.yml
• Environment: pypi-release

Authentication uses OIDC (id-token: write); no PyPI API token secret is needed. See PyPI's Trusted Publisher setup.