@edubeam/plot 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,39 @@
2
2
 
3
3
  All notable changes to `@edubeam/plot` are listed here. The project follows [Semantic Versioning](https://semver.org).
4
4
 
5
+ ## 0.3.0 (2026-11-20)
6
+
7
+ - **Drawing for an editor**: the options the EduBeam app's new renderer draws with, all off by default.
8
+ `sizes` overrides the symbols' px sizes; `loadLabels: 'ends'` writes a distributed load at both ends as bare
9
+ numbers; `constantDiagrams: 'ends'` and `cornerValues: 'each'` annotate every segment and every member's end;
10
+ `splitLoads` draws a load's two components as the two loads they were entered as; `sideBySide` stands two
11
+ values written along one ordinate line side by side, each half a line aside, rather than one pushed out;
12
+ `freeNodes` draws nodes no member reaches yet; `labelsAvoidSupports`, `displacementText`, `diagramFill`
13
+ (`hatch`, `solid`, `none`), `showDegrees`, `normalOnDashedSide`, `shearOnDashedSide` and `supportScale` follow
14
+ the app's settings.
15
+ - **Member names**: a `memberLabels` layer writes each member's name once, along it and never upside down.
16
+ - **Loads that push the same way stack**, as a textbook draws them: a second band on top of the first, a point
17
+ load's arrow beyond the last one's value.
18
+ - **Reactions on their line of action**: every reaction force, the horizontal ones too, now points at its node.
19
+ - A diagram running straight on through a node writes the value it has on both sides once.
20
+ - **Pointing at things**: paths, circles and texts carry the `entity` they draw (`member:…`, `node:…`,
21
+ `elementLoad:…`, `nodalLoad:…`), loads carry their `source` from `modelFromSolver`, and each distributed
22
+ load has an undrawn `hitArea` path covering its band, so an app can highlight or hit-test what it shows.
23
+ - **Values at the pointer**: `placeReadoutTags` places a readout's tags beside their diagram points, outward
24
+ only and inside a viewport; `readMember` and `readoutAt` snap to a member's ends and, for the quantities read,
25
+ to their interior extremes (the largest moment, where the shear is zero, first); `formatReadout` takes a
26
+ writer for displacements.
27
+ - **Label priorities**: `resolveScene` takes `lateGroups` (placed after the given data), `yieldingGroups` (give
28
+ way to every other label) and `keptGroups` (never left out), and reports the painted `bounds`. A text placement
29
+ marked `acrossDiagrams` may cross another diagram's outline.
30
+ - A structure drawn at an extreme zoom (a fit's first probe) no longer runs out of memory: a member gets at most
31
+ 500 load arrows or hatch lines, spaced wider when it is longer.
32
+ - **Faster**: labels are placed against a spatial grid (a 375-member frame placed in 0.3 s, down from 10 s),
33
+ `mergePaths` joins alike paths (a band of thirty arrows becomes two paths), and diagram maxima are cached.
34
+ - **`sceneSvg`** writes a scene laid out by an application as a standalone `.svg` file, and **`sceneMarkup`** as
35
+ markup for an SVG of its own, with the same Word- and Inkscape-safe output as `structureSvg`.
36
+ - `SymbolSizes` is exported.
37
+
5
38
  ## 0.2.0 (2026-11-19)
6
39
 
7
40
  - **Translatable screen-reader texts**: `PLOT_TEXTS` (an injection key) lets an app give the figure's accessible
@@ -9,7 +9,7 @@ import type { PlotLayer, ReactionLabels, ResultLabelMode, ResultLayer } from '..
9
9
  import type { Units } from '../core/units.js';
10
10
  import type { PlotColors } from './theme.js';
11
11
  export interface StructurePlotProps {
12
- /** A ts-fem solver; solved, to show results. Pass a new one (or bump `revision`) after a change. */
12
+ /** An @edubeam/fem solver; solved, to show results. Pass a new one (or bump `revision`) after a change. */
13
13
  solver?: Solver;
14
14
  /** Or the plain data `modelFromSolver` makes, e.g. prepared at build time. */
15
15
  model?: PlotModel;
@@ -31,7 +31,7 @@ export interface LineIntensity {
31
31
  }
32
32
  export type PlotLoad =
33
33
  /** A force at a node, global components, N. */
34
- {
34
+ ({
35
35
  readonly kind: 'nodalForce';
36
36
  readonly node: string;
37
37
  readonly fx: number;
@@ -80,6 +80,9 @@ export type PlotLoad =
80
80
  readonly dx?: number;
81
81
  readonly dz?: number;
82
82
  readonly ry?: number;
83
+ }) & {
84
+ /** Where the caller keeps it, to tell which drawn load is which (the editor's `nodalLoad:3`). */
85
+ readonly source?: string;
83
86
  };
84
87
  export type PlotLoadKind = PlotLoad['kind'];
85
88
  export type ReactionDof = 'dx' | 'dz' | 'ry';
@@ -24,7 +24,6 @@ export declare const evalPieceSlope: (piece: Piece, x: number) => number;
24
24
  * right of one - never leaks into the piece: its end values are the one-sided limits.
25
25
  */
26
26
  export declare const fitPiece: (f: (x: number) => number, x0: number, x1: number, degree: number) => Piece;
27
- /** Largest |value| over the pieces, end values and interior extremes included. */
28
27
  export declare const maxAbs: (pw: Piecewise) => number;
29
28
  /**
30
29
  * Drops coefficients below `tolerance`: the round-off a solved structure leaves in a value that is
@@ -3,7 +3,7 @@
3
3
  * values where a point load or a support makes a step.
4
4
  */
5
5
  import { type MemberResults, type PlotModel } from './model.js';
6
- import { type Tone, type Transform } from './scene.js';
6
+ import { type Bounds, type Tone, type Transform } from './scene.js';
7
7
  import { type Units } from './units.js';
8
8
  /** Either side of a point; the two are equal where the result is continuous. */
9
9
  export interface SidedValue {
@@ -22,14 +22,22 @@ export interface Readout {
22
22
  /** Displacement along the member's local x there, m. */
23
23
  readonly u: number;
24
24
  }
25
- /** The results at x, snapping to a break within `snap` metres so a step shows both its values. */
26
- export declare const readMember: (results: MemberResults, x: number, snap?: number) => {
25
+ /**
26
+ * The results at x, snapping to a point a reader looks for within `snap` metres: a break, so a step
27
+ * shows both its values, or - given the member's `length` - an end; else an interior extreme of a
28
+ * quantity in `extremaOf`, the largest moment (where the shear is zero) before the largest
29
+ * deflection, then shear and normal force. Within a kind, the nearest.
30
+ */
31
+ export declare const readMember: (results: MemberResults, x: number, snap?: number, length?: number, extremaOf?: readonly ReadoutQuantity[]) => {
27
32
  x: number;
28
33
  u: number;
29
34
  values: Record<ReadoutQuantity, SidedValue>;
30
35
  };
31
- /** The member nearest the screen point (px, py), within `reach` px, and its results there. */
32
- export declare const readoutAt: (model: PlotModel, t: Transform, px: number, py: number, reach: number) => Readout | null;
36
+ /**
37
+ * The member nearest the screen point (px, py), within `reach` px, and its results there, snapped
38
+ * to its steps, its ends and the extremes of the quantities in `extremaOf` (see `readMember`).
39
+ */
40
+ export declare const readoutAt: (model: PlotModel, t: Transform, px: number, py: number, reach: number, extremaOf?: readonly ReadoutQuantity[]) => Readout | null;
33
41
  /** Where a read value sits on the drawing: on its diagram's outline, or on the deformed shape. */
34
42
  export interface ReadoutMark {
35
43
  readonly tone: Tone;
@@ -44,5 +52,32 @@ export interface ReadoutMark {
44
52
  * per SI unit, `side` the side each diagram is drawn on (see `diagramScales`, `diagramSide`).
45
53
  */
46
54
  export declare const readoutMarks: (model: PlotModel, t: Transform, r: Readout, shown: readonly ReadoutQuantity[], k: Readonly<Record<ReadoutQuantity, number>>, side: Readonly<Record<"N" | "V" | "M", 1 | -1>>) => ReadoutMark[];
47
- /** "M = 54 kNm", or "V = 13.3 → −6.7 kN" across a step. */
48
- export declare const formatReadout: (r: Readout, q: ReadoutQuantity, units: Units, format?: Intl.NumberFormat) => string;
55
+ /**
56
+ * "M = 54 kNm", or "V = 13.3 → −6.7 kN" across a step. `write`, given a value in display units,
57
+ * writes the number in place of `format` (an editor's own style for displacements, say).
58
+ */
59
+ export declare const formatReadout: (r: Readout, q: ReadoutQuantity, units: Units, format?: Intl.NumberFormat, write?: (value: number) => string) => string;
60
+ /** A value read off the drawing, as a small tag beside the point it belongs to. */
61
+ export interface ReadoutTag {
62
+ readonly tone: Tone;
63
+ readonly text: string;
64
+ /** The tag's box, px. */
65
+ readonly x: number;
66
+ readonly y: number;
67
+ readonly w: number;
68
+ readonly h: number;
69
+ /** The point it belongs to, px: a diagram's tip, the displaced point, or the member point. */
70
+ readonly at: readonly [number, number];
71
+ }
72
+ /**
73
+ * Each read value as a tag just past the point it belongs to, along that quantity's own ordinate
74
+ * (out from the member), stepping further out only to keep clear of the tags already placed, the
75
+ * member and the pointer. The station's `x` is the last tag, beside the member point on the side
76
+ * the fewest values take. `member` is the member's line on screen, px.
77
+ */
78
+ export declare const placeReadoutTags: (readings: readonly {
79
+ readonly mark: ReadoutMark;
80
+ readonly text: string;
81
+ }[], caption: string | null, member: readonly [readonly [number, number], readonly [number, number]], pointer: readonly [number, number], fontSize: number,
82
+ /** The visible area, px: a tag that would leave it is put elsewhere */
83
+ viewport?: Bounds) => ReadoutTag[];
@@ -49,6 +49,11 @@ export type LayerIndex = (typeof LAYERS)[keyof typeof LAYERS];
49
49
  /** What every item carries: the caller's layer it belongs to, which switches it on and off. */
50
50
  interface SceneBase {
51
51
  readonly group: string;
52
+ /**
53
+ * What the item draws, for a caller that marks it on hover or selection: `member:<id>`,
54
+ * `node:<id>`, or a load's own `source`. Items of nothing in particular (dimensions) have none.
55
+ */
56
+ readonly entity?: string;
52
57
  }
53
58
  export interface ScenePath extends SceneBase {
54
59
  readonly kind: 'path';
@@ -73,6 +78,11 @@ export interface ScenePath extends SceneBase {
73
78
  readonly shield?: boolean;
74
79
  /** Drawn on from start to end when it appears; the number staggers members one after another. */
75
80
  readonly draw?: number;
81
+ /**
82
+ * Not drawn: the area a caller hit-tests the item it belongs to by (a distributed load's band,
83
+ * mostly empty between its arrows). Never an obstacle, never fitted.
84
+ */
85
+ readonly hitArea?: boolean;
76
86
  }
77
87
  export type TextAlign = 'start' | 'middle' | 'end';
78
88
  export type TextBaseline = 'top' | 'middle' | 'bottom';
@@ -87,6 +97,11 @@ export interface TextPlacement {
87
97
  readonly size?: number;
88
98
  /** Clockwise turn, degrees. */
89
99
  readonly rotate?: number;
100
+ /**
101
+ * The spot may cross another diagram's outline, the label's halo keeping it readable: beside a
102
+ * value at the same point, which is where a reader looks for it, rather than further away.
103
+ */
104
+ readonly acrossDiagrams?: boolean;
90
105
  }
91
106
  export interface SceneText extends SceneBase {
92
107
  readonly kind: 'text';
@@ -106,6 +121,8 @@ export interface SceneText extends SceneBase {
106
121
  readonly size?: number;
107
122
  /** Written after `text`, smaller and lower: the x of A_x. */
108
123
  readonly sub?: string;
124
+ /** The place may cross another diagram's outline (see TextPlacement). */
125
+ readonly acrossDiagrams?: boolean;
109
126
  /** Other places to try, in order, when the first is taken. */
110
127
  readonly alternatives?: readonly TextPlacement[];
111
128
  }
@@ -174,6 +191,7 @@ export interface Fit extends Transform {
174
191
  export declare const fitScene: (items: readonly SceneItem[], box: FitBox) => Fit;
175
192
  export interface ResolvedPath {
176
193
  readonly group: string;
194
+ readonly entity?: string;
177
195
  readonly d: string;
178
196
  readonly layer: LayerIndex;
179
197
  readonly tone: Tone;
@@ -184,9 +202,12 @@ export interface ResolvedPath {
184
202
  readonly dash?: string;
185
203
  readonly cap?: 'round' | 'butt';
186
204
  readonly draw?: number;
205
+ /** Not to be drawn: an area to hit-test by (see ScenePath) */
206
+ readonly hitArea?: boolean;
187
207
  }
188
208
  export interface ResolvedText {
189
209
  readonly group: string;
210
+ readonly entity?: string;
190
211
  readonly x: number;
191
212
  readonly y: number;
192
213
  readonly text: string;
@@ -200,6 +221,7 @@ export interface ResolvedText {
200
221
  }
201
222
  export interface ResolvedCircle {
202
223
  readonly group: string;
224
+ readonly entity?: string;
203
225
  readonly cx: number;
204
226
  readonly cy: number;
205
227
  readonly r: number;
@@ -212,6 +234,11 @@ export interface ResolvedScene {
212
234
  readonly paths: readonly ResolvedPath[];
213
235
  readonly circles: readonly ResolvedCircle[];
214
236
  readonly texts: readonly ResolvedText[];
237
+ /**
238
+ * What is painted, px at the transform's scale with no translation: the labels where they were
239
+ * placed (left-out ones not at all), without the fit-ignored hatching and hit areas.
240
+ */
241
+ readonly bounds: Bounds;
215
242
  }
216
243
  export declare const pathData: (segments: readonly Segment[], t: Transform) => string;
217
244
  /** Whether the segment p–q passes through the box (Liang-Barsky clipping). */
@@ -236,13 +263,30 @@ export interface ResolveOptions {
236
263
  * hidden diagram does not keep a load's value off the place it would take.
237
264
  */
238
265
  readonly shields?: ReadonlySet<string>;
266
+ /**
267
+ * Groups placed after every other label: the results, read off the structure. The others (loads,
268
+ * reactions, names) are what the reader was given, so they go first. With it, a label that finds
269
+ * no place clear of another diagram's outline may cross it, its halo keeping it readable, rather
270
+ * than be left out. Without it, every group is placed by priority alone.
271
+ */
272
+ readonly lateGroups?: ReadonlySet<string>;
273
+ /**
274
+ * Groups that give way to every other label: their labels are placed last, and their lines keep
275
+ * no other group's label off (an editor's loads, whose values stand outside their bands while the
276
+ * internal forces' values may lie over a band's side).
277
+ */
278
+ readonly yieldingGroups?: ReadonlySet<string>;
279
+ /** Groups whose labels are never left out: with no free place, at their first place all the same. */
280
+ readonly keptGroups?: ReadonlySet<string>;
239
281
  }
240
- /**
241
- * Which labels to draw. By priority, a label is kept unless it would overlap one already kept,
242
- * cross a member, or leave the viewport - so the figure never shows two numbers on top of each
243
- * other or a number struck through by the structure.
244
- */
245
282
  export declare const placeLabels: (items: readonly SceneItem[], t: Transform, options: ResolveOptions) => Map<SceneText, SceneText>;
246
283
  /** Screen geometry for the scene, with the labels `placeLabels` keeps. */
284
+ /**
285
+ * The resolved paths with every run that would paint alike - same layer, group, entity and style -
286
+ * joined into one path: a band of thirty arrows becomes two paths (shafts, heads) instead of sixty.
287
+ * Paint order is kept between layers and between different styles; within a layer, alike paths
288
+ * gather where the first of them was. Paths that animate on (`draw`) are left alone.
289
+ */
290
+ export declare const mergePaths: (paths: readonly ResolvedPath[]) => ResolvedPath[];
247
291
  export declare const resolveScene: (items: readonly SceneItem[], t: Transform, options: ResolveOptions) => ResolvedScene;
248
292
  export {};
@@ -11,7 +11,7 @@ import { type InternalForce, type MemberFrame, type MemberResults, type PlotMode
11
11
  import { type Anchor, type SceneItem, type TextPlacement } from './scene.js';
12
12
  import { type Units } from './units.js';
13
13
  /** What the caller switches on and off. Results are named by their symbol. */
14
- export type PlotLayer = 'nodes' | 'nodeLabels' | 'dimensions' | 'members' | 'supports' | 'loads' | 'reactions' | 'N' | 'V' | 'M' | 'w';
14
+ export type PlotLayer = 'nodes' | 'nodeLabels' | 'memberLabels' | 'dimensions' | 'members' | 'supports' | 'loads' | 'reactions' | 'N' | 'V' | 'M' | 'w';
15
15
  /** Every layer, in paint order: results under the structure, nodes on top as BuildSteps draws them. */
16
16
  export declare const PLOT_LAYERS: readonly PlotLayer[];
17
17
  export interface TemperatureSymbols {
@@ -28,8 +28,53 @@ export interface StructureSceneOptions {
28
28
  readonly layers: ReadonlySet<PlotLayer>;
29
29
  /** Thumbnail drawing: smaller symbols, at most two values per member, magnitudes only. */
30
30
  readonly compact: boolean;
31
+ /**
32
+ * Sizes in place of the preset's (full or compact), px: an editor draws its members lighter, its
33
+ * arrows shorter and alike for loads and reactions, its moments as a nearly closed ring.
34
+ */
35
+ readonly sizes?: Partial<SymbolSizes>;
36
+ /**
37
+ * How loads are written. `figure` (the default): with their units, a uniform load once as
38
+ * `q = …`. `ends`: as an editor annotates them, bare numbers (its units shown elsewhere), and a
39
+ * distributed load at both its ends, zero included, as students are taught to write it.
40
+ */
41
+ readonly loadLabels?: 'figure' | 'ends';
42
+ /**
43
+ * A diagram constant along its member: its value `once`, mid-member (the default), or at both
44
+ * `ends`, as students are taught to annotate every segment.
45
+ */
46
+ readonly constantDiagrams?: 'once' | 'ends';
47
+ /**
48
+ * A moment the same round a rigid corner: written `once` (the default), at the member with the
49
+ * most room, or at `each` member's end, as students annotate every member.
50
+ */
51
+ readonly cornerValues?: 'once' | 'each';
52
+ /** Labels keep off the support symbols too, not only the members and arrows. */
53
+ readonly labelsAvoidSupports?: boolean;
54
+ /**
55
+ * Nodes no member reaches are drawn too, with their names and supports: an editor's nodes, placed
56
+ * before they are connected. By default a figure leaves them out.
57
+ */
58
+ readonly freeNodes?: boolean;
59
+ /**
60
+ * A distributed load with both components drawn as the two loads it was entered as (along and
61
+ * across the member for a local load, x and z for a global one), each with its own value, rather
62
+ * than as their resultant.
63
+ */
64
+ readonly splitLoads?: boolean;
65
+ /**
66
+ * Values of different diagrams on one ordinate line, written along it, stand side by side there,
67
+ * each half a line aside, rather than one pushed further out (see `sideBySide`).
68
+ */
69
+ readonly sideBySide?: boolean;
31
70
  readonly units: Units;
32
71
  readonly numberFormat?: Intl.NumberFormat;
72
+ /**
73
+ * Writes a displacement, given in display units. Displacements are orders of magnitude smaller
74
+ * than the forces, so an editor writes them its own way (a power of ten where `numberFormat`'s
75
+ * fixed decimals would round a deflection to zero).
76
+ */
77
+ readonly displacementText?: (value: number) => string;
33
78
  /** The temperature load's symbols, which apps write differently: the Czech EduBeam has ΔTs and ΔTd − ΔTh. */
34
79
  readonly temperatureSymbols?: TemperatureSymbols;
35
80
  /** Current scale in px per metre: spaces ordinates and load arrows evenly on screen. */
@@ -42,6 +87,19 @@ export interface StructureSceneOptions {
42
87
  readonly diagramScale?: Partial<Record<ResultLayer, number>>;
43
88
  /** M on the tension side (most of Europe); off draws it on the compression side. */
44
89
  readonly momentOnTensionSide: boolean;
90
+ /** Positive N on the member's dashed side (local +z); off (the default), on the other. */
91
+ readonly normalOnDashedSide?: boolean;
92
+ /** Positive V on the member's dashed side (local +z); off (the default), on the other. */
93
+ readonly shearOnDashedSide?: boolean;
94
+ /**
95
+ * How a diagram's area is drawn: `hatch` (the default), lines across the member as drawn by
96
+ * hand; `solid`, a light tint; `none`, the outline alone.
97
+ */
98
+ readonly diagramFill?: 'hatch' | 'solid' | 'none';
99
+ /** Write each piece's polynomial degree inside the diagram: 0°, 1°, 2°, 3°. */
100
+ readonly showDegrees?: boolean;
101
+ /** Support symbols' size, as a multiple of the preset's (the editor's support size setting). */
102
+ readonly supportScale?: number;
45
103
  /** The plot's font size, px: labels in a tight spot may step down from it to 10 px. */
46
104
  readonly fontSize?: number;
47
105
  /** Values upright (`horizontal`) or turned to run along their ordinate (`axis`), as in the app. */
@@ -58,19 +116,88 @@ export type ResultLabelMode = 'axis' | 'horizontal';
58
116
  export type ReactionLabels = 'values' | 'names';
59
117
  /** Ordinates are this far apart on screen, as in the app and the website's figures. */
60
118
  export declare const HATCH_SPACING_PX = 7;
119
+ /** Symbol sizes in px: the website's figures, and a smaller set for thumbnails. */
120
+ declare const SIZES: {
121
+ readonly full: {
122
+ readonly member: 3.5;
123
+ /** A hinge's circle, radius: its own size, so a lighter member keeps a readable hinge */
124
+ readonly hinge: 4.5;
125
+ /** A moment load's arc: how far round it runs, its weight and its head */
126
+ readonly arcSweep: 270;
127
+ readonly arcWidth: 1.75;
128
+ readonly arcHead: 8;
129
+ readonly arcHeadHalf: 3.5;
130
+ readonly pointShaft: 3;
131
+ readonly pointHead: 12;
132
+ readonly pointHeadWidth: 14;
133
+ readonly pointArrow: 52;
134
+ readonly udlArrow: 32;
135
+ readonly udlSpacing: 18;
136
+ readonly reaction: 46;
137
+ readonly reactionShaft: 1.75;
138
+ readonly reactionHead: 9;
139
+ readonly reactionHeadWidth: 9;
140
+ readonly reactionGap: 11;
141
+ /** A reaction's arrow clear of a moment's ring round the same node */
142
+ readonly reactionArcGap: 8;
143
+ /** A node's label from the node, and from it when a moment's ring surrounds it */
144
+ readonly nodeLabelGap: 9;
145
+ readonly arcLabelGap: 24;
146
+ readonly arcLabelFirst: 24;
147
+ readonly arc: 15;
148
+ readonly reactionArc: 20;
149
+ /** A moment reaction's arc: a half circle on the support's side, clear of the diagrams */
150
+ readonly reactionArcSweep: 190;
151
+ readonly deformed: 2.25;
152
+ };
153
+ readonly compact: {
154
+ readonly member: 2.75;
155
+ readonly hinge: 3.75;
156
+ readonly arcSweep: 270;
157
+ readonly arcWidth: 1.75;
158
+ readonly arcHead: 8;
159
+ readonly arcHeadHalf: 3.5;
160
+ readonly pointShaft: 2.25;
161
+ readonly pointHead: 9;
162
+ readonly pointHeadWidth: 10;
163
+ readonly pointArrow: 34;
164
+ readonly udlArrow: 22;
165
+ readonly udlSpacing: 14;
166
+ readonly reaction: 32;
167
+ readonly reactionShaft: 1.75;
168
+ readonly reactionHead: 9;
169
+ readonly reactionHeadWidth: 9;
170
+ readonly reactionGap: 8;
171
+ readonly reactionArcGap: 8;
172
+ readonly nodeLabelGap: 9;
173
+ readonly arcLabelGap: 24;
174
+ readonly arcLabelFirst: 24;
175
+ readonly arc: 11;
176
+ readonly reactionArc: 15;
177
+ readonly reactionArcSweep: 190;
178
+ readonly deformed: 1.75;
179
+ };
180
+ };
181
+ /** Every symbol's size, px: line weights, arrow lengths and heads, arcs. */
182
+ export type SymbolSizes = {
183
+ readonly [K in keyof (typeof SIZES)['full']]: number;
184
+ };
61
185
  type Vec = {
62
186
  readonly x: number;
63
187
  readonly y: number;
64
188
  };
65
189
  /** Which way a positive value is drawn, along the member's local z: +1 toward local +z. */
66
- export declare const diagramSide: (q: InternalForce, momentOnTensionSide: boolean) => 1 | -1;
190
+ export declare const diagramSide: (q: InternalForce, momentOnTensionSide: boolean, dashed?: {
191
+ readonly normalOnDashedSide?: boolean;
192
+ readonly shearOnDashedSide?: boolean;
193
+ }) => 1 | -1;
67
194
  /**
68
195
  * Where a value goes: just beyond the tip of the ordinate it denotes, along that ordinate, so it
69
196
  * reads as the ordinate's continuation. With `axis` the text turns to run along the ordinate
70
197
  * (across the member), as the app writes it, never upside down. Each further place moves it
71
198
  * outward along the same ordinate - it never leaves its tip.
72
199
  */
73
- export declare const tipPlacements: (tip: Anchor, out: Vec, mode: ResultLabelMode, gaps?: number[]) => TextPlacement[];
200
+ export declare const tipPlacements: (tip: Anchor, out: Vec, mode: ResultLabelMode, gaps?: readonly number[], asides?: readonly number[]) => TextPlacement[];
74
201
  /** Every member carries one constant normal force and no member loads: a truss, read bar by bar. */
75
202
  export declare const isBarStructure: (model: PlotModel, results: Readonly<Record<string, MemberResults>>) => boolean;
76
203
  /** px per SI unit for each result, from the largest value anywhere in the structure. */
@@ -1,5 +1,5 @@
1
1
  import type { PlotModel } from './model.js';
2
- import { type Tone } from './scene.js';
2
+ import { type ResolvedScene, type Tone } from './scene.js';
3
3
  import { type PlotLayer, type ReactionLabels, type ResultLabelMode, type TemperatureSymbols } from './structure.js';
4
4
  import { type Units } from './units.js';
5
5
  /** Concrete colours for a file that has no page around it: the EduBeam app's, on white. */
@@ -48,3 +48,29 @@ export interface StructureSvgOptions {
48
48
  * `paint-order`.
49
49
  */
50
50
  export declare const structureSvg: (model: PlotModel, options?: StructureSvgOptions) => string;
51
+ export interface SceneSvgOptions {
52
+ readonly colors?: Partial<Record<Tone | 'paper', string>>;
53
+ /** The labels' size where a label has none of its own, px. Default 13. */
54
+ readonly fontSize?: number;
55
+ readonly fontFamily?: string;
56
+ /** Paint the background in `paper`; off leaves it transparent. Default on. */
57
+ readonly background?: boolean;
58
+ /** Accessible name, written as the SVG's `<title>`. */
59
+ readonly title?: string;
60
+ }
61
+ /** How a scene's shapes and labels are written: its colours and its labels' size. */
62
+ export type SceneMarkupOptions = Pick<SceneSvgOptions, 'colors' | 'fontSize'>;
63
+ /**
64
+ * A scene already laid out, as SVG markup without the root element: its shapes layer by layer in
65
+ * paint order, then every label, each with its halo as a text of its own underneath (for programs
66
+ * that ignore `paint-order`). For an application that places the drawing in an SVG of its own.
67
+ */
68
+ export declare const sceneMarkup: (resolved: Pick<ResolvedScene, "paths" | "circles" | "texts">, options?: SceneMarkupOptions) => string;
69
+ /**
70
+ * A scene already laid out, as the text of a standalone `.svg` file of the given size: for an
71
+ * application that lays a structure out its own way and saves it as `structureSvg` saves its own.
72
+ */
73
+ export declare const sceneSvg: (resolved: Pick<ResolvedScene, "paths" | "circles" | "texts">, size: {
74
+ readonly width: number;
75
+ readonly height: number;
76
+ }, options?: SceneSvgOptions) => string;
package/dist/index.d.ts CHANGED
@@ -6,12 +6,12 @@ export { EduBeamPlot } from './plugin.js';
6
6
  export { DEFAULT_PLOT_TEXTS, PLOT_TEXTS, usePlotTexts, type PlotTexts } from './components/texts.js';
7
7
  export { modelFromSolver, type FromSolverOptions } from './core/fromSolver.js';
8
8
  export { layoutStructure, alternativeResultGroups, type StructureLayout } from './core/layout.js';
9
- export { structureSvg, PRINT_COLORS, type StructureSvgOptions } from './core/svg.js';
9
+ export { structureSvg, sceneSvg, sceneMarkup, PRINT_COLORS, type StructureSvgOptions, type SceneSvgOptions, type SceneMarkupOptions, } from './core/svg.js';
10
10
  export * from './core/model.js';
11
11
  export * from './core/polynomial.js';
12
12
  export * from './core/units.js';
13
13
  export { supportKind, supportPlacement, supportGlyph, glyphReach, type SupportKind, type SupportPlacement, type GlyphPart, } from './core/supports.js';
14
- export { buildStructureScene, defaultResultLayer, diagramScales, diagramSide, isBarStructure, memberFrames, HATCH_SPACING_PX, DEFAULT_TEMPERATURE_SYMBOLS, PLOT_LAYERS, RESULT_LAYERS, type PlotLayer, type TemperatureSymbols, type ReactionLabels, type ResultLabelMode, type ResultLayer, type StructureSceneOptions, tipPlacements, } from './core/structure.js';
15
- export { fitScene, placeLabels, resolveScene, sceneBounds, project, type Anchor, type Fit, type FitBox, type SceneItem, type ResolvedScene, type ResolvedPath, type ResolvedText, type ResolvedCircle, type ResolveOptions, type SceneText, type Bounds, type TextPlacement, type Transform, type Tone, } from './core/scene.js';
16
- export { readMember, readoutAt, readoutMarks, formatReadout, type Readout, type ReadoutMark, type ReadoutQuantity, type SidedValue, } from './core/readout.js';
14
+ export { buildStructureScene, defaultResultLayer, diagramScales, diagramSide, isBarStructure, memberFrames, HATCH_SPACING_PX, DEFAULT_TEMPERATURE_SYMBOLS, PLOT_LAYERS, RESULT_LAYERS, type PlotLayer, type TemperatureSymbols, type ReactionLabels, type ResultLabelMode, type ResultLayer, type StructureSceneOptions, type SymbolSizes, tipPlacements, } from './core/structure.js';
15
+ export { fitScene, placeLabels, resolveScene, mergePaths, sceneBounds, project, type Anchor, type Fit, type FitBox, type SceneItem, type ResolvedScene, type ResolvedPath, type ResolvedText, type ResolvedCircle, type ResolveOptions, type SceneText, type Bounds, type TextPlacement, type Transform, type Tone, } from './core/scene.js';
16
+ export { readMember, readoutAt, readoutMarks, formatReadout, placeReadoutTags, type ReadoutTag, type Readout, type ReadoutMark, type ReadoutQuantity, type SidedValue, } from './core/readout.js';
17
17
  export { beamLine, lineDiagram, lineModel, pointLoadAt, rowOutline, rowOrdinates, rowRange, rowPeaks, rowBreaks, type BeamLine, type LineMember, type RowPeak, type StackRow, } from './core/stack.js';