CAD Overview

Overview#

This set of functions allows you to build and save CloudCAD files using SkyCiv's CAD software.

Top-Level Structure#

{
  "settings": { ... },        // Global canvas/display settings
  "s3d": { ... },              // Structural 3D export settings (optional)
  "attributeStyles": [ ... ], // Dimension/text/leader/axis sizing styles
  "blockReferences": [ ... ], // Block DEFINITIONS (reusable groups, e.g. title blocks)
  "pdfExport": { ... },        // Printed page setup (paper size, page frame) - optional
  "canvases": [ ... ]          // Array of canvas objects (drawings)
}

attributeStyles, blockReferences, and pdfExport are top-level fields, siblings of canvases - not nested inside a canvas object.

`settings`#

Controls display, snapping, colors, dimensions, and units. All fields are optional — defaults are applied for any omitted values.

Key	Type	Description
`canvasLengthUnits`	`string`	Length unit: `"mm"`, `"cm"`, `"m"`, `"ft"`, `"in"`
`gridSize`	`string`	Grid spacing value
`snapToGrid`	`bool`	Snap cursor to grid
`snapToPoint`	`bool`	Snap to existing points
`snapToLineEnds`	`bool`	Snap to line endpoints
`snapToLineMid`	`bool`	Snap to line midpoints
`snapToAlign`	`bool`	Snap to alignment guides
`snapToAxis`	`bool`	Snap to axes
`showGrid`	`bool`	Show background grid
`showAxis`	`bool`	Show axis lines
`showVertices`	`bool`	Show vertex markers
`showCreatedDimensions`	`bool`	Show user-created dimensions
`showSelectionDimensions`	`bool`	Show dimensions on selection
`canvasBackgroundColor`	`string`	Hex color for canvas background
`lineColor`	`string`	Default line color
`pointColor`	`string`	Default point color
`dimensionsColor`	`string`	Dimension label color
`selectionColor`	`string`	Selected item color
`highlightColor`	`string`	Hover/highlight color
`dimensionTextSize`	`string`	Font size for dimension labels
`globalDimsScale`	`string`	Global scale for dimension display
`globalTextScale`	`string`	Global scale for text display
`arcSegments`	`string`	Segment count for arc rendering
`circleSegments`	`string`	Segment count for circle rendering

Full settings object can include many more display/snap/color options. Omit any you don't need — sensible defaults are used.

`s3d` (Structural 3D Settings)#

Optional. Used when the CAD drawing maps to a structural model.

{
  "s3d": {
    "settings": {
      "units": "mm",
      "tolerance": 0.0001,
      "connect_floors_by_columns": false,
      "connect_floors_section_id": null,
      "remove_duplicate_members": true,
      "supports_only_base": true,
      "ignore_unassigned_sections": false
    },
    "sections": {},
    "elevations": [
      { "canvas_id": 0, "elevation": 0 }
    ]
  }
}

`canvases`#

Array of canvas (drawing) objects. Each canvas contains all the geometry, annotations, and metadata for one drawing sheet.

{
  "version": "2.0.0",
  "schema": "canvas-json-v2-optimized",
  "name": "Canvas 1",
  "drawing_type": "Plan",       // "Plan", "Elevation", etc.
  "is_base": true,
  "points": [],
  "lines": [],
  "polylines": [],
  "dimensions": [],
  "angleDimensions": [],
  "radiusDimensions": [],
  "leaderTexts": [],
  "multiLeaderTexts": [],
  "texts": [],
  "tables": [],
  "axes": [],
  "constructionLines": [],
  "revisionClouds": [],
  "hatches": [],
  "images": [],
  "block_instances": [],
  "layers": [],
  "s3d": {}
}

Block definitions are not a canvas field (see blockReferences at the top level, under "Blocks") - a canvas only places a block via block_instances.

Canvas Element Types#

Points#

{
  "x": 100,
  "y": 200,
  "id": "uuid"          // optional – auto-generated if omitted
}

Lines#

A straight segment between two points.

{
  "p1": { "x": 0, "y": 0 },
  "p2": { "x": 100, "y": 200 },
  "id": "uuid",
  "groupId": "uuid"     // optional – links lines into a group/polygon
}

Tip: To create a closed polygon, create multiple lines that share endpoints and assign the same groupId.

Polylines — Circle#

{
  "type": "circle",
  "center": { "x": 0, "y": 0 },
  "radius": 500,
  "radiusPoint": { "x": 500, "y": 0 },   // a point on the circumference
  "segments": 100,
  "id": "uuid"
}

Polylines — Arc#

Defined by three points: start, end, and a mid/control point on the arc.

{
  "type": "arc",
  "points": [
    { "x": 0, "y": 0 },       // start
    { "x": 100, "y": 100 },   // end
    { "x": 50, "y": 80 }      // point on arc (control)
  ],
  "segments": 100,
  "id": "uuid"
}

Dimensions (Linear)#

