Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
4e35ec2
Nested attachments in the preview and the plot
sc-frederick Nov 18, 2026
58ceac9
Polyline arcs and widths: bulges, rounded corners, revision clouds, d…
sc-frederick Nov 19, 2026
462fb94
readDXF leaves out what a file marks invisible, so a dynamic block re…
sc-frederick Nov 19, 2026
ef5b4d3
Paragraph text: one note that wraps to a width, with underline, bold …
sc-frederick Nov 19, 2026
b77731e
Dimension styles: stacked fractions, words below the line, text in a …
sc-frederick Nov 20, 2026
29098f6
Paragraph text: numbered and lettered lists, tab stops and a paragrap…
sc-frederick Nov 20, 2026
0c2dac9
Raster images: write, read, lint and plot them, clip and frame included
sc-frederick Nov 20, 2026
8c6ced2
Radius, diameter and jogged radius dimensions
sc-frederick Nov 20, 2026
02ce9b3
Paragraph text in columns that flow from one to the next
sc-frederick Nov 20, 2026
58d6fb7
Leaders whole: every attachment, notes that wrap, frames and masks, t…
sc-frederick Nov 20, 2026
cc9b806
Angular dimensions
sc-frederick Nov 20, 2026
f18c2bf
Solid fills, wipeouts and masks: written, read and plotted as CAD pro…
sc-frederick Nov 20, 2026
f4aca1f
Paragraph text lays out the codes that change the characters after them
sc-frederick Nov 20, 2026
b627992
Arc length dimensions
sc-frederick Nov 20, 2026
42f2ab1
Hatch patterns from a firm's pattern file: written, read and plotted …
sc-frederick Nov 20, 2026
08f30a1
Attributes of paragraph text
sc-frederick Nov 20, 2026
b97cd87
Gradient hatches: written, read and plotted as CAD programs draw them
sc-frederick Nov 20, 2026
03188e4
An attribute's text starts where CAD programs start it, and the check…
sc-frederick Nov 21, 2026
e61481f
Ellipses and splines: written, read and plotted as CAD programs draw …
sc-frederick Nov 21, 2026
f3ad36b
Ordinate dimensions
sc-frederick Nov 21, 2026
36c19fd
Linetypes with text: a pipe's letters along it, written, read and plo…
sc-frederick Nov 21, 2026
67521bd
Tables: one table entity, written, read and plotted as CAD programs d…
sc-frederick Nov 21, 2026
298d084
Linetypes with shapes: a fence's circles along it, drawn from the fir…
sc-frederick Nov 21, 2026
4a98d81
An entity's own color, by index or as a true color: written, read and…
sc-frederick Nov 21, 2026
b1beba1
The DWG reader reads the 2004, 2010 and 2013 formats
sc-frederick Nov 21, 2026
0f7103c
Read a PDF page's size: pdfPageSize
sc-frederick Nov 21, 2026
952032c
An entity's own transparency: written, read and plotted as CAD progra…
sc-frederick Nov 22, 2026
600cef6
The DWG reader reads the 2007 format, and tables before 2010
sc-frederick Nov 22, 2026
7338b7c
PDF underlays: a page of a PDF under a sheet, written, read and plott…
sc-frederick Nov 22, 2026
2e2309c
The shape sweep runs as seven test files after the other tests
sc-frederick Nov 22, 2026
ab49239
Points: plotted as CAD programs draw them, at the drawing's point style
sc-frederick Nov 22, 2026
4af6905
3D solids, regions and bodies: read by their edges, drawn in plan
sc-frederick Nov 22, 2026
30523f9
Agent notes: the rules of each part of the library in a page of its own
sc-frederick Nov 22, 2026
e44cdf7
Remove duplicate shape-sweep cases and share the drawability checks
sc-frederick Nov 22, 2026
8b16d83
Speed up drawing previews, exports and DXF reads
sc-frederick Nov 22, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
368 changes: 27 additions & 341 deletions AGENTS.md

Large diffs are not rendered by default.

421 changes: 421 additions & 0 deletions CHANGELOG.md

Large diffs are not rendered by default.

180 changes: 143 additions & 37 deletions GUIDE.md

Large diffs are not rendered by default.

152 changes: 144 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,10 @@ Entities go on layer `0` unless they are drawn inside a `layer()` callback.
Linetypes and lineweights are set on a layer, and an entity draws ByLayer unless
it is given its own. `DASHED`, `HIDDEN`, `CENTER`, `PHANTOM`, `DASHDOT` and `DOT`
are the leading CAD app's own definitions; `d.linetype({ name, pattern })` defines another,
with dashes as positive lengths, gaps as negative ones and dots as 0. A
with dashes as positive lengths, gaps as negative ones and dots as 0. Its `marks` draw texts
along the line, such as a water main's letters, and shapes of a firm's shape file, such as a
fence's circles, which `parseShapes` reads and the plot takes as `shapes`. `parseLinetypes` reads
a firm's linetype file. A polyline's `linetypeGeneration` runs the pattern on past its vertices. A
lineweight is in millimetres.

