kcl_lib/frontend/
sketch.rs

1#![allow(async_fn_in_trait)]
2
3use serde::{Deserialize, Serialize};
4
5use crate::{
6    ExecutorContext,
7    frontend::api::{
8        Expr, FileId, Number, ObjectId, ProjectId, Result, SceneGraph, SceneGraphDelta, SourceDelta, Version,
9    },
10};
11
12pub trait SketchApi {
13    /// Execute the sketch in mock mode, without changing anything. This is
14    /// useful after editing segments, and the user releases the mouse button.
15    async fn execute_mock(
16        &mut self,
17        ctx: &ExecutorContext,
18        version: Version,
19        sketch: ObjectId,
20    ) -> Result<(SourceDelta, SceneGraphDelta)>;
21
22    async fn new_sketch(
23        &mut self,
24        ctx: &ExecutorContext,
25        project: ProjectId,
26        file: FileId,
27        version: Version,
28        args: SketchCtor,
29    ) -> Result<(SourceDelta, SceneGraphDelta, ObjectId)>;
30
31    // Enters sketch mode
32    async fn edit_sketch(
33        &mut self,
34        ctx: &ExecutorContext,
35        project: ProjectId,
36        file: FileId,
37        version: Version,
38        sketch: ObjectId,
39    ) -> Result<SceneGraphDelta>;
40
41    async fn exit_sketch(&mut self, ctx: &ExecutorContext, version: Version, sketch: ObjectId) -> Result<SceneGraph>;
42
43    async fn delete_sketch(
44        &mut self,
45        ctx: &ExecutorContext,
46        version: Version,
47        sketch: ObjectId,
48    ) -> Result<(SourceDelta, SceneGraphDelta)>;
49
50    async fn add_segment(
51        &mut self,
52        ctx: &ExecutorContext,
53        version: Version,
54        sketch: ObjectId,
55        segment: SegmentCtor,
56        label: Option<String>,
57    ) -> Result<(SourceDelta, SceneGraphDelta)>;
58
59    async fn edit_segments(
60        &mut self,
61        ctx: &ExecutorContext,
62        version: Version,
63        sketch: ObjectId,
64        segments: Vec<ExistingSegmentCtor>,
65    ) -> Result<(SourceDelta, SceneGraphDelta)>;
66
67    async fn delete_objects(
68        &mut self,
69        ctx: &ExecutorContext,
70        version: Version,
71        sketch: ObjectId,
72        constraint_ids: Vec<ObjectId>,
73        segment_ids: Vec<ObjectId>,
74    ) -> Result<(SourceDelta, SceneGraphDelta)>;
75
76    async fn add_constraint(
77        &mut self,
78        ctx: &ExecutorContext,
79        version: Version,
80        sketch: ObjectId,
81        constraint: Constraint,
82    ) -> Result<(SourceDelta, SceneGraphDelta)>;
83
84    async fn chain_segment(
85        &mut self,
86        ctx: &ExecutorContext,
87        version: Version,
88        sketch: ObjectId,
89        previous_segment_end_point_id: ObjectId,
90        segment: SegmentCtor,
91        label: Option<String>,
92    ) -> Result<(SourceDelta, SceneGraphDelta)>;
93
94    async fn edit_constraint(
95        &mut self,
96        ctx: &ExecutorContext,
97        version: Version,
98        sketch: ObjectId,
99        constraint_id: ObjectId,
100        constraint: Constraint,
101    ) -> Result<(SourceDelta, SceneGraphDelta)>;
102}
103
104#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
105#[ts(export, export_to = "FrontendApi.ts", rename = "ApiSketch")]
106pub struct Sketch {
107    pub args: SketchCtor,
108    pub plane: ObjectId,
109    pub segments: Vec<ObjectId>,
110    pub constraints: Vec<ObjectId>,
111}
112
113/// Arguments for creating a new sketch. This is similar to the constructor of
114/// other kinds of objects in that it is the inputs to the sketch, not the
115/// outputs.
116#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
117#[ts(export, export_to = "FrontendApi.ts")]
118pub struct SketchCtor {
119    /// Identifier representing the plane or face to sketch on. This could be a
120    /// built-in plane like `XY`, a variable referencing a plane, or a variable
121    /// referencing a face. But currently, it may not be an arbitrary
122    /// expression. Notably, negative planes are not supported.
123    pub on: String,
124}
125
126#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
127#[ts(export, export_to = "FrontendApi.ts", rename = "ApiPoint")]
128pub struct Point {
129    pub position: Point2d<Number>,
130    pub ctor: Option<PointCtor>,
131    pub owner: Option<ObjectId>,
132    pub freedom: Freedom,
133    pub constraints: Vec<ObjectId>,
134}
135
136#[derive(Debug, Clone, Copy, PartialEq, Deserialize, Serialize, ts_rs::TS)]
137#[ts(export, export_to = "FrontendApi.ts")]
138pub enum Freedom {
139    Free,
140    Fixed,
141    Conflict,
142}
143
144impl Freedom {
145    /// Merges two Freedom values. For example, a point has a solver variable
146    /// for each dimension, x and y. If one dimension is `Free` and the other is
147    /// `Fixed`, the point overall is `Free` since it isn't fully constrained.
148    /// `Conflict` infects the most, followed by `Free`. An object must be fully
149    /// `Fixed` to be `Fixed` overall.
150    pub fn merge(self, other: Self) -> Self {
151        match (self, other) {
152            (Self::Conflict, _) | (_, Self::Conflict) => Self::Conflict,
153            (Self::Free, _) | (_, Self::Free) => Self::Free,
154            (Self::Fixed, Self::Fixed) => Self::Fixed,
155        }
156    }
157}
158
159#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
160#[ts(export, export_to = "FrontendApi.ts", rename = "ApiSegment")]
161#[serde(tag = "type")]
162pub enum Segment {
163    Point(Point),
164    Line(Line),
165    Arc(Arc),
166    Circle(Circle),
167}
168
169#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
170#[ts(export, export_to = "FrontendApi.ts")]
171pub struct ExistingSegmentCtor {
172    pub id: ObjectId,
173    pub ctor: SegmentCtor,
174}
175
176#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
177#[ts(export, export_to = "FrontendApi.ts")]
178#[serde(tag = "type")]
179pub enum SegmentCtor {
180    Point(PointCtor),
181    Line(LineCtor),
182    Arc(ArcCtor),
183    TangentArc(TangentArcCtor),
184    Circle(CircleCtor),
185}
186
187#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
188#[ts(export, export_to = "FrontendApi.ts")]
189pub struct PointCtor {
190    pub position: Point2d<Expr>,
191}
192
193#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
194#[ts(export, export_to = "FrontendApi.ts", rename = "ApiPoint2d")]
195pub struct Point2d<U: std::fmt::Debug + Clone + ts_rs::TS> {
196    pub x: U,
197    pub y: U,
198}
199
200#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
201#[ts(export, export_to = "FrontendApi.ts", rename = "ApiLine")]
202pub struct Line {
203    pub start: ObjectId,
204    pub end: ObjectId,
205    // Invariant: Line or MidPointLine
206    pub ctor: SegmentCtor,
207    // The constructor is applicable if changing the values of the constructor will change the rendering
208    // of the segment (modulo multiple valid solutions). I.e., whether the object is constrained with
209    // respect to the constructor inputs.
210    // The frontend should only display handles for the constructor inputs if the ctor is applicable.
211    // (Or because they are the (locked) start/end of the segment).
212    pub ctor_applicable: bool,
213}
214
215#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
216#[ts(export, export_to = "FrontendApi.ts")]
217pub struct LineCtor {
218    pub start: Point2d<Expr>,
219    pub end: Point2d<Expr>,
220}
221
222#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
223#[ts(export, export_to = "FrontendApi.ts", rename = "ApiStartOrEnd")]
224#[serde(tag = "type")]
225pub enum StartOrEnd<T> {
226    Start(T),
227    End(T),
228}
229
230#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
231#[ts(export, export_to = "FrontendApi.ts", rename = "ApiArc")]
232pub struct Arc {
233    pub start: ObjectId,
234    pub end: ObjectId,
235    pub center: ObjectId,
236    // Invariant: Arc or TangentArc
237    pub ctor: SegmentCtor,
238    pub ctor_applicable: bool,
239}
240
241#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
242#[ts(export, export_to = "FrontendApi.ts")]
243pub struct ArcCtor {
244    pub start: Point2d<Expr>,
245    pub end: Point2d<Expr>,
246    pub center: Point2d<Expr>,
247}
248
249#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
250#[ts(export, export_to = "FrontendApi.ts")]
251pub struct TangentArcCtor {
252    pub start: Point2d<Expr>,
253    pub end: Point2d<Expr>,
254    pub tangent: StartOrEnd<ObjectId>,
255}
256
257#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
258#[ts(export, export_to = "FrontendApi.ts", rename = "ApiCircle")]
259pub struct Circle {
260    pub start: ObjectId,
261    pub radius: Number,
262    // Invariant: Circle or ThreePointCircle
263    pub ctor: SegmentCtor,
264    pub ctor_applicable: bool,
265}
266
267#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
268#[ts(export, export_to = "FrontendApi.ts")]
269pub struct CircleCtor {
270    pub center: Point2d<Expr>,
271    pub radius: Expr,
272}
273
274#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
275#[ts(export, export_to = "FrontendApi.ts", rename = "ApiConstraint")]
276#[serde(tag = "type")]
277pub enum Constraint {
278    Coincident(Coincident),
279    Distance(Distance),
280    Horizontal(Horizontal),
281    LinesEqualLength(LinesEqualLength),
282    Parallel(Parallel),
283    Perpendicular(Perpendicular),
284    Vertical(Vertical),
285}
286
287#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
288#[ts(export, export_to = "FrontendApi.ts")]
289pub struct Coincident {
290    pub segments: Vec<ObjectId>,
291}
292
293#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
294#[ts(export, export_to = "FrontendApi.ts")]
295pub struct Distance {
296    pub points: Vec<ObjectId>,
297    pub distance: Number,
298}
299
300#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
301#[ts(export, export_to = "FrontendApi.ts")]
302pub struct Horizontal {
303    pub line: ObjectId,
304}
305
306#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
307#[ts(export, export_to = "FrontendApi.ts")]
308pub struct LinesEqualLength {
309    pub lines: Vec<ObjectId>,
310}
311
312#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
313#[ts(export, export_to = "FrontendApi.ts")]
314pub struct Vertical {
315    pub line: ObjectId,
316}
317
318#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
319#[ts(export, export_to = "FrontendApi.ts", optional_fields)]
320pub struct Parallel {
321    pub lines: Vec<ObjectId>,
322}
323
324#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, ts_rs::TS)]
325#[ts(export, export_to = "FrontendApi.ts", optional_fields)]
326pub struct Perpendicular {
327    pub lines: Vec<ObjectId>,
328}
kcl_lib/frontend/sketch.rs

kcl_lib/frontend/
sketch.rs
