@Section
   @Title { Lengths, angles, and points }
   @Tag { figlengths }
@Begin
@PP
We already know that two lengths placed side by side define a point.  This is 
only the simplest of a number of such geometrical combinations.
@PP
The symbol @Code "@Distance" returns the length of the line joining two
distance. @Index @Code "@Distance"
points:
@ID @Code "{0 0} @Distance {3 cm  4 cm}"
is equivalent to the length {@Code "5 cm"}.  The result of @Code "@Distance"
is never negative.  Notice that braces must enclose the two points.  The
symbol @Code "@XDistance" returns the distance in the @Eq { x } direction
xdistance. @Index @Code "@XDistance"
from one point to another:
@ID {
@Code "{" & @Eq { x sub 1 ``` y sub 1 } & @Code "}  @XDistance  {"
& @Eq { x sub 2 ``` y sub 2 } & @Code "}"
}
has for its result the length @Eq { x sub 2 - x sub 1 }, and so may be
negative.  There is an analogous @Code "@YDistance" symbol.
ydistance. @Index @Code "@YDistance"
@PP
The symbol @Code "@Angle" returns the angle @Eq {theta} from one point to
angle. @Index @Code "@Angle"
another:
@ID {
@Code "{" & @Eq { x sub 1 ``` y sub 1 } & @Code "}  @Angle  {"
& @Eq { x sub 2 ``` y sub 2 } & @Code "}"
||7ct
@Fig {
@Figure
   arrow { forward }
   shape { 4 cm 0 0 0 4 cm 3 cm }
{ 4c @Wide 3c @High }
// {4 cm 3 cm} ** 0.4 ++ { 0.5 cm 0 } @MarkOf @Eq { (x sub 1 & , y sub 1 & ) }
// {4 cm 3 cm} ** 0.4 @BaseOf @Circle margin { 0.05c } paint { black } {}
// {4 cm 3 cm} ** 0.8 ++ { 0.5 cm 0 } @MarkOf @Eq { (x sub 2 & , y sub 2 & ) }
// {4 cm 3 cm} ** 0.8 @BaseOf @Circle margin { 0.05c } paint { black } {}
// { 1 cm 0.2 cm } ** 0.7 @BaseOf @Eq { theta }
}
}
The result will be 0 if the two points are equal.  The symbol @Code "<<"
returns the point at a given distance and angle from @Eq { (0, 0) }:
@ID {
@Code "{" & @Eq { length }  @Code "<<"  @Eq { theta } & @Code "}"
||7ct
@Fig {
@Figure
   arrow { forward }
   shape { 4 cm 0 0 0 4 cm 3 cm }
{ 4c @Wide 3c @High }
// {4 cm 3 cm} ** 0.5 -- {1.5 cm 0} @BaseOf @I length
// {4 cm 3 cm} ** 0.8 @BaseOf @Circle margin { 0.05c } paint { black } {}
// { 1 cm 0.2 cm } ** 0.7 @BaseOf @Eq { theta }
}
}
For example, @Code "{ 5 cm << 45 dg }" is the point 5 cm
from @Eq { (0, 0) } at 45 degrees.
@PP
Points may be added, subtracted, and multiplied by a number:
"++" @Index { @Code "++" symbol (in Fig) }
"--" @Index { @Code "--" symbol (in Fig) }
"**" @Index { @Code "**" symbol (in Fig) }
@ID @Tab
     vmargin { 0.5vx }
     @Fmta { @Col A ! @Col is ! @Col B }
{
@Rowa
   A { @Code "{" & @Eq {x sub 1 ``` y sub 1} & @Code "}  ++  {" &
@Eq {x sub 2 ``` y sub 2} & @Code "}" }
   B { @Eq { (x sub 1 + x sub 2 & , y sub 1 + y sub 2 & ) } }
@Rowa
   A { @Code "{" & @Eq {x sub 1 ``` y sub 1} & @Code "}  --  {" &
@Eq {x sub 2 ``` y sub 2} & @Code "}" }
   B { @Eq { (x sub 1 - x sub 2 & , y sub 1 - y sub 2 & ) } }
@Rowa
   A { @Code "{" & @Eq {x sub 1 ``` y sub 1} & @Code "}  **  " & @Eq {k} }
   B { @Eq { (x sub 1 & k, y sub 1 & k) } }
}
For example,
@ID {
@Code "{" & @Eq {x sub 1 ``` y sub 1} & @Code "} ** 0.2  ++  " &
@Code "{" & @Eq {x sub 2 ``` y sub 2} & @Code "} ** 0.8"
}
is the point eight tenths of the way from 
@Eq { (x sub 1 & , y sub 1 & ) } to
@Eq { (x sub 2 & , y sub 2 & ) } on the line joining them:
@LP
@ID @Fig {
@Figure
   shape {
      {xsize 0} ** 0.3 ++ {0 ysize} @Label P1
      {xsize 0} ++ {0 ysize} ** 0.4 @Label P2
      P1 ** 0.2 @Label FP1
      P2 ** 0.8 @Label FP2
      0 0 P1 P2 0 0 [] FP1 FP1 ++ FP2 FP2
   }
{ 6c @High 9c @Wide }
// P1 ++ {0.3 cm 0} @BaseOf @Eq { (x sub 1 & , y sub 1 & ) }
// P2 ++ {0.3 cm 0} @BaseOf @Eq { (x sub 2 & , y sub 2 & ) }
// FP1 ++ FP2 ++ {0.3 cm 0} @BaseOf
@Eq { (0.2x sub 1 & + 0.8x sub 2 & , 0.2y sub 1 & + 0.8y sub 2 & ) }
}
When using {@Code "**"}, the point must be on the left and the number on
the right.  It would be more convenient to name these symbols
{@Code "+"}, {@Code "-"}, and {@Code "*"}, but these names
are often taken by equation formatters, and @Code "-" appears in
lengths, so we don't.  There are @Code "@Max" and @Code "@Min" symbols:
@ID @Tab
     vmargin { 0.5vx }
     @Fmta { @Col A ! @Col is ! @Col B }
{
@Rowa
  A { @Code "{" & @Eq {x sub 1 ``` y sub 1} & @Code "}  @Max  {" &
@Eq {x sub 2 ``` y sub 2} & @Code "}" }
  B { @Eq { (max(x sub 1 & , x sub 2 & ), max(y sub 1 & , y sub 2 & )) } }
@Rowa
  A { @Code "{" & @Eq {x sub 1 ``` y sub 1} & @Code "}  @Min  {" &
@Eq {x sub 2 ``` y sub 2} & @Code "}" }
  B { @Eq { (min(x sub 1 & , x sub 2 & ), min(y sub 1 & , y sub 2 & )) } }
}
Note carefully that these apply to points, not to numbers.
@PP
The result of adding two points together depends on where the origin is
at the time, as well as on the points themselves.  This can lead to
unexpected results, as the author has found to his cost more than
once.  Within the @Code shape option of {@Code "@Figure"}, the origin is
the lower left corner of the result of the {@Code "@Figure"}.  In cases
like the example on page {@PageOf sumpoints}, where points are added
outside of any {@Code "@Figure"} symbol, the origin is usually at the
bottom left corner of the figure as a whole.  A label always denotes a
particular point on the printed page, regardless of where the origin
happens to be.
@PP
The symbol @Code "@Prev" within the @Code "shape" option of
prev. @Index @Code "@Prev"
@Code "@Figure" denotes the previous point of the shape, ignoring points
within {@Code {"[" &0.5s "]"}}.  This makes it easy to specify each point
relative to the previous one:
@ID {
@Code {
"   shape {"
"      0 0"
"      { 2 cm << 30 }"
"      @Prev ++ { 2 cm << 90 }"
"      @Prev ++ { 2 cm << 150 }"
"      @Prev ++ { 2 cm << 210 }"
"      @Prev ++ { 2 cm << 270 }"
"      0 0"
"   }"
}
||7ct
@Fig { ||2.5c
@Figure
   shape {
      0 0
      { 2 cm << 30 }
      @Prev ++ { 2 cm << 90 }
      @Prev ++ { 2 cm << 150 }
      @Prev ++ { 2 cm << 210 }
      @Prev ++ { 2 cm << 270 }
      0 0
   }
{ 4c @Wide 4c @High }
}
}
@PP
There is a @Code "@Label" symbol, available only within the
@Code "shape" option of {@Code "@Figure"}, for attaching a label to
label. @Index { @Code "@Label" in figures }
a point in the shape, like this:
@ID @Code "{xsize ysize} ** 0.5 @Label CTR"
The point may then be referred to more concisely by its label,
{@Code CTR}.  For example, the large arrow appearing in Section
{@NumberOf newshapes} was built like this:
@ID {
@Code {
"@Figure"
"   shape {"
"      {0 ysize} ** 0.4 @Label SB"
"      {0 ysize} ** 0.6 @Label ST"
"      {xsize 0} ** 0.7 @Label HB"
"      SB"
"      SB ++ HB"
"      HB"
"      {xsize 0} ++ {0 ysize} ** 0.5"
"      HB ++ {0 ysize}"
"      HB ++ ST"
"      ST"
"      SB"
"   }"
"   paint { grey }"
"{ 6c @Wide 2c @High }"
}
||7ct
@Fig {
@Figure
   shape {
      {0 ysize} ** 0.4 @Label SB
      {0 ysize} ** 0.6 @Label ST
      {xsize 0} ** 0.7 @Label HB
      SB
      SB ++ HB
      HB
      {xsize 0} ++ {0 ysize} ** 0.5
      HB ++ {0 ysize}
      HB ++ ST
      ST
      SB
   }
   paint { grey }
{ 6c @Wide 2c @High }
// @ShowLabels
}
}
Incidentally, the labels of a figure can be displayed as above by putting
showlabels. @Index { @Code "@ShowLabels" in figures }
the symbol @Code "@ShowLabels" at the end of the figure.  Labels can
save a lot of effort.  They should contain only digits, upper-case
letters and {@Code "@"}, because @Code "@Fig" and Lout itself use labels
of their own made from lower-case letters.
@PP
The standard shapes have standard labels; for example, the labels
of @Code "@Ellipse" are
@LP
@ID {
@Code {
"@Ellipse"
"{ 3c @Wide 2c @High }"
}
||7ct
@Fig {
@Ellipse { 3c @Wide 2c @High }
// @ShowLabels
}
}
There is a symbol, {@Code "::"}, for @I relabelling an object.  Each
label in the right parameter is relabelled in the following way:
@LP
@ID {
@Code {
"E1:: @Ellipse"
"{ 3c @Wide 2c @High }"
}
||7ct
@Fig {
E1:: @Ellipse { 3c @Wide 2c @High }
// @ShowLabels
}
}
Within the right parameter of @Code "::" the original names hold sway;
but afterwards the names are changed by prefixing the label and @Code "@"
to them.  These composite labels may be used exactly like other
labels.  Relabelling can be nested to arbitrary depth:
@LP
@ID {
5c @Wide @Code {
"A::"
"{   1:: @Ellipse"
"    { 3c @Wide 2c @High }"
"    //1c"
"    2:: @Box"
"    { 3c @Wide 2c @High }"
"}"
}
||7ct
@Fig {
A::
{   1:: @Ellipse { 3c @Wide 2c @High }
    //1c
    2:: @Box { 3c @Wide 2c @High }
}
// @ShowLabels
}
}
The right parameter of @Code "::" may be any object.
@PP
The eight standard shapes ({@Code "@Box"}, {@Code "@CurveBox"},
{@Code "@ShadowBox"}, {@Code "@Square"}, {@Code "@Diamond"},
{@Code "@Polygon"}, {@Code "@Ellipse"}, and
{@Code "@Circle"}) have a special @Code CIRCUM label, not displayed by
circum.label @Index { @Code "CIRCUM" label in figures }
{@Code "@ShowLabels"}.  The expression
@ID {
@Eq { "angle" } @Code CIRCUM
}
yields the point on the boundary of the shape at the given angle from
the centre, in a coordinate system with the centre for origin.  Thus,
given a labelled standard shape such as
@ID @Code "A :: @Ellipse ..."
the point on its boundary at an angle of 45 degrees from the centre is
@ID @Code "A@CTR ++ {45 A@CIRCUM}"
The braces must be present.  Regrettably, there is no way to produce a
@Code CIRCUM label for shapes defined by the user in any reasonable time.
@PP
If the same label is used twice, as is inevitable with unlabelled standard
shapes, only the most recent value is remembered.  There is a limit on the
maximum number of distinct labels in any one figure, which can be changed
by means of an option to the @Code "@Fig" symbol:
@ID @OneRow @Code {
"@Fig"
"   maxlabels { 500 }"
"{ ... }"
}
The default value is 200.
@FootNote {
In recent versions of PostScript, a change has been made which has
the effect of automatically increasing the value of @Code maxlabels
when required.  In those versions you can safely forget about
{@Code "maxlabels"}.
}
 Large values could cause the printing device to run out of
memory.  Memory is reclaimed at the end of each figure.
@End @Section
