@c pattern.texi

@c This file is part of the 3DLDF User and Reference Manual.
@c Copyright (C) 2003, 2004 Laurence D. Finston 
@c See the section "GNU Free Documentation License" in the file 
@c fdl.texi for copying conditions.

@c $Id: pattern.texi,v 1.4 2004/01/12 18:40:03 lfinsto1 Exp lfinsto1 $

@node Pattern Reference, Solid Reference, Circle Reference, Top
@chapter Pattern Reference


There is no currently no class ``@code{Pattern}''.
If it turns out to be
useful for this purpose, I will define a @code{Pattern} class, and
perhaps additional derived classes.

@menu
* Plane Tesselations::          
* Roulettes and Involutes::     
@end menu

@node Plane Tesselations, Roulettes and Involutes, Pattern Reference, Pattern Reference
@section Plane Tesselations

3DLDF can be used to make perspective projections of plane tesselations
and other two-dimensional patterns.  These can be used for 
drawing tiled floors and other architectural items, among other things.  
While patterns can be generated by using the basic facilities of @cpp{} and
3DLDF without any specially defined functions, it can be useful to
define such functions.

3DLDF currently contains only one function for drawing patterns based on
a plane tessellation.  I plan to add more soon.

@deftypefun {unsigned int} hex_pattern_1 ([real @var{diameter_outer} = 5, [real @var{diameter_middle} = 0,              [real @var{diameter_inner} = 0, [{unsigned short} @var{first_row} = 5, [{unsigned short} @var{double_rows} = 10, [{unsigned short} @var{row_shift} = 2, [Color @var{draw_color_outer} = @code{*Colors::default_color}, [Color @var{fill_color_outer} = @code{*Colors::background_color}, [Color @var{draw_color_middle} = @code{*Colors::default_color}, [Color @var{fill_color_middle} = @code{*Colors::background_color}, [Color @var{draw_color_inner} = @code{*Colors::default_color}, [Color @var{fill_color_inner} = @code{*Colors::background_color}, [string @var{pen_outer} = "pencircle scaled .5mm", [string @var{pen_middle} = "pencircle scaled .3mm", [string @var{pen_inner} = "pencircle scaled .3mm", [Picture& @var{picture} = @code{current_picture}, [{unsigned int} @var{max_hexagons} = 1000]]]]]]]]]]]]]]]]])
@c
Draws a pattern consisting of hexagons forming a tesselation of the x-z
plane, with additional hexagons within them.

The arguments:
@table @asis
@item @code{real} @var{diameter_outer}
Default:  5.  The diameter of the outer hexagon in each set of three
hexagons.  The outer hexagons form a tessellation of the plane.

@item @code{real} @var{diameter_middle} 
Default: 0.  The diameter of the middle hexagon in a set of three
hexagons. 

@item @code{real} @var{diameter_inner} 
Default: 0.  The diameter of the inner hexagon in a set of three
hexagons. 

@item @code{unsigned short} @var{first_row} 
Default: 5.  The number of sets of hexagons in the first single row.
The second single row will have 
@math{@var{first_row} + 1} sets of hexagons.


@item @code{unsigned short} @var{double_rows} 
Default: 10.  The number of double rows drawn.

@item @code{unsigned short} @var{row_shift} 
Default: 2.  
For @var{row_shift}
@c
@iftex 
@tex
$\neq 0$,
@end tex
@end iftex
@ifnottex
@math{!= 0}, 
@end ifnottex 
@c
the number of sets of hexagons in each (single) row is
increased by 2 every @var{row_shift} rows.  If @var{row_shift} @equiv{}
0, the number sets of hexagons remains constant.
The rows remain centered around the z-axis.

@item @code{Color} @var{draw_color_outer}
Default: @code{*Colors::default_color}.  
The @code{Color} used for drawing the outer hexagons.

@item @code{Color} @var{fill_color_outer} 
Default: @code{*Colors::background_color}.
The @code{Color} used for filling the outer hexagons.

