@mark1russell7/layout-contract 0.0.0-stage → 0.2.1
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/LICENSE +21 -0
- package/README.md +46 -2
- package/build/index.d.ts +421 -0
- package/build/index.d.ts.map +1 -0
- package/build/index.js +584 -0
- package/build/index.js.map +1 -0
- package/package.json +57 -3
- package/src/geometry.ts +109 -0
- package/src/index.ts +9 -0
- package/src/input.ts +144 -0
- package/src/measures.ts +53 -0
- package/src/output.ts +58 -0
- package/src/record.ts +83 -0
- package/src/rules.ts +241 -0
- package/src/strategy.ts +20 -0
- package/src/tolerance.ts +25 -0
- package/src/turn.ts +67 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Mark Russell
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,47 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @mark1russell7/layout-contract
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The shared contract of two layout engines: [`packing`](https://github.com/mark1russell7/packing) places boxes, and [`highways`](https://github.com/mark1russell7/highways) routes the edges between them. Neither engine depends on the other. Both use this contract, so a placement and a routing compose.
|
|
4
|
+
|
|
5
|
+
The package has no runtime dependencies.
|
|
6
|
+
|
|
7
|
+
## The contents
|
|
8
|
+
|
|
9
|
+
| Part | Exports |
|
|
10
|
+
|---|---|
|
|
11
|
+
| Geometry | `Point`, `Rect`, `Region`, `Side`, `Sides`, `Margin`, `marginSides`, `grow`, `boundsOf`, `translate`, `overlapOf` |
|
|
12
|
+
| The input `layout-input/1` | `LayoutInput`, `LayoutBox` (`Item` for the packer), `Port`, `LayoutEdge`, `LayoutContainer`, `Obstacle`, `LayoutCell`, `LayoutGenerator` |
|
|
13
|
+
| The packer | `PackInput`, `toPackInput`, `Placement`, `PackOutput`, `StageTrace`, `applyPack` |
|
|
14
|
+
| The record `layout-record/1` | `LayoutRecord`, `Stage`, `Supports`, `RunFacts`, `RunEnv`, `toLayoutRecord` |
|
|
15
|
+
| The strategies | `StrategyInfo` |
|
|
16
|
+
| The measures | `MeasureSpec`, `Direction`, `JointMeasureId`, `JOINT_MEASURES`, `JOINT_MOVED_MIN` |
|
|
17
|
+
| The turn | `turnBox`, `turnPort`, `turnMargin`, `turnRegion`, `turnSide`, `turnPoint` |
|
|
18
|
+
| The tolerances | `EPS`, `RECORD_EPS`, `Tolerance`, `DEFAULT_TOLERANCE` |
|
|
19
|
+
| The hard rules | `countOverlaps`, `countObstacleHits`, `regionHitsRect`, `countOutside`, `countPortsOffBorder`, `packHard`, `PackHard`, `placedRect`, `checkInput` |
|
|
20
|
+
|
|
21
|
+
## The rules
|
|
22
|
+
|
|
23
|
+
- **The turn.** A turn is 90 degrees clockwise, with the y axis down. A point (`px`, `py`) of a box of height `h` goes to (`h - py`, `px`). Each side moves one step clockwise. The router gets the turned box and ports, and does not read `turn`.
|
|
24
|
+
- **The margin.** A margin is a ring around a box. No other box and no route enters it. A route from a port of the box crosses the ring at a right angle.
|
|
25
|
+
- **The gap.** The gap is the free space between two boxes with their margins. Routes use it. Two boxes are `mA + gap + mB` apart.
|
|
26
|
+
- **The ports.** A port can have a side. Without a side, the router picks the side. A fixed port has `x` and `y` on the border of the box, relative to its top-left corner.
|
|
27
|
+
- **The hard rules of a pack.** `no-overlap` counts the pairs of boxes and the pairs of a box and an obstacle. A locked box without a placement, or with a move of more than `RECORD_EPS`, breaks `locked-kept`. `checkInput` refuses a locked box without a position. Another box without a placement and not in `overflow` breaks `complete`.
|
|
28
|
+
- **The tolerances.** `EPS` (`1e-6`) is for the float compares in an engine. `RECORD_EPS` (`1e-3`) is for the compares on a written file. A record writes the tolerance of each hard rule in its field `tolerance`. The defaults are `overlap` `0.001` and `through` `0.5`.
|
|
29
|
+
|
|
30
|
+
## An example
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
import { applyPack, packHard, toPackInput, type LayoutInput } from "@mark1russell7/layout-contract";
|
|
34
|
+
|
|
35
|
+
const input: LayoutInput = {
|
|
36
|
+
schema: "layout-input/1",
|
|
37
|
+
id: "example",
|
|
38
|
+
container: { w: 200, fixed: "width" },
|
|
39
|
+
gap: 4,
|
|
40
|
+
boxes: [{ id: "a", w: 40, h: 20, margin: 2 }],
|
|
41
|
+
};
|
|
42
|
+
const output = myPacker(toPackInput(input));
|
|
43
|
+
const placed = applyPack(input, output);
|
|
44
|
+
const hard = packHard(input, output);
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The formats are in `docs/FORMAT.md` of `packing` and `docs/LAYOUT-RECORDS.md` of `highways`. The joint measures are in `docs/JOINT-MEASURES.md` of this repository.
|
package/build/index.d.ts
ADDED
|
@@ -0,0 +1,421 @@
|
|
|
1
|
+
/** A side of a box. The y axis points down, so `top` has the smallest y. */
|
|
2
|
+
export type Side = "top" | "right" | "bottom" | "left";
|
|
3
|
+
/** The sides in clockwise order, from the top. */
|
|
4
|
+
export declare const SIDES: readonly Side[];
|
|
5
|
+
export interface Point {
|
|
6
|
+
readonly x: number;
|
|
7
|
+
readonly y: number;
|
|
8
|
+
}
|
|
9
|
+
/** A rectangle: its top-left corner and its size. */
|
|
10
|
+
export interface Rect {
|
|
11
|
+
readonly x: number;
|
|
12
|
+
readonly y: number;
|
|
13
|
+
readonly w: number;
|
|
14
|
+
readonly h: number;
|
|
15
|
+
}
|
|
16
|
+
/** A value for each side of a box. */
|
|
17
|
+
export interface Sides {
|
|
18
|
+
readonly top: number;
|
|
19
|
+
readonly right: number;
|
|
20
|
+
readonly bottom: number;
|
|
21
|
+
readonly left: number;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* A region. The forms and the rules are those of `docs/FORMAT.md` of `packing`.
|
|
25
|
+
* A ring of a polygon closes without a copy of its first point.
|
|
26
|
+
*/
|
|
27
|
+
export type Region = {
|
|
28
|
+
readonly kind: "rect";
|
|
29
|
+
readonly x: number;
|
|
30
|
+
readonly y: number;
|
|
31
|
+
readonly w: number;
|
|
32
|
+
readonly h: number;
|
|
33
|
+
} | {
|
|
34
|
+
readonly kind: "polygon";
|
|
35
|
+
readonly points: readonly (readonly [number, number])[];
|
|
36
|
+
readonly holes?: readonly (readonly (readonly [number, number])[])[];
|
|
37
|
+
} | {
|
|
38
|
+
readonly kind: "circle";
|
|
39
|
+
readonly cx: number;
|
|
40
|
+
readonly cy: number;
|
|
41
|
+
readonly r: number;
|
|
42
|
+
} | {
|
|
43
|
+
readonly kind: "ellipse";
|
|
44
|
+
readonly cx: number;
|
|
45
|
+
readonly cy: number;
|
|
46
|
+
readonly rx: number;
|
|
47
|
+
readonly ry: number;
|
|
48
|
+
};
|
|
49
|
+
/** A margin: one value for the four sides, or one value for each side. */
|
|
50
|
+
export type Margin = number | Sides;
|
|
51
|
+
/** This function gives the value of each side of a margin. No margin gives 0 on each side. */
|
|
52
|
+
export declare function marginSides(margin: Margin | undefined): Sides;
|
|
53
|
+
/** This function gives the rectangle made larger by the margin on each side. */
|
|
54
|
+
export declare function grow(rect: Rect, margin: Margin | undefined): Rect;
|
|
55
|
+
/** This function gives the bounding box of a region. */
|
|
56
|
+
export declare function boundsOf(region: Region): Rect;
|
|
57
|
+
/** This function gives the region moved by `dx` and `dy`. */
|
|
58
|
+
export declare function translate(region: Region, dx: number, dy: number): Region;
|
|
59
|
+
/**
|
|
60
|
+
* This function gives the overlap of the insides of two rectangles on each axis.
|
|
61
|
+
* A value of 0 or less on an axis is no overlap. Two rectangles with a common edge have an overlap of 0.
|
|
62
|
+
*/
|
|
63
|
+
export declare function overlapOf(a: Rect, b: Rect): {
|
|
64
|
+
readonly x: number;
|
|
65
|
+
readonly y: number;
|
|
66
|
+
};
|
|
67
|
+
/** The epsilon for the float compares in an engine. */
|
|
68
|
+
export declare const EPS = 1e-6;
|
|
69
|
+
/**
|
|
70
|
+
* The epsilon for the float compares on a written file. A file rounds each number to 3 decimals,
|
|
71
|
+
* so a difference of two values can move by up to 0.001.
|
|
72
|
+
*/
|
|
73
|
+
export declare const RECORD_EPS = .001;
|
|
74
|
+
/**
|
|
75
|
+
* The tolerance of each hard rule, in layout units. A record writes the tolerance that its run used,
|
|
76
|
+
* in its field `tolerance`, next to `hard`.
|
|
77
|
+
*/
|
|
78
|
+
export interface Tolerance {
|
|
79
|
+
/** Two boxes with their margins break `no-overlap` when their insides overlap by more than this on each axis. */
|
|
80
|
+
readonly overlap: number;
|
|
81
|
+
/** A route breaks `no-pass-through` when a part longer than this is inside a box made this much smaller. */
|
|
82
|
+
readonly through: number;
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* The default tolerance of each rule. The packer is exact, so `overlap` is one unit of the rounding.
|
|
86
|
+
* Routes are sampled curves that follow the margin line, so `through` is larger.
|
|
87
|
+
*/
|
|
88
|
+
export declare const DEFAULT_TOLERANCE: Tolerance;
|
|
89
|
+
/**
|
|
90
|
+
* A port of a box: a place where edges go into the box.
|
|
91
|
+
* With `x` and `y`, the port is fixed on the border of the box, relative to its top-left corner.
|
|
92
|
+
* Without them, the router places the port on its `side`. Without a side, the router picks the side.
|
|
93
|
+
*/
|
|
94
|
+
export interface Port {
|
|
95
|
+
readonly id: string;
|
|
96
|
+
readonly side?: Side;
|
|
97
|
+
readonly x?: number;
|
|
98
|
+
readonly y?: number;
|
|
99
|
+
}
|
|
100
|
+
/** A box of an input. In the packer, its name is item. */
|
|
101
|
+
export interface LayoutBox {
|
|
102
|
+
readonly id: string;
|
|
103
|
+
readonly w: number;
|
|
104
|
+
readonly h: number;
|
|
105
|
+
/** The packer writes the position. The router reads it. */
|
|
106
|
+
readonly x?: number;
|
|
107
|
+
readonly y?: number;
|
|
108
|
+
/** A locked box keeps `x` and `y`. The packer reads it as an obstacle. */
|
|
109
|
+
readonly locked?: boolean;
|
|
110
|
+
/** The reading order. Without it, the order of the array is the rank. */
|
|
111
|
+
readonly rank?: number;
|
|
112
|
+
readonly parent?: string;
|
|
113
|
+
readonly group?: string;
|
|
114
|
+
/** A region relative to the origin of the box. Without it, the box is the rectangle `w` by `h`. */
|
|
115
|
+
readonly shape?: Region;
|
|
116
|
+
readonly ports?: readonly Port[];
|
|
117
|
+
/** A ring around the box. No other box enters it. Only a route from a port of the box enters it, at a right angle. */
|
|
118
|
+
readonly margin?: Margin;
|
|
119
|
+
/** The packer can turn the box by 90 degrees. The output has the turned box and ports. */
|
|
120
|
+
readonly turnable?: boolean;
|
|
121
|
+
/** The free data of the node. The grouping rule `keys` of `highways` reads `data.group`. */
|
|
122
|
+
readonly data?: Readonly<Record<string, unknown>>;
|
|
123
|
+
}
|
|
124
|
+
/** The packer name of a box. It is the same type. */
|
|
125
|
+
export type Item = LayoutBox;
|
|
126
|
+
/** An edge between two boxes, with optional ports. */
|
|
127
|
+
export interface LayoutEdge {
|
|
128
|
+
readonly id: string;
|
|
129
|
+
readonly source: string;
|
|
130
|
+
readonly target: string;
|
|
131
|
+
readonly sourcePort?: string;
|
|
132
|
+
readonly targetPort?: string;
|
|
133
|
+
readonly data?: Readonly<Record<string, unknown>>;
|
|
134
|
+
}
|
|
135
|
+
/** The container. `fixed` tells which sides of the size stay. */
|
|
136
|
+
export interface LayoutContainer {
|
|
137
|
+
readonly w?: number;
|
|
138
|
+
readonly h?: number;
|
|
139
|
+
readonly fixed: "size" | "width" | "height" | "none";
|
|
140
|
+
/** The target aspect: the width divided by the height. The default is 1. */
|
|
141
|
+
readonly aspect?: number;
|
|
142
|
+
/** The weight of the aspect error in the objective. 0 gives the least area. The default is 1. */
|
|
143
|
+
readonly aspectWeight?: number;
|
|
144
|
+
/** The shape. Without it, the container is the rectangle from 0, 0 to `w`, `h`. */
|
|
145
|
+
readonly shape?: Region;
|
|
146
|
+
/** The space between the border and the boxes with their margins. */
|
|
147
|
+
readonly inset?: number;
|
|
148
|
+
}
|
|
149
|
+
/** An area that boxes and routes avoid. Without `move`, it stays. With `move`, the packer can move it for `cost` times the distance. */
|
|
150
|
+
export interface Obstacle {
|
|
151
|
+
readonly id: string;
|
|
152
|
+
readonly region: Region;
|
|
153
|
+
readonly move?: {
|
|
154
|
+
readonly cost: number;
|
|
155
|
+
};
|
|
156
|
+
}
|
|
157
|
+
/** The generator of an input. The same name, version, parameters and seed give the same file, byte for byte. */
|
|
158
|
+
export interface LayoutGenerator {
|
|
159
|
+
readonly name: string;
|
|
160
|
+
readonly version: number;
|
|
161
|
+
readonly params: Readonly<Record<string, unknown>>;
|
|
162
|
+
readonly seed: number;
|
|
163
|
+
}
|
|
164
|
+
/** The cell of an input in the taxonomy: one value for each dimension. The dimensions are in `docs/FORMAT.md` of `packing`. */
|
|
165
|
+
export interface LayoutCell {
|
|
166
|
+
readonly containerSize?: "fixed" | "freeHeight" | "freeWidth" | "freeAspect" | "freeArea";
|
|
167
|
+
readonly containerShape?: "rect" | "convex" | "polygon" | "circle" | "ellipse" | "holes";
|
|
168
|
+
readonly obstacles?: "none" | "center" | "scattered" | "wall" | "corridors" | "touching" | "edge";
|
|
169
|
+
readonly sizes?: "identical" | "uniform" | "heavyTail" | "bimodal" | "extremeAspect" | "nearIdentical";
|
|
170
|
+
readonly count?: "1" | "10" | "100" | "1k" | "10k";
|
|
171
|
+
readonly mode?: "offline" | "online" | "incremental";
|
|
172
|
+
readonly edgeDensity?: "sparse" | "medium" | "dense";
|
|
173
|
+
readonly edgeShape?: "random" | "clustered" | "hubChain" | "longRange" | "tree" | "bundled";
|
|
174
|
+
readonly groups?: "none" | "flat" | "nested";
|
|
175
|
+
readonly ports?: "free" | "sides" | "fixed";
|
|
176
|
+
}
|
|
177
|
+
/** An input of the corpus: the format `layout-input/1`. */
|
|
178
|
+
export interface LayoutInput {
|
|
179
|
+
readonly schema: "layout-input/1";
|
|
180
|
+
readonly id: string;
|
|
181
|
+
readonly set?: string;
|
|
182
|
+
readonly family?: string;
|
|
183
|
+
readonly seed?: number;
|
|
184
|
+
/** The origin: `made-up`, `published:<set>` or `known-best:<construction>`. */
|
|
185
|
+
readonly source?: string;
|
|
186
|
+
/** The first 16 hex characters of the SHA-256 of the canonical file without this field. */
|
|
187
|
+
readonly hash?: string;
|
|
188
|
+
/** The generator of the input. `null` or no value tells that a person made the input. */
|
|
189
|
+
readonly generator?: LayoutGenerator | null;
|
|
190
|
+
readonly cell?: LayoutCell;
|
|
191
|
+
/** The place of the input in a sequence of changes. */
|
|
192
|
+
readonly step?: number;
|
|
193
|
+
/** A router input can have no container. */
|
|
194
|
+
readonly container?: LayoutContainer;
|
|
195
|
+
/** The free space between two boxes with their margins. Routes use it. */
|
|
196
|
+
readonly gap?: number;
|
|
197
|
+
readonly boxes: readonly LayoutBox[];
|
|
198
|
+
readonly edges?: readonly LayoutEdge[];
|
|
199
|
+
readonly obstacles?: readonly Obstacle[];
|
|
200
|
+
/**
|
|
201
|
+
* A variant names its base input and its change.
|
|
202
|
+
* With `packed`, the variant is the packed output of its base input: the router routes the positions of that pack.
|
|
203
|
+
*/
|
|
204
|
+
readonly base?: string;
|
|
205
|
+
readonly change?: "add" | "remove" | "resize" | "reorder" | "packed";
|
|
206
|
+
}
|
|
207
|
+
/** The input of a packer: a `layout-input/1` file without the edges. */
|
|
208
|
+
export interface PackInput {
|
|
209
|
+
readonly container: LayoutContainer;
|
|
210
|
+
readonly items: readonly Item[];
|
|
211
|
+
readonly obstacles?: readonly Obstacle[];
|
|
212
|
+
readonly gap?: number;
|
|
213
|
+
}
|
|
214
|
+
/** This function gives the packer input of a file. An input without a container gets `{ fixed: "none" }`, so the packer picks the size. */
|
|
215
|
+
export declare function toPackInput(input: LayoutInput): PackInput;
|
|
216
|
+
/** The position of one item. `turn` is 90 when the packer turned a turnable item. */
|
|
217
|
+
export interface Placement {
|
|
218
|
+
readonly id: string;
|
|
219
|
+
readonly x: number;
|
|
220
|
+
readonly y: number;
|
|
221
|
+
readonly turn?: 0 | 90;
|
|
222
|
+
}
|
|
223
|
+
/** The facts of one stage of a strategy, for the records and the site. */
|
|
224
|
+
export interface StageTrace {
|
|
225
|
+
readonly id: string;
|
|
226
|
+
readonly ms?: number;
|
|
227
|
+
readonly measures?: Readonly<Record<string, number>>;
|
|
228
|
+
}
|
|
229
|
+
/** The output of a packer. It does not change the input. */
|
|
230
|
+
export interface PackOutput {
|
|
231
|
+
readonly placements: readonly Placement[];
|
|
232
|
+
/** The ids of the items that the packer did not place. */
|
|
233
|
+
readonly overflow: readonly string[];
|
|
234
|
+
/** The size of the container after the pack. For a free size, the size that the search found. */
|
|
235
|
+
readonly size: {
|
|
236
|
+
readonly w: number;
|
|
237
|
+
readonly h: number;
|
|
238
|
+
};
|
|
239
|
+
/** The new top-left corner of the bounding box of each obstacle that moved. */
|
|
240
|
+
readonly moved: readonly {
|
|
241
|
+
readonly id: string;
|
|
242
|
+
readonly x: number;
|
|
243
|
+
readonly y: number;
|
|
244
|
+
}[];
|
|
245
|
+
readonly trace?: readonly StageTrace[];
|
|
246
|
+
}
|
|
247
|
+
/**
|
|
248
|
+
* This function gives the input with the output of a packer applied. Each placed box gets its position.
|
|
249
|
+
* A turned box gets its turned size, ports, margin and shape. Each moved obstacle moves.
|
|
250
|
+
* The container gets the size of the output. The router reads this result. It does not read `turn`.
|
|
251
|
+
*/
|
|
252
|
+
export declare function applyPack(input: LayoutInput, output: PackOutput): LayoutInput;
|
|
253
|
+
/** The stage of a record: the packer, the router, or both together. */
|
|
254
|
+
export type Stage = "pack" | "route" | "joint";
|
|
255
|
+
/** One run of one strategy on one input and seed: the format `layout-record/1`. A run writes one line of JSON Lines. */
|
|
256
|
+
export interface LayoutRecord {
|
|
257
|
+
readonly schema: "layout-record/1";
|
|
258
|
+
readonly stage: Stage;
|
|
259
|
+
readonly step: string;
|
|
260
|
+
readonly strategy: string;
|
|
261
|
+
/** The options in full, with the defaults. */
|
|
262
|
+
readonly options: Readonly<Record<string, unknown>>;
|
|
263
|
+
readonly corpus: string;
|
|
264
|
+
/** The id of the input. */
|
|
265
|
+
readonly input: string;
|
|
266
|
+
/** The `hash` of the input file. */
|
|
267
|
+
readonly inputHash: string;
|
|
268
|
+
readonly set: string;
|
|
269
|
+
readonly seed: number;
|
|
270
|
+
readonly nodes: number;
|
|
271
|
+
readonly edges: number;
|
|
272
|
+
/** The value of each measure, by its name: `pack.*`, `route.*` or `joint.*`. */
|
|
273
|
+
readonly measures: Readonly<Record<string, number>>;
|
|
274
|
+
/** The count of the breaks of each hard rule. A good run has 0 for each rule. */
|
|
275
|
+
readonly hard: Readonly<Record<string, number>>;
|
|
276
|
+
/** The tolerance of each hard rule of the run. */
|
|
277
|
+
readonly tolerance?: Readonly<Partial<Tolerance>>;
|
|
278
|
+
/** `true` when two runs with the same seed give the same positions. */
|
|
279
|
+
readonly deterministic: boolean;
|
|
280
|
+
/** The id of the prediction that was written before the run. */
|
|
281
|
+
readonly prediction?: string;
|
|
282
|
+
/** The median of `msRuns`, or the time of the one run. */
|
|
283
|
+
readonly ms: number;
|
|
284
|
+
/** The time of each timed repeat, in milliseconds. */
|
|
285
|
+
readonly msRuns?: readonly number[];
|
|
286
|
+
/**
|
|
287
|
+
* The first 16 hex characters of the SHA-256 of the canonical output of the stage.
|
|
288
|
+
* The packer hashes its placements by the order of the ids. The router hashes its routes by the order of the edge ids.
|
|
289
|
+
*/
|
|
290
|
+
readonly outputHash?: string;
|
|
291
|
+
/** The facts of the computer of the run. */
|
|
292
|
+
readonly env?: RunEnv;
|
|
293
|
+
/** The reason when the strategy did not run, for example an input over its `maxNodes`. Then the record has no measures. */
|
|
294
|
+
readonly skipped?: string;
|
|
295
|
+
readonly commit?: string;
|
|
296
|
+
}
|
|
297
|
+
/**
|
|
298
|
+
* The values that a strategy supports, for each dimension of a taxonomy.
|
|
299
|
+
* The dimension names are in `docs/FORMAT.md` of `packing` and `docs/LAYOUT-RECORDS.md` of `highways`.
|
|
300
|
+
*/
|
|
301
|
+
export type Supports = Readonly<Record<string, readonly string[]>>;
|
|
302
|
+
/** The facts of the computer of a run. */
|
|
303
|
+
export interface RunEnv {
|
|
304
|
+
readonly node: string;
|
|
305
|
+
readonly os: string;
|
|
306
|
+
readonly arch: string;
|
|
307
|
+
/** The name of the runner, for example `ubuntu-latest` or `local`. */
|
|
308
|
+
readonly runner: string;
|
|
309
|
+
/** The model of the processor. */
|
|
310
|
+
readonly cpu: string;
|
|
311
|
+
/** The count of the logical processors. */
|
|
312
|
+
readonly cpus: number;
|
|
313
|
+
}
|
|
314
|
+
/** The facts of a run that the input does not give. */
|
|
315
|
+
export type RunFacts = Omit<LayoutRecord, "schema" | "input" | "inputHash" | "set" | "nodes" | "edges">;
|
|
316
|
+
/** This function gives the record of a run. The input gives its id, its hash, its set and the counts of the nodes and the edges. */
|
|
317
|
+
export declare function toLayoutRecord(input: LayoutInput, run: RunFacts): LayoutRecord;
|
|
318
|
+
/** This function gives the area of a placed box: its shape or its rectangle, at its position. A box without a position gives `undefined`. */
|
|
319
|
+
export declare function placedRect(box: LayoutBox): Rect | undefined;
|
|
320
|
+
/**
|
|
321
|
+
* This function counts the pairs of placed boxes whose insides, with their margins, overlap by more than `tolerance` on each axis.
|
|
322
|
+
* A box with a shape counts as its bounding box. That area is larger, thus the count is safe.
|
|
323
|
+
*/
|
|
324
|
+
export declare function countOverlaps(boxes: readonly LayoutBox[], tolerance?: number): number;
|
|
325
|
+
/**
|
|
326
|
+
* This function counts the placed boxes that go out of the container.
|
|
327
|
+
* Each box with its margin must stay inside the container made smaller by `inset`. Only the fixed sides of the size count. A shaped container counts as its bounding box.
|
|
328
|
+
* An input without a container gives 0.
|
|
329
|
+
*/
|
|
330
|
+
export declare function countOutside(input: LayoutInput, tolerance?: number): number;
|
|
331
|
+
/** This function counts the fixed ports that are not on the border of their box, with the epsilon of a written file. A port without a side does not count. */
|
|
332
|
+
export declare function countPortsOffBorder(boxes: readonly LayoutBox[], eps?: number): number;
|
|
333
|
+
/** The count of the breaks of each hard rule of a pack. */
|
|
334
|
+
export interface PackHard {
|
|
335
|
+
readonly "no-overlap": number;
|
|
336
|
+
readonly "in-container": number;
|
|
337
|
+
readonly "locked-kept": number;
|
|
338
|
+
readonly complete: number;
|
|
339
|
+
}
|
|
340
|
+
/** This function tells if the inside of `region` and the inside of `rect` have a common point. */
|
|
341
|
+
export declare function regionHitsRect(region: Region, rect: Rect): boolean;
|
|
342
|
+
/**
|
|
343
|
+
* This function counts the pairs of a placed box and an obstacle that overlap by more than `tolerance`.
|
|
344
|
+
* The box counts with its margin. A box with a shape counts as its bounding box.
|
|
345
|
+
*/
|
|
346
|
+
export declare function countObstacleHits(boxes: readonly LayoutBox[], obstacles: readonly Obstacle[] | undefined, tolerance?: number): number;
|
|
347
|
+
/**
|
|
348
|
+
* This function gives the count of each hard rule of the output of a packer.
|
|
349
|
+
* It applies the output with `applyPack`. Only the placed boxes and the locked boxes count for the overlaps and the container.
|
|
350
|
+
* `no-overlap` counts the pairs of boxes and the pairs of a box and an obstacle.
|
|
351
|
+
* A locked box without a placement, or with a move of more than `RECORD_EPS`, breaks `locked-kept`.
|
|
352
|
+
* A locked box without a position in the input is a bad input, not a break. `checkInput` finds it.
|
|
353
|
+
* Another box without a placement that is not in `overflow` breaks `complete`.
|
|
354
|
+
*/
|
|
355
|
+
export declare function packHard(input: LayoutInput, output: PackOutput, tolerance?: number): PackHard;
|
|
356
|
+
/**
|
|
357
|
+
* This function gives the problems of an input file. An empty list tells that the file is good.
|
|
358
|
+
* A problem is a bad input, not a break of a hard rule. Thus an engine refuses the input.
|
|
359
|
+
*/
|
|
360
|
+
export declare function checkInput(input: LayoutInput): readonly string[];
|
|
361
|
+
/** This function gives the side after a turn of 90 degrees clockwise. */
|
|
362
|
+
export declare function turnSide(side: Side): Side;
|
|
363
|
+
/** This function gives a point of a box of height `h` after the turn. */
|
|
364
|
+
export declare function turnPoint(x: number, y: number, h: number): [number, number];
|
|
365
|
+
/** This function gives a port of a box of height `h` after the turn. Each value of the port turns, also a port with only `x` or only `y`. */
|
|
366
|
+
export declare function turnPort(port: Port, h: number): Port;
|
|
367
|
+
/** This function gives a margin after the turn: the value of each side moves one side clockwise. */
|
|
368
|
+
export declare function turnMargin(margin: Margin): Margin;
|
|
369
|
+
/** This function gives a region relative to the origin of a box of height `h` after the turn. */
|
|
370
|
+
export declare function turnRegion(region: Region, h: number): Region;
|
|
371
|
+
/** This function gives a box after the turn: the size, the ports, the margin and the shape turn. The position stays. */
|
|
372
|
+
export declare function turnBox(box: LayoutBox): LayoutBox;
|
|
373
|
+
/** The direction of a measure: the side of the better values. */
|
|
374
|
+
export type Direction = "lower" | "higher";
|
|
375
|
+
/**
|
|
376
|
+
* The facts of one measure: its unit, its direction and its range.
|
|
377
|
+
* `floor` and `tol` are the parameters of the floor rule of the promotion rule (`docs/PROMOTION.md` of `highways`).
|
|
378
|
+
* Each engine exports the specs of its own measures. This package exports the specs of the `joint.*` measures.
|
|
379
|
+
*/
|
|
380
|
+
export interface MeasureSpec<Id extends string = string> {
|
|
381
|
+
readonly id: Id;
|
|
382
|
+
readonly unit: string;
|
|
383
|
+
readonly direction: Direction;
|
|
384
|
+
/** The lowest value. */
|
|
385
|
+
readonly min: number;
|
|
386
|
+
/** The highest value. The value `Infinity` tells that the measure has no upper limit. */
|
|
387
|
+
readonly max: number;
|
|
388
|
+
/** The family of the measure in the measure note of its engine. */
|
|
389
|
+
readonly family?: string;
|
|
390
|
+
/** The best value. Without it, the measure has no floor. */
|
|
391
|
+
readonly floor?: number;
|
|
392
|
+
/** The absolute tolerance at the floor. */
|
|
393
|
+
readonly tol?: number;
|
|
394
|
+
/** The role of the measure in the joint selector. */
|
|
395
|
+
readonly role?: "guard" | "change-guard" | "diagnostic" | "time";
|
|
396
|
+
}
|
|
397
|
+
/** The id of a joint measure. `docs/JOINT-MEASURES.md` gives the definitions. */
|
|
398
|
+
export type JointMeasureId = "joint.fill" | "joint.aspectError" | "joint.spill" | "joint.straight.crossings" | "joint.straight.length" | "joint.stability.mean" | "joint.stability.moved" | "joint.proxy.rank" | "joint.ms";
|
|
399
|
+
/** The specs of the joint measures, in the order of `docs/JOINT-MEASURES.md`. */
|
|
400
|
+
export declare const JOINT_MEASURES: readonly MeasureSpec<JointMeasureId>[];
|
|
401
|
+
/** The threshold of `joint.stability.moved`, in widths `W` of the base. */
|
|
402
|
+
export declare const JOINT_MOVED_MIN = .01;
|
|
403
|
+
/**
|
|
404
|
+
* The common fields of a strategy of an engine. Each engine adds its own function, for example `pack` or `route`.
|
|
405
|
+
* `O` is the type of the options, and `S` is the type of `supports`.
|
|
406
|
+
*/
|
|
407
|
+
export interface StrategyInfo<O = unknown, S extends Supports = Supports> {
|
|
408
|
+
/** A stable name, for example `shelf`. The records use it. */
|
|
409
|
+
readonly id: string;
|
|
410
|
+
/** The family of the catalog of the engine. */
|
|
411
|
+
readonly family: string;
|
|
412
|
+
/** The ids of the catalog rows that the strategy builds. */
|
|
413
|
+
readonly catalog: readonly string[];
|
|
414
|
+
/** For each dimension of the taxonomy, the values that the strategy supports. */
|
|
415
|
+
readonly supports: S;
|
|
416
|
+
/** The default options. A record writes the options in full. */
|
|
417
|
+
readonly defaults: O;
|
|
418
|
+
/** The value is `true` when the result depends only on the input, the options and the seed. */
|
|
419
|
+
readonly deterministic: boolean;
|
|
420
|
+
}
|
|
421
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","names":[],"sources":["../src/geometry.ts","../src/tolerance.ts","../src/input.ts","../src/output.ts","../src/record.ts","../src/rules.ts","../src/turn.ts","../src/measures.ts","../src/strategy.ts"],"mappings":"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"}
|