diff --git a/collects/plot/scribblings/plot2d.scrbl b/collects/plot/scribblings/plot2d.scrbl index 1bfe3c6a50..741744fb8b 100644 --- a/collects/plot/scribblings/plot2d.scrbl +++ b/collects/plot/scribblings/plot2d.scrbl @@ -88,8 +88,8 @@ Use @(racket plot-snip) to create an @(racket image-snip%) regardless of the val } @doc-apply[plot/dc]{ -Plots to an arbitrary device context. -The width and height of the plot are the device context's width and height. +Plots to an arbitrary device context, in the rectangle with width @(racket width), height @(racket height), and upper-left corner @(racket x),@(racket y). + Every @secref{plot2d} procedure is defined in terms of @(racket plot/dc). Use this if you need to continually update a plot on a @(racket canvas%), or to create other @(racket plot)-like functions with different backends. diff --git a/collects/plot/scribblings/plot3d.scrbl b/collects/plot/scribblings/plot3d.scrbl index 4eaa012ac1..220e4c1848 100644 --- a/collects/plot/scribblings/plot3d.scrbl +++ b/collects/plot/scribblings/plot3d.scrbl @@ -54,7 +54,8 @@ These procedures correspond with @(racket plot-file), @(racket plot-pict), @(ra } @doc-apply[plot3d/dc]{ -Plots to an arbitrary device context. The width and height of the plot are the device context's width and height. +Plots to an arbitrary device context, in the rectangle with width @(racket width), height @(racket height), and upper-left corner @(racket x),@(racket y). + Every @secref{plot3d} procedure is defined in terms of @(racket plot3d/dc). Use this if you need to continually update a plot on a @(racket canvas%), or to create other @(racket plot3d)-like functions with different backends. diff --git a/collects/plot/scribblings/renderer2d.scrbl b/collects/plot/scribblings/renderer2d.scrbl index ad8a7eb391..c4592606c0 100644 --- a/collects/plot/scribblings/renderer2d.scrbl +++ b/collects/plot/scribblings/renderer2d.scrbl @@ -11,9 +11,9 @@ Returns @racket[#t] if @racket[value] is a 2D @tech{renderer}; that is, if @rack The following functions create such renderers. } -@section[#:tag "renderer-function-arguments"]{2D Renderer Function Arguments} +@section[#:tag "renderer2d-function-arguments"]{2D Renderer Function Arguments} -Functions that return renderers always have these kinds of arguments: +Functions that return 2D renderers always have these kinds of arguments: @itemlist[ @item{Required (and possibly optional) arguments representing the graph to plot.} @item{Optional keyword arguments for overriding calculated bounds, with the default value @(racket #f).} diff --git a/collects/plot/scribblings/renderer3d.scrbl b/collects/plot/scribblings/renderer3d.scrbl index a3d06e7bf1..ff132df30b 100644 --- a/collects/plot/scribblings/renderer3d.scrbl +++ b/collects/plot/scribblings/renderer3d.scrbl @@ -11,12 +11,23 @@ Returns @racket[#t] if @racket[value] is a 3D @tech{renderer}; that is, if @rack The following functions create such renderers. } +@section[#:tag "renderer3d-function-arguments"]{3D Renderer Function Arguments} + +As with functions that return 2D renderers, functions that return 3D renderers always have these kinds of arguments: +@itemlist[ + @item{Required (and possibly optional) arguments representing the graph to plot.} + @item{Optional keyword arguments for overriding calculated bounds, with the default value @(racket #f).} + @item{Optional keyword arguments that determine the appearance of the plot.} + @item{The optional keyword argument @(racket #:label), which specifies the name of the renderer in the legend.}] + +See @secref["renderer2d-function-arguments"] for a detailed example. + @section{3D Point Renderers} @doc-apply[points3d]{ Returns a renderer that draws points in 3D space. -A scatter plot of points sampled uniformly from the surface of a sphere: +For example, a scatter plot of points sampled uniformly from the surface of a sphere: @interaction[#:eval plot-eval (let () (define (runif) (- (* 2 (random)) 1)) @@ -38,10 +49,11 @@ A scatter plot of points sampled uniformly from the surface of a sphere: @section{3D Line Renderers} @doc-apply[lines3d]{ - +Returns a renderer that draws connected lines, with points in 3D space. } @doc-apply[parametric3d]{ +Returns a renderer that plots a vector-valued function of time. For example, @interaction[#:eval plot-eval (plot3d (parametric3d (λ (t) (vector (* (cos (* 80 t)) (cos t)) @@ -55,6 +67,7 @@ A scatter plot of points sampled uniformly from the surface of a sphere: @section{3D Surface Renderers} @doc-apply[surface3d]{ +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") (surface3d (λ (x y) (- (+ (sqr x) (sqr y)))) -1 1 -1 1 @@ -63,9 +76,14 @@ A scatter plot of points sampled uniformly from the surface of a sphere: } @doc-apply[polar3d]{ +Returns a renderer that plots a function from latitude and longitude to radius. +Currently, latitudes range from @(racket 0) to @(racket (* 2 pi)), and longitudes from @(racket (* -1/2 pi)) to @(racket (* 1/2 pi)). + +A sphere is the graph of a polar function of constant radius: @interaction[#:eval plot-eval (plot3d (polar3d (λ (θ ρ) 1)) #:altitude 25)] +Combining polar function renderers allows faking latitudes or longitudes in larger ranges, to get, for example, a seashell plot: @interaction[#:eval plot-eval (let () (define (f1 θ ρ) (+ 1 (/ θ 2 pi) (* 1/8 (sin (* 8 ρ))))) @@ -81,12 +99,22 @@ A scatter plot of points sampled uniformly from the surface of a sphere: @section{3D Contour Renderers} @doc-apply[contours3d]{ +Returns a renderer that plots contour lines on the surface of a function. + +The appearance keyword arguments are interpreted identically to the appearance keyword arguments to @(racket contours). +In particular, when @(racket levels) is @(racket 'auto), contour values correspond precisely to @italic{z} axis ticks. + +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") #:legend-anchor 'top-left)] } @doc-apply[contour-intervals3d]{ +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") @@ -96,6 +124,9 @@ A scatter plot of points sampled uniformly from the surface of a sphere: @section{3D Isosurface Renderers} @doc-apply[isosurface3d]{ +Returns a renderer that plots the surface of constant output value of the function @(racket f). The argument @(racket d) is the constant value. + +For example, a sphere is all the points in which the Euclidean distance function returns the sphere's radius: @interaction[#:eval plot-eval (plot3d (isosurface3d (λ (x y z) (sqrt (+ (sqr x) (sqr y) (sqr z)))) 1 -1 1 -1 1 -1 1) @@ -103,6 +134,9 @@ A scatter plot of points sampled uniformly from the surface of a sphere: } @doc-apply[isosurfaces3d]{ +Returns a renderer that plots multiple isosurfaces. The appearance keyword arguments are interpreted similarly to those of @(racket contours). + +Use this to visualize functions from three inputs to one output; for example: @interaction[#:eval plot-eval (let () (define (saddle x y z) (- (sqr x) (* 1/2 (+ (sqr y) (sqr z))))) (plot3d (isosurfaces3d saddle #:d-min -1 #:d-max 1 #:label "") @@ -110,13 +144,19 @@ A scatter plot of points sampled uniformly from the surface of a sphere: #:y-min -2 #:y-max 2 #:z-min -2 #:z-max 2 #:legend-anchor 'top-left))] + +If it helps, think of the output of @(racket f) as a density or charge. } @section{3D Rectangle Renderers} @doc-apply[rectangles3d]{ +Returns a renderer that draws rectangles. + +This can be used to draw histograms; for example, @interaction[#:eval plot-eval (let () + (define (norm2 x y) (exp (* -1/2 (+ (sqr (- x 5)) (sqr y))))) (define x-ivls (bounds->intervals (linear-seq 2 8 10))) (define y-ivls (bounds->intervals (linear-seq -5 5 10))) (define x-mids (linear-seq 2 8 9 #:start? #f #:end? #f)) @@ -126,13 +166,16 @@ A scatter plot of points sampled uniformly from the surface of a sphere: [y (in-list y-mids)]) (for/list ([x-ivl (in-list x-ivls)] [x (in-list x-mids)]) - (define z (exp (* -1/2 (+ (sqr (- x 5)) (sqr y))))) + (define z (norm2 x y)) (vector x-ivl y-ivl (ivl 0 z))))) #:alpha 3/4 - #:label "Approximate 2D Normal")))] + #:label "Appx. 2D Normal")))] } @doc-apply[discrete-histogram3d]{ +Returns a renderer that draws discrete histograms on a two-valued domain. + +Missing pairs are not drawn; for example, @interaction[#:eval plot-eval (plot3d (discrete-histogram3d '(#(a a 1) #(a b 2) #(b b 3)) #:label "Missing (b,a)"