Just as a foreword, I'm pretty new to the Phoebus repo, so a lot of this could be well off the mark - please correct me if there's anything incorrect/not possible, or if there's anything I'd not considered.
This has been updated to reflect changes in design following work on the project.
Proposal
This is a proposal / Story Issue for the creation of a new interactive graph widget for Phoebus. It's a feature that's been requested by our users at ISIS, and I think this might be something that could be contributed to Phoebus at large, since its function is reasonably generic, and therefore usable across many control systems.
Any feedback you can provide would be greatly appreciated, whether it's technical advice, or just registering of interest in this feature being added.
The main goal of this is to add behaviour to a XYPlot/Graph-style widget which allows users to more directly edit plotted PVs. A user can "drag" individual points on the graph to new coordinates, updating PVs without having to edit each number/value by hand.
This will require additions to the existing base graph code, but under a new Mouse Mode, so that it doesn't affect existing implementations, and usage of the new Widget is required to enable/view the new mode.
A mockup for what this might look like using Excel, with the second "edited" line drawn in a blue, dashed line
Architecture
Following discussion with Kay Kasemir, and initial development work on a local fork, the design has been adjusted as follows:
Overall Structure
Additions are made to the base Plot class used by XYPlot and RTPlot to track mouse interaction, which is then used higher up by XYPlotRuntime to update the values used to store the "edited" trace copy. These changes then trigger a redraw of the graph contents, so a preview of edits are displayed before anything is saved to the Live PV.
A new widget will not need to be created, as the new functionality will exist within the Plot class, and be optionally enabled, doing nothing by default.
Interaction/point-editing behaviour
Direct changes to the base Plot.java class will be made to facilitate this new behaviour. Cursor coordinate data already exists, but it is protected, so the new code accessing it will need to exist within the same scope.
There's a lot of likely issues that could happen with the existing graph controls interfering with point manipulation. To avoid this, the "Edit Points" functionality would be placed within a new mouse mode in the graph toolbar. This also should minimise any impact on performance to existing usages of Plots, since the checks and calculations will only occur when a user is using that functionality.
New Mouse Mode
In order to separate the new functionality from the mouse interaction already present in Plot and stop them from interfering with each other, a new mouse mode of "EDIT" can be added.
This means any new mouse interaction is added in the same area as other base-level interaction of the same type, and the information only has to be passed up to the Widget layer to interact with the PVs.
This mode will need to run a check for the nearest point from all traces with the Editable flag set to true, then check if that is close enough to the cursor to be considered a click "on" the point.
Local PVs Editable PVs & Traces
Due to concerns around feasibility of implementing local copies of trace PVs for the widget to edit, the design has changed to use "normal" PVs, but versions which are not used by the IOC for any actual function. Any PVs that are to be edited through these widget changes will need to have a corresponding "staging" PV, which then has its values applied over the original when saving.
A new flag is added to the traces in the XYPlot config to mark it as "editable", meaning it is then subject to the new mouse interaction. This would be set to false by default, so any existing usages of XYPlot won't have to make any changes.
This does mean there is an additional burden on any users of this new behaviour, as these "edit mode" PVs would need to be configured on their end for each PV that should be managed with the new graph editing.
Interaction
Graph
Each point on the graph has a square/marker on it - this is the expected point at which the cursor will "pick up" the point, then drag and drop to another position,
One check for the nearest point (which will be "selected" if within some minimum range) would occur on a mousedown, rather than continuously triggering as the point is moved. This would otherwise run the risk of it picking a different point as you move one over another, and slow down performance constantly carrying out that check.
"locking" axes
There are cases where a user may only wish to make changes in the x or y axis (and some may have fixed x axes/timeseries), so there should be a way to "lock" axes to prevent any movement in that direction while dragging a point.
Given the way many Trace PVs are a list of Y-only values, making changes to the X axis would either require converting data to have specific X-Y pairings, or otherwise apply the same changed X value to all other traces in the same plot. Separating editing into only one axis at a time would simplify the process, and also be the simpler implementation to at least allow Y-value editing initially.
Buttons
"Edit"
The new mouse mode would have a new button alongside the others in the Plot Toolbar.
Enables the ability to click & drag points on the graph, so that the user only makes changes when they want to, and to allow normal usage/interaction with the graph when edit mode isn't active.
This acts like another one of the existing Mouse Modes, so that editing points and other mouse interaction do not interfere.
However, as other interaction cannot happen simultaneously, points on the graph will only be able to be moved within the existing plot space
"Discard changes"
Button to revert any changes made to the local PVs, so they match the existing "original" PVs. Useful if lots of changes were made but were unnecessary, lots of mistakes were made, or if changes were made by mistake.
This would overwrite the "Editable" PV with the Live PV, so they match again with original values.
"Undo"
Undoes the most recent change. Useful if a single mistake was made, but undoing all changes would be too excessive. The Trace, axis, value index and original value would need to be stored per "undo" available (eg: last 5 changes). This could be set after mouseup; the point is "dropped" and therefore a change is finished being made. To undo a change, the relevant original value would be applied to the trace's PV.
"Save Changes"
Our users don't want changes to immediately be made to the "live" version of the PVs being displayed/edited.
This button means that once all the desired changes have been made on the graph, a single PV update is pushed, changing all the "live" values in one go. (Partly this is assuming that the provided PVs are a list or similar, rather than a large set of individual PVs)
UI design
Buttons
Different coloured to make sure they're not mistaken for each other?
RED for discard, green for save, yellow for undo?
Positioned to the side of the graph, potentially include icons in them (or just only be icons)
New icon for EDIT Mouse Mode toolbar button & cursor
Secondary/"edited" line
A dashed line will be useful to differentiate it from the "original" line, and could also be coloured differently to make it even more distinct. However, this means if it is plot on top of the original, it may not look particularly good. Also, it may be worth drawing the edited line thinner than the original so it doesn't cause graphical weirdness when plotted next to the original.
A different colour could be used to make them more clearly separate, but this could cause confusion if there are multiple plots in the same graph, and the new line's colour matches another which already exists. The edited line colour could be set using a property of the widget to avoid this.
Coordinates
When dragging (or at all times while editing), it could be useful to display the cursor's coordinates beneath/next to it. This is already possible when using the graph toolbar, but having it available/active within edit mode would make more precise changes easier.
Indicators for activity
Given that the graph plot may be slow to update, we may want some way to show the user that the interface is recognising their drag-and-drop interaction. This could be done by having a simple circle, cross or other indicator under the cursor to show the point where the value/line will move to.
Existing functionality
XYPlots already have the ability to display a marker line, which can be moved by clicking and dragging. Its position is determined by a PV, and a local one is used in one of the example Phoebus screens, so adapting this to be able to edit X or Y values, and update a list PV instead of a single scalar aren't too large a leap.
XYPlot's toolbar also allows you to show guidelines and live coordinates of cursor position, so reusing this for when moving a point on the graph would make changes more accurate.
Future/Larger Scope work
- Selecting and editing multiple points at once
- Additional manipulation tools (eg: smoothing by different curve types/equations)
- Adding data points (inbetweens, as well as adding points according to a certain curve type)
- Plotting/Editing values produced by functions, not just direct plotted PVs
- Archiving changes / more extensive undo history
Just as a foreword, I'm pretty new to the Phoebus repo, so a lot of this could be well off the mark - please correct me if there's anything incorrect/not possible, or if there's anything I'd not considered.
This has been updated to reflect changes in design following work on the project.
Proposal
This is a proposal / Story Issue for the creation of a new interactive graph widget for Phoebus. It's a feature that's been requested by our users at ISIS, and I think this might be something that could be contributed to Phoebus at large, since its function is reasonably generic, and therefore usable across many control systems.
Any feedback you can provide would be greatly appreciated, whether it's technical advice, or just registering of interest in this feature being added.
The main goal of this is to add behaviour to a XYPlot/Graph-style widget which allows users to more directly edit plotted PVs. A user can "drag" individual points on the graph to new coordinates, updating PVs without having to edit each number/value by hand.
This will require additions to the existing base graph code, but under a new Mouse Mode, so that it doesn't affect existing implementations, and usage of the new Widget is required to enable/view the new mode.
A mockup for what this might look like using Excel, with the second "edited" line drawn in a blue, dashed line
Architecture
Following discussion with Kay Kasemir, and initial development work on a local fork, the design has been adjusted as follows:
Overall Structure
Additions are made to the base Plot class used by XYPlot and RTPlot to track mouse interaction, which is then used higher up by XYPlotRuntime to update the values used to store the "edited" trace copy. These changes then trigger a redraw of the graph contents, so a preview of edits are displayed before anything is saved to the Live PV.
A new widget will not need to be created, as the new functionality will exist within the Plot class, and be optionally enabled, doing nothing by default.
Interaction/point-editing behaviour
Direct changes to the base Plot.java class will be made to facilitate this new behaviour. Cursor coordinate data already exists, but it is protected, so the new code accessing it will need to exist within the same scope.
There's a lot of likely issues that could happen with the existing graph controls interfering with point manipulation. To avoid this, the "Edit Points" functionality would be placed within a new mouse mode in the graph toolbar. This also should minimise any impact on performance to existing usages of Plots, since the checks and calculations will only occur when a user is using that functionality.
New Mouse Mode
In order to separate the new functionality from the mouse interaction already present in Plot and stop them from interfering with each other, a new mouse mode of "EDIT" can be added.
This means any new mouse interaction is added in the same area as other base-level interaction of the same type, and the information only has to be passed up to the Widget layer to interact with the PVs.
This mode will need to run a check for the nearest point from all traces with the Editable flag set to true, then check if that is close enough to the cursor to be considered a click "on" the point.
Local PVs Editable PVs & Traces
Due to concerns around feasibility of implementing local copies of trace PVs for the widget to edit, the design has changed to use "normal" PVs, but versions which are not used by the IOC for any actual function. Any PVs that are to be edited through these widget changes will need to have a corresponding "staging" PV, which then has its values applied over the original when saving.
A new flag is added to the traces in the XYPlot config to mark it as "editable", meaning it is then subject to the new mouse interaction. This would be set to false by default, so any existing usages of XYPlot won't have to make any changes.
This does mean there is an additional burden on any users of this new behaviour, as these "edit mode" PVs would need to be configured on their end for each PV that should be managed with the new graph editing.
Interaction
Graph
Each point on the graph has a square/marker on it - this is the expected point at which the cursor will "pick up" the point, then drag and drop to another position,
One check for the nearest point (which will be "selected" if within some minimum range) would occur on a mousedown, rather than continuously triggering as the point is moved. This would otherwise run the risk of it picking a different point as you move one over another, and slow down performance constantly carrying out that check.
"locking" axes
There are cases where a user may only wish to make changes in the x or y axis (and some may have fixed x axes/timeseries), so there should be a way to "lock" axes to prevent any movement in that direction while dragging a point.
Given the way many Trace PVs are a list of Y-only values, making changes to the X axis would either require converting data to have specific X-Y pairings, or otherwise apply the same changed X value to all other traces in the same plot. Separating editing into only one axis at a time would simplify the process, and also be the simpler implementation to at least allow Y-value editing initially.
Buttons
"Edit"
The new mouse mode would have a new button alongside the others in the Plot Toolbar.
Enables the ability to click & drag points on the graph, so that the user only makes changes when they want to, and to allow normal usage/interaction with the graph when edit mode isn't active.
This acts like another one of the existing Mouse Modes, so that editing points and other mouse interaction do not interfere.
However, as other interaction cannot happen simultaneously, points on the graph will only be able to be moved within the existing plot space
"Discard changes"
Button to revert any changes made to the local PVs, so they match the existing "original" PVs. Useful if lots of changes were made but were unnecessary, lots of mistakes were made, or if changes were made by mistake.
This would overwrite the "Editable" PV with the Live PV, so they match again with original values.
"Undo"
Undoes the most recent change. Useful if a single mistake was made, but undoing all changes would be too excessive. The Trace, axis, value index and original value would need to be stored per "undo" available (eg: last 5 changes). This could be set after mouseup; the point is "dropped" and therefore a change is finished being made. To undo a change, the relevant original value would be applied to the trace's PV.
"Save Changes"
Our users don't want changes to immediately be made to the "live" version of the PVs being displayed/edited.
This button means that once all the desired changes have been made on the graph, a single PV update is pushed, changing all the "live" values in one go. (Partly this is assuming that the provided PVs are a list or similar, rather than a large set of individual PVs)
UI design
Buttons
Different coloured to make sure they're not mistaken for each other?
RED for discard, green for save, yellow for undo?
Positioned to the side of the graph, potentially include icons in them (or just only be icons)
New icon for EDIT Mouse Mode toolbar button & cursor
Secondary/"edited" line
A dashed line will be useful to differentiate it from the "original" line, and could also be coloured differently to make it even more distinct. However, this means if it is plot on top of the original, it may not look particularly good. Also, it may be worth drawing the edited line thinner than the original so it doesn't cause graphical weirdness when plotted next to the original.
A different colour could be used to make them more clearly separate, but this could cause confusion if there are multiple plots in the same graph, and the new line's colour matches another which already exists. The edited line colour could be set using a property of the widget to avoid this.
Coordinates
When dragging (or at all times while editing), it could be useful to display the cursor's coordinates beneath/next to it. This is already possible when using the graph toolbar, but having it available/active within edit mode would make more precise changes easier.
Indicators for activity
Given that the graph plot may be slow to update, we may want some way to show the user that the interface is recognising their drag-and-drop interaction. This could be done by having a simple circle, cross or other indicator under the cursor to show the point where the value/line will move to.
Existing functionality
XYPlots already have the ability to display a marker line, which can be moved by clicking and dragging. Its position is determined by a PV, and a local one is used in one of the example Phoebus screens, so adapting this to be able to edit X or Y values, and update a list PV instead of a single scalar aren't too large a leap.
XYPlot's toolbar also allows you to show guidelines and live coordinates of cursor position, so reusing this for when moving a point on the graph would make changes more accurate.
Future/Larger Scope work