indicatrix-editor 0.7.2

GUI-free faceting-design editor logic shared by the desktop editor and the wasm web app: the EditorSession (design, undo/redo with caller-supplied coalescing timestamps, selection, dirty tracking), tier/preform/material form parsing, plain-struct view models, the cutting sheet, Retarget, the guided walkthrough and the solve policy. No GUI toolkit, no threads, no clock, no filesystem.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
//! The Solid viewport: picking facets, the drag handles, Slice, the Diagram view and the Cut
//! slider.

#![allow(
    clippy::too_many_lines,
    reason = "a tutorial is its step text; splitting it would only scatter the wording"
)]

use super::{
    VIEWPORT, VIEWPORT_TABLE, angle_moved, check, depth_moved, event, index_moved, rich_untouched,
};
use crate::guide::{
    Goal, Guide, GuideCategory, GuideStep, StartingState,
    tutorials::viewing_events::{
        CUT_SLIDER_FINISHED, CUT_SLIDER_ROUGH, CUT_SLIDER_STEP, DIAGRAM_PANEL_ENLARGED,
        FACET_PICKED, SLICE_CUTS_STONE, SLICE_DRAWN, SLICE_FLIPPED, SLICE_STARTED,
        SLICE_SYMMETRIC_TOGGLED, SNAP_TOGGLED, TIER_SELECTED,
    },
};

/// The lessons of this file, in browser order.
pub fn guides() -> Vec<Guide> {
    vec![
        solid_picking(),
        drag_handles(),
        slice(),
        diagram(),
        cut_slider(),
    ]
}

/// The number of tiers the Rich Teaching Design starts with; Keep in the Slice lesson makes one
/// more.
const START_TIERS: usize = 4;

fn solid_picking() -> Guide {
    Guide::new(
        "viewing-solid-picking",
        "Picking facets in the Solid view",
        "Point at a facet to read its tier, angle and index, then click it to select its whole tier.",
        GuideCategory::Viewing,
    )
    .starting(StartingState::Template(5))
    .step(
        GuideStep::new(
            "The Solid view",
            "The Edit tab shows your design as a flat-shaded stone you can point at.",
        )
        .actions([
            "Click the Edit tab above the picture, if it is not open.",
            "The buttons above the stone choose the view: Solid, Path-traced, Both and Diagram.",
            "In Solid, Path-traced and Both, drag to turn the stone and scroll to zoom.",
        ])
        .why("The Solid view is quick and independent of the light tracer, so it can follow almost every edit.")
        .highlight("view_modes")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Hover over a facet",
            "Pointing at a facet, without clicking, tells you what it is.",
        )
        .actions([
            "Move the pointer over the stone.",
            "A small panel in the lower-left corner names the tier, its angle, its index, its block (Crown, Pavilion or Girdle) and its margin over the critical angle.",
        ])
        .why("A positive margin means the facet stays clear of the critical angle for the design's refractive index.")
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Click a facet",
            "Clicking a facet selects the tier it belongs to.",
        )
        .actions(["Click one of the facets in the ring around the table."])
        .check("The tier's row is highlighted in the tier list and every facet of that tier is tinted on the stone.")
        .why("You picked one facet, but a tier is a whole ring of them, so the whole ring is selected.")
        .goal(event(FACET_PICKED), "A click on a facet")
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Pick in another view",
            "Picking works in every view that shows the stone, not only in Solid.",
        )
        .actions(["Click Both above the stone."])
        .check("Both is lit, and the solid's facet edges are drawn over the traced picture.")
        .why("Both puts the Solid view's facet edges on top of the path-traced picture, so you can see which edge belongs to which highlight.")
        .goal(Goal::ViewMode(2), "The Both view")
        .highlight("view_modes")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Click a different tier",
            "Selecting another tier moves the tint to its facets.",
        )
        .actions(["Click a facet that belongs to a different tier."])
        .check("A different row is highlighted in the tier list.")
        .goal(event(FACET_PICKED), "A click on a facet")
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Pick from the list instead",
            "Picking also works the other way round: choose the tier first and see where it is.",
        )
        .actions(["Click a row in the tier list."])
        .check("The facets of that tier are tinted on the stone.")
        .why("This is the quickest way to find out which facets a row stands for.")
        .goal(event(TIER_SELECTED), "A tier picked in the list")
        .highlight("tier_table")
        .allow(VIEWPORT_TABLE),
    )
    .step(
        GuideStep::new(
            "Done",
            "You can read any facet by hovering and select its tier by clicking, in the picture or in the list.",
        )
        .actions(["The drag handles tutorial shows how to change the selected tier by dragging."])
        .why("Every control is unlocked again."),
    )
}

