MapleCAM User Guide

MapleCAM is desktop CAM software for CNC routers and laser cutters. It generates toolpaths and G-code from SVG and DXF designs. It will probably work on a mill, but mills aren't the target and there are no mill-specific features.

What MapleCAM Does

1. Import vector designs (SVG or DXF files)
2. Create operations that describe how to cut each part (contour, pocket, engrave, V-carve, and more)
3. Generate toolpaths — the precise paths your cutting tool will follow
4. Validate toolpaths against your stock using 3D simulation
5. Export G-code for your CNC machine (GRBL or LinuxCNC)

Quick Start

If you're new to MapleCAM, start with Installation and then follow Your First Project for a guided walkthrough.

Documentation Sections

• Getting Started — Install, set up your machine, and complete your first project
• Workflow — How MapleCAM's design-to-G-code pipeline works
• Importing Designs — Bringing SVG and DXF files into MapleCAM
• Operations — Reference for all operation types (contour, pocket, V-carve, laser, etc.)
• Tools — Managing your tool library and presets
• Machines — Configuring machines and G-code dialects
• Visualization — 2D canvas, 3D view, and toolpath validation
• Exporting — Generating G-code and SVG output
• Reference — Keyboard shortcuts, project settings, defaults
• Troubleshooting — Common issues and FAQ

Installation

System Requirements

• Java 21 or later
• Operating System: Windows 10+, macOS 12+ (Apple Silicon), or Linux (X11 or Wayland)
• Memory: 4 GB RAM minimum, 8 GB recommended
• Disk: ~100 MB for MapleCAM (excluding the Java runtime)

Java

MapleCAM requires Java 21 or later. Use any JDK distribution — your system package manager, your OS vendor, or a binary download from openjdk.org. To verify, open a terminal and run:

java -version

The version reported should be 21 or higher.

Download

Pick the JAR for your platform from the downloads page:

• maplecam-alpha-windows-x64.jar — Windows on x86_64
• maplecam-alpha-macos-aarch64.jar — macOS on Apple Silicon
• maplecam-alpha-linux-x64.jar — Linux on x86_64

Each JAR bundles its target platform's JavaFX native libraries; pick the one that matches your OS and architecture. macOS Intel and Linux on ARM aren't published yet.

Running MapleCAM

From a terminal in the directory where the JAR was downloaded:

java -jar maplecam-alpha-<platform>.jar

On Windows, double-clicking the JAR also works once Java is installed; if Windows opens it as a ZIP archive instead, run the command above from PowerShell or cmd.

The first launch shows the machine setup wizard to capture your work area, spindle and laser capabilities, and default safe-Z heights. After that, see Your First Project for a walkthrough.

Initial Setup

When you first launch MapleCAM, the Initial Setup Wizard guides you through configuring your CNC machine.

The Setup Wizard

The wizard walks through:

1. Machine name — a label for your machine (e.g., "Shapeoko 4", "3018 Pro")
2. Work area — the X, Y, and Z travel dimensions of your machine, in millimeters
3. Capabilities — whether your machine has a spindle, a laser, or both
4. Spindle settings — minimum and maximum RPM (if applicable)
5. Safe Z height — the Z height for rapid moves above the stock (typically 5-10mm above your material)

After Setup

Your machine configuration is saved to your user profile and will be available in all future projects. You can modify it later via MapleCAM > Setup Wizards > Machine Setup....

You can also configure additional machines if you have more than one CNC — each project selects which machine it targets.

Next Steps

Proceed to Your First Project for a guided walkthrough of the full workflow.

Your First Project

This walkthrough takes you from a blank project to exported G-code. We'll cut a simple shape using an outside contour operation.

1. Create a New Project

Launch MapleCAM. A new empty project opens automatically. If you already have a project open, use File > New Project (Ctrl+N).

2. Configure Stock

Open MapleCAM > Project Settings and enter your stock dimensions:

• Width (X): the width of your material in mm
• Height (Y): the depth of your material in mm
• Thickness (Z): the thickness of your material in mm

The stock appears as a rectangle on the 2D canvas.

3. Import a Design

Drag and drop an SVG or DXF file onto the canvas, or use File > Import SVG / File > Import DXF.

Your design appears as paths on the canvas, positioned within the stock boundary.

4. Select Paths

Click on a path to select it. Hold Shift to select multiple paths. Selected paths highlight in the canvas and in the project tree on the left.

5. Create an Operation

With paths selected, create an operation in one of three ways:

• Right-click the selection and choose an operation type
• Toolbar — click the operation button in the toolbar
• Keyboard chord — press Ctrl+E, then C for a contour operation

For this walkthrough, create an outside contour to cut the shape out of your stock.

6. Assign a Tool

In the property panel on the right, click the tool dropdown and select an endmill from the built-in tool library. A 1/4" (6.35mm) flat endmill is a common starting point.

7. Configure Settings

The property panel shows the operation settings. Key settings for a contour:

• Cut side: Outside (to cut around the shape)
• Depth: Set to your stock thickness (or slightly deeper) to cut through
• Tabs: Enable hold-down tabs to prevent the part from moving during the final pass

Feed rate, spindle speed, and depth per pass come from the tool preset — you can adjust them if needed.

8. Preview Toolpaths

Toolpaths generate automatically when you configure an operation. Switch to the 3D view (F5) to see the cutting paths visualized against your stock.

9. Validate

Run toolpath validation to check for errors. The validator simulates the cut using a 3D voxel model and reports any overcuts or issues.

10. Export G-code

Use File > Export G-code (or the toolbar button). Choose your G-code dialect:

• GRBL — for GRBL-based controllers (most hobby CNC machines)
• LinuxCNC — for LinuxCNC-based controllers

Save the .nc file and load it into your CNC controller software.

The CAM Pipeline