A text is in the style `Standard` unless it names another. `d.textStyle({ name,
Expand Down Expand Up @@ -145,6 +148,115 @@ The path leads from the folder of the drawing's file. `toSVG` draws the referenc
when it is given one, as `toSVG(drawing, { xrefs: { BASE: base } })`. [Xrefs](docs/xrefs.md)
has the rest.

A polyline's sides can be arcs and can be drawn wide, and the builder makes a few shapes of
them, each one polyline in the file:

```ts
d.polyline(hook, false, { radius: 1.5, width: 0.625 }); // a bar's hook with its bend
d.cloud(outline, { arc: 3.75 }); // a revision cloud that bulges out of its outline
d.donut([10, 10], 0.5); // a filled dot
```

`bulges` makes any side an arc, and `widths` gives each side a width at each end.
[Polylines](docs/polylines.md) has the rest.

An ellipse is drawn by its center, the end of its major axis and the ratio of its axes, and a
spline through fit points, as a top of bank or a tree line is drawn through located shots, or by
its control points:

```ts
d.ellipse([10, 5], [4, 0], 0.5);
d.spline(bank); // the cubic CAD programs fit through the points
d.controlSpline(controlPoints, { degree: 3 });
```

[Ellipses and splines](docs/curves.md) has arcs of an ellipse, tangents, closed splines, knots
and weights.

A point marks a survey shot or a benchmark. Every point plots as the figure the drawing's point
style gives, at a size in drawing units or as a share of the view:

```ts
const d = createDrawing({ pointStyle: { figure: "cross", circle: true, size: 0.25 } });
d.point([10, 5]);
```

[Points](docs/points.md) has the figures and their sizes.

A paragraph is one text whose lines wrap at a width, which a CAD user edits as one. A line feed
starts a new paragraph, and small helpers write the codes for a numbered list, an underline,
bold, a stacked fraction and a superscript:

```ts
import { list, stack, underline } from "tsdraft";

d.paragraph(
`GENERAL NOTES\n${list([`${underline("VERIFY")} ALL DIMENSIONS.`, `GAP 3${stack("1", "2")}"`])}`,
{
at: [1, 20], // the upper left corner of its box
width: 4,
height: 0.1,
},
);
```

`measureParagraph` gives its lines and its box. [Paragraphs](docs/paragraphs.md) has the codes
it takes and what it refuses.

An image is a PNG or a JPEG drawn at a size in drawing units, such as an aerial under a plan or
a vicinity map on a sheet. The drawing holds the file's path and its pixels, which `rasterSize`
reads, and the plot draws the file from the bytes it is given:

```ts
import { rasterSize } from "tsdraft";

const pixels = rasterSize(readFileSync("aerial.png"))!;
d.image("aerial.png", [0, 0], {
pixels,
width: 400,
clip: [
[20, 20],
[380, 260],
],
});
toPDF(drawing, { images: { "aerial.png": readFileSync("aerial.png") } });
```

[Images](docs/images.md) has clips, frames and transparency, and what `lint` refuses.

An underlay places a page of a PDF under the sheet, such as an architect's plan, by its path,
its page and the page's size, which `pdfPageSize` reads. The plot draws it from a picture of the
page you give it, since tsdraft draws no PDF. [Underlays](docs/underlays.md) has the rest.

A hatch fills the area inside its loops solid, a loop inside another a hole, draws a pattern
of the firm's pattern file there, or runs from one color to another as a gradient. A wipeout hides what is drawn before it, and a paragraph's mask
hides it behind the text:

```ts
d.hatch([
{
points: [
[0, 0],
[96, 0],
[96, 8],
[0, 8],
],
},
{
points: [
[36, 0],
[72, 0],
[72, 8],
[36, 8],
],
},
]);
d.paragraph("VERIFY IN FIELD", { at: [40, 20], height: 3, mask: true });
```

[Fills, wipeouts and masks](docs/fills.md) has holes and arcs, patterns, gradients, wipeouts' frames, a
dimension style's mask and the draw order.

A dimension measures between two points and writes what it measures. In the file it is a
dimension, which a CAD program measures again when its points move, and a dimension style says how
it is drawn:
Expand All @@ -165,7 +277,9 @@ d.linearDimension([34, 30], [86, 30], [0, 22], { style: "PLAN" }); // 52.0'
```

