Chipload

Chipload is 2.5D CAM for CNC routers and mills: a drawing in, checked G-code out.

• In: DXF drawings, text in built-in fonts, pictures traced into shapes, and simple shapes drawn in Chipload (circles, rectangles, polylines).
• Out: G-code for your controller, in mm or inches, through a post-processor: GRBL, LinuxCNC and Mach3/4 are built in, and you can write your own.
• Operations:
  • profiles, spiralling down, with tabs, finishing passes, onion skins and dogbones;
  • ring pockets, with helix entry and rest machining;
  • V-carving;
  • follow path;
  • drilled and helically bored holes.
• Checked: every program passes an independent checker before Chipload writes it. The checker is separate code that reads the G-code back and refuses rapids through the stock, cuts outside the machine, and other mistakes.
• Seen before cut: a 3D view, a material-removal simulation, a playback slider, the cycle time, the chip load, and a setup sheet for the operator.
• Scriptable: everything works from the command line too, with JSON output for scripts, and AI assistants can drive it.
• mm or inches: the app shows lengths in either, and the G-code can be in either.

Testers with real machines wanted. Chipload’s programs pass its checker and many tests, but they haven’t been run on a real controller yet. If you have a CNC router or mill, please try it, starting with an air cut, and tell us how it went in an issue, also when it worked. The README says what to try and what to send.

Safety

CNC machines are dangerous. A wrong program can break tools, throw parts or swarf, damage the machine and injure people. The checker catches the mistakes it knows about, but it can’t know your clamps, your fixture, your tool or your machine’s real state. You are responsible for every program you run:

1. Look at the toolpath: in Chipload’s 3D view and simulation, or a G-code viewer such as NC Viewer or CAMotics. Check the depths, the work zero, clamps in the way, the order of the cuts and what holds the part.
2. Air-cut first: set the work zero above the stock (or raise Z) and run the program without cutting, with a hand on the stop button.
3. Only then cut, and never leave a running machine unattended.

Chipload comes with no warranty (GPL-3.0, sections 15 and 16). Its licence and the licences of everything it is built with are under Help > About and licences, and chipload licenses prints them.

What Chipload doesn’t do

Chipload is meant to be lean. It leaves out what other tools do better:

• nesting parts on a sheet;
• 3D surface machining;
• sending G-code to the machine (use your controller’s sender);
• CAD beyond a few shapes;
• facing the spoilboard.

This guide

This guide is for Chipload’s version in the title.

• Getting started: install Chipload and make your first part.
• Concepts: what every operation shares: units, stock and zero, depths, sides, tools, and the checker.
• One page per kind of operation, then tools, machines and posts.
• Before cutting: problems, the simulation, times and the setup sheet.
• Scripting and the generated reference pages, for every command and every field of the files.

Installing

Download Chipload from the releases page. For the app you need one file: the one named chipload-X.Y.Z-… for your system (below).

Chipload is two programs that read and write the same project files and make the same G-code:

• the desktop app, in the files named chipload-X.Y.Z-…;
• the command line chipload, for scripts and automation, in the archives named chipload-cli-X.Y.Z-…. You don’t need it to use the app.

Each release also has the user guide to read offline and SHA256SUMS.txt to check the files.

Linux

Download chipload-X.Y.Z-linux-x86_64.AppImage, make it executable and run it:

chmod +x chipload-*.AppImage
./chipload-*.AppImage                # the app; add a .chipload or .dxf file to open it

• ARM64 (Raspberry Pi 4 or 5 with a 64-bit OS, ARM boards and laptops): take chipload-X.Y.Z-linux-aarch64.AppImage instead. The app needs OpenGL 3, which a Pi 4 or 5 has with its standard graphics driver. Not yet tried on a Pi: reports welcome.
• Requirements: glibc 2.35 or newer (Ubuntu 22.04, Debian 12, Fedora 36 or newer, Raspberry Pi OS 12 “Bookworm”).
• Command line: it’s in chipload-cli-X.Y.Z-linux-x86_64.tar.gz (ARM64: …-linux-aarch64.tar.gz). Unpack it and put chipload on your PATH.
• File dialogs: these need an XDG desktop portal or zenity. Without them, use File > Open path… (and Import image from path…, Update drawing from path…), or give the files on the command line.

Windows

Download chipload-X.Y.Z-windows-x86_64.exe: the app as one file with nothing to install. Double-click it to start. On a Windows laptop with an ARM processor (Snapdragon), take chipload-X.Y.Z-windows-aarch64.exe instead.

The app isn’t code-signed, so Windows SmartScreen may warn the first time. Choose More info > Run anyway.

• Command line: it’s in chipload-cli-X.Y.Z-windows-x86_64.zip (ARM: …-windows-aarch64.zip). Unzip it and run chipload.exe from a terminal (PowerShell or Command Prompt); it isn’t meant to be double-clicked.

macOS

No release has macOS files yet. Until one does, build Chipload from the source (below). Once there: download chipload-X.Y.Z-macos-universal.dmg, open it and drag Chipload onto Applications. It runs on Apple silicon and Intel Macs with macOS 11 or newer.

The app isn’t notarised by Apple, so macOS refuses it the first time. Open *System Settings

Privacy & Security*, scroll down to the message about Chipload and choose Open Anyway.

• Command line: it’s in chipload-cli-X.Y.Z-macos-universal.tar.gz. Unpack it and put chipload on your PATH. If macOS stops it, run xattr -d com.apple.quarantine chipload once.
• Opening files: use File > Open in the app; double-clicking a .chipload file in Finder doesn’t open it yet.

From source

Install Rust with rustup, then:

git clone https://github.com/chipload/chipload
cd chipload
cargo build --release -p chipload-gui -p chipload-cli
# target/release/chipload-gui and target/release/chipload

Your settings

Chipload keeps your tool library, machine profiles, own post-processors and app settings in one folder:

A project keeps its own copy of the tools, machine and post it uses, so it cuts the same on any computer, whatever that computer’s library holds.

Your first part

This walks through one part, from a DXF to G-code: a plate with holes, cut out with an outside profile. The same steps follow in the app and on the command line.

In the app

1. Import the drawing: File > Import DXF… (Ctrl+I).

   • If the DXF doesn’t say whether it’s in mm or inches, Chipload asks. It never guesses.
   • The report under the canvas lists what was imported, and anything skipped or repaired: duplicate lines, gaps it closed, splines turned into arcs.

2. Check the job settings: click Job settings in the Browser on the left. A new project starts with:

   • stock just covering the drawing, 10 mm thick;
   • work zero at the drawing’s origin, Z zero on the stock top;
   • the GRBL post, a safe height of 5 mm;
   • a 6 mm endmill at 18 000 rpm.

   With a tool library and machine profiles set up, your defaults come instead. Set the real stock thickness now: depths are measured from its top.

3. Select what to cut:

   • click the outline on the canvas;
   • Ctrl+click adds more;
   • right-click selects a whole layer;
   • or click a DXF or one of its layers in the Browser.

4. Add an operation: Profile, in the ribbon’s OPERATION group.

   • Side: Chipload picks outside for an outline and inside for holes, and asks when a selection mixes both.
   • End depth: for a cut-out, the stock thickness plus a little, e.g. 10.3 mm into a spoilboard. More than the allowed overcut (0.5 mm by default, under Job settings) is refused.
   • Step down: how deep each pass goes.
   • Tabs: they keep the part from coming loose on the last pass. Add them under Tabs.

5. Generate: F5, or leave View > Update toolpath automatically on.

   • The toolpath shows on the canvas: arrows give the cutting direction, rapids are dashed, and each operation’s number sits at its first plunge.
   • Problems show in red on the field they’re about.
   • Warnings appear in the report.

   

6. Look at it: 3D shows the toolpath at its real depths. View > Show stock shows the stock as cut, and the slider under the canvas plays the program back.

7. Export: File > Export G-code… (Ctrl+E).

   • You can only export once the checker has passed the program.
   • Next to the G-code comes a setup sheet (part-sheet.html) for the operator: stock, zero, tools in order, operations and times.

8. Save the project: Ctrl+S. A project (.chipload) keeps the drawing itself, so the DXF isn’t needed again unless it changes.

On the command line

chipload import plate.dxf -o plate.chipload        # add --units mm if the DXF doesn't say
chipload inspect plate.chipload                    # contours with their numbers and layers
chipload set plate.chipload stock.thickness=12 \
  'operations.0={"type": "profile", "name": "Outline", "part": 1,
    "select": {"layer": "CUT_OUTSIDE"}, "side": "outside", "direction": "climb", "tool": 1, "start_depth": 0,
    "end_depth": 12.3, "clearance": 0, "step_down": 3, "feed": 1500, "plunge_feed": 400,
    "ramp_angle": 0.0524,
    "tabs": {"count": 4, "width": 6, "height": 2, "flank_angle": 1.5707963267948966}}'
chipload plan plate.chipload                       # warnings, cycle time, chip load
chipload run plate.chipload -o plate.nc            # checked G-code and plate-sheet.html

• set adds the operation (see Scripting); part is the project’s one part, which a new project has as part 1.
• select picks the outline by its layer, as inspect lists it. To pick single shapes instead, use {"shapes": [ids]}: inspect --json gives each contour’s shape ids.
• Angles in project files are in radians: 0.0524 is the 3° spiral ramp every profile goes down at, and 1.5707963267948966 is 90°, a straight tab.
• The app makes the same project. Open plate.chipload in it to see and change the operation.

The checker

Before Chipload writes a program, an independent checker reads the G-code back and refuses it if it finds, among other things:

• a rapid move (G0) down into the stock, or sideways while the tool is below the safe height;
• a cut deeper than the stock bottom plus the allowed overcut;
• a move beyond the machine’s travel, when the travel is set;
• an arc whose ends don’t lie on its circle;
• a cutting move with no feed, or with the spindle off;
• other units than the machine’s, or relative coordinates;
• a tool change with the spindle running or below the safe height.

The checker is separate code that shares nothing with the part of Chipload that makes the toolpath, so a bug in one is likely caught by the other. chipload check part.nc --job part.chipload runs it on any G-code, also from other programs.

Before you cut

• Work zero: the setup sheet says where X0 Y0 and Z0 are. Set them on the machine exactly there.
• Clamps: look at the 3D view or the simulation for clamps in the toolpath. Chipload doesn’t know where your clamps are.
• Air cut: run the program once above the stock.
• What holds the part: in the last pass, tabs or an onion skin should keep it in place.

The window

The header

At the top, a slim top bar:

• Left: Open, Save, Undo and Redo.
• Middle: the project’s name on a tab. A dot on it means unsaved changes. Closing, opening or starting a project with unsaved changes asks first, in the middle of the window: Save (then go on), Don’t save or Cancel.
• Changed by another program: when the project’s file is saved by another program (an AI assistant, a script), the app loads the new version within a couple of seconds and says so in the report. Ctrl+Z goes back to what you had. If you have unsaved changes, it asks first: Load it (your changes stay one Ctrl+Z away) or Keep mine (your next Save overwrites the file).
• Right: the colour theme (a click goes System → Light → Dark), ? Help (user guide, keyboard shortcuts, about) and the version.

Under it, the ribbon groups the buttons:

Generate (F5) and Export sit at the right end.

Each group’s caption (FILE ▾ …) opens its whole menu. This guide writes those menus as File > …, Draw > … and View > …. Help > … is the question mark in the top bar.

The status bar at the bottom gives hints on the left. On the right it shows the cursor’s position, the number of copies, the cycle time once generated, the post-processor and the units.

The Browser

The Browser on the left holds your library and the whole project as a tree:

• This computer, at the top and folded at the start: what is kept on this computer for every project. It is there also with no project open.
  • Preferences: the setup sheet, updating the toolpath by itself, the units and the colour theme.
  • Tools and Machines: your tool library and machine profiles.
  • Post-processors: the built-in ones and yours; click one for what it writes, and Use in this project.
• The project, named after its file.
  • Job settings: stock, machine, post-processor and tools, shown on the right when clicked. A red dot means one of them has a problem.
  • Tools: the project’s tools, each with the library tool it came from at the right (“← 6 mm 2F”, “(changed)” when the values differ). See Tool library.
  • Drawing: what the shapes come from. Each DXF has its layers under it; then come each picture, and the shapes drawn in Chipload by kind (circles, rectangles, polylines). See Several drawings.
  • Parts, each with its operations under it, in cutting order. A line marks each tool change. See Parts.

Rows:

• Click a row to select it.
  • A DXF, picture or layer selects its shapes for a new operation, and Ctrl+click adds to the selection.
  • An operation, a part, a tool, Tools, Job settings, a DXF (or one of its layers) or a picture shows its settings on the right, in Properties.
• Double-click a picture for its trace settings, or a part to make it the active part.
• Right-click a row for the rest:
  • A DXF: Place… (its properties), Update from a DXF… and Remove.
  • A picture: Trace settings… and Remove.
  • An operation: Move up and Move down (also Alt+↑ and Alt+↓), Duplicate, for a pocket Add rest pass ▸ (a rest pass shows under it), and Delete.
  • A rest pass: Remove.
  • The Drawing folder: Add DXF… and Import image….
  • A part: Activate, New operation (for the selected shapes), Move up, Move down and Delete part (with its operations).
  • The Parts folder: New part.
  • A library tool: Add to project, Make default, Delete. A library machine: Use in this project, Make default, Delete. This computer > Tools or Machines: New, Import…, Export….
• The triangle opens and closes a folder, and so does a click on a plain folder like Tools.

The eye hides a DXF, layer, picture or kind of drawn shape on the canvas: it isn’t drawn and can’t be clicked. Hidden shapes are still cut.

The tick in front of an operation or a part turns it on or off. One that is off isn’t in the program, and its row is dimmed; a part that is off takes its operations with it.

The active part is in bold, marked active. New operations from the ribbon go into it, whatever is open. Its name is also in the status bar.

On an operation’s row:

• Right end: its tool, and how many hidden contours it cuts (“3 hidden · T1”).
• A red dot marks a problem.
• Hover the row for its kind, its geometry, its depths, its time once generated and its first problem.
• Drag the row onto another to move it there, or onto a part to move it to the end of that part.

Drag a library tool onto the project’s Tools to copy it into the project.

The canvas

