#Kerfio Real-Time Machine Progress Preview, Animated Toolhead Visualization, and Live Camera Overlay Specification

#Purpose

This document defines a shared Kerfio module for all machine sections:

1. CNC Progress Preview
2. Laser Progress Preview
3. 3D Printer Progress Preview
4. Live Camera Overlay / Camera Merge System
5. Real-Time Toolhead Animation
6. Job Simulation + Actual Machine Tracking

The goal is to give Kerfio a modern, professional, interactive preview that shows the machine creating the object step by step in real time.

The user should be able to see:

• Current machine head position
• Completed toolpath
• Remaining toolpath
• Live progress percentage
• Estimated remaining time
• Current operation
• Current G-code line
• Machine status
• Material/object being created
• Optional live camera feed merged with digital preview

This preview should become one of the signature features of Kerfio.

#Product Name

Recommended module name:

Kerfio Live Machine Preview

Alternative names:

• Real-Time Job Preview
• Machine Progress View
• Live Toolpath Preview
• Digital Twin Preview
• Live Build Preview
• Live Cut Preview
• Live Engraving Preview

Recommended final name inside app:

Live Machine Preview

#Core Concept

Kerfio should use one shared preview engine for CNC, Laser, and 3D Printer.

The visual style changes depending on the machine type, but the engine is shared.

G-code / Toolpath
→ Parser
→ Motion Timeline
→ Preview Renderer
→ Real-Time Machine State
→ Animated Toolhead + Progress View
→ Optional Camera Overlay

The user should not only see a static preview before starting. During the job, Kerfio should animate the progress and show the object being created.

#Main Preview Modes

Kerfio should support three main preview modes:

#Simulation Preview

Before running the job, Kerfio simulates the process virtually.

Purpose:

• Check path
• Check job boundaries
• Check tool movement
• Detect possible errors
• Estimate job time
• Show expected result

#Live Machine Preview

While the machine is running, Kerfio shows real-time progress.

Purpose:

• Show current head/nozzle/spindle/laser position
• Show completed path
• Show remaining path
• Show object creation step by step
• Show status and warnings

#Camera-Merged Preview

If the machine has a camera, Kerfio merges camera feed with digital preview.

Purpose:

• See real object and digital toolpath together
• Monitor the actual job visually
• Align digital preview to the real bed
• Detect mismatch between expected and actual result

#Shared Preview Architecture

Recommended architecture:

Frontend React UI
  ↓
Preview State Store
  ↓
G-code Parser / Toolpath Parser
  ↓
Motion Timeline Generator
  ↓
Renderer Layer
  ↓
Machine State Stream
  ↓
Camera Stream Optional

#Frontend Responsibilities

The frontend handles:

• Rendering preview
• Animating toolhead
• Showing progress
• Showing camera overlay
• User interaction
• Layer visibility
• Speed control for simulation
• Real-time display during actual job

#Backend Responsibilities

The backend handles:

• Parsing large G-code if needed
• Streaming machine state
• Receiving serial/controller updates
• Managing camera stream
• Sending progress updates
• Job timing and logging
• Safety state reporting

#Core Data Sources

The preview should combine multiple data sources.

#Planned Toolpath

Generated from:

• CNC CAM G-code
• Laser raster/vector G-code
• 3D printer slicer G-code

Used for:

• Full expected path
• Remaining path
• Estimated progress
• Bounding box
• Simulation

#Real Machine State

Read from controller:

• Current position
• Machine status
• Feed rate
• Spindle/laser/extruder state
• Temperature if 3D printer
• Alarm/error state
• Current line number if available

For GRBL/FluidNC, this may come from status reports like:

<Run|MPos:10.000,20.000,0.000|FS:1200,0>

For 3D printers, this may come from firmware responses, temperature reports, and sender state.

#Sender Progress

If exact machine line tracking is limited, Kerfio can track progress from its own sender:

• Current sent G-code line
• Confirmed/acknowledged lines
• Buffer state
• Job elapsed time
• Estimated remaining time

#Camera Stream

Optional source:

• USB camera
• Raspberry Pi camera stream
• IP camera
• WebRTC stream
• MJPEG stream
• RTSP stream

Used for:

• Live video layer
• Bed monitoring
• Overlay with toolpath
• Manual alignment
• Future AI monitoring

#Visual Layers

Kerfio Live Machine Preview should use layers.

#Common Layers

• Machine bed / build plate
• Work area boundary
• Job bounding box
• Planned path
• Completed path
• Remaining path
• Current toolhead position
• Travel moves
• Active cutting/engraving/printing moves
• Warnings and limits
• Camera feed layer
• Grid and rulers
• Object/result layer

#CNC-Specific Layers

• Stock material block
• Toolpath lines
• Current cutter/spindle position
• Removed material preview
• Pocket areas
• Profile cuts
• Drill points
• Tabs
• Safe Z moves
• Current depth layer

#Laser-Specific Layers

• Laser bed
• Raster scan path
• Vector cut path
• Engraved/completed pixels
• Burn simulation result
• Current laser head position
• Laser on/off indicator
• Power intensity visualization
• Cut/score/engrave layer colors

#3D Printer-Specific Layers

• Build plate
• Printed object preview
• Current layer
• Previous layers
• Future layers
• Nozzle position
• Extrusion path
• Travel moves
• Supports
• Infill
• Perimeters
• Temperature indicators

#CNC Real-Time Preview

#Purpose

The CNC preview should show how the router/spindle is cutting material step by step.

#Required Features

• Show stock material dimensions
• Show toolpath before job
• Animate spindle/head movement
• Show completed cut path
• Show remaining path
• Show current Z depth
• Show current operation:
  • Profile
  • Pocket
  • Drill
  • Engrave
  • Facing
• Show current tool
• Show feed rate
• Show spindle RPM if available
• Show elapsed time
• Show remaining time
• Show warnings

#Advanced CNC Features

• Removed material simulation
• 2.5D depth color visualization
• Tool diameter visualization
• Cut direction arrows
• Tabs visualization
• Collision warning later
• Probe result overlay later

#CNC Toolhead Animation

The animated head should show:

• Router/spindle icon
• Current X/Y/Z position
• Active cutting state
• Travel state
• Tool diameter circle
• Z depth shadow

Example states:

Idle: gray spindle
Travel: blue movement
Cutting: highlighted cutting path
Paused: yellow icon
Alarm: red icon

#Laser Real-Time Preview

#Purpose

The laser preview should show the laser head engraving/cutting the design in real time.

#Required Features

• Show laser bed
• Show imported image/vector path
• Show raster scan progress
• Show completed engraving pixels/lines
• Show remaining engraving area
• Show cut path progress
• Show current laser head position
• Show laser on/off status
• Show current power value
• Show speed/feed rate
• Show layer currently running
• Show estimated remaining time

#Raster Engraving Preview

For raster jobs, Kerfio should show:

• Current scan line
• Completed lines
• Remaining lines
• Bidirectional scan animation
• Laser intensity map
• Burn simulation result building gradually

#Vector Laser Preview

For vector cut/score jobs, Kerfio should show:

• Current vector path
• Completed cut segments
• Remaining cut segments
• Layer color
• Cut/score/engrave operation type

#Laser Toolhead Animation

The animated head should show:

• Laser head icon
• Active laser beam indicator when laser is on
• Power intensity glow
• Current X/Y position
• Current operation type

Example states:

Travel: head moves with laser off
Engraving: head emits soft beam/glow
Cutting: stronger beam/glow
Paused: warning ring around head
Alarm: red flashing state

#3D Printer Real-Time Preview

#Purpose

The 3D printer preview should show the object being printed layer by layer.

#Required Features