`alignedDimension` measures along the two points, and a style with `units: "architectural"`
writes feet and inches, as `4'-1 7/16"`. [Dimensions](docs/dimensions.md) has the rest.
writes feet and inches, as `4'-1 7/16"`, with the fraction on the line or stacked. A style puts
the text above the line or in a break of it and moves a text with no room out on a leader, and
a dimension takes words below its line. [Dimensions](docs/dimensions.md) has the rest.

A layout is a sheet of paper that a CAD program shows as a tab and plots as one page. What is drawn
inside `layout` is on the sheet, in inches of paper, and a viewport shows the model on it at a
Expand Down Expand Up @@ -211,16 +325,16 @@ tsdraft is early, and its API still changes. Until 1.0 any release, a patch
included, can break code written for the one before. [CHANGELOG.md](CHANGELOG.md)
starts each breaking change with `Breaking:`.

It draws layers, lines, polylines, rectangles, circles, arcs and single-line text, with
linetypes and lineweights, text styles and justification, blocks with attributes and inserts
It draws layers, lines, polylines with arcs and widths, rectangles, revision clouds, donuts,
circles, arcs, single-line text and paragraph text that wraps to a width, with lists, tab
stops and columns, linetypes and lineweights, an entity's own color by index or as a true color, text styles and justification, blocks with attributes and inserts
of them, references to DWG files as xrefs, linear and aligned dimensions in decimal units or
feet and inches, leaders, layouts with a page setup and viewports, which can freeze their own
feet and inches with stacked fractions, words below the line and text on a leader, leaders, layouts with a page setup and viewports, which can freeze their own
layers or twist the view, and layers that are off, frozen, locked or not plotted. A firm's
[standard](docs/standard.md) sets its layers, pens, text and sheets. It writes DXF, not DWG.

It does not yet have paragraph text, arcs or widths in a polyline, ellipses, splines or
points, hatches, solid fills or masks, images, tables, color or transparency set on one
entity, linetypes with text or shapes, PDF underlays, or the other kinds of dimension.
It does not yet have overlines in paragraph text, ellipses, splines or points, tables, PDF underlays,
or the other kinds of dimension.

