= [wiki:Development/cabb-upgrade/]PGFLAG =

[[PageOutline]]

== Specification ==

We want a simple PGPLOT-based utility to
 * display UV data from a single baseline, in the format (achieved in version 1)
   * channel number on X axis
   * time on Y axis
   * amplitude or phase shown as "greyscale"
 * display a cursor with 'live' readback of the amplitude/phase, channel number, frequency and timestamp
   * PGPLOT has no callback routines on cursor movement, so unable to implement live readback
   * instead have made it possible to 'measure' the point under the cursor via keypress
 * it would be helpful to display the source name as well, either as a live readback, or as an annotation on the display window (perhaps at the scan boundaries)
   * not implemented in version 1.3

We want to use this to select subsets of the displayed data and apply flagging commands to the subset.

 === Display characteristics ===
 * display one baseline at a time (version 1)
 * we want to be able to jump to a different baseline number (forward and back thro' the sequence) (version 1)
 * don't average time steps by default (make the averaging a command parameter) (version 1)
 * do sum the channels such that the entire bandpass fits in the PGPLOT display window (allow turning this off via command line params)
   * PGPLOT routine PGGRAY does this automatically (version 1)
 * if the uvdata array extends beyond the edges of the display window, allow scrolling (vertically or horizontally) (version 1)
 * when it is possible to scroll, show an arrow (outside the display grid) pointing in the direction one can scroll. Arrow keys are the most obvious shortcut key!
   * PGPLOT uses the cursor keys in interactive mode as another way to move the mouse
   * instead version 1 uses the vi movement keys h,j,k,l for scrolling
 * the cursor would ideally be an 'open plus' shape - lines extending to the edge of the display grid but with a small open area at the intersection (so you can see what is directly under the cursor).
   * unable to change PGPLOT interactive cursor shape
 * zooming - allow zooming up to 1:1 display. May be useful to have higher zooms than this?
   * PGPLOT routine PGGRAY allows for easy zooming with automatic scaling (version 1)
 * must support SELECT and LINE keywords (version 1)

 === Flagging ===
 * when user selects a piece of data, and says 'flag it'
   * update the display to show the data flagged away (version 1)
   * allow 'undo' of the last flagging command. (version 1)
 * selection:
   * by area (PGPLOT boxing) (version 1)
   * this will do single rows and columns as well.
   * however one does want to be able to flag an entire row while still zoomed in (ie data extends beyond display borders)
     * version 1 can extend the selection to the entire row/column, but only on viewed region
     * version 1.3 can extend the selection to entire row/column, past the viewed region, allowing flagging of all data while zoomed
 * should be able to abort a flagging session, ie throw all flags for the current baseline and/or all baselines flagged so far.
   * version 1 can abort completely, not start again without reloading
   * version 1.3 can discard flags on displayed baseline or all baselines without restarting
 * probably want to use temporary flagging files that only replace the flag file for the dataset at the end of the task
   * version 1 uses in-memory flagging, and applies only at the end
 * probably want to allow logging of the flagging commands so they can be played back/edited with UVFLAG
   * version 1 logs all flags to the history, and can make BLFLAG selgen-like files, but of course the 'select' keyword cannot be used to constrain channel ranges


----
[wiki:Development/cabb-upgrade/ CABB home][[BR]]
[wiki:WikiStart Miriad home]