• Show build plate
• Show full sliced model preview
• Show current layer
• Show completed layers
• Show remaining layers
• Animate nozzle position
• Show extrusion path
• Show travel moves
• Show supports
• Show infill/perimeters/top/bottom paths
• Show temperatures:
  • Nozzle temperature
  • Bed temperature
• Show fan speed
• Show print speed
• Show elapsed time
• Show remaining time

#Layer Progress

The user should be able to see:

• Current layer number
• Total layer count
• Layer height
• Z position
• Current feature type:
  • Perimeter
  • Infill
  • Support
  • Travel
  • Bridge
  • Top solid
  • Bottom solid

#3D Printer Toolhead Animation

The animated head should show:

• Nozzle icon
• Extrusion state
• Current X/Y/Z position
• Filament extrusion line
• Travel movement
• Layer-building animation

Example states:

Heating: orange temperature indicator
Printing: nozzle lays down material
Travel: nozzle moves without extrusion
Paused: yellow indicator
Error: red warning

#Camera Merge / Live Video Overlay

#Purpose

If the machine has a camera, Kerfio should merge the live camera with the digital preview.

This is especially useful for:

• CNC bed monitoring
• Laser engraving alignment
• Laser job supervision
• 3D printer print monitoring
• Visual inspection
• Detecting mismatch between expected and actual result

#Supported Camera Sources

Kerfio should support:

• USB webcam
• Raspberry Pi camera
• Raspberry Pi stereo camera later
• IP camera
• MJPEG stream
• RTSP stream
• WebRTC stream

Recommended first version:

USB camera + MJPEG/WebRTC camera stream

For Babak's CNC vision project with Raspberry Pi 5 and stereo IMX219 camera, the recommended source is:

Raspberry Pi 5 camera service → WebRTC stream → Kerfio React UI

#Camera Overlay Modes

Kerfio should support several modes:

#Side-by-Side Mode

Digital preview and camera feed appear next to each other.

Best for:

• Simple monitoring
• Low setup complexity

#Picture-in-Picture Mode

Camera appears as a small floating window over the preview.

Best for:

• Compact UI
• Monitoring while focusing on toolpath

#Transparent Overlay Mode

Camera feed is placed under the digital toolpath with adjustable opacity.

Best for:

• Alignment
• Checking if real material matches digital design

#Calibrated Overlay Mode

Digital toolpath is geometrically aligned to the camera view.

Best for:

• Professional camera-based bed alignment
• Laser positioning
• CNC vision workflows

#Camera Calibration

To merge camera and toolpath correctly, Kerfio needs camera calibration.

#Basic Manual Calibration

The user selects reference points on the camera image and matching points on the digital bed.

Example:

Point 1: Bed front-left
Point 2: Bed front-right
Point 3: Bed back-right
Point 4: Bed back-left

Kerfio then maps camera pixels to machine coordinates.

#Homography Mapping

For top-down cameras, Kerfio can use a 2D perspective transform / homography.

Camera pixel coordinates → Machine X/Y coordinates

This allows the digital toolpath to overlay on the live video.

#Advanced Calibration Later

Future features:

• Lens distortion correction
• ArUco marker calibration
• Checkerboard calibration
• Automatic bed boundary detection
• Stereo depth calibration for Raspberry Pi stereo camera
• Tool/nozzle/laser spot detection

#Interactive Controls

The preview should be interactive.

#Common Controls

• Zoom
• Pan
• Rotate view
• Fit to job
• Fit to bed
• Toggle grid
• Toggle camera
• Toggle completed path
• Toggle remaining path
• Toggle travel moves
• Toggle warnings
• Change simulation speed
• Scrub timeline before job
• Pause preview animation
• Jump to current machine position

#During Live Job

Controls:

• Follow toolhead on/off
• Lock view to bed
• Camera opacity slider
• Show current G-code line
• Show machine coordinates
• Show work coordinates
• Show elapsed/remaining time
• Pause/feed hold
• Resume
• Stop
• Emergency stop

