kcl_lib/frontend/
sketch.rs

1#![allow(async_fn_in_trait)]
2
3use serde::Deserialize;
4use serde::Serialize;
5
6use crate::ExecutorContext;
7use crate::front::Plane;
8use crate::frontend::api::Expr;
9use crate::frontend::api::FileId;
10use crate::frontend::api::Number;
11use crate::frontend::api::ObjectId;
12use crate::frontend::api::ProjectId;
13use crate::frontend::api::Result;
14use crate::frontend::api::SceneGraph;
15use crate::frontend::api::SceneGraphDelta;
16use crate::frontend::api::SourceDelta;
17use crate::frontend::api::Version;
18
19/// Information about a newly created segment for batch operations
20#[derive(Debug, Clone)]
21pub struct NewSegmentInfo {
22    pub segment_id: ObjectId,
23    pub start_point_id: ObjectId,
24    pub end_point_id: ObjectId,
25    pub center_point_id: Option<ObjectId>,
26}
27
28pub trait SketchApi {
29    /// Execute the sketch in mock mode, without changing anything. This is
30    /// useful after editing segments, and the user releases the mouse button.
31    async fn execute_mock(
32        &mut self,
33        ctx: &ExecutorContext,
34        version: Version,
35        sketch: ObjectId,
36    ) -> Result<(SourceDelta, SceneGraphDelta)>;
37
38    async fn new_sketch(
39        &mut self,
40        ctx: &ExecutorContext,
41        project: ProjectId,
42        file: FileId,
43        version: Version,
44        args: SketchCtor,
45    ) -> Result<(SourceDelta, SceneGraphDelta, ObjectId)>;
46
47    // Enters sketch mode
48    async fn edit_sketch(
49        &mut self,
50        ctx: &ExecutorContext,
51        project: ProjectId,
52        file: FileId,
53        version: Version,
54        sketch: ObjectId,
55    ) -> Result<SceneGraphDelta>;
56
57    async fn exit_sketch(&mut self, ctx: &ExecutorContext, version: Version, sketch: ObjectId) -> Result<SceneGraph>;
58
59    async fn delete_sketch(
60        &mut self,
61        ctx: &ExecutorContext,
62        version: Version,
63        sketch: ObjectId,
64    ) -> Result<(SourceDelta, SceneGraphDelta)>;
65
66    async fn add_segment(
67        &mut self,
68        ctx: &ExecutorContext,
69        version: Version,
70        sketch: ObjectId,
71        segment: SegmentCtor,
72        label: Option<String>,
73    ) -> Result<(SourceDelta, SceneGraphDelta)>;
74
75    async fn edit_segments(
76        &mut self,
77        ctx: &ExecutorContext,
78        version: Version,
79        sketch: ObjectId,
80        segments: Vec<ExistingSegmentCtor>,
81    ) -> Result<(SourceDelta, SceneGraphDelta)>;
82
83    async fn delete_objects(
84        &mut self,
85        ctx: &ExecutorContext,
86        version: Version,
87        sketch: ObjectId,
88        constraint_ids: Vec<ObjectId>,
89        segment_ids: Vec<ObjectId>,
90    ) -> Result<(SourceDelta, SceneGraphDelta)>;
91
92    async fn add_constraint(
93        &mut self,
94        ctx: &ExecutorContext,
95        version: Version,
96        sketch: ObjectId,
97        constraint: Constraint,
98    ) -> Result<(SourceDelta, SceneGraphDelta)>;
99
100    async fn chain_segment(
101        &mut self,
102        ctx: &ExecutorContext,
103        version: Version,
104        sketch: ObjectId,
105        previous_segment_end_point_id: ObjectId,
106        segment: SegmentCtor,
107        label: Option<String>,
108    ) -> Result<(SourceDelta, SceneGraphDelta)>;
109
110    async fn edit_constraint(
111        &mut self,
112        ctx: &ExecutorContext,
113        version: Version,
114        sketch: ObjectId,
115        constraint_id: ObjectId,
116        value_expression: String,
117    ) -> Result<(SourceDelta, SceneGraphDelta)>;
118
119    /// Batch operations for split segment: edit segments, add constraints, delete objects.
120    /// All operations are applied to a single AST and execute_after_edit is called once at the end.
121    /// new_segment_info contains the IDs from the segment(s) added in a previous step.
122    #[allow(clippy::too_many_arguments)]
123    async fn batch_split_segment_operations(
124        &mut self,
125        ctx: &ExecutorContext,
126        version: Version,
127        sketch: ObjectId,
128        edit_segments: Vec<ExistingSegmentCtor>,
129        add_constraints: Vec<Constraint>,
130        delete_constraint_ids: Vec<ObjectId>,
131        new_segment_info: NewSegmentInfo,
132    ) -> Result<(SourceDelta, SceneGraphDelta)>;
133
134    /// Batch operations for tail-cut trim: edit a segment, add coincident constraints,
135    /// delete constraints, and execute once.
136    async fn batch_tail_cut_operations(
137        &mut self,
138        ctx: &ExecutorContext,
139        version: Version,
140        sketch: ObjectId,
141        edit_segments: Vec<ExistingSegmentCtor>,
142        add_constraints: Vec<Constraint>,
143        delete_constraint_ids: Vec<ObjectId>,
144    ) -> Result<(SourceDelta, SceneGraphDelta)>;
145}
146
147#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
148#[ts(export, export_to = "FrontendApi.ts", rename = "ApiSketch")]
149pub struct Sketch {
150    pub args: SketchCtor,
151    pub plane: ObjectId,
152    pub segments: Vec<ObjectId>,
153    pub constraints: Vec<ObjectId>,
154}
155
156/// Arguments for creating a new sketch. This is similar to the constructor of
157/// other kinds of objects in that it is the inputs to the sketch, not the
158/// outputs.
159#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
160#[ts(export, export_to = "FrontendApi.ts")]
161pub struct SketchCtor {
162    /// The sketch surface.
163    pub on: Plane,
164}
165
166#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
167#[ts(export, export_to = "FrontendApi.ts", rename = "ApiPoint")]
168pub struct Point {
169    pub position: Point2d<Number>,
170    pub ctor: Option<PointCtor>,
171    pub owner: Option<ObjectId>,
172    pub freedom: Freedom,
173    pub constraints: Vec<ObjectId>,
174}
175
176#[derive(Debug, Clone, Copy, PartialEq, Deserialize, Serialize, ts_rs::TS)]
177#[ts(export, export_to = "FrontendApi.ts")]
178pub enum Freedom {
179    Free,
180    Fixed,
181    Conflict,
182}
183
184impl Freedom {
185    /// Merges two Freedom values. For example, a point has a solver variable
186    /// for each dimension, x and y. If one dimension is `Free` and the other is
187    /// `Fixed`, the point overall is `Free` since it isn't fully constrained.
188    /// `Conflict` infects the most, followed by `Free`. An object must be fully
189    /// `Fixed` to be `Fixed` overall.
190    pub fn merge(self, other: Self) -> Self {
191        match (self, other) {
192            (Self::Conflict, _) | (_, Self::Conflict) => Self::Conflict,
193            (Self::Free, _) | (_, Self::Free) => Self::Free,
194            (Self::Fixed, Self::Fixed) => Self::Fixed,
195        }
196    }
197}
198
199#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
200#[ts(export, export_to = "FrontendApi.ts", rename = "ApiSegment")]
201#[serde(tag = "type")]
202pub enum Segment {
203    Point(Point),
204    Line(Line),
205    Arc(Arc),
206    Circle(Circle),
207}
208
209#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
210#[ts(export, export_to = "FrontendApi.ts")]
211pub struct ExistingSegmentCtor {
212    pub id: ObjectId,
213    pub ctor: SegmentCtor,
214}
215
216#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
217#[ts(export, export_to = "FrontendApi.ts")]
218#[serde(tag = "type")]
219pub enum SegmentCtor {
220    Point(PointCtor),
221    Line(LineCtor),
222    Arc(ArcCtor),
223    Circle(CircleCtor),
224}
225
226#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
227#[ts(export, export_to = "FrontendApi.ts")]
228pub struct PointCtor {
229    pub position: Point2d<Expr>,
230}
231
232#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
233#[ts(export, export_to = "FrontendApi.ts", rename = "ApiPoint2d")]
234pub struct Point2d<U: std::fmt::Debug + Clone + ts_rs::TS> {
235    pub x: U,
236    pub y: U,
237}
238
239#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
240#[ts(export, export_to = "FrontendApi.ts", rename = "ApiLine")]
241pub struct Line {
242    pub start: ObjectId,
243    pub end: ObjectId,
244    // Invariant: Line or MidPointLine
245    pub ctor: SegmentCtor,
246    // The constructor is applicable if changing the values of the constructor will change the rendering
247    // of the segment (modulo multiple valid solutions). I.e., whether the object is constrained with
248    // respect to the constructor inputs.
249    // The frontend should only display handles for the constructor inputs if the ctor is applicable.
250    // (Or because they are the (locked) start/end of the segment).
251    pub ctor_applicable: bool,
252    pub construction: bool,
253}
254
255#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
256#[ts(export, export_to = "FrontendApi.ts")]
257pub struct LineCtor {
258    pub start: Point2d<Expr>,
259    pub end: Point2d<Expr>,
260    #[serde(skip_serializing_if = "Option::is_none")]
261    #[ts(optional)]
262    pub construction: Option<bool>,
263}
264
265#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
266#[ts(export, export_to = "FrontendApi.ts", rename = "ApiStartOrEnd")]
267#[serde(tag = "type")]
268pub enum StartOrEnd<T> {
269    Start(T),
270    End(T),
271}
272
273#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
274#[ts(export, export_to = "FrontendApi.ts", rename = "ApiArc")]
275pub struct Arc {
276    pub start: ObjectId,
277    pub end: ObjectId,
278    pub center: ObjectId,
279    // Invariant: Arc
280    pub ctor: SegmentCtor,
281    pub ctor_applicable: bool,
282    pub construction: bool,
283}
284
285#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
286#[ts(export, export_to = "FrontendApi.ts")]
287pub struct ArcCtor {
288    pub start: Point2d<Expr>,
289    pub end: Point2d<Expr>,
290    pub center: Point2d<Expr>,
291    #[serde(skip_serializing_if = "Option::is_none")]
292    #[ts(optional)]
293    pub construction: Option<bool>,
294}
295
296#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
297#[ts(export, export_to = "FrontendApi.ts", rename = "ApiCircle")]
298pub struct Circle {
299    pub start: ObjectId,
300    pub center: ObjectId,
301    // Invariant: Circle
302    pub ctor: SegmentCtor,
303    pub ctor_applicable: bool,
304    pub construction: bool,
305}
306
307#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
308#[ts(export, export_to = "FrontendApi.ts")]
309pub struct CircleCtor {
310    pub start: Point2d<Expr>,
311    pub center: Point2d<Expr>,
312    #[serde(skip_serializing_if = "Option::is_none")]
313    #[ts(optional)]
314    pub construction: Option<bool>,
315}
316
317#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
318#[ts(export, export_to = "FrontendApi.ts", rename = "ApiConstraint")]
319#[serde(tag = "type")]
320pub enum Constraint {
321    Coincident(Coincident),
322    Distance(Distance),
323    Angle(Angle),
324    Diameter(Diameter),
325    HorizontalDistance(Distance),
326    VerticalDistance(Distance),
327    Horizontal(Horizontal),
328    LinesEqualLength(LinesEqualLength),
329    Parallel(Parallel),
330    Perpendicular(Perpendicular),
331    Radius(Radius),
332    Tangent(Tangent),
333    Vertical(Vertical),
334}
335
336#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
337#[ts(export, export_to = "FrontendApi.ts")]
338pub struct Coincident {
339    pub segments: Vec<ObjectId>,
340}
341
342#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
343#[ts(export, export_to = "FrontendApi.ts")]
344pub struct Distance {
345    pub points: Vec<ObjectId>,
346    pub distance: Number,
347    pub source: ConstraintSource,
348}
349
350#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
351#[ts(export, export_to = "FrontendApi.ts")]
352pub struct Angle {
353    pub lines: Vec<ObjectId>,
354    pub angle: Number,
355    pub source: ConstraintSource,
356}
357
358#[derive(Debug, Clone, Default, PartialEq, Deserialize, Serialize, ts_rs::TS)]
359#[ts(export, export_to = "FrontendApi.ts")]
360pub struct ConstraintSource {
361    pub expr: String,
362    pub is_literal: bool,
363}
364
365#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
366#[ts(export, export_to = "FrontendApi.ts")]
367pub struct Radius {
368    pub arc: ObjectId,
369    pub radius: Number,
370    #[serde(default)]
371    pub source: ConstraintSource,
372}
373
374#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
375#[ts(export, export_to = "FrontendApi.ts")]
376pub struct Diameter {
377    pub arc: ObjectId,
378    pub diameter: Number,
379    #[serde(default)]
380    pub source: ConstraintSource,
381}
382
383#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
384#[ts(export, export_to = "FrontendApi.ts")]
385pub struct Horizontal {
386    pub line: ObjectId,
387}
388
389#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
390#[ts(export, export_to = "FrontendApi.ts")]
391pub struct LinesEqualLength {
392    pub lines: Vec<ObjectId>,
393}
394
395#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
396#[ts(export, export_to = "FrontendApi.ts")]
397pub struct Vertical {
398    pub line: ObjectId,
399}
400
401#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
402#[ts(export, export_to = "FrontendApi.ts", optional_fields)]
403pub struct Parallel {
404    pub lines: Vec<ObjectId>,
405}
406
407#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
408#[ts(export, export_to = "FrontendApi.ts", optional_fields)]
409pub struct Perpendicular {
410    pub lines: Vec<ObjectId>,
411}
412
413#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
414#[ts(export, export_to = "FrontendApi.ts", optional_fields)]
415pub struct Tangent {
416    pub input: Vec<ObjectId>,
417}
kcl_lib/frontend/sketch.rs

kcl_lib/frontend/
sketch.rs
