Skip to content

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.

docs/examples/src/tut26_clip.F90, run as tut26_clip --examples /tmp/figure-studio --case /tmp/figure-studio/plate

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 plane
  • to_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):

fortran
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
endif

After view%draw, two calls draw over the view:

fortran
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
endif
  • view%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, with plane changed 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.
fortran
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 clip

view%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):

fortran
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 window tools (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, with view%view_matrix and view%projection_matrix), as cb_gizmo does.

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:

fortran
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 next app%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 writes tut26_clip.new.png and tut26_clip.diff.png beside 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, by test_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.

text
$ ./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 passed

What 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'.

Released under the MIT licence.