fn drag_handles() -> Guide {
    Guide::new(
        "viewing-drag-handles",
        "Drag handles",
        "Change a tier by dragging its angle (A), depth (D) and index (I) handles on the stone.",
        GuideCategory::Viewing,
    )
    .starting(StartingState::Template(5))
    .step(
        GuideStep::new(
            "Select a tier",
            "Three handles grow out of the selected tier's facet, so start by selecting one.",
        )
        .actions([
            "Click the Edit tab above the picture, if it is not open.",
            "Click a facet of the ring around the table (Crown Main).",
        ])
        .check("Three handles appear on the facet: A (a cyan circle), D (a blue square) and I (an amber diamond).")
        .why("The handles need a solved design. A handle drags the whole tier, not only the facet you grabbed.")
        .goal(event(TIER_SELECTED), "A selected tier")
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Drag the angle handle",
            "A tilts the tier: steeper one way, shallower the other.",
        )
        .actions([
            "Press on A, the cyan circle, and drag it along its line.",
            "Watch the line under the toolbar: it names the tier and its new angle while you drag.",
        ])
        .check("The tier list shows a new angle for the tier.")
        .why("The angle stays on its own side of zero, so a crown tier stops at 0 degrees instead of turning into a pavilion tier.")
        .goal(check("a tier is at another angle", angle_moved), "A tier at a new angle")
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "One drag, one undo",
            "However long you dragged, the whole gesture is a single step in the undo history.",
        )
        .actions(["Press Ctrl+Z, or click Undo."])
        .check("The tier is back at the angle it had before you pressed.")
        .goal(check("the stone is as it started", rich_untouched), "The starting angles back")
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Drag the depth handle",
            "D moves the tier in or out along its own normal, which changes its depth.",
        )
        .actions([
            "Press on D, the blue square, and drag it along its line.",
            "Let go, and read the toast under the picture.",
        ])
        .check("The tier list shows a new depth (mast) for the tier.")
        .why("Dragging D pins the tier to the mast you drop it on, replacing whatever it met before. Undo brings that back.")
        .goal(check("a tier is at another depth", depth_moved), "A tier at a new depth")
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Turn the tier with the index handle",
            "I turns the tier round the index wheel, a whole number of teeth at a time.",
        )
        .actions([
            "Press on I, the amber diamond, and drag it a few teeth round.",
            "The line under the toolbar counts the teeth.",
        ])
        .check("The tier's facets sit at new index positions.")
        .why("A tier with no index positions, such as the Table, has no I handle.")
        .goal(check("a tier is at other indices", index_moved), "A tier at new indices")
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Switch snapping off",
            "By default an angle snaps to 0.1 degrees and a depth to 0.01. The Snap pill turns that off.",
        )
        .actions([
            "Click the Snap pill in the toolbar.",
            "Hold Shift while you drag A or D to move in fine steps instead (0.01 degrees and 0.001).",
        ])
        .check("The Snap pill is no longer lit.")
        .why("The index handle always moves in whole teeth, whatever the pill says.")
        .goal(event(SNAP_TOGGLED), "The Snap pill clicked")
        .highlight("snap_pill")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Switch snapping back on",
            "Free dragging is for fine work; coarse snapping is easier for everything else.",
        )
        .actions(["Click the Snap pill again."])
        .check("The Snap pill is lit.")
        .goal(event(SNAP_TOGGLED), "The Snap pill clicked")
        .highlight("snap_pill")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Cancel a drag",
            "A drag you do not like never has to be undone.",
        )
        .actions([
            "Press Escape while you are still holding the mouse button: the design goes back exactly as it was when you pressed.",
            "Escape with nothing being dragged clears the selection.",
            "Press Ctrl+Z to put back anything you changed in this lesson.",
        ])
        .why("Every control is unlocked again."),
    )
}

