JSON API - Blade Generation System

Blade Retention Schema (v1.5 - Updated)

Configuration for blade-to-blade interlocking and blade-to-baseplate mounting.

🆕 New in V1.5: Complete Retention System

Comprehensive configuration for all retention mechanisms including crossover gaps, shift-lock tabs, and captured nut mounting.

→ See full Blade Retention documentation

Blade-to-Blade Interlocking

"bladeRetention": { "bladeToBlade": { "type": "keyhole", // "keyhole" | "friction-slot" | "cross-pin" | "weld-only" | "none" // Slot clearances "clearanceLeft": 0.1, // mm - gap on left side of N-tab "clearanceRight": 0.1, // mm - gap on right side of N-tab "additionalClearance": 0, // mm - extra on BOTH sides // Crossover configuration (where N-blade meets U-blade) "crossover": { "mode": "ratio", // "ratio" | "fixed" "ratio": 0.5, // 0.0-1.0 (50% = middle of intersection) "fixedHeight": 25, // mm (if mode=fixed, always this height) "gapOrRadius": "gap", // "gap" | "radius" "gap": 2, // mm flat clearance between faces "radius": 3 // mm fillet radius (if gapOrRadius=radius) }, // Keyhole options "keyhole": { "enabled": true, "entryDiameter": "auto", "position": "bottom" }, // Relief holes for serviceability "reliefHoles": { "enabled": true, "count": 2, "diameter": 4, "offsetFromSlot": 8 } } }

Crossover Height Modes

Mode	Parameter	Description
`ratio`	`ratio: 0.5`	50% of intersection height (scales with blade)
`fixed`	`fixedHeight: 25`	Always 25mm from bottom (constant)

Blade-to-Baseplate Mounting

"bladeRetention": { "bladeToBaseplate": { "type": "tabSlot", // "tabSlot" | "shiftLock" | "capturedNut" | "weld" // Tab configuration "tab": { "count": "auto", "spacing": 100, // mm between tabs "width": 20, // mm "depth": "through" // "through" | "partial" | number (mm) }, // Shift-lock options (blade shifts sideways to lock) "shiftLock": { "shiftDistance": 5, // mm blade shifts to lock "lockLip": 3, // mm undercut depth "clipType": "nucleo", // "nucleo" | "spring" | "custom" "generateClipDXF": true }, // Captured nut options (screw from below) "capturedNut": { "threadSize": "M6", "nutType": "hex", "screwHead": "socket", // "socket" | "countersunk" | "button" "countersinkBaseplate": true, "nutSpacing": 150 // mm between nut locations } } }

Mounting Type Comparison

Type	Serviceability	Strength	Best For
`tabSlot`	Excellent	Medium	Prototypes, light duty
`shiftLock`	Good	High	Production fixtures
`capturedNut`	Excellent	High	Heavy duty, serviceable
`weld`	None	Very High	Permanent fixtures

Architecture Overview

Language-independent parameter dialogs using JSON Schema with universal renderers.

Data Flow

┌─────────────────────────────────────────────────────┐ │ JSON Schema (blade_params.schema.json) │ │ - Defines all fields, types, validation │ │ - Localizable labels via i18n keys │ └─────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────┐ │ React + RJSF (Web UI) │ │ - Runs in browser OR Electron │ │ - Single codebase for web + desktop │ └─────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────┐ │ Output: blade_params.json │ │ - PEPS macro reads this via PAC/file I/O │ └─────────────────────────────────────────────────────┘

Schema Structure (v1.2)

✅ JSON Parser Complete

6/6 tests passing. Parser integrated with blade generation macros.

Section	Purpose
`version`	Schema version for compatibility
`metadata`	Job ID, part file, timestamps
`blade`	Core geometry (position, thickness, length)
`profile`	Offset, gravity direction, contact arc mode
`trimming`	Open side, extensions, gravity trim
`partRetention`	Plungers, grippers, clamp shelves
`edgeModifications`	Taper, blend, notches
`edgeFeatures`	NEW Pocket wall detection config (peaks, recess, fillets)
`modularAssembly`	Segmentation, T-wedges, feet
`output`	Layer name, color, DXF generation
`processingMode`	Headless, progress, debug level, graphics control
`dangerZone`	NEW Sharp edge safety marking and blending
`materialSuggestion`	NEW Weight-based thickness recommendation
`aiAssist`	NEW External AI integration for weld analysis

⚙️ Processing Mode Options (v1.2)

Control debug output, progress display, and graphics behavior:

"processingMode": { "headless": false, "showProgress": true, "progressMinDelta": 10, "debugLevel": 0, "debugLevelOverride": true, // NEW: JSON overrides fxGlobals.var "limitViewMode": true, // NEW: Zoom to sphere during updates "suppressGraphics": true, // NEW: Skip graphics refresh (50%+ speedup) "mosaicFilterMode": 0 // NEW: 0=auto, 1=always, 2=never (filter overhead control) }

Field	Type	Description
`debugLevelOverride`	boolean	When true, JSON debugLevel takes precedence over fxGlobals.var
`limitViewMode`	boolean	Zoom camera to progress sphere area (reduces repaint overhead)
`suppressGraphics`	boolean	Disable graphics refresh during heavy ops (major performance gain)
`mosaicFilterMode`	integer	0=AUTO (skip for simple/orthogonal blades), 1=ALWAYS run O(n²) filter, 2=NEVER (fastest)

📁 File Locations

File	Path
Schema	`schemas/blade_params.schema.json`
Examples	`io/json/examples/`
Parser	`macros/fxReadJsonParams.ovm`

Mixed Units Support

The JSON API supports mixed units within a single file. Plain numbers default to metric (mm), while explicit unit suffixes allow inch values. All values are automatically converted to the current working units.

Supported Formats

Format	Example	Interpretation
Plain number	`6`	6 mm (metric default)
Explicit mm	`"6mm"`	6 mm
Explicit inch	`"0.25in"`	0.25 inches → 6.35 mm
Fraction	`"1/4"`	0.25 inches (fractions default to inches)
Fraction + unit	`"1/4in"`	0.25 inches → 6.35 mm
Fraction mm	`"3/2mm"`	1.5 mm

Example: Mixed Units in One File

{ "blade": { "thickness": "1/4in", // Fraction → 6.35mm "overshoot": "1in", // Decimal inch → 25.4mm "stockMargin": 25 // Plain number → 25mm }, "profile": { "offset": "0.125in" // Decimal inch → 3.175mm }, "trimming": { "topExtension": "0.5in", // Decimal inch → 12.7mm "bottomExtension": 15, // Plain number → 15mm "sideExtension": { "left": "3/8in", // Fraction → 9.525mm "right": 10 // Plain number → 10mm } }, "edgeModifications": { "blend": { "radius": "1/16in" // Fraction → 1.5875mm } } }

Fields Supporting Mixed Units

Section	Fields
blade	`thickness`, `overshoot`, `stockMargin`
profile	`offset`
trimming	`topExtension`, `bottomExtension`, `openSideCutLevel`, `sideExtension.left`, `sideExtension.right`, `gravityTrim.distanceFromContact`
edgeModifications	`blend.radius`

Note: Coordinate values (x, y, z in positions, normals, from/to points) are always interpreted in current working units and do not support unit suffixes.

✅ Test Coverage

Mixed units parsing verified by fxTestMixedUnits.ovm (9/9 tests passing).

Test file: io/json/testing/blade_mixed_units_test.json

Material Suggestion (New in v1.2)

Automatic blade thickness recommendation based on part weight calculation.

Configuration

"materialSuggestion": { "suggestThicknessFromWeight": true, "partMaterial": "steel", "customDensity": null, "thicknessLookupTable": "default", "overrideIfSet": false }

Supported Materials

Material	Density (kg/m³)
steel	7850
aluminum	2700
stainless	8000
brass	8500
copper	8960
titanium	4500
custom	Use `customDensity`

Default Thickness Lookup

Part Weight	Suggested Blade Thickness
< 10 kg	3 mm
10 - 50 kg	5 mm
50 - 200 kg	6 mm
> 200 kg	8 mm

Custom lookup tables can be provided via CSV file path.

AI Integration (New in v1.2)

Optional external AI service integration for intelligent fixture analysis.

Configuration

"aiAssist": { "analyzeWeldPositions": true, "weldAnalysisEndpoint": "https://api.example.com/weld-analyze", "validateFixtureDesign": false, "designValidationEndpoint": "https://api.example.com/validate", "apiKey": "sk-xxx-ref-secure-store", "timeout": 30 }

Available Services

Service	Flag	Description
Weld Position Analysis	`analyzeWeldPositions`	Sends part STL + blade positions to AI, receives optimal weld bead coordinates and torch approach vectors
Design Validation	`validateFixtureDesign`	Sends complete fixture assembly to AI, receives collision warnings, stress analysis, and improvement suggestions

⚠️ Fallback Behavior

If AI service is unavailable or times out:

Blade generation continues without AI suggestions
Warning logged to output JSON
Manual weld positioning required

Timeout: 5-300 seconds (default: 30)

Danger Zone Marking (New in v1.3)

Automatic safety marking for sharp edges on thin blade faces. Identifies dangerous edges and marks them with red strips for operator awareness.

Configuration

"dangerZone": { "enabled": false, "distance": 5, "angleThreshold": 90, "blend": false }

Parameters

Field	Type	Default	Description
`enabled`	boolean	false	Master enable for danger zone marking
`distance`	number	5	Width of danger strip from edge (mm). Also used as blend radius if blending is enabled
`angleThreshold`	number	90	Maximum angle between faces to consider an edge "sharp" (degrees). Edges where adjacent face normals meet at this angle or less are marked
`blend`	boolean	false	Apply constant blend to inner edges where two red (danger) faces meet

How It Works

Thin Face Detection - Only processes edges on faces where the shortest edge ≤ material thickness
Sharp Edge Identification - Finds edges where both adjacent faces are thin AND meet at an acute angle
Danger Strip Creation - Imprints red-colored strips on both faces adjacent to each danger edge
Optional Blending - If enabled, applies constant blend to edges where two red faces meet (inner corners)

Visual Result

BEFORE: AFTER: ┌───────────┐ ┌───────────┐ │ │ │█████ │ ← Red danger strip │ │ │█████ │ │ BLADE ├── │ BLADE ├██──── │ │ │ │↑ │ │ │ │Red on both faces └───────────┘ └───────────┘ Sharp corner Marked for safety

⚠️ Usage Notes

Only marks edges on thin faces (shortest edge ≤ blade thickness)
Large flat faces (like blade sides) are ignored even if they have sharp corners
Red face IDs are tracked and stored for blend edge detection
Blend radius equals the distance parameter

Global Variables (fxJSON.var)

Variable	JSON Path	Description
`i_FX_JSON_DANGER_ZONE_ENABLED`	dangerZone.enabled	Master enable (0/1)
`w_FX_JSON_DANGER_ZONE_DIST`	dangerZone.distance	Strip width and blend radius
`w_FX_JSON_DANGER_ZONE_ANGLE`	dangerZone.angleThreshold	Angle threshold (degrees)
`i_FX_JSON_DANGER_ZONE_BLEND`	dangerZone.blend	Enable blending (0/1)
`i_FX_DANGER_ZONE_COUNT`	(output)	Number of zones marked

Direct Macro Call

'*** Via JSON configuration: { "dangerZone": { "enabled": true, "distance": 5, "angleThreshold": 90, "blend": true } } '*** Or direct macro call after setting globals: i_FX_JSON_DANGER_ZONE_ENABLED = 1 w_FX_JSON_DANGER_ZONE_DIST = 5 w_FX_JSON_DANGER_ZONE_ANGLE = 90 i_FX_JSON_DANGER_ZONE_BLEND = 1 call fxDangerZoneMarking i_bladeBody

Trimming & Open Side Cut

Control blade trimming for part extraction clearance. The openSide feature removes material from the blade using boolean subtraction, creating clean vertical edges that eliminate "nubs" that would otherwise form when the blade follows part contours around radii.

Configuration

"trimming": { "openSide": "bottom", // "none", "top", or "bottom" "openSideCutLevel": 0, // mm relative to contact point "sideExtension": { "left": 0, "right": 0 }, "gravityTrim": { "enabled": false, "distanceFromContact": 25, "trimSide": "below" }, "topExtension": 10, "bottomExtension": 10 }

🔪 Open Side Cut Level

The openSideCutLevel parameter positions the cut plane relative to the part's contact point:

Value	Effect	Use Case
`0`	Cut exactly at contact point	Part rests directly on blade edge
`+5`	Cut 5mm above contact	Gap for extraction clearance
`-3`	Cut 3mm below contact	Blade wraps part slightly (retention)

Nub Problem & Solution

WITHOUT Open Side: WITH openSide="bottom": ┌─────────────┐ ┌─────────────┐ │ PART │ │ PART │ ╰─────────────╯ ╰─────────────╯ ════╲ ╱════ ║ ║ ╲ ╱ ║ ║ ╲─────────╱ └─────────────┘ ↑ "nubs" block extraction ↑ clean vertical edges

The boolean subtraction cube removes all material below the cut level, including any curved sections that would otherwise create extraction interference.

Processing Order

Side extensions applied (left/right)
Profile generated and extruded to 3D blade
Open side cut applied (boolean subtraction)
Edge modifications (taper, blend)

Note: openSide supersedes gravityTrim on the affected side. If openSide="bottom", the gravityTrim settings for the bottom are ignored.

Implementation Details

Macro	Purpose
`fxApplyOpenSideCut.ovm`	Boolean subtraction using oversized cube
`fxApplyOpenSideCutFromProfile`	Wrapper that extracts contact Z from profile data

Global variables:

w_FX_CONTACT_MIN_Z - Lowest contact Z (for openSide="bottom")
w_FX_CONTACT_MAX_Z - Highest contact Z (for openSide="top")

Edge Features Configuration (New in v1.4)

Configuration for the fxBladeEdgeFeatures system that identifies pocket walls for gripper placement, edge modifications, and other blade features.

🆕 New in V3.6

includePeaks and excludeRecess options for fine-grained wall selection.

Zone Configuration Schema

"edgeFeatures": { "global": { "includeFillets": true, "includePeaks": false, "excludeRecess": false, "debugLevel": 0 }, "zones": { "leftInside": { "includeFillets": true, "includePeaks": false, "excludeRecess": true }, "rightInside": { "includeFillets": true, "includePeaks": true, "excludeRecess": false }, "allInside": { "includeFillets": true } } }

Configuration Options

Option	Type	Default	Description
`includeFillets`	boolean	true	Include cylindrical fillet faces adjacent to pocket walls
`includePeaks`	boolean	false	Include walls on isolated peaks/towers not topologically connected to the main pocket floor
`excludeRecess`	boolean	false	Exclude walls adjacent to recessed/stepped floors (higher Z than main pocket floor)
`debugLevel`	integer	0	Debug output verbosity (0=none, 1=summary, 2=detailed, 3=verbose)

Zone Types

Zone	Description	Wall Normal Direction
`leftInside`	Left walls of U-channel pocket (walls pointing right into void)	NormX > +0.7
`rightInside`	Right walls of U-channel pocket (walls pointing left into void)	NormX < -0.7
`allInside`	All inside pocket walls	Either direction
`outside`	External blade walls	Faces away from part

Understanding Peaks vs Recess

PEAKS (isolated towers): RECESS (stepped shelves): ┌─────┐ Main floor ────────┐ │PEAK │ │ │walls│◄── includePeaks: true Recess floor ─────┐│ │ │ ││ ────┴─────┴──── Recess ◄──────┘│ Main pocket walls │ floor │ excludeRecess: true│ skips these walls ─┘

Peaks: Walls on isolated geometry (towers, pillars) that are not topologically connected to the main pocket floor. The topology walk from the main floor cannot reach them.

Recess: Walls adjacent to stepped/recessed floors that are higher (greater Z) than the main pocket floor. These are topologically connected but may not be desired for gripper placement.

Visual Indication (Debug Mode)

Color	Meaning
GREEN	Normal pocket walls (from topology walk)
MAGENTA	Peak walls (added by safety-net pass)
CYAN	Fillet faces
GRAY	Excluded recess walls

PEPS Global Variables

Variable	JSON Path	Description
`i_FX_INCLUDE_FILLETS`	edgeFeatures.global.includeFillets	Master fillet inclusion flag
`i_FX_INCLUDE_PEAKS`	edgeFeatures.global.includePeaks	Include isolated peak walls
`i_FX_EXCLUDE_RECESS`	edgeFeatures.global.excludeRecess	Exclude recess/stepped walls
`i_FX_EF_DEBUG`	edgeFeatures.global.debugLevel	Debug verbosity level

Example: Complex Blade with Peaks and Recess

{ "edgeFeatures": { "global": { "includeFillets": true, "includePeaks": false, "excludeRecess": false }, "zones": { "leftInside": { "includePeaks": true, // Include tower walls on left "excludeRecess": true // But skip stepped shelf walls }, "rightInside": { "includePeaks": false, // Skip towers on right "excludeRecess": false // Include shelf walls } } } }

This configuration:

Left zone: Includes peak walls, excludes recess walls
Right zone: Excludes peak walls, includes recess walls
Both zones: Include fillet faces

Zone Management (New in v1.5)

Zones allow grouping blades together to apply common properties. Bridge blades connect zones using neutral settings.

🆕 New in V1.5

Zone-based blade management with automatic bridge detection.

→ See full Zone Management documentation

Zone Configuration Schema

"zones": { "enabled": true, "neutral": { "retention": { "type": "friction-slot", "reliefHoles": { "enabled": false } }, "color": "#808080", "transparency": 0 }, "autoDetectBridges": true, "bridgeBlades": [], "definitions": [ { "id": "primary-support", "description": "Main load-bearing blades", "blades": [1, 2, 3, 4, 5, 6], "visual": { "color": "#4080C0", "transparency": 0, "layer": "BLADES_PRIMARY" }, "retention": { "type": "keyhole", "keyhole": { "enabled": true, "position": "bottom" }, "reliefHoles": { "enabled": true, "count": 2 } }, "edgeFeatures": { "grippers": { "enabled": true } } }, { "id": "inspection-window", "blades": [10, 11, 12], "visual": { "color": "#40C040", "transparency": 70 }, "retention": { "type": "none" } } ] }

Zone Properties

Property	Type	Description
`id`	string	Unique zone identifier
`blades`	array	Blade IDs or names belonging to this zone
`visual.color`	string	Hex color for zone blades
`visual.transparency`	integer	0-100% transparency
`retention`	object	Retention settings (see Blade Retention)
`edgeFeatures`	object	Gripper/plunger settings

Bridge Blade Detection

When autoDetectBridges: true, the system automatically identifies blades that intersect multiple zones:

Bridge blades receive neutral settings
Avoids conflict between different zone retention types
Manual override via bridgeBlades array

Neutral Settings

Applied to all bridge blades connecting multiple zones:

Property	Recommended Value	Reason
retention.type	"friction-slot"	Universal compatibility
reliefHoles.enabled	false	Maximum strength
color	"#808080" (gray)	Visual distinction

Blade Retention Schema (New in v1.5)

Configuration for blade-to-blade interlocking mechanisms. Can be specified at fixture level, zone level, or for individual blades.

Retention Configuration

"retention": { "type": "keyhole", // "keyhole" | "friction-slot" | "weld-only" | "none" "slot": { "width": "auto", // "auto" = blade thickness + 0.1mm "length": 25, // mm "terminationRadius": 2 // mm stress relief radius }, "keyhole": { "enabled": true, "entryDiameter": "auto", // "auto" = slot width * 2 "position": "bottom" // "top" | "bottom" }, "reliefHoles": { "enabled": true, "count": 2, // 0, 1, or 2 "diameter": 4, // mm "offsetFromSlot": 8, // mm from slot centerline "position": "top" // "top" | "bottom" relative to slot }, "alignmentHole": { "enabled": false, "type": "square", // "square" | "round" "size": 5 // mm }, "tab": { "width": "auto", "height": 20, // mm "headDiameter": "auto", "chamfer": 0.5 // mm } }

Retention Types

Type	Description	Serviceability
`keyhole`	Slot with enlarged entry for quick-lock assembly	Tool-free removal
`friction-slot`	Simple slot with friction fit	Pry/force removal
`weld-only`	No mechanical interlock, welded joints	Destructive only
`none`	No retention features	N/A

→ See Blade Retention for detailed documentation

Part Retention Schema (v1.5 - Updated)

Configuration for plungers, grippers, and other part retention features.

🆕 New in V1.5: Locator Plate Plunger System

Robust plunger mounting using top/bottom locator plates instead of threading into blade.

→ See full Part Retention documentation

Plunger Mounting Assembly Schema

"partRetention": { "plungers": { "enabled": true, "mountingType": "locatorPlate", // "locatorPlate" | "clipSystem" | "tSlot" | "directThread" "locatorPlate": { "threadSize": "M6", // M5, M6, M8 "pocketWidth": 16, // mm "pocketLength": 16, // mm "recessDepth": 2, // mm - top plate recess "topPlateThickness": 2, // mm "bottomPlateThickness": 2, // mm "clearance": 0.5 // mm - assembly clearance }, "tSlot": { "threadSize": "M6", "nutWidth": 10, // mm "tStemWidth": 10.5, // mm "tPocketWidth": 15, // mm "clipHoleOffset": 2 // mm from nut edge }, "clipSystem": { "threadSize": "M6", // M5, M6, M8 "clipWidth": 14, // mm - overall clip width "clipLegWidth": 3, // mm - width of each leg "clipThickness": 2, // mm - material thickness "slotWidth": 3.5, // mm - blade slot width "slotLength": 10, // mm - blade slot length "locatorDiameter": 12 // mm - bottom locator OD }, "placements": [ { "edge": { "semantic": "left" }, "position": { "percent": 25 }, "mountingType": "locatorPlate" // Override per-placement }, { "edge": { "edgeId": 3 }, "position": { "distanceMm": 100 }, "mountingType": "tSlot" // Thin blade area } ], "autoPlacement": { "enabled": false, "minSpacing": 100, // mm between plungers "preferredEdges": ["left", "right"], "avoidZones": [] // Edge regions to skip } }, "grippers": { "enabled": true, "interval": 50, // mm spacing "radius": 2, // mm protrusion radius "height": 1, // mm into pocket "zones": ["bottom", "sides"] // Placement zones } }

Mounting Type Comparison

Type	Min Blade Thickness	Best For
`locatorPlate`	12mm (M6)	Thick blades, heavy loads, serviceability
`tSlot`	3mm	Thin blades, sheet metal
`directThread`	8mm	Simple cases, permanent installation

Locator Plate Components

Component	Description	Generated Output
Top Plate	Green - sits in recess, prevents upward movement	`plunger_top_plate_M6.dxf`
Bottom Plate	Orange - stabilizes nut, slightly different shape	`plunger_bottom_plate_M6.dxf`
Blade Pocket	Rectangular pocket with top recess	Integrated in blade DXF

Edge Reference Types

Type	Example
Semantic	`{"semantic": "left"}`
Numeric ID	`{"edgeId": 3}`
Coordinate	`{"nearPoint": {"x": 150, "y": 200}}`

3-Tier Architecture

Tier	Description	Pros	Cons
Tier 1: Full Local	Air-gapped, all processing local	Data isolation, works offline	No AI, manual updates
Tier 2: Thin Client	Local CAD, web UI, optional cloud AI	AI assistance, easy updates	Requires network
Tier 3: Web SaaS	Browser-based, full cloud	No install, full AI context	Geometry upload required

Implementation Status

✓ JSON Schema definition (v1.1)
✓ PEPS JSON parser (6/6 tests)
✓ Mixed units support (9/9 tests)
○ React + RJSF web UI
○ Electron desktop wrapper
○ i18n localization files
○ Web API endpoint

📦 Deliverables

blade_params.schema.json - master schema definition

fxReadJsonParams.ovm - PEPS JSON parser

i18n/*.json - translation files (planned)

web-ui/ - React + RJSF application (planned)