cvsPlotUtils Reference Manual

Graph Plotting Utilities

The cvsPlotUtils-01.js is a extention module for the CvsGraphCtx canvas graphics context. It provides 3 additional methods to assist the quick programming of 2D graphs on the canvas element, drawAxes, drawBoxAxes and drawXYAxes. In addition it supplies several support functions for generating 'nice' values for tick intervals and axes extents. All these extensions require the cvsGraphCtx canvas graphics context version 1v01 or later.

The following functions are provided in this graphics library.

drawAxes

Syntax:

cvsCtx.drawAxes(orgX:Number, orgY:Number, xmin:Number, xmax:Number, ymin:Number, ymax:Number, xMinorTic:Number, yMinorTic:Number, xMajorTic:Number, yMajorTic:Number)

Description:

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

Parameters:

orgX:Number - X coordinate of the intersection of the X and Y axes. Measured in the X axis world coordinates.

orgY:Number - Y coordinate of the intersection of the X and Y axes. Measured in the Y axis world coordinates.

xmin:Number - Minimum X axis value, the value of the left end of the X axis. Measured in the X axis world coordinates.

xmax:Number - Maximum X axis value, the value of the right end of the X axis. Measured in the X axis world coordinates.

ymin:Number - Minimum Y axis value, the value of the bottom end of the Y axis. Measured in the Y axis world coordinates.

ymax:Number - Maximum Y axis value, the value of the top end of the Y axis. Measured in the Y axis world coordinates.

xMinorTic:Number - Spacing between minor tick marks drawn on the X axis. Measured in the X axis world coordinates.

yMinorTic:Number - Spacing between minor tick marks drawn on the Y axis. Measured in the Y axis world coordinates.

xMajorTic:Number - Spacing between major tick marks drawn on the X axis. Major tick spacing should be a simple multiple of the minor tick spacing. Measured in the X axis world coordinates. The major tick marks are automatically labeled with their world coordinate value.

yMajorTic:Number - Spacing between major tick marks drawn on the Y axis. Major tick spacing should be a simple multiple of the minor tick spacing. Measured in the Y axis world coordinates. The major tick marks are automatically labeled with their world coordinate value.

drawBoxAxes

Syntax:

cvsCtx.drawBoxAxes(orgX:Number, orgY:Number, xmin:Number, xmax:Number, ymin:Number, ymax:Number, xTicSpacing:Number, yTicSpacing:Number, xUnits:String, yUnits:String, title:String)

Description:

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

Parameters:

orgX:Number - X coordinate of the intersection of the X and Y axes. Measured in the X axis world coordinates.

orgY:Number - Y coordinate of the intersection of the X and Y axes. Measured in the Y axis world coordinates.

xmin:Number - Minimum X axis value, the value of the left end of the X axis. Measured in the X axis world coordinates.

xmax:Number - Maximum X axis value, the value of the right end of the X axis. Measured in the X axis world coordinates.

ymin:Number - Minimum Y axis value, the value of the bottom end of the Y axis. Measured in the Y axis world coordinates.

ymax:Number - Maximum Y axis value, the value of the top end of the Y axis. Measured in the Y axis world coordinates.

xTicSpacing:Number - Spacing between tick marks drawn on the X axis. Measured in the X axis world coordinates.

yTicSpacing:Number - Spacing between tick marks drawn on the Y axis. Measured in the Y axis world coordinates.

xUnits:String - Text of the label to be drawn just below the center of the X axis. This text should describe the units of the X axis, eg "kHz". The string is prepended with the xTicSpacing value and the string "/div" is appended.

yUnits:String - Text of the label to be drawn at the left of the center of the Y axis. This text should describe the units of the Y axis, eg "dB". The string is prepended with the yTicSpacing value and the label "/div" is drawn below the yUnits label.

title:String - Text of the label to be drawn at the top left of the axes box, normally used to describe the graphed data.

drawXYAxes

Syntax:

cvsCtx.drawXYAxes(orgX:Number, orgY:Number, xmin:Number, xmax:Number, ymin:Number, ymax:Number, xUnits:String, yUnits:String, xLabel:String, yLabel:String)

Description:

Draws a set of Cartesian coordinate (X, Y) axes with automatic tick marking of the axes.

Parameters:

