Guides

Graphics

View as Markdown

Indicator Tutorial 11

Custom Indicators now has a Graphics module. We can leverage this in our own indicators to create more complex graphics. To enable graphics in your indicator, modify the object return value of map.

1//...
2    map(d) {
3        return {
4            graphics: {
5                items: [
6                    //GraphicsObjects go here.
7                ]
8            }
9        }
10    }
11//...

The items field within graphics tells the renderer what graphics to display. Each item must adhere to the GraphicsObject interface.

Let’s imagine we want to note when a substantial gain has occured at an index on the chart. To do so we must track the last known value. Let’s write a tool to help us do this:

1function MyTracker(magicNumber) {
2    function tracker(value) {
3        return tracker.push(value)
4    }
5    
6    tracker.push = (value) => {
7        let result = value - tracker.state.last >= magicNumber
8        tracker.state.last = value
9        return result
10    }
11    
12    tracker.reset = () => {
13        tracker.state = {
14            last: -1
15        }
16    }
17    
18    tracker.reset()
19    
20    return tracker
21}

On push, the tracker tool will compare the difference of incoming value and the last known value against a magicNumber that will be set by UI parameters. The push function will return true if the difference is greater than or equal to the magic number, indicating a ‘substantial gain’, as defined by the end user. We will use boolean result to determine whether or not to render a graphic at the point of ‘substantial gain’.

Now let’s build our calculator - the class that will ultimately represent our indicator.

1const { op, px, du } = require('./tools/graphics')
2const predef = require('./tools/predef')
3
4class SubstantialGain {
5    init() {
6        this.tracker = MyTracker(this.props.magicNumber)
7    }
8
9    map(d) {
10        const shouldDraw = this.tracker(d.value())
11        return {
12            graphics: shouldDraw && {
13                items: [
14                    {
15                        tag: "Text",
16                        key: "ex",
17                        point: {
18                            x: op(du(d.index()), '-', px(2)),
19                            y: op(du(d.value()), '-', px(58)),
20                        },
21                        text: "!",
22                        style: { fontSize: 18, fontWeight: "bold", fill: "#5c5" },
23                        textAlignment: "centerMiddle"
24                    },
25                ]
26            }
27        }
28    }
29}
30
31module.exports = {
32    name: "substantialGain",
33    description: "SubstantialGain",
34    calculator: SubstantialGain,
35    params: {
36        magicNumber: predef.paramSpecs.number(1.00, 0.25, 0.25)
37    },
38    tags: ["Drawings"],
39}

We first must initialize our tracker tool. We do so in the init function of our calculator, leveraging our module’s props. In the map function, we use our tracker tool to get a boolean value for the bar currently being drawn. Finally in the return object of our map, we can add our first graphics item. This particular object is a Text object. If we were to select our Substantial Gains indicator and supply it with a (reasonable) magic number, we should see some greenish exclamation points rendered over some of our chart’s bars.

That’s a great start, but we have substantially more power at our disposal. Let’s start by making our graphic a bit more complex. Within our items array, let’s add another GraphicsObject.

1//...
2{
3    tag: "Shapes",
4    key: 'circs',
5    primitives: [
6        {
7            tag: 'Circle',
8            radius: 10,
9            center: {
10                x: op(du(d.index()), '-', px(2)),
11                y: op(du(d.value()), '-', px(60)),
12            },
13        },
14        
15    ],
16    fillStyle: {
17        color: "#5c5"
18    }
19},
20//...

This is another type of GraphicsObject, the ContourShapes type. This object describes one or more Shape objects to apply a border stroke to, as defined by its lineStyle field. Now we should see a circled exclamation point on bars that have had ‘substantial gains’. Now that we have more than one logically grouped element, we should consider containing them as a unit. To do so, we can use the Container type. Replace your items code with this single GraphicsObject object.

1//...
2{
3    tag: 'Container',
4    key: 'mediumContainer',
5    children: [
6        {
7            tag: "Text",
8            key: "ex",
9            point: {
10                x: op(du(d.index()), '-', px(2)),
11                y: op(du(d.value()), '-', px(58)),
12            },
13            text: "!",
14            style: { fontSize: 18, fontWeight: "bold", fill: "#5c5" },
15            textAlignment: "centerMiddle"
16        },
17        {
18            tag: "ContourShapes",
19            key: 'circs',
20            primitives: [
21                {
22                    tag: 'Circle',
23                    radius: 10,
24                    center: {
25                        x: op(du(d.index()), '-', px(2)),
26                        y: op(du(d.value()), '-', px(60)),
27                    },
28                },
29                
30            ],
31            lineStyle: {
32                lineWidth: 2,
33                color: "#5c5"
34            }
35        },
36    ],
37},
38//...

