9 Plot Contracts

6.2.900.17

9 Plot Contracts

package: plot-lib

9.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.

procedure
(treeof elem-contract) → contract?
elem-contract : contract?

Identifies values that meet the contract elem-contract, lists of such values, lists of lists, and so on.

9.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.

9.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
(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-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
(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 →

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

9.1	Plot Element Contracts
9.2	Appearance Argument Contracts
9.3	Appearance Argument List Contracts