requirements for waterfall plot

[shroffk]

Collecting requirements for waterfall plots:

supported inputs
waveform pvs
list of scalar pv's

[kasemir]

Users likely expect something like this from https://en.wikipedia.org/wiki/Waterfall_plot that scrolls up or down at a constant rate:

For the specific example, it would scroll "up", so the bottom line is the current spectrum, and the lines above reflect the history for the last ~14 seconds.

One issue for data coming from PVs is the timing. You may not receive an update every second, and you should use the received time stamp, not the time when the PV update happened to be received.
If the PV is a waveform that updates every second, a decent implementation would be to refresh the plot whenever an update is received. Note that the updates won't actually be received exactly each second because of the network, but the time stamps in the updates should indicate a constant period and the updates are likely close enough to once per second.

But there are several issues: If the PV disconnects, the plot shouldn't simply stop. It needs to continue scrolling up once per second, adding "invalid" rows for the missing data.
If the PV for some reason stops updating, that should probably be treated as "PV has the same value", suppressing updates to save network bandwidth. Unclear how the plot should decide that it's been long enough since the last update to assume that we can show a new row with the value from the last update.

Finally, when the input is a list of PVs, you need to somehow combine them into one "row", same issue as with a scatter plot https://github.com/ControlSystemStudio/phoebus/wiki/Display-Builder-Plot-Compatibility#scatter-plot

[kasemir]

Because of issues with combining the data into a constantly scrolling plot, one easy way out is to handle all this on the IOC and simply generate an "image", displaying it in the existing image widget.

The big advantage of a waterfall plot would be that it's more efficient, because what we transfer once per second is not the complete image but just the last new row, AND the drawing can then be optimized for this by basically doing a System.arraycopy to shift the raw image bits one row "up" or "down", then drawing just the one new row.

[kasemir]

For what it's worth, tested basic System.arraycopy behavior. Works fine with the overlap of source and destination, so could be used to move raw image buffer content "up" or "down":

final int WIDTH = 4;
int data[] = new int[]
{
     1, 2, 3, 4,
     5, 6, 7, 8,
     9,10,11,12,
    13,14,15,16
};

for (int row = 0; row < data.length/WIDTH; ++row)
{
    for (int col = 0; col < WIDTH; ++col)
        System.out.format("%2d ", data[row*WIDTH + col]);
    System.out.println();
}

// Scroll down
//        System.arraycopy(data, 0, data, WIDTH, 3*WIDTH);

// Scroll up
System.arraycopy(data, WIDTH, data, 0, 3*WIDTH);

for (int row = 0; row < data.length/WIDTH; ++row)
{
    for (int col = 0; col < WIDTH; ++col)
        System.out.format("%2d ", data[row*WIDTH + col]);
    System.out.println();
}

Moreover, that doesn't seem to be luck in this implementation of arraycopy but is documented:

If the {@code src} and {@code dest} arguments refer to the
same array object, then the copying is performed as if the
components at positions {@code srcPos} through
{@code srcPos+length-1} were first copied to a temporary
array with {@code length} components and then the contents of
the temporary array were copied into positions
{@code destPos} through {@code destPos+length-1} of the
destination array.