kernel_api/query.rs
1//! Questions asked of a built solid and their answers: projected edges,
2//! sections, drawings, probes, holes, frames along paths and construction
3//! geometry.
4
5use serde::{Deserialize, Serialize};
6
7use crate::*;
8
9/// An edge of a solid projected onto a plane, in the plane's own 2D
10/// coordinates (along its `x_axis` and `y_axis`).
11#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
12pub enum ProjectedEdge {
13 /// The edge runs along the plane's normal, so it projects to a point.
14 Point([f64; 2]),
15 /// A segment.
16 Line { start: [f64; 2], end: [f64; 2] },
17 /// A circle or circular arc, `centre + radius (cos t, sin t)`, turning
18 /// counter-clockwise from `range.0` to `range.1`; a full circle when the
19 /// range spans a turn.
20 Circle {
21 centre: [f64; 2],
22 radius: f64,
23 range: (f64, f64),
24 },
25 /// An ellipse or elliptical arc, `centre + major cos t + minor sin t`,
26 /// `minor` the major axis turned a quarter counter-clockwise and scaled
27 /// by `ratio`, from `range.0` to `range.1`.
28 Ellipse {
29 centre: [f64; 2],
30 major: [f64; 2],
31 ratio: f64,
32 range: (f64, f64),
33 },
34 /// A piece of a parabola, `vertex + axis s² / (4 focal) + side s`,
35 /// `axis` a unit vector the way it opens and `side` it turned a quarter
36 /// counter-clockwise, from `s = range.0` to `range.1`.
37 Parabola {
38 vertex: [f64; 2],
39 axis: [f64; 2],
40 focal: f64,
41 range: (f64, f64),
42 },
43 /// A piece of one branch of a hyperbola, `centre + major cosh s +
44 /// minor sinh s`, `major` (centre to the branch's vertex) square to
45 /// `minor`, from `s = range.0` to `range.1`.
46 Hyperbola {
47 centre: [f64; 2],
48 major: [f64; 2],
49 minor: [f64; 2],
50 range: (f64, f64),
51 },
52 /// A B-spline, as the kernel projects it: `degree`, its clamped
53 /// `knots` (`control_points + degree + 1` of them), and a weight per
54 /// control point when rational (empty when every weight is one).
55 Spline {
56 degree: u32,
57 knots: Vec<f64>,
58 control_points: Vec<[f64; 2]>,
59 weights: Vec<f64>,
60 },
61 /// Any other curve, as points along it: exact at each point, straight
62 /// between.
63 Polyline(Vec<[f64; 2]>),
64}
65
66/// One curve where a plane crosses a shape.
67#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
68pub struct SectionCurve {
69 /// The exact curve, in the plane's own 2D coordinates.
70 pub curve: ProjectedEdge,
71 /// Points along it, in the shape's own frame, in the order its run
72 /// goes.
73 pub points: Vec<[f64; 3]>,
74 /// The run goes against the way `curve` runs.
75 #[serde(default)]
76 pub reversed: bool,
77}
78
79/// Curves where a plane crosses a shape, end to end: a closed loop round
80/// a solid's cut, or an open run where a sheet's edge stops it.
81#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
82pub struct SectionRun {
83 pub curves: Vec<SectionCurve>,
84 pub closed: bool,
85}
86
87/// One edge of a face's boundary loop.
88#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
89pub struct LoopEdge {
90 /// Points along it, in the shape's own frame, in the order the loop
91 /// walks it.
92 pub points: Vec<[f64; 3]>,
93 /// The edge a round face meets itself along: it turns up twice in
94 /// its loop, once each way.
95 #[serde(default)]
96 pub seam: bool,
97}
98
99/// The curves and texts of a 2D drawing file, in the drawing's own
100/// coordinates.
101#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
102pub struct Drawing2d {
103 /// Millimetres per drawing unit, when the drawing names its unit.
104 pub unit_mm: Option<f64>,
105 /// Every curve, in the order the file has them.
106 pub curves: Vec<DrawingCurve>,
107 /// Every line of text, in the order the file has them.
108 #[serde(default)]
109 pub texts: Vec<DrawingText>,
110}
111
112/// One curve of a drawing, and whether the drawing marks it hidden
113/// (a hidden layer, or a dashed line type).
114#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
115pub struct DrawingCurve {
116 pub hidden: bool,
117 pub shape: DrawingShape,
118 /// The layer it is drawn on; empty for the drawing's default layer.
119 #[serde(default)]
120 pub layer: String,
121}
122
123/// A line of text on a drawing.
124#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
125pub struct DrawingText {
126 /// The start of its baseline.
127 pub at: [f64; 2],
128 /// The height of its capitals.
129 pub height: f64,
130 /// Its baseline's direction, radians counter-clockwise from x.
131 pub angle: f64,
132 pub text: String,
133 /// The layer it is written on; empty for the drawing's default layer.
134 #[serde(default)]
135 pub layer: String,
136}
137
138/// The kinds of curve a drawing carries. Angles are radians, arcs run
139/// counter-clockwise.
140#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
141pub enum DrawingShape {
142 /// Points in order, each segment a line, or an arc where the bulge of
143 /// the segment starting at that point (the tangent of a quarter of its
144 /// included angle, positive counter-clockwise) is not zero. `bulges`
145 /// is as long as `points`, or empty for straight segments only.
146 Polyline {
147 points: Vec<[f64; 2]>,
148 bulges: Vec<f64>,
149 closed: bool,
150 },
151 Arc {
152 centre: [f64; 2],
153 radius: f64,
154 start_angle: f64,
155 end_angle: f64,
156 },
157 Circle {
158 centre: [f64; 2],
159 radius: f64,
160 },
161 /// Points `centre + major cos t + ratio perp(major) sin t` for `t`
162 /// from `start_param` to `end_param`; the whole ellipse when those span
163 /// a full turn.
164 Ellipse {
165 centre: [f64; 2],
166 major: [f64; 2],
167 ratio: f64,
168 start_param: f64,
169 end_param: f64,
170 },
171 /// A spline, as points along the exact curve.
172 Spline {
173 points: Vec<[f64; 2]>,
174 closed: bool,
175 },
176}
177
178/// A connected volume where a scan and a solid differ the same way, in the
179/// solid's frame.
180#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
181pub struct VolumeRegion {
182 /// In the solid and out of the scan; else in the scan and out of the
183 /// solid.
184 pub missing: bool,
185 /// In mm³.
186 pub volume: f64,
187 /// How far apart the two surfaces stand across it, in mm.
188 pub depth: f64,
189 /// Wider than twice its depth: a face standing off, rather than a boss
190 /// or a pocket.
191 pub layer: bool,
192 pub min: [f64; 3],
193 pub max: [f64; 3],
194 /// It rests on a hole of the scan, or is too shallow for its volume to
195 /// be read.
196 pub unsure: bool,
197}
198
199/// The solid two shapes share: its volume, its centre and its mesh, in
200/// the first shape's frame.
201#[derive(Debug, Clone)]
202pub struct Overlap {
203 pub volume_mm3: f64,
204 pub centre_mm: [f64; 3],
205 pub mesh: TriMesh,
206}
207
208/// How near two shapes come: the distance between their boundaries and a
209/// nearest point on each, in the first shape's frame. Zero where the
210/// boundaries touch or cross.
211#[derive(Debug, Clone, Copy, PartialEq)]
212pub struct Gap {
213 pub distance_mm: f64,
214 pub on_a: [f64; 3],
215 pub on_b: [f64; 3],
216}
217
218/// A stretch of a region's medial axis, in the profile plane's own 2D
219/// coordinates: points along one branch with the clearance at each, the
220/// radius of the largest disc centred there that stays inside the region.
221#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
222pub struct MedialPath {
223 pub points: Vec<[f64; 2]>,
224 /// One per point, in millimetres.
225 pub clearance: Vec<f64>,
226 /// Whether the first and the last point end the axis on the boundary
227 /// (a corner, or a rounded end's centre) rather than meet other
228 /// branches: towards such an end the clearance falls without the
229 /// region getting thinner.
230 pub boundary_ends: [bool; 2],
231}
232
233/// Where a region is narrowest, and how narrow: the smallest clearance on
234/// its medial axis away from the branch ends at its corners (where the
235/// clearance runs down to nothing without the region getting any thinner).
236/// The wall there is twice the clearance.
237#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
238pub struct Narrowest {
239 pub at: [f64; 2],
240 pub clearance: f64,
241}
242
243/// The medial axis of one region of a profile: an outer wire and its holes.
244#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
245pub struct MedialRegion {
246 /// The profile's wires that bound it, by index, the outer one first.
247 pub wires: Vec<usize>,
248 pub paths: Vec<MedialPath>,
249 /// `None` only when the axis has no place away from the corners.
250 pub narrowest: Option<Narrowest>,
251}
252
253/// A picked face: its name, and a point on it with its outward normal.
254/// A rebuild finds the face by its name, the point choosing among the
255/// pieces of a face that split; without a name (or when no face bears it
256/// any more), the face nearest the point.
257#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize)]
258pub struct FaceProbe {
259 pub point: [f64; 3],
260 pub normal: [f64; 3],
261 #[serde(default)]
262 pub name: TopoName,
263}
264
265/// A question about a solid a reference stands on, named geometrically so
266/// it can be asked again of the solid a rebuild makes.
267#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
268pub enum ShapeProbe {
269 /// The face named `name`, else the face nearest `point` (among faces
270 /// as near, the one whose outward normal agrees best with `normal`),
271 /// and where on it `point` falls.
272 Face {
273 point: [f64; 3],
274 normal: [f64; 3],
275 #[serde(default)]
276 name: TopoName,
277 },
278 /// The edge between faces named `faces`, else the edge nearest `point`
279 /// that runs along `direction` there (a zero direction takes the
280 /// nearest edge whichever way it runs).
281 Edge {
282 point: [f64; 3],
283 direction: [f64; 3],
284 #[serde(default)]
285 faces: [TopoName; 2],
286 /// A share along the edge from its start (0 to 1) whose point and
287 /// tangent the answer also gives.
288 #[serde(default, skip_serializing_if = "Option::is_none")]
289 along: Option<f64>,
290 },
291 /// The solid's centre of mass and principal axes of inertia.
292 Mass,
293}
294
295/// What a solid answers to a [`ShapeProbe`], in the solid's own frame.
296#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
297pub enum ProbeAnswer {
298 /// The point of the face nearest the probe's, the face's outward normal
299 /// there, and the face's surface.
300 Face {
301 point: [f64; 3],
302 normal: [f64; 3],
303 surface: FaceSurface,
304 },
305 /// The point of the edge nearest the probe's and the way the edge runs
306 /// there, its two ends and its middle (halfway along its parameter,
307 /// which is halfway along an arc), and the circle it runs round when
308 /// it is a circle or an arc of one.
309 Edge {
310 point: [f64; 3],
311 direction: [f64; 3],
312 start: [f64; 3],
313 end: [f64; 3],
314 middle: [f64; 3],
315 circle: Option<ProbedCircle>,
316 /// The point and tangent the probe's share along gives, when it
317 /// asked for one.
318 #[serde(default, skip_serializing_if = "Option::is_none")]
319 along: Option<([f64; 3], [f64; 3])>,
320 },
321 /// The centre of mass and the principal axes of inertia, the axis of
322 /// the smallest moment first.
323 Mass {
324 centre: [f64; 3],
325 axes: [[f64; 3]; 3],
326 },
327}
328
329/// The circle an edge runs round.
330#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
331pub struct ProbedCircle {
332 pub centre: [f64; 3],
333 pub normal: [f64; 3],
334 pub radius: f64,
335}
336
337/// A probe asked part way through a solid-op chain: of the solid the first
338/// `after_op` ops make.
339#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
340pub struct ChainProbe {
341 pub after_op: usize,
342 pub probe: ShapeProbe,
343}
344
345/// A solid's edge projected onto a plane, or the curves where one of its
346/// faces crosses the plane: what a sketch takes from the solid it stands
347/// on, asked again of the solid a rebuild makes.
348#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize)]
349pub struct ProjectionProbe {
350 /// A point on the edge (on the face, for a section), in the solid's
351 /// own frame.
352 pub point: [f64; 3],
353 /// The names of the two faces the edge runs between: the edge is found
354 /// by them first, `point` choosing among its pieces, and by `point`
355 /// alone without them or when no edge runs between them.
356 #[serde(default)]
357 pub faces: [TopoName; 2],
358 /// The face nearest `point` is cut by the plane, in place of an edge
359 /// projected onto it.
360 #[serde(default)]
361 pub section: bool,
362 /// The plane, in the solid's own frame: the curves come in its own 2D
363 /// coordinates.
364 pub plane: ProfilePlane,
365}
366
367/// A projection asked part way through a solid-op chain: of the solid the
368/// first `after_op` ops make.
369#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
370pub struct ChainProjection {
371 pub after_op: usize,
372 pub probe: ProjectionProbe,
373}
374
375/// The centre line of a pipe-like solid between two of its faces.
376#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
377pub struct CentreLine {
378 /// Points along it, from the first face to the second, in the shape's
379 /// frame.
380 pub points: Vec<[f64; 3]>,
381 /// Its length, in millimetres.
382 pub length: f64,
383 /// The largest distance measured from the centroid of a section cut
384 /// square to the line to the line itself.
385 pub deviation: f64,
386 /// It is one straight segment.
387 pub straight: bool,
388}
389
390/// A round hole found in a solid: a full bore, open at one end (blind)
391/// or both (through), closed by a flat bottom or a drill point.
392#[derive(Debug, Clone, PartialEq)]
393pub struct RecognizedHole {
394 /// The centre of its opening, on its axis.
395 pub entry: [f64; 3],
396 /// Along its axis, into the material.
397 pub direction: [f64; 3],
398 pub diameter: f64,
399 /// The bore's length from the opening, not counting a drill point.
400 pub depth: f64,
401 /// Open at both ends.
402 pub through: bool,
403 /// The included angle of the cone that ends a blind hole, degrees;
404 /// `None` for a flat bottom or a through hole.
405 pub drill_point_deg: Option<f64>,
406 /// A point on each face the hole is made of (its bore, its bottom),
407 /// with that face's outward normal.
408 pub faces: Vec<([f64; 3], [f64; 3])>,
409}
410
411/// Geometry questions a workbench may ask while it runs, answered by the
412/// kernel at once. Shapes arrive as the snapshot bytes the document keeps.
413/// How two faces of a shape meet across an edge they share: a point
414/// halfway along it, in the shape's own frame, the largest gap between the
415/// edge and the faces, the largest angle between the faces' normals along
416/// it (zero where they meet tangent), and the largest difference in how
417/// sharply they bend square to it (1/mm; zero where they meet curvature
418/// continuous, `None` where it could not be read).
419#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
420pub struct EdgeContinuity {
421 pub point: [f64; 3],
422 pub gap: f64,
423 pub angle_deg: f64,
424 #[serde(default)]
425 pub curvature: Option<f64>,
426}
427
428/// A face of a shape, named by a point inside it, and points on it, each
429/// with the normal its curvature is signed against.
430pub type FacePoints = ([f64; 3], Vec<([f64; 3], [f64; 3])>);
431
432/// A point on a path and the way the path runs there.
433#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
434pub struct PathFrame {
435 pub point: [f64; 3],
436 /// A unit vector along the path, the way it is walked.
437 pub tangent: [f64; 3],
438}
439
440/// Stations along a path, by arc length: what is repeated along a curve
441/// stands at them.
442#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
443pub struct PathFrames {
444 /// The path's whole length, mm.
445 pub length: f64,
446 /// Whether the path ends where it starts.
447 pub closed: bool,
448 /// One per station asked for, in the order asked.
449 pub frames: Vec<PathFrame>,
450}
451
452/// Reference geometry with no topology: what STEP and IGES files carry as
453/// construction geometry beside (or instead of) a part's solid.
454#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
455pub enum ConstructionShape {
456 Point([f64; 3]),
457 /// An axis placement: `z` its axis, `x` its reference direction.
458 Axis {
459 origin: [f64; 3],
460 z: [f64; 3],
461 x: [f64; 3],
462 },
463 /// Straight pieces through the points; closed back to the first.
464 Polyline {
465 points: Vec<[f64; 3]>,
466 closed: bool,
467 },
468 Circle {
469 centre: [f64; 3],
470 normal: [f64; 3],
471 radius: f64,
472 },
473 /// A plane over `u` along `x_axis` and `v` along `normal × x_axis`
474 /// from `origin`.
475 Plane {
476 origin: [f64; 3],
477 normal: [f64; 3],
478 x_axis: [f64; 3],
479 u: [f64; 2],
480 v: [f64; 2],
481 },
482}
483
484/// A named item of construction geometry.
485#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
486pub struct ConstructionItem {
487 pub name: String,
488 pub shape: ConstructionShape,
489}
490
491/// Construction geometry written as IGES, with any omitted geometry or names reported.
492#[derive(Debug, Clone, Default)]
493pub struct IgesExport {
494 pub text: String,
495 pub warnings: Vec<String>,
496}