{
  "p1": { "x": 0, "y": 0 },           // first measured point
  "p2": { "x": 1000, "y": 0 },        // second measured point
  "offsetPoint": { "x": 500, "y": 200 }, // position of the dimension line
  "id": "uuid",
  "projectionType": "vertical"         // optional – "vertical", "horizontal", or omit for auto
}

Leader Texts#

An arrow from a point to a text label.

{
  "startPoint": { "x": 0, "y": 0 },   // arrow tip
  "endPoint": { "x": 200, "y": 100 }, // text position
  "text": "Label",
  "id": "uuid"
}

Multi-Leader Texts#

A text annotation with multiple arrow leaders.

{
  "anchorPoint": { "x": 0, "y": 0 },
  "arrowPoints": [
    { "x": -100, "y": -50 },
    { "x": 100, "y": 50 }
  ],
  "text": "Note",
  "id": "uuid"
}

Texts#

{
  "position": { "x": 100, "y": 200 },
  "text": "Hello I am Text",
  "size": 14,
  "color": "#aaaaaa",
  "backgroundColor": "#336e7a",
  "backgroundColorOpacity": 0,        // 0 = transparent, 1 = opaque
  "alignment": "center",              // "left", "center", "right"
  "textPosition": "top-center",
  "bold": false,
  "italic": false,
  "id": "uuid"
}

Tables#

{
  "id": "uuid",
  "position": { "x": 0, "y": 0 },
  "rows": [
    ["Header 1", "Header 2", "Header 3"],
    ["Cell 1",   "Cell 2",   "Cell 3"]
  ],
  "opts": {
    "first_row_header": true,
    "alignment": "center",
    "text_color": "#ffffff",
    "bg_color": "#000000",
    "header_background_color": "#4a5568",
    "font_size": 15,
    "width": 2000,
    "height": 800,
    "row_height": 200
  }
}

Axes (Gridlines)#

A labeled axis/gridline between two points.

{
  "p1": { "x": 0, "y": -5000 },
  "p2": { "x": 0, "y": 5000 },
  "label": "A",
  "id": "uuid"
}

Construction Lines#

Infinite reference lines defined by a point and angle (in degrees).

{
  "point": { "x": 0, "y": 0 },
  "angle": 90,             // degrees
  "id": "uuid",
  "isHidden": false
}

Revision Clouds — Rectangle#

Rectangular revision cloud defined by bounding box.

{
  "id": "uuid",
  "minX": 0,
  "minY": 0,
  "maxX": 1000,
  "maxY": 500,
  "arcRadius": 500,        // size of cloud scallops
  "segments": 10,
  "arcs": [ ... ]          // auto-generated arc segments — typically computed by CAD
}

Revision Clouds — Circular#

{
  "id": "uuid",
  "minX": 0,
  "minY": 0,
  "maxX": 1000,
  "maxY": 1000,
  "arcRadius": 500,
  "segments": 10,
  "center": { "x": 500, "y": 500 },
  "radius": 500,
  "arcs": [ ... ]
}

The arcs array is typically auto-generated. When creating revision clouds programmatically, provide the bounding box (minX, minY, maxX, maxY) and arcRadius — the renderer will compute the scallop arcs.

Hatches#

A filled region defined by one or more closed loops.

{
  "id": "uuid",
  "type": "hatch",
  "color": "#5a5995",
  "opacity": 0.5,
  "loops": [
    {
      "segments": [
        {
          "type": "line",
          "start": { "x": 0, "y": 0 },
          "end": { "x": 100, "y": 0 }
        },
        {
          "type": "line",
          "start": { "x": 100, "y": 0 },
          "end": { "x": 100, "y": 100 }
        },
        {
          "type": "line",
          "start": { "x": 100, "y": 100 },
          "end": { "x": 0, "y": 0 }
        }
      ]
    }
  ]
}

Each loop is a closed boundary. Segments within a loop can be "line" or "arc" types.

Blocks#

Blocks allow you to define reusable groups of drawing elements - used for anything placed more than once, including a title block (see "Pages & Title Blocks" below).

Block References (Definitions)#

Top-level field, camelCase: blockReferences (a sibling of canvases, not nested inside one). A canvas only places a block via block_instances - it never defines one itself.

{
  "id": "uuid",
  "name": "Block Example",
  "basePoint": { "x": 0, "y": 0 },
  "items": [
    { "type": "point", "data": { "x": 10, "y": 20 } },
    { "type": "line",  "data": { "p1": { "x": 0, "y": 0 }, "p2": { "x": 100, "y": 100 } } },
    { "type": "arc",   "data": { "type": "arc", "points": [ ... ], "segments": 100 } },
    { "type": "dimension", "data": { "p1": { ... }, "p2": { ... }, "offsetPoint": { ... } } },
    { "type": "multiLeaderText", "data": { "anchorPoint": { ... }, "arrowPoints": [ ... ], "text": "Note" } },
    { "type": "hatch", "data": { "color": "#5a5995", "opacity": 0.5, "loops": [ ... ] } },
    { "type": "text", "data": { "position": { "x": 0, "y": 0 }, "text": "Label", "size": 14, "textPosition": "middle-center" } },
    { "type": "leaderText", "data": { "startPoint": { ... }, "endPoint": { ... }, "text": "Note" } }
  ]
}