Important: Control buttons that affect the machine should be visually separated from preview-only controls.

#Progress Timeline

Kerfio should show a progress timeline.

Common timeline data:

• Total job length
• Current time position
• Completed percentage
• Current operation
• Current layer/scanline/depth
• Warnings/events
• Pauses
• Errors

#CNC Timeline

Timeline markers:

• Toolpath start
• Pocket operation
• Drill operation
• Profile cut
• Tool change
• Final pass

#Laser Timeline

Timeline markers:

• Raster engraving start
• Vector score start
• Cut layer start
• Pass 1/2/3
• Air assist on/off

#3D Printer Timeline

Timeline markers:

• Heating
• First layer
• Supports
• Infill-heavy region
• Layer changes
• Cooling commands
• Filament change
• Print complete

#Progress Calculation

Kerfio should use multiple progress methods depending on machine capabilities.

#Best Method: Actual Controller Feedback

Use when controller reports:

• Current position
• Status
• Line number
• Planner/buffer state

#Practical Method: Sender Line Tracking

If controller feedback is limited, Kerfio tracks:

• Lines sent
• Lines acknowledged
• Total lines

Progress:

acknowledged_lines / total_lines

#Better Method: Motion Time Estimation

For visual progress, line count is not always accurate. Some lines take longer than others.

Kerfio should eventually estimate progress from:

• Segment length
• Feed rate
• Acceleration approximation
• Raster scan time
• Layer time

#Camera-Based Progress Later

Future AI system can compare camera view with expected output.

Examples:

• Detect if laser engraving is happening
• Detect if CNC cut is producing expected path
• Detect if 3D print failed
• Detect smoke/fire risk for laser
• Detect spaghetti failure in 3D print

#G-code Parser Requirements

Kerfio needs a strong G-code parser.

#Common Parser Responsibilities

• Read G-code file
• Remove comments if needed
• Track modal state
• Track coordinates
• Track feed rate
• Track units: mm/inch
• Track absolute/relative movement
• Track work offsets if needed
• Track current line number
• Build motion segments

#CNC Parser Additions

• Z depth
• Spindle state
• Tool number
• Arc moves G2/G3
• Drilling cycles later
• Work coordinate systems

#Laser Parser Additions

• Laser state M3/M4/M5
• S power value
• Raster movement detection
• Engraving/cutting state
• Power intensity visualization

#3D Printer Parser Additions

• Extrusion axis E
• Retraction detection
• Temperature commands
• Fan commands
• Layer comments
• Feature comments from slicer

#Renderer Strategy

#2D Renderer

Best for:

• Laser
• Simple CNC top view
• G-code path preview

Recommended tools:

• Canvas/WebGL
• Konva.js for UI overlays
• PixiJS for high-performance 2D rendering

#3D Renderer

Best for:

• 3D printer
• CNC stock simulation
• 3D toolpath view

Recommended tools:

• Three.js
• React Three Fiber optional
• WebGL line rendering

#Hybrid Renderer

Kerfio should support hybrid view:

• 2D top view
• 3D perspective view
• Camera overlay view

#Modern UI Design Requirements

Kerfio preview should look modern and professional.

#Visual Style

Recommended:

• Dark technical workspace option
• Clean bed grid
• Smooth animated head movement
• Soft glow for laser beam
• Clear color coding
• Minimal clutter
• Floating status cards
• Timeline at bottom
• Layer/operation panel on side
• Camera opacity slider

#Status Cards

Show compact cards:

Progress: 43%
Time Left: 18m 20s
Position: X120.5 Y40.2 Z-1.5
Operation: Pocket Pass 2
Speed: 900 mm/min
Power/RPM/Temp: Depends on section

#Machine-Specific Status Cards

#CNC