The canvas shows the stock, the drawing and the toolpath on a soft gradient. It follows the colour theme: dark, or light grey.

• The grid lies on the stock top, in top view and in 3D.
  • Its fine lines are where clicks snap while drawing. A stronger line comes every ten.
  • It follows the zoom, and the status bar gives its step (“grid 5 mm”).
  • G or View > Show grid hides it, and Chipload remembers that.
• The axes: a red line along X and a green one along Y run through the program’s zero. Short thick strokes point the positive way, and in 3D a blue one points up Z.
• The navigation bar floats at the bottom, each button an icon over its name:
  • how you look: Fit (F), Top (T) and 3D;
  • what is shown: Stock (the simulation), Toolpath, Drawing, Images and Grid (G);
  • with two parts or more, All parts: the toolpath and simulation of every part, not only the active one.
  • When the canvas is too narrow for the names, the buttons show only their icons; hover over one to see its name.
• Drawing off hides the drawing’s contours, to see the simulated stock or the toolpath alone. While it’s off, clicks on the canvas don’t select anything. Selecting something in the Browser, or starting to draw a shape, shows the drawing again.
• The corner:
  • In 3D, the top right corner has a cube that turns with the view. Click a face (TOP, FRONT, RIGHT, BACK, LEFT) to look straight at it.
  • In top view, the corner has an X–Y sign instead.
• The legend (bottom left) explains the colours.

Properties

The Properties panel on the right shows what is open, under a title:

• Job settings: the stock, the machine and the post.
• Preferences: the settings folder, whether a setup sheet is written with the G-code, updating the toolpath automatically, the units (mm or inch) and the colour theme.
• A post-processor: its name, files, extension, decimals, arcs and tool changes.
• Tools: every tool, with Add from library… and New tool; a tool alone, with how it stands to the library tool it came from, Save to library and Remove tool.
• A library tool or machine: its values, with Save and Revert while it has changes.
• A DXF: its file, units and size, its position and scale, Update from a DXF… and Remove.
• A picture: its width, lower-left corner and layer. A change applies when you finish the edit, and traces the picture again. Trace settings… opens its window.
• A part: its name, on or off, and its copies.
• An operation: its settings, under its kind and number (“Pocket · Operation 1”).

While shapes are selected, a Selection section comes first. It holds:

• what is selected, by contour number;
• a drawn shape’s exact values, to edit;
• Copy as selector, which copies the selection as JSON for a project file (also under DRAW ▾, and Ctrl+Shift+C).

Its triangle folds it away. While an operation is open there is no Selection section, so selecting shapes never moves the operation’s settings: its Use selection button counts what is selected (“Use selection (3)”), and its tooltip lists the contours. To edit a drawn shape’s values, open the project (Job settings) and select the shape. Nor is there one when the open DXF, picture or text is itself what is selected.

Making room for the canvas

• Narrower panels: drag the edge between a panel and the canvas. The Properties panel goes down to about 250 pixels: its labels and fields get narrower, a button or a note beside a field moves under it, and a long section summary ends in “…”.
• Folding a panel: drag its edge past its narrowest, or double-click the edge. It folds to a thin strip at the window’s side; the arrow on the strip opens it again.
• Both at once: P folds the Browser and Properties together for the largest canvas, and opens them again. Also in View: Show Browser, Show Properties, Fold both panels.
• The Report at the bottom folds with its triangle.

Units and coordinates

• Millimetres inside. Chipload works in mm throughout: the project and the toolpath. A drawing in inches is converted once, on import.
• G-code in mm or inches. G-code units (Job settings > Machine) says what the program is written in: mm (G21, the default) or inch (G20), as your controller is set. In inches every coordinate, arc centre and feed (in/min) is converted as the program is written, with 4 decimals, and the header says so. The project itself stays in mm. The checker reads the program in its own units and refuses one in other units than the machine’s, or one that changes units part way.
• A DXF’s units: Chipload reads them from the DXF’s own setting ($INSUNITS). A DXF that doesn’t say is never guessed at: the app asks for mm or inch, and the command line needs --units mm or --units inch. The choice is kept in the project, so updating from a new version of the DXF reads it the same way.
• Coordinates: X to the right, Y up, as in the drawing. Angles count counter-clockwise. The app shows them in degrees, and project files store them in radians (90° is 1.5707963267948966).
• Absolute moves: the G-code uses absolute coordinates (G90), in its units, from the work zero.

The canvas shows the cursor’s position in drawing coordinates and in work coordinates. View > Measure (M) gives the distance, ΔX, ΔY and the angle between two clicks.

mm or inches on screen

Units (Preferences, or the VIEW menu) says what the app shows and takes lengths in: mm, or inch. It is a setting of this computer, not of the project: a project is always stored in mm, so it opens the same for someone who works in the other units.

With inch:

• every length field shows inches with 4 decimals (0.2500 in) and takes inches. You can type a fraction, 1/4 or 1 1/2, or another unit: 6mm is turned into inches;
• feeds are in in/min and the chip load in in/tooth;
• the grid steps are inch fractions (1/32“, 1/16“, 1/8“, 1/4“, …) with a stronger line every inch, and clicks snap to them;
• the cursor position, Measure, the playback line and the setup sheet are in inches;
• a new project starts from inch values: stock 24“ × 12“ × 3/4“, safe Z 0.2“, 0.02“ below the stock allowed, and a 1/4“ endmill.

In mm, fields also take a length in inches: type 1/4in or 0.25".

On the command line a plain number is mm, as always, so scripts don’t change. A length can carry its unit: --height 0.5in, --diameter 1/4in, --at 1in,2in, --width 1 1/2in (quoted), --travel 30in,30in,4in; feeds --max-feed 200in/min. chipload run --sheet-units inch and chipload sheet --units inch write the setup sheet in inches. --json, get, set, the project file and the MCP tools are always in mm.

Messages follow the display units too: the report’s notes, the checker’s warnings, the problems on fields and in the Problems strip, and the setup sheet’s Watch out list (“cuts 0.0118 in below the stock”). On the command line they stay in mm, as its other output. The G-code’s units are a separate setting of the machine (above): you can show inches and send mm G-code, or the other way round.

Stock and work zero

Job settings > Stock describes the material on the machine, and Job settings > Machine says where the G-code’s zero is.

Stock

A new project from a DXF gets stock that just covers the drawing. If the drawing reaches past the stock (after an update, or a move), the report says so.

Work zero

Work zero X Y (under Machine) is the point of the drawing that becomes X0 Y0 in the G-code:

• the drawing’s origin, the default;
• a stock corner or the stock centre;
• any point, in drawing coordinates.

Only the G-code moves; the drawing and the canvas stay where they are. The canvas draws the X and Y axes at the work zero.

Every program says where its zero is in a comment at the top, e.g. (Work zero: stock center = drawing X150.000 Y110.000, Z0 = stock top), and so does the setup sheet. Set the machine’s zero exactly there.

Safe Z and travel

Under Machine:

• Safe Z: the height for every rapid move sideways, above the stock top. Make it clear of your clamps. Before a plunge the tool rapids down to 1 mm above the stock top, then feeds; it never rapids below the stock top.
• Travel X Y Z: the machine’s travel. When set, the checker refuses a program that moves farther than the machine can.
• Max feed: the fastest feed the machine takes. Feeds above it are refused, and the cycle time uses it for rapid moves.
• G-code units: mm (G21) or inch (G20), as your controller expects. Only the program changes; see Units and coordinates. Command line: chipload set part.chipload machine.gcode_units=inch, or --gcode-units inch on machine add and machine set.

Depths and oversize

Start and end depth

Every operation cuts from its start depth to its end depth, in mm down from the stock top, whatever the Z zero is.

• Rule: 0 ≤ start depth < end depth.
• Passes: the cut goes down in equal passes no deeper than the step down, and the last pass is exactly at the end depth. Start 2, end 6, step down 2 gives passes at 4 and 6 mm.
• Cutting through: an end depth below the stock bottom goes into the spoilboard. That’s allowed up to Max depth below stock (Job settings), with a warning; deeper is refused, so a typo can’t reach the machine bed. For 12 mm board, an end depth of 12.3 cuts 0.3 mm into the spoilboard. The Through button next to the end depth sets it to the stock thickness plus that allowance.
• Going down: from safe Z the tool rapids to 1 mm above the stock top, then goes down at the plunge feed. The air between the stock top and the start depth is crossed at the plunge feed too: Chipload doesn’t know whether another operation already cleared it.

Oversize

Oversize is how much more than drawn is cut, in mm: the cut moves into the material that is kept by that much. Positive removes more; negative leaves material. In the project file the field is clearance. Other CAM programs call the opposite “stock to leave” or “allowance”: there, a positive value leaves material.

• How: the tool’s centre runs at its radius minus the oversize from the drawn line.
• Limit: an oversize of the tool radius or more is refused. Use a profile on the line, or a smaller tool.
• Corners: inside corners of the kept material stay as round as the tool. Outside corners get rounded with the oversize as radius, because the tool reaches past them.
• Use:
  • a little positive oversize gives a fit, such as a lid that drops into its box;
  • a negative oversize leaves stock for a finishing pass (see also the profile’s finishing pass).

Side and direction

Side (profiles)

A profile cuts outside the line (the part is what’s inside), inside it (a hole: the waste is inside), or on the line (the tool’s centre follows it, like a slot).

When you add a profile, Chipload picks outside for outlines and inside for holes. For a selection with both, or with nothing to go by, it asks: the side is marked until you choose one. It never guesses which side is waste.

Direction

Climb or conventional, per operation:

• Climb: the cutter’s edge enters the material at full chip thickness. This gives a better finish and less rubbing on rigid machines, and is the usual choice on CNC routers.
• Conventional: the edge enters at zero chip thickness. It is gentler on machines with backlash.

What it means for the path. With the spindle turning clockwise (M3, Job settings > Machine > Spindle):

• climb goes clockwise round an outside profile and an island;
• climb goes counter-clockwise round an inside profile and a pocket’s walls.

Conventional, or a counter-clockwise spindle, turns each way round. The arrows on the canvas show the direction.

Tools and tool changes

The project’s tools

Tools in the Browser lists the tools the project cuts with; click it to see them all in Properties, or click one tool. Each has an id (T1, T2, …), which is the tool number in the G-code, and:

Each operation names its tool: pick it in the operation’s form, or on the command line chipload op tool part.chipload --op 2 --tool 3 (the tool must be in the project). Changing the tool keeps the feeds; check them. Tools usually come from your tool library: the project keeps its own copy, so it cuts the same later.

Tool changes

Operations run in the list’s order. A run of operations next to each other with the same tool is a tool group, and between groups the tool changes. The Browser draws a line at each change.

Tool changes (Job settings > Machine) says how a job with several tools is written:

• One file per tool: part-1-T1.nc, part-2-T3.nc, … Change the tool by hand between files, set Z zero with the new tool, and keep X and Y zero. Every post can do this.
• One file with tool changes (T2 M6): for a sender or controller that handles the change. Only posts that support it offer it (GRBL, whose sender must do the change).

The command line can override it for one run: chipload run part.chipload -o part.nc --tool-change program. The setup sheet lists the tools in the order they’re used.

The checker

Every program goes through an independent checker before Chipload writes it, in the app and on the command line. A program that fails isn’t exported.

What it is. The checker is separate code that shares nothing with the code that makes the toolpath. It reads the finished G-code line by line, as a controller would, and judges it against the project’s stock, safe Z and machine. Because it is independent, a bug in the toolpath code is likely to be caught by the checker, and the other way round.

What it refuses:

• a rapid (G0) down into the stock, or sideways while the tool is below safe Z;
• a cut deeper than the stock bottom plus Max depth below stock;
• moves beyond the machine’s travel, when the travel is set;
• an arc whose ends don’t lie on its circle, or an arc that is a full circle in one move;
• a cutting move with no feed, a zero feed, or the spindle off;
• relative (G91) coordinates, and motion before G21 or G20 and G90;
• a program in other units than the machine’s G-code units, or one that changes units part way (an inch program is read in inches and checked in mm);
• a tool change with the spindle running or below safe Z;
• any G or M code it doesn’t know (see Post-processors).

What it warns about:

• cuts into the spoilboard, within the allowed depth;
• travel limits that weren’t checked because the machine’s travel isn’t set.

On any G-code: chipload check part.nc --job part.chipload checks a file, also one made by another program, against a project’s stock and machine. With several tools, add --tool N to check one file of a set.

What it can’t know: your clamps and fixtures, the tool’s real length, whether the stock is really there, and whether the zero is set right. The safety rules still apply.

Importing a DXF

File > Import DXF… (Ctrl+I), or chipload import part.dxf -o part.chipload, makes a new project from a DXF. File > Open… also opens a .dxf directly. chipload inspect part.dxf shows what Chipload sees in a DXF without making a project.

Dropping files on the window:

• A .chipload project opens (after asking about unsaved changes).
• DXFs and pictures are added to the open project: each DXF as another drawing, each picture through its image window, one after the other. With no project open, the first starts one.
• The hint while you drag says which will happen.

What is read

• Read: lines, arcs, circles, polylines with arcs (bulges), splines and ellipses (turned into arcs within 0.01 mm), and blocks inserted with a move, turn or scale.
• Not supported: DWG files. Save as DXF in your CAD program.
• Layers are kept, and you can select by them: right-click a shape on the canvas selects its whole layer. In DXF, layer names don’t care about upper or lower case.
• Closed shapes are read as drawn: a closed polyline, a circle or a closed spline is one closed contour, even where other shapes touch it or share its edges. A pocket drawn against the part’s outline leaves both whole.
• Joining: loose lines and arcs whose ends meet (within 0.001 mm) are joined into contours, only with others on the same layer:
  • closed, for profiles, pockets and V-carving;
  • open, for follow path; profiles and pockets skip them with a note.
• Outer and hole: each closed contour is an outer (outline) or a hole (inside another), which sets the default side of a new profile.
• The project keeps the geometry itself. The DXF isn’t needed afterwards, unless the drawing changes (Updating from a new DXF).

The import report

Chipload reads the drawing as drawn: as little repair as possible, and nothing dropped without saying so. The report under the canvas (and from inspect) lists:

Crossing contours are fine. Two shapes that cross, such as a pocket cutting through a part’s outline to make an opening, are separate shapes, each cut on its own. Chipload never merges them.

