helix.sankhacooray.com (site source: helix-sankhacooray-com)
Turn a PDF into laser jobs for an Epilog Helix (or Mini) and send them over the network — no VisiCut, no Windows-only Epilog driver, no CUPS printer queue.
It runs as a small local web app: you start a Python server on your own
machine, open http://localhost:4060 in any browser, drop in a PDF, place it
on a picture of the bed, pick a material preset, and hit Send. The job
queues on the laser and you press GO on the machine itself.
PDF ──▶ place on the bed ──▶ pick material + preset ──▶ Send ──▶ press GO
- Works on macOS, Windows and Linux — the only interface is your browser.
- Nothing leaves your machine. The server binds to localhost, and the only outbound connection is to the laser on your own network.
- Material presets are Epilog's published suggested settings for a 30-watt Helix/Mini, transcribed from the datasheet.
A laser cutter is a fire hazard and a machine that can hurt you.
- Never run a job unattended, and keep the lid closed and extraction on.
- The shipped presets are starting points from Epilog's datasheet for a 30 W tube. Your machine's real power, optics and material differ. Always test on scrap first.
- The bed size and safe travel in
data/machine.jsonare the calibration of one specific machine. They are almost certainly wrong for yours — see Configure your machine before your first send. The server refuses out-of-bounds jobs, but that guard is only as good as the numbers you give it. - This software is provided as-is, with no warranty (see LICENSE). You are responsible for what your laser does.
| What | Why | Notes |
|---|---|---|
| Python 3.9+ | runs the server | python3 --version |
| Pillow | rasterises the artwork | installed with pip, below |
| Poppler | reads and renders the PDF (pdfinfo, pdftocairo) |
a separate install, below |
| An Epilog Helix / Mini on your network | receives the job over LPD (port 515) | you need its IP address |
macOS (with Homebrew):
brew install popplerWindows (PowerShell):
winget install --id oschwartz10612.PopplerThen close and reopen the terminal so the new PATH takes effect. If
pdfinfo -v still isn't found, add Poppler's bin folder to your PATH
manually. (choco install poppler works too, if you use Chocolatey.)
Linux:
sudo apt install poppler-utils # Debian / Ubuntu
sudo dnf install poppler-utils # FedoraCheck it worked — this should print a version, not "command not found":
pdfinfo -vgit clone https://github.com/bsc2fast/helix-studio.git
cd helix-studio
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python3 -m pip install -r requirements.txtThe virtual environment is optional but recommended; without it,
python3 -m pip install --user -r requirements.txt is fine.
Copy the example config and edit it with your own laser's IP address and bed measurements:
cp config.example.json config.json # Windows: copy config.example.json config.jsonconfig.json is gitignored, so your settings survive a git pull. Any key you
leave out keeps the shipped default. Find your laser's IP on the machine's
own control panel, under its network/TCP-IP settings.
Helix Studio also writes a prefs.json beside it — the setup you were last
working in (material, thickness, stock size and where that stock lies on the
bed, machine, and a laser adopted by a scan), so a new session opens where the
last one left off. It is a convenience file, not configuration: delete it and
you only lose the dropdown positions, and config.json always wins over it. The
preset is not remembered — a new session starts on the material's first
preset, so check power and speed for the job in front of you.
Material colours and stock sizes you add on the Settings page (⚙) are
kept in a finishes.json beside it, also gitignored. The built-in ones can't
be edited; yours sit beside them, and a size of your own is offered only for
its material. Settings also switches the display between mm and inches —
display and entry only: everything is stored and sent in mm.
Start conservative with
usable_*. Widen it only after you have watched the head travel to that edge and clear the rails.
python3 server.pyIt prints:
helix-studio: settings from /path/to/helix-studio/config.json
helix-studio on http://127.0.0.1:4060 (laser 192.168.1.6)
Open http://localhost:4060. Leave the terminal running while you work; press
Ctrl-C to stop the server.
Useful flags — these beat config.json, which beats the shipped defaults:
python3 server.py --laser 10.0.0.9 # a different laser, just this once
python3 server.py --port 4070 # if 4060 is taken
python3 server.py --bind 0.0.0.0 # let other machines on the LAN use itHELIX_LASER_HOST, HELIX_PORT, HELIX_BIND and HELIX_CONFIG do the same
as environment variables.
--bind 0.0.0.0exposes the UI — and through it your laser — to everyone on the network, with no password. Only do that on a network you trust.
-
Drop a PDF onto the window (or click the Artwork card to choose one). Vector artwork works best; the page is cropped to its ink, so whitespace around the design is ignored. Drop several PDFs, or add more later with + PDF — they all stay open, listed down the left, and one job can mix pages from any of them. A cutter
.plt(HPGL, e.g. from Kerf or SignMaster) works too: its cut paths come in as red hairlines, so a Cut preset cuts along them and an Engrave preset burns them as fine lines. -
Place it. Drag the artwork around the bed picture, or type X/Y in mm. X/Y is measured from the laser's home corner (top-left).
Rotateturns it in 90° steps,Centercentres it in the safe area. Hovering a page shows its dotted outline; it turns red, and stays, once the page crosses the dashed safety boundary or overlaps another — and Send is disabled while it is red (hover Send to see what's holding it back). A pulsing ⚠ in the Artwork card's title collects the warnings; hover it to read them. Delete takes the selected page off the bed. Page layout (a chip on the Artwork card) places a page by the whole page instead of its ink, so artwork keeps the spot it was designed in: set the artboard to the stock's size (Illustrator: select a stock-sized frame, Object → Artboards → Fit to Selected Art, then delete the frame). A page the size of the chosen stock switches it on by itself and lands on the stock. Only placement changes — safety and overlap checks, and what is sent, still go by the ink. The Artwork card also says whether a page is Vector and, for pictures in it, their resolution as placed (amber below 150 dpi). Rulers run along all four sides: top/left from the home corner, bottom/right from the opposite one. Pick a material size (A4, Arch B, Letter… — only sizes that fit the bed are listed) to see your stock drawn on the bed; drag it, or type its X/Y in the Material card, to match where the sheet really lies.Rotateon either card is only enabled when the turned sheet or artwork still fits from where it sits — the card says how far to move it when it doesn't. The page list down the left shows every page of every open PDF, grouped by file — including a one-page PDF. Page 1 of each file starts on the bed; Include puts another page on in the first free spot, so pages from one file or several can be laid out on one larger sheet and sent as a single job. − n + on a page sets how many copies of it are on the bed; each copy is placed in the next free spot and can be dragged and rotated on its own. With more than one file open, each is lettered and its pages are labelledA1,B2… on the bed (B2·1,B2·2for copies). ✕ closes a file and takes its pages off with it. Overlapping pages turn red and Send stays disabled until you move them apart. -
Pick material and thickness, then a preset. Each dropdown opens a visual picker: materials as swatches in the colours they're sold in, thicknesses edge-on at real size, stock sizes drawn on the bed, presets as a sample burn. The material, its colour, thickness and stock size come back as you left them next time you start; the preset does not. Engrave presets (
▦) raster the artwork; cut presets (✂) follow its vector lines. Presets that cannot cut through the thickness you chose are hidden. Engrave + cut presets (where the material and thickness allow a cut) send one job: the engraving first, then the cut, so one GO does both. There's one per engrave style, each paired with the thinnest rated cut that goes through the stock. Settings → Cut lines chooses how a page splits into cut lines and engraving:- Hairline (default): strokes no wider than 0.1 mm (adjustable) are cut — e.g. Illustrator's 0.001 pt line.
- Colour: anything drawn in the cut colour (default red, any thickness) is cut; Illustrator's CMYK red counts.
- Outline vs fill: every stroked line is cut; fills and text engrave.
The cut lines are left out of the engraving. By default plain Cut presets still cut every path; the same page can make them follow the decode mode instead. Check a new setup with
samples/engrave-cut-test.pdffirst. The bed shows the burn, not the PDF: artwork is drawn on the stock as the laser will leave it, darker and deeper for harder presets. The raster is 1-bit — every pixel that isn't near-white burns at full power — so greys and colours all burn alike, and the preview shows exactly that. -
Send. The job appears on the laser's queue; walk over and press GO. The Send button shows the estimated job time (
≈11:47). It comes from the job exactly as the driver will emit it — rows swept and their length for an engrave, path count and length for a cut — fitted to jobs timed on this machine. After a send, type how long it really took into Took (mm:ss): it's kept intimings.json(gitignored) and every later estimate uses it. Cuts show~until one has been timed.
To engrave and then cut the same piece, send twice: choose the engrave preset and send, then switch to the cut preset and send again without moving anything. Both jobs are placed from the same origin, so they line up.
PDF ──pdftocairo──► preview + raster ──┬──► engrave: 1-bit mask (PackBits)
└──► cut: vector paths flattened to mm
│
▼
PJL / PCL + HP-GL over LPD:515
| Path | What it is |
|---|---|
server.py |
the local web server + REST API, and the out-of-bounds guard |
driver/epilog.py |
standalone Epilog driver (raster + vector + LPD send), ported from liblasercut. Vector cuts get a small overcut so the laser's start-of-vector firing lag doesn't leave the first edge uncut |
driver/laserlink.py |
is the laser reachable (LPD port probe), and a local-network scan to find it |
driver/pdfjob.py |
PDF → page size, colour raster, layer detection, vector extraction (Poppler + a compact SVG path flattener) |
data/materials.json |
Epilog Mini/Helix suggested settings, 30 W column |
data/machine.json |
the shipped bed calibration — override it in config.json |
web/ |
the UI (index.html, app.js, and picker.js for the visual pickers, material looks and Settings — no build step, no dependencies) |
web/img/ |
optional photos: <machine-name>.jpg for the machine, mat-<material>-<colour>.jpg to replace a drawn material |
prefs.json |
the last setup, written as you work (gitignored) |
finishes.json |
your own material colours, from Settings (gitignored) |
Speed and power are 0–100 %. Engraving is specified in DPI, cutting in frequency (Hz).
The REST API is small enough to drive from a script: POST /api/import with
raw PDF bytes (returns an id, the page count and page 1; an X-Filename header
names it), GET /api/page/<id>/<n> for any other page, then POST /api/send
with an operation and the placed pages as
items: [{doc, page, offset_mm: [x, y], rotation}] — or a single offset_mm +
rotation for page 1, or a list of per-colour assignments. Each item's doc
is the id of any import, so one job can carry pages from several PDFs; leave it
out and the top-level id is used. Placed pages must not overlap; they go to
the laser as one job.
Poppler is required but pdfinfo is not on PATH — step 1 didn't take
effect. On Windows, reopen the terminal after installing.
Address already in use — something else holds port 4060. Use
python3 server.py --port 4070.
The IP chip says Scan — the laser didn't answer on port 515. Helix Studio scans your local network for it (right away, then every 30 s) and switches to the new address when it finds exactly one; if several printers answer it asks which one is the laser. Send stays disabled until it's reachable.
The job never arrives / Send hangs — check laser_host is right and that
the machine is on and idle: ping <laser-ip>. The laser must be reachable on
TCP port 515, which means the same network segment as your computer, no VPN in
the way.
"No printable artwork detected" — the first page rendered blank. Check the PDF isn't a single huge white image. For a multi-page PDF, include the page that has the artwork from the page list on the left; pages that render blank are marked Blank there and can't be put on the bed.
A cut preset does nothing — cutting follows vector paths. A PDF that contains only a photo or a flattened bitmap has none; export vectors from your design tool, or use an engrave preset instead.
The engraving came out lighter or deeper than expected — that is the
preset meeting your actual machine. Adjust speed/power in
data/materials.json, and test on scrap.
MIT — see LICENSE. Not affiliated with, or endorsed by, Epilog Laser. "Epilog" and "Helix" are their trademarks.
{ "laser_host": "192.168.1.6", // your laser's IP address "machine": { "name": "Epilog Helix 24x18 (30W)", "bed_w_mm": 609.6, // full bed, X = the long axis "bed_h_mm": 457.2, "usable_w_mm": 605.0, // how far the head actually reaches, measured "usable_h_mm": 450.0, "safety_mm": 10.0 // no-go border; jobs crossing it are refused } }