Command: graduation

Syntax

graduation <name> {= <dent>}

Description

Create or redefine a graduation identifier.

Parameters

• <name>
  The name of the tile identifier.

• <ident>
  If present, copy the attributes of an existing graduation identifier into the new graduation identifier. All command switches are ignored.

Switches

• -a=<angle>
  The angle of a linear graduation. An angle of 0 (the default) defines a horizontal fill with vertical striped graduations. Angles are measured counter clockwise. The measure of the angle (degrees, radians) is determined by the value of the system string angle_mode. This switch is ignored for non-linear graduations.

• -c=<nums>
  The center of a non-linear graduation. This is an array of 2 numeric values, each with a range -1 through 1 indicating a factor of the maximum bounding rectangle of the area being filled. 0,0 (the default) implies the center, -1,-1 is the top left corner, +1,+1 is the bottom right corner. This switch is ignored by linear graduations

• -fac=<nums>
  An array of blend factors for a custom blend (omit the -ty switch). Each array value provides a factor of (alternately) the start or finish color between 0 and 1. If blend positions are also provided (by the -pos switch), there should be the same number of factors as there are positions.

• -foc<num>
  The blend focus for linear blends (triangular and bell). A value between 0 and 1 is permitted to indicate a position along the full linear graduation. The default value is 0.5, i.e. in the middle.

• -pos=<nums>
  An array of blend positions for a custom blend (omit the -ty switch). Each array value provides a factor of the total graduation distance between 0 and 1. If blend factors are also provided (by the -fac switch), there should be the same number of factors as there are positions.

• -rgb=<nums>
  This switch provides the colors of the graduation in the form of as many sets of red,green,blue triplets necessary to define the start, finish, and possibly intermediate colors. Each color component value must be in the range 0 through 100. There must be at least six values, for example to define a simple graduation from one color to another, i.e. 2 sets of red,green,blue values.

• -sh=<num>
  The shape of the graduation, linear or one of the non-linear variations. The following values are permitted:

  Value	Shape
  0	Linear (the default)
  1	Non-linear automatic (assumes the shape of the bounding area)
  2	Non-linear circular shape
  3	Non-linear square shape

• -ty=<num>
  The blend type, which indicates how the color changes in the transition from start to finish. This applies only to graduations with 2 colors. The following values are permitted:

  Value	Blend type	Description
  0	Normal blend (the default)	The start color graduates to the finish color at a uniform rate.
  1	Triangular blend	The start color graduates to the finish color and back again to the start color. The rate of change is constant and the color-reversion point (i.e. the apex of the color triangle) can be set by a blend focus factor. This reversion point is by default the middle of the fill polygon.
  2	Bell blend	The start color graduates to the finish color and back again to the start color. The rate of change is not constant giving more emphasis to the finish color, and like the triangular blend the color-reversion point (i.e. the top of the color bell) can be set by a blend focus factor.
  omitted	Custom blend	The start color graduates to the finish color but different intermediate intensities may be specified to give a striped effect. Each intensity is specified as a factor of the finish color between 0 and 1, and each intensity position as a factor of the fill distance between 0 and 1. Up to 10 intensities may be specified.

  A custom blend may be specified by omitting this switch and providing custom blend factors and parameters with the -fac and -pos switches.

Notes

The width and height of the tile are defined within the file.

Graduation identifiers can have global or application scope, but cannot have local scope. When local graduation identifiers are required, string identifiers should be used to reference graduations by name.

Examples

A simple 2-color linear graduation, green (0,100,0) to dark grey (30,30,30)

graduation mygrad,-rgb=<0,100,0, 30,30,30>

A 2 color linear graduation, from blue (0,100,0) to yellow (100,100,0), using a bell blend with a three-quarter focus position.

graduation mygrad,-rgb=<blue.rgb,yellow.rgb>,-ty=2,-foc=0.75

A multi-colored (5) linear graduation with 4 positions where the colors change.

graduation mygrad,-rgb=<white.rgb,maroon.rgb,yellow.rgb,green.rgb, 75,75,75>,\ 
    -pos=<0,0.3,0.6,0.8,1>

A non-linear circular graduation, from brown (60,20,20) to yellow (100,100,0), with a non-default center.

graduation mygrad,-rgb=<brown.rgb,yellow.rgb>,-sh=2,-cen=<-1,0>

See Also