class LineGenerator Javadoc

Following is the portion of the LineGenerator Javadoc detailing the algorithm used for generating lines.

This page has been generated to accompany Cartesian Plane Lesson 6: Unit Testing.

Line Generation Algorithm

Following are the constraints and parameters governing the generation of lines within the bounds of a given rectangle.

Given:

• rectXco: The x-coordinate of the upper left corner of the rectangle.
• rectYco: The y-coordinate of the upper left corner of the rectangle.
• rectWidth: The width of the rectangle.
• rectHeight: The height of the rectangle.

1. [rule: boundingRect] The rectangle bounding the grid is given by the user of this class.
2. The left-bound of the rectangle (rectXco) is inside the rectangle.
3. The upper-bound of the rectangle (rectYco) is inside the rectangle.
4. The right-bound of the rectangle, given by rectXco + rectWidth, is outside the rectangle.
5. The lower-bound of the rectangle, given by rectYco + rectHeight, is outside the rectangle.
6. [rule: gridUnit] The grid unit (gridUnit), is given by the user of this class; it is the number of pixels (pixels-per-unit or PPU) allocated to the length of a unit.
7. [rule: lpu] The lines-per-unit (lpu), is given by the user of this class; it is the number of lines to be drawn for each unit.
8. [rule: gridSpacing] The distance between two consecutive grid lines (gridSpacing) is given by gridSpacing = gridUnit / lpu.
9. [rule: xAxis] The coordinates of the x-axis are given by y = rectYco + (rectHeight - 1) / 2  (centerYco) for x in the range [rectXco, rectXco + rectWidth).
10. [rule: yAxis] The coordinates of the y-axis are given by x = rectXco + (rectWidth - 1) / 2 (centerXco) for y in the range [rectYco, rectYco + rectHeight).
11. [rule: numHLinesAbove] The number of horizontal lines above the x-axis is calculated as floor((rectHeight - 1) / 2 / gridSpacing).
12. [rule: numHLinesBelow] The number of horizontal lines below the x-axis is always the same as the number of horizontal lines above the x-axis.
13. [rule: numHLinesTotal] The total number of horizontal lines is calculated as 2 * floor((rectHeight - 1) / 2 / gridSpacing) + 1.
14. [rule: numVLinesLeft] The number of vertical lines left of the y-axis is calculated as floor((rectWidth - 1) / 2 / gridSpacing).
15. [rule: numVLinesRight] The number of vertical lines right of the y-axis is always the same as the number of vertical lines left of the y-axis.
16. [rule: numVLinesTotal] The total number of vertical lines is calculated as 2 * floor((rectWidth - 1) / 2 / gridSpacing) + 1.
17. [rule: nthHLineAbove] The y-coordinate of the n^th horizontal line above the x-axis is given by -n * gridSpacing.
18. [rule: nthHLineBelow] The y-coordinate of the n^th horizontal line below the x-axis is given by n * gridSpacing.
19. [rule: nthVLineLeft] The x-coordinate of the n^th vertical line left of the y-axis is given by -n * gridSpacing.
20. [rule: nthVLineRight] The x-coordinate of the n^th vertical line right of the y-axis is given by n * gridSpacing.
21. A line segment is defined as a horizontal or vertical line with a specific length n (i.e. the line does not span the width or height of the bounding rectangle).
22. [rule: hLineSegmentXco1] The left x-coordinate of a horizontal line segment of length n is the x-coordinate of the y-axis minus n / 2.
23. [rule: hLineSegmentXco2] The right x-coordinate of a horizontal line segment of length n left x-coordinate plus n.
24. [rule: vLineSegmentYco1] The upper y-coordinate of a vertical line segment of length n is the y-coordinate of the x-axis minus n / 2.
25. [rule: vLineSegmentYco2] The lower y-coordinate of a vertical line segment of length n upper y-coordinate plus n.

Caveats:

1. [rule: cumulativeRoundingErrors] Given:
   1. The possibility of cumulative rounding errors;
   2. The fact that calculations by the AWT are not always the most helpful to line positioning;
   3. The difficulties inherent in converting user coordinates to device coordinates (see the documentation for java.awt.Graphics2D);
   line-drawing may occasionally be less than perfect. In particular lines may be calculated that are outside of the grid's bounding rectangle (usually by one pixel or less). For the purpose of testing such anomalies should be ignored. Correction for stray marks at runtime can be avoided by the user by setting a clip region to the shape of the bounding rectangle.
2. [rule: clipRegionErrors] The clip-region processing by the AWT is occasionally off by a pixel. From a testing and validation point of view this should be tolerated.