cadcraft/docs/plotters.md

Plotters

A plotter (output device) decides what a plot writes and on which paper sizes. Page setups and plots pick a device and one of its papers. Each paper carries margins, which bound its printable area. Layouts show the printable area as a dashed outline on the sheet.

Devices

The built-in devices come first:

Device	Output
CADCraft PDF	vector PDF
CADCraft PNG	raster PNG on white paper at the device resolution (300 dpi)
CADCraft SVG	vector SVG

They offer the standard sizes:

• ISO 216 A0–A6 and B0–B5
• ANSI A–E and Legal
• ARCH A–E and E1

ISO sheets have 5 mm margins. Inch sheets have quarter-inch (6.35 mm) margins. A page setup with the device None plots to PDF on the page setup's paper, as before.

User devices are files in our own format, kept in the plotters folder of the CADCraft settings directory:

System	Folder
Linux and FreeBSD	$XDG_CONFIG_HOME/cadcraft/plotters or ~/.config/cadcraft/plotters
macOS	~/Library/Application Support/CADCraft/plotters
Windows	%APPDATA%\CADCraft\plotters

CADCRAFT_CONFIG_DIR replaces the settings directory. On the web, devices last for the session unless the host provides storage (cmd::plotters::set_plotter_store). Binary .pc3 files are not read; we haven't found a public specification of that format.

Files

<name>.plotter.json, UTF-8 JSON with a format marker:

{
  "cadcraftPlotter": 1,
  "name": "Office A3",
  "description": "Raster proofs",
  "output": "png",
  "resolution": 150,
  "orientation": "landscape",
  "defaultPaper": "A3 borderless",
  "papers": [
    { "name": "A3 borderless", "width": 297, "height": 420, "margins": [0, 0, 0, 0] },
    { "name": "ISO A4 (210.00 x 297.00 MM)", "width": 210, "height": 297, "margins": [5, 5, 5, 5] }
  ]
}

• output is pdf, png or svg.
• resolution is in dots per inch (50–2400) and applies to PNG.
• orientation (portrait or landscape) is used when a page setup switches to the device.
• Paper sizes are in millimetres on the portrait sheet. margins are left, bottom, right and top, in mm.

Reading fixes hostile values:

• Sizes are kept within 1–5080 mm, and width and height are swapped to portrait.
• Margins are kept within 0–1000 mm. Margins that leave no printable area are dropped.
• Paper names are unique, and a device keeps at most 512 papers.
• A missing or unknown defaultPaper becomes the first paper.
• Files over 1 MB are refused.

In the file name, characters other than letters, digits, spaces and -_()+, become _.

Commands

• plottermanager {action, …} (also File ▸ Plotter Manager...) manages the devices:

  • list (the default) shows the built-in devices first.
  • get {name} returns a device.
  • new {name, from?, output?, …} copies from, or the built-in device for output with the standard papers.
  • set {name, description?, output?, resolution?, orientation?, defaultPaper?, paper?: {name, width, height, margins?}, removePaper?} edits a device. paper adds a paper or replaces the one of that name.
  • delete {name} removes a device.
  • load {text, name?} stores a device file's contents.
  • save {name, path?} writes the file to path, or returns it as text.

  Built-in devices can't be edited or deleted.

• Typed PLOTTERMANAGER or -PLOTTERMANAGER prompts for an option:

  • ? lists the devices.
  • New asks for a name and an output (Pdf, PNg, Svg).
  • Delete asks for a device.
  • Paper asks for a device, a paper name and width,height in mm, and adds that paper.

• pagesetup {layout, device, paper?} sets the layout's device. paper names one of the device's papers, or a standard size by its short name (A3, Letter). The paper's margins become the layout's printable area. Without paper, a device change keeps the current paper if the device has it, else takes the device's default paper. A device change also takes the device's orientation unless landscape is given. device: "None" clears it.

• plot {device?, paper?, …} plots with device, or with the layout's page setup device.

  • The device sets the output and resolution.
  • paper (one of the device's papers) sets the size and margins for this plot.
  • A model-space plot without paper uses the device's default paper and orientation.
  • For Model plots, center defaults to true, preserving the existing centered output. Set center: false with offset: [x, y] to place the plotted bounds' lower-left corner from the printable area's lower-left origin; offsets are millimetres, default to [0, 0], and are bounded to ±100,000 mm. PDF and PNG support these controls. SVG plots keep their extents view; an active offset is rejected rather than ignored. Layout plots do not use model offsets.
  • exportpdf takes the same options and always writes PDF.

Model-space PDF plots don't apply the paper's margins yet. They fit the drawing inside the default margins. PNG plots apply them. SVG plots show a layout's whole sheet, or the model-space extents.

Plot transparency

Objects plot with their transparency (their own, their layer's when ByLayer, the block reference's when ByBlock) only when asked, as in AutoCAD:

• pagesetup {layout, plotTransparency: bool} stores the layout's "Plot transparency" (off by default). The Page Setup Manager and the Plot dialog have the checkbox.
• plot {plotTransparency?: bool} (and exportpdf, preview) overrides it for one plot. Model-space plots have it off unless asked.
• PLOTTRANSPARENCYOVERRIDE decides first: 0 never plots transparency, 1 (default) uses the setting above, 2 always plots it.

PDF plots write it as alpha (/ExtGState with /ca and /CA), PNG plots blend it, SVG plots use opacity. A plot without transparency is written exactly as before. The DXF plot layout flags have no bit for the option, so it isn't saved in DXF or DWG files.

On screen, TRANSPARENCYDISPLAY (on by default; the status bar's Transparency button) shows transparency; PNG and SVG exports of a drawing always draw it.