{"size": 8741, "ext": "scrbl", "max_stars_repo_path": "plot-doc/plot/scribblings/compat.scrbl", "max_stars_repo_name": "capfredf/plot", "max_stars_repo_stars_event_min_datetime": "2015-03-24T15:02:43.000Z", "max_stars_repo_stars_event_max_datetime": "2022-03-02T06:06:55.000Z", "max_issues_repo_path": "plot-doc/plot/scribblings/compat.scrbl", "max_issues_repo_name": "capfredf/plot", "max_issues_repo_issues_event_min_datetime": "2015-01-12T16:12:11.000Z", "max_issues_repo_issues_event_max_datetime": "2022-03-01T22:57:19.000Z", "max_forks_repo_path": "plot-doc/plot/scribblings/compat.scrbl", "max_forks_repo_name": "capfredf/plot", "max_forks_repo_forks_event_min_datetime": "2015-03-18T17:23:26.000Z", "max_forks_repo_forks_event_max_datetime": "2022-01-15T01:58:03.000Z"}
{"max_stars_count": 30, "max_issues_count": 94, "max_forks_count": 25, "avg_line_length": 44.5969387755, "max_line_length": 180, "alphanum_fraction": 0.597872097}
#lang scribble/manual

@(require (for-label racket
                     racket/gui/base
                     plot/compat))

