Skip to main content

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}