batch - Gsharp batch mode

Syntax:

float batch()

Description:

Return true if Gsharp is running in batch mode

Code sample:

 
if batch() print;

See also:

appseat, version, webedition

beep - make a noise

Syntax:

beep(float pitch, float duration, float volume)

Description:

beep is used for the visualisation of your data using sound.

  • pitch is in Hz

  • duration is in milliseconds

  • volume ranges from 0 to 255

Usage

 
beep();

Code sample:

 
function PlayNote(string note, float length)
string PITCHPTR, accident;
float pitch, octave;
  C=261.63; D=293.66; E=329.63; F=349.23; G=392; A=440; B=493.88;
  semitone = exp(log(2)/12);
  PITCHPTR = substr(note,1,1);
  octave = strvalue(substr(note,2,2));
  accident = substr(note,3,3);
  pitch = $pitch * 2^octave;
  if accident = "#" then
    pitch = pitch * semitone;
  elif accident = "b" then
    pitch = pitch / semitone;
  endif
  beep(pitch, length*250, 50);
endfunction
PlayNote("D1",1);
PlayNote("F1#",1);
PlayNote("A1",1);
PlayNote("D2",1);

bilinear - bilinear interpolation

Syntax:

float bilinear(float x, float y, float z, float xgrid, float ygrid, float xreg, float yreg, float xbar, float ybar , float estimation, float sorting, float radius, float smoothing, float radiusFactor, float feedbackFactor)

Description:

Interpolate the irregular points (x,y) with value z into a rectangular grid.

The method:

  1. For each input point, the closest grid node is found and the value of the node is set to the value of the input point. If several points share a grid node, then the average is taken. See sorting.
  2. Nodes without values are given values based on surrounding nodes using the specified estimation method. See radius
  3. The grid is smoothed using quadratic interpolation. Quadratic interpolation is a nonlinear filtering operation which tends to amplify local extrema. See smoothing, radiusFactor and feedbackFactor
  4. Finally the values are refined using a weighted average of the surrounding nodes. This step can be repeated a number of times. See smoothing.

The new gridded surface will smooth the original data points, but will not necessarily pass through them.

  • The x location of the grid is defined like so:

    • If xgrid is an array then xgrid is used.

    • If xgrid is a single value, range(x,xgrid) is used

    • If xgrid is not specified, range(x,33) is used.

  • The y location is determined in a similar way

  • x and y must not contain any undef points. If they do you can use the following code to get rid of them:

undefpoints = (x=undef) or (y=undef);
x = mask(x, not undefpoints);
y = mask(y, not undefpoints);
z = mask(z, not undefpoints);

  • xreg and yreg can be used to specify a region to interpolate within.

    • Each region must be specified as a closed polygon

    • Each region must be separated by an (undef,undef) point

    • It is also possible to interpolate over the entire grid and then apply the region what the grid is plotted. This has the advantage that the plot will contour right up to the edges of the region, rather than leaving a jagged edge.

  • xbar and ybar can be used to specify a barrier in the interpolation. This ensures that the interpolation on one side of the barrier is unaffected by the values of points on the other side of the barrier.

  • estimation is used to specify the estimation method used in step 2:

    2
    		  Bilinear Interpolation (default) 
    1
    		  Distance Weighted average interpolation

  • sorting is used to decide the value of a grid node closest to more than one input point. See step 1 above. The options are:

  •  0   Average (default) 
     1  Minimum 
     2  Maximum 
     3  First value 
     4  Last value 
     5  Sum 

  • radius can be used to specify a search radius. During step 2 an approximate value is calculated for each grid node. The search radius can be used to limit the number of neighbouring nodes that are included in that approximation. Use as small a radius as possible to reduce interpolation time.

  • The smoothing level is used to control whether steps 3 and 4 are used. Step 3 is used if the smoothing is >= -1. Step 4 is applied (smoothing+1) times. The default value of smoothing is 0, which means that step 3 is applied and then step 4 is applied once.

  • It is possible to control the quadratic interpolation in step 3 using radiusFactor and feedbackFactor. radiusFactor must be > 1 (default is 1.25) and feedbackFactor must be > 0 (default is 0.15).

A dialog for using the bilinear function can be found in the interpolation menu of the DataManager.

