raumata

package module
v0.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 15, 2024 License: Apache-2.0 Imports: 12 Imported by: 0

README

Go Reference

Raumata - Network Map Renderer

Raumata (Māori: 'mesh') is a library to aid in the creation of network maps. It is essentially a specialized graphics package for network maps.

Example network map

Features

  • Grid-based Layout
  • Automatic Link Routing
  • Automatic Label Placement
  • SVG Output
  • Static Map Generator, make-map
Planned Features

These features are planned and may be implemented at some point in the future:

  • Additional Node Shapes
  • Additional Link Styles
  • Automatic Node Placement
  • Additional Output Formats

Documentation

Overview

Package raumata is a package for rendering network maps. It provides methods for decribing the network topology, automatically routing links, placing node labels, and rendering the map to an image.

The canvas sub-package provides a more general-purpose drawing interface, as well as an SVG renderer.

Example

This is a bare-minimum example of usage 

package main

import (
	"os"

	"github.com/REANNZ/raumata"
	"github.com/REANNZ/raumata/canvas"
)

func main() {
	// This would normally come from an outside source,
	// e.g. a JSON file or database
	networkTopology := &raumata.Topology{
		Nodes: map[raumata.NodeId]*raumata.Node{
			"ruru": {
				Id:  "ruru",
				Pos: &[2]int16{0, 0},
			},
			"kea": {
				Id:  "kea",
				Pos: &[2]int16{10, 5},
			},
			"kaka": {
				Id:  "kaka",
				Pos: &[2]int16{0, 10},
			},
		},
		Links: map[raumata.LinkId]*raumata.Link{
			"ruru-kea": {
				Id:   "ruru-kea",
				From: "ruru",
				To:   "kea",
			},
			"kea-kaka": {
				Id:   "kea-kaka",
				From: "kea",
				To:   "kaka",
			},
			"kaka-ruru": {
				Id:   "kaka-ruru",
				From: "kaka",
				To:   "ruru",
			},
		},
	}

	router := raumata.NewLinkRouter(networkTopology)
	router.RouteLinks()

	raumata.PlaceLabels(networkTopology)

	renderer := raumata.NewRenderer()

	drawCanvas := canvas.NewCanvas()

	renderer.RenderTopologyToCanvas(networkTopology, drawCanvas)

	svgRenderer := canvas.NewSVGRenderer(os.Stdout)
	drawCanvas.Render(svgRenderer)
}

Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func PlaceLabels 

func PlaceLabels(topo *Topology)

Determine good placement for node labels

Types

type LabelStyle 

type LabelStyle struct {
	Size         float32      `json:"size"`                       // Font size
	Color        canvas.Color `json:"color"`                      // Text color
	FontFamily   string       `json:"font-family"`                // Font family
	Background   canvas.Color `json:"background-color,omitempty"` // Background color - Link only
	Border       canvas.Color `json:"border-color,omitempty"`     // Border color - Link only
	BorderRadius float32      `json:"border-radius,omityempty"`   // Border radius - Link only
	Width        float32      `json:"width,omitempty"`            // Label width - Link only
	Opacity      float32      `json:"opacity,omitempty"`          // Label background opacity - Link only
}

Style information for node and link labels

func (*LabelStyle) UnmarshalJSON 

func (s *LabelStyle) UnmarshalJSON(data []byte) error
type Link struct {
	Id       LinkId       `json:"id"`
	From     NodeId       `json:"from"`
	To       NodeId       `json:"to"`
	Via      [][2]int16   `json:"via,omitempty"`
	SplitAt  *float32     `json:"split_at,omitempty"`
	Class    string       `json:"class,omitempty"`
	State    string       `json:"state,omitempty"`
	Style    *LinkStyle   `json:"style,omitempty"`
	Route    vec.Polyline `json:"route,omitempty"`
	FromData *LinkData    `json:"from_data,omitempty"`
	ToData   *LinkData    `json:"to_data,omitempty"`
}

Link represents a link between two nodes.

While the ends are labeled "to" and "from", links are expected to be bi-directional, the naming is simply for convenience.

type LinkData 

type LinkData struct {
	// The "value" of the link, typically link usage as a %
	Value option.Float32 `json:"value"`
	// The label for the link, typically the amount of traffic
	Label string `json:"label"`
}

Data associated with a link

type LinkId 

type LinkId string

func (LinkId) String 

func (id LinkId) String() string

type LinkRouter 

type LinkRouter struct {
	// Avoid other nodes when routing (default true)
	AvoidNodes bool
	// contains filtered or unexported fields
}

LinkRouter routes links through a grid. The zero value is not usable.

func NewLinkRouter 

func NewLinkRouter(topo *Topology) *LinkRouter

func (*LinkRouter) GetExtents 

func (r *LinkRouter) GetExtents() (min, max vec.Vec2)
func (r *LinkRouter) RouteLinks()

Route all the links in the topology and update the links.

func (*LinkRouter) SetExtents 

func (r *LinkRouter) SetExtents(minX, minY, maxX, maxY int)

Set the minimum and maximum extents of the grid

These are otherwise determined by the positions of nodes and vias in the topology.

Setting the extents such that nodes lie outside the grid will cause links to fail to route

type LinkStyle 

type LinkStyle struct {
	Size float32 `json:"size"`
	// Bend radius for the drawn line
	Radius option.Float32 `json:"radius"`
	*canvas.Style
}

Stores style information for links

type Node 

