EasyShape5000 — Workflow Guide

Interface Overview

The interface mirrors EasyTrace5000's layout but adds scene-graph capabilities. A central canvas with two sidebars — the left for the scene tree and operations list, the right for shape properties and operation parameters.

The left sidebar is split into two panels. The Scene Tree shows the hierarchical structure of your imported SVG — groups and individual shapes with lock, visibility, and delete controls. Below it, the Operations List shows each assigned operation as a bucket with three stages: Geometry, Offsets, and Preview.

The right sidebar adapts to your selection. When a shape is selected, the top shows its transform inspector (position, rotation, scale, mirror). Below, the operation panel shows parameters for the assigned operation type, or the operation type selector if nothing is assigned yet.

The Workflow

EasyShape5000 follows a per-shape workflow: import a design, select shapes, assign operations, generate, and export — all non-destructively.

1. Importing SVGs

Drag and drop an SVG file onto the canvas, or use Actions → Import SVG. The file's group hierarchy is preserved: SVG <g> elements become groups in the scene tree, paths and shapes become selectable nodes.

Each shape's geometry is stored in its original coordinate space. Transforms (move, rotate, scale) are applied non-destructively — the source geometry is never modified. The world-space position used for G-code export is computed by multiplying the parent chain's affine matrices.

2. The Scene Tree

The scene tree (left sidebar, top) shows every shape and group in your workspace. Each row has controls for:

Visibility (eye icon)

Hides the shape from the canvas. Hidden shapes are excluded from marquee selection and export.

Lock (padlock icon)

Prevents the shape from being moved, rotated, or deleted. Locked shapes can still be selected (so you can unlock them) but cannot be mutated.

Delete (trash icon)

Removes the shape from the scene. Undoable with Ctrl+Z.

Groups can be collapsed, and locking a group locks all its children. Use Ctrl+G to group selected shapes and Ctrl+Shift+G to ungroup. When ungrouping, the group's transform is folded into each child so their visual position is preserved.

3. Assigning Operations

Select one or more shapes, then choose an operation type from the tabs on the right sidebar (Profile, Pocket, Drill, etc.). The operation panel appears with default parameters pulled from the active tool in the tool library.

Multi-selection: if you select shapes with different operation types, the panel shows parameters for the anchor shape's type and notes the mixed selection. Changes apply only to shapes of the matching type.

4. Generating Geometry

Click the Generate button (e.g. "Generate Profile Path") in the operation panel. The geometry engine uses Clipper2 (WebAssembly) to compute offset paths, pocket passes, or drill strategies.

Generated geometry appears in the Operations List (left sidebar, bottom) as a bucket with stage nodes. Click a stage node to view its parameters or re-generate. If you change parameters after generating, the bucket is marked as invalidated until you regenerate.

5. Generating Preview

After offsets are generated, click Generate Preview. This creates a tool-reach simulation — the offset paths stroked at the tool's diameter — showing exactly what material will be removed. The preview is visual only; no G-code is generated yet.

The preview stage also sets the Z-axis parameters (cut depth, multi-pass depth, entry strategy). These feed into the toolpath optimizer during export.

6. Exporting G-code

Click Export Manager (the button at the machine stage, or use the toolbar). The export modal opens with a summary of all operations that have reached the preview stage. From here you can:

1. Select your post-processor (GRBL, Marlin, LinuxCNC, etc.)
2. Click Calculate Toolpaths to run the optimization pipeline (staydown clustering, path ordering, segment simplification)
3. Review the G-code preview in the text area
4. Click Export Files to download

Operations using different tools must be exported as separate files — automatic tool change (M6) is not yet supported.

Operation Types

Profile Cut

A profile cut traces the boundary of a closed shape at a configured offset distance. The standard operation for cutting parts out of sheet material.

Cut Side

Outside: tool path runs outside the shape boundary (the shape is the part you keep). Inside: tool path runs inside (you keep the surrounding material). On: tool center follows the path exactly (no offset compensation).

Nesting Detection