Code sample:

 
x = rnd(10)-.5;  y=rnd(10)-.5;  z=rnd(10);
xgrid = (-5:5)/10;   ygrid = xgrid;
i=(0:360)/180*pi;  xreg=sin(i)/2;  yreg=cos(i)/2;
xbar = 0//.5;  ybar = 0.01//0.01;
grid = bilinear(x, y, z, xgrid, ygrid, , , xbar, ybar);
create Viewport page_1.viewport_1;
create Domain page_1.viewport_1.domain_1;
create Graph page_1.viewport_1.domain_1.graph_1
   ( XuNbarrierBorderCells = "contoured",
     XuNbarrierColor = 1,
     XuNbarrierXData = "xbar",
     XuNbarrierYData = "ybar",
     XuNcolorDataGrid = "grid",
     XuNgraphType = "2DContour",
     XuNregionBorderCells = "contoured",
     XuNregionXData = "xreg",
     XuNregionYData = "yreg",
     XuNxData = "xgrid",
     XuNyData = "ygrid"
   );

See also:

bivariate, fault, polynomial, range, nicerange, unique

bivariate - bivariate interpolation

Syntax:

float bivariate(float x, float y, float z, float xgrid, float ygrid)

Description:

Interpolate the irregular points (x,y) with value z into a rectangular grid.

  • The x location of the grid is defined like so:

    • If xgrid is an array then xgrid is used.

    • If xgrid is a single value, range(x,xgrid) is used

    • If xgrid is not specified, range(x,33) is used.

  • The y location is determined in a similar way.

  • You must remove any undef points from x and y in the same way as bilinear

  • There is no support for regions or barriers

  • There is a maximum of 250 input points

The interpolated surface goes through the original datapoints.

A dialog for using the bivariate function can be found in the interpolation menu of the DataManager.

Code sample:

 
x = nint(rnd(200)*30);  y=rnd(200)*10;  z=rnd(20);
xgrid = unique(x);
ygrid = nicerange(y,30);
grid = bivariate(x,y,z,xgrid,ygrid);

create Viewport page_1.viewport_1;
create Domain page_1.viewport_1.domain_1;
create Graph page_1.viewport_1.domain_1.graph_1
   ( XuNbarrierBorderCells = "contoured",
     XuNcolorDataGrid = "grid",
     XuNgraphType = "2DContour",
     XuNxData = "xgrid",
     XuNyData = "ygrid"
   );

See also:

bilinear, fault, polynomial, range, nicerange, unique

bounding_polygon - bounding polygon of an object

Syntax:

float bounding_polygon(string object, float numVertices, float x, float y, string component, float row, float column, float plane, float numData, string resources)

Description:

bounding_polygon returns the outline of any graphical object in Gsharp. It's main use is in the Gsharp Web Edition to create image maps for drilling down into graphs. See the Gsharp Web Edition documentation for more details and examples.

  • The function returns the number of polygons that bound the object

  • numVertices, x and y must already exist before bounding_polygon is called.

  • component can be used to specify the component of an axis object, e.g. "axle", "labels", "text", "tickmarks", "ticklines" or "unit". The default is "all".

  • The built-in function bounding_polygon specifies the polygon in mm's. The function HTMLbounding_polygon is a wrapper to this function which can be used to convert to your own preferred units.

Example:

 
include "$UNIDIR/lib/libhtml.gsl";
function PolygonExample(string object)
  float npoly, numvert, x, y, r, c, p, numdata;
  float lines, vertIndex, dataIndex;
  string resources;
  npoly = HTMLbounding_polygon(object, numvert, x, y, "",
                                          r, c, p, numdata, resources, 100, 100);

  vertIndex = 0//accum(numvert);
  dataIndex = 0//accum(numdata);

  for i=1 to npoly
    lines = (vertIndex[i]+1):vertIndex[i+1];
    rx = slicex(x,lines);    ry = slicex(y,lines);
    lines = (dataIndex[i]+1):dataIndex[i+1];
    j = lines[1];
    echo("row="+r[j]+" column="+c[j]+" plane="+p[j]);
    echo("("+rx+","+ry+")");
  endfor
endfunction
create Viewport page_1.viewport_1;
create Domain page_1.viewport_1.domain_1;
create Graph page_1.viewport_1.domain_1.graph_1
   ( XuNgraphType = "bar",
     XuNxData = "1:4",
     XuNyData = "1:4"
   );
PolygonExample("page_1.viewport_1.domain_1.graph_1")

break - break from loop

Syntax:

break

Description:

break out of the innermost for or while loop

  • To continue with the next iteration of the loop use continue.

Code sample:

 
for PTR in all("Viewport")
  if (PTR=undef)  break;
  $(PTR).XuNobjectEnabled = false;
endfor
 
#Usage: DebugStop("About to read input file");
function DebugStop(string message)
  string comm;
  while (comm<>"")
    comm = input_string(message);
    if (comm=undef)  quit();
    if (comm="")  break;
    eval(comm);
  endwhile
endfunction

See also:

continue