fn slice() -> Guide {
    Guide::new(
        "viewing-slice",
        "Slice: cut a facet with the mouse",
        "Draw a line across the stone, cut it in with the depth handle and keep it as a new tier.",
        GuideCategory::Viewing,
    )
    .starting(StartingState::Template(5))
    .step(
        GuideStep::new(
            "Switch Slice on",
            "Slice starts a new tier by drawing on the stone instead of typing an angle and an index.",
        )
        .actions([
            "Click the Edit tab above the picture, then Solid, if they are not already chosen.",
            "Click the Slice pill in the toolbar (or press S with the stone in focus).",
        ])
        .check("The Slice pill is lit and the line under the toolbar says what to do.")
        .why("While Slice is on, a left drag draws a line instead of turning the stone. Slice needs the 3D stone, so it is not offered in the Diagram view.")
        .goal(event(SLICE_STARTED), "Slice switched on")
        .highlight("slice_pill")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Draw a line",
            "The line says where the new facet goes and which side is cut away.",
        )
        .actions([
            "Press on one side of the stone, drag across its upper part and release.",
            "The part to the right of your drag direction is cut away; three faint ticks mark that side.",
        ])
        .check("The new tier appears with a green outline and the line under the toolbar gives its angle and index.")
        .why("Nothing is cut yet and nothing is in the undo history. The plane is snapped to the index wheel and to 0.1 degrees, and placed so it only just touches the stone.")
        .goal(event(SLICE_DRAWN), "A line drawn on the stone")
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Flip the side",
            "If the cut would take the wrong side, you do not have to draw again.",
        )
        .actions([
            "Click Flip in the strip under the toolbar (or press F).",
            "Click it again to come back to the first side.",
        ])
        .check("The green outline moves to the other side of the stone.")
        .goal(event(SLICE_FLIPPED), "Flip pressed")
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Cut it in",
            "A new facet starts exactly touching the stone, so it cuts nothing yet.",
        )
        .actions([
            "Drag the depth handle D, the blue square, inward.",
            "Stop when the line under the toolbar no longer says to drag the depth handle inward first.",
        ])
        .check("The green outline now cuts into the stone.")
        .why("Keep refuses until the facet really touches the stone. The angle and index handles work on the new tier too; none of these drags is an undo step yet.")
        .goal(event(SLICE_CUTS_STONE), "The new facet cutting the stone")
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Symmetric or single",
            "The Symmetric pill decides how many facets the new tier has.",
        )
        .actions([
            "Click Symmetric in the strip under the toolbar to turn it off: the cut becomes a single facet.",
            "Click it again to turn it back on.",
        ])
        .check("The Symmetric pill changes between lit and dark.")
        .why("On, the new tier is cut at every index position the design's symmetry gives it, like any other orbit. Off, it is cut at one position only. The tier keeps its angle and depth when you switch.")
        .goal(event(SLICE_SYMMETRIC_TOGGLED), "Symmetric clicked")
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Keep the facet",
            "Keeping turns the provisional facet into a real tier.",
        )
        .actions(["Click Keep in the strip under the toolbar (or press Enter)."])
        .check("A new row appears in the tier list and is selected, and Slice switches off.")
        .why("Keep adds the tier as one undo step. Discard (or Escape) throws it away instead and leaves the design as it was.")
        .goal(Goal::TierCountAtLeast(START_TIERS + 1), "The new tier kept")
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Undo the new tier",
            "A kept slice is one step in the history.",
        )
        .actions(["Press Ctrl+Z, or click Undo."])
        .check("The new row is gone from the tier list.")
        .goal(
            check("the slice is undone", |ctx| ctx.design.tiers.len() <= START_TIERS),
            "The slice undone",
        )
        .highlight("tier_table")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Done",
            "Slice is quick for a first sketch of a facet; the tier form is better for exact numbers.",
        )
        .why("Every control is unlocked again."),
    )
}