• Spindle RPM
• Feed rate
• Z depth
• Tool
• Operation

#Laser

• Laser power
• Scan line
• Layer
• Speed
• Pass

#D Printer

• Nozzle temp
• Bed temp
• Fan
• Layer
• Filament used

#Data Model

#Toolpath Segment

{
  "id": "seg_001",
  "type": "linear",
  "machine_type": "laser",
  "start": { "x": 0, "y": 0, "z": 0 },
  "end": { "x": 10, "y": 0, "z": 0 },
  "feed_rate": 3000,
  "line_number": 120,
  "operation": "engrave",
  "active": true,
  "power": 650,
  "estimated_time_ms": 220
}

#Machine State

{
  "status": "running",
  "machine_type": "laser",
  "position": { "x": 120.5, "y": 40.2, "z": 0 },
  "work_position": { "x": 120.5, "y": 40.2, "z": 0 },
  "feed_rate": 1800,
  "current_line": 5420,
  "progress_percent": 43.2,
  "operation": "raster_engraving",
  "timestamp": "2026-05-31T12:00:00Z"
}

#Camera Calibration Object

{
  "camera_id": "cam_001",
  "machine_profile_id": "laser_400x400",
  "calibration_type": "homography",
  "image_points": [
    [120, 80],
    [880, 90],
    [890, 680],
    [110, 690]
  ],
  "machine_points": [
    [0, 0],
    [400, 0],
    [400, 400],
    [0, 400]
  ],
  "opacity": 0.65
}

#Backend API Endpoints

Recommended endpoints:

POST /api/preview/parse-gcode
GET  /api/preview/jobs/{job_id}/toolpath
GET  /api/preview/jobs/{job_id}/state
WS   /api/preview/jobs/{job_id}/stream
POST /api/preview/jobs/{job_id}/simulate
POST /api/preview/jobs/{job_id}/seek
GET  /api/camera/sources
POST /api/camera/connect
GET  /api/camera/{camera_id}/stream
POST /api/camera/{camera_id}/calibrate
GET  /api/camera/{camera_id}/calibration

For real-time updates, use WebSocket:

WS /api/machine/{machine_id}/state-stream
WS /api/jobs/{job_id}/progress-stream

#Frontend Components

Recommended React components:

LiveMachinePreview.tsx
ToolpathCanvas2D.tsx
ToolpathViewer3D.tsx
AnimatedToolhead.tsx
MachineStatusCards.tsx
ProgressTimeline.tsx
CameraOverlay.tsx
CameraCalibrationPanel.tsx
LayerVisibilityPanel.tsx
GcodeLineInspector.tsx
MachineControlBar.tsx

Machine-specific wrappers:

CncLivePreview.tsx
LaserLivePreview.tsx
Printer3DLivePreview.tsx

#Recommended Technology Stack

#Frontend

• React + TypeScript
• Vite
• Tailwind
• Zustand or Redux Toolkit
• Three.js
• React Three Fiber optional
• PixiJS or WebGL for high-performance 2D paths
• Konva.js for interactive overlays
• Web Workers for G-code parsing
• WebSocket for real-time state
• WebRTC for camera streams

#Backend

• Python FastAPI
• WebSocket support
• pyserial for machine communication
• OpenCV for camera calibration
• aiortc for WebRTC if needed
• SQLite for job history and calibration data
• NumPy for geometry calculations

#Performance Requirements

The preview must handle large files.

#Large G-code Handling

Kerfio should support:

• Millions of G-code lines if needed
• Progressive parsing
• Segment simplification for zoomed-out view
• Level-of-detail rendering
• Web Worker parsing
• Chunked toolpath loading
• GPU rendering for path lines

#Live Rendering

Target:

• Smooth animation at 30–60 frames per second where possible
• No UI freeze during parsing
• Progressive preview while parsing
• Low CPU camera overlay mode

#Safety Requirements

The preview is visual, but machine controls are real.

