Cango Axes Module User Guide

Cango axes drawing extension

The Cango Axes extension module provides additional methods to the Cango library to simplify generating graph axes when plotting data with Cango.

The extension requires Cango canvas graphics library Version 11 or later. Download the source code from CangoAxes-4v00.js and the minified version at CangoAxes-4v00-min.js

Also included in the module are additional Cango methods for drawing arrows, vector text which can be treated as a Path, and HTML text which is within the DOM and so can be processed by the MathJax utility. These additional Cango methods are:

drawAxes
drawBoxAxes
drawHTMLText
drawVectorText
drawArrow
drawArrowArc

The CangoAxes module also provides two global utility functions to format numbers in engineering notation which is scientific notation but the powers of ten are restricted to the preferred; nano, micro, milli, kilo, Mega, Giga etc. values. A JavaScript implementation of very useful 'sprintf' function is also included.

toEngFixed
toEngPrec
sprintf

Cango methods

drawAxes

Syntax:

cgo.drawAxes(xmin, xmax, ymin, ymax [, options])

Description:

Draws a set of Cartesian coordinate (X, Y) axes.

Parameters:

Optional Properties:

Example:

function drawAxesTest(cvsID)
{
  var gc = new Cango(cvsID),
      xmin = -20000, xmax = 25000,
      ymin = -300, ymax = 600;

  gc.gridboxPadding(5);
  gc.setWorldCoordsRHC(xmin, ymin, xmax-xmin, ymax-ymin);
  gc.drawAxes(xmin, xmax, ymin, ymax, {
    xOrigin: -10000,
    yOrigin: 0,
    xUnits:"nm",
    yUnits:"ft",
    xLabel:"X",
    yLabel:"Fn" });
}

drawBoxAxes

Syntax:

cgo.drawBoxAxes(xmin, xmax, ymin, ymax [, options])

Description:

Draws a set of X, Y axes in the shape of a box.

Parameters:

Optional Properties:

Example:

function drawBoxAxesTest(cvsID)
{
  var g = new Cango(cvsID),
      data = [],
      i;

  g.fillGridbox("#303a30");
  g.gridboxPadding(12, 8, 3, 8);
  g.setWorldCoordsRHC(0, -10, 1200, 20);

  g.drawBoxAxes(0, 1200, -10, 10, {xUnits:"Hz", yUnits:"dB", title:"REAL"});
  for (i=0; i<=200; i++)
  {
    data.push(i*6, 5*Math.sin(i/6));
  }
  g.drawPath(data, {strokeColor:'#c0e0ff'});
}

drawHTMLText

Syntax:

cgo.drawHTMLText(str [, options]);

Description:

The drawHTMLText method allows the HTML text 'str' to be written over the canvas element integrated with the Cango graphics context. The Cango method creates a small transparent overlay DIV element for each text string and positions it using the Cango world coordinate system. Any HTML text can be used. Mathematical expressions in LaTeX syntax will be correctly parsed by MathJax.

The 'options' parameter is a JavaScript object which can hold several properties that configure how the text will be formatted as it is rendered onto the page over the canvas. Supported properties include 'x' and 'y' which set the world coordinates where the text drawing origin will be drawn. The options property 'lorg' (locate origin) can specify the spot within the text bounding box that will be drawn at the x,y coordinates. This may specify any of 9 possible locations 1=top-left, 2=top center, ... 9=lower-right corner.

NOTE: Spaces in multi-word strings will generate newline breaks, Use non-breaking spaces ( ) to keep words on the same line.

NOTE: If the text is to be further processed after rendering, such as by MathJax utility then the '\' characters should be entered into 'str' as '\\' to be correctly interpreted.

Optional Properties:

Example:

function drawHTML(cvsID)
{
  var gc = new Cango(cvsID),
      xmin = -50, xmax = 250,
      ymin = 0, ymax = 100,
      r, t, s;

  gc.setWorldCoordsRHC(xmin, ymin, xmax-xmin, ymax-ymin);

  r = "Test rotation degs:30°";
  gc.drawHTMLText(r, {x:170, y:70, fontsize:18, fontWeight:400, degs:30, fillcolor:"blue", lorg:5});

  t = "HTML text test multi-line and special chars too < & etc.";
  gc.drawHTMLText(t, {x:-25, y:80, fontSize:16, fontWeight:"bold", fillColor:"brown"});

  // test the MathJax access to the HTML overlay text
  s = "MathJax and KaTeX work $$ v = \\sqrt{\\frac{p}{m + \\tfrac{1}{3}p} ln(\\frac{L}{c})}$$";

  gc.drawHTMLText(s, {x:-25, y:40, fillColor:"red", fontSize:20, fontWeight:800});
}

