NAP Library: nap_function

Miscellaneous Functions

Introduction
color_wheel( n , v , b )
cv( main_nao[ , dim_number] )
derivative( a[ , dim_number] )
fill_holes( x )
fuzzy_floor( x[ , eps] )
fuzzy_ceil( x[ , eps] )
gets_matrix( filename[ , n_header_lines] )
head( x[ , n] )
hsv2rgb( hsv )
isMissing( x )
isPresent( x )
magnify_interp( a , mag_factor )
mixed_base( x , b )
nub( x )
outer( dyad , y[, x] )
palette_interpolate( from , to)
scattered2grid( xyz , ycv , xcv )
scaleAxis( xstart , xend[ , nmax[ , nice]] )
scaleAxisSpan( xstart , xend[ , nmax[ , nice]] )
range( a )
tail( x[ , n] )

Introduction

The following functions are defined in the file nap_function_lib.tcl.

`color_wheel(` `n` `,` `v` `,` `b` `)`

Square containing color wheel.
n is number rows & columns
v is desired "value" level
b is background colour outside circle

Example:
nap "color_wheel(100,255,3#150)"
This produces a u8 array with shape {3 100 100} & values from 0 to 255.

`cv(` `main_nao`[ `,` `dim_number`] `)`

This is simply an alias for coordinate_variable.

`derivative(` `a`[ `,` `dim_number`] `)`

Estimate derivative along dimension dim_number (default is 0) of array a. The result has the same shape as a.

Example (assuming vector has dimension (& coordinate variable) time:

derivative(vector); # result is derivative with respect to time

Examples (assuming matrix has dimensions latitude & longitude):

derivative(matrix, 'latitude'); # result is derivative with
respect to latitude
derivative(matrix, 0);          # result is derivative with respect to
latitude
derivative(matrix);             # result is derivative with respect to
latitude
derivative(matrix,'longitude'); # result is derivative with
respect to longitude
derivative(matrix, 1);          # result is derivative with respect to
longitude

Based on quadratic through 3 points (provided size of dimension is > 2 -- if only 2 then based on straight line). These always include the point corresponding to the result. For interior points, the other 2 are the closest neighbour on each side. For boundary points, these are the 2 closest neighbours.

Let D(x) be the derivative of quadratic through points (x0,y0), (x1,y1), (x2,y2).

D1 = D(x1) = a0 * y0 + a1 * y1 + a2 * y2
where the coefficients a0, a1, a2 are defined by:
        a0 = (x1 - x2) / ((x1 - x0) * (x2 - x0))
        a1 = 1 / (x1 - x0) - 1 / (x2 - x1)
        a2 = (x1 - x0) / ((x2 - x0) * (x2 - x1))

`fill_holes(x,` [`max_nloops`]`)`

x is array to be filled.
max_nloops is maximum number of iterations.
Replace missing values by estimates based on means of neighbours. If max_nloops is not specified then fill_holes continues until there are no missing values.

`fuzzy_floor(` `x`[ `,` `eps`] `)`

Like floor() except allow for rounding error.
eps is tolerance and defaults to 1e-9.

Example:
% [nap "fuzzy_floor({4.998 4.9998},1e-3)"] 4 5

`fuzzy_ceil(` `x`[ `,` `eps`] `)`

Like ceil() except allow for rounding error.
eps is tolerance and defaults to 1e-9.

Example:
% [nap "fuzzy_ceil({5.002 5.0002},1e-3)"] 6 5

`gets_matrix(` `filename`[ `,` `n_header_lines`] `)`

Read text file and return NAO matrix whose rows correspond to the lines in the file. Ignore:

first n_header_lines (default 0) lines
blank lines
lines whose first non-whitespace character is ' #'

Examples:
nap "m1 = gets_matrix('matrix1.txt')" nap "m2 = gets_matrix('matrix2.txt', 3)"; # Skip 1st 3 lines

`head(` `x`[ `,` `n`] `)`

If n ≥ 0 then result is 1st n elements of x, cycling if n > nels( x).
n defaults to 1.
If n < 0 then result is 1st nels( x)+ n elements of x i.e. drop − n from end

Examples:

% [nap "head({3 1 9 2 7})"]
3
% [nap "head({3 1 9 2 7}, 2)"]
3 1
% [nap "head({3 1 9 2 7}, -2)"]
3 1 9

`hsv2rgb(` `hsv` `)`

Convert colour in HSV form to RGB.
hsv is an array whose leading dimension has size 3.

Layer 0 along this dimension corresponds to hue as an angle in degrees. Angles of any sign or magnitude are allowed. Red = 0, yellow = 60, green = 120, cyan = 180, blue = −120, magenta = −60.

Layer 1 along this dimension corresponds to saturation in range 0.0 to 1.0.

Layer 2 along this dimension corresponds to "value". This has the same range as the RGB values, normally either 0.0 to 1.0 or 0 to 255. If you are casting the result to an integer & want a maximum of 255 then set the maximum to say 255.999. Otherwise you will get few if any 255s.

The result has the same shape as the argument (hsv).

See Foley, vanDam, Feiner and Hughes, Computer Graphics Principles and Practice, Second Edition, 1990, ISBN 0201121107 page 593.

Example:
% [nap "hsv2rgb {180.0 0.5 100.0}"] 50 100 100

`isMissing(` `x` `)`

1 if x missing, 0 if present.

Example:
% [nap "isMissing {0 _ 9}"] 0 1 0

`isPresent(` `x` `)`

0 if x missing, 1 if present.

Example:
% [nap "isPresent {0 _ 9}"] 1 0 1

`magnify_interp(` `a` `,` `mag_factor` `)`

Magnify each dimension of array a by factor defined by the corresponding element of mag_factor if this is a vector. If this is a scalar then every dimension is magnified by the same factor. The new values are estimated using multi-linear interpolation.

This function can be used to make images larger or smaller.

Example:
% [nap "magnify_interp({{1 2 3}{4 5 6}}, {1 3})"] value 1.00000 1.33333 1.66667 2.00000 2.33333 2.66667 3.00000 4.00000 4.33333 4.66667 5.00000 5.33333 5.66667 6.00000

`magnify_nearest(` `a` `,` `mag_factor` `)`

This function is similar to magnify_interp except that the new values are defined by the nearest neighbour rather than interpolation.

Example:
% [nap "magnify_nearest({{1 2 3}{4 5 6}}, {1 3})"] value 1 1 2 2 2 3 3 4 4 5 5 5 6 6

`mixed_base(` `x` `,` `b` `)`

Convert scalar value x to mixed base defined by vector b.

Following example converts 87 inches to yards, feet & inches:
% [nap "mixed_base(87, {3 12})"] 2 1 3

`nub(` `x` `)`

Result is vector of distinct values in argument (in same order).

`outer(` `dyad` `,` `y`[, `x`] `)`

Tensor outer-product.

dyad is name of either

function with two arguments
binary (dyadic) operator
x is vector
y is vector defaulting to x
Result is cross-product of x and y, applying dyad to each combination of x & y.
x & y are the coordinate variables of the result.

Following example produces a multiplication table:

% [nap "outer('*', 1 .. 5)"]
 1  2  3  4  5
 2  4  6  8 10
 3  6  9 12 15
 4  8 12 16 20
 5 10 15 20 25

`palette_interpolate(` `from` `,` `to`)

