2 2D and 3D Plotting Procedures

8.1

2 2D and 3D Plotting Procedures

The plotting procedures exported by plot/no-gui produce bitmap% and pict instances, and write to files. They do not require racket/gui, so they work in headless environments; for example, a Linux terminal with DISPLAY unset.

The plot module re-exports everything exported by plot/no-gui, as well as plot, plot3d, and other procedures that create interactive plots and plot frames. Interactive plotting procedures can always be imported, but fail when called if there is no working display or racket/gui is not present.

Each 3D plotting procedure behaves the same way as its corresponding 2D procedure, but takes the additional keyword arguments #:z-min, #:z-max, #:angle, #:altitude and #:z-label.

2.1 GUI Plotting Procedures

(require plot)

package: plot-gui-lib

procedure
(plot renderer-tree
[ #:x-min x-min
#:x-max x-max
#:y-min y-min
#:y-max y-max
#:width width
#:height height
#:title title
#:x-label x-label
#:y-label y-label
#:aspect-ratio aspect-ratio
#:legend-anchor legend-anchor
#:out-file out-file
#:out-kind out-kind])
→ (or/c (is-a?/c snip%) void?)
  renderer-tree : (treeof (or/c renderer2d? nonrenderer?))
  x-min : (or/c rational? #f) = #f
  x-max : (or/c rational? #f) = #f
  y-min : (or/c rational? #f) = #f
  y-max : (or/c rational? #f) = #f
  width : exact-positive-integer? = (plot-width)
  height : exact-positive-integer? = (plot-height)
  title : (or/c string? pict? #f) = (plot-title)
  x-label : (or/c string? pict? #f) = (plot-x-label)
  y-label : (or/c string? pict? #f) = (plot-y-label)
   aspect-ratio : (or/c (and/c rational? positive?) #f)
= (plot-aspect-ratio)
  legend-anchor : legend-anchor/c = (plot-legend-anchor)
  out-file : (or/c path-string? output-port? #f) = #f
  out-kind : plot-file-format/c = 'auto

Plots a 2D renderer or list of renderers (or more generally, a tree of renderers), as returned by points, function, contours, discrete-histogram, and others.

By default, plot produces a Racket value that is displayed as an image and can be manipulated like any other value. For example, they may be put in lists:

> (parameterize ([plot-width    150]
                 [plot-height   150]
                 [plot-x-label  #f]
                 [plot-y-label  #f])
    (list (plot (function sin (- pi) pi))
          (plot (function sqr -2 2))))
'( )

When the parameter plot-new-window? is #t, plot opens a new window to display the plot and returns (void).

When #:out-file is given, plot writes the plot to a file using plot-file as well as returning a snip% or opening a new window.

When given, the x-min, x-max, y-min and y-max arguments determine the bounds of the plot, but not the bounds of the renderers. For example,

When given, the aspect-ratio argument defines the aspect ratio of the plot area, see plot-aspect-ratio for more details.

> (plot (function (λ (x) (sin (* 4 x))) -1 1)
#:x-min -1.5 #:x-max 1.5 #:y-min -1.5 #:y-max 1.5)

Here, the renderer draws in [-1,1] × [-1,1], but the plot area is [-1.5,1.5] × [-1.5,1.5].

Deprecated keywords. The #:fgcolor and #:bgcolor keyword arguments are currently supported for backward compatibility, but may not be in the future. Please set the plot-foreground and plot-background parameters instead of using these keyword arguments. The #:lncolor keyword argument is also accepted for backward compatibility but deprecated. It does nothing.

Changed in version 7.9 of package plot-gui-lib: Added support for pictures for #:title, #:x-label and #:y-label. And to plot the legend outside the plot-area with #:legend-anchor

Changed in version 8.1 of package plot-gui-lib: Added #:aspect-ratio

procedure
(plot3d renderer-tree
[ #:x-min x-min
#:x-max x-max
#:y-min y-min
#:y-max y-max
#:z-min z-min
#:z-max z-max
#:width width
#:height height
#:angle angle
#:altitude altitude
#:title title
#:x-label x-label
#:y-label y-label
#:z-label z-label
#:aspect-ratio aspect-ratio
#:legend-anchor legend-anchor
#:out-file out-file
#:out-kind out-kind])
→ (or/c (is-a?/c snip%) void?)
  renderer-tree : (treeof (or/c renderer3d? nonrenderer?))
  x-min : (or/c rational? #f) = #f
  x-max : (or/c rational? #f) = #f
  y-min : (or/c rational? #f) = #f
  y-max : (or/c rational? #f) = #f
  z-min : (or/c rational? #f) = #f
  z-max : (or/c rational? #f) = #f
  width : exact-positive-integer? = (plot-width)
  height : exact-positive-integer? = (plot-height)
  angle : real? = (plot3d-angle)
  altitude : real? = (plot3d-altitude)
  title : (or/c string? pict? #f) = (plot-title)
  x-label : (or/c string? pict? #f) = (plot-x-label)
  y-label : (or/c string? pict? #f) = (plot-y-label)
  z-label : (or/c string? pict? #f) = (plot-z-label)
   aspect-ratio : (or/c (and/c rational? positive?) #f)
= (plot-aspect-ratio)
  legend-anchor : legend-anchor/c = (plot-legend-anchor)
  out-file : (or/c path-string? output-port? #f) = #f
  out-kind : plot-file-format/c = 'auto

Plots a 3D renderer or list of renderers (or more generally, a tree of renderers), as returned by points3d, parametric3d, surface3d, isosurface3d, and others.

When the parameter plot-new-window? is #t, plot3d opens a new window to display the plot and returns (void).

When #:out-file is given, plot3d writes the plot to a file using plot3d-file as well as returning a snip% or opening a new window.

When given, the x-min, x-max, y-min, y-max, z-min and z-max arguments determine the bounds of the plot, but not the bounds of the renderers.

When given, the aspect-ratio argument defines the aspect ratio of the plot area, see plot-aspect-ratio for more details.

The #:az and #:alt keyword arguments are backward-compatible, deprecated aliases for #:angle and #:altitude, respectively.

Changed in version 7.9 of package plot-gui-lib: Added support for pictures for #:title, #:x-label and #:y-label. And to plot the legend outside the plot-area with #:legend-anchor

Changed in version 8.1 of package plot-gui-lib: Added #:aspect-ratio

procedure
(plot-snip <plot-argument> ...) → (is-a?/c 2d-plot-snip%)
<plot-argument> : <plot-argument-contract>

procedure
(plot3d-snip <plot-argument> ...) → (is-a?/c snip%)
<plot-argument> : <plot-argument-contract>

procedure
(plot-frame <plot-argument> ...) → (is-a?/c frame%)
<plot-argument> : <plot-argument-contract>

procedure
(plot3d-frame <plot-argument> ...) → (is-a?/c frame%)
<plot-argument> : <plot-argument-contract>

Plot to different GUI backends. These procedures accept the same arguments as plot and plot3d, except deprecated keywords, and #:out-file and #:out-kind.

Use plot-frame and plot3d-frame to create a frame% regardless of the value of plot-new-window?. The frame is initially hidden.

Use plot-snip and plot3d-snip to create an interactive snip% regardless of the value of plot-new-window?.

The snip% objects returned by plot-snip can be used to construct interactive plots. See Interactive Overlays for 2D plots for more details.

2.2 Non-GUI Plotting Procedures

(require plot/no-gui)

package: plot-lib

procedure
(plot-file renderer-tree
output
[ kind]
#:<plot-keyword> <plot-keyword> ...) → void?
  renderer-tree : (treeof (or/c renderer2d? nonrenderer?))
  output : (or/c path-string? output-port?)
  kind : plot-file-format/c = 'auto
  <plot-keyword> : <plot-keyword-contract>

procedure
(plot3d-file renderer-tree
output
[ kind]
#:<plot3d-keyword> <plot3d-keyword> ...) → void?
  renderer-tree : (treeof (or/c renderer3d? nonrenderer?))
  output : (or/c path-string? output-port?)
  kind : plot-file-format/c = 'auto
  <plot3d-keyword> : <plot3d-keyword-contract>

procedure
(plot-pict <plot-argument> ...) → pict?
<plot-argument> : <plot-argument-contract>

procedure
(plot3d-pict <plot3d-argument> ...) → pict?
<plot3d-argument> : <plot3d-argument-contract>

procedure
(plot-bitmap <plot-argument> ...) → (is-a?/c bitmap%)
<plot-argument> : <plot-argument-contract>

procedure
(plot3d-bitmap <plot3d-argument> ...) → (is-a?/c bitmap%)
<plot3d-argument> : <plot3d-argument-contract>

Plot to different non-GUI backends. These procedures accept the same arguments as plot and plot3d, except deprecated keywords, and #:out-file and #:out-kind.

Use plot-file or plot3d-file to save a plot to a file. When creating a JPEG file, the parameter plot-jpeg-quality determines its quality. When creating a PostScript or PDF file, the parameter plot-ps/pdf-interactive? determines whether the user is given a dialog to set printing parameters. (See post-script-dc% and pdf-dc%.) When kind is 'auto, plot-file and plot3d-file try to determine from the file name extension the kind of file to write.

Use plot-pict or plot3d-pict to create a pict. For example, this program creates a slide containing a 2D plot of a parabola:

#lang slideshow
(require plot)

(plot-font-size (current-font-size))
(plot-width (current-para-width))
(plot-height 600)
(plot-background-alpha 1/2)

(slide
#:title "A 2D Parabola"
(plot-pict (function sqr -1 1 #:label "y = x^2")))

Use plot-bitmap or plot3d-bitmap to create a bitmap%.

procedure
(plot/dc renderer-tree
dc
x
y
width
height
#:<plot-keyword> <plot-keyword> ...) → void?
  renderer-tree : (treeof (or/c renderer2d? nonrenderer?))
  dc : (is-a?/c dc<%>)
  x : real?
  y : real?
  width : (>=/c 0)
  height : (>=/c 0)
  <plot-keyword> : <plot-keyword-contract>

procedure
(plot3d/dc renderer-tree
dc
x
y
width
height
#:<plot3d-keyword> <plot3d-keyword> ...) → void?
  renderer-tree : (treeof (or/c renderer3d? nonrenderer?))
  dc : (is-a?/c dc<%>)
  x : real?
  y : real?
  width : (>=/c 0)
  height : (>=/c 0)
  <plot3d-keyword> : <plot3d-keyword-contract>

Plot to an arbitrary device context, in the rectangle with width width, height height, and upper-left corner x,y. These procedures accept the same arguments as plot and plot3d, except deprecated keywords, and #:out-file and #:out-kind.

Use these if you need to continually update a plot on a canvas%, or to create other plot-like functions with different backends.

2.3 Pict-Plotting Work-a-Likes

(require plot/pict)

package: plot-lib

When setting up an evaluator for a Scribble manual, require plot/pict instead of plot. Evaluation will produce picts instead of snips, which scale nicely in PDF-rendered documentation.

For example, this is how the evaluator for the Plot documentation is defined:

(define plot-eval
  (let ([eval  (make-base-eval)])
    (eval '(begin
             (require racket/math
                      racket/match
                      racket/list
                      racket/draw
                      racket/class
                      plot/pict
                      plot/utils)))
    eval))

If you use (require (for-label plot)), links in example code should resolve to documentation for the functions exported by plot.

procedure
(plot <plot-argument> ...) → pict?
<plot-argument> : <plot-argument-contract>

procedure
(plot3d <plot3d-argument> ...) → pict?
<plot3d-argument> : <plot3d-argument-contract>

Like the functions of the same name exported from plot, but these produce pict instances instead of interactive snips.

2.4 Bitmap-Plotting Work-a-Likes

(require plot/bitmap)

package: plot-lib

When plotting in an environment where bitmap% instances can be shown but snip% instances cannot (for example, on a web page that evaluates Racket code), require plot/bitmap instead of plot.

procedure
(plot <plot-argument> ...) → (is-a?/c bitmap%)
<plot-argument> : <plot-argument-contract>

procedure
(plot3d <plot3d-argument> ...) → (is-a?/c bitmap%)
<plot3d-argument> : <plot3d-argument-contract>

Like the functions of the same name exported from plot, but these produce bitmap% instances instead of interactive snips.

top ← prev up next →

1	Introduction
2	2D and 3D Plotting Procedures
3	2D Renderers
4	3D Renderers
5	Nonrenderers
6	Axis Transforms and Ticks
7	Plot Utilities
8	Plot and Renderer Parameters
9	Plot Contracts
10	Porting From Plot <= 5.1.3
11	Legacy Typed Interface
12	Compatibility Module

2.1	GUI Plotting Procedures
2.2	Non-GUI Plotting Procedures
2.3	Pict-Plotting Work-a-Likes
2.4	Bitmap-Plotting Work-a-Likes