Package org.bzdev.p3d

Class SteppedGrid.Builder

java.lang.Object
org.bzdev.p3d.SteppedGrid.Builder
Enclosing class:
SteppedGrid

public static class SteppedGrid.Builder extends Object
Build a SteppedGrid specified by a set of rectangles and half rectangles. This class is provided to simplify the creation of a SteppedGrid. Stepped grids are configured with a set of X values and a set of Y values, sorted in ascending order. The grid is divided into components that represent rectangular cells. An index (i,j) places the lower left corner of each component at the location (xs[i], ys[j]), where xs and ys are the arrays of the X and Y values respectively. The width of a component is xs[i+1]-xs[i] and the height of a component is ys[j+1]-ys[j], which implies that the number of I indices is one less than the number of X values and the number of J indices is one less than the number of Y values. Each component also has a z value associated, measured from a base z value for the grid as a whole.

Creating a grid and filling it is tedious except for simple cases. The SteppedGrid.Builder class allows a stepped grid to be specified by providing individual rectangles and assigning height to them. The SteppedGrid.Builder supports both open and closed grids. Open grids consist of a single grid, whereas closed grids consist of two grids, which will be connected where appropriate with vertical surfaces. For a closed grid, rectangles denoted as placeholders are left blank and are to be filled in by the caller.

The methods used depend on whether the SteppedGrid that will be created is open or closed (open grids contain a single grid whereas closed grids contain two, an upper and a lower grid). The methods addHalfRectangle(double,double,int,Corner,double), addHalfRectangle(double,double,int,Corner,double,boolean), addRectangle(double,double,double,double,double,boolean), and addRectangle(double,double,double,double,double,boolean,boolean) are used to configure open grids, whereas the methods addHalfRectangles(double,double,int,Corner,double,double), addHalfRectangles(double,double,int,Corner,double,double,boolean,boolean), addRectangles(double,double,double,double,double,double), addRectangles(double,double,double,double,double,double,boolean,boolean), addRectangle(double,double,double,double,double,boolean), and addRectangle(double,double,double,double,double,boolean,boolean) are used to configure closed grids. One method is used for both open and closed grids: removeRectangles(double,double,double,double). When the rectangles specified by these methods intersect, the parameters for the rectangle created by the most recent call are used to configure a grid component.

To configure a SteppedGrid, one simply specifies a sequence of rectangles and half rectangles. The half rectangles must be specified after all the full rectangles are specified. when two rectangles intersect, the data for the component placed at the intersection will be that specified by the most recent call to addRectangle, addHalfRectangle, addRectangles, addHalfRectangles, or removeRectangles. The use of placeholders is the same as for* SteppedGrid. After calls to addRectangle, addRectangles, addHalfRectangle, addHalfRectangles, and/or removeRectangles, one will call the method create() to generate the stepped grids.

For example, if m3d is an instance of Model3D,


  SteppedGrid.Builder sgb = new SteppedGrid.Builder(m3d, 10.0, -10.0);
  sgb.addRectangles(0.0, 0.0, 100.0, 100.0, 0.0, 0.0);
  sgb.addRectangles(20.0, 20.0, 60.0, 60.0, 0.0, 0.0, true, false);
  SteppedGrid sg = sgb.create()
  m3d.addTriangle(50.0, 50.0, 30.0,
                  20.0, 20.0, 10.0,
                  80.0, 20.0, 10.0);
  m3d.addTriangle(50.0, 50.0, 30.0,
                  80.0, 20.0, 10.0,
                  80.0, 80.0, 10.0);
  m3d.addTriangle(50.0, 50.0, 30.0,
                  80.0, 80.0, 10.0,
                  20.0, 80.0, 10.0);
  m3d.addTriangle(50.0, 50.0, 30.0,
                  20.0, 80.0, 10.0,
                  20.0, 20.0, 10.0);
 
will create a box with a pyramid at its center. The second call to addRectangles overrides the parameters provided by the first call inside a rectangular area 60 by 60 in size that constitutes the base of the pyramid. The second to the last argument in the second call to addRectangles is true, implying that the rectangle specifies a placeholder for the upper grid. The lower grid will be filled as the final argument is false. The empty area is then filled in by calls to Model3D.addTriangle(double,double,double,double,double,double,double,double,double). The resulting object is shown in the following image:

3D printed object example

Since a stepped grid implements the Shape3D interface, one can easily obtain the boundary for a stepped grid (e.g., a closed stepped grid with placeholders):


  Path3D boundary = sg.getBoundary();
 

If stepped-grid builder is improperly configured, sgb.create() may throw an exception. The method P3d.printSteppedGridBuilderCalls(Appendable,String,SteppedGrid.Builder) can be used to print information about which addRectangle or addRectangles methods were responsible.

