2 2D and 3D Plotting Procedures

▼ |  | Plot: Graph Plotting

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 | 2D and 3D Plotting Procedures

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

On this page:

2.1 GUI Plotting Procedures
plot
plot3d
plot-snip
plot3d-snip
plot-frame
plot3d-frame
2.2 Non-GUI Plotting Procedures
plot-file
plot3d-file
plot-pict
plot3d-pict
plot-bitmap
plot3d-bitmap
plot/ dc
plot3d/ dc
2.3 Pict-Plotting Work-a-Likes
plot
plot3d
2.4 Bitmap-Plotting Work-a-Likes
plot
plot3d

8.18
top contents ← prev up next →

## 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 (and/c (is-a?/c snip%) (is-a?/c plot-metrics<%>)) 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 (and/c (is-a?/c snip%) (is-a/c plot-metrics<%>)) 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.

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.

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> ...)
> → (and/c (is-a?/c 2d-plot-snip%) (is-a?/c plot-metrics<%>))
> <plot-argument> : <plot-argument-contract>

> procedure (plot3d-snip <plot-argument> ...)
> → (and/c (is-a?/c snip%) (is-a?/c plot-metrics<%>))
> <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> ...) → plot-pict?
> <plot-argument> : <plot-argument-contract>

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

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

> procedure (plot3d-bitmap <plot3d-argument> ...)
> → (and/c (is-a?/c bitmap%) (is-a?/c plot-metrics<%>))
> <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> ...) |
> → (is-a?/c plot-metrics<%>)
> 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> ...) |
> → (is-a?/c plot-metrics<%>)
> 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 contents ← prev up next →