When enabled, inner shapes are automatically detected as holes. A rectangle with a circle inside produces an outer cut and an inner cut with reversed winding — the circle becomes a raised island.

Holding Tabs

Optional bridges that keep the part attached to the stock during cutting. Configured by count, width, and height. The machine processor inserts Z-lifts at tab positions during G-code generation.

Profile cuts require closed geometry. Open paths will trigger a warning — close them in your SVG editor before importing.

Pocket Clearing

Pocket clearing removes all material inside a closed shape using concentric inward offset passes. The tool spirals inward from the boundary until no clearable area remains.

Stepover

The percentage of the tool diameter used as the distance between passes. Lower stepover = smoother floor finish but more passes. 40-60% is typical for wood.

Nesting Detection

Same as profile: inner shapes become islands that the pocket cuts around rather than through.

Pocket operations always use internal offsets. If the tool diameter is too large for the shape, no paths are generated — reduce the tool size or enlarge the design.

Drilling

Drilling converts SVG circles (and obround shapes) into drill holes or milled slots. The handler automatically classifies each primitive:

Holes (circles)

If the circle diameter is within 0.1mm of the tool diameter, a peck cycle is used. If the circle is larger, a helical or plunge-mill strategy clears the oversized hole.

Slots (obrounds)

Obround shapes are converted into milled slot paths — the tool follows the slot's centerline with width compensation.

Peck Depth

For peck drilling, controls how deep each peck goes before retracting to clear chips. Shallower pecks are safer for deep holes.

Scene Management

The scene is a tree of groups and shapes with full undo/redo. Every structural mutation (move, group, delete, assign operation) is recorded as a command and can be reversed.

Grouping

Select 2+ items, press Ctrl+G. A new group node is inserted at the position of the first selected item. The group inherits no transform — children keep their positions.

Ungrouping

Select a group, press Ctrl+Shift+G. Children are moved to the group's parent. The group's transform is composited into each child (via matrix multiplication and TRS decomposition) so their visual position doesn't change.

Drag-move

Click and drag on the canvas to move selected shapes. The delta is projected into each node's parent coordinate space so movement is correct even inside rotated or scaled groups. The move is recorded on mouse-up.

Multi-selection

Shift-click to toggle, Ctrl-click to add, or drag a marquee rectangle. Alt-click bypasses group selection to pick the individual leaf shape.

Shape Transforms

Each shape (and group) has a local TRS transform: translation (X/Y), rotation (degrees), and scale (uniform, with independent mirror on X/Y). The right sidebar's transform inspector shows the values for the selected shape.

Position (X / Y)

Relative nudge fields. Enter a value and press Enter to move the shape by that amount. The fields reset to 0 after each commit — they represent a delta, not an absolute position.

Rotation

Absolute rotation in degrees. Rotates around the shape's geometric center (or a pinned pivot if set by a prior rotation). Click the reset button to return to 0° and release the pinned pivot.

Scale

Uniform scale factor. 1.0 = original size, 2.0 = double. The mirror checkboxes flip the shape on the X or Y axis independently — they toggle the sign of scaleX or scaleY without changing the magnitude.

All transforms are non-destructive. The world-space position for rendering and G-code export is computed by multiplying the parent chain's affine matrices — the same math in TransformMath.js used throughout the application.

Machine Settings

Machine parameters are configured in the right sidebar's collapsible Machine Settings panel and in the per-operation parameter forms. These values directly affect the generated G-code.

Global Machine Parameters

Safe Z Height (typical: 5-15mm)

The Z height the tool retracts to when moving between cuts (rapid moves). Must be above all clamps and workholding.

Travel Z Height (typical: 2-5mm)

A lower retract height used for short hops between nearby cuts (staydown optimization). Faster than retracting to safe Z for every move.

Per-Operation Parameters

Tool Selection

Selects the cutting tool from the tool library. The tool's diameter is used to compute offset distances. V-bits use their tip diameter.

Cut Depth (total depth, mm)

How deep to cut in total. For multi-pass operations, this is divided by the depth-per-pass value.

Depth per Pass (mm)