@title[#:tag "compat"]{Compatibility Module}

@author["Alexander Friedman" "Jamie Raymond" "Neil Toronto"]

@defmodule[plot/compat]

This module provides an interface compatible with Plot 5.1.3 and earlier.

@bold{Do not use this module in new programs.}
It is likely to disappear in a near future release.

@bold{Do not try to use both @racketmodname[plot] and @racketmodname[plot/compat] in the same program.}
The new features in Plot 5.2 and later require the objects plotted in @racketmodname[plot] have to be a different data type than the objects plotted in @racketmodname[plot/compat].
They do not coexist easily, and trying to make them do so will result in errors.

@; ----------------------------------------

@section[#:tag "plot"]{Plotting}

@defproc[(plot [data (-> (is-a?/c 2d-plot-area%) void?)]
               [#:width width real? 400] [#:height height real? 400]
               [#:x-min x-min real? -5] [#:x-max x-max real? 5]
               [#:y-min y-min real? -5] [#:y-max y-max real? 5]
               [#:x-label x-label string? "X axis"] [#:y-label y-label string? "Y axis"]
               [#:title title string? ""]
               [#:fgcolor fgcolor (list/c byte? byte? byte?) '(0 0 0)]
               [#:bgcolor bgcolor (list/c byte? byte? byte?) '(255 255 255)]
               [#:lncolor lncolor (list/c byte? byte? byte?) '(255 0 0)]
               [#:out-file out-file (or/c path-string? output-port? #f) #f]
               ) (is-a?/c image-snip%)]{
Plots @racket[data] in 2D, where @racket[data] is generated by
functions like @racket[points] or @racket[line].

A @racket[data] value is represented as a procedure that takes a
@racket[2d-plot-area%] instance and adds plot information to it.

The result is an @racket[image-snip%] for the plot. If an @racket[#:out-file]
path or port is provided, the plot is also written as a PNG image to
the given path or port.

The @racket[#:lncolor] keyword argument is accepted for backward compatibility, but does nothing.
}

@defproc[(plot3d [data (-> (is-a?/c 3d-plot-area%) void?)]
                 [#:width width real? 400] [#:height height real? 400]
                 [#:x-min x-min real? -5] [#:x-max x-max real? 5]
                 [#:y-min y-min real? -5] [#:y-max y-max real? 5]
                 [#:z-min z-min real? -5] [#:z-max z-max real? 5]
                 [#:alt alt real? 30]
                 [#:az az real? 45]
                 [#:x-label x-label string? "X axis"]
                 [#:y-label y-label string? "Y axis"]
                 [#:z-label z-label string? "Z axis"]
                 [#:title title string? ""]
                 [#:fgcolor fgcolor (list/c byte? byte? byte?) '(0 0 0)]
                 [#:bgcolor bgcolor (list/c byte? byte? byte?) '(255 255 255)]
                 [#:lncolor lncolor (list/c byte? byte? byte?) '(255 0 0)]
                 [#:out-file out-file (or/c path-string? output-port? #f) #f]
                 ) (is-a?/c image-snip%)]{
Plots @racket[data] in 3D, where @racket[data] is generated by a
function like @racket[surface]. The arguments @racket[alt] and
@racket[az] set the viewing altitude (in degrees) and the azimuth
(also in degrees), respectively.

A 3D @racket[data] value is represented as a procedure that takes a
@racket[3d-plot-area%] instance and adds plot information to it.

The @racket[#:lncolor] keyword argument is accepted for backward compatibility, but does nothing.
}

@defproc[(points [vecs (listof (vectorof real?))]
                 [#:sym sym (or/c char? string? exact-integer? symbol?) 'square]
                 [#:color color plot-color? 'black]
                 ) (-> (is-a?/c 2d-plot-area%) void?)]{
Creates 2D plot data (to be provided to @racket[plot]) given a list
of points specifying locations. The @racket[sym] argument determines
the appearance of the points.  It can be a symbol, an ASCII character,
or a small integer (between -1 and 127).  The following symbols are
known: @racket['pixel], @racket['dot], @racket['plus],
@racket['asterisk], @racket['circle], @racket['times],
@racket['square], @racket['triangle], @racket['oplus], @racket['odot],
@racket['diamond], @racket['5star], @racket['6star],
@racket['fullsquare], @racket['bullet], @racket['full5star],
@racket['circle1], @racket['circle2], @racket['circle3],
@racket['circle4], @racket['circle5], @racket['circle6],
@racket['circle7], @racket['circle8], @racket['leftarrow],
@racket['rightarrow], @racket['uparrow], @racket['downarrow].
}

@defproc[(line [f (-> real? (or/c real? (vector/c real? real?)))]
               [#:samples samples (and/c exact-integer? (>=/c 2)) 150]
               [#:width width (>=/c 0) 1]
               [#:color color plot-color/c 'red]
               [#:mode mode (one-of/c 'standard 'parametric) 'standard]
               [#:mapping mapping (one-of/c 'cartesian 'polar) 'cartesian]
               [#:t-min t-min real? -5] [#:t-max t-max real? 5]
               ) (-> (is-a?/c 2d-plot-area%) void?)]{
Creates 2D plot data to draw a line.

The line is specified in either functional, i.e. @math{y = f(x)}, or
parametric, i.e. @math{x,y = f(t)}, mode.  If the function is
parametric, the @racket[mode] argument must be set to
@racket['parametric].  The @racket[t-min] and @racket[t-max] arguments
set the parameter when in parametric mode.
}

@defproc[(error-bars [vecs (listof (vector/c real? real? real?))]
                     [#:color color plot-color? 'black]
                     ) (-> (is-a?/c 2d-plot-area%) void?)]{
Creates 2D plot data for error bars given a list of vectors.  Each
vector specifies the center of the error bar @math{(x,y)} as the first
two elements and its magnitude as the third.
}

@defproc[(vector-field [f (-> (vector/c real? real?) (vector/c real? real?))]
                       [#:samples samples (and/c exact-integer? (>=/c 2)) 20]
                       [#:width width exact-positive-integer? 1]
                       [#:color color plot-color? 'red]
                       [#:style style (one-of/c 'scaled 'normalized 'real) 'scaled]
                       ) (-> (is-a?/c 2d-plot-area%) void?)]{
Creates 2D plot data to draw a vector-field from a vector-valued
function.
}

@defproc[(contour [f (-> real? real? real?)]
                  [#:samples samples exact-nonnegative-integer? 50]
                  [#:width width (>=/c 0) 1]
                  [#:color color plot-color/c 'black]
                  [#:levels levels (or/c (and/c exact-integer? (>=/c 2)) (listof real?)) 10]
                  ) (-> (is-a?/c 2d-plot-area%) void?)]{
Creates 2D plot data to draw contour lines, rendering a 3D function
a 2D graph cotours (respectively) to represent the value of the
function at that position.
}

@defproc[(shade [f (-> real? real? real?)]
                [#:samples samples (and/c exact-integer? (>=/c 2)) 50]
                [#:levels levels (or/c (and/c exact-integer? (>=/c 2)) (listof real?)) 10]
                ) (-> (is-a?/c 2d-plot-area%) void?)]{
Creates 2D plot data to draw like @racket[contour], except using
shading instead of contour lines.
}

@defproc[(surface [f (-> real? real? real?)]
                  [#:samples samples (and/c exact-integer? (>=/c 2)) 50]
                  [#:width width (>=/c 0) 1]
                  [#:color color plot-color/c 'black]
                  ) (-> (is-a?/c 3d-plot-area%) void?)]{
Creates 3D plot data to draw a 3D surface in a 2D box, showing only
the @italic{top} of the surface.
}

@defproc[(mix [data (-> any/c void?)] ...) (-> any/c void?)]{
Creates a procedure that calls each @racket[data] on its argument in
order. Thus, this function can composes multiple plot @racket[data]s
into a single data.
}

@defproc[(plot-color? [v any/c]) boolean?]{
Returns @racket[#t] if @racket[v] is one of the following symbols,
@racket[#f] otherwise:

@racketblock[
'white 'black 'yellow 'green 'aqua 'pink
'wheat 'grey 'blown 'blue 'violet 'cyan
'turquoise 'magenta 'salmon 'red
]
}

@; ----------------------------------------

@section{Miscellaneous Functions}

@defproc[(derivative [f (-> real? real?)] [h real? .000001]) (-> real? real?)]{
Creates a function that evaluates the numeric derivative of
@racket[f].  The given @racket[h] is the divisor used in the
calculation.
}

@defproc[(gradient [f (-> real? real? real?)] [h real? .000001])
         (-> (vector/c real? real?) (vector/c real? real?))]{
Creates a vector-valued function that computes the numeric gradient of
@racket[f].
}

@defproc[(make-vec [fx (-> real? real? real?)] [fy (-> real? real? real?)])
         (-> (vector/c real? real?) (vector/c real? real?))]{
Creates a vector-valued function from two parts.
}
