10 Plot Contracts

10.1 Plot Element Contracts

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 : contract?

= (one-of/c 'default 'decorative 'roman  'script 'swiss           'modern  'symbol     'system)

Identifies legal font family values. See plot-font-family.

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.

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.