Centre lines and other open lines on a cutting layer don’t stop a profile or pocket on that layer: they’re skipped, with a note.

Units

If the DXF doesn’t say whether it’s in mm or inches, Chipload asks (command line: --units mm or --units inch). See Units and coordinates.

New project defaults

The stock just covers the drawing, 10 mm thick:

• its bottom-left corner sits at the drawing’s origin when the drawing lies right of and above the origin;
• otherwise it is centred on the origin.

The machine and tool come from your default machine profile and tool if you have them. Otherwise you get GRBL, a safe Z of 5 mm, and a 6 mm endmill at 18 000 rpm.

Placing the drawing

The imported drawing can be moved, turned by any angle and scaled on the stock, without changing the DXF. In the app, click the DXF in the Browser: its Position, rotation and scale are in Properties.

Each row has a reset button: the position back to where the DXF has it, rotation 0, scale 1. A change applies when you finish the edit (Enter, Tab or releasing a drag), as one undo step.

On the command line, chipload place (for a picture, --image ID with --at, --rotate and --width):

• Order: a turn and a scale come before an alignment, so --rotate 90 --align bottom-left turns the part and then puts it in the corner.
• Saved as values: the placement is kept in the project, and updating from a new DXF puts the new drawing in the same place.
• What follows: operations follow the drawing, and their start points move with it.
• Arcs: scaling and turning keep arcs exact. Turns by 90°, 180° and 270° are exact to the bit; other angles are as exact as the computer’s arithmetic.
• Where it is now: chipload place part.chipload with no option prints the placement and size.

Shapes drawn in Chipload aren’t part of the imported drawing and stay where they are. With several DXFs, each is placed on its own: --dxf ID says which.

To have the G-code’s zero somewhere else, without moving anything, set the work zero instead.

Updating from a new DXF

When the drawing changes, File > Update drawing from DXF…, or chipload update part.chipload --from part.dxf, takes in the new version and keeps the operations.

• Same shape, same id: shapes are matched by their DXF handle, the DXF’s own id for each entity, which CAD programs keep when you edit. An operation that selected a shape keeps it.
• Placed as before: the new drawing gets the same move, turn and scale.
• Drawn shapes stay: shapes drawn in Chipload are kept, with their ids.
• Several DXFs: --dxf ID says which one the new file replaces; the others stay as they are (Several drawings).
• The report lists what’s unchanged, changed, added and removed, and what that means for each operation:
  • geometry changed; check its toolpath;
  • layer X now uses the updated drawing;
  • shapes … no longer exist; choose its geometry again: the operation can’t run until you give it geometry again. The command line exits with 1 in that case.
• Units: taken from the last import. --units overrides them, if the new DXF is different.
• Stock: the stock isn’t changed. If the drawing now reaches past it, the report says so.

An empty project (File > New project, chipload new) takes its first DXF the same way: File > Import DXF into project….

A DXF saved by a program that gives every entity a new handle on each save makes every shape look new. Operations that select by layer survive that; ones that select single shapes need their geometry chosen again.

Several drawings

A project can hold several DXFs, for example two parts cut from one sheet, besides its images and the shapes you draw. Each DXF has its own place, turn and scale, and is updated from its own file.

chipload dxf add part.chipload lid.dxf --name lid     # a second DXF, where its file has it
chipload dxf list part.chipload                       # id, name, file, placement, size
chipload place part.chipload --dxf 2 --by 250,0       # move, turn or scale that one
chipload update part.chipload --from lid.dxf --dxf 2  # a new version of that one
chipload dxf remove part.chipload 2                   # it and its shapes

In the app: File > Add DXF to project…, or drop the DXF on the window.

In the Browser

The Drawing folder of the Browser lists what the project’s shapes come from:

• Each DXF, with its layers inside.
• Each image.
• The shapes drawn in Chipload, by kind: rectangles, circles, polylines.

• A click selects the whole group, or one layer of one DXF; Ctrl+click adds. An operation added from it cuts only that (its selector names the DXF or image). A DXF or picture also shows its properties: position and scale, or size and place.
• Right-click has the rest:
  • For a DXF: Place… (its properties: Placing the drawing), Update from a DXF… or from a path…, and Remove.
  • For an image: Trace settings… (also a double-click) and Remove.
• The eye hides a group or a layer on the canvas: it isn’t drawn and can’t be clicked. Hidden shapes are still cut. An operation that cuts some says so on its row (“3 hidden · T1”), and its toolpath still shows. To stop cutting them, untick the operation.
• Saved: what is hidden is saved in the project (drawing.hidden). Changing it is a step you can undo.

File > Update drawing from DXF… works while the project has one DXF. With several, update each from its row’s right-click menu.

• Where it goes: a new DXF lands where its file has it, often on top of the first. Place it afterwards.
• Which one: with several DXFs, place and update need --dxf ID. With one, they work as before.
• Name: the file’s name without its extension, unless you give --name. A second copy of the same file is named “part 2”.
• Removing a DXF removes its shapes. The report names the operations that used them; they can’t run until you give them geometry again.

What an operation selects

An operation selects a DXF or image as a whole, a layer within one, or shapes:

"select": {"dxf": 2}                       // all of part B, whatever its layers
"select": {"dxf": 2, "layer": "HOLES"}     // part B's holes
"select": {"image": 1}                     // a traced picture
"select": {"image": 1, "exclude": [863]}   // the picture but one of its shapes
"select": {"shapes": [12, 14]}             // these shapes

A DXF or an image selected as a whole, or one of its layers, follows the DXF when it is updated and the picture when it is traced again. In the app:

• A click on a DXF or image in the Browser picks the whole DXF or image.
• A click on a layer in the Browser, or right-click Select layer on the canvas, picks that layer of that DXF only.
• Leaving some out: with a whole DXF or picture selected, Ctrl+click a contour on the canvas to leave it out, and again to put it back. The selection then reads “image 1, 1 left out”, and the operation’s selector gets exclude.

When a picture is traced again (a new size, place or setting), its shapes get new numbers. Left-out shapes are found again by where they sit in the picture, and the report says so. One that can’t be found (the tracing changed too much) gives a problem, and nothing is generated until you pick the shapes to leave out again. Ctrl+Z undoes the retrace.

Adding a DXF never changes what an existing operation cuts. An operation that selected a layer by its name alone, made while the project had one DXF, keeps cutting that DXF when the new one has the same layer. The report says so: Operations 1, 2 keep cutting part only.

A selector with a layer and no DXF (written by hand, or by Chipload before 0.16) means that layer in every DXF. When a layer is in more than one, the report says so: layer “HOLES” is in lid and part; it cuts all of them.

The setup sheet lists every DXF and image with where it was put, when there is more than one.

Drawing shapes

Chipload draws three kinds of shape, for the odd hole, slot or outline that isn’t in the DXF, or a project without one:

• Circle: centre and radius.
• Rectangle: centre, length and width, a rotation, and a corner radius (0: sharp corners).
• Polyline: points joined by straight or arc segments, open or closed.

Circle, Rectangle or Polyline in the ribbon’s DRAW group, then click on the canvas. Clicks snap to the drawing’s ends, centres and middles, else to the grid, whose step the status bar gives (“grid 1 mm”). Anything more is CAD’s job: draw it there and import the DXF.

Editing

• Handles: drag a selected shape’s handles to change it. A drag snaps to end points, centres and middles; hold Alt to turn snapping off.
• Exact values: under Selection in the Properties panel, a selected shape has its exact numbers and its layer.
• Rounded corners: a rectangle’s Corner radius rounds all four corners with true arcs (G2/G3 in the program). It can be at most half the shorter side: half of it rounds the short ends fully, into a slot. A larger radius is refused rather than shrunk, and a corner handle won’t drag the rectangle smaller than its corners allow; lower the radius first. The reset button makes the corners sharp again.
• Move, turn and size: select a polyline, or several drawn shapes (Ctrl+click), and a dashed box shows round them: drag the square in the middle to move them, the round handle beyond the right side to turn them (in steps of 15°; hold Alt for 0.1°), a corner to scale them evenly, the opposite corner staying put. One circle or rectangle keeps its own handles instead. The shapes keep their ids, so the operations that cut them follow, and so do the operations’ start points, corner choices and tabs placed by hand on them (also with shape move, turn and scale, and when you change one shape through its own handles or form: a corner’s choice stays with that corner of a rectangle you move or resize).
• Position and Turn: a selected polyline’s form, and the Selection section when several drawn shapes are selected, have Position (the lower-left corner of the box round them: type a value to move them there) and Turn: ⟲ 90, ⟳ 90, or type an angle and press Enter. A polyline keeps no angle of its own; turning moves its points.
• In the Browser: under Drawing, the Circles, Rectangles and Polylines groups list their shapes, in a folder per layer when there are several. Click a row to select the shape (Ctrl+click adds or removes); right-click to rename, copy or delete it. A group with more than 20 shapes starts closed.
• Names: give a drawn shape a Name in its form (or Rename… in the Browser); the Browser shows it, with its number beside it. Empty: it’s shown by its number. Copies start without a name.
• Copy and paste: Ctrl+C and Ctrl+V. Draw > Paste puts the copy 10 mm right and up; Ctrl+V over the canvas pastes at the cursor.
• Mirror: Draw > Mirror left–right and Mirror up–down flip shapes about the middle of their box.
• Delete: Del. Operations that cut the shape are flagged.
• Undo: Ctrl+Z.

Imported shapes can’t be edited: they change only with the DXF, unless you explode it. Lines whose ends almost meet can be joined into one shape with Draw > Join ends… (same page).

On the command line

chipload shape add part.chipload circle --center 40,30 --radius 5 --layer HOLES   # prints its id
chipload shape add part.chipload rectangle --center 80,30 --length 40 --width 10 --angle-deg 15
chipload shape set part.chipload 9 --corner-radius 3  # round the rectangle's corners
chipload shape add part.chipload polyline --points "0,0 50,0 50,20" --bulges "0 1" --open
chipload shape set part.chipload 8 --radius 6         # change a value or the layer
chipload shape set part.chipload 8 --name "Lid"       # its name in the Browser ("" takes it away)
chipload shape copy part.chipload 8 9 --dx 25 --dy 0  # copies, with new ids
chipload shape mirror part.chipload 8 9 --axis x      # flip in place; ids kept
chipload shape move part.chipload 8 9 --dx 10 --dy -5
chipload shape turn part.chipload 8 9 --angle-deg 30  # about the middle of their box (or --about X,Y)
chipload shape scale part.chipload 8 --factor 1.5
chipload shape remove part.chipload 8
chipload shape join part.chipload --gap 0.05   # join ends that almost meet

Bulges are as in DXF: tan(sweep / 4), 0 straight, 1 a counter-clockwise half circle, −1 clockwise.

Exploding a DXF, joining ends

A DXF’s shapes are read-only: they change only when the DXF is updated. To rework them in Chipload, explode the DXF: its shapes become drawn shapes, with handles, values you can type, copy, mirror and delete, like the ones you draw.

Explode

Right-click the DXF in the Browser, Explode into shapes…, or Explode… in its properties.

• The project forgets the DXF file. It leaves the Browser, and Update from DXF is no longer possible for these shapes. Ctrl+Z undoes it until the project is saved; after that, the only way back is adding the DXF again.
• Circles stay circles; everything else becomes a polyline of straight and arc segments. An arc of more than half a circle becomes two segments.
• Operations keep cutting the same shapes, with the same G-code. The shapes keep their ids and layers. An operation that selected a layer of that DXF now selects its shapes by number, so a layer of the same name elsewhere doesn’t join in; the report lists these.
• Circles that the placement turned start at their right-hand point afterwards, as every drawn circle does, so the cut may start elsewhere on them. The report names them.

Tick Join ends closer than to join the exploded lines straight away (below).

Join ends

A drawing made of separate lines and arcs whose ends almost meet can’t be pocketed: each piece is an open contour. Draw > Join ends… joins open drawn polylines whose ends lie closer than the gap into one, and closes a chain that comes back to its start.

• The selected shapes, or every drawn shape when none is selected.
• Gap: 0.01 mm unless you type another, at most 1 mm. Both ends move to the point between them; a shape moves by at most half the gap.
• Same layer only. Pieces on different layers stay apart.
• Only clear pairs. Where three or more ends meet within the gap, nothing joins there: which way the outline goes would be a guess. The report gives the point.
• The joined shape keeps the lowest id of its pieces; operations that selected any of them select it.
• The report says how many shapes became how many, the widest gap closed, and the ends still open with the distance to the nearest other end: the gap that would close them.

On the command line

chipload dxf explode part.chipload                  # the project's only DXF
chipload dxf explode part.chipload 2 --join 0.05mm  # DXF 2, then join ends closer than 0.05 mm
chipload shape join part.chipload                   # every drawn shape, gap 0.01 mm
chipload shape join part.chipload 12 13 14 --gap 0.1

With --json, shapes lists the shapes that came of it and removed those joined into others.

Images

A picture, such as a logo, a scanned sketch or lettering, can be traced into shapes and then V-carved. Chipload turns it black and white, traces the edges between black and white, and puts the outlines on a layer of their own.

A picture of strokes, such as handwriting, a signature or line art, can instead be traced into the strokes’ centre lines and cut with a follow path.

Black is what gets carved: for a V-carve, black is the inside of the shapes. A light logo on a dark background needs invert.

PNG, JPEG and BMP pictures work, up to 20 MB and 20 megapixels. The picture is stored in the project, so its settings can be changed later.

Size and place

A new picture comes in half the stock’s width, with its lower-left corner at X0 Y0. Click it in the Browser (it is selected right after importing) for its properties:

• Position: the lower-left corner of its box, mm;
• Rotation: degrees counter-clockwise, any angle, about its centre, with ⟲ 90 and ⟳ 90. The picture is traced as it is and its shapes are then turned, so the trace doesn’t change; on the canvas the picture is drawn turned too;
• Width in mm; its height follows from the picture. Chipload doesn’t use the picture’s DPI, which is often missing or wrong.

On the canvas: with the picture selected, its box shows handles (in top view):

• the square in the middle moves it;
• the square beyond its right side turns it about its centre, in steps of 15°;
• a corner square makes it larger or smaller, keeping its proportions; the opposite corner stays where it is. Its width is rounded to 0.1 mm.

