Allow picts to be used as legend entries in plots (#64)

Allow pictures to be used as legend entries in plots

Updated 2D and 3D plot renderers to accept a picture (from the pict library)
or a string as the label used in the plot legend.

The original request was to allow LaTeX notation for the labels, this
changeset will enable doing that (and more) by installing the additional
`latex-pict` package and using the pictures produced by that package as
labels.

When updated the code which draws the legend, several considerations were
made:

* the `get-text-extent` method of `plot-device%` accepts a pict as an argument
  and will return the picture dimensions in that case.  The method was not
  renamed, however.

* the font used for text legend entries determines the inset (inside border)
  of the legend, gap between entries and length of the "sample" line.  This
  was essentially unchanged behavior and using the pict dimensions for this
  purpose results in bad looking legends, where the inset is too small, the
  sample line too long and gap too big.

Also updated some of the examples in the documentation to replace x^2 with x²,
to illustrate that Unicode can be used for the string labels.

See also

* #58
* racket/racket#3321

Author: alex-hhh

plot-doc/plot/scribblings/contracts.scrbl

@@ -202,7 +202,7 @@ Like @(racket plot-colors/c), but for fill styles.
 Like @(racket plot-colors/c), but for opacities.
 }
 
-@defproc[(labels/c [in-contract contract?]) contract? #:value (maybe-function/c in-contract (listof (or/c string? #f)))]{
+@defproc[(labels/c [in-contract contract?]) contract? #:value (maybe-function/c in-contract (listof (or/c string? pict? #f)))]{
 Like @racket[plot-colors/c], but for strings.
 This is used, for example, to label @racket[stacked-histogram]s.
 }

plot-doc/plot/scribblings/renderer2d.scrbl

@@ -34,7 +34,7 @@ See @secref["renderer2d-function-arguments"] for a detailed example.
           [#:size size (>=/c 0) (point-size)]
           [#:line-width line-width (>=/c 0) (point-line-width)]
           [#:alpha alpha (real-in 0 1) (point-alpha)]
-          [#:label label (or/c string? #f) #f]
+          [#:label label (or/c string? pict? #f) #f]
           ) renderer3d?]{
 Returns a renderer that draws points in 3D space.
 
@@ -62,6 +62,8 @@ negative direction, so total spread along e.g. the x-axis is twice @racket[x-jit
 
 Note that adding random noise to data, via jittering or otherwise, is usually a bad idea.
 See the documentation for @racket[points] for examples where jittering may be appropriate.
+
+@history[#:changed "7.9" "Added support for pictures for #:label"]
 }
 
 @defproc[(vector-field3d
@@ -76,13 +78,15 @@ See the documentation for @racket[points] for examples where jittering may be ap
           [#:line-width line-width (>=/c 0) (vector-field-line-width)]
           [#:line-style line-style plot-pen-style/c (vector-field-line-style)]
           [#:alpha alpha (real-in 0 1) (vector-field-alpha)]
-          [#:label label (or/c string? #f) #f]
+          [#:label label (or/c string? pict? #f) #f]
           ) renderer3d?]{
 Returns a renderer that draws a vector field in 3D space.
 The arguments are interpreted identically to the corresponding arguments to @racket[vector-field].
 @examples[#:eval plot-eval
                  (plot3d (vector-field3d (λ (x y z) (vector x z y))
                                          -2 2 -2 2 -2 2))]
+
+@history[#:changed "7.9" "Added support for pictures for #:label"]
 }
 
 @section{3D Line Renderers}
@@ -96,10 +100,12 @@ The arguments are interpreted identically to the corresponding arguments to @rac
           [#:width width (>=/c 0) (line-width)]
           [#:style style plot-pen-style/c (line-style)]
           [#:alpha alpha (real-in 0 1) (line-alpha)]
-          [#:label label (or/c string? #f) #f]
+          [#:label label (or/c string? pict? #f) #f]
           ) renderer3d?]{
 Returns a renderer that draws connected lines.
 The @racket[parametric3d] function is defined in terms of this one.
+
+@history[#:changed "7.9" "Added support for pictures for #:label"]
 }
 
 @defproc[(parametric3d
@@ -113,14 +119,16 @@ The @racket[parametric3d] function is defined in terms of this one.
           [#:width width (>=/c 0) (line-width)]
           [#:style style plot-pen-style/c (line-style)]
           [#:alpha alpha (real-in 0 1) (line-alpha)]
-          [#:label label (or/c string? #f) #f]
+          [#:label label (or/c string? pict? #f) #f]
           ) renderer3d?]{
 Returns a renderer that plots a vector-valued function of time. For example,
 @interaction[#:eval plot-eval
                     (require (only-in plot/utils 3d-polar->3d-cartesian))
                     (plot3d (parametric3d (λ (t) (3d-polar->3d-cartesian (* t 80) t 1))
                                           (- pi) pi #:samples 3000 #:alpha 0.5)
                             #:altitude 25)]
+
+@history[#:changed "7.9" "Added support for pictures for #:label"]
 }
 
 @section{3D Surface Renderers}
@@ -137,14 +145,16 @@ Returns a renderer that plots a vector-valued function of time. For example,
           [#:line-width line-width (>=/c 0) (surface-line-width)]
           [#:line-style line-style plot-pen-style/c (surface-line-style)]
           [#:alpha alpha (real-in 0 1) (surface-alpha)]
-          [#:label label (or/c string? #f) #f]
+          [#:label label (or/c string? pict? #f) #f]
           ) renderer3d?]{
 Returns a renderer that plots a two-input, one-output function. For example,
 @interaction[#:eval plot-eval (plot3d (list (surface3d (λ (x y) (+ (sqr x) (sqr y))) -1 1 -1 1
-                                                       #:label "z = x^2 + y^2")
+                                                       #:label "z = x² + y²")
                                             (surface3d (λ (x y) (- (+ (sqr x) (sqr y)))) -1 1 -1 1
                                                        #:color 4 #:line-color 4
-                                                       #:label "z = -x^2 - y^2")))]
+                                                       #:label "z = -x² - y²")))]
+
+@history[#:changed "7.9" "Added support for pictures for #:label"]
 }
 
 @defproc[(polar3d
@@ -159,7 +169,7 @@ Returns a renderer that plots a two-input, one-output function. For example,
           [#:line-width line-width (>=/c 0) (surface-line-width)]
           [#:line-style line-style plot-pen-style/c (surface-line-style)]
           [#:alpha alpha (real-in 0 1) (surface-alpha)]
-          [#:label label (or/c string? #f) #f]
+          [#:label label (or/c string? pict? #f) #f]
           ) renderer3d?]{
 Returns a renderer that plots a function from longitude and latitude to radius.
 @racket[(f θ ϕ)] → @racket[r]
@@ -181,6 +191,8 @@ Combining polar function renderers allows faking latitudes or longitudes in larg
                                              #:line-style 'transparent #:alpha 2/3)
                                     (polar3d f2 #:color "navajowhite"
                                              #:line-style 'transparent #:alpha 2/3))))]
+
+@history[#:changed "7.9" "Added support for pictures for #:label"]
 }
 
 @defproc[(parametric-surface3d
@@ -199,7 +211,7 @@ Combining polar function renderers allows faking latitudes or longitudes in larg
           [#:line-width line-width (>=/c 0) (surface-line-width)]
           [#:line-style line-style plot-pen-style/c (surface-line-style)]
           [#:alpha alpha (real-in 0 1) (surface-alpha)]
-          [#:label label (or/c string? #f) #f]
+          [#:label label (or/c string? pict? #f) #f]
           ) renderer3d?]{
 Returns a renderer that plots a two-input, one-output function. @racket[(f s t)] → @racket['(x y z)]
 
@@ -225,6 +237,8 @@ For example,
                          #:label "torus2"))
                        #:z-min -6 #:z-max 6
                        #:altitude 22)]
+
+@history[#:changed "7.9" "Added support for pictures for #:label"]
 }
 
 @defproc[(polygons3d
@@ -238,7 +252,7 @@ For example,
           [#:line-width line-width (>=/c 0) (surface-line-width)]
           [#:line-style line-style plot-pen-style/c (surface-line-style)]
           [#:alpha alpha (real-in 0 1) (surface-alpha)]
-          [#:label label (or/c string? #f) #f]
+          [#:label label (or/c string? pict? #f) #f]
           ) renderer3d?]{
 Returns a renderer that draws polygons.
 The @racket[parametric-surface3d] function is defined in terms of this one.
@@ -248,6 +262,8 @@ The @racket[parametric-surface3d] function is defined in terms of this one.
                                                   (list (list 1 0 0)(list 0 1 0)(list 0 0 0))))
                                 #:angle 355
                                 #:altitude 30)]
+
+@history[#:changed "7.9" "Added support for pictures for #:label"]
 }
 
 @section{3D Contour (Isoline) Renderers}
@@ -262,7 +278,7 @@ The @racket[parametric-surface3d] function is defined in terms of this one.
           [#:width width (>=/c 0) (line-width)]
           [#:style style plot-pen-style/c (line-style)]
           [#:alpha alpha (real-in 0 1) (line-alpha)]
-          [#:label label (or/c string? #f) #f]
+          [#:label label (or/c string? pict? #f) #f]
           ) renderer3d?]{
 Returns a renderer that plots a single contour line on the surface of a function.
 
@@ -273,6 +289,8 @@ This function is not terribly useful by itself, but can be when combined with ot
                     (define (saddle x y) (- (sqr x) (sqr y)))
                     (plot3d (list (surface3d saddle -1 1 -1 1)
                                   (isoline3d saddle 1/4 #:width 2 #:style 'long-dash)))]
+
+@history[#:changed "7.9" "Added support for pictures for #:label"]
 }
 
 @defproc[(contours3d
@@ -286,7 +304,7 @@ This function is not terribly useful by itself, but can be when combined with ot
           [#:widths widths (pen-widths/c (listof real?)) (contour-widths)]
           [#:styles styles (plot-pen-styles/c (listof real?)) (contour-styles)]
           [#:alphas alphas (alphas/c (listof real?)) (contour-alphas)]
-          [#:label label (or/c string? #f) #f]
+          [#:label label (or/c string? pict? #f) #f]
           ) renderer3d?]{
 Returns a renderer that plots contour lines on the surface of a function.
 
@@ -295,7 +313,9 @@ In particular, when @(racket levels) is @(racket 'auto), contour values correspo
 
 For example,
 @interaction[#:eval plot-eval (plot3d (contours3d (λ (x y) (+ (sqr x) (sqr y))) -1.1 1.1 -1.1 1.1
-                                                  #:label "z = x^2 + y^2"))]
+                                                  #:label "z = x² + y²"))]
+
+@history[#:changed "7.9" "Added support for pictures for #:label"]
 }
 
 @defproc[(contour-intervals3d
@@ -314,15 +334,17 @@ For example,
           [#:contour-widths contour-widths (pen-widths/c (listof real?)) (contour-widths)]
           [#:contour-styles contour-styles (plot-pen-styles/c (listof real?)) (contour-styles)]
           [#:alphas alphas (alphas/c (listof ivl?)) (contour-interval-alphas)]
-          [#:label label (or/c string? #f) #f]
+          [#:label label (or/c string? pict? #f) #f]
           ) renderer3d?]{
 Returns a renderer that plots contour intervals and contour lines on the surface of a function.
 The appearance keyword arguments are interpreted identically to the appearance keyword arguments to @(racket contour-intervals).
 
 For example,
 @interaction[#:eval plot-eval (plot3d (contour-intervals3d (λ (x y) (+ (sqr x) (sqr y)))
                                                            -1.1 1.1 -1.1 1.1
-                                                           #:label "z = x^2 + y^2"))]
+                                                           #:label "z = x² + y²"))]
+
+@history[#:changed "7.9" "Added support for pictures for #:label"]
 }
 
 @section{3D Isosurface Renderers}
@@ -339,7 +361,7 @@ For example,
           [#:line-width line-width (>=/c 0) (surface-line-width)]
           [#:line-style line-style plot-pen-style/c (surface-line-style)]
           [#:alpha alpha (real-in 0 1) (surface-alpha)]
-          [#:label label (or/c string? #f) #f]
+          [#:label label (or/c string? pict? #f) #f]
           ) renderer3d?]{
 Returns a renderer that plots the surface of constant output value of the function @(racket f). The argument @(racket d) is the constant value.
 
@@ -348,6 +370,8 @@ For example, a sphere is all the points in which the Euclidean distance function
                                        (λ (x y z) (sqrt (+ (sqr x) (sqr y) (sqr z)))) 1
                                        -1 1 -1 1 -1 1)
                                       #:altitude 25)]
+
+@history[#:changed "7.9" "Added support for pictures for #:label"]
 }
 
 @defproc[(isosurfaces3d
@@ -364,7 +388,7 @@ For example, a sphere is all the points in which the Euclidean distance function
           [#:line-widths line-widths (pen-widths/c (listof real?)) (isosurface-line-widths)]
           [#:line-styles line-styles (plot-pen-styles/c (listof real?)) (isosurface-line-styles)]
           [#:alphas alphas (alphas/c (listof real?)) (isosurface-alphas)]
-          [#:label label (or/c string? #f) #f]
+          [#:label label (or/c string? pict? #f) #f]
           ) renderer3d?]{
 Returns a renderer that plots multiple isosurfaces. The appearance keyword arguments are interpreted similarly to those of @(racket contours).
 
@@ -377,6 +401,8 @@ Use this to visualize functions from three inputs to one output; for example:
                             #:z-min -2 #:z-max 2)]
 
 If it helps, think of the output of @(racket f) as a density or charge.
+
+@history[#:changed "7.9" "Added support for pictures for #:label"]
 }
 
 @section{3D Rectangle Renderers}
@@ -392,7 +418,7 @@ If it helps, think of the output of @(racket f) as a density or charge.
           [#:line-width line-width (>=/c 0) (rectangle3d-line-width)]
           [#:line-style line-style plot-pen-style/c (rectangle-line-style)]
           [#:alpha alpha (real-in 0 1) (rectangle-alpha)]
-          [#:label label (or/c string? #f) #f]
+          [#:label label (or/c string? pict? #f) #f]
           ) renderer3d?]{
 Returns a renderer that draws rectangles.
 
@@ -415,6 +441,8 @@ This can be used to draw histograms; for example,
                                                (vector x-ivl y-ivl (ivl 0 z)))))
                                           #:alpha 3/4
                                           #:label "Appx. 2D Normal"))]
+
+@history[#:changed "7.9" "Added support for pictures for #:label"]
 }
 
 @defproc[(discrete-histogram3d
@@ -430,7 +458,7 @@ This can be used to draw histograms; for example,
           [#:line-width line-width (>=/c 0) (rectangle3d-line-width)]
           [#:line-style line-style plot-pen-style/c (rectangle-line-style)]
           [#:alpha alpha (real-in 0 1) (rectangle-alpha)]
-          [#:label label (or/c string? #f) #f]
+          [#:label label (or/c string? pict? #f) #f]
           [#:add-x-ticks? add-x-ticks? boolean? #t]
           [#:add-y-ticks? add-y-ticks? boolean? #t]
           [#:x-far-ticks? x-far-ticks? boolean? #f]
@@ -443,6 +471,8 @@ Missing pairs are not drawn; for example,
                     (plot3d (discrete-histogram3d '(#(a a 1) #(a b 2) #(b b 3))
                                                   #:label "Missing (b,a)"
                                                   #:color 4 #:line-color 4))]
+
+@history[#:changed "7.9" "Added support for pictures for #:label"]
 }
 
 @defproc[(stacked-histogram3d

plot-doc/plot/scribblings/renderer3d.scrbl

@@ -3,6 +3,7 @@
 ;; Functions that create legend entries and lists of legend entries.
 
 (require racket/class racket/match racket/list racket/string
+         (only-in typed/pict pict)
          "type-doc.rkt"
          "math.rkt"
          "format.rkt"
@@ -14,15 +15,15 @@
 ;; ===================================================================================================
 ;; Line legends
 
-(:: line-legend-entry (-> String Plot-Color Nonnegative-Real Plot-Pen-Style legend-entry))
+(:: line-legend-entry (-> (U String pict) Plot-Color Nonnegative-Real Plot-Pen-Style legend-entry))
 (define (line-legend-entry label color width style)
   (legend-entry label (λ (pd x-size y-size)
                         (define y (* 1/2 y-size))
                         (send pd set-pen color width style)
                         (send pd set-alpha 1)
                         (send pd draw-line (vector (ann 0 Real) y) (vector x-size y)))))
 
-(:: line-legend-entries (-> String (Listof Real) (Listof String)
+(:: line-legend-entries (-> (U String pict) (Listof Real) (Listof String)
                             (Plot-Colors (Listof Real))
                             (Pen-Widths (Listof Real))
                             (Plot-Pen-Styles (Listof Real))
@@ -51,7 +52,7 @@
 ;; ===================================================================================================
 ;; Rectangle legends
 
-(:: rectangle-legend-entry (-> String
+(:: rectangle-legend-entry (-> (U String pict)
                                Plot-Color Plot-Brush-Style
                                Plot-Color Nonnegative-Real Plot-Pen-Style
                                legend-entry))
@@ -63,7 +64,7 @@
                         (send pd draw-rect (vector (ivl 0 x-size) (ivl 0 y-size))))))
 
 (:: rectangle-legend-entries
-    (-> String (Listof Real)
+    (-> (U String pict) (Listof Real)
         (Plot-Colors (Listof Real)) (Plot-Brush-Styles (Listof Real))
         (Plot-Colors (Listof Real)) (Pen-Widths (Listof Real)) (Plot-Pen-Styles (Listof Real))
         (Listof legend-entry)))
@@ -97,7 +98,7 @@
 ;; ===================================================================================================
 ;; Interval legends
 
-(:: interval-legend-entry (-> String
+(:: interval-legend-entry (-> (U String pict)
                               Plot-Color Plot-Brush-Style
                               Plot-Color Nonnegative-Real Plot-Pen-Style
                               Plot-Color Nonnegative-Real Plot-Pen-Style
@@ -123,7 +124,7 @@
                               (vector x-size (ann 0 Real))))))
 
 (:: interval-legend-entries
-    (-> String (Listof ivl) (Listof String)
+    (-> (U String pict) (Listof ivl) (Listof String)
         (Plot-Colors (Listof ivl)) (Plot-Brush-Styles (Listof ivl))
         (Plot-Colors (Listof ivl)) (Pen-Widths (Listof ivl)) (Plot-Pen-Styles (Listof ivl))
         (Plot-Colors (Listof ivl)) (Pen-Widths (Listof ivl)) (Plot-Pen-Styles (Listof ivl))
@@ -178,7 +179,7 @@
 ;; ===================================================================================================
 ;; Point legends
 
-(:: point-legend-entry (-> String Point-Sym Plot-Color Plot-Color Nonnegative-Real Nonnegative-Real
+(:: point-legend-entry (-> (U String pict) Point-Sym Plot-Color Plot-Color Nonnegative-Real Nonnegative-Real
                            legend-entry))
 (define (point-legend-entry label sym color fill-color size line-width)
   (legend-entry label (λ (pd x-size y-size)
@@ -188,7 +189,7 @@
                         (send pd draw-glyphs
                               (list (vector (* 1/2 x-size) (* 1/2 y-size))) sym size))))
 
-(:: arrow-legend-entry (-> String Plot-Color Nonnegative-Real Plot-Pen-Style legend-entry))
+(:: arrow-legend-entry (-> (U String pict) Plot-Color Nonnegative-Real Plot-Pen-Style legend-entry))
 (define (arrow-legend-entry label color line-width line-style)
   (legend-entry label (λ (pd x-size y-size)
                         (send pd set-pen color line-width line-style)