26. A clip plane by hand, the studio as a picture
The 3-D panel's cut, a plane fixed at the probe line since chapter 14, becomes a plane the user places: a gizmo drawn over the view moves it along its arrows and turns it on its rings, and a view cube in the corner turns the camera. Then the studio's test grows two ways: it finds its items by their paths, and it compares the studio's main window, rendered headless, with a committed picture.
The whole program: tut26_clip.F90, chapter 25's studio with the changes below.
What this chapter adds to chapter 25's program, tut25_editor.F90:
clip: Clip the 3-D view by the planeto_pixel: Where a point of the 3-D view is drawn on the display [pixels]- changed:
build_3d,draw_3d,draw_case,self_test
A plane the user places
Checking clip places a plane across the plate at the probe line; its placement is a 4 x 4 matrix, in columns: the plane's two in-plane axes, its normal, its point (Gizmos):
if (ig_checkbox('clip', cut)) then
if (cut) then ! a plane across the plate at the probe line, keeping x < probe
plane = 0.0_real64 ! columns: the plane's two axes, its normal, its point
plane(1:3, 1) = [0.0_real64, 0.0_real64, 1.0_real64]
plane(1:3, 2) = [0.0_real64, 1.0_real64, 0.0_real64]
plane(1:3, 3) = [-1.0_real64, 0.0_real64, 0.0_real64]
plane(1:4, 4) = [probe_x, 0.5_real64 * fly, 0.0_real64, 1.0_real64]
call clip()
else
call view%unclip()
endif
endifAfter view%draw, two calls draw over the view:
call view%view_cube() ! top-right: a click on a face looks at it, a drag turns
if (cut) then
if (view%gizmo('clip plane', plane, mode=trim(GIZMO_MODES(gizmo_mode)))) call clip() ! the user moved the plane
endifview%view_cube()draws the cube in the view's top-right corner: a click on a face turns the camera to look at it, a drag on the cube orbits.view%gizmo(id, plane, mode=...)draws the gizmo at the plane's point and is true on the frames the user drags it, withplanechanged in place;'translate'shows three arrows,'rotate'three rings ('scale', the third mode, would stretch the axes: the studio offers move and turn). Nothing is called back: the studio polls the result and clips the view again.
subroutine clip()
!< Clip the 3-D view by the plane: what lies on the side its normal points to is kept.
real(real64) :: n(3) !< The normal, unit.
n = plane(1:3, 3) / norm2(plane(1:3, 3))
call view%unclip()
call view%clip(n, plane(1:3, 4))
endsubroutine clipview%clip(normal, point) keeps what lies on the side the normal points to; the normal is made unit first, since a turned matrix carries rounding. The view keeps the clip across frames; unclip removes it.
The test, by paths
Since chapter 17 the test has found its targets by their pixels: the centre of the last item drawn, kept in a variable for the purpose (title_at, east_at, ...). The new checks name the items instead, by the path of labels that leads to them (Finding items by path):
call test_item_click('tools/3-D') ! the 3-D panel in front, by its button in the tools' bar
call settle()
call test_item_click('3-D/clip') ! the checkbox, found by its path
call settle()
call check(cut .and. test_item_checked('3-D/clip'), 'the clip box, clicked by its path, is checked')
x0 = plane(1, 4)
call to_pixel(plane(1:3, 4), p0(1), p0(2))
call to_pixel(plane(1:3, 4) + [0.1_real64, 0.0_real64, 0.0_real64], p1(1), p1(2))
u = (p1 - p0) / norm2(p1 - p0) ! the x arrow's direction on the display
call test_mouse_move(p0(1) + 50.0_real64 * u(1), p0(2) + 50.0_real64 * u(2)) ! on the arrow, as the user grabs it
call frames(2_int32)
call test_mouse_button(.true.)
call frames(2_int32)
call test_mouse_move(p0(1) + 110.0_real64 * u(1), p0(2) + 110.0_real64 * u(2))
call frames(1_int32)
call test_mouse_button(.false.)
call frames(6_int32)
call check(plane(1, 4) > x0 + 0.05_real64, 'the gizmo''s arrow, dragged, moves the plane along x')
call test_item_click('3-D/clip') ! off again
call settle()
call test_mouse_move(10.0_real64, 300.0_real64)
call frames(2_int32)test_item_click('tools/3-D'): the tool button labelled 3-D in the windowtools(the bar's own name);test_item_click('3-D/clip'): the checkbox clip in the panel 3-D. A click on an item that is not there, or disabled, or hidden behind another tab, stops the test with a message naming the nearest item.test_item_checked('3-D/clip')reads the check mark as it was drawn.- The gizmo has no label: the test aims at its arrow from the view's own matrices (
to_pixel, withview%view_matrixandview%projection_matrix), ascb_gizmodoes.
The studio as a picture
Every check so far reads a value. One more compares what the studio looks like: the main window, once the plate is open and its field read, with a picture committed beside the example, docs/examples/data/tut26_clip.png:
do k = 1_int32, 1000000_int32 ! the plate's field, read by a task: at a time of the task's
if (size(field) > 0) exit
call frames(1_int32)
enddo
call frames(360_int32) ! the notifications gone (5 s of frame time), nothing moving
call test_capture('tut26_clip.png') ! the whole window, written when this frame is rendered
call frames(1_int32)
masks(:, 1) = path_rect ! the case's path: this machine's folders
masks(:, 2) = 0.0_real64 ! the title bar: left out where it is the other platform's
call test_frame_rect('close', r(1), r(2), r(3), r(4))
call test_frame_rect('menus', m(1), m(2), m(3), m(4))
if (r(1) < m(1)) call test_frame_rect('bar', masks(1, 2), masks(2, 2), masks(3, 2), masks(4, 2)) ! macOS: buttons left
call check(test_compare_image('tut26_clip.png', golden, masks=masks), &
'the main window looks as committed (docs/examples/data/tut26_clip.png)')
call check(test_id_conflicts() == 0_int32, 'no two items of the main window share an id')test_capture(file)writes the whole frame as a PNG when it is rendered, at the nextapp%next_frame. Headless, FIGURE's own renderer draws it, the same on any machine, without a GPU (Capture).test_compare_image(file, golden, masks=...)is true when no pixel differs by more than 2 levels per channel, outside the masks (Pictures as tests); on a mismatch it writestut26_clip.new.pngandtut26_clip.diff.pngbeside the committed picture, to look at. The first mask is the case's path in the Case panel: the folder the test runs in is this machine's. The second is the title bar where its buttons are on the left (the close button left of the menus, bytest_frame_rect): on macOS, while the committed picture has them on the right; elsewhere it is an empty rectangle, which masks nothing.- Wait for what the picture shows. The field is read by a task, at a time of the task's; the test draws until it is there, then 360 frames, for the notifications to fade (5 s of frame time each). Then nothing on the screen depends on the clock.
test_id_conflicts(): no two items of the window share an id, which a path could not tell apart.
A change to the studio that shows, a label renamed, a colour, a margin, fails the check: the picture is then taken again, looked at, and committed with the change.
$ ./tut26_clip --test tut26-cases ../../../docs/examples/data/tut26_clip.png
[ok] the title bar holds the studio's menus
[ok] the title drags the window
[ok] ctrl+o shows the file browser on the example cases
[ok] Choose opens the case, the window's title says which
[ok] the main window looks as committed (docs/examples/data/tut26_clip.png)
[ok] no two items of the main window share an id
[ok] escape leaves the title as it was, unedited
[ok] enter commits the title, one undo step, and the window's title marks it unsaved
[ok] a drop asks before discarding the edit
[ok] Discard opens the dropped case
[ok] F5 runs the solver to convergence
[ok] the task reads the field the solver wrote
[ok] right moves the probe line while Result has the focus
[ok] and not while the title field is edited
[ok] nor while another panel has the focus
[ok] the run's snapshots are listed; a frame with nothing changed colours nothing
[ok] playing steps through the snapshots, each coloured once
[ok] the pointer over the monitor reads iteration 111: residual 3.91E-05, mean 20.615 C
[ok] the averaging window spans the run: its mean is the mean of every iteration
[ok] two runs in the table, sorted by iterations on a click of its header
[ok] a second click reverses the order
[ok] a right click on a run opens its menu
[ok] the clip box, clicked by its path, is checked
[ok] the gizmo's arrow, dragged, moves the plane along x
[ok] View > Analysis: Input hidden, Messages shown beside Run
[ok] the 3-D view docked on the right of the result
[ok] View > Input shows the panel the layout hid
[ok] View > Setup gives back the input's layout
[ok] the editor finds "omega" in the text
[ok] a name the namelist has not is marked on its line; Apply waits
[ok] the name corrected, no line is marked
[ok] F1 shows the help; it finds "omega"
[ok] a click on a problem shows the Body section, the radius in keys
[ok] a click on the sketch's east side chooses it
[ok] an input with the body out of the plate is refused
[ok] and accepted once corrected
[ok] larger text: one em is 19 pixels, the bar 5 em
[ok] a stray ig_end_tab is reported by the next frame, naming the call
ig_end_tab: no ig_begin_tab is open (no scope is open)
[ok] no other frame of the test had a usage error
[ok] the title bar's close button ends the studio
40 of 40 checks passedWhat you learned
view%gizmo and view%view_cube, a plane placed and the camera turned by hand, view%clip; test_item_click and test_item_checked, items found by their paths; test_capture and test_compare_image, the window tested as a picture, with masks for what is not the program's. Reference: Gizmos, Finding items by path, Pictures as tests.
Run it: build it as chapter 7 shows (with tut22_heat beside it), then ./tut26_clip --examples /tmp/studio --case /tmp/studio/plate.
This is the end of part three. The Cookbook answers one task per recipe, the Reference lists every procedure, and the name map gives the FIGURE call of a Dear ImGui, ImPlot or ImPlot3D function, and of the extensions'.