fn diagram() -> Guide {
    Guide::new(
        "viewing-diagram",
        "The Diagram view",
        "Read the crown, pavilion and profile panels, pick a facet and drag its handle on the flat diagram.",
        GuideCategory::Viewing,
    )
    .starting(StartingState::Template(5))
    .step(
        GuideStep::new(
            "Switch to the Diagram",
            "The Diagram draws your design the way a faceting reference diagram does.",
        )
        .actions([
            "Click the Edit tab above the picture, if it is not open.",
            "Click Diagram above the stone.",
        ])
        .check("Three flat panels appear: Crown, Pavilion and Profile.")
        .why("The Diagram does not turn with the camera, and it always shows the finished design: switching to it puts the Cut slider back to Finished.")
        .goal(Goal::ViewMode(3), "The Diagram view")
        .highlight("view_modes")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Read the three panels",
            "Each panel looks at the stone from a different side.",
        )
        .actions([
            "Crown looks straight down at the top of the stone.",
            "Pavilion looks straight up at the bottom, so it is mirrored left to right compared with the crown.",
            "Profile is a side view: the crown angle, the girdle and the pavilion angle stacked up.",
            "The ring of ticks round the crown and pavilion is the index wheel. Index 0 is always at the top.",
        ])
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Pick a facet",
            "Clicking works as in the Solid view, on the diagram's own layout.",
        )
        .actions(["Click a facet in the Crown panel."])
        .check("The tier's row is highlighted in the tier list, and its handles A, D and I appear on a panel.")
        .why("The exact facet you click is remembered, so the same facet stays picked when you switch back to the Solid view.")
        .goal(event(FACET_PICKED), "A click on a facet")
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Drag a handle on the diagram",
            "The handles work exactly as they do on the stone.",
        )
        .actions([
            "Press on A and drag it away from the centre of the wheel to make the facet steeper, or towards the centre to make it shallower.",
            "Hold Shift for fine steps.",
        ])
        .check("The tier list shows a new angle.")
        .why("D moves the tier in or out and I turns it round the wheel, on the crown and pavilion panels. The Profile panel offers handles only for facets seen exactly side on.")
        .goal(check("a tier is at another angle", angle_moved), "A tier at a new angle")
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Enlarge a panel",
            "One panel at a time can fill the whole view.",
        )
        .actions([
            "Click the Pavilion pill in the toolbar (or double-click a panel).",
        ])
        .check("The panel fills the view and its pill is lit.")
        .why("Scroll to zoom and drag to pan the diagram; Reset View puts both back.")
        .goal(event(DIAGRAM_PANEL_ENLARGED), "A panel enlarged")
        .highlight("solid_viewport")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Back to all three",
            "Going back is the same gesture.",
        )
        .actions([
            "Click the lit pill again, double-click the panel, or press Escape.",
            "Press Ctrl+Z to put back the angle you changed.",
        ])
        .why("Every control is unlocked again."),
    )
}

fn cut_slider() -> Guide {
    Guide::new(
        "viewing-cut-slider",
        "The Cut slider",
        "Watch the stone being cut: the rough, the stone after each step and the finished design.",
        GuideCategory::Viewing,
    )
    .starting(StartingState::Template(5))
    .step(
        GuideStep::new(
            "Find the Cut slider",
            "The Cut slider shows the stone as it looks after each tier of the cutting steps.",
        )
        .actions([
            "Click the Edit tab above the picture, then Solid, Path-traced or Both.",
            "The slider is at the left end of the toolbar, with a label beside it that reads Finished.",
        ])
        .why("It appears as soon as the design has a tier. The Diagram does not show it, because the Diagram always draws the finished design.")
        .highlight("cut_slider")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Go back to the rough",
            "All the way to the left is the block before any facet is cut.",
        )
        .actions(["Drag the slider all the way to the left."])
        .check("The label reads Rough and the stone is the uncut block.")
        .why("Every position is a whole stone: a step only removes material, so even the rough is a closed solid you can turn and pick.")
        .goal(event(CUT_SLIDER_ROUGH), "The slider at the rough")
        .highlight("cut_slider")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Step through the cuts",
            "Each step to the right adds one tier.",
        )
        .actions(["Drag the slider one step to the right, then another."])
        .check("The label names the tier you have just cut and counts the steps, for example After Crown Main (2 of 4).")
        .why("The steps follow the order of the cutting instructions. With a concave tier they follow the order the stone is really cut in.")
        .goal(event(CUT_SLIDER_STEP), "The slider between rough and finished")
        .highlight("cut_slider")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "Back to the finished stone",
            "All the way to the right is the whole design.",
        )
        .actions(["Drag the slider all the way to the right."])
        .check("The label reads Finished and the border is no longer amber.")
        .why("The slider's border turns amber whenever it is anywhere but Finished, so you can tell at a glance that you are looking at part of the design.")
        .goal(event(CUT_SLIDER_FINISHED), "The slider at Finished")
        .highlight("cut_slider")
        .allow(VIEWPORT),
    )
    .step(
        GuideStep::new(
            "What the slider leaves alone",
            "The slider changes what you see, never the design.",
        )
        .actions([
            "While it is short of Finished the drag handles are hidden.",
            "Live Render follows the cut, with a small amber badge and a Show finished button.",
            "Exports, the tilt video and the tilt curves always use the finished stone.",
        ])
        .why("Every control is unlocked again."),
    )
}