10 Plot Contracts

▼ |  | PLo T: Graph Plotting

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

► | 10 | Plot Contracts

10.1 | Plot Element Contracts
10.2 | Appearance Argument Contracts
10.3 | Appearance Argument List Contracts

On this page:

10.1`` Plot Element Contracts
renderer2d?
renderer3d?
nonrenderer?
10.2`` Appearance Argument Contracts
anchor/ c
color/ c
plot-color/ c
plot-pen-style/ c
plot-brush-style/ c
font-family/ c
point-sym/ c
known-point-symbols
10.3`` Appearance Argument List Contracts
maybe-function/ c
maybe-apply
plot-colors/ c
plot-pen-styles/ c
pen-widths/ c
plot-brush-styles/ c
alphas/ c
labels/ c

5.3.6
top ← prev up next →

### 10`` Plot Contracts

#### 10.1`` Plot Element Contracts

> procedure (renderer2d? value) → boolean?
> value : any/c

Returns #t if value is a 2D renderer; that is, if plot can plot value. See 2D Renderers for functions that construct them.

> procedure (renderer3d? value) → boolean?
> value : any/c

Returns #t if value is a 3D renderer; that is, if plot3d can plot value. See 3D Renderers for functions that construct them.

> procedure (nonrenderer? value) → boolean?
> value : any/c

Returns #t if value is a nonrenderer. See Nonrenderers for functions that construct them.

#### 10.2`` Appearance Argument Contracts