`readDXF` reads an ASCII DXF into a model to inspect, which is not a drawing tsdraft can edit
and write again. [Reading drawing files](docs/reading.md) has what it reads.
Expand Down Expand Up @@ -270,6 +384,8 @@ the drawing's version, and `toDXF(drawing, { version })` writes another one.
| Format code | AC1032 | AC1009 |
| Drawing units | Stored in `$INSUNITS`. | Not stored. Set them in CAD with `UNITS`. |
| Polylines | `LWPOLYLINE` | `POLYLINE` with `VERTEX` records |
| Polyline arcs and widths | Yes | No |
| Paragraph text | `MTEXT` | No |
| Text | UTF-8 | ASCII, with `\U+XXXX` escapes for other characters |
| Layer names | Up to 255 characters, except those in [the rules](docs/rules.md#errors) | Up to 31 letters, digits, `$`, `-` and `_` |
| Linetypes, lineweights | Yes | No: only `Continuous`, and no lineweights |
Expand Down Expand Up @@ -317,6 +433,26 @@ lint(drawing, { version: "R12" }); // check a drawing against another version
characters it refuses.
- [Blocks](docs/blocks.md) covers blocks, inserts and attributes: layers in a
block, names, handles and what the preview draws.
- [Polylines](docs/polylines.md) covers arcs by their bulge, rounded corners, revision clouds,
widths and donuts, how a wide polyline plots, and what `lint` refuses of them.
- [Ellipses and splines](docs/curves.md) covers ellipses and their arcs, splines through fit
points and by control points, how they plot and dash, and what `lint` refuses of them.
- [Points](docs/points.md) covers points and the point style, how a figure plots and how big, and
what `lint` refuses of them.
- [Paragraphs](docs/paragraphs.md) covers paragraph text: its width and box, the codes its
value takes, the helpers that write them, how it is laid out, and what `lint` refuses.
- [Images](docs/images.md) covers raster images: the path and the pixels, clips, frames,
transparency, how the plot draws one, and what `lint` refuses.
- [Underlays](docs/underlays.md) covers PDF underlays: the path, the page and its size, scale,
clips, fade, contrast and monochrome, frames, the page's picture the plot draws, and what `lint`
refuses.
- [Fills, wipeouts and masks](docs/fills.md) covers hatches with holes, solid, of a pattern
file's patterns or of a gradient, wipeouts, the masks of paragraphs, leaders and dimensions, the draw order, and
what `lint` refuses.
- [Colors](docs/colors.md) covers an entity's own color by index or as a true color, ByBlock in
a block, how each plots under a plot style table, and the color codes of paragraph text.
- [Transparency](docs/transparency.md) covers an entity's own transparency, ByBlock in a block,
and how it plots when the plot asks for it.
- [Dimensions](docs/dimensions.md) covers dimension styles, linear and aligned
dimensions, how a measurement is written, and what `lint` refuses.
- [Xrefs](docs/xrefs.md) covers references to DWG files: the path, units, a
Expand Down
13 changes: 9 additions & 4 deletions cli/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,11 @@
gained the inserts on layouts while layouts were unreleased.
- The command opens no file an xref names. The worker draws an xref from the drawing file's
named export `xrefs` alone, and `drawing.xrefs` says with `shown` which ones the pictures
have, so an agent knows what it is not seeing.
have, so an agent knows what it is not seeing, and for one shown, the same of its own `xrefs`.
A value given as `{ drawing, xrefs }` draws its attachments where the copy of tsdraft has
`drawnXrefs`. The worker takes from it what the pictures draw, lints each of those drawings
once, leaves out one with an error, which cuts nothing else, and passes the export to `lint`
for why a drawing given is not drawn.
- `outputs.svg` and `outputs.png` are model space, with or without layouts, and
`outputs.layouts` has each sheet. The worker draws a layout only with a copy of tsdraft that
has `viewportView`, since an older one would draw model space for it. `without` leaves a
Expand All @@ -25,8 +29,9 @@
there is no `prlimit`.
- The renderer consults no system font by name. `src/fonts.ts` looks in the machine's font
folders, once for the life of the command, for the file of each TrueType font of `FONTS`,
or of a font made to its widths, and takes a file only when the family name inside it is
the one expected. `src/png.ts` sends the renderer's process the files a picture needs, and
or of a font made to its widths, and of its bold beside it, and takes a file only when the
family name inside it is the one expected. A bold text's `font-weight` comes before the three
attributes `src/png-child.ts` sizes a text by, so it sizes one by its bold face's cap height. `src/png.ts` sends the renderer's process the files a picture needs, and
the process sets the SVG's font family to the file's own. Every other font is drawn in the
shipped JetBrains Mono. `outputs.pngFonts` and each layout's `pngFonts` say which, from
`pictureFaces`, the one function that picks the files `toPNG` sends. A PDF embeds the same
Expand Down Expand Up @@ -75,7 +80,7 @@
for an entity so the others keep their indexes. `drawing.omitted` lists what was left out,
and the counts are the real drawing's. If that throws too, the build fails with `lint`'s
diagnostics kept and exit code 2. A throw with no lint error is a failed build as before.
`test/shape.test.ts` in the package proves `without` gives a drawing `toSVG` draws.
`test/shape-sweep.ts` in the package proves `without` gives a drawing `toSVG` draws.
- `tsdraft dev` must never present a stale or mismatched answer as current. Every file a build
loads whose real path has no `node_modules` folder is watched and version-checked, wherever it
is; `inProject` only places errors. A build that read a file changed since, or one file at two
Expand Down
16 changes: 13 additions & 3 deletions cli/assets/page.html
Original file line number Diff line number Diff line change
Expand Up @@ -730,10 +730,20 @@ <h3>Diagnostics</h3>
}
}

// The page draws an xref only when the drawing file gave its drawing.
// The page draws an xref only when the drawing file gave its drawing. Inside a drawing it
// draws, an attachment its model space places and not drawn is missing too; CAD draws no
// overlay there, and nothing the drawing places elsewhere.
function xrefsFact(xrefs) {
const missing = xrefs.filter((x) => !x.shown).length;
return missing ? `${xrefs.length}, ${missing} not drawn` : `${xrefs.length}`;
// A nested xref placed nowhere its drawing's model space reaches draws nothing below it.
const placed = (x, top) => top || (x.attach && x.inserts > 0);
const missing = (list, top) =>
list.reduce(
(count, x) =>
count + (!placed(x, top) ? 0 : x.shown ? missing(x.xrefs ?? [], false) : 1),
0,
);
const count = missing(xrefs, true);
return count ? `${xrefs.length}, ${count} not drawn` : `${xrefs.length}`;
}

// The standard the drawing file exports, beside the file's name.
Expand Down
1 change: 1 addition & 0 deletions cli/scripts/bench.ts
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ export default d.build();
// It is copied with its helpers, importing the library by name as the other two do.
const sheet = `${dir}/site-plan.ts`;
mkdirSync(`${dir}/lib`, { recursive: true });
copyFileSync(`${root}../examples/vicinity-map.png`, `${dir}/vicinity-map.png`);
for (const file of ["site-plan.ts", "lib/drafting.ts"]) {
const source = readFileSync(`${root}../examples/${file}`, "utf8");
writeFileSync(`${dir}/${file}`, source.replace(/"(\.\.\/)+src\/index\.ts"/, '"tsdraft"'));
Expand Down
Loading
Loading