The box follows the cursor while you drag, and the picture is traced again when you let go, as one undo step. Hold Alt for no steps (any angle, any size) and no snapping.

On the command line, give --width, --at (the picture’s corner before it is turned) and --rotate.

Black and white

The traced shapes

• Smooth edges: the edge is traced where the blurred grey crosses the threshold, between pixel centres, so there are no pixel steps.
• Always valid: the outlines are always closed and never cross. A white part inside a black one is a hole, as in a pocket.
• Picture border: black that reaches the picture’s edge is closed along it, with a note: usually a background that wants invert.
• Too many shapes: a picture that traces into more than 5000 shapes (a photo, noise) is refused. Blur it more, raise the smallest piece or change the threshold.
• Arcs: with arcs on, the edges are fitted with arcs as well as lines, still within the smoothing: a traced logo becomes a few dozen pieces instead of hundreds of short lines. A profile, pocket or follow path of them is then cut with G2/G3 arcs: a smaller program, and smoother motion, since a controller slows down at every short line. A V-carve gains little: its moves are lines anyway. An outline whose arcs would come too near another one is kept as lines, and the report says so.
• Not editable: the shapes can’t be edited in Chipload.

Changing a setting traces the picture again and replaces its shapes, which get new ids. So an operation selects the image as a whole ("select": {"image": 1}), never its shapes one by one: Chipload refuses an operation that selects traced shapes by id.

The drawing’s placement moves only the DXF’s shapes, never a traced picture; a picture has its own X, Y and width.

Centre lines

With Trace: centre lines, each black stroke becomes a path along its middle: open, or closed for a ring like an O. A follow path cuts each stroke in one pass at the depth you choose, as wide as the bit, whatever the pen did. Select the image and Follow (ribbon, OPERATION).

• Junctions: where strokes meet (a T, a Y), their paths end at the same point.
• Ends: a path stops half a stroke’s width short of a round stroke end, at the middle of its curve, so a bit as wide as the stroke reaches the end. Small side branches from a rough edge or a square corner are tidied away.
• Stroke width: the report gives the strokes’ width (“Strokes 2.9 to 3.2 mm wide”), to pick a bit by.
• Dots (the point of an i, a full stop) are too small for a centre line. They are left out and counted in the report.
• For strokes only: a filled area’s centre line is a branching skeleton. That is correct, but rarely what you want; a wide range in the stroke widths shows it.
• Closed lines are outlines too: an outline drawn by hand and scanned traces as one closed centre line, and a profile or pocket can cut round it like any outline. The report says how many lines are closed.
• Open lines only for a follow path: a profile, pocket or V-carve of a picture whose centre lines are all open is refused, with a hint to use a follow path or trace the image as outlines. With both kinds, the open lines are skipped, with a note.

In the app

File > Import image… picks a picture and opens its window. A project is made first if none is open. Without a file dialog (see Install), File > Import image from path… takes the picture’s path instead.

• Left: the picture as black and white, updated as you change the settings: the dark parts are what is traced. With centre lines, the lines are drawn over it in orange. Scroll over it to zoom in at the pointer, up to 32 times, drag to move about, and double-click to see all of it again.
• Right: the conversion settings, and what was traced (with the threshold auto picked). The size, place and layer are not here: they are the picture’s properties.
• Import: puts the shapes into the project and selects the image, so V-carve carves them (or, for centre lines, Follow cuts them). It is one undo step.

Afterwards:

• Move or resize it: click it in the Browser and change its position, rotation, width or layer in Properties.
• Trace it differently: double-click it, or right-click it > Trace settings…: the same window opens (its button says Apply).
• Remove it: right-click > Remove removes the picture and its shapes.
• See it: Images on the canvas’s navigation bar (or View > Show images) shows the pictures faintly on the stock top, over the simulated stock and under the drawing, in top view and 3D, for comparing the traced shapes, and the cut, with the picture.
• Leaving shapes out: with the picture selected, Ctrl+click a shape to leave it out of the operation (What an operation selects).
• Operations: clicking traced shapes on the canvas and adding an operation selects the whole image, not the shapes.

On the command line

chipload image add part.chipload logo.png --width 120 --at 10,10 --threshold auto
chipload image add part.chipload signature.png --width 80 --trace centre-line
chipload image set part.chipload 1 --threshold 140 --blur 2 --invert true --arcs false
chipload image set part.chipload 1 --rotate 30         # turned 30° about its centre
chipload place part.chipload --image 1 --at 10,10      # as for a DXF: --at, --rotate, --width
chipload image list part.chipload
chipload image preview part.chipload 1 -o bw.png
chipload image remove part.chipload 1

• image add: the layer is the file’s name unless --layer says otherwise. It reports how many shapes were traced, the threshold, the specks dropped, and whether black touches the border; for centre lines also the stroke widths and the dots left out.
• image preview: writes the black-and-white picture exactly as it is traced.
• chipload set: also reaches the settings (drawing.images.0.threshold=140). The image is then traced again, as with image set, also for --set on a single run.

In the file

drawing.images in the project file: id, file, sha256, data (the picture, base64), layer, x, y, width, threshold (a number or "auto"), invert, blur, min_area, smoothing, trace ("outline" or "centre_line"), arcs. The traced shapes are path shapes with "image": id. Images in projects from Chipload 0.15 open as outlines without arcs, exactly as they were traced.

Text

Write a name, a label or a sign straight into the project: Chipload turns the letters into shapes that you V-carve, pocket or cut out with a profile. (Design: docs/specs/text.md.)

Writing a text

1. Draw > Text in the ribbon (or DRAW > Text), then click on the canvas where the text should start. That point is the lower-left corner of the text’s box; set Anchor to centre afterwards to keep it centred on a point instead.
2. A text saying “Text” appears there, selected, with its properties open and the text field ready: type what it should say. Enter starts a new line. The letters are made again when you click elsewhere.
3. With the text selected, V-carve (or Pocket, Profile) in the ribbon cuts it. A new V-carve takes a V-bit from the project if it has one.

Esc stops placing a text.

Properties

Click the text in the Browser (under Drawing, with an A) or one of its letters on the canvas:

• Text: what it says, on one or more lines;
• Font: one of the built-in fonts (below);
• Height: the height of a capital letter, mm; what a ruler measures on an H;
• Anchor: what Position is: the lower-left corner of the text’s box, or its centre. A centred text stays centred when you change its words, font or size, which is handy for a name in the middle of a sign. Changing the anchor doesn’t move the text;
• Position: the anchor’s place on the stock, mm;
• Rotation: degrees counter-clockwise, any angle, about the box’s centre, with ⟲ 90 and ⟳ 90;
• Align: how lines line up: left, centre or right;
• Letter spacing: extra space between letters, mm; 0 keeps the font’s own spacing, kerning included (in a serif font, “AV” sits closer than “A V”);
• Line spacing: from one line’s base to the next, in capital heights (1.6 by default);
• Layer: the layer its letters go on (text by default);
• Size: the box’s width and height, for reference.

Each change applies when you finish the edit, as one undo step: Ctrl+Z brings the earlier text back. An operation that selects the text follows the change.

On the canvas: with the text selected, its box shows handles (in top view):

• the square in the middle moves it;
• the square beyond its right side turns it about its centre, in steps of 15°;
• a corner square makes it larger or smaller, keeping its proportions; the opposite corner stays where it is. Its height is rounded to 0.1 mm.

The box follows the cursor while you drag, and the text is written again when you let go, as one undo step. Hold Alt for no steps (any angle, any size) and no snapping.

Fonts

Chipload has 17 fonts built in, so a project writes the same letters on every computer. The Font list groups them and shows each name in its own face; chipload text fonts lists them with their style.

• Plain: FreeSans, FreeSerif and FreeMono, each also bold (GNU FreeFont), and Roboto Slab and Roboto Slab Bold.
• Script: Satisfy, Yellowtail and Rochester, handwriting with joined letters.
• Display: Luckiest Guy, Ultra, Chewy, Smokum, Cherry Cream Soda and Permanent Marker, bold and decorative, for headings and signs.

They all have the Latin letters with accents (Å, Ä, Ö, É, Ñ, Ø, …), digits and the common symbols (€, °, ±; ⌀ only in some of the FreeFont faces). A character a font lacks is left out, and the report names it.

Joined letters: where letters overlap, as in a script where one letter runs into the next, or where a letter is drawn as overlapping strokes, Chipload joins them into one outline, so a pocket or V-carve sees clean shapes. Holes stay holes where nothing covers them. Letters that don’t overlap anything keep the font’s exact outline.

Choosing: serif fonts V-carve beautifully: the V-bit cuts the thin strokes shallow and the thick ones deep. The scripts V-carve well too. For a pocket or a profile, a font with even, sturdy strokes works best (FreeSans Bold, Roboto Slab, Ultra, Luckiest Guy, Chewy); Smokum’s pointed serifs need a pocketing tool of 2 mm or more.

Licences: GNU FreeFont is under the GPL with the font exception, the others under the Apache License 2.0. Neither puts any condition on what you make: the letters you cut and their G-code are yours.

In the project file

A text is stored with what it says and how, and its letters are stored as shapes too. So the font is needed only to change the text; a project cuts the same whatever the computer has installed. Chipload 0.19 and older can’t open a project that has a text.

Leaving letters out

As with a picture: with the whole text selected, Ctrl+click a letter (or one part of it, such as the hole of an O) to leave it out of the operation, and again to put it back. A left-out letter is found again when the text changes size, place or font.

Command line

chipload text add sign.chipload "MAKER\nSPACE" --height 20 --at 40,30 --font "FreeSerif Bold" --align center
chipload text set sign.chipload 1 --rotate 15 --spacing 1     # change it; its letters are made again
chipload text set sign.chipload 1 --anchor center --at 85,55  # centred on X85 Y55, and stays centred
chipload place sign.chipload --text 1 --at 10,10 --height 25  # its corner, turn and height
chipload text list sign.chipload
chipload text remove sign.chipload 1
chipload text fonts

\n in the text starts a new line. An operation selects the text with "select": {"text": 1}, and any value can be changed with chipload set (drawing.texts.0.text="SIGN"); the letters are made again.

Copies

Each part can be cut several times, in a grid of its own: click the part in the Browser and set Copies in its properties, or use chipload copies. With several parts, give --part.

chipload copies part.chipload --grid 3x2 --gap 10     # 3 columns, 2 rows, 10 mm between cuts
chipload copies part.chipload --grid 3x2 --pitch 120,80
chipload copies part.chipload --order by-copy         # every operation on one copy, then the next
chipload copies part.chipload --off                   # one copy again
chipload copies part.chipload --part 2 --grid 2x1 --gap 10   # with several parts

• Pitch: the distance from copy to copy. Gap works the pitch out from the part’s real cut, tool included, so the cuts of neighbours stay that far apart. A negative pitch grows the grid left or down.
• Order:
  • by operation (the default): each operation on every copy, then the next, so tool changes happen once;
  • by copy: every operation on one copy, then the next (called by part before Chipload 0.17; --order by-part still works).
• Checked:
  • every copy is planned and checked like the original;
  • copies whose cuts would overlap each other, or another part, are refused;
  • copies have to fit the stock and the machine like anything else.
• Limits: up to 100 columns or rows, and 1 000 copies.
• Display: the canvas draws the copies faded: each part’s copies of the shapes it cuts. The setup sheet and the playback say which copy is being cut.

Copies don’t turn, and they aren’t nested. To fit different parts on one sheet, give each its own part and grid, or arrange them in CAD.

Parts

The operations of a project are grouped into parts. A part is a name, the operations that cut it, its copies, and an on/off switch. Most projects have one part. Use several when one sheet holds different things, for example 4 lids and 2 boxes.

• What a part cuts: its operations select shapes, DXFs and layers as usual. A part owns no geometry, so one DXF with a layer per part can feed several parts.
• Order: part by part. Each part is cut with all its copies before the next one starts, and within a part its operations run in order. Operations are numbered across the whole project (1, 2, 3 …), as the G-code comments and the report number them.
• Tool changes: a tool used in two parts is changed back for the second part. Two parts that each use T1 and then T2 change tool three times. The report counts the changes.
• Off: a part that is off is left out with all its operations.
• The active part: new operations go into it. Adding a part makes the new one active.
• Seeing one part: with two parts or more, Generate, the automatic update, the simulation and playback show only the active part, so a change to part 2 doesn’t plan part 1 again. The status bar says “part 2 of 2 · cycle …”. All parts on the canvas bar shows every part.
• Export always writes every part that is on. When only the active part is shown, Export plans the whole project first, then writes it.
• Stock: all parts share the project’s stock and work zero. Parts cut from a different material belong in another project.
• Safety:
  • Copies of a part must not cut into each other.
  • A copy must not cut into another part. The parts as drawn may overlap, for example an engraving over a cut-out.
  • Overlaps are refused.
• In the G-code: with two parts or more, a comment marks where each part starts: (Part 2: box, 2 copies).

chipload part list part.chipload                        # id, name, copies, operations
chipload part add part.chipload --name box              # an empty part, now active
chipload op part part.chipload --op 4 --part 2          # move operation 4 into part 2
chipload copies part.chipload --part 2 --grid 2x1 --gap 10
chipload part set part.chipload 2 --name lid --off      # rename, turn off (--on)
chipload part activate part.chipload 1
chipload part remove part.chipload 2 --with-operations  # without the flag: refused while it has operations

In the app, the Browser lists the parts with their operations. Click a part to see its copies in Properties. Right-click it to activate, move or delete it, or right-click Parts for a new one. Drag an operation onto a part to move it there.

Profile

A profile cuts along a closed contour:

• outside it, to cut a part out;
• inside it, to cut a hole;
• on the line.

Select the contours, then Profile (ribbon, OPERATION). See Side and direction and Depths and oversize for what every profile shares.

Open contours (centre lines, construction lines) in the selection are skipped with a note. To cut along an open line, use Follow path.

The spiral ramp

A profile always goes down as one forward spiral along the contour: no plunge into the part, so there is no plunge mark, and any endmill can cut it, centre-cutting or not. In the operation’s Cut settings, right after the step down, the ramp angle (3° by default, at most 30°) says how steeply:

• each pass goes down at the ramp angle, then runs level for the rest of its lap, and never more than one step down per lap (on small contours the angle alone decides, so a pass may take more than one lap);
• at the end only the ramped stretch is cut level, so the floor is flat;
• the tool rises out along the cut path, never back and forth.

A steeper angle makes the ramp shorter: 4 mm at 3° takes 76 mm of contour, at 10° 23 mm. In the file the angle is ramp_angle, in radians.

Holding the part

Holding chooses how a part that is cut out stays in place: none, tabs, onion skin, or onion skin and tabs. Only the chosen kind’s settings show.

• Tabs keep the part attached at a few points until you cut it free.
• An onion skin holds it all round during the roughing; the last lap then cuts through the skin, and the part is free during that lap.
• Both: the skin holds it all round during the roughing, and the tabs keep it from moving while the last lap cuts through the skin.

Tabs

Tabs are bridges of material left at the bottom of the cut, so a part cut out doesn’t come loose on the last pass.

• Placement: tabs slide off corners to straight stretches, by up to a quarter of their spacing.
• Spacing: they keep a tool diameter from each other and from the start of the contour.
• Shown highlighted on the canvas.

Tabs placed by hand

You can put a contour’s tabs where you want them instead. Select the profile after generating: each tab has a small square on the canvas, hollow where Chipload spaced it and filled where you placed it.

• Drag a tab along its contour; it generates again when you let go.
• Right-click a tab to remove it, or to space that contour’s tabs evenly again.
• Right-click the contour’s toolpath for Add a tab here.
• Under Tabs in Properties, 5 tabs placed by hand counts them, and Reset spaces every contour’s tabs evenly again. Each change is one undo step.

On the command line, list them and add or remove one at a point on (or near) the contour:

chipload op tabs part.chipload --op 2
ring 1  (146.551, 132.176)  spaced
…
chipload op tab part.chipload --op 2 --at 162,91            # add one
chipload op tab part.chipload --op 2 --at 146.5,132 --remove
chipload op tab part.chipload --op 2 --at 162,91 --even     # this contour spaced evenly again
chipload op tab part.chipload --op 2 --reset                # every contour

• The first tab you add or remove on a contour keeps its other tabs where Chipload had put them; from then on that contour has exactly the tabs you placed, and count is for the contours you haven’t touched.
• A tab placed by hand stays where you put it, also on a corner (the report notes it).
• Generating stops, naming the tab, if two tabs come closer than their width plus two tool diameters, if a tab covers the contour’s start (move the tab or the start), or if a tab is no longer on any contour of the operation (the drawing changed).
• The points move with the drawing when you place it or move, turn or scale the drawn shape, and every copy gets them. In the file they are tabs.at, points in drawing coordinates.

Start point

Each contour’s cut starts at a point Chipload picks. To move it, select the operation, then drag the start marker along the contour on the canvas; right-click the marker to reset it. Tabs Chipload spaces move with the start; tabs placed by hand stay. In the file, starts holds the points.

Finishing pass

Finishing pass with a stock value:

• the roughing laps leave that much on the wall;
• one light lap at the wall at full depth then takes it off.

The wall comes out clean: the tool isn’t loaded on that lap, so it doesn’t deflect, and there are no step marks from the passes. The stock must be less than the tool radius.

Onion skin

Onion skin with a thickness:

• the passes stop that far above the end depth;
• one last lap cuts through the skin.

Small parts stay held until the very end, on a vacuum table or instead of tabs. The skin is at most one step down, and thinner than the tab height when there are tabs (onion skin and tabs under Holding).

Dogbones and T-bones

A round tool leaves a fillet of its radius in every inside corner, so a square tenon won’t go into the mortise. Corners reaches into them:

• dogbones: the tool goes into the corner along its bisector;
• T-bones: the tool goes in along the longer wall, so the notch is in the shorter wall, out of sight.

up to sets the sharpest corner angle that gets one (100° by default, so 90° corners drawn slightly off count). A corner the tool can’t reach at all (a notch narrower than the tool) is left round, with a note.

A bone that also cuts into another contour that is cut (a thin wall between this cut and another), or into another wall of its own (a short step next to the corner), is cut all the same, with a warning that names the corner: check the part there, or choose another bone for that corner. Lines that don’t count:

• lines no enabled operation cuts (construction lines, a layer nothing cuts, a disabled operation’s shapes);
• a line that meets what the operation cuts near the bone: on its own wall (a shared edge), crossing it, or, in a pocket, running into the pocket. It has been cut through there already.

Corner by corner

Any corner can have its own choice, whatever Corners says: round, dogbone, T-bone along the longer wall or T-bone along the shorter wall. It goes past up to too. So you can turn one T-bone the other way, leave out the one corner where a bone doesn’t fit, or leave Corners on round and give bones only to the corners that need them.

With the operation selected, every corner on the tool’s side has a small diamond on the canvas: filled, with the tool’s circle where its bone goes, when it gets one; hollow when it stays round; amber when the last generation’s tool couldn’t reach into it. A ring round the diamond marks a corner with its own choice. Click a diamond (or right-click it) for its menu: As the operation, Round, Dogbone, T-bone along the longer wall, T-bone along the shorter wall. Hovering an entry draws its bone; clicking it generates again. Each choice is one undo step. Under Corners in Properties, 2 corners chosen one by one counts them, and Reset gives every corner the operation’s setting again.

On the command line, list an operation’s corners and what each gets, then choose:

chipload op corners part.chipload --op 2
(11.214, 301)  90.0°  dogbone
(511.214, 301)  90.0°  dogbone
…
chipload op corner part.chipload --op 2 --at 11.214,301 --bone tbone --along shorter
chipload op corner part.chipload --op 2 --at 511.214,301 --bone none
chipload op corner part.chipload --op 2 --at 511.214,301 --as-operation   # its choice removed
chipload op corner part.chipload --op 2 --reset                           # every choice removed

A choice is kept as the corner’s point on the drawing, as start points are, and moves with the DXF when you place it. Every copy gets it. If the drawing changes so a chosen corner is gone, generating stops and says which choice to remove. The setup sheet says how many corners were chosen one by one.

In the file

"type": "profile" in the project file. Lengths are in mm, feeds in mm/min, angles in radians.

Pocket

A pocket clears everything inside closed contours, down to the end depth, leaving islands standing. Select the contours, then Pocket (ribbon, OPERATION).

What gets cleared

• Each selected outline is its own pocket. Two that cross are cleared separately and never merged: the second cuts air where they overlap.
• Islands: a selected contour wholly inside a pocket is left standing. A contour inside an island is a pocket again.
• Not selected, not counted: contours that aren’t selected don’t matter, even inside a pocket. A circle you’ll drill later doesn’t become an island.
• Same shape twice: two selected contours that are the same shape are refused, since one can’t be both outline and island.

Rings

The pocket is cleared in rings:

• Order: rings are offsets of the walls, cut from the centre outwards, with the wall ring last at each depth. Round islands, each island’s rings are cut one after another, out to the island, before the next island’s, so the tool doesn’t cross the pocket between rings. Where an island is close to the wall (less than a tool diameter), its rings and the wall’s take turns there, so no ring meets more than a stepover of material.
• Stepover: the distance between rings, as a fraction of the tool diameter (0.4 by default).
• Rounded inner rings: every ring but the wall ring has rounded corners (up to two stepovers in radius), for smoother, faster motion. Where rounding would leave material, the corners are rounded less.
• Spiral: each ring steps out onto the next over its last stretch instead of closing, so the rings of a lobe are one continuous spiral with no stop and no sideways move into material. Round an island, its rings spiral out towards it the same way. The stepped-out stretch is checked against the walls and islands like a ring; where it wouldn’t fit (against a sharp corner, or onto a ring with a lead or a chosen start) the ring closes and is linked.
• Links: where a ring closes, the tool feeds across to the next at depth when the move stays clear of the walls and is at most one tool diameter, which it checks; otherwise it retracts. There is nothing to set: a checked link is always better than a retract.

What a round tool leaves is normal: inside corners keep the tool’s radius, and slots narrower than the tool stay uncut. The simulation shows it. Chipload also warns about two things:

• Uncut material: the rings don’t pass close enough to some material (a stepover too large for the shape). Lower the stepover.
• A narrow part: the tool doesn’t fit through a narrow part of the pocket. The pocket is cleared as separate areas, and material stays in between; a rest pass with a smaller tool can clear it.

Entry

• Plunge: straight down at the innermost ring. It needs a centre-cutting endmill.
• Ramp: down along the first ring, out and back, never steeper than the ramp angle.
• Helix: down round a small circle at the pocket’s widest point, as helical G2/G3.
  • The radius is a quarter of the tool diameter by default, and must be less than the tool radius. Where there’s no room, it shrinks.
  • With no room for even a tenth of the tool’s diameter, the pocket ramps in, with a note.
  • New pockets use a helix when the tool is marked not centre-cutting.

Start point and lead

As on profiles: drag the start marker of each wall ring, and add a lead from the cleared side onto the wall.

Dogbones

Corners puts dogbones or T-bones into the pocket wall’s inside corners, as on profiles, and any corner can have its own choice (corner by corner). Not with rest machining.

Rest machining

A pocket can have rest passes: smaller tools that clear only what its tool left, shown under it in the Browser. See Rest machining.

In the file

"type": "pocket" in the project file. Lengths are in mm, feeds in mm/min, angles in radians.

Projects from before Chipload 0.14 that used the removed trochoidal or adaptive clearing are cut as ring pockets. Projects from before 0.18 that had the tool retracting between rings or sharp inner rings now get links and rounded rings: the same rings, cut faster.

Rest machining

A large tool clears a pocket fast, but leaves material where it doesn’t fit:

• inside corners rounded to its radius;
• slots and gaps narrower than the tool.

A rest pass with a smaller tool cuts only that material, instead of clearing the whole pocket again. (Design: docs/specs/rest-passes.md.)

Adding one

• Right-click the pocket in the Browser, then Add rest pass ▸, and pick a smaller endmill: the project’s tools come first, then those in your tool library. A library tool is copied into the project’s Tools. When the entry is greyed out, point at it to see why: no smaller endmill in the project or your library, or the pocket has dogbone corners. Command line: chipload op add-rest part.chipload --op 1 --tool 2 (copy a library tool in first with chipload tool use).
• It belongs to the pocket: it shows as a leaf under it, numbered after it (1.1, 1.2), and takes the pocket’s shapes, depths, oversize and direction. Change the pocket and the pass follows; turn the pocket off and its passes aren’t cut either.
• Its own: the tool, feed, plunge feed, step down, stepover, entry, and on/off. Click the pass to change them; its right-click menu removes it.
• Feeds and step down come from your tool library’s values for the small tool when it has them. Otherwise they’re copied from the pocket: check them.
• Several passes: a pocket can have more than one, each with a smaller tool than the one before (12, then 6, then 3 mm). Each clears what the one before it left.

Command line: chipload op rest-pass part.chipload --op 1 lists a pocket’s passes, and with --pass 1 changes one (--tool, --feed, --plunge-feed, --step-down, --stepover, --enabled false) or removes it (--remove).

When it is cut

A rest pass waits for the pockets next to its pocket that use the same tool. After the last of them come all their rest passes, the larger tools first, then the operations after them. So with two pockets and an outline, all cut with a 12 mm tool, and a 4 mm rest pass on each pocket:

The small tool comes in once, and the outline, which frees the part, stays last. The report, the G-code headers and the setup sheet show the passes where they are cut.

What it cuts

• Worked out from the tool’s size: Chipload works out what a tool of the larger tool’s size can’t reach in the pocket’s shapes. It looks at the size, not at what the pocket’s toolpath did.
• Rings: around each piece of that material, the small tool clears a small pocket with rings, within its own diameter. Along the real walls it follows the walls, so the corners come out with the small tool’s radius.
• Pieces too small for the small tool too are skipped, with a note giving their size.
• Nothing left: if the large tool reaches the whole pocket (a circle wider than it), the pass cuts nothing and says so.

View > Show stock shows the result: the corners cut by the small tool.

Rules

• A smaller endmill: a pass’s tool must be an endmill smaller than the tool before it.
• No dogbones: a pocket with dogbones can’t have rest passes; its corners need no rest.

A rest pocket on its own

When the large pocket is cut elsewhere, in another project or another program, a pocket can rest after a tool by itself: Clearing > Rest after in its properties (command line: chipload op rest part.chipload --op 2 --after-tool 1). It is an ordinary operation in the list, cut where it stands. Chipload warns when no earlier, enabled pocket cuts the same shapes with that tool at least as deep; it is still safe, it just leaves the bulk of the material.

A rest pocket that copies an earlier pocket of the project (same shapes, depths, oversize and direction, after its tool), as Add rest pocket made them before rest passes, can become that pocket’s rest pass: right-click it, Make it a rest pass of operation N (command line: chipload op make-rest-pass part.chipload --op 2). It is then cut after the run of pockets it belongs to.

V-carve

A V-carve engraves closed shapes, such as lettering (converted to outlines in CAD), logos and inlay outlines, with a V-bit:

• the bit follows each shape’s centre line;
• it goes as deep as makes the cut exactly as wide as the shape at the surface.

Narrow strokes come out shallow and wide ones deep, and sharp outside corners such as serif tips stay sharp. Select the closed contours, then V-carve (ribbon, OPERATION). A logo or sketch that is only a picture can be traced into shapes first.

The V-bit

The tool must be a V-bit with its angle set: the included angle, e.g. 60° or 90°. Tip is the flat tip’s diameter, 0 for a pointed bit. Chipload never guesses the angle; a V-bit without one is refused.

Settings

Regions work as in pockets: an outline minus the selected contours inside it (the inside of an O stays standing). Open contours are skipped.

Limits

• A flat tip: it can’t reach into the last bit of a sharp corner, and strokes narrower than the tip are left out, with a warning.
• No floor clearing: the floor is the V the bit leaves; wide areas aren’t cleared flat. For that, pocket them first with an endmill and carve on the pocket floor with the start depth.
• Text: text from the DXF must be converted to outlines (curves) in CAD first. Chipload doesn’t read TEXT entities or fonts.

Every V-carve move is checked so the cone never reaches past the outline at the surface.

In the file

"type": "vcarve" in the project file. Lengths are in mm, feeds in mm/min, angles in radians.

Follow path