Define a palette by interpolating around the HSV (hue, saturation, value) colour wheel with both S (saturation) and V (value) set to 1. The arguments from and to are angles in degrees which specify the range of of H (hue). Red is 0, green is -240 and blue is 240.

`scattered2grid(` `xyz` `,` `ycv` `,` `xcv` `)`

Produce a matrix grid from scattered ( x,y,z) data using triangulation. Grid points within each triangle are defined by interpolating using a plane through the three vertices of the triangle.

xyz is an n× m matrix containing data corresponding to n points ( x,y,z). The number of columns ( m) must be at least 3. Columns 0, 1 and 2 contain x, y and z values respectively. Any further columns are ignored.

ycv and xcv specify the coordinate-variables for the grid.

The following example defines a grid from the four points (2,2,0), (6,4,0), (2,4,4) and (4,5,3). Note that the missing values in the result correspond to points which are outside of both the triangles produced by the triangulation. You could eliminate these missing values by defining values at all four corners of the grid.

% nap "z = scattered2grid({{2 2 0}{6 4 0}{2 4 4}{4 5 3}}, 2 .. 5, 2 .. 6)"
::NAP::1020-1020
% $z
0.00    _    _    _    _
2.00 0.75 0.00    _    _
4.00 2.50 1.50 0.75 0.00
   _    _ 3.00    _    _
% [nap "z(@2, @2)"]; # Check value at x=2, y=2
0
% [nap "z(@4, @6)"]; # Check value at x=6, y=4
0
% [nap "z(@4, @2)"]; # Check value at x=2, y=4
4
% [nap "z(@5, @4)"]; # Check value at x=4, y=5
3

`scaleAxis(` `xstart` `,` `xend`[ `,` `nmax`[ `,` `nice`]] `)`

Find suitable values for axis of graph.
xstart: 1st data value
xend: Final data value
nmax: Max. allowable number of elements in result (Default: 10)
nice: Allowable increments (Default: {1 2 5})
Result is the arithmetic progression which:

is within interval from xstart to xend
has same order (ascending/descending) as xstart // xend
has increment equal to element of nice times a power (-30 .. 30) of 10
has at least two elements
has no more than nmax elements if possible
has as many elements as possible. (Ties are resolved by choosing earlier element in nice.)

Example:
% [nap "axis = scaleAxis(-370, 580, 10, {10 20 25 50})"] value -300 -200 -100 0 100 200 300 400 500

`scaleAxisSpan(` `xstart` `,` `xend`[ `,` `nmax`[ `,` `nice`]] `)`

includes the interval from xstart to xend
has same order (ascending/descending) as xstart // xend
has increment equal to element of nice times a power (-30 .. 30) of 10
has at least two elements
has no more than nmax elements if possible
has as many elements as possible. (Ties are resolved by choosing earlier element in nice.)

Example:
% [nap "axis = scaleAxisSpan(-370, 580, 10, {10 20 25 50})"] value -400 -200 0 200 400 600

`range(` `a` `)`

Result is 2-element vector containing minimum and maximum of array a.
Example:

% [nap "range {{9 -1 -5}{2 9 3}}"]
  
-5 9

`tail(` `x`[ `,` `n`] `)`

If n ≥ 0 then result is final n elements of x, cycling if n > nels( x).
n defaults to 1.
If n < 0 then result is final nels( x )+ n elements of x i.e. drop − n from start.

Example:

% [nap "tail({3 1 9 2 7})"]
7
% [nap "tail({3 1 9 2 7}, 2)"]
2 7
% [nap "tail({3 1 9 2 7}, -2)"]
9 2 7

Author: Harvey Davies © 2002, CSIRO Australia. Legal Notice and Disclaimer
CVS Version Details: $Id: nap_function_lib.html,v 1.12 2005/08/04 05:34:43 dav480 Exp $

Miscellaneous Functions

Table of Contents