> > > value anchor/c : contract?
> > = |
> > (one-of/c 'top-left 'top 'top-right
> > 'left 'center 'right
> > 'bottom-left 'bottom 'bottom-right)

> The contract for anchor arguments and parameters, such as plot-legend-anchor.

> > > value color/c : contract?
> > = |
> > (or/c (list/c real? real? real?)
> > string? symbol?
> > (is-a?/c color%))

> A contract for very flexible color arguments. Functions that accept a color/c almost always convert it to an RGB triplet using ->color.

> > > value plot-color/c : contract?
> = | (or/c exact-integer? color/c)

> The contract for #:color arguments, and parameters such as line-color and surface-color. For the meaning of integer colors, see ->pen-color and ->brush-color.

> > > value plot-pen-style/c : contract?
> > = |
> > (or/c exact-integer?
> > (one-of/c 'transparent 'solid 'dot 'long-dash
> > 'short-dash 'dot-dash))

> The contract for #:style arguments (when they refer to lines), and paramters such as line-style. For the meaning of integer pen styles, see ->pen-style.

> > > value plot-brush-style/c : contract?
> > = |
> > (or/c exact-integer?
> > (one-of/c 'transparent 'solid
> > 'bdiagonal-hatch 'fdiagonal-hatch 'crossdiag-hatch
> > 'horizontal-hatch 'vertical-hatch 'cross-hatch))

> The contract for #:style arguments (when they refer to fills), and parameters such as interval-style. For the meaning of integer brush styles, see ->brush-style.

> value font-family/c : flat-contract?

Identifies legal font family values. The same as font-family/c from racket/draw.

> > > value point-sym/c : contract?
> = | (or/c char? string? integer? (apply one-of/c known-point-symbols))

> The contract for the #:sym arguments in points and points3d, and the parameter point-sym.

> > > value known-point-symbols : (listof symbol?)
> > = |
> > (list 'dot 'point 'pixel
> > 'plus 'times 'asterisk
> > '5asterisk 'odot 'oplus
> > 'otimes 'oasterisk 'o5asterisk
> > 'circle 'square 'diamond
> > 'triangle 'fullcircle 'fullsquare
> > 'fulldiamond 'fulltriangle 'triangleup
> > 'triangledown 'triangleleft 'triangleright
> > 'fulltriangleup 'fulltriangledown 'fulltriangleleft
> > 'fulltriangleright 'rightarrow 'leftarrow
> > 'uparrow 'downarrow '4star
> > '5star '6star '7star
> > '8star 'full4star 'full5star
> > 'full6star 'full7star 'full8star
> > 'circle1 'circle2 'circle3
> > 'circle4 'circle5 'circle6
> > 'circle7 'circle8 'bullet
> > 'fullcircle1 'fullcircle2 'fullcircle3
> > 'fullcircle4 'fullcircle5 'fullcircle6
> > 'fullcircle7 'fullcircle8)

> A list containing the symbols that are valid points symbols.

#### 10.3`` Appearance Argument List Contracts

> > > procedure (maybe-function/c in-contract out-contract) → contract?
> > > in-contract : contract?
> > > out-contract : contract?
> = | (or/c out-contract (in-contract . -> . out-contract))

> Returns a contract that accepts either a function from in-contract to out-contract, or a plain out-contract value.

> > > (require racket/contract)
> > > (define/contract (maybe-function-of-real-consumer x)
> > ((maybe-function/c real? real?) . -> . real?)
> > (maybe-apply x 10))
> > > (maybe-function-of-real-consumer 4)
> > 4
> > > (maybe-function-of-real-consumer (λ (x) x))
> > 10

> Many plot functions, such as contours and isosurfaces3d, optionally take lists of appearance values (such as (listof plot-color/c)) as arguments. A very flexible argument contract would accept functions that produce lists of appearance values. For example, contours would accept any f with contract (-> (listof real?) (listof plot-color/c)) for its #:colors argument. When rendering a contour plot, contours would apply f to a list of the contour z values to get the contour colors.

> However, most uses do not need this flexibility. Therefore, plot’s functions accept either a list of appearance values or a function from a list of appropriate values to a list of appearance values. The maybe-function/c function constructs contracts for such arguments.

> In plot functions, if in-contract is a listof contract, the output list’s length need not be the same as the input list’s length. If it is shorter, the appearance values will cycle; if longer, the tail will not be used.

> procedure (maybe-apply f arg) → any/c
> f : (maybe-function/c any/c any/c)
> arg : any/c

If f is a function, applies f to args; otherwise returns f.

This is used inside many renderer-producing plot functions to convert maybe-function/c values to lists of appearance values.

> > > procedure (plot-colors/c in-contract) → contract?
> > > in-contract : contract?
> = | (maybe-function/c in-contract (listof plot-color/c))

> Returns a contract for #:colors arguments, as in contours and contour-intervals. See maybe-function/c for a discussion of the returned contract.

> The following example sends a list-valued (plot-colors/c ivl?) to contour-intervals, which then cycles through the colors:

> > > (plot (contour-intervals (λ (x y) (+ x y)) 0 1 0 1
> > #:colors '(1 2)))

> This is equivalent to sending (λ _ '(1 2)).

> The next example is more sophisticated: it sends a function-valued (plot-colors/c ivl?) to contour-intervals. The function constructs colors from the values of the contour intervals.

> > > (define (brown-interval-colors ivls)
> > (define z-size (- (ivl-max (last ivls))
> > (ivl-min (first ivls))))
> > (for/list ([i (in-list ivls)])
> > (match-define (ivl z-min z-max) i)
> > (define z-mid (/ (* 1/2 (+ z-min z-max)) z-size))
> > (list (* 255 z-mid) (* 128 z-mid) (* 64 z-mid))))
> > > (plot (contour-intervals (λ (x y) (+ x y)) 0 1 0 1
> > #:colors brown-interval-colors))

> > > procedure (plot-pen-styles/c in-contract) → contract?
> > > in-contract : contract?
> = | (maybe-function/c in-contract (listof plot-pen-style/c))

> Like plot-colors/c, but for line styles.

> > > procedure (pen-widths/c in-contract) → contract?
> > > in-contract : contract?
> = | (maybe-function/c in-contract (listof (>=/c 0)))

> Like plot-colors/c, but for line widths.

> > > procedure (plot-brush-styles/c in-contract) → contract?
> > > in-contract : contract?
> = | (maybe-function/c in-contract (listof plot-brush-style/c))

> Like plot-colors/c, but for fill styles.

> > > procedure (alphas/c in-contract) → contract?
> > > in-contract : contract?
> = | (maybe-function/c in-contract (listof (real-in 0 1)))

> Like plot-colors/c, but for opacities.

> > > procedure (labels/c in-contract) → contract?
> > > in-contract : contract?
> = | (maybe-function/c in-contract (listof (or/c string? #f)))

> Like plot-colors/c, but for strings. This is used, for example, to label stacked-histograms.

top ← prev up next →