Skip to content

Settings

Jump to bottom Edit New page
sheymann edited this page Sep 17, 2014 · 10 revisions

How settings work in sigma

Sigma is a very complex library, made of several different interconnected components. And customizing sigma in nice ways often requires to change how some of these components work by changing their configuration. And this requires a pretty precise way to deal with settings.

Here is a basic example to understand the problem:

  1. It must be possible to have two running instances of sigma with different parameters.
  2. It must be possible to have two running renderers of the same sigma instance with different parameters.
  3. The settings of each renderer, of each instance, and the global settings must be modifiable at any time.

So, anytime a component of a sigma's instance must retrieve a settings value, it will first be checked in its own configuration, then in the instance one, and finally in the global default settings.

Let's introduce the class that deals with this problem in sigma, sigma.classes.configurable. Basically, here is how it works:

  1. It is a function that must be instanciated with some objects.
  2. It can retrieve, for a given key, a value from an object.
  3. If multiple objects are given, the function will return the first value found in an object where the key is.
  4. It is also possible to call it with more objects that will checked at first.
  5. It is finally possible to embed more objects in it with its method embedObjects.

And all the objects to search in can be dynamically changed, so this function never clones any object and just keeps reference to them.

Here are some examples to make it simpler to understand:

Instantiation

var settings = new sigma.classes.configurable({
  param1: 'abc',
  param2: 42
});

Retrieve a value

console.log(settings('param1')); // ouputs 'abc'
console.log(settings('param2')); // ouputs 42
console.log(settings('param3')); // ouputs undefined

Retrieve a value through other objects

console.log(settings({ param2: 'def' }, 'param1')); // ouputs 'abc'
console.log(settings({ param2: 'def' }, 'param2')); // ouputs 'def'
console.log(settings({ param2: 'def' }, 'param3')); // ouputs undefined

Embed other objects

var embed = settings.embedObjects({ param2: 'def' });
console.log(embed('param1')); // ouputs 'abc'
console.log(embed('param2')); // ouputs 'def'
console.log(embed('param3')); // ouputs undefined

It is also noticeable that the function returned by the embedObjects is a new configurable instance, which provides as well the possibility to pass objects before the key, and the embedObjects method. You can check the sourcecode to know more about it.

Instantiation

var multiSettings = new sigma.classes.configurable(
  {
    param1: 'abc',
    param2: 42
  },
  {
    param2: 123,
    param3: 456,
  }
);

console.log(multiSettings('param1')); // ouputs 'abc'
console.log(multiSettings('param2')); // ouputs 123
console.log(multiSettings('param3')); // ouputs 456
console.log(multiSettings('param4')); // ouputs undefined

Available settings list

The default settings are stored in the sigma.settings object. In the code source, every default values are grouped in the sigma.settings.js file. If a plugin requires some default settings values, it is possible to add them directly in the sigma.settings object, without modifying the related core file.

Here is an exhaustive list of every settings that are recognized by default by the different sigma's core components:

Graph settings

  • clone
    • Indicates if the data have to be cloned in methods to add nodes or edges.
    • type: boolean
    • default value: true
  • immutable
    • Indicates if nodes "id" values and edges "id", "source" and "target" values must be set as immutable.
    • type: boolean
    • default value: true
  • verbose
    • Indicates if sigma can log its errors and warnings.
    • type: boolean
    • default value: false

Renderers settings

Note: To change the background of sigma, you have to change the CSS rules of the container. Since the different layers are transparent (except of the drawn elements), the background of the container is the actual background of your display.

For everything else, here are the available settings:

  • defaultLabelColor
    • type: string
    • default value: "#000"
  • defaultEdgeColor
    • type: string
    • default value: "#000"
  • defaultNodeColor
    • type: string
    • default value: "#000"
  • defaultLabelSize
    • type: string
    • default value: 14
  • edgeColor
    • Indicates how to choose the edges color. Available values: "source", "target", "default"
    • type: string
    • default value: "source"
  • font
    • type: string
    • default value: "arial"
  • fontStyle
    • type: string
    • default value: ""
    • example: "bold"
  • labelColor
    • Indicates how to choose the labels color. Available values: "node", "default"
    • type: string
    • default value: "default"
  • labelSize
    • Indicates how to choose the labels size. Available values: "fixed", "proportional"
    • type: string
    • default value: "fixed"
  • labelSizeRatio
    • The ratio between the font size of the label and the node size.
    • type: string
    • default value: 1
  • labelThreshold
    • The minimum size a node must have to see its label displayed.
    • type: number
    • default value: 8
  • webglOversamplingRatio
    • The oversampling factor used in WebGL renderer.
    • type: number
    • default value: 2

The following settings are dedicated to customize the appearance of hovered nodes:

  • borderSize
    • The size of the border of hovered nodes.
    • type: number
    • default value: 0
  • defaultNodeBorderColor
    • The default hovered node border's color.
    • type: number
    • default value: "#000"
  • hoverFont
    • The hovered node's label font. If an empty string, will heritate the "font" value.
    • type: number
    • default value: ""
  • hoverFontStyle
    • example: 'bold'
    • type: string
    • default value: ""
  • labelHoverShadow
    • Indicates how to choose the hovered nodes shadow color. Available values: "node", "default"
    • type: string
    • default value: "default"
  • labelHoverShadowColor
    • type: string
    • default value: "#000"
  • nodeHoverColor
    • Indicates how to choose the hovered nodes color. Available values: "node", "default"
    • type: string
    • default value: "node"
  • defaultNodeHoverColor
    • type: string
    • default value: "#000"
  • labelHoverBGColor
    • Indicates how to choose the hovered nodes background color. Available values: "node", "default"
    • type: string
    • default value: "default"
  • defaultHoverLabelBGColor
    • type: string
    • default value: "#fff"
  • labelHoverColor
    • Indicates how to choose the hovered labels color. Available values: "node", "default"
    • type: string
    • default value: "default"
  • defaultLabelHoverColor
    • type: string
    • default value: "#000"