Follow path puts the tool’s centre exactly on the selected lines, open or closed, down to the end depth in passes. Use it for engraving, V-grooves, score and fold lines, or a single cut through thin material.

Select the shapes, then Follow (ribbon, OPERATION). A picture of handwriting or line art can be traced into centre lines for it.

• Open lines are cut back and forth, pass by pass.
• Closed shapes go round, as a profile on the line does.
• Order: the paths are cut nearest first.

It cuts only what it selects. Profiles and pockets keep skipping open lines, so a centre line on a cutting layer is never cut by them. A follow path that selects a whole layer does cut that layer’s centre lines.

There is no side, oversize, tabs, lead or start point: the tool is on the line.

In the file

"type": "path" in the project file. Lengths are in mm, feeds in mm/min, angles in radians.

Holes

Holes cuts every selected circle, either drilled with a drill or bored with a helix with an endmill. Select the circles (a whole layer is fine: other shapes are skipped with a note), then Holes (ribbon, OPERATION). Circles drawn in Chipload count, and so do imported circles, including ones drawn as two half arcs.

The tool decides how:

Drilling

• The drill feeds straight down at the hole’s centre.
• Pecks (optional): it drills that many mm, rapids up to clear the chips, rapids back down to 0.5 mm above the bottom, and drills on.
• End depth is the depth of the drill’s point. The full diameter ends a little higher, about 0.3 × the diameter for a 118° point.
• Plain moves: the holes are written as plain G0/G1 moves, not canned cycles, so they run the same on every controller and the checker reads them. The checker allows exactly one kind of rapid below the stock top: straight back into the hole just drilled.

Helical boring

• The path: the endmill goes down a helix at the hole’s wall, at most step per turn per turn and never steeper than the ramp angle. Then it cuts one level circle at the bottom, for a flat floor and a clean wall.
• Size: the hole comes out at its drawn size.
• Any endmill: the helix never plunges, so a tool that isn’t centre-cutting is fine.
• Too small: a hole must be larger than the tool, by at least a tenth of the tool’s diameter. Smaller holes are skipped, with a note.
• Larger holes: more than twice the tool’s diameter, the helix cuts a ring and leaves a core.
  • In a through hole, the core comes loose at the last turn, with a note. Hold it down, or use a pocket.
  • A blind hole that would leave a core standing is refused: use a pocket.

Order

Holes are cut nearest first, from where the tool is. Where the Holes operation sits in the list decides whether holes come before or after the profiles.

In the file

"type": "holes" in the project file. Lengths are in mm, feeds in mm/min, angles in radians.

Surface

Surface takes the whole stock top down flat with a wide endmill. Use it to flatten your spoilboard, or to face a board before cutting it. It needs no selection: click Surface (ribbon, OPERATION), or right-click a part, New operation ▸ Surface. On the command line, chipload op add-surface part.chipload.

A new surface goes first in the active part, since it faces the stock before anything else is cut. It takes the project’s widest endmill and 0.5 mm off the top in one pass.

How it cuts

• Back and forth along the stock’s longer side, in straight passes one stepover apart. Half the passes climb, half are conventional: usual for a shallow facing pass, and about half the time of cutting one way only.
• Past the ends: each pass starts and ends beside the stock, the tool’s edge just clear of it, so the tool goes down in the air, never into the stock. No ramp or helix is needed. Between passes it moves across beside the stock, without lifting.
• Past the sides: the first and last passes reach past the stock’s long sides by a quarter of the tool, so the edges come out clean even when the stock is a little larger than entered.
• Depths: with a step down smaller than the end depth, each depth comes back the other way, going down beside the stock where the one before ended.
• Once: the stock is faced once, even when the part has copies.

The setup sheet says how far the tool runs past the stock’s ends (its radius): keep clamps and fences clear of that.

Settings

• End depth: how much comes off, from the stock top. At most the stock thickness.
• Step down: the deepest each pass goes. Usually the whole depth in one pass.
• Stepover: how far each pass moves across, as a fraction of the tool diameter, from 0.1 to 0.9. A new surface takes 0.75.
• Feed and plunge feed: the plunge feed is for the moves down beside the stock.

The other operations’ depths don’t change: they still count from the stock top as entered. Facing 0.5 mm off means their first 0.5 mm cuts air, which is safe. A surface placed after other operations of its part gets a warning: it would face what they already cut.

Flattening the spoilboard

1. Make a project whose stock is the spoilboard’s area, Z zero at its top (Stock and work zero).
2. Copy your surfacing bit into the project (Tool library).
3. Add a Surface, with 0.3 to 0.5 mm off: enough to take out the dips.
4. Export, zero Z on the spoilboard, and run it.

In the file

"type": "surface" in the project file. Lengths are in mm, feeds in mm/min.

Tool library

Your tools, kept between projects in tools.json in your settings folder. A project copies the tools it uses, so its G-code never depends on the library: it cuts the same on another computer, or after you change the library.

In the app

Your tools are under This computer > Tools at the top of the Browser. Tools in the ribbon’s LIBRARY group opens it.

• Click a tool to edit it in Properties. Changes are a draft, marked unsaved in the Browser, until you press Save; Revert drops them.
• Drag a tool onto the project’s Tools (or right-click it > Add to project) to copy it into the project.
• Right-click a tool for Make default (new projects start with it) and Delete, or This computer > Tools for New tool, Import… and Export….

Project tools and the library

Each project tool remembers the library tool it was copied from, by an id that stays when the library tool is renamed. Its row in the Browser shows that tool’s name (“← 6 mm 2F”), and its properties say how they stand:

• Use library tool… gives the project tool another library tool’s values.
• Save as new… keeps the project tool’s values under another name.
• A new operation gets a library tool’s cutting values while the project tool still has the library tool’s values.

What a tool has

The project tool’s values (Tools and tool changes), plus:

• Name: how you find it, e.g. “6 mm 2F upcut”.
• Tool number: the id it gets in a project, when that number is free there.
• Flutes: used for the chip load.
• Cutting values (optional): feed, plunge feed, step down and stepover. A new operation made with this tool starts with them. They never change an existing operation. Without them, a new operation copies the operation above it, or starts from the tool’s diameter: 250 mm/min per mm (a 6 mm tool: 1500 mm/min), a third of that to plunge, 1 mm step down. Check the chip load before cutting.

On the command line

chipload tool list                                     # the tools, and where the file is
chipload tool add "6 mm 2F" --diameter 6 --flutes 2 --rpm 18000 \
  --feed 1500 --plunge-feed 400 --step-down 2 --stepover 0.4
chipload tool add "V 60" --type vbit --diameter 12.7 --angle 60 --tip 0.2
chipload tool add "5 mm drill" --type drill --diameter 5 --rpm 3000
chipload tool set "6 mm 2F" --rpm 20000                # or --rename
chipload tool default "6 mm 2F"
chipload tool use "V 60" part.chipload                 # copy into a project; prints its id there
chipload tool save part.chipload --tool 2 --name "3 mm downcut"   # links tool 2 to it
chipload tool compare part.chipload                # each project tool: same, differs, not in the library, or not from it
chipload tool remove "5 mm drill"

Cutting values come as a set: give all four, or none.

Sharing

chipload tool export tools.json [--name …] writes your tools, or some of them, to a file. chipload tool import FILE adds a file’s tools:

• tools you don’t have are added;
• tools with the same name and the same values are left alone;
• each tool keeps its id, so projects made on the other computer stay linked;
• tools with the same name but other values are listed, and kept as yours unless you add --replace.

The app has the same: right-click This computer > Tools for Import… and Export…. The file format is documented, so a script can make one, e.g. from a supplier’s catalogue.

Machine profiles

A machine profile keeps a machine’s values, so new projects start with them:

• the post-processor;
• safe Z, the travel, the max feed;
• the spindle direction;
• how tool changes are written;
• the work zero.

Profiles are kept in machines.json in your settings folder. As with tools, a project copies the values; the profile is only where new projects start.

In the app

Your profiles are under This computer > Machines in the Browser. Machines in the ribbon’s LIBRARY group opens it.

• Click a profile to edit it in Properties; Save writes it.
• Right-click it for Use in this project, Make default and Delete.

In Job settings > Machine:

• Use profile… applies a profile to the project: all its values.
• While the project’s machine is the same as its profile, the machine’s values (post, spindle, max feed, tool changes, travel) are shown greyed under “From machine Shapeoko”. Edit here makes them editable for this project; it stays linked.
• When they differ, each value that differs has a ↶ button: hover it for the profile’s value, click it to take it. Update from library takes them all.
• Safe Z, the work zero and the max depth below the stock belong to the job: they’re always editable and never count as differing. A profile only gives a project its first values for them.
• A line says how the machine stands to its profile, as for tools, with Save to library, Save as new… and Show in library.

A profile whose post is one of your own post-processors copies that post into the project.

On the command line

chipload machine list
chipload machine add "Shapeoko" --post grbl --safe-z 10 --travel 838,838,95 --max-feed 5000
chipload machine set "Shapeoko" --safe-z 15        # or --rename
chipload machine default "Shapeoko"
chipload import part.dxf -o part.chipload --machine "Shapeoko"   # start from a profile
chipload machine use "Shapeoko" part.chipload                   # apply to an existing project
chipload machine save part.chipload --name "Shapeoko 4"         # links the project to it
chipload machine compare part.chipload                          # same, differs, not in the library, or not from a profile
chipload machine export machines.json ; chipload machine import machines.json
chipload machine remove "Shapeoko 4"

chipload machine add --help lists every value. The file format is documented.

Post-processors

A post-processor turns Chipload’s toolpath into the G-code dialect your controller reads. Three are built in:

The LinuxCNC and Mach3/4 posts haven’t been run on a real controller yet. Their programs say so in a header comment: check the program and air-cut before you cut. If you run one of them successfully, please report it.

Every post writes arcs as G2/G3, mm and absolute coordinates, and waits 3 s after starting the spindle. The post-processor reference lists every post’s settings.

Choosing the post

• App: Job settings > Machine > Post. The list shows the built-in posts, then yours.
• Command line: chipload post use part.chipload --post linuxcnc.
• Machine profile: a profile names its post, and a project made from the profile gets it.

Your own post

A post is two files in the posts folder of your settings folder:

• NAME.toml, the settings (reference);
• the template the settings name (template = "NAME.nc.j2"), a Jinja text that writes the program.

The easiest start is a copy of a built-in post, from the crates/chipload-post/posts/ and templates/ folders of the source. Rules:

• Names: a post can’t take a built-in name (grbl, linuxcnc, mach3).
• Copied into the project: a project that uses your post keeps its own copy of both files, so it gives the same G-code on another computer or after you change the files. When your files differ from the project’s copy, the app shows Update next to the Post box (command line: run post use again).
• Sandboxed: the template sees only the values below, can’t read files, and stops with an error if it loops without end.
• The checker still decides. Whatever your template writes, the checker reads it back as a controller would. It accepts only the codes it knows: G0–G3, G4, G17, G20, G21, G90, G91.1, G94, the setup codes G40, G49, G80, G54, G61 and G64 P (at most 0.05 mm), M3–M6, M7–M9 and M30, and % lines. Anything else, such as G41/G42 cutter compensation, G43 tool lengths, G28 or G53 machine moves, or G91 relative moves, makes the check fail, and nothing is exported.

chipload post list shows every post and why one can’t be used, and chipload post show NAME what one writes (extension, decimals, arcs, tool changes). In the app they are under This computer > Post-processors in the Browser. chipload render writes a bare toolpath through a post, for trying a template (the result isn’t checked: use run to cut).

What the template sees

Numbers come already formatted in the program’s units: with the settings’ decimals in mm, inch_decimals (4 if missing) in inches.

Inches. A post writes inch G-code only if its settings say its template can: units = ["mm", "inch"], and the template writes {{ units_word }} where it would write G21. A post without units writes mm only, and a project whose machine is set to inch is refused with that post, so a template that writes G21 itself never gets inch numbers.

The built-in GRBL template shows how they fit together:

{{ units_word }} G90 G17 G94
{{ "M3" if spindle == "cw" else "M4" }} S{{ rpm }}
{% if dwell is not none %}G4 P{{ dwell }}{% endif %}
{% for s in segments %}
{% for m in s.moves %}
{% if m.comment is not none %}
({{ m.comment }})
{% endif %}
{{ m.code }}{% if m.x is not none %} X{{ m.x }}{% endif %}{% if m.y is not none %} Y{{ m.y }}{% endif %}{% if m.z is not none %} Z{{ m.z }}{% endif %}{% if m.i is not none %} I{{ m.i }} J{{ m.j }}{% endif %}{% if m.f is not none %} F{{ m.f }}{% endif %}
{% endfor %}
{% endfor %}
M5
M30

Problems

The app checks the project while you edit, before anything is generated:

• On the field: a field with a problem turns red, e.g. an end depth above the start depth, an oversize as large as the tool radius, or a tool without a spindle speed. Hovering it says why.
• On the operation: its row in the Browser gets a red dot, and hovering it shows the first problem.
• Above the form: a strip lists them all; click one to go to its operation.

Generating is blocked until they’re fixed; warnings don’t block it. On the command line, chipload check-project part.chipload lists the same problems with the path of each field (operations.1.end_depth), and chipload set can fix it by that path (Scripting).

Problems and warnings

Warnings appear in the report under the canvas after generating, on the command line as warning: … lines, and on the setup sheet under Watch out.

Generating

• F5 (Generate at the ribbon’s right end) plans the toolpath, writes the G-code and runs the checker.
• With View > Update toolpath automatically (on by default), this happens by itself half a second after each change, in the background. The app stays responsive, and a running generation can be cancelled: Cancel takes Generate’s place meanwhile.
• Out of date: a toolpath on the canvas that no longer matches the project is drawn faded until the next generation.

Export (Ctrl+E) is only possible once the current project has generated and passed the check.

3D view, simulation and playback

3D view

3D, on the canvas’s navigation bar, shows the toolpath at its real depths.

• Turn: left-drag.
• Pan: right-drag.
• Zoom: the scroll wheel.
• Back to top view: Top on the navigation bar, View > Top view or T.
• Straight at a side: click a face of the cube in the canvas’s top right corner (TOP, FRONT, RIGHT, …).
• Shallow cuts: View > Z scale in 3D stretches depth, for cuts too shallow to see.