Important safety rules:

• Emergency stop must always be visible
• Stop/pause controls must be separated from view controls
• Camera delay must be shown if significant
• Preview must not imply physical safety guarantee
• If real position differs from expected path, show warning
• If machine stops responding, freeze preview and alert user
• If job line tracking is uncertain, show estimated status clearly

#MVP Feature Set

MVP means Minimum Viable Product.

#Shared MVP

• Parse G-code
• Show full toolpath preview
• Show animated head/nozzle/spindle
• Show completed vs remaining path
• Show progress percent
• Show elapsed/remaining time
• Show current position
• Show current G-code line
• Use sender line tracking
• WebSocket state updates
• Basic 2D/3D preview depending on section

#CNC MVP

• 2D top-view toolpath
• Animated spindle position
• Z-depth color indication
• Completed path highlight
• Remaining path dimmed

#Laser MVP

• 2D bed preview
• Raster scan progress
• Vector cut progress
• Laser-on glow indicator
• Power value display

#3D Printer MVP

• 3D build plate preview
• Layer slider
• Current layer animation
• Nozzle position
• Extrusion/travel path distinction
• Temperature cards

#Camera MVP

• Connect USB/MJPEG/WebRTC camera stream
• Show camera side-by-side
• Picture-in-picture camera window
• Manual opacity overlay

#Professional Phase 2 Features

• Calibrated camera overlay
• Homography-based bed mapping
• Toolpath aligned on video
• Multi-camera support
• CNC removed material simulation
• Laser burn simulation updated live
• 3D print object build-up visualization
• Timeline scrubber
• Real-time line inspector
• Job event markers

#Advanced Phase 3 Features

• AI camera monitoring
• Laser smoke/fire detection
• 3D print spaghetti failure detection
• CNC chip/dust/cut anomaly detection
• Camera-based job alignment
• Auto bed boundary detection
• Tool/nozzle/laser spot detection
• Stereo camera depth support
• Digital twin calibration
• Remote monitoring dashboard

#Section Integration

#CNC Integration

CNC CAM Job
→ Generate G-code
→ Parse toolpath
→ Simulate
→ Start job
→ Live preview follows spindle
→ Optional camera overlay shows material

#Laser Integration

Laser Image/Vector Job
→ Generate G-code
→ Parse raster/vector path
→ Simulate burn/cut
→ Start job
→ Live preview follows laser head
→ Optional camera overlay shows engraving/cutting result

#3D Printer Integration

3D Model
→ Slice to G-code
→ Parse layers
→ Preview layers
→ Start print
→ Live preview follows nozzle
→ Optional camera overlay shows actual print

#Important Design Decision

Kerfio should not implement three separate preview systems.

Recommended:

One shared Live Machine Preview engine
+ machine-specific visualization adapters

Shared engine:

• G-code parsing
• Progress tracking
• WebSocket state
• Timeline
• Camera overlay
• Toolhead animation framework

Machine adapters:

• CNC adapter
• Laser adapter
• 3D Printer adapter

This keeps the architecture clean and reusable.

#Final Recommendation

Kerfio should include a modern Live Machine Preview module across CNC, Laser, and 3D Printer sections.

This feature should show the machine creating the object in real time with:

• Animated spindle / laser head / printer nozzle
• Completed path
• Remaining path
• Current operation
• Current coordinates
• Progress percentage
• Timeline
• Estimated remaining time
• G-code line inspection
• Camera feed when available
• Optional calibrated camera overlay

This will make Kerfio feel much more professional than a simple G-code sender.

The best implementation path is:

Phase 1: Digital G-code preview + animated progress
Phase 2: Live machine state tracking + camera side-by-side
Phase 3: Calibrated camera overlay
Phase 4: AI monitoring and digital twin features

The final user experience should feel like watching a modern digital twin of the machine working, with optional real camera confirmation from the actual hardware.