Hylograph.Flow.Render.Engine
- Package
- purescript-hylograph-flow-render
- Repository
- afcondon/purescript-hylograph-flow-render
What any layout engine makes, and an engine as a value.
In 0.2 the renderer had one layout, the Sankey layout, and its types
were that layout's: a Layout was what layout returned, a picture
held Sankey Metrics and Widths, and the laws asserted Sankey facts.
A trial that drew the same flows with a second engine had to pass its result off as a Sankey layout. This module
is the layout result with the Sankey layout taken out of it, so that the
tree draws a Layout and the laws and measures read one without
knowing which engine made it.
It is designed for three engines and no others: the Sankey layout
(Hylograph.Flow.Render.Sankey), layered-layout (ports, right-angled
routes, no widths; its adapter lives outside this package,
which must not depend on it), and Stemma, a rewrite of Graphviz dot
(clusters, splines, ranks, top-down by default).
THE DECISIONS, each with its reason.
- A route is data (
Hylograph.Flow.Render.Route), and a placed edge has nopath,start,end,widthorstrokeof its own: each is read from the route (Route.svgPath,Route.start, …), so none can disagree with it. - Ports are placed on nodes (
PlacedNode.ports). A placed port is which port (its name, and whether it is one of the node's inputs or its outputs: a step may have an input and an output of one name), the side of the box it is on, and how far along that side: so it is on the box's boundary by construction, andportPointsays where. An engine places the ports it gives a place to and no others: the Sankey layout stacks a node's edges by where they go, not by port, and places none. Whether an edge meets a port is not a field of the edge: the edge already names its ports (Edge.fromPort,Edge.toPort, the core's), and the law is that where the node has that port placed the route ends there. directionis the layout's, not the tree's or the caller's: the engine knows which way it ran. The laws read "forward" and "aligned" by it, and the tree sets a node's words by it.layerstays aMaybe. It is the layer (dot's rank) the engine put a node in of the whole picture, and some placed nodes have none: the Sankey layout's shelf of nodes no edge touches, and every node of a layout made of several layerings (layered-layoutrun once for each open group). Both are real, so the case is not designed out; what is designed out is a layer that means something only within a part of the picture.- An engine is a value (
Engine): a name, the function, and what it promises. APictureis what every engine is told beside the projection: what is written in a node, and which groups are open. What only one engine can be told (the Sankey layout'sMetricsandWidths, the other's spacings) is that engine's own configuration, given where the engine is made (sankey metrics widths), and is not inPicture. Node breadth is among those: an engine may size a node as it likes, and the law about words reads the breadth a node was given from its own box. - Promises are a closed ADT (
Promise), one constructor for each law that holds of some engines and not of all. A promise carries what its law needs and no layout holds:WidthsConservedcarries the scale and the edge's quantity.Hylograph.Flow.Render.Lawschecks the general laws of every layout and, of an engine's layout, exactly the laws it promises: an engine that does not conserve widths is not asked to, so nothing has to be suppressed.
#PlacedPort Source
type PlacedPort = { along :: Number, flow :: PortFlow, name :: PortName, side :: Side }A port with a place. along: how far along side it is, in pixels
from the side's top (a left or right side) or its left end (a top or
bottom side).
#PlacedNode Source
type PlacedNode = { box :: Box, index :: Int, layer :: Maybe Int, node :: Node, ports :: Array PlacedPort, words :: Maybe SetWords }index: the node's place in the projection. layer: its layer in the
whole picture, where the engine gave it one (see the module's header).
words: what is written in it, as set, where the picture said
(Picture.words); Nothing where it did not. ports: the ports the
engine gave a place; none for an item, which has none.
#PlacedEdge Source
type PlacedEdge wire = { course :: Course, edge :: Edge wire, index :: Int, route :: Route }index: the edge's place in the projection. edge: the projection's
own, with the wires it stands for, so what is known of a wire can be
shown on it. route: the line it is drawn along, from its source to
its target.
#PlacedOutline Source
type PlacedOutline = { box :: Box, depth :: Int, group :: GroupId, header :: Number, members :: Array Int, name :: String, parent :: Maybe GroupId }An open group's outline. name: the group's, from the grouping.
header: the height of the strip at the top of box that is kept for
the name. depth: how many outlines it is inside; parent: the
nearest. members: the indices of the nodes inside it, however deep.
#Layout Source
type Layout wire = { direction :: Direction, edges :: Array (PlacedEdge wire), height :: Number, nodes :: Array PlacedNode, outlines :: Array PlacedOutline, width :: Number }Nodes and edges in the projection's order. An edge with an end that is
no node of the projection has no place and is left out (project makes
none). Outlines outermost first, so drawn in order an outline is over
the one that holds it; none unless the picture told of groups.
#OutlineMetrics Source
type OutlineMetrics = { header :: Number, padding :: Number }padding: from an outline to what is in it. header: the strip for
the group's name.
#Picture Source
type Picture = { groups :: Maybe Groups, lettering :: Lettering, outline :: OutlineMetrics, words :: Maybe (Node -> Words) }What every engine is told beside the projection. words: what is
written in each node, for the engine to wrap to the breadth it gives
the node and make room for; Nothing leaves every node as tall as the
engine makes it and its label to the tree, on one line. groups: the
open groups to outline; Nothing for none.
#plainPicture Source
plainPicture :: PictureNo words set and no group outlined.
#openPaths Source
openPaths :: Groups -> { nameOf :: GroupId -> String, pathOf :: ElementKey -> Array GroupId }The open groups a drawn element is in, outermost first, and every
group's name. A step is where Member puts it and an item where
Holds does; a closed group's step and its summary are in the groups
their group is in; an item a closed group holds that is drawn all the
same (an open step writes it) is in the open groups over that group.
An element no group holds is in none.
#Conservation Source
type Conservation wire = { pixelsPerUnit :: Number, unitsOf :: Edge wire -> Number }What the law of conserved widths needs and no layout holds: the pixels to one unit of width, and an edge's width in units.
#Promise Source
data Promise wireA law that holds of some engines' layouts and not of every layout; an
engine lists the ones it keeps. What each says exactly is in
Hylograph.Flow.Render.Laws.
FlowsForward: an edge not turned back runs with the flow, and where the projection has no cycle no edge is turned back.LayersAligned: the nodes of one layer stand in one line across the flow.RoutesOrthogonal: every route is straight legs along the axes.WidthsConserved: every route is a ribbon as broad as its quantity says, and at each node the ribbons of a side stand in the node, beside one another, and the node is as tall as the broader side.
Constructors
#run Source
run :: forall wire. Engine wire -> Picture -> Projection wire -> Layout wireAn engine's layout of a projection.
#engineName Source
engineName :: forall wire. Engine wire -> String