Supported item types inside a block: point, line, arc, dimension, multiLeaderText, hatch, text, leaderText.

basePoint is the local-space point that maps onto a placed instance's position - not necessarily the block's bounding-box corner.

Block Instances#

Place a block definition on a canvas with position, rotation, and scale.

{
  "id": "uuid",
  "blockId": "block-definition-uuid",   // references a top-level blockReferences[].id
  "position": { "x": 0, "y": 0 },
  "rotation": 0,                         // degrees
  "scale": { "x": 1, "y": 1 }
}

Placement transform (rotation = 0): a point local in the block definition maps to canvas space as world = position + scale * (local - basePoint) (component-wise on x/y). With rotation != 0, apply a 2D rotation about basePoint before scaling/translating.

Layers#

Assign canvas items to layers for organization, color, and visibility control.

{
  "id": "uuid",
  "name": "Layer 1",
  "color": "#9ef5af",
  "visible": true,
  "locked": false,
  "lineThickness": 2,
  "lineType": "solid",        // "solid", "dashed", etc.
  "patternScale": 1,
  "items": [
    { "type": "circle", "id": "polyline-uuid" },
    { "type": "line",   "id": "line-uuid" }
  ]
}

Items reference elements by their type and id. When displayColorByLayers is enabled in settings, items inherit the layer color.

`pdfExport` (Pages)#

Top-level field, sibling of canvases: pdfExport.pdfPages[] defines the physical printed page(s) - a rectangle in canvas units overlaid on the canvas, plus paper metadata.

{
  "pdfPages": [
    {
      "frame": { "start": { "x": 67000, "y": -105000 }, "end": { "x": 126400, "y": -63000 } },
      "orientation": "landscape",   // "landscape" or "portrait"
      "format": "A2",               // paper size label, e.g. "A0"-"A4"
      "printPage": true,
      "offset": { "top": 0, "right": 0, "bottom": 0, "left": 0 },  // print margins
      "scale": 100,                 // print scale, percent
      "canvasIndex": 0              // which canvases[] entry this page belongs to
    }
  ]
}

frame.start/frame.end is the page - format/orientation are descriptive labels that must stay consistent with it. Compute the frame from the paper size in mm x 100 (e.g. A2 landscape = 594mm x 420mm -> 59400 x 42000 units, as above). A sibling savedSettings key may also appear - that's CAD editor UI state, safe to omit when creating a drawing programmatically.

Pages & Title Blocks#

To produce a finished, print-ready sheet (a page border + title block, not bare geometry), reuse the ready-made template at assets/Title-Block-Example.json - a real A2-landscape page + title block exported from the platform - rather than building one from scratch. Copy its pdfExport, its blockReferences[0] (the title block definition), and the canvas's block_instances[0] (which places it at position: {x:96700, y:-86048}, scale: {x:2, y:2}) into a new cad_data, then add your own drawing content scaled/centered to fit the page without overlapping the title block.

This template is only cleanly reusable at A2 landscape, or other ISO 'A' landscape sizes via uniform rescaling (they share the same aspect ratio) - portrait or non-ISO formats need their own template, since the title block's geometry is fixed artwork, not a parametric layout. See cloudcad-api/SKILLS.md's "Pages & Title Blocks" section for the full reuse pattern and its known limitations.

Minimal Example#

A simple drawing with one line and one circle:

{
  "settings": {
    "canvasLengthUnits": "mm"
  },
  "canvases": [
    {
      "version": "2.0.0",
      "schema": "canvas-json-v2-optimized",
      "name": "My Drawing",
      "drawing_type": "Plan",
      "is_base": true,
      "points": [],
      "lines": [
        {
          "p1": { "x": 0, "y": 0 },
          "p2": { "x": 5000, "y": 0 }
        }
      ],
      "polylines": [
        {
          "type": "circle",
          "center": { "x": 2500, "y": 2500 },
          "radius": 1000,
          "segments": 100
        }
      ],
      "dimensions": [],
      "angleDimensions": [],
      "radiusDimensions": [],
      "leaderTexts": [],
      "multiLeaderTexts": [],
      "texts": [],
      "tables": [],
      "axes": [],
      "constructionLines": [],
      "revisionClouds": [],
      "hatches": [],
      "images": [],
      "block_instances": [],
      "layers": []
    }
  ]
}

Sending Data to CAD from other pages#

From anywhere on the SkyCiv platform, you can open CAD with pre-built drawing data using:

SKYCIV_UTILS.exportToCad(cad_data);

Where cad_data is a JSON object following the schema described below.