On this page:
pict
child
explain
explain-child

1 Pict Datatype

A pict is a pict structure representing an image. Some functions, such as hline, create new simple picts. Other functions, such as ht-append, build new picts out of existing picts. In the latter case, the embedded picts retain their identity, so that offset-finding functions, such as lt-find, can find the offset of an embedded pict in a larger pict.

In addition to its drawing part, a pict has the following bounding box structure:

image

That is, the bounding box has a width w and a height h. For a single text line, d is descent below the baseline, and a+d=h. For multiple text lines (often created with a function like vc-append), a is the ascent of the top line, and d is the descent of the bottom line, so a+d<h. Many picts have d=0 and a=h.

In addition, a pict can have a last sub-pict that corresponds to the last item on the last line of text, so that extra lines can be added to the last line. In particular, the last element is useful for adding closing parentheses to a block of Racket code, where the last line of code not the longest line in the block.

The size information for a pict is computed when the pict is created. This strategy supports programs that create new picts though arbitrarily complex computations on the size and shape of existing picts. The functions pict-width, pict-height, pict-descent, and pict-ascent extract bounding box information from a pict.

A pict is a convertible datatype through the file/convertible protocol. Supported conversions include 'png-bytes, 'eps-bytes, 'pdf-bytes, 'svg-bytes, and variants such as 'png-bytes+bounds and 'png-bytes+bounds8.

A pict is serializable via racket/serialize, but serialization loses sub-pict information (preserving only the pict’s drawing and bounding box).

Changed in version 1.2 of package pict-lib: Added support for 'png-bytes+bounds, 'png-bytes+bounds8 and similar variants.
Changed in version 1.3: Enabled serialization.

struct

(struct pict (draw
    width
    height
    ascent
    descent
    children
    panbox
    last)
    #:extra-constructor-name make-pict)
  draw : any/c
  width : real?
  height : real?
  ascent : real?
  descent : real?
  children : (listof child?)
  panbox : (or/c #f any/c)
  last : (or/c #f pict-path?)
A pict structure is normally not created directly with make-pict. Instead, functions like text, hline, and dc are used to construct a pict.

The draw field contains the pict’s drawing information in an internal format. Roughly, the drawing information is a procedure that takes a dc<%> drawing context and an offset for the pict’s top-left corner (i.e., it’s bounding box’s top left corner relative to the dc<%> origin). The state of the dc<%> is intended to affect the pict’s drawing; for example, the pen and brush will be set for a suitable default drawing mode, and the dc<%> scale will be set to scale the resulting image. Use draw-pict (as opposed to pict-draw) to draw the picture.

The panbox field is internal and initialized to #f.

The last field indicates a pict within the children list (transitively) that can be treated as the last element of the last line in the pict. A #f value means that the pict is its own last sub-pict.

struct

(struct child (pict dx dy sx sy syx sxy)
    #:extra-constructor-name make-child)
  pict : pict?
  dx : real?
  dy : real?
  sx : real?
  sy : real?
  syx : real?
  sxy : real?
Records, for a pict constructed of other picts, the transformation to arrive at a inverted point in the composed pict from an inverted point in a constituent pict’s. An inverted point is a point relative to a pict’s lower-left corner with an increasing value moving upward.

A child structure is normally not created directly with make-child. Instead, functions like hc-append create child structures when combining picts to create a new one.

procedure

(explain p    
  [#:border bord    
  #:ascent asc    
  #:baseline base    
  #:scale s    
  #:line-width lw])  pict?
  p : pict-convertible?
  bord : (or/c #f string? (is-a?/c color%)) = "firered"
  asc : (or/c #f string? (is-a?/c color%)) = "seagreen"
  base : (or/c #f string? (is-a?/c color%)) = "royalblue"
  s : real? = 5
  lw : real? = 1
Draw a pict like p, but the pict’s bounding box is framed in the color bord, the baseline is draw in base, and the line defined by the ascent is drawn in asc. If any are #f then that part is not drawn. The pict is scaled up by s. The lines drawn are of width lw before scaling is applied.

Note that for single lines of text the baseline and ascent are the same, so only one line will be visible.

Examples:
> (define t (text "ij"))
> (define tt (vl-append t t))
> (explain t)

image

> (explain tt)

image

Added in version 1.10 of package pict-lib.

procedure

(explain-child p    
  path ...    
  [#:border bord    
  #:ascent asc    
  #:baseline base    
  #:scale s    
  #:line-width lw])  pict?
  p : pict-convertible?
  path : pict-path?
  bord : (or/c #f string? (is-a?/c color%)) = "firered"
  asc : (or/c #f string? (is-a?/c color%)) = "seagreen"
  base : (or/c #f string? (is-a?/c color%)) = "royalblue"
  s : real? = 5
  lw : real? = 1
Like explain, except the the explanation is drawn for some each inner pict of p, pointed to by path.

Examples:
> (define t1 (text "ij"))
> (define t2 (text "ij"))
> (define t3 (vl-append t1 t2))
> (explain-child t3 t3)

image

> (explain-child t3 t1)

image

> (explain-child t3 t2)

image

> (explain-child t3 t1 t2)

image

Added in version 1.10 of package pict-lib.