<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="/pattern.xsl"?>
<pattern id="">
  <name>Selector</name>
<relatedPatterns>
  <relatedPattern ref="">
      <patternLink>Reporter</patternLink>
  </relatedPattern>
  <relatedPattern ref="" />
</relatedPatterns>
  <diagram>
    <img src="DiagramSele.jpg" width="400"  />			
  </diagram>
  <what>
    <paragraph>
      Select members of a collection that have specified properties.
    </paragraph>		
  </what>
  <when>
    <paragraph>
      Selection is a universal in interactive systems. In parametric
      systems, selection can be part of the model itself. At each
      update of the propagation graph, objects can select the
      arguments to their update methods. Use this pattern when you
      want to locally and dynamically restructure a model depending its
      state.
    </paragraph>
  </when>
  <why>
    <paragraph>
      Creating objects and using objects are different acts. You will
      often specify, say, a set of points by giving their Cartesian
      coordinates. When it comes to using these points, you might be
      interested only in those that are close to a line. The selector
      pattern allows you to separate object creation and later use,
      and express these two common operations in the terms most
      suitable for each.
    </paragraph>
  </why>
  <how>
    <paragraph>
      In the <patternName>Selector</patternName> pattern, there is
      always a collection of given objects and a collection that is
      the outcome of the <patternName>Selector's</patternName> action.
      We call the first list the <em>target</em> and the second list
      the <em>result</em>. The <patternName>Selector</patternName>
      object mediates between these by determining which elements of
      the target to include in the result.  The properties that
      objects must have or conditions they must meet in order to be
      selected we call the <patternName>Selector's</patternName>
      <em>behavior</em>.
    </paragraph>
    <paragraph>
      For example (See the Sample entitled Distance between Points), the
      target may be a list of points and the
      <patternName>Selector</patternName> a compound of a point, a
      circle and a function. The point provides the location of the
      <patternName>Selector</patternName>; the circle displays the
      distance within which selection will occur; and the function
      specifies how points will be selected and how selected points
      will be constructed. The function embodies the
      <patternName>Selector</patternName>'s behaviour. The aim is to
      select the points whose distance to the
      <patternName>Selector</patternName> point is less than (or
      greater than or equal to) the variable <math latex="d">d</math>
      which itself parameterizes the
      <patternName>Selector</patternName>'s behavior.
    </paragraph>
    <paragraph>
      The simplest representation of a
      <patternName>Selector</patternName>'s behaviour is a function<latex>\index{function}</latex>
      that considers each of the target points individually.  For each
      target, it computes the behaviour and returns a copy of any
      objects that conform. For instance, with selection based on
      distance, a <patternName>Selector</patternName> compares the
      distance between target and <patternName>Selector</patternName>
      against the threshold <math latex="d">d</math>. If the target
      object satisfies the condition, the function creates a
      coincident point and returns this point (acting in a sense as a
      <patternLink>Reporter</patternLink>).  As a result, the
      function's (and <patternName>Selector</patternName>'s) output
      will be a new list of points.
    </paragraph>
    <paragraph>
      The result is not a subset of the target. Rather, it is a new
      set of points, identical to the selected points in the target.
    </paragraph>
  </how>

<pre>			
function selectByDistance(Point selector, 
                          Point target, 
                          double distance)
 {                                        
  for (value i = 0; i &lt; target.Count; ++i)
   {                                            
    if (Distance(selector,target[i]) &lt; distance)
     {
      Point result= new Point(this);
      result.ByCartesianCoordinates(baseCS, 
                                    target[i].X, 
                                    target[i].Y, 
                                    target[i].Z);
     }
   }
 };		
</pre>	

<more>
An actual call to the <patternName>Selector</patternName>'s behaviour function would take the following form:
</more>

<pre>
selectByDistance(selector,target,distance);		
</pre>	