See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    Enumeration naming the corner of a half rectangle.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Builder(Model3DOps<?> m3d, double zBase, boolean isUpper)
    Constructor for creating a partial stepped grid.
    Builder(Model3DOps<?> m3d, double zBase1, double zBase2)
    Constructor for creating a full stepped grid.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addHalfRectangle(double x, double y, int length, SteppedGrid.Builder.Corner filledCorner, double zOffset)
    Insert a half rectangle into the upper or lower grid, but not both.
    void
    addHalfRectangle(double x, double y, int length, SteppedGrid.Builder.Corner filledCorner, double zOffset, boolean placeholder)
    Insert a half rectangle into the upper or lower grid, but not both, and specifying if the rectangle is a placeholder.
    void
    addHalfRectangles(double x, double y, int length, SteppedGrid.Builder.Corner filledCorner, double zOffset1, double zOffset2)
    Add half rectangles to the upper and lower grids.
    void
    addHalfRectangles(double x, double y, int length, SteppedGrid.Builder.Corner filledCorner, double zOffset1, double zOffset2, boolean placeholder1, boolean placeholder2)
    Add half rectangles to the upper and lower grids, specifying if the half rectangles are placeholders.
    void
    addRectangle(double x, double y, double xlength, double ylength, double zOffset, boolean isUpper)
    Add a rectangle to the upper or lower grid.
    void
    addRectangle(double x, double y, double xlength, double ylength, double zOffset, boolean isUpper, boolean placeholder)
    Add a rectangle to the upper or lower grid, specifying whether the rectangle is a placeholder.
    void
    addRectangles(double x, double y, double xlength, double ylength, double zOffset1, double zOffset2)
    Add rectangles to the upper and lower grids.
    void
    addRectangles(double x, double y, double xlength, double ylength, double zOffset1, double zOffset2, boolean placeholder1, boolean placeholder2)
    Add rectangles to the upper and lower grids, specifying whether the rectangles are a placeholders.
    void
    addX(double x)
    Add a vertical grid separator at a specified X value.
    void
    addY(double y)
    Add a vertical grid separator at a specified Y value.
    Create a stepped grid and place it in the default model.
    Create a stepped grid.
    int
    getIndexFromX(double x)
    For a given key get the index into the array that getXs() would return.
    int
    getIndexFromY(double y)
    For a given key, get the index into the array that getYs() would return.
    int
    getLengthFromX(double x1, double x2)
    Get the number of vertical grid separators to traverse when going between two values of X
    int
    getLengthFromY(double y1, double y2)
    Get the number of horizontal grid separators to traverse when going between two values of Y
    Get a stack trace containing the call to a SteppedGrid.Builder method that set part of the lower grid so as to cause an exception to be thrown.
    double
    Get the maximum spacing between vertices in the Z direction.
    Get a stack trace containing the call to a SteppedGrid.Builder method that set part of the upper grid so as to cause an exception to be thrown.
    double[]
    Get the X coordinates delimiting grid elements.
    double[]
    Get the Y coordinates delimiting grid elements.
    boolean
    Determine if this stepped grid has a maximum spacing in the Z direction.
    void
    removeRectangles(double x, double y, double xlength, double ylength)
    Remove any portions of rectangles that intersect a rectangular area in the upper and/or lower grids.
    void
    setMaxZSpacing(double spacing)
    Set the maximum spacing between vertices in the Z direction.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • Builder

      public Builder(Model3DOps<?> m3d, double zBase, boolean isUpper)
      Constructor for creating a partial stepped grid.
      Parameters:
      m3d - the model
      zBase - the base height in the Z direction for the grid.
      isUpper - true if the grid's outside direction faces up; false if it faces down
    • Builder

      public Builder(Model3DOps<?> m3d, double zBase1, double zBase2)
      Constructor for creating a full stepped grid. This constructor creates a stepped grid with an upper and lower grid.
      Parameters:
      m3d - the model
      zBase1 - the base height in the Z direction for the upper grid
      zBase2 - the base height in the Z direction for the lower grid
  • Method Details

    • getUpperTrace

      public StackTraceElement[] getUpperTrace()
      Get a stack trace containing the call to a SteppedGrid.Builder method that set part of the upper grid so as to cause an exception to be thrown.
      Returns:
      the stack trace; null if there is no such call or if this builder was created when its model did not allow stack traces.
    • getLowerTrace

      public StackTraceElement[] getLowerTrace()
      Get a stack trace containing the call to a SteppedGrid.Builder method that set part of the lower grid so as to cause an exception to be thrown.
      Returns:
      the stack trace; null if there is no such call or if this builder was created when its model did not allow stack traces.
    • addX

      public void addX(double x)
      Add a vertical grid separator at a specified X value. This increases the total number of grid elements traversed in the X direction by 1.
      Parameters:
      x - the value of X
    • addY

      public void addY(double y)
      Add a vertical grid separator at a specified Y value. This increases the total number of grid elements traversed in the Y direction by 1.
      Parameters:
      y - the value of Y
    • getLengthFromX

      public int getLengthFromX(double x1, double x2)
      Get the number of vertical grid separators to traverse when going between two values of X
      Parameters:
      x1 - the starting value of X
      x2 - the ending value of X, which must be larger than or equal to x1
      Returns:
      the number of grid separators to traverse
    • getLengthFromY

      public int getLengthFromY(double y1, double y2)
      Get the number of horizontal grid separators to traverse when going between two values of Y
      Parameters:
      y1 - the starting value of Y
      y2 - the ending value of Y, which must be larger than or equal to y1
      Returns:
      the number of grid elements to traverse
    • addHalfRectangles

      public void addHalfRectangles(double x, double y, int length, SteppedGrid.Builder.Corner filledCorner, double zOffset1, double zOffset2)
      Add half rectangles to the upper and lower grids.
      Parameters:
      x - the X coordinate of the lower left corner of the rectangle containing this half rectangle
      y - the Y coordinate of the lower left corner of the rectangle containing this half rectangle
      length - the number of grid elements
      filledCorner - the corner within a filled region
      zOffset1 - the height in the Z direction measured from the the upper grid's base
      zOffset2 - the height in the Z direction measured from the the lower grid's base
    • addHalfRectangles

      public void addHalfRectangles(double x, double y, int length, SteppedGrid.Builder.Corner filledCorner, double zOffset1, double zOffset2, boolean placeholder1, boolean placeholder2)
      Add half rectangles to the upper and lower grids, specifying if the half rectangles are placeholders.
      Parameters:
      x - the X coordinate of the lower left corner of the rectangle containing this half rectangle
      y - the Y coordinate of the lower left corner of the rectangle containing this half rectangle
      length - the number of grid elements
      filledCorner - the corner within a filled region
      zOffset1 - the height in the Z direction measured from the the upper grid's base
      zOffset2 - the height in the Z direction measured from the the lower grid's base
      placeholder1 - true if the half-rectangle for the upper grid is a placeholder; false if it is not
      placeholder2 - true if the half-rectangle for the lower grid is a placeholder; false if it is not
    • addRectangles

      public void addRectangles(double x, double y, double xlength, double ylength, double zOffset1, double zOffset2)
      Add rectangles to the upper and lower grids. If rectangles intersect, the offsets and placeholder flags provided by the most recently defined of these rectangles are the offsets and placeholder flags used. The default placeholder flags used by this method have the value false.
      Parameters:
      x - the lower-left X coordinate for the rectangle
      y - the lower-left Y coordinate for the rectangle
      xlength - the length of the rectangle in the X direction
      ylength - the length of the rectangle in the Y direction
      zOffset1 - the Z value of the upper-grid's rectangle relative to the base value for its grid
      zOffset2 - the Z value of the lower-grid's rectangle relative to the base value for its grid
    • addRectangles

      public void addRectangles(double x, double y, double xlength, double ylength, double zOffset1, double zOffset2, boolean placeholder1, boolean placeholder2)
      Add rectangles to the upper and lower grids, specifying whether the rectangles are a placeholders. If rectangles intersect, the offsets and placeholder flags provided by the most recently defined of these rectangles are the offsets and placeholder flags used.
      Parameters:
      x - the lower-left X coordinate for the rectangle
      y - the lower-left Y coordinate for the rectangle
      xlength - the length of the rectangle in the X direction
      ylength - the length of the rectangle in the Y direction
      zOffset1 - the Z value of the upper-grid's rectangle relative to the base value for its grid
      zOffset2 - the Z value of the lower-grid's rectangle relative to the base value for its grid
      placeholder1 - true if the rectangle to be added to the upper grid is a placeholder; false otherwise
      placeholder2 - true if the rectangle to be added to the lower grid is a placeholder; false otherwise
    • removeRectangles

      public void removeRectangles(double x, double y, double xlength, double ylength)
      Remove any portions of rectangles that intersect a rectangular area in the upper and/or lower grids.
      Parameters:
      x - the lower-left X coordinate for the rectangular area
      y - the lower-left Y coordinate for the rectangular area
      xlength - the length of the rectangular area in the X direction
      ylength - the length of the rectangular area in the Y direction
    • addHalfRectangle

      public void addHalfRectangle(double x, double y, int length, SteppedGrid.Builder.Corner filledCorner, double zOffset)
      Insert a half rectangle into the upper or lower grid, but not both.
      Parameters:
      x - the lower-left X coordinate for the rectangle
      y - the lower-left Y coordinate for the rectangle
      length - the number of elements in the X and Y directions covered by this component.
      filledCorner - the corner that lies within the filled region of this half rectangle
      zOffset - the Z value of the upper-grid's rectangle relative to the base value for its grid
    • addHalfRectangle

      public void addHalfRectangle(double x, double y, int length, SteppedGrid.Builder.Corner filledCorner, double zOffset, boolean placeholder)
      Insert a half rectangle into the upper or lower grid, but not both, and specifying if the rectangle is a placeholder.
      Parameters:
      x - the lower-left X coordinate for the rectangle
      y - the lower-left Y coordinate for the rectangle
      length - the number of elements in the X and Y directions covered by this component.
      filledCorner - the corner that lies within the filled region of this half rectangle
      zOffset - the Z value of the upper-grid's rectangle relative to the base value for its grid
      placeholder - true if this object is a placeholder; false if it is not.
    • addRectangle

      public void addRectangle(double x, double y, double xlength, double ylength, double zOffset, boolean isUpper)
      Add a rectangle to the upper or lower grid. For stepped grids that do not have both a lower and upper grid, the isUpper parameter must match the choice made in the constructor. If rectangles intersect, the offsets and placeholder flags provided by the most recently defined of these rectangles are the offsets and placeholder flags used. The default placeholder flags used by this method have the value false.
      Parameters:
      x - the lower-left X coordinate for the rectangle
      y - the lower-left Y coordinate for the rectangle
      xlength - the length of the rectangle in the X direction
      ylength - the length of the rectangle in the Y direction
      zOffset - the Z value of the grid's rectangle relative to the base value for its grid
      isUpper - true if the rectangle should be added to an upper grid; false if the rectangle should be added to the lower grid
    • addRectangle

      public void addRectangle(double x, double y, double xlength, double ylength, double zOffset, boolean isUpper, boolean placeholder)
      Add a rectangle to the upper or lower grid, specifying whether the rectangle is a placeholder. For stepped grids that do not have both a lower and upper grid, the isUpper parameter must match the choice made in the constructor. If rectangles intersect, the offsets and placeholder flags provided by the most recently defined of these rectangles are the offsets and placeholder flags used.
      Parameters:
      x - the lower-left X coordinate for the rectangle
      y - the lower-left Y coordinate for the rectangle
      xlength - the length of the rectangle in the X direction
      ylength - the length of the rectangle in the Y direction
      zOffset - the Z value of the grid's rectangle relative to the base value for its grid
      isUpper - true if the rectangle should be added to an upper grid; false if the rectangle should be added to the lower grid
      placeholder - true if the rectangle to be added is a placeholder; false otherwise
    • setMaxZSpacing

      public void setMaxZSpacing(double spacing)
      Set the maximum spacing between vertices in the Z direction.

      This method is intended for cases where a model is configured with an instance of Transform3D, when that transform does not map straight lines to straight lines. In that case, one will typically configure a grid as collection of small rectangles. This method will ensure that the spacing between vertices is small in the Z direction as well.

      Parameters:
      spacing - the maximum spacing; 0.0 or a negative value if there is none
    • hasMaxZSpacing

      public boolean hasMaxZSpacing()
      Determine if this stepped grid has a maximum spacing in the Z direction.
      Returns:
      true if a maximum spacing exists; false otherwise
    • getMaxZSpacing

      public double getMaxZSpacing()
      Get the maximum spacing between vertices in the Z direction.
      Returns:
      the maximum spacing; 0.0 if none is defined.
    • getXs

      public double[] getXs()
      Get the X coordinates delimiting grid elements.
      Returns:
      the X coordinates in ascending order.
    • getYs

      public double[] getYs()
      Get the Y coordinates delimiting grid elements.
      Returns:
      the Y coordinates in ascending order.
    • getIndexFromX

      public int getIndexFromX(double x)
      For a given key get the index into the array that getXs() would return.
      Parameters:
      x - the key
      Returns:
      the index; a negative value if x does not lie on the boundary between elements
    • getIndexFromY

      public int getIndexFromY(double y)
      For a given key, get the index into the array that getYs() would return.
      Parameters:
      y - the key
      Returns:
      the index; a negative value if y does not lie on the boundary between elements
    • create

      public SteppedGrid create()
      Create a stepped grid and place it in the default model.
      Returns:
      the stepped grid that was created
    • create

      public SteppedGrid create(Model3DOps<?> m3d)
      Create a stepped grid.
      Parameters:
      m3d - the model to which the grid will be added
      Returns:
      the stepped grid that was created