Dithering

Syntax: DENSITY\DITHERING { x y } z { p1 p2 }
DENSITY\DITHERING\DITHERVECTOR d { x y } z { p1 p2 }
DENSITY\DITHERING\LEVELS lvl { x y } z { p1 p2 }
DENSITY\DITHERING\LEVELS\DITHERVECTOR d lvl { x y } z { p1 p2 }
Qualifiers: \LEGEND, \DITHERVECTOR, \CONTOURS, \LEVELS, \AREAS, \VOLUMES, \LINES, \EQUALLYSPACED, \PARTIAL, \XPROFILE, \YPROFILE, \BORDER, \AXES, \RESET
Defaults: if z is a matrix: x=[1;2;3;...], y=[1;2;3;...], p1=0, p2=1, d=[1;1;2;1;2;2;3;2;3;3;4;3;4;4;5;5;6;6;0;0], \-PARTIAL, \-LEGEND, \-XPROFILE, \-YPROFILE, \BORDER, \AXES, \RESET, \-LEVELS, \-AREAS, \-VOLUMES, \-LINES, \-EQUALLYSPACED

In this type of density plot, by default, the range of data values is divided into ten (10) equally spaced levels and a different dithering pattern is associated with each level. A value is interpolated at every pixel location within the bounds of the data region to determine the level for that point. The dithering pattern for that level then determines whether that pixel is to be lit up. Thus, the boundaries of the data are divided up into different dithering pattern regions.

Input variables

If z is a vector, the parameters x and y are expected and must be vectors. x and y are assumed to represent a scattered set of points, where z[i] is the altitude corresponding to the location (x[i],y[i]). A matrix is interpolated on these scattered points by means of a Thiessen triangulation of the plane. The three vectors must be the same length.

If z is a matrix, the parameters x and y default to [1;2;3;...], but if entered they must be vectors. Each matrix element, z[i,j], is associated with the coordinates (x[j],y[i]). The length of x must be equal to the number of columns of z and the length of y must be equal to the number of rows. The vectors x and y are used for scaling the axes.

Dithering pattern definition

The default dithering pattern vector is:

[ 1;1; 2;1; 2;2; 3;2; 3;3; 4;3; 4;4; 5;5; 6;6; 0;0 ]

A user defined dithering pattern can be entered by using the \DITHERVECTOR qualifier and entering the dithering pattern vector, d, as the first parameter.

The dithering pattern is determined by pairs of numbers from d, so the number of dithering patterns defined by d is ½ the length of d.

For pattern number i, every d[2i-1]th pixel is lit up horizontally, and every d[2i]th pixel is lit up vertically. For example, if d[1]=1 and d[2]=1, then for level 1 every pixel is lit up, while if d[3]=2 and d[4]=3, then for level 2 every second pixel is lit up horizontally and every third pixel is lit up vertically.

Changing the range of values

The optional parameters p1 and p2 can be used to broaden or shrink the range of data values. If zmax is the maximum value of the data and zmin} is the minimum value of the data, the full colour range will be from a minimum of min = p1*(zmax-zmin)+zmin to a maximum of max = p2*(zmax-zmin)+zmin. If z is a data value and if z < p1*(zmax-zmin)+zmin, that data value is treated as zmin. If z > p1*(zmax-zmin)+zmin, that data value is treated as zmax. The default values are: p1=0 and p2=1.

Legend

If the \LEGEND qualifier is used, a legend is drawn along the right side of the axes. The legend requires the right end of the x-axis to be set to 75% of the window, that is, XUPPERAXIS is set to 75%.

When a y-profile is drawn, using the \YPROFILE qualifier, the right edge of the axis box must allow space for the profile as well as a possible legend. If a y-legend profile and a legend are present, then XUPPERAXIS is set to 65%. If a y-legend profile is present but not a legend, then XUPPERAXIS is set to 85%.

By default, XUPPERAXIS is reset to its former value after the DENSITY command. If the /-RESET qualifier is used, the axis location is not reset.

Contours

By default, a contour line is drawn around the boundary of each dithering pattern region. If the \-LINES qualifier is used, then these contour lines will not be drawn.

If the qualifier \CONTOURS is used, an automatically created vector named DENSITY$CONTOURS will be made which will contain the boundary values of each region. If there are N regions, the length of DENSITY$CONTOURS will be N+1.

User specified contour levels

A specific set of contour levels can be entered by using \LEVELS and entering a vector of contour level values, lvl, as the first parameter, unless the \DITHERVECTOR qualifier is also used, in which case the contour level vector should be the second parameter. If both are used, and the length of the dithering vector is N, the length of the level vector must be N/2 - 1. Suppose that zmin and zmax are the minimum and maximum of the data z. The level vector must be strictly monotonically increasing, with lvl[1] > zmin and lvl[#] < zmax.

The \EQUALLYSPACED qualifier only applies to the case of a dithering type density plot with legend, where the user supplies the contour levels, for example:

DENSITY\DITHERING\LEVELS\LEGEND\EQUALLYSPACED lvl x y m

If the \EQUALLYSPACED qualifier is used, the legend boxes will all be the same size, irregardless of the values specified in the levels vector, lvl.

Areas and volumes

If the \AREAS qualifier is used, an automatically created vector named DENSITY$AREAS will be made which will contain the percentage areas contained within each region. If the \VOLUMES qualifier is used, an automatically created vector named DENSITY$VOLUMES will be made which will contain the percentage volumes contained within each region. If there are N regions, the length of DENSITY$AREAS and DENSITY$VOLUMES will both be N. Also, the sum of the elements of each of these vectors will always be 100.

Examples

These examples use the following vectors.

 X=[  1;  0;  1;  0;   .2; .3;   .5;  .8]
 Y=[  5;  5;  0;  0;    1;1.5;  2.5;   4]
 Z=[ 10; 10; 10; 10; -100; 10; -100; 500]
 D=[ 1;1; 2;2; 4;4; 7;7; 11;11; 0;0 ]
 
DENSITY\DITHERING X Y Z

DENSITY\DITHERING\LEGEND X Y Z

DENSITY\DITHERING\DITHERVECTOR\LEGEND D X Y Z

  GRADIENTS
  DIFFUSION