The following flags make possible to keep edges, labels and / or nodes to be drawn:

  • drawLabels
    • Determines wether or not the labels should be drawn.
    • type: boolean
    • default value: true
  • drawEdges
    • Determines wether or not the edges should be drawn.
    • type: boolean
    • default value: true
  • drawNodes
    • Determines wether or not the nodes should be drawn.
    • type: boolean
    • default value: true

A simple way to make sigma's manipulation way more fluid is to batch edges rendering. Also, keeping edges to be rendered when the scene is moved or dragged. The following settings are dedicated to deal with these questions:

  • batchEdgesDrawing
    • Indicates if the edges must be drawn in several frames or in one frame, as the nodes and labels are drawn.
    • type: boolean
    • default value: false
  • hideEdgesOnMove
    • Indicates if the edges must be hidden during dragging and animations.
    • type: boolean
    • default value: false
  • canvasEdgesBatchSize
    • The number of edges to draw per batch in the Canvas renderer when the setting "batchEdgesDrawing" is true.
    • type: false
    • default value: 500
  • webglEdgesBatchSize
    • The number of edges to draw per batch in the WebGL renderer when the setting "batchEdgesDrawing" is true.
    • type: false
    • default value: 1000

Rescale settings

  • scalingMode

    • Indicates of to scale the graph relatively to its container. Available values: "inside", "outside"
    • type: string
    • default value: "inside"

  • sideMargin

    • The margin to keep around the graph.
    • type: number
    • default value: 0

The following settings determine the size of the smallest and the biggest node / edges on the screen when the camera ratio is 0. This mapping makes easier to display the graph, avoiding too big nodes that take half of the screen, or too small ones that are not readable. If the min and max parameters are equals, then the minimal display size will be 0 and the maximal will be equal to the given value. And if they are both equal to 0, then there is no mapping, and the radius of the nodes will be their size.

  • minEdgeSize
    • type: number
    • default value: 0.5
  • maxEdgeSize
    • type: number
    • default value: 1
  • minNodeSize
    • type: number
    • default value: 1
  • maxNodeSize
    • type: number
    • default value: 8

Captors settings

  • touchEnabled
    • Use it to enable or disable the touch support.
    • type: boolean
    • default value: true
  • mouseEnabled
    • Use it to enable or disable the mouse support.
    • type: boolean
    • default value: true
  • doubleClickEnabled
    • Use it to enable or disable the zoom on double-click.
    • type: boolean
    • default value: true
  • eventsEnabled
    • Defined whether the internal events such as "clickNode" can be used.
    • type: boolean
    • default value: true
  • zoomingRatio
    • Defines by how much multiplicating the zooming level when the user zooms with the mouse-wheel.
    • type: number
    • default value: 1.7
  • doubleClickZoomingRatio
    • Defines by how much multiplicating the zooming level when the user zooms by double clicking.
    • type: number
    • default value: 2.2
  • zoomMin
    • The minimum zooming level.
    • type: number
    • default value: 0.0625 (== 1 / 16)
  • zoomMax
    • The maximum zooming level.
    • type: number
    • default value: 2
  • mouseZoomDuration
    • The duration of animations following a mouse scrolling.
    • type: number
    • default value: 200
  • doubleClickZoomDuration
    • The duration of animations following a mouse double click.
    • type: number
    • default value: 200
  • mouseInertiaDuration
    • The duration of animations following a mouse dropping.
    • type: number
    • default value: 200
  • mouseInertiaRatio
    • The inertia power (mouse captor).
    • type: number
    • default value: 3
  • touchInertiaDuration
    • The duration of animations following a touch dropping.
    • type: number
    • default value: 200
  • touchInertiaRatio
    • The inertia power (touch captor).
    • type: number
    • default value: 3
  • doubleClickTimeout
    • The maximum time between two clicks to make it a double click.
    • type: number
    • default value: 300
  • doubleTapTimeout
    • The maximum time between two taps to make it a double tap.
    • type: number
    • default value: 300
  • dragTimeout
    • The maximum time of dragging to trigger inertia.
    • type: number
    • default value: 200

Global settings

  • autoResize
    • Determines whether the instance has to refresh itself automatically when a "resize" event is dispatched from the window object.
    • type: boolean
    • default value: true
  • autoRescale
    • Determines whether the "rescale" middleware has to be called automatically for each camera on refresh.
    • type: boolean
    • default value: true
  • enableCamera
    • If set to false, the camera method goTo will basically do nothing.
    • type: boolean
    • default value: true
  • enableHovering
    • If set to false, the nodes cannot be hovered.
    • type: boolean
    • default value: true
  • rescaleIgnoreSize
    • If set to true, the rescale middleware will ignore node sizes to determine the graphs boundings.
    • type: boolean
    • default value: false
  • skipErrors
    • Determines if the core has to try to catch errors on rendering.
    • type: boolean
    • default value: false

Camera settings

The power degrees applied to the nodes / edges size relatively to the zooming level. Basically:

  • onScreenR = Math.pow(zoom, nodesPowRatio) * R

  • onScreenT = T / Math.pow(zoom, edgesPowRatio)

  • nodesPowRatio

    • type: number
    • default value: 0.5

  • edgesPowRatio

    • type: number
    • default value: 0.5

Animations settings

  • animationsTime:
    • The default animation time.
    • type: number
    • default value: 200
Add a custom footer
Add a custom sidebar
Clone this wiki locally