Maximum material removed per Z-level pass. The machine processor automatically generates multiple depth levels when cut depth exceeds this value.

Feed Rate (mm/min)

Horizontal cutting speed. Higher = faster but rougher. Depends on material, tool, and machine rigidity.

Plunge Rate (mm/min)

Vertical entry speed when the tool descends into material. Usually 30-50% of the feed rate.

Spindle Speed (RPM)

Rotation speed of the spindle. CNC routers typically run 10,000-24,000 RPM depending on material and tool diameter.

The Export Manager

The Export Manager is a modal that opens when you reach the export stage. It coordinates the final translation from geometry into machine-ready G-code.

Workflow Inside the Export Manager

1. Review operations: The left panel lists all export-ready operations with their type, tool, and pass count.
2. Select post-processor: Choose your machine's dialect (GRBL, Marlin, etc.) from the dropdown. This affects G-code header format, spindle commands, and coordinate conventions.
3. Calculate Toolpaths: Click the button to run the three-stage optimization pipeline:
   • Geometry Translation: converts offset primitives into toolpath plans with entry/exit points
   • Toolpath Optimization: staydown clustering, nearest-neighbor path ordering, collinear segment simplification
   • Machine Processing: injects rapids, plunges, retracts, multi-depth passes, tab Z-lifts, and spindle commands
4. Preview: The generated G-code appears in the text preview with line count, operation count, estimated time, and total travel distance.
5. Export: Click Export Files to download. The filename includes the operation type and post-processor.

Post-Processor Notes

GRBL is the only post-processor tested on real hardware. All others (grblHAL, Marlin, LinuxCNC, Mach3, UCCNC, Makera, Roland RML) generate syntactically correct output but are considered experimental. Always dry-run G-code on your controller before cutting material.

Tips & Current Limitations

Best Practices

Start with the Built-in Example

Load the Mesa example from the welcome screen and walk through the complete workflow before processing your own files. This helps you understand what to expect at each stage.

Check Tool Diameter vs Shape Size

If pocket or profile generation returns zero paths, the tool is too large for the shape. Either reduce the tool diameter in the tool library or scale up your design.

Operation Order for Multi-Tool Jobs

When your design uses multiple tools, plan the cut order:

1. Pockets and internal features (while stock is rigid)
2. Drilling
3. Profile cuts last (parts may shift once cut free)

Each tool change requires a separate export file.

Common Issues

Canvas is Blank or Black

Cause: Browser GPU compositing issue (common on laptops with dual GPUs).

Solution: Close and restart the browser. The canvas should render correctly on reload.

"Open Paths Detected" Warning

Cause: Profile and pocket operations require closed shapes. Your SVG has paths that don't form closed loops.

Solution: Open the SVG in your vector editor and close the paths (Join nodes, or use Path → Close Path). Re-import.

Shapes Import at Wrong Position

Cause: SVG transforms (translate, rotate, matrix) on parent elements can cause unexpected placement.

Solution: In Inkscape, select all and use Edit → Paste In Place after flattening transforms. In Figma, export with "Flatten" enabled.

Offset Generation Takes a Long Time

Cause: Boolean operations on complex geometry (many points, many passes) are computationally intensive.

Solution: Reduce the number of passes, increase stepover, or simplify the SVG geometry before import.

Current Limitations (v1.0)

No laser pipeline

CNC G-code export only. Laser/vector export is planned.

No tool change commands

Operations using different tools must be exported as separate G-code files.

Engraving, V-Carve, Pattern, and 3D Relief

Listed in the UI but not yet functional. Engraving and pattern generation are coming shortly; v-carve and 3D relief require the planned 3D preview system.

Bézier offsetting

Bézier curves from SVGs are interpolated into line segments before offsetting. True analytic Bézier offsetting is not yet supported.

Touch pinch-to-zoom

Two-finger pinch zoom works during pan but is not available on the default select tool. Known gap.

No undo for operation assignment changes

Operation assignment is undoable via Ctrl+Z, but parameter edits within the operation panel are not individually tracked in the undo stack.