The container has one unique field, children, which is an array of GraphicsObjects. You can leverage this grouping to apply transformations that keep these contained objects in relative space. That way you can move the whole container instead of each object. The other benefit of this is that we can leverage VisibilityConditions over whole groups. Here’s what we should see when we render this indicator:

Greenish, circled exclamation points.

To understand our next step, let’s do an experiment. First, zoom way out in the X axis - you can do so by scrolling the mouse wheel. Those circled exclamations don’t scale down to fit the new bar size, instead they get clumped up and look bad. Now zoom way in on the X axis. Now because we haven’t scaled up they look somewhat lacking and small. We can fix all of this by creating a variety of groups to describe each breakpoint and give them a conditions field. These are the VisibilityConditions} for the object being rendered.

VisibilityConditions consist of scalar ranges in the X or Y axis. These are measured in pixels-per-domain-unit. This works out to roughly the pixel distance between bars in the X axis, and the tick-size in pixels of an index for the given contract being calculated. What this allows us to do is render something different based on breakpoints we define. Here’s an example:

1//...
2{
3    tag: 'Container',
4    key: 'mediumContainer',
5    conditions: { //<== Added this field!
6        scaleRangeX: { min: 10 },
7    },
8    children: [
9        //... Same as defined before
10    ],
11},
12{
13    tag: 'Container',
14    key: 'tinyContainer',
15    conditions: {
16        scaleRangeX: { min: 0, max: 10 },
17    },
18    children: [
19        {
20            tag: 'Dots',
21            key: 'dots',
22            dots: [
23                { 
24                    point: {
25                        x: du(d.index()), 
26                        y: op(du(d.value()), '-', px(48))
27                    }, 
28                    color: {
29                        r: .25, 
30                        g: .8, 
31                        b: .25
32                    } 
33                }
34            ],
35            style: {
36                lineWidth: 6,
37                color: '#5c5'
38            }
39        },
40    ],
41},
42//...

Now when the bars are tiny, and have only between 0 and 10 pixels between them, we will render a tiny dot instead of the circled exclamation.

Now we have green dots over the small-scale bars.

This introduces anotherGraphicsObject as well - the Dots object. It describes one or more WebGL dots to render. At 10 pixels of space per bar or greater we draw our standard circled exclamation. Note that the scaleRangeX, scaleRangeY, and their min and max fields are actually optional. If omitted, we simply won’t apply a bound in the ignored direction or on the ignored axis. We can of course apply something extra for large pixel distances as well.

I’d like to display the amount of the ‘substantial gain’ at high pixel-per-domain-unit distances. We will need to modify our tracker slightly to accomodate this - we currently discard our last value on each push. We will could provide the difference in the two values as part of the return value of our tracker’s push function.

1//... in tracker, we simply change push a tiny bit
2    tracker.push = (value) => {
3        let number = value - tracker.state.last
4        let result = number >= magicNumber
5        tracker.state.last = value
6        return [result, number]
7    }
8
9//... in SubstantialGains class we change our tracker's expected return to 2 destructured variables
10    map(d) {
11        const [shouldDraw, difference] = this.tracker(d.value());
12        
13        return {
14            graphics: shouldDraw && {
15                items: [
16                    //We only want to add a single extra element - no need for another container
17                    {
18                        conditions: {
19                            scaleRangeX: { min: 30 }
20                        },
21                        tag: "Text",
22                        key: "bigText",
23                        text: `+ ${difference}`,
24                        point: {
25                            x: op(du(d.index()), '-', px(4)),
26                            y: op(du(d.value()), '-', px(84))
27                        },
28                        style: { fontSize: 20, fontWeight: "bold", fill: "#0bf" },
29                        textAlignment: "centerMiddle"
30                    },
31                    //...
32                ]
33            }
34        }
35    }            
36//...

Rendering our indicator should yield this result at big pixel-to-domain ratios:

A bit of cyan text indicating the difference between the value at the last index and the bar's value.