@item @code{Color} @var{draw_color_middle} 
Default:  @code{*Colors::default_color}.  
The @code{Color} used for drawing the middle hexagon.

@item @code{Color} fill_color_middle 
Default:  @code{*Colors::background_color}.
The @code{Color} used for filling the middle hexagons.

@item @code{Color} @var{draw_color_inner} 
Default:  @code{*Colors::default_color}.
The @code{Color} used for drawing the inner hexagons.

@item @code{Color} @var{fill_color_inner} 
Default:  @code{*Colors::background_color}.
The @code{Color} used for filling the inner hexagons.

@item @code{string} @var{pen_outer}
Default: @code{"pencircle scaled .5mm"}.
The pen used for drawing the outer hexagons.

@item @code{string} @var{pen_middle}
Default:  @code{"pencircle scaled .3mm"}.
The pen used for drawing the middle hexagons.

@item @code{string} pen_inner 
Default:  @code{"pencircle scaled .3mm"}.
The pen used for drawing the inner hexagons.

@item @code{Picture&} @var{picture} 
Default:  @code{current_picture}.
The @code{Picture} onto which the pattern is put.

@item @code{unsigned int} @var{max_hexagons} 
Default:  1000.
The maximum number of hexagons that will be drawn.

@end table

Draws a pattern in the x-z plane consisting of hexagons.  The outer
hexagons form a tessellation.  The middle and inner hexagons fit
within the outer hexagons.  The hexagons are drawn in double rows.
The tessellation can be repeated by copying a
double row and shifting the copy to lie directly behind the first double
row.  If the @code{Picture} with the pattern is projected with the
@code{Focus} in front of the pattern, looking in the direction of the back
of the pattern,
the first row of hexagons will appear larger than the rows
behind it.  Therefore, in order for the perspective projection of the
pattern to fill a rectangular area on the plane of projection,
it will generally be necessary to increase the number of sets of
hexagons in each double row.  On the other hand, if the same number of
sets of hexagons were used in the front double row, as will be needed for the
back double row, many of them would probably be unprojectable.  

The return value of this function is the number of hexagons drawn. 

@example
default_focus.set(0, 10, -10, 0, 10, 25, 10);
hex_pattern_1(1, 0, 0, 5, 5);
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(0, 10, -10, 0, 10, 25, 10);}
\immediate\write\examples{hex_pattern_1(1, 0, 0, 5, 5);} 
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.178.png"
alt="[Figure 178. Not displayed.]"
/>
<br>
<br>
Fig. 178.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 178 not displayed.]
@end ifinfo

@example
default_focus.set(-5, 5, -10, 0, 10, 25, 10);
hex_pattern_1(2, 1.5, 1, 2, 5, 2, black, gray, black, 
              light_gray, black); 
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(-5, 5, -10, 0, 10, 25, 10);}
\immediate\write\examples{hex_pattern_1(2, 1.5, 1, 2, 5, 2, black, gray, black, light_gray, black);} 
\OEX{}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.179.png"
alt="[Figure 179. Not displayed.]"
/>
<br>
<br>
Fig. 179.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 179 not displayed.]
@end ifinfo

@end deftypefun 

@node Roulettes and Involutes,  , Plane Tesselations, Pattern Reference
@section Roulettes and Involutes

@quotation
``A @dfn{roulette} is the curve generated by a point which is carried by
a curve which rolls on a fixed curve. [@dots{}]  The locus of a point
carried by a circle rolling on a straight line is a @dfn{trochoid}.  If
the point is inside the circle the trochoid has inflexions;  if it is
outside the circle, but rigidly attached to it, the trochoid has loops.
[@dots{}]  In the particular case when the point is on the circumference
of the rolling circle the roulette is a @dfn{cycloid}.  When the circle
rolls on the outside of another circle the corresponding curves are the
@dfn{epitrochoids} and @dfn{epicycloids};  if it rolls on the inside,
they are the @dfn{hypotrochoids} and @dfn{hypocycloids}.''
@flushright
H. Martyn Cundy and A. P. Rollett, @emph{Mathematical Models}, p.@: 46.
@end flushright
@end quotation

