mirror of
https://github.com/storytold/cadcraft.git
synced 2026-10-14 14:26:45 -04:00
cyfung1031
bcd6322ee9
* plot: add bounded model-space paper placement * plot: expose center and paper offset parameters * ui: add model-space Plot offset controls
114 lines
5.0 KiB
Markdown
114 lines
5.0 KiB
Markdown
# 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:
|
||
|
||
```json
|
||
{
|
||
"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.
|