type Node struct {
	Id      NodeId     `json:"id"`
	Pos     *[2]int16  `json:"pos,omitempty"`
	Label   string     `json:"label,omitempty"`
	LabelAt string     `json:"label_at,omitempty"`
	Class   string     `json:"class,omitempty"`
	Style   *NodeStyle `json:"style,omitempty"`
}

Represents a node on the map

type NodeId 

type NodeId string

func (NodeId) String 

func (id NodeId) String() string

type NodeStyle 

type NodeStyle struct {
	// Size of the node
	Size float32 `json:"size"`
	*canvas.Style
}

Stores style information for nodes

type RenderConfig 

type RenderConfig struct {
	MinNodeSep       float32              `json:"min-node-sep"`
	DefaultNodeStyle NodeStyle            `json:"node-style"`
	NodeStyles       map[string]NodeStyle `json:"node-styles,omitempty"`
	DefaultLinkStyle LinkStyle            `json:"link-style"`
	LinkStyles       map[string]LinkStyle `json:"link-styles,omitempty"`
	NodeLabelStyle   LabelStyle           `json:"node-label-style"`
	LinkLabelStyle   LabelStyle           `json:"link-label-style"`
	LinkColorScale   *canvas.ColorScale   `json:"link-color-scale"`
}

Configuration values for the renderer

The zero value is not usable, instead it is better to create one with DefaultRenderConfig and modify it.

func DefaultRenderConfig 

func DefaultRenderConfig() *RenderConfig

type Renderer 

type Renderer struct {
	Config *RenderConfig
	// contains filtered or unexported fields
}

func NewRenderer 

func NewRenderer() *Renderer

func NewRendererWithConfig 

func NewRendererWithConfig(config *RenderConfig) *Renderer

func (*Renderer) GetScale 

func (r *Renderer) GetScale() float32

GetScale returns the scale factor used for converting positions from the topology grid into canvas positions

By default it is calculated so the largest node size (from configured styles) is approximately the same as one unit in the grid.

Use Renderer.SetScale to override the scale 

func (r *Renderer) RenderLink(link *Link) (canvas.Object, error)

RenderLink renders the given Link and returns a canvas.Object

func (*Renderer) RenderLinkLabel 

func (r *Renderer) RenderLinkLabel(pos vec.Vec2, text string) (canvas.Object, error)

RenderLinkLabel renders a link label at pos and returns a canvas.Object 

func (r *Renderer) RenderLinks(links []*Link) (canvas.Object, error)

RenderLinks renders a list of links and returns a canvas.Object

func (*Renderer) RenderNode 

func (r *Renderer) RenderNode(node *Node) (canvas.Object, error)

RenderNode renders the given Node and returns a canvas.Object

func (*Renderer) RenderNodeLabel 

func (r *Renderer) RenderNodeLabel(node *Node) (canvas.Object, error)

RenderNodeLabel renders the label for the given Node and returns a canvas.Object

func (*Renderer) RenderNodes 

func (r *Renderer) RenderNodes(nodes []*Node) (canvas.Object, error)

RenderNodes renders a list of nodes and returns a canvas.Object

func (*Renderer) RenderShape 

func (r *Renderer) RenderShape(radius float32, paths ...vec.Polyline) canvas.Object

Helper function for rendering shapes in grid-space at the appropriate scale. Paths is a set of paths that define the shape, the shape is always closed, corners are radiused if radius > 0

func (*Renderer) RenderTopology 

func (r *Renderer) RenderTopology(topo *Topology) (canvas.Object, error)

RenderTopology renders the given Topology and returns a canvas.Object that can be added to a canvas or other object

func (*Renderer) RenderTopologyToCanvas 

func (r *Renderer) RenderTopologyToCanvas(topo *Topology, c *canvas.Canvas) error

RenderTopologyToCanvas renders the given Topology to the top level of the given This also adds the styles to the canvas.

func (*Renderer) SetScale 

func (r *Renderer) SetScale(s float32)

Explicitly set the scale, s must be greater than 0

func (*Renderer) SetStyles 

func (r *Renderer) SetStyles(c *canvas.Canvas)

Sets the styles configured in the Renderer to the canvas

The following classes are created in the canvas:

  • "node" - Styles that apply to all nodes
  • "link-segment" - Styles that apply to all link segments
  • "node-label-text" - Styles that apply to all node labels
  • "link-label-text" - Styles that apply to all link labels
  • "link-label-box" - Styles that apply to all link labels

type Topology 

type Topology struct {
	Nodes map[NodeId]*Node `json:"nodes"`
	Links map[LinkId]*Link `json:"links"`
}

A full map topology 

func (t *Topology) GetLink(id LinkId) *Link

func (*Topology) GetNode 

func (t *Topology) GetNode(id NodeId) *Node

func (*Topology) UnmarshalJSON 

func (t *Topology) UnmarshalJSON(data []byte) error

UnmarshalJSON supports a couple different ways of representing a Topology

It is always an object with fields: "nodes" and "links", However each field can either be an array of nodes/links, or an object with { "id": <node/link> } fields.

Node ids are automatically set if the object format used, otherwise they must be both present and unique.

Link ids, if not provided, are determined automatically from the "from" and "to" fields of the link.

Source Files

View all Source files

Directories

Path Synopsis
The canvas package provides an API for drawing.
 The canvas package provides an API for drawing.
cmd
make-map
MakeMap generates a map from a topology.
 MakeMap generates a map from a topology.
f32
Functions for operating on 32bit floats, mostly just wrappers around the functions from std/math
 Functions for operating on 32bit floats, mostly just wrappers around the functions from std/math

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.