@menu
* Epicycloids::                 
@end menu
 
@node Epicycloids,  , Roulettes and Involutes, Roulettes and Involutes
@subsection Epicycloids

@c !! TO DO:  Check whether @code{epicycloid_pattern_3()} works.  If it
@c does, document it here.  LDF 2003.09.02.

@deftypefun {unsigned int} epicycloid_pattern_1 (real @var{diameter_inner}, real @var{diameter_outer_start}, real @var{diameter_outer_end}, real @var{step}, int @var{arc_divisions}, {unsigned int} @var{offsets}, [{vector<const Color*>} @var{colors} = @code{Colors::default_color_vector}])
@c
Draws a pattern consisting of epicycloids.  The  outer circle rolls
around the circumference of the inner circle and a @code{Point} on the
outer circle traces an epicycloid.  


If @var{offsets} is greater than 1, the outer circle is rotated
@var{offset} times around the center of the inner circle 
by 
@iftex 
@tex
$360 / \sl{offsets\/}$ 
@end tex
@end iftex
@c
@ifnottex 
@math{360 / offsets} 
@end ifnottex 
@c
(starting from the outer circle's original
position).  From each of these new positions, an epicycloid is drawn.


While @var{diameter_outer_start} is
greater than or equal to @var{diameter_outer_end}, the diameter of the
outer circle is reduced by @var{step}, and another set of epicycloids is
traced, as described above.  Each time the diameter of
the outer circle is reduced, a new @code{Color} is taken from
@var{colors} for the drawing commands.  If there are more iterations
than @code{Colors}, the last @code{Color} on @var{colors} is used for
the remaining iterations.

@c !! TO DO:  Change function, so that the list is run through again.

The arguments:
@table @asis
@item @code{real} @var{diameter_inner}
The diameter of the inner circle.  

@item @code{real} @var{diameter_outer_start}
The diameter of the outer circle for the first iteration.  It must be
greater than or equal to @var{diameter_outer_end}. 

@item @code{real} @var{diameter_outer_end}
The diameter of the outer circle for the last iteration.  
It must be
less than or equal to @var{diameter_outer_start}.   

@item @code{real} @var{step}
The amount by which the diameter of the outer circle is @emph{reduced}
upon each iteration.

@item @code{int} @var{arc_divisions}
The number of divisions of the circle used for calculating @code{Points}
on the epicycloid.  For instance, if @var{arc_divisions} is 90, then
the @code{Path} for each epicycloid will only have 4 @code{Points},
since @math{360 / 90 = 4}.  

@item @code{unsigned int} @var{offsets}
The number of epicycloids drawn upon each iteration.  Each one is
rotated by @math{360 / @var{offsets}} around the center of the inner circle.
@var{offsets} must be greater than or equal to 1.

@item @code{vector<const Color*>} @var{colors}
Default: @code{Colors::default_color_vector}.  The @code{Colors} pointed
to by the pointers on this vector are used for drawing the epicycloids.  
One @code{Color} is used for each iteration.

@end table


Example:
@example
epicycloid_pattern_1(5, 3, 3, 1, 72);
current_picture.output(Projections::PARALLEL_X_Z);
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{epicycloid_pattern_1(5, 3, 3, 1, 72);} 
\OEX{Projections::PARALLEL_X_Z}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.180.png"
alt="[Figure 180. Not displayed.]"
/>
<br>
<br>
Fig. 180.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 180 not displayed.]
@end ifinfo

Example:
@example
default_focus.set(2, 5, -10, 2, 5, 10, 10);  
epicycloid_pattern_1(5, 3, 3, 1, 36);
current_picture.output();
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(2, 5, -10, 2, 5, 10, 10); }
\immediate\write\examples{epicycloid_pattern_1(5, 3, 3, 1, 36);} 
\OEX{}
\EGRP
\EEX 1
\fi
\PEX     
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.181.png"
alt="[Figure 181. Not displayed.]"
/>
<br>
<br>
Fig. 181.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 181 not displayed.]
@end ifinfo

@end deftypefun 
