Skip to content

23. The field and its snapshots ​

This chapter changes how the studio draws its result. The field is coloured through the colormap once, into a texture, and coloured again only when something changed; its legend becomes the colour scale's control, dragged and zoomed by the user; and a player steps through the snapshots the solver wrote during the run, the converged field last.

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

The whole program: tut23_player.F90, chapter 22's studio with the changes below. The solver is chapter 22's, started with --snapshots 4: every 4 iterations it writes the field to snap_NNNNNN.dat and a line to snapshots.txt.

What this chapter adds to chapter 22's program, tut22_monitor.F90:

  • read_snapshots: The list of the run's snapshots, snapshots.txt of the case (none
  • show_snapshot: The field of the player's snapshot in shown_field (the converged one for the last), coloured again
  • changed: draw_result, self_test, start_run, take_field

The field through a colormap, in one call ​

Part two drew the field with ip_heatmap, which ImPlot colours cell by cell on every frame. ip_field_image colours the field into a texture kept between frames, and colours it again only when the field, its range, its colormap or its scale change (Fields):

fortran
! the cells' edges: half a spacing beyond the first and last nodes
call ip_field_image('##t', shown_field, -0.5_real64 * dx, cx + 0.5_real64 * dx, -0.5_real64 * dy, &
                    cy + 0.5_real64 * dy, colormap=cmap, vmin=t_lo, vmax=t_hi, changed=recolour)
recolour = .false.                             ! coloured: until the values, the range or the map change
  • x0, x1, y0, y1 are the edges of the cells, in plot units, as for the heatmap; the field is read in place (f(i, j), i along x, j = 1 at the bottom).
  • A field changed in place is not seen. FIGURE compares the array's address, its shape, the range, the colormap and the scale, not the values: when the program writes new values into the same array it says so with changed=.true., for one frame. The studio sets recolour when it puts a snapshot into shown_field, and clears it after the call.
  • A field of millions of cells costs its colouring once, not on every frame: a lazy studio that redraws for a moving pointer does not colour anything.

A legend that sets the range ​

fortran
if (bands > 0_int32) then                         ! drag it to move the range, the wheel over it to zoom it
   if (ip_colormap_legend_edit('legend', cmap, t_lo, t_hi, levels=bands, height=-1.0_real64, label_format='%.0f')) &
      continue                                    ! t_lo, t_hi changed in place: the field is coloured again
else
   if (ip_colormap_legend_edit('legend', cmap, t_lo, t_hi, height=-1.0_real64, label_format='%.0f')) continue
endif

ip_colormap_legend_edit draws the legend of chapter 13 and lets the user change its range: a drag along the bar moves [t_lo, t_hi] with the pointer, the wheel over it zooms the range about the value under the pointer; the two variables change in place, and ip_field_image, given them, colours the field again on that frame (Fields). The program keeps its own way back: Reset range sets them to the field's minimum and maximum.

A player over the snapshots ​

After a run, read_snapshots reads the list the solver wrote and sets up a player_object: count the snapshots and the converged field, index the one shown, the last at first. The player is one widget:

fortran
call ig_set_next_item_width(ig_em(18))
if (ig_player('snapshots', player, snap_labels)) call show_snapshot() ! true on the frame the index changed

ig_player draws a step-back button, a play/pause button, a step-forward button and a slider showing the label of the snapshot shown; a right click on it opens a menu for the speed, in snapshots per second, and the mode, 'loop' (the default), 'once' or 'bounce'. It is true on the frame index changed, by a button, the slider or the playing itself (Players); the studio then reads that snapshot:

fortran
recolour = .true.                                 ! ip_field_image does not see a change in place: the program says
if (player%index > size(snap_iters)) then
   shown_field = coarse
   return
endif

The player plays on the frame clock and asks for the frames it needs while playing, so a lazy loop (Lazy redraw) keeps time without input; paused, the studio sleeps again.

The test ​

test_field_uploads() counts the colourings ip_field_image made: none on a frame where nothing changed, one per snapshot while playing. The test plays the player as its play button does, by setting playing:

fortran
uploads = test_field_uploads()
call frames(3_int32)
call check(size(snap_iters) > 1 .and. test_field_uploads() == uploads, &
           'the run''s snapshots are listed; a frame with nothing changed colours nothing')
player%playing = .true.                           ! as the play button does
call frames(20_int32)
player%playing = .false.
call frames(2_int32)
call check(player%index < player%count .and. test_field_uploads() > uploads .and. &
           any(shown_field /= coarse), 'playing steps through the snapshots, each coloured once')
text
$ ./tut23_player --test tut23-cases
[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]     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]     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
28 of 28 checks passed

(The ig_end_tab line is the report of chapter 19's deliberate mistake.)

What you learned

ip_field_image, a field coloured once and again only on a change, with changed for values changed in place; ip_colormap_legend_edit, a legend whose range the user drags and zooms; player_object and ig_player, a player over saved snapshots. Reference: Fields, Players.

Run it: build it as chapter 7 shows (with tut22_heat beside it), then ./tut23_player --examples /tmp/studio --case /tmp/studio/plate.

Chapter 24 hands the studio's windows to FIGURE: a View menu, layouts, and the user's settings kept.

Released under the MIT licence.