legend outside the plot area (return legend as pict?)

[bennn]

Currently, plot draws legends on the plot area.

It would be nice if plotting functions could return the plot and legend as two picts that could be combined using a pict combiner or progressive pict.

(edit) see also:

• https://groups.google.com/d/msg/racket-users/QLfNmsluVHM/d8DNKggeBQAJ
• https://groups.google.com/d/msg/racket-users/siAC4VWpzNA/W8-GLWCcBQAJ

[alex-hhh]

These are some notes for adding support to draw the plot legend outside the plot area. Doing this is surprisingly difficult, as the notes below show.

Define new legend anchor types

The location of the plot legend is controlled by the plot-legend-anchor parameter, which is of type Anchor, defined here:

plot/plot-lib/plot/private/common/types.rkt

Line 15 in 4df3489

(deftype Anchor

We need to add 'outer-top-left, 'outer-left, 'outer-bottom-left, 'outer-top-right, 'outer-right and 'outer-bottom-right cases to this type.

NOTE unfortunately, this type is also used as an anchor to the labels on the plot and the new types would be invalid values for use as plot labels. Also the anchor type already contains 'auto, which is used by the plot labels (meaning to place the label such that it fits inside the plot), but has no meaning for legend entries. Perhaps we should separate the types and use Anchor for labels and a new type LegendAnchor for plot legends.

Separate the legend size calculation from the drawing

plot/plot-lib/plot/private/common/plot-device.rkt

Line 613 in 4df3489

(define/public (draw-legend legend-entries rect)

The legend is actually drawn in plot-device%/draw-legend, this function both calculates the size of the legend and draws it. It receives the legend entries, plus the plot area in plot coordinates (since, as of now, the legend is drawn inside the plot area).

We need at least a function which calculates the legend-x-size and legend-y-size separately.

Also this function will need to be updated to recognize the new legend anchors and adjust the position of the legend accordingly.

Make room for the legend when it is outside

When the legend is outside the plot, space will need to be reserved for it. This is done here (there is an equivalent place for 3D plots):

plot/plot-lib/plot/private/plot2d/plot-area.rkt

Line 554 in 4df3489

(let-values ([(left-val right-val top-val bottom-val)

The get-param-vs/set-view->dc! will need to be updated to add an entry for the legend, if the legend is outside. The function returns a list of entries for margin-fixpoint to use. Each entry is in the format:

(list label (vector x y) Anchor Angle)

The x, y are the location of the label in DC coordinates, label is currently either a string or a picture (something on which margin-fixpoint can calculate width and height), Anchor represents the position of the label relative to the (x,y) point and Angle is the direction of the label. For examples on how these entries are constructed, see get-{x,y,z}-label-params in the same file.

We will need to construct such an entry for the legend, if the legend is to be rendered outside the plot area. Unfortunately, at this stage, we don't know about the legend yet!

Note that the Anchor passed here would be a different anchor than the legend anchor supplied by the user: it refers to the position on the legend where the x,y point will be.

For example: for a 'outer-top-left legend anchor: x, y will be the position of the top-left top area (view->dc 0 1), minus a gap, minus the space for the plot ticks, minus the space for the y axis label. The anchor will than be 'top-right, as this is the point on which the legend will be attached to this point.

Inform 2d-plot-area% about the legend early on.

The plot-area% object does not know about the legend, until it is asked to draw it. The plot-area function (see link below) will receive a 2d-plot-area% instance (which already has all its sizes calculated), draw the renderers on it, than draw the legend as the last step (this is when the plot area first sees the legend):

plot/plot-lib/plot/private/no-gui/plot2d-utils.rkt

Line 68 in 8dcfd77

(define (plot-area area renderer-list)

The plot-area function already receives a 2d-plot-area% object will all the layout calculated, so it is already too late to inform it about the legend. The 2d-plot-area% object is created in several places, and the legend will need to be passed here, so it can be used for size calculations:

plot/plot-lib/plot/private/no-gui/plot2d.rkt

Line 40 in 18d8eca

(define (plot/dc renderer-tree dc x y width height

plot/plot-gui-lib/plot/private/gui/plot2d.rkt

Line 116 in 18d8eca

(make-object 2d-plot-area%

plot/plot-gui-lib/plot/private/gui/snip2d.rkt

Line 258 in 58b5d7e

(make-object 2d-plot-area%

Same changes for 3D plots

While the drawing of the plot legend is handled in common, there is a different, 3d-plot-area% object and it will need to be updated in the same way as the 2d-plot-area% object.

[bdeket]

In order to get to the legend entries early, the (2D-)Render-Proc's will need to be called early.
We can do this

• by calling the Render-Proc with a fake plot area: this will mean that for expensive functions a lot of time will be invested in drawing something that we are going to discard
• by calling the Render-Proc with bounds (Rect (ivl #f #f) (ivl #f #f)): all the render procs will need to be updated to accept this as a valid region and only send back the legend entry. Currently most functions either error or send back an empty list as legend entry in this case. (This option does not mean that we accept this as sensible bounds, this is still checked elsewhere in the get-bounds-rect function)
• Changing the signature for Render-Proc into a struct or similar of (-> Area Void) and (-> (Treeof legend-entry))

personally I prefer option 3 since that makes it clear that two separate functionalities need to be provided. If we go with 2 we need to make sure that new render functions don't forget to send the label for the empty bounds.

[bdeket]

TODO list

• Separate legend and renderer : renderer2d and 3d have an extra struct field label [legend pt1] legend outside plot area #70
• Separate the legend size calculation from the drawing : plot-device% has an extra method calculate-legend-rect [legend pt2] separate legend size calculation and drawing functionality #71
• Define new legend anchor types : Legend-Anchor is (U #f Anchor (List (U 'inside 'outside) Anchor)) [Legend pt3] Make legend available to area at start #72
• Inform plot-area% about the legend early on : plot-area% takes an extra argument legend [Legend pt3] Make legend available to area at start #72
• Plot and legend in seperate picts [legend pt4] Plot+legend picts #73
• Make room for the legend when it is outside : outside currently places the legend as lowest element outside the plot-area, but other elements will be drawn on top of it, #f will not draw the legend at all
• Update docs
• Add new tests

[alex-hhh]

Thinks to do after completing this task:

• Document the 'auto entry for anchor/c, see discussion on [Legend pt3] Make legend available to area at start #72 -- this is already documented in contracts.scrbl, but in a peculiar way: the Anchor TR type contains 'auto, but the anchor/c contract does not. This means that auto cannot be used as a legend anchor (as this is protected by the contract), but can be used for point-label, whose #:label parameter is protected by a contract generated from TR (TR = Typed Racket)
• add a horizontal layout mode for the plot legend
• Avoid starting the plot render when there are no entries, see discussion on [Legend pt3] Make legend available to area at start #72 -- this will require updating some test data.
• center plot3d-snip overlay messages on the plot area
• add a test for plot-legend-as-pict , this requires extending the test framework for picts, but the same technique can be used.