This document defines the strictly required structure for .xcs (xTool Creative Space) files to ensure full compatibility with the xTool F2 hardware system.
Every XCS project must follow a specific top-level node hierarchy to be recognized by the F2 system.
canvasId and device metadata.
extId: "GS006" Mandatory (Identifies xTool F2)extName: "F2" Mandatoryversion: "1.5.8" (Stable baseline)canvas[]): Contains visual shape definitions and layer manifests.device): Contains hardware-specific processing parameters.The xTool F2 hardware switches between two distinct laser sources. The XCS format handles this via specific string keys and internal mappings.
| Source | Wavelength | Spot Size | XCS Key (processingLightSource) |
|---|---|---|---|
| IR Laser | 1064nm (Fiber) | 0.03mm (Circular) | "red" or "ir" |
| Blue Laser | 455nm (Diode) | 0.08 x 0.06mm (Rect) | "blue" |
1-100 (Percentage).1-500 mm/s.dotDuration (µs) in some modes.COLOR_FILL_ENGRAVE, the density field uses a 1:1 mapping (e.g., 1000 in JSON = 1000 LPCM in UI).10 / LPCM.BITMAP_ENGRAVING.DPI ≈ LPCM * 2.54.XCS links geometry (on the canvas) to processing settings (in the device tree) using a strict three-point synchronization logic.
Individual shapes are linked via their unique GUIDs:
canvas[0].displays[i].iddevice.data.value[0][1].displays.value[j][0]UI Integrity Rule: For the xTool F2 user interface to function correctly (showing power/speed sliders), every shape in the device tree MUST include all four operation nodes, even if they are empty or inactive.
| Key | Type | Description |
|---|---|---|
COLOR_FILL_ENGRAVE |
Fill | Standard area engrave. Uses 1:1 LPCM mapping. Includes scanAngle and bitmapScanMode. |
VECTOR_ENGRAVING |
Score | Outlines / line-following. Used for "Score" in UI. |
VECTOR_CUTTING |
Cut | High-power cutting operations. |
BITMAP_ENGRAVING |
Image | Specific to BITMAP types. Uses dpi and dotDuration. |
RELIEF |
3D | Advanced depth mode. Includes sliceNumber (usually 256) and zAxisMove. |
INTAGLIO |
3D | Relief and deep engraving operations. |
Text objects are the most complex node in XCS. For the F2 system (which often processes offline), the file must contain baked glyph paths.
type: "TEXT"charJSONs: Mandatory An array of PATH objects containing the SVG dPath data for every character.fontData: Mandatory Full metrics and glyph dictionary.style.fontSize: Points (pt).
height (mm) ≈ fontSize (pt) * 0.2757
XCS uses a Left-Baseline anchor for text. The exporter must manually calculate positions for alignment.
| Scenario | Anchor (x, y) | Growth Direction |
|---|---|---|
| Horizontal (0°) | Left-edge Baseline | Grows Right (+X) |
| Vertical (-90°) | Top-edge Baseline | Grows Down (+Y) |
| Centering | Manual Offset Required | x = targetX - (width/2) |
Sequencing is controlled by layer metadata combined with global path planning flags.
Located in canvas[0].layerData[HEX_COLOR].order.
Note: Processing typically occurs from Highest Order to Lowest Order.
Path: device.data.value[canvasId].data.LASER_PLANE
pathPlanning: "custom": Respects layer order.isProcessByLayer: true: Completes each layer before starting the next.canvasId MUST match the ID of the first canvas and exist as a key in the device map.display.id on the canvas MUST have a corresponding entry in the device parameter tree.{"dataType": "Map", "value": [...]}.The following aspects of the XCS format have been observed but their exact behavioral impact or implementation details remain unverified:
isWhiteModel: Frequently found on BITMAP and non-fill objects. Suspected to relate to how the hardware treats "empty" space or background transparency, but its toggle logic in the UI is inconsistent.bitmapScanMode: Options include "oneWay", "twoWay", and "zMode". While zMode is clearly for relief, the performance difference between oneWay and twoWay in Galvo-based systems (like F2) vs Gantry systems is not fully benchmarked.planType: Appears to be a redundant flag for the laser source ("red"/"blue") but may also trigger specific trajectory planning algorithms in the Galvo controller.A-arc Commands: Some baked glyph paths contain absolute Arcs. XCS handles these, but the exact tolerance for "broken" arcs or non-standard SVG arc flags is unknown.mm, some internal metadata (like unitsPerEm in fontData) remains fixed at 2000 regardless of actual font metrics.