Simulation

The simulation cuts the stock with every move of the program and shows the result. It is on when the app starts; View > Show stock (or Stock on the canvas’s navigation bar) turns it off and on.

• Top view: a shaded picture.
• 3D: a surface you can turn.
• Tool shapes: each tool’s real shape is used: a flat endmill, a V-bit’s cone with its tip, and a drill’s 118° point.
• When: it runs in the background after each generation. Until it’s done, the canvas says Updating the simulation… and still shows the stock as the last toolpath cut it.
• Without the toolpath: View > Show toolpath (also Toolpath on the navigation bar and a checkbox on the canvas legend) hides the toolpath’s lines, plunges and tabs. During playback, the tool still shows where it is.
• The stock alone: turn off Drawing on the navigation bar (or View > Show drawing) as well, and only the simulated stock is left.

Use it to see what the toolpath really leaves:

• material in corners;
• a missing pass;
• a cut into the wrong place;
• the floor of a V-carve.

The report gives the volume removed and the deepest cut.

On the command line, chipload simulate part.chipload prints the same numbers and writes a shaded top view (part-sim.png). --after N stops after the first N moves.

Playback

Under the canvas, a slider runs through the program by time, like a 3D printer’s preview:

• Dragging: the moves done so far are drawn, the rest faint, and the tool is shown where it is.
• With the simulation on: the stock is shown as cut up to that point, also part of the way along a long straight move.
• Marks on the slider show where each operation starts and where the tool changes.
• The readout shows the time so far and in all, the operation and copy, the tool’s X, Y and Z, and the feed.

Keys:

• ← / → one move;
• Shift + ← / → to the next mark;
• Home / End the start or the end.

▶ plays it at ×1, ×10 or ×100 the estimated speed.

Cycle time and chip load

Cycle time

After generating, the report gives the program’s estimated time, split into cutting, rapids and spindle start-up, with one line per operation. With several parts, each part’s time comes first, with its operations under it. With several tools, it also gives a time per file and the number of tool changes. Hovering an operation in the Browser shows its time, and so does the setup sheet.

• Feeds as programmed: the estimate uses the programmed feeds, and moves at the full feed from start to end.
• Real time is longer: a real machine slows down in corners and while accelerating. Take the estimate as a lower bound for jobs with many short moves.
• Rapids move at the machine’s max feed (Job settings > Machine). Without one, the estimate assumes 5 000 mm/min and says so: set the max feed for a better estimate.

chipload plan part.chipload prints the same, and --json gives it as numbers.

Chip load

For each operation, Chipload shows the chip load: how thick a chip each cutting edge takes, in mm per tooth:

chip load = feed / (spindle speed × flutes)

• Too thin and the tool rubs and heats up.
• Too thick and it may break.

The right value depends on the material, the tool and the machine, so Chipload shows the number and doesn’t judge it. As a rough guide:

• wood and plastics with 3–12 mm tools often take 0.05–0.25 mm per tooth;
• aluminium takes 0.02–0.08.

Check the tool maker’s figures.

Setting it up:

• Flutes and spindle speed: the tool needs both, on the tool (click it in the Browser) or in the tool library.
• Feed: a drill’s chip load uses its feed down; everything else uses the cutting feed.

Setup sheet

With the G-code, Chipload writes a setup sheet for the operator: an HTML page next to it, part-sheet.html. Open it in a browser, or print it. It holds:

• Time: the estimated cycle time.
• Stock and zero: the stock’s size and thickness, where X0 Y0 and Z0 are, and the copies. With several parts, each part with its copies.
• A top view: the stock, the part, each file’s or tool’s cuts, the tabs, and the X0 Y0 mark.
• Files and tools in order: for each file or tool change, the tool to put in, the operations it cuts, and the time.
• Operations:
  • with several parts, under each part’s name;
  • their kind, side and direction;
  • their depths and passes;
  • feeds with the chip load;
  • entry, tabs and time.
• Watch out: every warning and check warning.

The sheet is written:

• in the app, by File > Export G-code… when This computer > Preferences > Setup sheet in the Browser is on (the default; it applies to every project);
• on the command line, by chipload run unless you add --no-sheet;
• alone, by chipload sheet part.chipload -o sheet.html.

Its lengths and feeds are in the app’s units (the command line writes mm). When the machine’s G-code is in inches, the top of the sheet says so: G-code in inches (G20).

Its words are in the app’s language; the command line writes English unless you add --lang de to chipload sheet (or --sheet-lang de to chipload run; also fr, es, it, sv). Names, numbers and the G-code are never translated.

Scripting Chipload

Everything Chipload does can be driven from scripts: the command line takes every action, --json gives results a program can read, get/set change any value of a project, and JSON Schemas describe the files. (Design: docs/specs/scripting.md.) An AI assistant can drive the same commands through MCP.

JSON output

Add --json to any command, before or after it (chipload --json plan part.chipload or chipload plan part.chipload --json). The command then prints exactly one JSON object on stdout, on one line, and nothing else. This holds when it fails too.

Every object has these keys:

problems are the project’s problems, as the GUI shows them, each with the path of the field it is about (operations.0.rest). Pass that path to set to fix the field.

The exit codes are the same with or without --json:

• 0: done;
• 1: failed, including a refused check or problems found;
• 2: the command line itself is wrong (clap’s message, not JSON).

Each command’s own keys

Operations and moves are indexed from 0 in JSON. Times are in seconds and lengths in mm. Object keys come out sorted.

schema prints the schema itself, with or without --json (see below).

Reading and changing values: get and set

A path is keys and array indexes joined by dots, as in the project file, counting from 0: stock.thickness, operations.1.end_depth, tools.0.rpm. Note that --op on op tool and op rest counts from 1, as Chipload numbers operations on screen.

chipload get part.chipload operations.1.end_depth          # 6.0
chipload set part.chipload operations.1.end_depth=6.5 operations.1.name=Corners
chipload set part.chipload 'operations.1.rest={"after_tool": 1}'
chipload set part.chipload operations.1.rest=null           # turn an optional setting off
chipload set part.chipload "operations.3=$(chipload get part.chipload operations.0)"   # with 3 operations: append a copy of the first
chipload check-project part.chipload                        # problems with their paths

How set works:

• Values: each value is JSON if it parses (6.5, true, null, {"after_tool": 1}), and text otherwise (Corners). For text that looks like JSON, quote it: name='"6"'.
• Adding: setting the index one past the end of a list appends to it. A missing optional field is added.
• Checked before writing: the whole project is loaded again before anything is written. A misspelt field, a wrong type, or a value the format refuses stops it, and the file stays as it was.
• Problems don’t stop it: a project that loads but would be refused at generation (a rest tool smaller than the pocket’s, say) is written, and its problems are listed, as the GUI keeps an edit with a red field.
• Fixed fields: schema_version and written_by can’t be set.

For one run only, run, plan, simulate and sheet take --set PATH=VALUE, which you can repeat. The project file isn’t changed:

chipload run part.chipload --set stock.thickness=18 -o part-18mm.nc

JSON Schemas

chipload schema project  > chipload-project.schema.json
chipload schema tools    > chipload-tools.schema.json
chipload schema machines > chipload-machines.schema.json

The same files are in this repository under docs/schemas/.

What they cover:

• Current version only: they describe the files at the current version. Older projects still load; Chipload upgrades them, and saving writes the current version.
• What they check: field names and types, required fields, and the allowed values of choices.
• What they don’t check: ranges and rules between fields, such as “stepover between 0 and 1” or “clearance less than the tool radius”. Use chipload check-project for those.
• Descriptions: every field has one, taken from Chipload’s source.

VS Code (completion and checking while editing a project by hand): in your settings,

"files.associations": { "*.chipload": "json" },
"json.schemas": [
  { "fileMatch": ["*.chipload"], "url": "file:///path/to/chipload-project.schema.json" }
]

Recipes

Chipload has no batch command: the shell does that better, in parallel too. These need jq for the JSON.

Every project in a folder to G-code, listing failures (bash):

for p in *.chipload; do
  chipload run "$p" -o "${p%.chipload}.nc" --json |
    jq -r --arg p "$p" 'if .ok then empty else "\($p): \(.error.message)" end'
done

In parallel, four at a time:

ls *.chipload | xargs -P 4 -I{} sh -c 'chipload run "{}" -o "$(basename "{}" .chipload).nc" > /dev/null || echo "failed: {}"'

One project at several stock thicknesses:

for t in 12 15 18; do
  chipload run part.chipload --set stock.thickness=$t \
    --set operations.0.end_depth=$(echo "$t + 0.3" | bc) -o "part-${t}mm.nc"
done

Cycle times into a CSV:

echo "project,seconds" > times.csv
for p in *.chipload; do
  chipload plan "$p" --json | jq -r --arg p "$p" 'select(.ok) | "\($p),\(.estimate.total_s)"' >> times.csv
done

Check every project (for example after changing a post-processor):

for p in *.chipload; do chipload check-project "$p" --json | jq -r 'select(.ok | not) | .error.message'; done

PowerShell (Windows), every project to G-code:

Get-ChildItem *.chipload | ForEach-Object {
  $r = chipload run $_.FullName -o ($_.BaseName + ".nc") --json | ConvertFrom-Json
  if (-not $r.ok) { "$($_.Name): $($r.error.message)" }
}

And in parallel (PowerShell 7):

Get-ChildItem *.chipload | ForEach-Object -Parallel {
  chipload run $_.FullName -o ($_.BaseName + ".nc") --json | ConvertFrom-Json
} -ThrottleLimit 4 | Where-Object { -not $_.ok } | ForEach-Object { $_.error.message }

AI assistants (MCP)

An AI assistant such as Claude can work in Chipload for you. You describe the part (“cut the outline out of 12 mm plywood with four tabs, and pocket the slots 4 mm deep”), and the assistant makes the project, sets up the operations, checks them, plans and simulates them, and writes the G-code when you ask.

It does this through chipload mcp, a server for the Model Context Protocol (MCP), which assistants use to call programs’ tools. (Design: docs/specs/mcp.md.)

Setting it up

The assistant starts chipload mcp itself and talks to it over its input and output. Nothing listens on the network.

• Claude Code: in your project’s folder, run

  claude mcp add chipload -- chipload mcp
  

  Give the full path to chipload if it isn’t on your PATH. Paths the assistant uses are relative to the folder Claude Code runs in.

• Claude Desktop and other MCP clients: add a server whose command is chipload with the argument mcp. In Claude Desktop’s claude_desktop_config.json:

  {
    "mcpServers": {
      "chipload": { "command": "/path/to/chipload", "args": ["mcp"] }
    }
  }
  

  On Windows, the command is the full path to chipload.exe, from chipload-cli-X.Y.Z-windows-x86_64.zip. Ask the assistant to use full paths to your files there, as it has no project folder.

What the assistant can do

Every command is a tool with the same options, apart from mcp, reference and render. Each tool gives the same JSON as the command with --json. So the assistant:

• imports DXFs and pictures, and places them;
• reads and changes any value with get and set (an operation is added by setting a whole one);
• reads the project’s problems with their paths, and fixes them;
• plans and simulates. With an output picture, simulate also shows the assistant the cut stock;
• writes G-code with run, which, as always, writes only programs that pass the checker.

Tools that only read (inspect, plan, get, check-project, the lists…) are marked so, and your assistant may run them without asking you. For the others, it may ask first.

Safety

The assistant can do what the chipload command can do, and no more.

• It can’t move your machine. Chipload never does.
• render, which writes unchecked G-code for testing posts, isn’t offered.
• A saved project keeps the previous file as .bak.

Look at what it made before you cut:

• open the project in the app;
• check the toolpath and the simulation;
• read the setup sheet;
• do an air cut.

An assistant can misread a drawing, or choose a side, a depth or a tool you didn’t mean.

Watching it work

Open the project in the app while the assistant works on it. Each time the assistant saves the file, the app loads the new version within a couple of seconds, so you see each change on the canvas, with its toolpath and simulation. Ctrl+Z goes back a step. If you’ve changed something in the app yourself and not saved it, the app asks before loading (The window).

Limits

• The assistant works on the project’s file, not in the app. What you change in the app reaches the assistant only once you save.
• It does one thing at a time; planning a big project takes a few seconds.

Command line

Every command takes --json: one JSON object instead of text (see Scripting). chipload --help and chipload COMMAND --help print the same help in the terminal.

chipload inspect

Dump units, entities, contours and issues of a DXF or a project

chipload inspect <FILE> [OPTIONS]

chipload new

Create an empty project, to draw in or import a DXF into later (update --from)

chipload new [OPTIONS]

chipload import

Create a project from a DXF

chipload import <DXF> [OPTIONS]

chipload update

Replace a project’s imported drawing with a new version of the DXF

chipload update <PROJECT> [OPTIONS]

chipload plan

Plan a project’s toolpath without writing G-code

chipload plan <PROJECT> [OPTIONS]

chipload run

Generate checked G-code from a project

chipload run <PROJECT> [OPTIONS]

chipload simulate

Simulate the material a project’s program removes (docs/specs/simulation.md): print the numbers and write a shaded top view (PNG). The job is generated and checked as by run; no G-code is written

chipload simulate <PROJECT> [OPTIONS]

chipload sheet

Write a project’s setup sheet for the operator (HTML), without the G-code. The job is generated and checked as by run

chipload sheet <PROJECT> [OPTIONS]

chipload render

Render a toolpath JSON (as plan --json prints under “program”) through a post-processor. For testing posts; the output is NOT checked, use run to cut

chipload render <PROGRAM> [OPTIONS]

chipload check

Check a G-code program against a project’s stock, safe height and machine limits

chipload check <GCODE> [OPTIONS]

chipload op

Change an operation of a project

chipload op tool

Set the tool an operation cuts with (docs/specs/tool-per-operation.md §7). The tool must be in the project: copy one in from your library with tool use

chipload op tool <PROJECT> [OPTIONS]

chipload op add-rest

Add a rest pass to a pocket (docs/specs/rest-passes.md): a smaller endmill that clears what the pocket’s tool (or its last pass’s) leaves, in the pocket’s shapes and depths. It is cut after the run of pockets with the pocket’s tool

chipload op add-rest <PROJECT> [OPTIONS]

chipload op add-surface

