Wumpus.Core.Picture

Construction of pictures, paths and text labels.

Construction

frame :: (Real u, Floating u, FromPtSize u) => [Primitive u] -> Picture u

Lift a list of primitives to a composite picture.

The order of the list maps to the zorder - the front of the list is drawn at the top.

This function throws an error when supplied the empty list.

multi :: (Fractional u, Ord u) => [Picture u] -> Picture u

Place multiple pictures within the standard affine frame.

This function throws an error when supplied the empty list.

fontDeltaContext :: FontAttr -> Picture u -> Picture u

Update the font delta attributes for SVG output.

Note - fontDeltaContext does not set the font properties of elements in the supplied Picture, it is solely a mechanism to help reduce the code size of the generated SVG by factoring common attributes into a group (g) element. For instance, settting the font properties with fontDeltaContext can eliminate the repeated use of font-family and font-size in this code:

 <text font-family="Helvetica" font-size="12"> ... </text>
 <text font-family="Helvetica" font-size="12"> ... </text>
 <text font-family="Helvetica" font-size="12"> ... </text>

With the appropriate font delta context, this code will be generated:

 <g font-family="Helvetica" font-size="12">
   <text > ... </text>
   <text > ... </text>
   <text > ... </text>
 </g>

Wumpus ignores fontDeltaContext directives when generating PostScript. Unlike SVG, PostScript is not naturally nested, so introducing nesting with gsave and grestore is not likely to improve the PostScript Wumpus generates.

path :: Point2 u -> [PrimPathSegment u] -> PrimPath u

Create a Path from a start point and a list of PathSegments.

lineTo :: Point2 u -> PrimPathSegment u

Create a straight-line PathSegment.

curveTo :: Point2 u -> Point2 u -> Point2 u -> PrimPathSegment u

Create a curved PathSegment.

vertexPath :: [Point2 u] -> PrimPath u

Convert the list of vertices to a path of straight line segments.

curvedPath :: [Point2 u] -> PrimPath u

Convert a list of vertices to a path of curve segments. The first point in the list makes the start point, each curve segment thereafter takes 3 points. Spare points at the end are discarded.

xlinkhref :: String -> XLink

Create a hyperlink for SVG output.

Constructing primitives

ostroke :: Num u => RGBi -> StrokeAttr -> PrimPath u -> Primitive u

Create a open, stroked path.

cstroke :: Num u => RGBi -> StrokeAttr -> PrimPath u -> Primitive u

Create a closed, stroked path.

xostroke :: Num u => RGBi -> StrokeAttr -> XLink -> PrimPath u -> Primitive u

Create a open, stroked path with a hyperlink.

Note - hyperlinks are only rendered in SVG output.

xcstroke :: Num u => RGBi -> StrokeAttr -> XLink -> PrimPath u -> Primitive u

Create a closed, stroked path with a hyperlink.

Note - hyperlinks are only rendered in SVG output.

zostroke :: Num u => PrimPath u -> Primitive u

Create an open, stroked path using the default stroke attributes and coloured black.

zcstroke :: Num u => PrimPath u -> Primitive u

Create a closed stroked path using the default stroke attributes and coloured black.

fill :: Num u => RGBi -> PrimPath u -> Primitive u

Create a filled path.

xfill :: Num u => RGBi -> XLink -> PrimPath u -> Primitive u

Create a filled path with a hyperlink.

Note - hyperlinks are only rendered in SVG output.

zfill :: Num u => PrimPath u -> Primitive u

Create a filled path coloured black.

bordered :: Num u => RGBi -> StrokeAttr -> RGBi -> PrimPath u -> Primitive u

Create a closed path that is both filled and stroked (the fill is below in the zorder).

 fill colour * stroke attrs * stroke_colour * ...

xbordered :: Num u => RGBi -> StrokeAttr -> RGBi -> XLink -> PrimPath u -> Primitive u

Create a bordered, closed path with a hyperlink.

Note - hyperlinks are only rendered in SVG output.

clip :: (Num u, Ord u) => PrimPath u -> Picture u -> Picture u

Clip a picture with respect to the supplied path.

textlabel :: Num u => RGBi -> FontAttr -> String -> Point2 u -> Primitive u

Create a text label. The string should not contain newline or tab characters.

The supplied point is the left baseline.

xtextlabel :: Num u => RGBi -> FontAttr -> XLink -> String -> Point2 u -> Primitive u

Create a text label with a hyperlink. The string should not contain newline or tab characters.

The supplied point is the left baseline.

Note - hyperlinks are only rendered in SVG output.

ztextlabel :: Num u => String -> Point2 u -> Primitive u

Create a label where the font is Courier, text size is 14pt and colour is black.

wumpus_default_font :: FontAttr

Constant for the default font, which is Courier (aliased to Courier New for SVG) at 14 point.

hkernlabel :: Num u => RGBi -> FontAttr -> [KerningChar u] -> Point2 u -> Primitive u

Create a text label with horizontal kerning for each character.

Note - kerning is relative to the left baseline of the previous character, it is *not relative* to the right-hand boundary of the previous char. While the later would be more obvious it would take a lot of effort to implement as it would need access to the metrics encoded in font files.