drawVectorText

Syntax:

cgo.drawVectorText(str[, options]);

Description:

Converts the text 'str' to a Path object. The font used is the Hershey vector font. The character set comprises 96 printable ASCII characters and the full Greek alphabet.

Special characters within the string may be specified by Unicode escapes. These are six characters long, \u followed by exactly four hexadecimal characters. If the hex character code is only one, two or three characters long, then the code must be padded with leading zeroes. The Greek letter 'π' which has character code 240 is written '\u03C0'. The hexadecimal part of this kind of character escape is not case sensitive ie. '\u03C0' and '\u03c0' are equivalent.

The 'options' parameter is a JavaScript object which can hold several properties that configure how the text will be formatted as it is rendered onto the page over the canvas. Supported properties include 'x' and 'y' which set the world coordinates where the text drawing origin will be drawn. The options property 'lorg' (locate origin) can specify the spot within the text bounding box that will be drawn at the x,y coordinates. This may specify any of 9 possible locations 1=top-left, 2=top center, ... 9=lower-right corner.

NOTE: Since the string is drawn as a stroked Path, the color is set by the options property "strokeColor" rather than "fillColor" which sets the color of Text objects.

Optional Properties:

Example:

function vectorText(cvsID)
{
  var g = new Cango(cvsID);

  g.setWorldCoordsRHC(-15, -15, 40);

  g.drawVectorText("abcd \u0026 ABCD", {x:0, y:10, fontSize: 30});
  g.drawVectorText("Greek Letters: \u03B1\u03B2\u03B3\u03B4 \u0391\u0392\u0393\u0394",
    {x:0, y:5, fontSize: 15});
  g.drawVectorText("strokeColor:'blue', lorg=7",
    {x:0, y:0, strokeColor:"blue", fontSize:20, fontWeight:200, lorg:7});
  g.drawVectorText("bgFillColor: lime, lorg 3",
    {x:0, y:0, fontSize:15, fontWeight:700, lorg:3, bgFillColor:'lime', degs: 30});
}

Vector Text character set

To generate the characters shown, insert the character (or its Unicode) into the string.

To generate the symbols shown, insert the Unicode shown below the symbol into the string.

drawArrow

cgo.drawArrow(headX, headY [, options]);

Description:

Draws a straight arrow shape. The arrow starting at world coordinates 0, 0 unless the options parameter has properties 'x' and/or 'y' in which case the arrow will be drawn from these x,y coordinates. The arrow head will end at the point with world coordinates (headX, headY). An arrow head is draw at the end point. The arrow shaft width mat be set in either pixels or world coordinates and head size can be adjusted by specifying a head size scale factor relative to the shaft width.

The arrow is a Shape object so it can be drawn with different colored border, a drop shadow or any of the other properties supported by Shape objects.

NOTE: The arrow shape is always drawn with the 'iso' property set true to preserve the arrow shape when independent X and Y world coordinate scaling is used.

Parameters:

Optional Properties:

The other Shape object optional properties are also supported:

• scl
• degs

• border
• strokeColor
• lineWidthWC
• lineWidth

• dashed
• dashOffset

• shadowOffsetX
• shadowOffsetY
• shadowBlur
• shadowColor

(see Shape.setProperty method for more details).

Example:

function drawArrows(cvsID)
{
  var gc = new Cango(cvsID),
      xmin = -15, xmax = 25,
      ymin = 0, ymax = 4;

  gc.gridboxPadding(10, 8, 2, 8);
  gc.setWorldCoordsRHC(xmin, ymin, xmax-xmin, ymax-ymin);
  gc.drawAxes(xmin, xmax, ymin, ymax, {xOrigin:0, yOrigin:0, strokeColor:'gray'});

  // test straight arrow
  gc.drawArrow(20, 3, {
    x:5, y:1,
    shaftWidthWC:2,
    headSize:4,
    fillColor:'red',
    border:true,
    strokeColor:'blue',
    lineWidth:2});

  gc.drawArrow(-10, 4, {
    x:0, y:1,
    shaftWidth: 8,
    fillColor:'green'});
}

drawArrowArc

Syntax:

cgo.drawArrowArc(radius, startAngle, stopAngle, options);

Description:

Draws a curved arrow whose shape is a circular arc of radius 'radius' starting at the angle 'startAngle' from the X axis and finishing at 'stopAngle'. An arrow head is drawn at the end with its tip at radius 'radius' and angle 'stopAngle'. The drawing origin will be at the center of the circular arc. If options properties 'x' and/or 'y' are specified then the center of the arc will be drawn at world coordinates x,y otherwise the center will be drawn at world coordinates 0,0.

NOTE: The arrow shape is always drawn with the 'iso' property set true to preserve the arrow shape when independent X and Y world coordinate scaling is used.

Parameters:

Optional Properties:

The other Shape object optional properties are also supported:

• scl
• degs

• border
• strokeColor
• lineWidthWC
• lineWidth

• dashed
• dashOffset

• shadowOffsetX
• shadowOffsetY
• shadowBlur
• shadowColor

(see Shape.setProperty method for more details).

Example:

function arrowArcDemo(cvsID)
{
  var xmin = -15, xmax = 25,
      ymin = -4, ymax = 4;

  cgo = new Cango(cvsID),
  cgo.clearCanvas("beige");
  cgo.gridboxPadding(15, 2, 15, 2);  // data area, units are % of canvas width

  cgo.setWorldCoordsRHC(xmin, ymin, xmax-xmin, ymax-ymin);
  cgo.drawAxes(xmin, xmax, ymin, ymax, {
    xOrigin: 0, yOrigin: 0,
    xLabel:"X", yLabel:"Y",
    fontSize: 10 });

  cgo.drawArrowArc(8, 40, 280, {
    x:-10,
    y:-2,
    clockwise:true,
    shaftWidth:4,
    fillColor:'black'});
  cgo.drawArrowArc(12, 280, 40, {
    clockwise:false,
    shaftWidth:8,
    fillColor:'green',
    shadowOffsetX:0.50,
    shadowOffsetY:-0.1,
    shadowBlur:0.5,
    shadowColor:'gray'});
  cgo.drawArrowArc(15, 20, 156, {
    clockwise: false,
    shaftWidthWC: 1.7,
    fillColor: 'steelblue',
    border:true,
    strokeColor:'red'});
}

Global utilities added

toEngFixed

Syntax:

var str = toEngFixed(val, decPlaces);

Description:

Converts the value val to engineering notation, i.e. mantissa and exponent where the exponent is restricted to values that are multiples of 1000. The string returned denotes the exponent by the standard single letter values µ, m, k, M, G etc. All mantissa values are expressed in the range 1 to 1000 with the number of decimal places set by the decPlaces parameter. The result is rounded to the decPlaces decimal places with no trailing zeroes are removed.

Parameters:

val:Number - The value to be formatted.

decPlaces:Number - the number of decimal places in the mantissa.

Returns:

String - The formatted string version of val.

Examples:

toEngFixed(1200.0, 3) returns "1.200k".
toEngFixed(0.012345, 2) returns "12.35m".

toEngPrec

Syntax:

var str = toEngPrec(val, sigFigs);

Description:

Converts the value val to engineering notation, i.e. mantissa and exponent where the exponent is restricted to values that are multiples of 1000. The result is then rounded to a precision of sigFigs significant figures which must be 3 or greater. The string returned denotes the exponent by the standard single letter values p, n, µ, m, k, M, G. All mantissa values are expressed in the range 1 to <1000. Trailing zeroes are removed.

Parameters:

val:Number - The value to be formatted.

sigFigs:Number - the number, greater than 3 of significant figures in the mantissa.

Returns:

String - The formatted string version of val.

Examples:

toEngPrec(1234.5678, 5) returns "1.2346k".
toEngPrec(0.012345, 3) returns "12.3m".

sprintf

Syntax:

var str = sprintf(format, arg1, arg2 ...);

Description:

This JavaScript implementation of the 'sprintf' utility was originally written by Ash Searle (2007/03/printf-sprintf/) and enhanced by Kevin van Zonneveld (http://kevin.vanzonneveld.net).

The 'format' string is composed of ordinary characters (excluding %) and optional conversion specifications. Ordinary characters are copied directly to the result. Each conversion specification consists of a percent sign (%), followed by one or more of these elements, flags, width, precision and type specifier. Each conversion specifications takes an argument in turn from those following 'format' and converts it a substring which replaces the specifier in the output.

Parameters:

  %[flags][width][.precision]type_specifier

Returns:

String - The formatted version of format with specifiers replaced with arguments in the order passed.

Examples:

var str = sprintf("pi = %4.2f", Math.PI); //  returns "pi = 3.14".