Add a surface (docs/specs/surfacing.md): the whole stock taken down flat with a wide endmill, in straight passes back and forth, first in the active part. Flattens the spoilboard or faces the stock

chipload op add-surface <PROJECT> [OPTIONS]

chipload op rest-pass

A pocket’s rest passes (docs/specs/rest-passes.md): without –pass, list them; with it, change, turn off or on, or remove one

chipload op rest-pass <PROJECT> [OPTIONS]

chipload op make-rest-pass

Make a rest pocket that copies an earlier pocket (same shapes, depths, clearance and direction, rest after its tool) a rest pass of that pocket (docs/specs/rest-passes.md §5). It is then cut after the run of pockets it belongs to

chipload op make-rest-pass <PROJECT> [OPTIONS]

chipload op part

Move an operation into another part, at the end of its operations (docs/specs/parts.md §7). Operations are numbered again in the new order

chipload op part <PROJECT> [OPTIONS]

chipload op corners

List a profile’s or pocket’s corners on the tool’s side, with what each gets (round, dogbone, T-bone along the longer or shorter wall) and whether that is the corner’s own choice (docs/specs/dogbone-per-corner.md)

chipload op corners <PROJECT> [OPTIONS]

chipload op corner

Give one corner of a profile or pocket its own bone, whatever the operation’s corners say (docs/specs/dogbone-per-corner.md): --bone none keeps it round. op corners lists the corners

chipload op corner <PROJECT> [OPTIONS]

chipload op tabs

List a profile’s tabs: each contour’s, with their centres on the tool path and whether they were placed by hand (docs/specs/tabs-by-hand.md). The job is planned

chipload op tabs <PROJECT> [OPTIONS]

chipload op tab

Place a profile’s tabs by hand (docs/specs/tabs-by-hand.md): add a tab at a point, or remove the one there. The first on a contour keeps that contour’s other tabs where Chipload put them. --even spaces one contour’s tabs evenly again, --reset all

chipload op tab <PROJECT> [OPTIONS]

chipload op rest

Make a pocket clear only what a larger tool leaves (docs/specs/rest-machining.md)

chipload op rest <PROJECT> [OPTIONS]

chipload shape

Draw in a project: add, change or delete circles, rectangles and polylines

chipload shape add

Add a drawn shape; prints its id

chipload shape add <PROJECT> <KIND> [OPTIONS]

chipload shape set

Change a drawn shape’s values or layer; it keeps its id

chipload shape set <PROJECT> <ID> [OPTIONS]

chipload shape remove

Remove a drawn shape. Operations that used it are flagged

chipload shape remove <PROJECT> <ID> [OPTIONS]

chipload shape copy

Copy drawn shapes, moved by –dx and –dy, on their layers; prints the new ids

chipload shape copy <PROJECT> <IDS>... [OPTIONS]

chipload shape mirror

Mirror drawn shapes in place, about the middle of the box round them. They keep their ids, so the operations that cut them follow

chipload shape mirror <PROJECT> <IDS>... [OPTIONS]

chipload shape move

Move drawn shapes by –dx and –dy; they keep their ids, so the operations that cut them follow (docs/specs/drawn-shapes-box.md)

chipload shape move <PROJECT> <IDS>... [OPTIONS]

chipload shape turn

Turn drawn shapes counter-clockwise about the middle of the box round them, or a point

chipload shape turn <PROJECT> <IDS>... [OPTIONS]

chipload shape scale

Scale drawn shapes evenly about the middle of the box round them, or a point

chipload shape scale <PROJECT> <IDS>... [OPTIONS]

chipload shape join

Join open drawn polylines whose ends are closer than –gap into one, on the same layer; a chain that comes back to its start closes (docs/specs/explode-and-join.md)

chipload shape join <PROJECT> <IDS>... [OPTIONS]

chipload image

Pictures traced into shapes for V-carving: add, change, list, preview, remove

chipload image add

Add a picture (PNG, JPEG or BMP) and trace it into shapes on its own layer

chipload image add <PROJECT> <PICTURE> [OPTIONS]

chipload image set

Change an image’s settings, position or size, and trace it again

chipload image set <PROJECT> <ID> [OPTIONS]

chipload image list

The project’s images: picture, place, settings and shapes

chipload image list <PROJECT>

chipload image preview

Write an image as black and white, as it is traced (PNG)

chipload image preview <PROJECT> <ID> [OPTIONS]

chipload image remove

Remove an image and its shapes

chipload image remove <PROJECT> <ID> [OPTIONS]

chipload text

Text written into shapes for V-carving, pocketing or profiling: add, change, list, remove, and the built-in fonts (docs/specs/text.md)

chipload text add

Write a text into shapes on its own layer; prints its id. “\n” in the text starts a new line

chipload text add <PROJECT> <TEXT> [OPTIONS]

chipload text set

Change a text (what it says, its font, size, place or turn) and write it again

chipload text set <PROJECT> <ID> [OPTIONS]

chipload text list

The project’s texts: what they say, font, size, place and shapes

chipload text list <PROJECT>

chipload text remove

Remove a text and its letters

chipload text remove <PROJECT> <ID> [OPTIONS]

chipload text fonts

The built-in fonts

chipload text fonts

chipload dxf

A project’s DXFs: add another, list them, remove one (docs/specs/drawing-sources.md)

chipload dxf add

Add a DXF to the project, where the file has it; move it with place --dxf ID

chipload dxf add <PROJECT> <DXF> [OPTIONS]

chipload dxf list

The project’s DXFs: id, name, file, placement and shapes

chipload dxf list <PROJECT>

chipload dxf explode

Turn a DXF’s shapes into drawn shapes you can edit; the project no longer knows the DXF (docs/specs/explode-and-join.md). Operations keep cutting the same shapes

chipload dxf explode <PROJECT> <ID> [OPTIONS]

chipload dxf remove

Remove a DXF and its shapes

chipload dxf remove <PROJECT> <ID> [OPTIONS]

chipload tool

Your tool library: tools kept for every project (copied into a project when used)

chipload tool export

Write the tools to a file: a backup, or for another computer

chipload tool export <FILE> [OPTIONS]

chipload tool import

Add the tools of an exported file (or another computer’s library file)

chipload tool import <FILE> [OPTIONS]

chipload tool list

List the library’s tools and where the library is

chipload tool list

chipload tool add

Add a tool to the library

chipload tool add <NAME> [OPTIONS]

chipload tool set

Change a library tool

chipload tool set <NAME> [OPTIONS]

chipload tool remove

Remove a tool from the library

chipload tool remove <NAME>

chipload tool default

The tool new projects start with

chipload tool default <NAME>

chipload tool use

Copy a library tool into a project; prints its id there

chipload tool use <NAME> <PROJECT> [OPTIONS]

chipload tool compare

How each project tool stands to the library tool it came from: same, differs (with the differences), missing, or none

chipload tool compare <PROJECT>

chipload tool save

Save a project’s tool into the library; the project’s tool is linked to it

chipload tool save <PROJECT> [OPTIONS]

chipload machine

Your machine profiles: machine values a new project starts with

chipload machine export

Write the machine profiles to a file: a backup, or for another computer

chipload machine export <FILE> [OPTIONS]

chipload machine import

Add the machine profiles of an exported file (or another computer’s library file)

chipload machine import <FILE> [OPTIONS]

chipload machine list

List the machine profiles and where they are kept

chipload machine list

chipload machine add

Add a machine profile. Values not given are the built-in project defaults

chipload machine add <NAME> [OPTIONS]

chipload machine set

Change a machine profile

chipload machine set <NAME> [OPTIONS]

chipload machine remove

Remove a machine profile

chipload machine remove <NAME>

chipload machine default

The machine new projects start with

chipload machine default <NAME>

chipload machine use

Copy a profile’s values into a project; lists what changed

chipload machine use <NAME> <PROJECT> [OPTIONS]

chipload machine compare

How the project’s machine stands to the profile it came from: same, differs (with the differences), missing, or none

chipload machine compare <PROJECT>

chipload machine save

Save a project’s machine values as a profile; the project is linked to it

chipload machine save <PROJECT> [OPTIONS]

chipload post

Post-processors: the built-in ones and yours (docs/specs/user-posts.md)

chipload post list

List the built-in post-processors and yours, and where yours go

chipload post list

chipload post show

What a post-processor writes: its name, files, extension, decimals, arcs, tool change modes and spindle dwell

chipload post show <NAME>

chipload post use

Make a post-processor the project’s; one of yours is copied into the project (run again after changing it, to update the copy)

chipload post use <PROJECT> [OPTIONS]

chipload part

A project’s parts: groups of operations, each cut with its copies before the next (docs/specs/parts.md)

chipload part list

The project’s parts: id, name, on or off, copies and operations

chipload part list <PROJECT>

chipload part add

Add an empty part at the end; it becomes the active part

chipload part add <PROJECT> [OPTIONS]

chipload part set

Rename a part, or turn it off or on (a part that is off isn’t cut)

chipload part set <PROJECT> <ID> [OPTIONS]

chipload part activate

Make a part the active one: where the app adds new operations

chipload part activate <PROJECT> <ID> [OPTIONS]

chipload part remove

Remove a part. Refused while it has operations, unless –with-operations

chipload part remove <PROJECT> <ID> [OPTIONS]

chipload copies

Cut a part several times in a grid (docs/specs/copies-grid.md)

chipload copies <PROJECT> [OPTIONS]

chipload place

Move, turn or scale the imported drawing (docs/specs/drawing-placement.md, drawing-rotation.md, drawing-scale.md). Without an option, print where it is

chipload place <PROJECT> [OPTIONS]

chipload licenses

Print Chipload’s licence and the licences of every third-party component

chipload licenses

chipload get

Print a project value by path, as JSON (docs/specs/scripting.md §4), e.g. operations.1.end_depth: keys and indexes from 0, as in the file

chipload get <PROJECT> <PATH>

chipload set

Set project values by path (docs/specs/scripting.md §4): operations.1.end_depth=6.5. A value is JSON when it parses (6.5, true, null, {“after_tool”: 1}), else text. The project must still load; problems are listed but don’t stop the write

chipload set <PROJECT> <VALUES>... [OPTIONS]

chipload check-project

List a project’s problems with their paths, without planning; exits 1 if any

chipload check-project <PROJECT>

chipload schema

Print the JSON Schema of a file format (docs/specs/scripting.md §2)

chipload schema <FORMAT>

chipload mcp

Serve the commands as tools to an AI assistant over the Model Context Protocol, on stdin and stdout (e.g. claude mcp add chipload -- chipload mcp)

chipload mcp

Project file

A project (.chipload) is a JSON file. Chipload writes every field; when you write one by hand or with a script, the fields marked no may be left out. Lengths are in mm, angles in radians, feeds in mm/min. chipload schema project prints the JSON Schema this page is made from.

Schema version 29. Older files load through Chipload’s migrations; this schema describes only the current version.

The file

ArcSegment

From start_angle through sweep radians (positive = counter-clockwise).

AutoThreshold

The word “auto”.

One of: "auto".

Bone

What a chosen corner gets.

One of: "none", "dogbone", "tbone".

Copies

A grid of copies of a part: copy (column c, row r) is the part moved by (c·dx, r·dy) mm.

CopyOrder

In which order the copies are cut.

• "by_operation": Each operation on every copy, then the next operation.

• "by_copy": Every operation on one copy, then the next copy. Called by_part before parts came (schema 22).

CornerChoice

A corner with its own bone, chosen by the user.

Corners

How the tool reaches into the inside corners it would leave round, so a square part fits: every corner on the tool’s side up to max_angle.

"type": "dogbone"

In along the corner’s bisector.

"type": "tbone"

In along the longer wall: the notch is in the shorter one.

CustomPost

A user post-processor’s config and template, exactly as read from the posts folder.

Direction

One of: "climb", "conventional".

Drawing

The project’s drawing: shapes in millimetres, or (only for jobs from before v4) a reference to a DXF that still has to be embedded.

DrawingSource

Provenance of the imported shapes.

Entry

How the tool goes down into the material at the start of each pass, for pockets and follow paths (a profile always spirals: its ramp_angle).

"type": "plunge"

Straight down: needs a centre-cutting tool. An empty struct variant, as Rings.

"type": "ramp"

Down along the path and back, never steeper than ramp_angle (radians, 0 < angle <= 30°).

"type": "helix"

Pockets only: down round a circle of radius (the tool centre’s), never steeper than ramp_angle.

Finish

A finishing pass on a profile.

HoleMethod

How a Holes operation cuts.

"type": "drill"

Straight down at the hole’s centre, peck mm at a time.

"type": "bore"

A helix at the wall, at most step_down mm per turn and never steeper than ramp_angle (radians, 0 < angle <= 30°), then one level circle.

Image

A picture traced into shapes: the picture itself, where it goes, and how it becomes black and white. Its traced shapes are path shapes on its layer that name it in image.

ImageThreshold

Where grey turns black: “auto” or a grey value.

• AutoThreshold: Picked from the picture.

• integer: Grey values below this are black, 1 to 254.

ImageTrace

What a picture is traced into.

• "outline": Closed outlines round the black parts, black inside.

• "centre_line": Open (or closed) paths along the black strokes’ middles.

IssueSeverity

One of: "warning", "error".

Lead

Quarter-circle lead-in and lead-out.

LineSegment

Machine

Operation

"type": "profile"

"type": "pocket"

"type": "vcarve"

V-carve: a V-bit follows the centre line of closed shapes, as deep as makes the cut exactly as wide as the shape.

"type": "path"

Follow path: the tool centre on the selected shapes, open or closed.

"type": "holes"

Holes: drilled with a drill, bored with a helix with an endmill.

"type": "surface"

Surface: the whole stock top taken down flat, in straight passes back and forth.

Part

A part: a named group of operations, cut together, with its own copies (docs/specs/parts.md §2). It owns no geometry: its operations select the shapes.

PathSegment

• object:

• object:

Placement

Where the imported drawing is put: a DXF point p goes to scale · rotate(p) + (dx, dy), turned and scaled about the DXF’s origin.

Rest

Rest machining: the pocket clears only the material the larger tool after_tool can’t reach in its shapes.

RestPass

One rest pass of a pocket (docs/specs/rest-passes.md §2): it takes the pocket’s shapes, depths, clearance and direction, and clears only what the tool before it leaves.

Selector