MapleCAM follows a four-stage pipeline from design to machined part:

Design → Operations → Toolpaths → G-code

1. Design (Import)

You start with a 2D vector design — an SVG or DXF file created in tools like Inkscape, Illustrator, LibreCAD, or AutoCAD. The design contains paths (lines, arcs, curves) that define the shapes you want to cut.

2. Operations

You assign operations to paths. An operation describes how to cut: contour around the outside, pocket out the interior, engrave along the line, V-carve with variable depth, etc. Each operation has settings like cut depth, feed rate, and tool selection.

3. Toolpaths

MapleCAM generates toolpaths from your operations. Toolpaths are the precise XYZ coordinates your cutting tool will follow, including:

• Tool offset (compensating for the tool's radius)
• Multi-pass depth stepping
• Lead-in and lead-out moves
• Rapid positioning between cuts
• Tab placement for hold-down tabs

Toolpath generation is automatic — it runs whenever you change an operation's settings.

4. G-code

Finally, you export G-code — the machine-readable instructions for your CNC controller. MapleCAM translates toolpaths into the G-code dialect your machine understands (GRBL, LinuxCNC, etc.), including spindle/laser control, feed rates, and safe movement heights.

Coordinate System

MapleCAM uses a right-handed coordinate system measured in millimeters:

• X — right (positive) / left (negative)
• Y — forward (positive) / backward (negative)
• Z — up (positive) / down (negative)

Z=0: The Stock Surface

The top surface of your stock is always at Z = 0. Cutting goes into negative Z values. For example, if your stock is 20mm thick, the bottom of the stock is at Z = -20.

This convention matches most CNC workflows where you zero the Z axis to the top of the material.

Safe Z and Clearance Height

Two Z heights control rapid (non-cutting) movement:

• Safe Z — the height for rapid moves between distant cuts (typically 5-10mm above stock). The tool lifts to Safe Z when moving between separate regions.
• Clearance height — a smaller lift for moves between nearby paths within the same operation (micro-lifts). This is faster than lifting all the way to Safe Z.

Both values are positive Z (above the stock surface) and are configured in Project Settings.

Projects and Files

Project Files (.mcp)

MapleCAM saves projects as .mcp files — compressed JSON containing your stock dimensions, imported parts, operations, tool assignments, and all settings. The design geometry is embedded in the project file, so you don't need to keep the original SVG/DXF alongside it.

Creating and Saving

• New Project — File > New Project (Ctrl+N)
• Save — File > Save (Ctrl+S)
• Save As — File > Save As (Ctrl+Shift+S)

Multi-Tab Editing

MapleCAM supports multiple projects open simultaneously in separate tabs. Each tab has its own undo/redo history, selection state, and dirty flag.

Recent Files

The File menu shows recently opened projects for quick access. Use File > Clear Recent Files to reset the list.

Project Settings

Each project stores:

• Stock dimensions — width (X), height (Y), thickness (Z)
• Material — selected from the material library (affects recommended feed rates)
• Machine — which machine configuration to target
• Safe Z — height for rapid positioning moves
• Clearance height — height for short repositioning moves

SVG Import

MapleCAM imports SVG (Scalable Vector Graphics) files — the most common format for 2D vector designs.

How to Import

• Drag and drop an SVG file onto the canvas
• File > Import SVG (menu)

Supported SVG Elements

MapleCAM supports standard SVG path elements including lines, arcs, cubic and quadratic Bezier curves, and basic shapes (rect, circle, ellipse, polygon, polyline). Transforms (translate, rotate, scale, matrix) are applied during import.

Units

SVG files can declare lengths in mm, cm, in, pt, pc, or px. MapleCAM converts everything to millimeters on import — you don't have to set your document to mm beforehand. SVG without an explicit unit (and px) is treated as CSS reference pixels (96 dpi).

Tips for Preparing SVGs

• Convert text to paths — MapleCAM imports geometry, not fonts. In Inkscape: select text, then Path > Object to Path.
• Flatten transforms — while MapleCAM handles transforms, flattening them in your editor can avoid surprises.
• Remove clipping masks and filters — MapleCAM ignores raster effects, gradients, and clipping paths.
• Check path direction — for contour operations, path direction (CW vs CCW) can affect which side is "inside" vs "outside."

DXF Import

MapleCAM imports DXF (Drawing Exchange Format) files — the standard interchange format for CAD software.

How to Import

• Drag and drop a DXF file onto the canvas
• File > Import DXF (menu)

Supported DXF Entities

MapleCAM supports common DXF entities including LINE, ARC, CIRCLE, ELLIPSE, LWPOLYLINE, POLYLINE, and SPLINE.

Units

MapleCAM reads the $INSUNITS header variable and converts to millimeters automatically. Inches, feet, miles, mm, cm, m, km, microinches, and mils are all recognised. If $INSUNITS is missing or 0 (unitless), the file is treated as already-mm — set the header in your CAD software if your "unitless" drawing is actually in another unit.

Tips for Preparing DXFs

• Join open paths — disconnected line segments may not form closed contours. Use your CAD software's "join" or "pedit" command to create closed polylines.
• Flatten to 2D — MapleCAM imports 2D geometry. If your DXF contains 3D elements, flatten them before importing.
• Remove construction geometry — layers containing reference lines, dimensions, or annotations should be removed or hidden before export.

Working with Parts

When you import a design from SVG or DXF, the imported geometry becomes a part in your project — a named container holding the paths from the file. A project can hold multiple parts, each from a separate import.

What a part contains

Each part has:

• A name, taken from the imported filename
• A set of paths (the geometry from the SVG or DXF)
• A position (X, Y) on the stock
• A uniform scale factor

Parts can be moved and scaled, but not rotated. If you need rotated geometry, rotate it in your design tool before importing.

Selecting

Click on a path in the 2D canvas to select it. Hold Shift to add more paths to the selection or to select multiple parts. Selection syncs between the canvas and the project tree on the left.

Positioning

Drag a selected part on the canvas to move it within the stock area. The position can also be entered numerically in the property panel when a part is selected. Parts must fit within the stock dimensions for valid toolpaths to generate.

Scale

A part has a single scale factor (uniform across X and Y). Change it in the property panel; the underlying path geometry is multiplied by the factor at toolpath-generation time.

In the project tree

The project tree shows every part and its paths. Expand a part to see individual paths; expand a path to see the operations assigned to it. This is the easiest way to find an operation when the canvas gets crowded.

Operations Overview

An operation tells MapleCAM how to cut a path or set of paths. Each operation type produces different toolpaths suited to different tasks.

Operation Types

Spindle Operations

Laser Operations

Creating Operations

There are three ways to create an operation:

1. Right-click selected paths and choose from the context menu
2. Toolbar buttons for common operation types
3. Keyboard chords — press Ctrl+E then a key for spindle operations, or Ctrl+L then a key for laser operations (see Keyboard Shortcuts)

The Property Panel

When an operation is selected, the property panel on the right shows all configurable settings. Changes take effect immediately and toolpaths regenerate automatically.

Property Cascade

Operation settings are resolved through a cascade:

1. Operation — settings you've explicitly set on this operation
2. Operation Group — inherited from the group (display grouping only)
3. Tool Preset — defaults from the assigned tool's preset
4. Built-in Default — hardcoded fallback values

This means you only need to override the settings that differ from your tool preset.

Contour

A contour cuts along a path, with the tool offset to one side so the finished edge lands exactly on the design line. It runs at the depth schedule defined by the assigned tool preset, stepping down through multiple passes when the total depth exceeds the depth-of-cut. Variable-width tools (V-bits, tapered endmills) get extra shoulder clearing passes between depth steps so the finished wall is uniform.

Cut side and offset

You set the Contour Side to choose where the tool cuts relative to the path:

• Outside — tool runs outside the path. Use to cut a part out of stock.
• Inside — tool runs inside the path. Use to cut holes, slots, or sized openings.
• On Line — tool centre follows the path exactly, no offset.

A non-zero Contour Offset shifts the tool further from the path in addition to the cut-side offset, in mm. Useful for leaving a finishing allowance, or for tuning fit on a part that came out slightly oversize.

Tabs

Hold-down tabs are short bridges of uncut material that keep a through-cut part attached to the stock during the final passes, preventing it from shifting or being thrown by the tool. Tabs are configured via the Tabs setting:

• Off — no tabs.
• Auto — MapleCAM places a chosen number of tabs at even intervals around the path. Set count, width, and height.
• Manual — you place each tab explicitly. Set width and height, then drop tabs at specific points along the path.

Settings

Feed rate, plunge rate, spindle speed, total depth, and depth-of-cut all come from the assigned tool preset.

Tool requirement

Any rotary cutter (flat endmill, ball endmill, V-bit, tapered, surfacing). Laser tools won't appear in the tool selector for contour operations.

When to use

• Cutting a part out of stock (Outside + tabs)
• Cutting holes, slots, or fitted openings (Inside)
• Profiling an existing edge to a final dimension
• Engraving along a path at zero offset (On Line)

Pocket

A pocket clears material from inside a closed boundary down to the target depth. Anything you draw inside the boundary is treated as an island — the tool steps around it, so the island stays standing at full stock height. Pockets run as multi-pass cuts when the total depth exceeds the depth-of-cut from the tool preset.

Clearing strategy

Three patterns determine how the tool fills the area at each depth:

• Offset — concentric passes that follow the boundary inward, with each pass spaced by the preset's stepover. Produces the cleanest wall and floor finish; good default for most pockets.
• Line — straight parallel passes at a configurable angle. Fast on large open areas; small scallops at the walls.
• ZigZag — like Line, but bidirectional with linking moves at each end. Reduces non-cutting travel on long passes.

For Offset, Inside Out flips the order so the tool starts at the centre and spirals outward, which can help chip clearance on deep pockets in some materials. The Clearing Angle setting controls the line direction for Line and ZigZag (it has no effect on Offset).

Settings

Total depth, depth-of-cut, stepover, feed rate, plunge rate, and spindle speed all come from the assigned tool preset.

Tool requirement

A flat or ball endmill that can plunge, ramp, or helix into the material. V-bits and laser tools won't appear in the tool selector.

When to use

• Recesses, cavities, and inlay pockets
• Clearing material from inside a profile
• Removing a defined volume that has internal islands or features
• Any enclosed area that needs to be lowered to a known depth

Facing

A facing operation removes a thin layer of material from a flat surface — usually the top of the stock — to bring it to a known, even reference plane. It uses an endmill (typically a flat or surfacing bit) and runs as a clearing operation, like a pocket that covers the whole face.

If you draw an explicit boundary, facing operates within it. Otherwise it faces the full stock area. The boundary is expanded outward by one tool radius internally, so the cut reaches the actual edge instead of stopping a tool radius short.

Islands

Areas you want to leave standing — bosses, raised features, parts that should remain proud of the surface — can be marked as islands. The tool clears around them.

Clearing strategy

Three strategies determine the tool's path across the area:

• Offset — concentric passes that follow the boundary inward. Smoothest finish; the default for most facing.
• Line — parallel straight passes. Faster on large open areas; the Clearing Angle sets the direction of the lines.
• ZigZag — like Line, but bidirectional with linking moves at each end. Reduces non-cutting travel on long passes.

For Offset, Inside Out can reverse the order so passes start at the centre and work outward, which can help with chip clearance on deep facing cuts.

Settings

Depth, depth-per-pass, stepover, feed rate, plunge rate, and spindle speed all come from the assigned tool preset and don't need to be set per-operation.

Tool requirement

Any endmill that can plunge or ramp — flat endmills and dedicated surfacing/spoilboard cutters are the typical pick. V-bits and laser tools won't appear in the tool selector.

When to use

• Bringing rough or warped stock to an even, flat reference surface
• Reducing stock to an exact target thickness
• Surfacing a spoilboard before a precision job
• Cleaning up the top of stock before V-carving or engraving

Engrave

An engrave operation follows a path with the tool centre exactly on the line, at a single shallow depth. There's no offset, no clearing strategy, and no multi-pass schedule — engrave is the simplest spindle operation, intended for marking, line work, and shallow detail.

How it differs from on-line contour

A contour with Cut Side set to On Line also runs the tool centre along the path, but supports the full contour feature set: tabs, multi-pass depth, contour offset, and shoulder clearing for variable-width tools. Engrave drops all of that for a single-pass, fixed-depth cut.

If you need shallow line work, engrave is simpler. If you need multi-pass depth, tabs, or any contour-style behaviour along a line, use a contour with On Line cut side instead.

Settings

Engrave has no operation-specific settings. Cut depth, feed rate, plunge rate, and spindle speed all come from the assigned tool preset.

Tool requirement

Any rotary cutter — flat endmills and V-bits are the typical pick for line engraving. Laser tools won't appear in the selector (use a Laser Engrave operation for laser line marking).

When to use

• Text and lettering once converted to vector paths
• Fine detail, score lines, or guide marks
• Serial numbers, labels, or part identification
• Decorative line work on the surface of a workpiece

V-Carve

A V-carve uses a V-bit (or any tapered tool with a defined included angle) to cut a closed region at variable depth. The tool plunges deeper in wider parts of the shape and shallower in narrower parts, so the cut's edges follow the design outline exactly while the groove cross-section is a clean V.

How it works

For each closed region, MapleCAM computes the medial axis — the centreline skeleton of the shape, equidistant from the boundary on both sides. The tool follows that skeleton, with cut depth at each point determined by the local width of the shape and the V-bit's angle. Wide areas hit the tool's depth limit (set on the tool preset); narrow areas barely scratch the surface.

Flat bottom

For designs with regions wider than the V-bit can reach within the preset's depth limit, Flat Bottom mode kicks in. The wide area is cleared with a flat endmill (configured separately on the tool preset) at the depth limit, and the V-bit finishes the edges. This keeps the maximum depth bounded while preserving the V profile along the outline.

Settings

A few advanced tuning knobs are also exposed (tolerance mode, Z tolerance, max Z raise, significance threshold). Defaults are fine for most carving; reach for them only if your output has stair-stepping or mis-aligned arc-fit segments.

Feed rate, plunge rate, spindle speed, and max depth come from the assigned tool preset.

Tool requirement

A V-bit (or other tapered tool) with a defined included angle. Flat endmills, ball endmills, and laser tools won't appear in the tool selector for V-carve operations. If Flat Bottom is enabled, a secondary flat endmill is also pulled from the preset.

When to use

• Carved-style signs and lettering
• Decorative panel work
• Any design where you want a classic carved-edge profile
• Works on closed paths only — open paths can't be V-carved

Chamfer

A chamfer cuts an angled bevel along the top edge of a path using a V-bit. It runs as a single pass at the depth you set; the bevel width is determined by the tool's geometry, not entered separately.

Depth and width

You set the chamfer depth. The bevel width that results is calculated from the V-bit's tip diameter d and included angle a:

chamferWidth = d + 2 * chamferDepth * tan(a / 2)

A wider chamfer needs either more depth or a flatter (larger-angle) V-bit. To plan the other way around — pick a target width and solve for depth — use chamferDepth = (chamferWidth - d) / (2 * tan(a / 2)).

Cut side

• Outside — the bevel is cut on the outside of the path. Useful for chamfering the top edge of a part you're cutting out of stock.
• Inside — the bevel is cut on the inside of the path. Useful for chamfering the rim of a pocket or a hole.

Settings

Feed rate, plunge rate, and spindle speed come from the assigned tool preset and don't need to be set per-operation.

Tool requirement

A tapered tool with a defined included angle (a V-bit). Flat endmills, ball endmills, and laser tools won't appear in the tool selector for chamfer operations.

When to use

• Decorative bevels on the top edge of a cut-out part
• Easing the rim of a pocket or pour-fill area
• Rounding sharp edges before assembly or finishing

Helical Contour

A helical contour follows a closed path while spiralling continuously downward, instead of cutting at one depth, lifting, and stepping back down. Engagement stays even and entry is gradual, which is gentler on the tool and the workpiece — particularly in deep cuts or hard material. It accepts the same cut-side and tab settings as the regular Contour operation.

Helical descent

The tool drops by one depth-of-cut for every full revolution around the path, working from the start depth down toward the end depth. The last revolution is run at the end depth as a clean finishing pass; an optional spring pass runs once more at the same depth to shave off any spring-back.

Depth-of-cut, start depth, end depth, and the finish/spring pass flags all come from the active tool preset, so the operation usually just needs the cut side and any tabs configured per project.

Cut side

• Outside — tool centre runs outside the path. Use when cutting a part out of stock.
• Inside — tool centre runs inside the path. Use for cutting pockets and openings to size.
• On Line — tool centre follows the path exactly, no offset.

Settings

Feed rate, plunge rate, spindle speed, and the depth schedule come from the assigned tool preset.

Tool requirement

Any rotary cutter (flat, ball, V-bit, tapered, surfacing). Laser tools won't appear in the selector.

When to use

• Deep contours where a straight plunge would stress the tool
• Hard or brittle materials that don't tolerate sudden engagement
• Anywhere a smoother surface finish on the contour wall matters

Laser Operations

Laser operations are available when your machine has a laser capability enabled. They use laser power and travel speed instead of spindle speed and feed rate.

Laser vs Spindle Operations

Vector Operations

These take vector paths from the canvas:

• Laser Contour — cuts along a path with multi-pass support and tabs
• Laser Engrave — traces path centrelines for line work and text
• Laser Hatch — fills enclosed regions with parallel lines

Image Operations

These take a raster image and render it onto the stock surface:

• Laser Raster — pixel-power-modulated greyscale engraving (needs dynamic laser power)
• Laser Halftone — binary dithering for on/off-only lasers
• Laser Stippling — Voronoi-stippled point fields for a pointillist look

Creating Laser Operations

The keyboard chord Ctrl+L followed by a key creates the vector operations:

The image operations are created from the operation menu after loading an image.

Laser operations only appear when the current machine has laser capability enabled.

Laser Contour

A laser contour cuts along a path with the laser, supporting multiple passes with optional Z stepping between them. Like the rotary contour operation it has cut-side and offset settings, plus tabs for keeping parts attached to the stock during through-cuts.

Passes and Z step

Two ways to control how the cut is divided across passes:

• Set Number of Passes for an explicit pass count.
• Set Cut Depth Per Pass for a target depth per pass; the number of passes is then derived from the total depth.

The Z Step controls how far the laser focus drops between passes. With Z Step = 0, every pass runs at the same Z (useful for cutting thicker stock by repetition without refocusing). With a non-zero Z Step, the laser refocuses deeper on each pass.

Cut side

• Outside — beam runs outside the path. Use to cut a part out.
• Inside — beam runs inside the path. Use for holes or openings.
• On Line — beam follows the path exactly, no offset.

Tabs

Through-cuts can leave a part loose. Tabs are short uncut bridges that hold it in place until removal. The Tabs setting can be Off, Auto (count + width + height), or Manual (you place each tab).

Settings

Feed rate comes from the assigned tool preset.

Tool requirement

A laser tool. Rotary tools won't appear in the selector.

When to use

• Cutting out parts from sheet material (acrylic, plywood, leather, etc.)
• Cutting interior holes or openings
• Score-and-snap work where multiple shallow passes are easier on the laser
• Anywhere a contour needs no physical kerf compensation

Laser Engrave

A laser engrave operation traces the centreline of a path with the laser. There's no offset — the beam follows the design path exactly. It can run as a single pass or multiple passes, with each subsequent pass dropping by a fixed Z step for focus or depth control.

Passes and Z step

Set Number of Passes to repeat the engraving. Each pass after the first descends by the Z Step value. With Z Step = 0 every pass runs at the same depth, which is useful for darkening the engraving with multiple passes at the same Z. With a non-zero Z Step, three passes at 0.1 mm step engrave at 0, -0.1, and -0.2 mm.

Settings

Feed rate comes from the assigned tool preset.

Tool requirement

A laser tool. Rotary tools won't appear in the selector for laser operations.

When to use

• Engraving text and lettering once converted to vector paths
• Tracing fine line work, decorative outlines, or guide marks
• Score lines that don't need to cut through the material
• Multi-pass darkening of an existing engraving

For raster-fill image engraving (photos, grayscale art), use Laser Hatch for line-fill or one of the image-based laser operations.

Laser Hatch

A laser hatch fills a closed region with parallel lines at a chosen angle. Lines are clipped to the boundary and to any internal islands. The fill can run as multiple passes, with the laser focus dropping by a fixed Z step between passes.

Hatch direction and overscan

The Hatch Angle sets the direction of the parallel lines: 0 degrees runs horizontally, 90 degrees runs vertically. Cross-hatching is two laser hatch operations at different angles on the same region.

Overscan Distance extends each line a small distance past the boundary. With CO2 and diode lasers that take time to reach steady power after starting a stroke, overscan keeps the actual fill region from being under-burned at the edges. Default is zero.

Settings

Feed rate comes from the assigned tool preset. Line spacing comes from the laser tool's defined width on the preset.

Tool requirement

A laser tool. The tool's effective width determines the line spacing of the fill, so wider beams produce coarser hatching.

When to use

• Filling shapes with a hatched or shaded look
• Cross-hatching by stacking two hatch operations at different angles
• Area marking, texture, and infill on engravable material
• Burning off a coating or paint within a defined region

Laser Raster

A laser raster operation engraves an image by mapping pixel intensity directly to laser power. Each pixel becomes a short laser move at a power level interpolated between the configured min and max — white pixels run at min, black pixels at max, with continuous greyscale between. This produces continuous-tone output, in contrast to halftone mode which dithers to binary on/off.

Scanning

The image is scanned row by row. The Dots Per Mm setting defines both the spacing between scan lines and the spacing between pixels within a row, so it directly controls the engraving resolution.

Bidirectional scanning runs alternate rows in opposite directions, which roughly doubles throughput. Unidirectional (every row scanned in the same direction) avoids the one-pixel-wide kerf offset some machines exhibit between forward and reverse strokes, at the cost of extra return moves.

Settings

Feed rate comes from the assigned laser tool preset.

Tool requirement

A laser tool with dynamic power output. Static-on/off lasers can run this operation but won't reproduce greyscale; use Laser Halftone instead.

When to use

• Photographic image engraving on wood, MDF, leather, or acrylic
• Continuous-tone shading where you want subtle gradients
• Image-based marking where halftone dots would be visible

Laser Halftone

A laser halftone operation engraves an image by dithering it to pure black-and-white at the chosen resolution, then scanning each row. The laser fires at the configured power for black pixels and is off for white pixels. Consecutive black pixels in a row are merged into single line segments, so the laser runs continuously across darker areas instead of toggling per-pixel.

Dithering and resolution

The Dither Method chooses how the source image is converted to binary. Different algorithms produce different visual textures; Floyd-Steinberg is the typical default, with Atkinson and ordered dithering as alternatives. Dots Per Mm sets the grid resolution of the dither — higher values produce finer detail and longer engrave times.

Scanning

Bidirectional scanning runs alternate rows in opposite directions to halve the total return-travel time. Disable it if your machine shows a horizontal offset between forward and reverse strokes.

Settings

Feed rate comes from the assigned laser tool preset.

Tool requirement

A laser tool. Halftone runs on any laser with on/off control — dynamic power isn't required because the output is binary.

When to use

• Image engraving on lasers without reliable dynamic power
• Photographic engraving when a halftone aesthetic is desired
• High-contrast image marking where greyscale fidelity isn't needed

Laser Stippling

A laser stippling operation engraves an image as a field of dots distributed by image darkness. Darker regions get more closely packed dots, lighter regions get sparser ones; each dot becomes a short laser pulse at the configured power. The result is a pointillist-style rendering of the source image.

How the points are placed

The algorithm seeds an initial random distribution of points weighted by image darkness, then runs Lloyd's relaxation to push them toward weighted-centroid positions iteratively. Relaxation Iterations controls how many smoothing passes run — more iterations produce a more even distribution within the density-weighted regions, at the cost of longer planning time.

Dots Per Mm controls the overall density (and therefore the total number of stipple points). The Seed is the random seed for the initial distribution, exposed so a particular result can be reproduced exactly across runs.

Settings

Feed rate comes from the assigned laser tool preset.

Tool requirement

A laser tool. Like halftone, stippling drives the laser on/off per point and doesn't require dynamic power.

When to use

• Pointillist-style image engraving for an artisanal look
• Tonal shading on materials where line-fill or hatch would scorch
• Reproducible stippled portraits or graphics (use the Seed to lock in a result)

Tool Library

MapleCAM maintains a tool library — a persistent collection of cutting tools with their dimensions and default cutting parameters. The library is shared across all projects and stored in your user profile (~/.maplecam/tools.json).

Built-in Tools

MapleCAM ships with a set of common tools pre-configured. These cover typical endmill sizes, V-bits, and other common cutters.

Managing Tools

Open the tool library via MapleCAM > Tool Library.

From the library dialog you can:

• Add a new tool with custom dimensions
• Edit an existing tool's properties
• Delete tools you don't use
• Duplicate a tool as a starting point for a similar one

Assigning Tools to Operations

When you create or select an operation, the property panel shows a tool dropdown. Only tools compatible with the operation type are shown:

• Flat and ball endmills — contour, pocket, facing, engrave
• V-bits — V-carve, chamfer, engrave
• Any tool — engrave operations accept all tool types

Tool Properties

Tool Types

MapleCAM models cutting tools as one of five concrete types. The type of a tool determines its geometry — the shape of the cutting profile — which in turn affects toolpath generation, tool offset calculation, and which operations the tool can be used in.

Flat Endmill

A cylindrical cutter with a flat bottom and constant diameter along the cutting length. The most common CNC router tool.

Best for: pockets, contours, facing, line engraving. Wide-diameter flat endmills are also used as surfacing or spoilboard bits.

Ball Endmill

A cutter with a hemispherical tip and a constant shank diameter above the ball. Produces a rounded bottom along its centreline.

Best for: 3D surface finishing, smooth contours where a rounded bottom is acceptable.

V-Bit

A conical cutter with a pointed tip, characterised by the included angle (commonly 30, 60, 90, or 120 degrees). The cutting width depends on the depth of cut: width = tipDiameter + 2 * depth * tan(angle/2).

Best for: V-carving, chamfering, fine line engraving.

Tapered Ball Endmill

A ball-tipped endmill where the shank tapers outward toward the collet. Stronger than a straight ball endmill at the same effective tip diameter, with side cutting that follows the taper angle.

Best for: detailed 3D carving with a small effective tip and extra rigidity for reach.

Burr Endmill

A small-diameter cutter with a rounded or rounded-end tip used for fine detail work and clean-up passes. Geometry is similar to a ball endmill at small diameters.

Best for: fine detail, deburring, finishing passes after a rougher pass.

Presets and the Property Cascade

What Are Presets?

A preset stores default cutting parameters for a tool. When you assign a tool to an operation, the preset's values become the starting point for that operation's settings.

Preset parameters include:

The Property Cascade

When MapleCAM needs a value for an operation setting, it looks through a cascade of sources:

1. Operation — if you've explicitly set the value on this operation, that value is used
2. Operation Group — if the operation is part of a group, group-level settings apply
3. Tool Preset — the assigned tool's preset provides defaults
4. Built-in Default — hardcoded fallback values

This means:

• You only need to override settings that differ from your tool preset
• Changing a tool preset updates all operations using that tool (unless they have explicit overrides)
• Operation-level overrides always take priority

Material-Specific Presets

Different materials require different cutting parameters. The material selected in Project Settings can influence recommended preset values.

Default Presets

See Default Tool Presets for a table of the built-in preset values.

Machine Configuration

A machine in MapleCAM describes your CNC hardware — its physical dimensions, capabilities, and the G-code dialect it speaks.

Machine Properties

Creating a Machine

Use MapleCAM > Setup Wizards > Machine Setup... wizard, or open Machine > Manage Machines... for direct editing.

The Machine Setup wizard walks you through each setting step by step. Direct editing gives you access to all fields at once.

Multiple Machines

You can configure multiple machines. Each project selects which machine it targets. The machine selection affects:

• Available operation types (spindle vs laser)
• G-code dialect for export
• Work area validation (parts must fit within the machine's travel)
• Spindle speed range validation

Machine Storage

Machine configurations are saved in your user profile (~/.maplecam/machines.json) and are available across all projects.

G-code Dialects

MapleCAM supports multiple G-code dialects to match different CNC controllers.

Supported Dialects

GRBL

The most common controller for hobby CNC machines. Used by Shapeoko, X-Carve, OpenBuilds, 3018 machines, and many others.

Key characteristics:

• Spindle control via M3 S{speed} / M5
• Feed rate set with F{rate} on motion commands
• Arc commands G2/G3 with I/J offsets
• No subroutines or canned cycles

LinuxCNC

An open-source CNC controller running on Linux PCs. Common in more advanced hobby and semi-professional setups.

Key characteristics:

• Full G-code implementation including canned cycles
• Spindle control via M3 S{speed} / M5
• Supports tool change (M6 T{n})
• Comment syntax: ; comment or ( comment )

Dialect Differences

Choosing a Dialect

Select the dialect in your machine configuration. If you're unsure, GRBL is the safe default — it works with the majority of hobby CNC controllers.

The dialect is used during G-code export. You can change it at any time without regenerating toolpaths.

2D Canvas

The 2D canvas is MapleCAM's primary design view. It shows your stock, imported parts, and toolpath previews from above.

Navigation

Canvas Elements

• Grid — reference grid (toggleable)
• Rulers — millimeter rulers along top and left edges
• Stock outline — rectangle showing your material dimensions
• Parts — imported design geometry (paths and shapes)
• Toolpaths — cutting paths overlaid on the design (when generated)
• Selection highlight — selected paths and operations are highlighted

Selecting

• Click a path to select it
• Shift+click to add to selection
• Click empty space to deselect all

Dragging Parts

Click and drag a selected part to reposition it within the stock area.

3D View

The 3D view shows a three-dimensional visualization of your stock, toolpaths, and simulated cutting results. Toggle it with F5 or View > 3D View.

Camera Controls

Visualization Layers

The 3D view displays multiple layers that can be toggled individually:

Layer Visibility

Toggle layer visibility using the controls in the 3D view toolbar. Hiding layers like rapids or cutting volumes can make complex toolpaths easier to read.

Toolpath Validation

MapleCAM includes a 3D voxel-based toolpath validator that simulates your operations against the stock and detects errors before you run your machine.

What Validation Checks

The validator builds a 3D voxel model of your stock, then simulates each toolpath cutting through it. It detects:

• Overcuts — the tool removing material outside the intended operation region
• Plunge errors — the tool entering material at an unsafe rate or location
• Boundary violations — cutting outside the stock dimensions

Running Validation

Validation runs automatically after toolpath generation. Progress is shown in the status bar. You can also manually trigger it via View > Recalculate Toolpaths.

Interpreting Results

After validation completes, the project tree shows status indicators on each operation:

• Pass — no issues detected
• Warning — potential issues that may be acceptable
• Error — definite problems that should be fixed before cutting

The 3D view's Remaining Material layer shows the voxel simulation result — you can visually inspect what material remains after all operations.

Validation Resolution

The validator uses a default voxel resolution of 0.2mm. This means the simulation has approximately 0.2mm precision — features smaller than this may not be accurately represented.

Always Validate Before Cutting

Validation is your last check before sending G-code to your machine. While it can't catch every possible issue (e.g., workholding, tool breakage), it catches the most common CAM errors that could damage your work or machine.

G-code Export

Exporting G-code is the final step — it translates your toolpaths into machine-readable instructions.

How to Export

1. File > Export G-code or use the toolbar export button
2. Choose a file location and name (.nc extension)
3. The G-code is written using the dialect configured in your machine settings

What the G-code Contains

The exported file includes:

• Header — initialization commands, units (G21 for mm), coordinate mode
• Spindle start — M3 S{rpm} to start the spindle
• Toolpaths — G0 (rapid) and G1 (linear) / G2/G3 (arc) moves
• Safe Z retracts — G0 Z{safe} between operations
• Spindle stop — M5 at the end
• Footer — return to safe position, program end (M30 for GRBL, M2 for LinuxCNC)

Pre-Export Checklist

Before exporting, verify:

1. All operations have valid toolpaths (no errors in the tree)
2. Toolpath validation passes (no overcuts)
3. Stock dimensions match your actual material
4. Tool assignments are correct
5. Feed rates and speeds are appropriate for your material

G-code Dialects

The export format is determined by your machine's G-code dialect. See G-code Dialects for details on supported dialects and their differences.

SVG Export

MapleCAM can export your toolpaths as an SVG file. This is useful for documentation, review, or further processing in vector graphics software.

How to Export

File > Export SVG — saves the current toolpaths as vector paths in an SVG file.

What's Included

The exported SVG contains the toolpath geometry — the actual paths the tool follows. This includes cutting moves but typically not the stock outline or rapid moves.

When to Use SVG Export

• Creating documentation of your cutting plan
• Reviewing toolpaths in a vector editor
• Sharing toolpath previews without sharing the full project file

Keyboard Shortcuts

Standard Shortcuts

Key Chords — Spindle Operations (Ctrl+E)

Press Ctrl+E to enter endmill operation mode, then press the second key within 2 seconds. Available operations appear in the status bar. Press Escape to cancel.

Spindle operation chords are only available when the current machine has spindle capability.

Key Chords — Laser Operations (Ctrl+L)

Press Ctrl+L to enter laser operation mode, then press the second key.

Laser operation chords are only available when the current machine has laser capability.

Canvas Navigation

3D View Navigation

Project Settings

Access via MapleCAM > Project Settings.

Stock

Heights

Material

Select the material from the material library. Material selection affects recommended cutting parameters.

Machine

Select which machine configuration this project targets. This determines available operation types and G-code dialect for export.

Default Tool Presets

MapleCAM ships with a library of pre-configured tools and presets. These are based on tested speeds and feeds for hobby CNC machines.

Tool Categories

• V-Bits — 30, 60, 90 degree V-bits in various sizes
• Ball Nose — ball endmills for 3D finishing
• Tapered Ball — tapered ball endmills for detailed carving
• Flat Endmills — standard flat endmills from 1mm to 1/2 inch
• Compression — compression spiral endmills for clean edges on sheet goods
• Surfacing — large diameter surfacing/spoilboard bits

Preset Values

Preset values vary by tool size and type. Key parameters:

Customizing Presets

Open the Tool Library (MapleCAM > Tool Library) to view, edit, or create tool presets. Changes are saved to your user profile and persist across projects.

Default Materials

MapleCAM's material library includes common CNC materials organized by category.

Material Categories

How Material Affects Operations

The selected material influences recommended cutting parameters through tool presets. Harder materials generally require:

• Lower feed rates
• Lower depth per pass
• Potentially lower spindle speeds (especially metals)

Customizing Materials

Materials are stored in your user profile (~/.maplecam/materials.json).

Supported SVG Elements

This page lists the SVG elements and attributes that MapleCAM can import.

Supported Elements

Supported Attributes

Not Supported

• Text elements (convert to paths in your editor first)
• Raster images (<image>)
• Gradients and patterns (fill/stroke styling)
• Clipping paths and masks
• CSS styling (inline style attribute is partially supported)
• Filters and effects
• <use> / <defs> references (may have partial support)

Supported DXF Entities

This page lists the DXF entities that MapleCAM can import.

Supported Entities

Not Supported

• 3D entities (3DFACE, 3DSOLID, MESH)
• Dimension entities
• Text and MTEXT
• Hatching
• Blocks and INSERT references (may have partial support)
• External references (XREF)

Common Issues

No toolpaths generated

Symptom: You created an operation but no toolpaths appear.

Possible causes:

• No paths are assigned to the operation — select paths first, then create the operation
• The tool is too large for the geometry — try a smaller diameter tool
• Depth is set to zero — check the depth setting in the property panel
• The operation has an error — check the project tree for error indicators

"No compatible tools" when creating an operation

Symptom: The tool dropdown is empty or shows no options.

Possible cause: The tool library has no tools compatible with the selected operation type. For example, V-carve operations require V-bits.

Fix: Open MapleCAM > Tool Library and add a compatible tool, or use one of the built-in tools.

Export produces empty or very small G-code file

Symptom: The exported G-code file contains only header/footer but no cutting moves.

Possible causes:

• No operations have generated toolpaths
• All operations have errors
• Stock dimensions are zero

Validation shows overcuts

Symptom: Toolpath validation reports overcut errors.

Possible causes:

• Tool diameter is too large for tight corners in the geometry
• Contour cut side is wrong (inside vs outside)
• Operations overlap in ways that remove unintended material

Fix: Review the operation settings, consider a smaller tool, or adjust the geometry.

Imported design is wrong size

Symptom: The imported SVG or DXF is much larger or smaller than expected.

Possible causes:

• The file declares no units. SVG without a unit suffix and DXF with $INSUNITS=0 are both treated as already-millimetres; if your source was actually in another unit, the result is mis-scaled by that unit's mm conversion factor.
• SVG viewBox and width/height attributes disagree, producing an unintended scale factor.
• The DXF $INSUNITS header is missing or set to a value that doesn't match what the file is actually drawn in.

Fix: Set explicit units in your design software before exporting (SVG: set the document unit; DXF: set $INSUNITS correctly). MapleCAM converts whatever unit you declare to millimeters automatically — see SVG Import and DXF Import.

Application won't start

Symptom: Double-clicking the JAR file does nothing, or a command-line error appears.

Possible causes:

• Java is not installed or is an older version
• Java installation is not on the system PATH

Fix: Install Java 21 or later from any JDK distribution (your package manager, your OS vendor, or openjdk.org). Verify with java -version.

FAQ

What file formats can MapleCAM import?

SVG (Scalable Vector Graphics) and DXF (Drawing Exchange Format). Both are 2D vector formats. See SVG Import and DXF Import for details on supported elements.

What CNC controllers does MapleCAM support?

MapleCAM exports G-code for GRBL and LinuxCNC controllers. GRBL covers the majority of hobby CNC machines (Shapeoko, X-Carve, OpenBuilds, 3018, etc.). See G-code Dialects.

Can MapleCAM do 3D carving?

MapleCAM is a 2.5D CAM application — it works with 2D designs and controls depth (Z), but does not support full 3D surface machining from STL or 3D models. V-carving provides variable-depth cutting within 2D shapes.

What units does MapleCAM use?

Internally, everything is in millimeters. You don't need to convert your designs — the SVG and DXF importers handle units automatically.

• SVG: lengths in mm, cm, in, pt, pc, or px (CSS reference pixels at 96 dpi) are all converted on import.
• DXF: the $INSUNITS header is read; inches, feet, mm, cm, m, km, microinches, mils, etc. all convert correctly.

Where are my settings stored?

User data (tools, machines, materials, preferences) is stored in ~/.maplecam/ on Linux/macOS and %USERPROFILE%\.maplecam\ on Windows.

Can I use MapleCAM with a laser?

Yes. If your machine has a laser module, enable laser capability in the machine configuration. This unlocks laser operations (contour, engrave, hatch, pattern) with power and speed controls instead of spindle/feed settings.

How do I update MapleCAM?

Download the latest release from the Downloads page and replace your existing JAR file. Your settings and tool library are stored separately and will be preserved.

What is the .mcp file format?

MapleCAM project files (.mcp) are gzip-compressed JSON. They contain the full project state including imported geometry, operations, settings, and tool assignments. The original SVG/DXF files are not needed after import — the geometry is embedded in the project.