YAML documentation

Documentation: YAML cut description

The simpliest way to interact with opencut is to write a YAML description of the cuts you would like. More advanced users can use the javascript API directly if they find they have more complex needs than can be easily described directly.

Overview

A top level Job object defines the workspace parameters and the cuts we would like to have made. It is defined as follows:

job
units {enum} - The unit of measurement to use ("mm", "inches")
bit_diameter {number} - The diameter of the cutting bit
feed_rate {number} - The X/Y feed rate in units per minute
plunge_rate {number} - The Z plunge rate in units per minute
z_step_size {number} - How far down to cut in each pass
safety_height {number} - A safe height for free gantry movement
default_depth {number, optional} - The default depth for cuts if a depth is not specified
name {string, optional} - The name of this job
cuts {Cut, repeated} - A list of cuts to make

cut
type {string} - The name of the cut to make
depth {number} - The depth of the cut to make
z_step_size {number} - Override the default step size in each Z pass
z_top {number} - The top of each cut (default=0)

cut:shape
type {enum} - The type of shape ("rectangle", "circle")

cut:shape:circle
center {array<number>} - A point where the center of the circle should be
radius {number} - The radius of the circle from the center point

cut:shape:rectangle
origin {array<number>} - A point where the bottom-left corner should be
size {array<number>} - The (width, height) of the rectangle

Cut Types

Drill

Drill cuts will move the cutter to each specified point, then drill down making a hole the size of the cutting bit.

cut:drill
points {array<array<number>>} - A list of points to drill at

units: inch
bit_diameter: 0.125
feed_rate: 15
plunge_rate: 5
cuts:
- type: drill
  depth: -0.25
  points: [[0.125, 0.125], [0.125, 1.375]]

Path

Path cuts will move the cutter along the specified path in multiple passes to reach the specified depth.

cut:path
points {array<array<number>>} - A list of points to drill at

units: inch
bit_diameter: 0.125
feed_rate: 15
plunge_rate: 5
z_step_size: 0.1
cuts:
- type: path
  depth: -0.2
  points: [[0.375, 0.375], [0.625, 0.75], [0.375, 1.125]]

Profile

Profile cuts will move the cutter such that the cut is to one side or the other of a shape. For example, if cutting a circle, the cutter could cut out the inside to make a hole of the specified size, or it could cut around the outside to make a plug of the specified size.

cut:profile
side {enum} - Which side of the shape to cut ("inside", "outside")
shape {Shape} - The shape to cut (mutually exclusive with 'points)
points {array<array<number>>} - A series of points to cut along (mutually exclusive with 'shape')
corner_radius {number, optional} - Apply a circular arc to the corner interiors
corner_compensation {bool, optional} - True to cut all the way to the corner, compensating for bit size (overrides 'corner_radius')

units: inch
bit_diameter: 0.125
feed_rate: 15
plunge_rate: 5
z_step_size: 0.1
cuts:
- type: profile
  side: outside
  depth: -0.25
  shape: {type: circle, radius: 0.25, center: [1.5, 0.75]}
- type: profile
  side: inside
  depth: -0.25
  corner_compensation: true
  shape: {type: rectangle, origin: [0, 0], size: [3, 1.5]}

Profile cuts can also be specifed as a closed series of points, in clockwise order.

units: mm
bit_diameter: 3
feed_rate: 250
plunge_rate: 120
z_step_size: 1
cuts:
  - type: path
    points: [[0, 0], [45, 0], [45, 15], [15, 15], [15, 45], [0, 45], [0, 0]]

Pocket

Pocket cuts are used to cut away material from inside a shape. This is useful when you don't want to cut all of the way through your workpiece.

cut:pocket
corner_compensation {bool} - True to cut all the way to the corner, compensating for bit size
shape {Shape} - The shape to cut

units: inch
bit_diameter: 0.125
feed_rate: 15
plunge_rate: 5
z_step_size: 0.1
cuts:
- type: pocket
  depth: -0.125
  corner_compensation: true
  shape: {type: rectangle, origin: [0.25, 0.25], size: [0.5, 1]}
- type: pocket
  depth: -0.125
  shape: {type: circle, radius: 0.5, center: [1.5, 0.75]}

Screwhole

Make a hole for a screw, optionally milling a wider top for a pan-head screw top.

cut:screwhole
points {array<array<number>>} - A list of points to make holes
shaft_diameter {number} - The diameter of the screw shaft
depth {number} - The depth to mill the hole.
cap_diameter {number, optional} - The diameter of the screw cap
cap_depth {number, optional} - The depth to mill the screw cap area.

units: mm
bit_diameter: 3.175
feed_rate: 250
plunge_rate: 125
cuts:
- type: screwhole
  depth: -5
  shaft_diameter: 3
  cap_diameter: 6
  cap_depth: -1.5
  points: [[0, 0], [0, 15], [15, 0], [15, 15]]

gcode

A hack of a cut to allow arbitrary gcode to be embedded.

cut:gcode
gcode {array<string>} - A list of gcode commands

cuts:
 - type: "gcode"
   gcode: ["M3", "M5"]