Wumpus.Core.Picture

Construction of pictures, paths and text labels.

Note - the text label functions are only appropriate for single printed lines of text. Wumpus-Core does not interpret special white-space characters (i.e. tab or newline) and passes them forward into the output file. Renderers will then deal with white-space as they please, which is usually to ignore it.

Also, SVG output does not currently use space="preserve". It would be desirable to do so, as the PostScript generated by Wumpus can use doubled up spaces to print wide spaces. Unfortunately, SVG renderers seem to differ as to whether they can inherit space="preserve" from a top level attribute or whether it must be annotated on every <text> element. Wumpus considers the latter to be a too-high burden as it will expand the code size (this view may change).

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 order of printing - the front of the list is drawn first in the file. This also means that the front of the list is drawn at the back in the Z-Order.

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 -> Primitive u -> Primitive 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.

primPath :: Num u => Point2 u -> [AbsPathSegment u] -> PrimPath u

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

lineTo :: Point2 u -> AbsPathSegment u

lineTo : end_point -> path_segment

Create a straight-line PathSegment, the start point is implicitly the previous point in a path.

curveTo :: Point2 u -> Point2 u -> Point2 u -> AbsPathSegment u

curveTo : control_point1 * control_point2 * end_point -> path_segment

Create a curved PathSegment, the start point is implicitly the previous point in a path.

vertexPath :: Num u => [Point2 u] -> PrimPath u

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

curvedPath :: Num u => [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.

xlink :: XLink -> Primitive u -> Primitive u

Create a hyperlinked Primitive.

svgattr :: String -> String -> SvgAttr

Create an attribute for SVG output.

annotateGroup :: [SvgAttr] -> Primitive u -> Primitive u

Add SVG attribute annotations to a Primitive.

The primitive will be printed in a g (group) element labelled with the annotations.

annotateXLink :: XLink -> [SvgAttr] -> Primitive u -> Primitive u

Add SVG XLink and attribute annotations to a Primitive.

The primitive will be printed in a g (group) element, itself inside an a link.

primGroup :: [Primitive u] -> Primitive u

Group a list of Primitives.

This function throws a runtime error when supplied with an empty list.

primCat :: Primitive u -> Primitive u -> Primitive u

Concatenate two Primitives.

If both primitves are groups, then the groups are merged.

If one or other primitive is a group, the singleton is added into the group at the respective end.

Otherwise a group is formed adding both elements as children.

The Primitive type in Wumpus is a tree. In theory primCat can make flatter and wider trees than primGroup, though in practice this may have no noticeable benefit as Wumpus has very simple access patterns into the Primitive tree.

Constructing primitives

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

ostroke : rgb * stroke_attr * path -> Primitive

Create a open, stroked path.

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

cstroke : rgb * stroke_attr * path -> Primitive

Create a closed, stroked path.

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

zostroke : path -> Primitive

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

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

zcstroke : path -> Primitive

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

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

fill : rgb * path -> Primitive

Create a filled path.

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

zfill : path -> Primitive

Create a filled path coloured black.

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

fillStroke : fill_rgb * stroke_attr * stroke_rgb * path -> Primitive

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

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

clip : path * picture -> Picture

Clip a picture with respect to the supplied path.

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

textlabel : rgb * font_attr * string * baseline_left -> Primitive

Create a text label. The string should not contain newline or tab characters. Also double-spaces should not be used - a rendering agent for SVG will coalesce double-spaces into a single space. For precise control of spacing and kerning use hkernlabel.

The supplied point is the left baseline.

rtextlabel :: Num u => RGBi -> FontAttr -> String -> Point2 u -> Radian -> Primitive u

rtextlabel : rgb * font_attr * string * baseline_left * rotation -> Primitive

Create a text label rotated by the supplied angle about the baseline-left.

The supplied point is the left baseline.

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

ztextlabel : string * baseline_left -> Primitive

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

escapedlabel :: Num u => RGBi -> FontAttr -> EscapedText -> Point2 u -> Primitive u

escapedlabel : rgb * font_attr * escaped_text * baseline_left -> Primitive

Version of textlabel where the label text has already been parsed for special characters.

The supplied point is the left baseline.

rescapedlabel :: Num u => RGBi -> FontAttr -> EscapedText -> Point2 u -> Radian -> Primitive u

rescapedlabel : rgb * font_attr * escaped_text * baseline_left * rotation -> Primitive

Version of rtextlabel where the label text has already been parsed for special characters.

The supplied point is the left baseline.

zescapedlabel :: Num u => EscapedText -> Point2 u -> Primitive u

zescapedlabel : escaped_text * baseline_left -> Primitive

Version of ztextlabel where the label text has already been encoded.

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

hkernlabel : rgb * font_attr * kerning_chars * baseline_left -> Primitive

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.

** CAUTION ** - for SVG, hkernlabel generates a coordinate list of X-positions rather than a single start point. This is syntactically valid SVG, but it is not universally supported by renderers. Chrome support is fine, but Firefox and Safari currently seem lacking.

Also, note this feature does not have a directly compatible PostScript analogue. While the same picture is generated in both cases, the PostScript code is not particularly inefficient.

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

vkernlabel : rgb * font_attr * kerning_chars * baseline_left -> Primitive

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.

** CAUTION ** - for SVG, hkernlabel generates a coordinate list of Y-positions rather than a single start point. This is syntactically valid SVG, but it is not universally supported by renderers. Chrome support is fine, but Firefox and Safari currently seem lacking.

Also, note this feature does not have a directly compatible PostScript analogue. While the same picture is generated in both cases, the PostScript code is not particularly inefficient.

kernchar :: u -> Char -> KerningChar u

kernchar : displacement * char -> KerningChar

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

kernEscInt : displacement * char_code -> KerningChar

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

kernEscName :: u -> String -> KerningChar u

kernEscName : displacement * char_name -> KerningChar

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

strokeEllipse : rgb * stroke_attr * rx * ry * center -> Primtive

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!

rstrokeEllipse :: Num u => RGBi -> StrokeAttr -> u -> u -> Radian -> Point2 u -> Primitive u

rstrokeEllipse : rgb * stroke_attr * rx * ry * rotation * center -> Primtive

Create a stroked ellipse rotated about the center by theta.

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

fillEllipse : rgb * stroke_attr * rx * ry * center -> Primtive

Create a filled ellipse.

rfillEllipse :: Num u => RGBi -> u -> u -> Radian -> Point2 u -> Primitive u

rfillEllipse : colour * stroke_attr * rx * ry * rotation * center -> Primtive

Create a filled ellipse rotated about the center by theta.

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

zellipse : rx * ry * center -> Primtive

Create a black, filled ellipse.

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

fillStrokeEllipse : fill_rgb * stroke_attr * stroke_rgb * rx * ry * center -> Primtive

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

rfillStrokeEllipse :: Num u => RGBi -> StrokeAttr -> RGBi -> u -> u -> Radian -> Point2 u -> Primitive u

rfillStrokeEllipse : fill_rgb * stroke_attr * stroke_rgb * rx * ry * theta * center -> Primtive

Create a bordered (i.e. filled and stroked) ellipse rotated about the center by theta.

Operations

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

extendBoundary : x * y * picture -> Picture

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 : bbox_rgb * 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 : bbox_rgb * 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

illustrateControlPoints : control_point_rgb * primitive -> Picture

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

This has no effect on TextLabels. Nor does it draw Beziers of a hyperlinked object.

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