<more>
where <exp>selector</exp> and <exp>target</exp> are points<latex>\index{point}</latex> (or point
collections) in the model and <exp>distance</exp> is a value held in a
model variable<latex>\index{variable}</latex> or object property<latex>\index{property}</latex>.
</more>
 
  <samples>
    
    <sample id="DistanceBetweenPoints">
      <name>Distance between Points</name>
      <when>
	<paragraph>
	  Select points from a collection depending on
	  their distance to a selector point.
	</paragraph>
      </when>
      <how>
	<paragraph>
	  First write a function<latex>\index{function}</latex> a condition for target points to be
	  selected. In this sample example,  the
	  distance between the target and the selector point must be
	  less than variable <math latex="d">d</math>.
	</paragraph>
	<paragraph>
	  Write a behaviour function that checks the target points one
	  by one and compares the distance between each point and the
	  selector point using the threshold <math
	  latex="d">d</math>. For each member of the list, if the
	  condition is satisfied, the selector function creates a copy
	  of the target point.
	</paragraph>
	<paragraph>
	  The behaviour function returns a new list of result points
	  that are within distance <math latex="d">d</math> of the
	  selector point. Note that the structure of the target and
	  result my differ. For instance, the target may be a 2D array<latex>\index{data structure!array}</latex>
	  and the result a 1D array. You have to make and remember such choices.
	</paragraph>
      </how>
      <a href="Samples/SeleDistanceBetweenPoints/SeleDistanceBetweenPoints.gct" >Click to download SeleDistanceBetweenPoints.gct</a> 				
      <animation src="Samples/SeleDistanceBetweenPoints/AnimationDistanceBetweenPoints00.swf"/>			
    </sample>
    
    <sample id="PartOfCurve">
      <name>Part of Curve</name>
      <when>
	<paragraph>
	  Select part of a curve depending on its
	  distance to a point.
	</paragraph>
      </when>
      <how>
	<paragraph>
	  Place a collection of parametric points<latex>\index{point}</latex> on the curve<latex>\index{curve}</latex>. Use
	  the same mechanism for selecting these points as in the
	  sample <em>Distance between Points.</em> Write a function
	  that checks each of the points and reports them if they
	  satisfy the condition.
	</paragraph>
	<paragraph>
	  Placing a curve through the selected points yields an
	  approximate copy of part of the original curve. Moving the
	  selector point, controls the part of the curve to be
	  copied. The more points on the original curve, the more
	  accurate the selected curve.
	</paragraph>
	<paragraph>
	  The original points sample the curve and so will not
	  generally capture the exact point on the curve that is at
	  the specified distance. This problem may be addressed by
	  searching between the last selected point and the first
	  non-selected point for the point at which the distance to
	  the selector is exactly the threshold. If, however, the original
	  points are widely spaced, very small sections of the curve
	  that are within the threshold might fail to be
	  detected. This can be addressed by projecting<latex>\index{transformation!projection}</latex> the selector
	  point onto the curve. If the distance to the selector point
	  is less than than the threshold, search on either side of
	  the projected point for the exact end points of the curve.
	</paragraph>
      </how>
      <a href="Samples/SelePartOfACurve/SelePartOfACurve.gct" >Click to download SelePartOfACurve.gct</a> 
      <animation src="Samples/SelePartOfACurve/AnimationPartOfACurve00.swf"/>			
    </sample>				
    
    <sample id="LinesInsideCurve">
      <name>Lines inside Curve</name>
      <when>
	<paragraph>
	  Select all lines that are completely inside a closed curve.
	</paragraph>
      </when>
      <how>
	<paragraph>
	  This <patternName>Selector</patternName> has two parts.
	</paragraph>
	<paragraph>
	  First, if a line<latex>\index{line!segment}</latex> segment is entirely inside or outside a curve<latex>\index{curve}</latex> it
	  does not intersect the curve. In order to check the position
	  of a line against a curve, first compute the
	  intersection. If the result is null, the line may be either
	  inside or outside.
	</paragraph>

	<latex>
          \begin{bodyNote}
            \pbOneCol
              {
                \input{\GCFigsPath/Patterns/SeleJordanCurve10.tex}
                \input{\GCFigsPath/Patterns/SeleJordanCurve20.tex}
              }
          \end{bodyNote}
	</latex>
	<web>
	  <img src="Samples/SeleLinesInsideCurve/SeleLinesInsideCurve20.jpg" width="400"  />
	</web>

	<paragraph>
          Second, if an endpoint of a non-intersecting line is inside
          the curve, so is the line. The Jordan Curve theorem<latex>\index{Jordan Curve theorem}</latex> states
          that a point is inside a closed curve if a line segment
          between the point and anther points external to the curve
          intersects the curve an odd number of times. Use the Jordan
          Curve theorem to determine the position of either end of the
          line segment against the closed curve. Don't count
          tangencies as crossings! If the number of intersections is
          odd, the line is inside the curve.
	</paragraph>

	<latex>
          \begin{bodyNote}
            \pbOneCol
              {
                \input{\GCFigsPath/Patterns/SeleJordanCurve30.tex}
                \input{\GCFigsPath/Patterns/SeleJordanCurve40.tex}
              }
          \end{bodyNote}
	</latex>
	<web>
	  <img src="Samples/SeleLinesInsideCurve/SeleLinesInsideCurve21.jpg" width="400"  />
	</web>
	
      <paragraph>
	Write a function<latex>\index{function}</latex> that performs both of the above tests in
	turn. If both succeed (non-intersection of the segment and odd
	intersections of a ray from an end point) copy and return the
	line.
      </paragraph>
    </how>
    <a href="Samples/SeleLinesInsideCurve/SeleLinesInsideCurve.gct" >Click to download SeleLinesInsideCurve.gct</a> 
    <animation src="Samples/SeleLinesInsideCurve/AnimationLinesInsideCurve00.swf"/>			
  </sample>

  
  <sample id="PointsInsideSector">
    <name>Points inside Sector</name>
    <when>
      <paragraph>
	Select the points<latex>\index{point}</latex> that lie inside a 2D sector (two vectors bound to a common point).
      </paragraph>
    </when>
    <how>
      <paragraph>
	The sector comprises a base point and two vectors <math latex =
	"\afVr[u]">u</math> and <math latex = "\afVr[v]">v</math> bound to it. Taken in
	order, these define an angle between <math latex="0">0</math> and <math
	latex="360^{\circ}">360 degrees</math>. Imagine a target vector <math latex =
	"\afVr[a]">a</math> for each target point connecting from the base point to the
	target point. Take the two cross products<latex>\index{vector!cross product}</latex> <math latex =
	"\afVr[u]\otimes\afVr[a]"></math> and <math latex =
	"\afVr[a]\otimes\afVr[v]"></math>. Remember <latex>from Section
	\ref{sec:Frames:cross-prod}</latex> that the right hand rule<latex>\index{frame!right hand rule}</latex>
	determines the orientation of the cross product of two
	vectors. If the angle between the vectors <math latex =
	"\afVr[u]">u</math> and <math latex = "\afVr[v]">v</math> is less than <math
	latex="180^{\circ}">180 degrees</math>, a target point is between two selector
	vectors if the <math>z</math>-components of both the cross products of its vector
	with the selector vectors are positive.  If the angle<latex>\index{angle}</latex> is greater than <math
	latex="180^{\circ}">180 degrees</math>, the target point is in the sector if one
	or both of the cross products are positive.
      </paragraph>

      <paragraph>
	<web>
	<img src="Samples/SelePointsInsideSector/SelePointsInsideSector35.jpg" width="650"  />	
	</web>
	<latex>
          \begin{bodyNote}
	    \pbOneCol
	      {
	        \input{\GCFigsPath/Geometry/crossProductInLt180.tex}
		\input{\GCFigsPath/Geometry/crossProductOutLt180.tex}
	      }
              \vspace{3mm}
	    \pbOneCol
	      {
	        \input{\GCFigsPath/Geometry/crossProductInReflex.tex}
		\input{\GCFigsPath/Geometry/crossProductOutReflex.tex}
	      }
          \end{bodyNote}
	</latex>
      </paragraph>
	
      <paragraph>
	The scalar product<latex>\index{vector!scalar product}</latex> determines if the sector given by the base point and <math latex =
	"\afVr[u]">u</math> and <math latex = "\afVr[v]">v</math> is greater than <math
	latex="180^{\circ}">180 degrees</math>. If the sector is between <math
	latex="0">0s</math> and <math latex="180^{\circ}">180 degrees</math>, <math latex = "\afDot{\afVr[u]}{\afVr[v]}">u.v</math>
	is positive. If the sector is between <math latex="180">180</math> and
	<math latex="360^{\circ}">360 degrees</math>, <math latex = "\afDot{\afVr[u]}{\afVr[v]}">u.v</math> is negative.
      </paragraph>

      <paragraph>
	When <math latex = "\afVr[u]">u</math> and <math latex = "\afVr[v]">v</math> are
	colinear, the sector is either <math latex="0^{\circ}">0 degrees</math> (<math latex =
	"\afDot{\afVr[u]}{\afVr[v]} \geq 0">u.v &gt; = 0</math>) or <math latex="180^{\circ}">180
	degrees</math> (<math latex = "\afDot{\afVr[u]}{\afVr[v]} \le 0 ">u.v &lt; 0</math>).
      </paragraph>

      <web>
	<paragraph>
	  <img src="Samples/SelePointsInsideSector/SelePointsInsideSector30.jpg" width="450"  />
	</paragraph>
      </web>	

      <paragraph>
	The selector function<latex>\index{function}</latex> iterates over the target points<latex>\index{point}</latex> one by
	one. For each point, it computes the two cross products<latex>\index{vector!cross product}</latex><math latex =
	"\afVr[u]\otimes\afVr[a]"></math> and <math latex =
	"\afVr[a]\otimes\afVr[v]"></math>. Using the rules above it determines if each point lies within the sector and includes each successful point in the result.
      </paragraph>
    </how>
    <a href="Samples/SelePointsInsideSector/SelePointsInsideSector.gct" >Click to download SelePointsInsideSector.gct</a> 
    <a href="Samples/SelePointsInsideSector/SelePointsInside3DSector.gct" >Click to download SelePointsInside3DSector.gct</a> 
    <animation src="Samples/SelePointsInsideSector/AnimationPointsInsideSector00.swf"/>			
  </sample>

  
  <sample id="PointsinsideBox">
    <name>Points inside Box</name>
    <when>
      <paragraph>
	Select points that are inside a box.
      </paragraph>
    </when>
    <how>
      <paragraph>
	Write a behaviour function<latex>\index{function}</latex> that checks the position of the
	target points<latex>\index{point}</latex> against the box. The function reports their
	position in the coordinate system<latex>\index{frame}</latex> of the selector box one by
	one and compares their new coordinates to two opposite corners
	of the box. The function then reports them in the result list
	if they are inside the box.
      </paragraph>
    </how>
    <a href="Samples/SelePointsInsideBox/SelePointsInsideBox.gct" >Click to download SelePointsInsideBox.gct</a> 
    <animation src="Samples/SelePointsInsideBox/AnimationPointsInsideBox00.swf"/>						
  </sample>

  <latex>\renewcommand{\sampleNewPage}[0]{false}</latex>  
  <sample id="LengthofLine">
    <name>Length of Line</name>
    <when>
      <paragraph>
	Select lines based on their length.
      </paragraph>
    </when>
    <how>
      <paragraph>
	Given a list of lines<latex>\index{line}</latex>, select those whose lengths are equal to
	a variable, equal to the length of a selector line, or between
	the lengths of two selector lines.
      </paragraph>
      <paragraph>
	Use a function<latex>\index{function}</latex> that iterates through the target lines. For
	each target line, if it has the desired length, the function
	reports it and puts it in a new list of result lines.
      </paragraph>
    </how>
    <a href="Samples/SeleLengthOfLine/SeleLengthOfLine.gct" >Click to download SeleLengthOfLine.gct</a> 
    <animation src="Samples/SeleLengthOfLine/AnimationLengthOfLine00.swf"/>			
  </sample>		
  <web>
  <sample id="Boundary">
    <name>Boundary</name>
    <when>
      <paragraph>
	To be added.
      </paragraph>
    </when>
    <how>
      <paragraph>
	To be added.
      </paragraph>
    </how>
    <a href="Samples/SeleBoundry/SeleBoundry.gct" >Click to download SeleBoundary.gct</a> 
    <animation src="Samples/SeleBoundry/AnimationBoundry00.swf"/>			
  </sample>
  </web>
</samples>
</pattern>