Characters are expected to be drawn left to right, so displacements should not be negative. If the displacement is zero the character will be drawn ontop of the previous char.

The charcters should not contain newline or tab characters.

The supplied point is the left baseline.

vkernlabel :: Num u => RGBi -> FontAttr -> [KerningChar u] -> Point2 u -> Primitive u

Create a text label with vertical kerning for each character - the text is expected to grow downwards.

Note - kerning here is the measure between baselines of sucessive characters, it is *not* the distance between the bottom of one chararter and the top of the next character.

While the later maybe be more obvious from a drawing perspective, it would take a lot of effort to implement as it would need access to the metrics encoded in font files.

Characters are expected to be drawn downwards - a positive number represents the downward displacement - so displacements should not be negative. If the displacement is zero the character will be drawn ontop of the previous char.

The charcters should not contain newline or tab characters.

The supplied point is the left baseline of the top character.

xhkernlabel :: Num u => RGBi -> FontAttr -> XLink -> [KerningChar u] -> Point2 u -> Primitive u

Create a horizontally kerned text label with a hyperlink.

The is the hyperlink version of hkernlabel.

Note - hyperlinks are only rendered in SVG output.

xvkernlabel :: Num u => RGBi -> FontAttr -> XLink -> [KerningChar u] -> Point2 u -> Primitive u

Create a vertically drawn text label with a hyperlink.

The is the hyperlink version of vkernlabel.

Note - hyperlinks are only rendered in SVG output.

kernchar :: u -> Char -> KerningChar u

Construct a regular (i.e. non-special) Char along with its displacement from the left-baseline of the previous Char.

kernEscInt :: u -> Int -> KerningChar u

Construct a Char by its character code along with its displacement from the left-baseline of the previous Char.

kernEscName :: u -> String -> KerningChar u

Construct a Char by its character name along with its displacement from the left-baseline of the previous Char.

strokeEllipse :: Num u => RGBi -> StrokeAttr -> u -> u -> Point2 u -> Primitive u

Create a stroked ellipse.

Note - within Wumpus, ellipses are considered an unfortunate but useful optimization. Drawing good cicles with Beziers needs at least eight curves, but drawing them with PostScript's arc command needs a single operation. For drawings with many dots (e.g. scatter plots) it seems sensible to employ this optimization.

A deficiency of Wumpus's ellipse is that (non-uniformly) scaling a stroked ellipse also (non-uniformly) scales the pen it is drawn with. Where the ellipse is wider, the pen stroke will be wider too.

Avoid non-uniform scaling stroked ellipses!

fillEllipse :: Num u => RGBi -> u -> u -> Point2 u -> Primitive u

Create a filled ellipse.

xstrokeEllipse :: Num u => RGBi -> StrokeAttr -> XLink -> u -> u -> Point2 u -> Primitive u

Create a stroked ellipse with a hyperlink.

Note - hyperlinks are only rendered in SVG output.

xfillEllipse :: Num u => RGBi -> XLink -> u -> u -> Point2 u -> Primitive u

Create a filled ellipse.

Note - hyperlinks are only rendered in SVG output.

zellipse :: Num u => u -> u -> Point2 u -> Primitive u

Create a black, filled ellipse.

borderedEllipse :: Num u => RGBi -> StrokeAttr -> RGBi -> u -> u -> Point2 u -> Primitive u

Create a bordered (i.e. filled and stroked) ellipse.

Operations

extendBoundary :: (Num u, Ord u) => u -> u -> Picture u -> Picture u

Extend the bounding box of a picture.

The bounding box is both horizontal directions by x and both vertical directions by y. x and y must be positive This function cannot be used to shrink a boundary.

Picture composition

picOver :: (Num u, Ord u) => Picture u -> Picture u -> Picture u

picOver : picture -> picture -> picture

Draw the first picture on top of the second picture - neither picture will be moved.

picMoveBy :: (Num u, Ord u) => Picture u -> Vec2 u -> Picture u

picMoveBy : picture -> vector -> picture

Move a picture by the supplied vector.

picBeside :: (Num u, Ord u) => Picture u -> Picture u -> Picture u

picBeside : picture -> picture -> picture

Move the second picture to sit at the right side of the first picture

Illustrating pictures and primitives

printPicture :: (Num u, PSUnit u) => Picture u -> IO ()

Print the syntax tree of a Picture to the console.

illustrateBounds :: (Real u, Floating u, FromPtSize u) => RGBi -> Picture u -> Picture u

illustrateBounds : colour -> picture -> picture

Draw the picture on top of an image of its bounding box. The bounding box image will be drawn in the supplied colour.

illustrateBoundsPrim :: (Real u, Floating u, FromPtSize u) => RGBi -> Primitive u -> Picture u

illustrateBoundsPrim : colour -> primitive -> picture

Draw the primitive on top of an image of its bounding box. The bounding box image will be drawn in the supplied colour.

The result will be lifted from Primitive to Picture.

illustrateControlPoints :: (Real u, Floating u, FromPtSize u) => RGBi -> Primitive u -> Picture u

Generate the control points illustrating the Bezier curves within a picture.

This has no effect on TextLabels.

Pseudo control points are generated for ellipses, although strictly speaking ellipses do not use Bezier curves - they are implemented with PostScript's arc command.