orgX:Number - X coordinate of the intersection of the X and Y axes. Measured in the X axis world coordinates.

orgY:Number - Y coordinate of the intersection of the X and Y axes. Measured in the Y axis world coordinates.

xmin:Number - Minimum X axis value, the value of the left end of the X axis. Measured in the X axis world coordinates.

xmax:Number - Maximum X axis value, the value of the right end of the X axis. Measured in the X axis world coordinates.

ymin:Number - Minimum Y axis value, the value of the bottom end of the Y axis. Measured in the Y axis world coordinates.

ymax:Number - Maximum Y axis value, the value of the top end of the Y axis. Measured in the Y axis world coordinates.

xUnits:String - Text of the label is placed within brackets and appended to the xLabel. This text should describe the units of the X axis, eg "kHz".

yUnits:String - Text of the label is placed within brackets and appended to the yLabel. This text should describe the units of the Y axis, eg "dB".

xLabel:String - Text of the label to be drawn adjacent to the xMax end of the X axis, it should describe the X variable of the graph.

yLabel:String - Text of the label to be drawn adjacent to the yMax end of the Y axis, it should describe the Y variable of the graph.

toEngFixed

Syntax:

toEngFixed(val:Number, decPlaces:Number):String

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:

toEngPrec(val:Number, sigFigs:Number):String

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. 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. No trailing zeroes are removed.

Parameters:

val:Number - The value to be formatted.

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

Returns:

String - The formatted string version of val.

Examples:

toEngPrec(1234.5, 3) returns "1.23k".
toEngPrec(0.012345, 2) returns "12m".

getMax

Syntax:

getMax(A:Array)

Description:

Returns the maximum value from the array A.

Parameters:

A:Array - Array of numbers.

Returns:

Number - The maximum value found in the array A.

getMin

Syntax:

getMin(A:Array)

Description:

Returns the minimum value from the array A.

Parameters:

A:Array - Array of numbers.

Returns:

Number - The minimum value found in the array A.

getMaxAbs

Syntax:

getMaxAbs(Ar:Array, Ai:Array)

Description:

Returns the maximum absolute value from the two arrays Ar and Ai.

Parameters:

Ar:Array - Array of numbers.

Ai:Array - Array of numbers.

Returns:

Number - The maximum absolute value found in either of the arrays Ar or Ai.

scale248max

Syntax:

scale248max(Ar:Array, Ai:Array)

Description:

Find first value in the sequence 2, 4, 8, 20, 40 ... that equals or exceeds the value val. This function is useful in finding the maximum value of a graph axis where the tick interval is constrained to be a quarter of the maximum value. The 2, 4, 8, 20 sequence will give tick interval values in the desirable 1, 2, 5, 10 sequence.

Parameters:

val:Number - The maximum value to be plotted on the axis with the return value as its maximum.

Returns:

Number - The first val in the 2, 4, 8, 20 sequence that equals or exceeds val.

scale125max

Syntax:

scale125max(Ar:Array, Ai:Array)

Description:

Find first value in the sequence 1, 2, 5, 10, 20 ... that equals or exceeds the value val.

Parameters:

val:Number - The maximum value to be plotted on the axis with the return value as its maximum.

Returns:

Number - The first val in the 1, 2, 5, 10 ... sequence that equals or exceeds val.

scale125step

Syntax:

scale125step(Ar:Array, Ai:Array)

Description:

Find first value in the sequence 1, 2.5, 5, 10, 25 ... that equals or exceeds the value val. This function is useful in finding the maximum value of a graph axis where the tick interval is constrained to be either a fifth or tenth of the maximum value. The 1, 2.5, 5, 10, 25 ... sequence will give tick interval values in the desirable 1, 2, 5, 10 sequence.

Parameters:

val:Number - The maximum value to be plotted on the axis with the return value as its maximum.

Returns:

Number - The first val in the 1, 2.5, 5, 10, 25 ... sequence that equals or exceeds val.

scaleLog

Syntax:

scaleLog(val:Number)

Description:

Find first value that is a multiple of 10 that equals or exceeds the value val. This function is useful in finding the maximum value for a graph axis where the logarithm of the data values are to be plotted.

Parameters:

val:Number - The maximum value to be plotted on the axis.

Returns:

Number - The first val in the -200, -190, ... 180, 190, 200 sequence that equals or exceeds val.